One Markdown-to-program mapping, no version selector or legacy mapper. Frontend/runtime: - resolve @exec/@knowledge heading declarations with nearest-ancestor inheritance; only an Exec H2 is callable; add UnitKind::Knowledge and sem.* diagnostics (mode marker, unit name, exec-without-function, payload nesting/empty, syntax, control stack, params position, version directive, inferred-signature lint) - extract Strong/Emph/inline Code as one-statement carriers, refuse nested carriers, and honour heading segment boundaries so an if/while cannot be closed across a heading - lower if/else/while/end to the existing Branch/Loop/Return IR with a compile-time control stack; keep payload-relative source spans through expression parsing and rewrite them onto the file - accept params(...) only as the first direct Exec H2 payload; keep the existing free-variable inference and named-only rule for inferred signatures; fix duplicate-mode/else/end and Knowledge-body inertness - reject marqdo_semantics/syntax front matter directives Data and tests: - migrate stdlib/**/*.mq.md, regenerate stdlib.json digest - migrate examples and the full semantics/negative/runtime corpus to the only current syntax; expected values/runtime codes preserved - migrate Rust-embedded .mq.md fixtures, init template, CLI help and security-lane fixtures Verified: cargo fmt --check, cargo clippy -D warnings and cargo test --workspace --locked (green).
5.7 KiB
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/build/solver.so
Inspect
Manifest validation and artifact verification are implemented by
crates/marqdo-plugin-abi and exposed through marqdo plugin inspect (which
never loads plugin code):
./examples/plugin-demo/build.sh # writes build/solver.<dylib> + manifest
marqdo plugin inspect examples/plugin-demo/build
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.
Call from a Marqdo document (implemented)
Once the host has made the explicit in-process trust decision, plugin exports are callable through the namespace that prefixes their export names. Plugin calls take named arguments only in this build:
## @exec main
`结果 = solver.add(a=20, b=22)`
> **打印(结果)**
marqdo run examples/plugin-demo/plugin-call.mq.md \
--plugin examples/plugin-demo \
--trust-native-plugin \
--allow-plugin demo.solver
# 42
--plugin <path>loads one manifest/artifact (repeatable).--allow-plugin demo.solvergrants the plugin capability; without it the call fails withpermission.denied.--trust-native-pluginacknowledges that in-process native code shares the host address space and is not sandboxed. This build has no isolated worker transport, and--mode strictrefuses to run at all.- Plugin failures become structured runtime errors:
plugin.abi_mismatch,plugin.failure,symbol.unknown(namespace not loaded), orpermission.denied.