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:
1 parent
f6c3efa849
commit
6da206a906
20 files changed
+5171
-1
No files matched your search
@@ -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.
|
||||
Executable
+22
@@ -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"
|
||||
@@ -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"
|
||||
@@ -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;
|
||||
}
|
||||
Reference in new issue
Block a user