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.
112 lines
4.6 KiB
Markdown
112 lines
4.6 KiB
Markdown
# 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`](../../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_capability` can 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):
|
|
|
|
```sh
|
|
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`](plugin.yaml) to match what you built:
|
|
|
|
```sh
|
|
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:
|
|
|
|
1. parse `plugin.yaml`,
|
|
2. validate name, semver-ish version, `^1.0` ABI requirement, kind, exports,
|
|
capability names and artifact declarations,
|
|
3. resolve the artifact for the host target triple,
|
|
4. verify the sha256 against the manifest,
|
|
5. only then (with explicit trust) load and call
|
|
`mq_plugin_entry_v1`.
|
|
|
|
The entry point must:
|
|
|
|
- check `host->struct_size` and `host->abi_major == MQ_ABI_MAJOR`
|
|
(`MQ_ERR_ABI_MISMATCH` otherwise),
|
|
- report `plugin->abi_major`/`abi_minor` and `plugin_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:
|
|
|
|
```text
|
|
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.
|