feat(plugin-abi,sdk): versioned C ABI v1, host bindings, Rust SDK and C example

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.
This commit is contained in:
cflmy committed 2026-11-20 10:43:59 +08:00
1 parent f6c3efa849
commit 6da206a906
20 files changed
+5171 -1

No files matched your search

+111
View File
@@ -0,0 +1,111 @@
# 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.
+22
View File
@@ -0,0 +1,22 @@
#!/usr/bin/env bash
# Build the example C plugin and refresh the sha256 in plugin.yaml.
#
# The artifact is intentionally NOT committed: installing/inspecting a package
# never implies trusting or loading its native code, and the manifest must
# describe the artifact you actually build on your machine.
set -euo pipefail
here="$(cd "$(dirname "$0")" && pwd)"
repo="$(cd "$here/../.." && pwd)"
cd "$repo"
cc -shared -fPIC -I include -o "$here/solver.so" "$here/solver.c"
hash="$(sha256sum "$here/solver.so" | cut -d' ' -f1)"
python3 - "$here/plugin.yaml" "$hash" <<'PY'
import sys, re, pathlib
path, digest = sys.argv[1], sys.argv[2]
p = pathlib.Path(path)
text = p.read_text()
text = re.sub(r'(?m)^(\s*sha256:\s*")[0-9a-fA-F]{64}(")', r'\g<1>' + digest + r'\g<2>', text)
p.write_text(text)
PY
echo "built $here/solver.so (sha256 $hash)"
echo "now run: marqdo plugin inspect $here"
+25
View File
@@ -0,0 +1,25 @@
# Example Marqdo plugin manifest (plugin ABI v1).
#
# Installing this package never grants permissions. Loading the native library
# additionally requires an explicit trust decision by the host/user; a C ABI is
# not a sandbox. Replace the sha256 below with the digest of the artifact you
# actually build:
#
# sha256sum examples/plugin-demo/solver.so
#
# and replace `target` with your host's Rust target triple if it is not
# x86_64-unknown-linux-gnu (`rustc -vV | grep host`).
plugin:
name: demo.solver
version: 0.1.0
abi: "^1.0"
kind: native
exports:
- name: solver.add
signature: "($a: Int, $b: Int) -> Int"
requires:
- math.compute
artifacts:
- target: x86_64-unknown-linux-gnu
file: solver.so
sha256: "0000000000000000000000000000000000000000000000000000000000000000"
+256
View File
@@ -0,0 +1,256 @@
/*
* Marqdo plugin ABI v1 example plugin in C.
*
* Exports `solver.add` through `mq_plugin_entry_v1`, using the wire_version 1
* JSON envelope. It deliberately has no external dependencies: the tiny JSON
* scanning below is a demo aid, not a general-purpose JSON parser.
*
* Build:
* cc -std=c11 -O2 -shared -fPIC -I include examples/plugin-demo/solver.c \
* -o examples/plugin-demo/solver.so
*
* Test-only compile switches (used by the host-side conformance tests):
* -DMQ_SOLVER_REPORT_ABI_MAJOR=2 report a wrong ABI major on purpose
*/
#include "marqdo_plugin_abi_v1.h"
#include <limits.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#ifndef MQ_SOLVER_REPORT_ABI_MAJOR
#define MQ_SOLVER_REPORT_ABI_MAJOR MQ_ABI_MAJOR
#endif
static const char PLUGIN_METADATA[] =
"{\"name\":\"demo.solver\",\"version\":\"0.1.0\"}";
static const char SIGNATURE_ADD[] = "{\"signature\":\"($a: Int, $b: Int) -> Int\"}";
/* Single-threaded ABI: the host table is captured once at entry. */
static const MqHostApi *g_host = NULL;
/* Return the pointer just past `"key"` + optional whitespace + ':' inside
* `json`. Returns NULL when the key is absent. This is a demo scanner. */
static const char *find_key(const char *json, const char *key) {
size_t key_len = strlen(key);
const char *cursor = json;
while ((cursor = strchr(cursor, '"')) != NULL) {
const char *name_start = cursor + 1;
const char *name_end = strchr(name_start, '"');
if (name_end == NULL) {
return NULL;
}
if ((size_t)(name_end - name_start) == key_len &&
memcmp(name_start, key, key_len) == 0) {
const char *after = name_end + 1;
while (*after == ' ' || *after == '\t' || *after == '\n' ||
*after == '\r') {
after++;
}
if (*after != ':') {
return NULL;
}
after++;
while (*after == ' ' || *after == '\t' || *after == '\n' ||
*after == '\r') {
after++;
}
return after;
}
cursor = name_end + 1;
}
return NULL;
}
/* Find the object that is the value of key `name` and return a pointer to its
* opening '{'. */
static const char *find_object_value(const char *json, const char *name) {
const char *value = find_key(json, name);
if (value == NULL || *value != '{') {
return NULL;
}
return value;
}
/* Extract a quoted JSON string value for `key`, copying at most `out_len - 1`
* bytes into `out` (NUL terminated). Rejects escapes for simplicity. */
static int read_string_value(const char *object, const char *key, char *out,
size_t out_len) {
const char *value = find_key(object, key);
if (value == NULL || *value != '"') {
return -1;
}
const char *start = value + 1;
const char *end = strchr(start, '"');
if (end == NULL) {
return -1;
}
size_t len = (size_t)(end - start);
if (len + 1 > out_len || memchr(start, '\\', len) != NULL) {
return -1;
}
memcpy(out, start, len);
out[len] = '\0';
return 0;
}
/* Extract the integer argument `name` from the request's `args` object. */
static int read_int_argument(const char *json, const char *name,
long long *out_value) {
const char *args = find_object_value(json, "args");
if (args == NULL) {
return -1;
}
const char *argument = find_object_value(args, name);
if (argument == NULL) {
return -1;
}
char decimal[32];
if (read_string_value(argument, "decimal", decimal, sizeof(decimal)) != 0) {
return -1;
}
char *end = NULL;
long long value = strtoll(decimal, &end, 10);
if (end == NULL || *end != '\0' || end == decimal) {
return -1;
}
*out_value = value;
return 0;
}
/* Allocate an output buffer through the host allocator and copy `len` bytes.
* The host frees it after copying; the plugin never frees output buffers. */
static int32_t emit(const char *json, size_t len, MqOwnedBytes *out) {
uint8_t *buffer;
if (g_host == NULL || out == NULL) {
return MQ_ERR_INVALID_ARGUMENT;
}
buffer = (uint8_t *)g_host->alloc(g_host->host_data, len);
if (buffer == NULL) {
return MQ_ERR_OUT_OF_MEMORY;
}
memcpy(buffer, json, len);
out->data = buffer;
out->len = len;
return MQ_OK;
}
static int32_t emit_error(const char *code, const char *message,
MqOwnedBytes *out, int32_t failure_code) {
char json[512];
int written = snprintf(
json, sizeof(json),
"{\"wire_version\":1,\"kind\":\"response\",\"error\":"
"{\"kind\":\"invoke\",\"code\":\"%s\",\"message\":\"%s\"}}",
code, message);
if (written < 0 || (size_t)written >= sizeof(json)) {
return MQ_ERR_INTERNAL;
}
if (emit(json, (size_t)written, out) != MQ_OK) {
return MQ_ERR_OUT_OF_MEMORY;
}
/* Non-zero: the invocation failed even though an error envelope was
* written. The host reads the envelope for the structured error. */
return failure_code;
}
/* Implementation of the `solver.add` export. */
static int32_t solver_add(MqCallContext *ctx, MqBytes args_wire,
MqOwnedBytes *result_wire, MqOwnedBytes *error_wire) {
char *json;
long long a = 0;
long long b = 0;
long long sum;
char response[160];
int written;
(void)ctx;
if (result_wire == NULL || error_wire == NULL) {
return MQ_ERR_INVALID_ARGUMENT;
}
*result_wire = (MqOwnedBytes){NULL, 0};
*error_wire = (MqOwnedBytes){NULL, 0};
if (args_wire.data == NULL || args_wire.len == 0) {
return emit_error("bad_arguments", "request wire is empty", error_wire,
MQ_ERR_INVALID_ARGUMENT);
}
if (args_wire.len > MQ_MAX_REQUEST_WIRE_BYTES) {
return emit_error("request_too_large", "request wire is too large",
error_wire, MQ_ERR_INVALID_ARGUMENT);
}
json = (char *)malloc(args_wire.len + 1);
if (json == NULL) {
return emit_error("out_of_memory", "plugin could not copy request",
error_wire, MQ_ERR_OUT_OF_MEMORY);
}
memcpy(json, args_wire.data, args_wire.len);
json[args_wire.len] = '\0';
if (read_int_argument(json, "a", &a) != 0 ||
read_int_argument(json, "b", &b) != 0) {
free(json);
return emit_error("bad_arguments",
"solver.add requires Int arguments `a` and `b`",
error_wire, MQ_ERR_INVALID_ARGUMENT);
}
free(json);
if (__builtin_add_overflow(a, b, &sum)) {
return emit_error("integer_overflow", "solver.add overflowed i64",
error_wire, MQ_ERR_INTERNAL);
}
written = snprintf(
response, sizeof(response),
"{\"wire_version\":1,\"kind\":\"response\",\"value\":"
"{\"type\":\"int\",\"decimal\":\"%lld\"}}",
sum);
if (written < 0 || (size_t)written >= sizeof(response)) {
return MQ_ERR_INTERNAL;
}
return emit(response, (size_t)written, result_wire);
}
/* Required ABI v1 entry point. */
int32_t mq_plugin_entry_v1(const MqHostApi *host, MqPluginApi *plugin) {
MqBytes export_name;
MqBytes signature_wire;
int32_t code;
if (host == NULL || plugin == NULL) {
return MQ_ERR_INVALID_ARGUMENT;
}
if (host->struct_size < sizeof(MqHostApi)) {
return MQ_ERR_ABI_MISMATCH;
}
if (host->abi_major != MQ_ABI_MAJOR) {
return MQ_ERR_ABI_MISMATCH;
}
if (host->alloc == NULL || host->free == NULL ||
host->register_function == NULL || host->request_capability == NULL) {
return MQ_ERR_ABI_MISMATCH;
}
g_host = host;
/* The host pre-fills struct_size; keep it and report our ABI version. */
plugin->struct_size = (uint32_t)sizeof(MqPluginApi);
plugin->abi_major = MQ_SOLVER_REPORT_ABI_MAJOR;
plugin->abi_minor = MQ_ABI_MINOR;
plugin->plugin_metadata_wire.data = (const uint8_t *)PLUGIN_METADATA;
plugin->plugin_metadata_wire.len = sizeof(PLUGIN_METADATA) - 1;
export_name.data = (const uint8_t *)"solver.add";
export_name.len = sizeof("solver.add") - 1;
signature_wire.data = (const uint8_t *)SIGNATURE_ADD;
signature_wire.len = sizeof(SIGNATURE_ADD) - 1;
code = host->register_function(host->host_data, export_name, signature_wire,
solver_add);
if (code != MQ_OK) {
return code;
}
return MQ_OK;
}