Blueprint section 10: a first-class plugin ABI independent of the legacy MARQDO_ABI_VERSION=2, with a C ABI that is explicitly not a sandbox. - include/marqdo_plugin_abi_v1.h: frozen stable-layout C contract with documented buffer ownership/lifetimes, size limits, NULL/zero-length semantics, single-threaded invocation, no hot-unload policy, version negotiation and target-triple requirements. - marqdo-plugin-abi (host side): repr(C) mirrors with compile-time layout assertions, major/minor negotiation (wrong major fails, minor clamps), plugin.yaml parsing/validation, target selection and sha256 artifact verification, wire_version 1 typed JSON request/response envelopes, structured PluginError, and a libloading-based loader with host alloc/free, export registration and runtime ABI re-negotiation. - marqdo-plugin-sdk (plugin side): mq_plugin_entry! macro, panic containment, safe byte-buffer wrappers, capability/logging context and JSON helpers; it depends only on the shared ABI crate. - examples/plugin-demo: dependency-free C plugin (solver.add), manifest, build.sh that refreshes the artifact hash, README explaining that install, inspect and load are three different trust decisions. - Tests: C plugin cross-compiled with cc and loaded, plus wrong ABI major, missing symbol/artifact, hash mismatch and malformed manifest cases.
Marqdo plugin ABI v1 demo (C)
This example shows how a third-party C developer implements a Marqdo native
plugin against the frozen, versioned C ABI v1 in
include/marqdo_plugin_abi_v1.h, with
no Marqdo source access and no Rust dependency.
It implements one export:
| Export | Signature | Behaviour |
|---|---|---|
solver.add |
($a: Int, $b: Int) -> Int |
Returns a + b using the wire_version 1 JSON envelope |
Security model (read this first)
- A C ABI is not a sandbox. A loaded native plugin runs in the host process and can read memory, crash the process or bypass the capability model entirely.
- Installing is not loading. Placing the package in a plugin directory grants nothing.
- Loading is not permission. Loading requires an explicit host/user trust decision for in-process native code.
- Declaring is not granting.
requires: [math.compute]only states what the plugin wants; the host authorization layer decides whether the capability is granted.request_capabilitycan never escalate. - Default third-party execution must use the isolated worker path. This demo is for trusted, in-process development and ABI conformance testing.
Build
From the repository root (gcc/clang):
cc -std=c11 -O2 -shared -fPIC -I include examples/plugin-demo/solver.c \
-o examples/plugin-demo/solver.so
The artifact is target-specific. Build it for the same target triple, pointer
width and byte order as the host; 32-bit and 64-bit artifacts are never
interchangeable. Update artifacts[0].target and sha256 in
plugin.yaml to match what you built:
sha256sum examples/plugin-demo/solver.so
Inspect
Manifest validation and artifact verification are host-side library calls
(crates/marqdo-plugin-abi); the CLI wrappers are part of the broader
package/CLI workstream. A typical inspection flow is:
- parse
plugin.yaml, - validate name, semver-ish version,
^1.0ABI requirement, kind, exports, capability names and artifact declarations, - resolve the artifact for the host target triple,
- verify the sha256 against the manifest,
- only then (with explicit trust) load and call
mq_plugin_entry_v1.
The entry point must:
- check
host->struct_sizeandhost->abi_major == MQ_ABI_MAJOR(MQ_ERR_ABI_MISMATCHotherwise), - report
plugin->abi_major/abi_minorandplugin_metadata_wire, - register every manifest-declared export via
host->register_function.
The ABI is single-threaded: the entry point is called once by the loading thread, invocations and host callbacks happen on that same thread, one call at a time. The host does not support hot-unloading in v1.
Load and call
The host-side loader (marqdo_plugin_abi::LoadedPlugin) performs the full
lifecycle and invokes solver.add with a wire request:
wire request : {"wire_version":1,"kind":"request","function":"solver.add",
"args":{"a":{"type":"int","decimal":"20"},
"b":{"type":"int","decimal":"22"}},
"context":{}}
wire response: {"wire_version":1,"kind":"response",
"value":{"type":"int","decimal":"42"}}
The integration test
crates/marqdo-plugin-abi/tests/loader_unix.rs compiles this exact
solver.c with cc -shared -fPIC, loads it with libloading, and round-trips
the request. It duplicates the compilation with
-DMQ_SOLVER_REPORT_ABI_MAJOR=2 to prove that a wrong ABI major fails the
load.
Buffer rules in one paragraph
The host owns alloc/free. Input buffers (args_wire, export names,
signatures, metadata) are borrowed only for the duration of the call; the
plugin must copy and never retain or free them. Output buffers
(result_wire, error_wire, capability replies) must be allocated with
host->alloc and are then freed by the host after copying. Zero-length
buffers are {NULL, 0}. On success fill result_wire and leave
error_wire empty; on failure fill error_wire with a JSON error envelope
and leave result_wire empty. Size limits are defined in the header (16 MiB
requests, 64 MiB results, 1 MiB errors).
What the demo deliberately does not do
The JSON scanner in solver.c is intentionally minimal (no escapes, i64
only) to keep the example dependency-free. A real plugin should use a proper
JSON library and its language's SDK bindings (the Rust SDK is
crates/marqdo-plugin-sdk). The demo also does not request capabilities; see
CallContext::capability_request in the SDK for that path.