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

+2 -1
View File
@@ -16,4 +16,5 @@ serde_json = { workspace = true }
serde_yaml = { workspace = true }
thiserror = { workspace = true }
libloading = { workspace = true }
sha2 = { workspace = true }
hex = { workspace = true }
+608
View File
@@ -0,0 +1,608 @@
//! Stable-layout Rust mirrors of the canonical C ABI v1 header
//! (`include/marqdo_plugin_abi_v1.h`) plus version negotiation.
//!
//! The structs in this module are the *only* types allowed to cross the
//! native plugin boundary. Layout is asserted at compile time for both 32-bit
//! and 64-bit targets; do not reorder, resize or add fields to an existing
//! struct outside of a new ABI minor that appends fields after `struct_size`.
use std::ffi::c_void;
use std::ptr;
use serde::{Deserialize, Serialize};
use crate::error::PluginError;
/// Canonical C header version this crate implements.
pub mod version {
/// Plugin ABI major version. A major mismatch always fails the load.
pub const ABI_MAJOR: u32 = 1;
/// Plugin ABI minor version implemented by this crate.
pub const ABI_MINOR: u32 = 0;
/// Human-readable ABI version.
pub const ABI_VERSION_STRING: &str = "1.0";
/// Required exported entry symbol.
pub const ENTRY_SYMBOL: &[u8] = b"mq_plugin_entry_v1";
/// Required exported entry symbol (UTF-8 form).
pub const ENTRY_SYMBOL_STR: &str = "mq_plugin_entry_v1";
}
pub use version::{ABI_MAJOR, ABI_MINOR, ABI_VERSION_STRING, ENTRY_SYMBOL};
/// ABI result codes returned by the entry point and invocation callbacks.
pub mod result {
/// Success.
pub const OK: i32 = 0;
/// Malformed argument (NULL pointer, bad pointer/length pair, ...).
pub const INVALID_ARGUMENT: i32 = 1;
/// ABI major mismatch or incompatible `struct_size`.
pub const ABI_MISMATCH: i32 = 2;
/// A required export could not be registered.
pub const REGISTRATION: i32 = 3;
/// Operation/type/capability not supported by this version.
pub const UNSUPPORTED: i32 = 4;
/// Host allocation failed.
pub const OUT_OF_MEMORY: i32 = 5;
/// Payload is not valid wire_version 1 JSON.
pub const BAD_WIRE: i32 = 6;
/// Unexpected internal plugin failure (including caught panics).
pub const INTERNAL: i32 = 7;
/// Capability request failed or was denied.
pub const CAPABILITY: i32 = 8;
/// Human-readable name for a result code.
pub const fn name(code: i32) -> &'static str {
match code {
OK => "ok",
INVALID_ARGUMENT => "invalid_argument",
ABI_MISMATCH => "abi_mismatch",
REGISTRATION => "registration",
UNSUPPORTED => "unsupported",
OUT_OF_MEMORY => "out_of_memory",
BAD_WIRE => "bad_wire",
INTERNAL => "internal",
CAPABILITY => "capability",
_ => "unknown",
}
}
}
/// Maximum export-name length in bytes.
pub const MAX_EXPORT_NAME_BYTES: usize = 256;
/// Maximum `signature_wire` length in bytes.
pub const MAX_SIGNATURE_WIRE_BYTES: usize = 4096;
/// Maximum plugin metadata wire length in bytes.
pub const MAX_METADATA_WIRE_BYTES: usize = 65_536;
/// Maximum request wire length in bytes (16 MiB).
pub const MAX_REQUEST_WIRE_BYTES: usize = 16 * 1024 * 1024;
/// Maximum result wire length in bytes (64 MiB).
pub const MAX_RESULT_WIRE_BYTES: usize = 64 * 1024 * 1024;
/// Maximum error wire length in bytes (1 MiB).
pub const MAX_ERROR_WIRE_BYTES: usize = 1024 * 1024;
/// Maximum capability reply length in bytes (16 MiB).
pub const MAX_CAPABILITY_REPLY_BYTES: usize = 16 * 1024 * 1024;
/// Borrowed, immutable byte view (`MqBytes`).
///
/// The producer keeps ownership; the pointer is only valid for the duration
/// of the call that received it. `{NULL, 0}` denotes the empty buffer.
#[repr(C)]
#[derive(Clone, Copy)]
pub struct MqBytes {
/// Pointer to the first byte, or NULL when `len == 0`.
pub data: *const u8,
/// Length in bytes.
pub len: usize,
}
impl MqBytes {
/// The empty buffer `{NULL, 0}`.
pub const EMPTY: Self = Self {
data: ptr::null(),
len: 0,
};
/// Construct a borrowed byte view from a raw pointer and length.
pub const fn new(data: *const u8, len: usize) -> Self {
Self { data, len }
}
/// Construct a borrowed view over a slice.
pub fn from_slice(bytes: &[u8]) -> Self {
Self {
data: bytes.as_ptr(),
len: bytes.len(),
}
}
/// Whether the view is empty.
pub fn is_empty(&self) -> bool {
self.len == 0
}
/// Validate the pointer/length invariant.
pub fn validate(&self) -> Result<(), PluginError> {
if self.len == 0 {
return Ok(());
}
if self.data.is_null() {
return Err(PluginError::wire(
"invalid_bytes",
"non-empty MqBytes has a NULL data pointer",
));
}
Ok(())
}
/// View the bytes as a slice.
///
/// # Safety
///
/// If `len > 0`, `data` must point to `len` initialized bytes that stay
/// alive for `'a`. For ABI borrows, `'a` must not outlive the call that
/// produced the pointer.
pub unsafe fn as_slice<'a>(self) -> Result<&'a [u8], PluginError> {
self.validate()?;
if self.len == 0 {
return Ok(&[]);
}
// SAFETY: guaranteed by the caller's contract above.
Ok(unsafe { std::slice::from_raw_parts(self.data, self.len) })
}
}
impl std::fmt::Debug for MqBytes {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
f.debug_struct("MqBytes")
.field("data", &self.data)
.field("len", &self.len)
.finish()
}
}
/// Mutable, owned byte buffer (`MqOwnedBytes`).
///
/// The producer allocates with `MqHostApi::alloc` and transfers ownership to
/// the consumer, which copies and then calls `MqHostApi::free`.
#[repr(C)]
#[derive(Clone, Copy)]
pub struct MqOwnedBytes {
/// Pointer to the first byte, or NULL when `len == 0`.
pub data: *mut u8,
/// Length in bytes.
pub len: usize,
}
impl MqOwnedBytes {
/// The empty buffer `{NULL, 0}`.
pub const EMPTY: Self = Self {
data: ptr::null_mut(),
len: 0,
};
/// Construct an owner-transfer buffer from a raw pointer and length.
pub const fn new(data: *mut u8, len: usize) -> Self {
Self { data, len }
}
/// Whether the buffer is empty.
pub fn is_empty(&self) -> bool {
self.len == 0
}
/// Validate the pointer/length invariant.
pub fn validate(&self) -> Result<(), PluginError> {
if self.len == 0 {
return Ok(());
}
if self.data.is_null() {
return Err(PluginError::wire(
"invalid_bytes",
"non-empty MqOwnedBytes has a NULL data pointer",
));
}
Ok(())
}
/// Copy the buffer into a `Vec`.
///
/// # Safety
///
/// If `len > 0`, `data` must point to `len` initialized bytes.
pub unsafe fn to_vec(&self) -> Result<Vec<u8>, PluginError> {
self.validate()?;
if self.len == 0 {
return Ok(Vec::new());
}
// SAFETY: guaranteed by the caller's contract above.
Ok(unsafe { std::slice::from_raw_parts(self.data, self.len) }.to_vec())
}
/// View the bytes as a slice.
///
/// # Safety
///
/// If `len > 0`, `data` must point to `len` initialized bytes that stay
/// alive for `'a`.
pub unsafe fn as_slice<'a>(self) -> Result<&'a [u8], PluginError> {
self.validate()?;
if self.len == 0 {
return Ok(&[]);
}
// SAFETY: guaranteed by the caller's contract above.
Ok(unsafe { std::slice::from_raw_parts(self.data, self.len) })
}
}
impl std::fmt::Debug for MqOwnedBytes {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
f.debug_struct("MqOwnedBytes")
.field("data", &self.data)
.field("len", &self.len)
.finish()
}
}
/// Opaque, host-owned invocation context.
///
/// Plugins only ever hold a pointer to this type; its layout is private to
/// the host and may change in a later ABI minor. It is valid only during the
/// invocation it was minted for.
#[repr(C)]
pub struct MqCallContext {
host_data: *mut c_void,
}
impl MqCallContext {
/// Mint a context for a host invocation.
pub(crate) fn new(host_data: *mut c_void) -> Self {
Self { host_data }
}
/// Opaque host data pointer carried by this context.
pub(crate) fn host_data(&self) -> *mut c_void {
self.host_data
}
}
impl std::fmt::Debug for MqCallContext {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
f.write_str("MqCallContext(..)")
}
}
/// Host allocator callback (`MqHostApi::alloc`).
pub type MqAllocFn = unsafe extern "C" fn(host_data: *mut c_void, size: usize) -> *mut c_void;
/// Host deallocator callback (`MqHostApi::free`).
pub type MqFreeFn = unsafe extern "C" fn(host_data: *mut c_void, ptr: *mut c_void);
/// Export registration callback (`MqHostApi::register_function`).
pub type MqRegisterFunctionFn = unsafe extern "C" fn(
host_data: *mut c_void,
export_name: MqBytes,
signature_wire: MqBytes,
invoke: MqPluginInvoke,
) -> i32;
/// Capability request callback (`MqHostApi::request_capability`).
pub type MqRequestCapabilityFn = unsafe extern "C" fn(
ctx: *mut MqCallContext,
name: MqBytes,
request_wire: MqBytes,
reply_wire: *mut MqOwnedBytes,
) -> i32;
/// Plugin invocation callback (`MqPluginInvoke`).
pub type MqPluginInvoke = unsafe extern "C" fn(
ctx: *mut MqCallContext,
args_wire: MqBytes,
result_wire: *mut MqOwnedBytes,
error_wire: *mut MqOwnedBytes,
) -> i32;
/// Plugin entry point (`mq_plugin_entry_v1`).
pub type MqPluginEntryV1 =
unsafe extern "C" fn(host: *const MqHostApi, plugin: *mut MqPluginApi) -> i32;
/// Host-provided function table (`MqHostApi`).
///
/// Mirrors the C struct exactly. `struct_size` must be `sizeof(MqHostApi)` as
/// built by the host; the v1.0 contract requires all function pointers to be
/// non-NULL.
#[repr(C)]
pub struct MqHostApi {
/// `sizeof(MqHostApi)` as seen by the host.
pub struct_size: u32,
/// Host-supported ABI major (always [`ABI_MAJOR`] for this version).
pub abi_major: u32,
/// Host-supported ABI minor.
pub abi_minor: u32,
/// Opaque host state; passed back to every callback.
pub host_data: *mut c_void,
/// Host allocator; NULL on failure and for `size == 0`.
pub alloc: MqAllocFn,
/// Host deallocator for pointers returned by `alloc`.
pub free: MqFreeFn,
/// Export registration callback.
pub register_function: MqRegisterFunctionFn,
/// Capability request callback.
pub request_capability: MqRequestCapabilityFn,
}
/// Plugin version/metadata table (`MqPluginApi`).
#[repr(C)]
pub struct MqPluginApi {
/// `sizeof(MqPluginApi)` as initialized by the host.
pub struct_size: u32,
/// Plugin ABI major; must equal [`ABI_MAJOR`].
pub abi_major: u32,
/// Plugin ABI minor; the host clamps to its own supported minor.
pub abi_minor: u32,
/// Plugin metadata JSON, valid only during the entry call.
pub plugin_metadata_wire: MqBytes,
}
impl MqPluginApi {
/// Host-side initialization before calling the entry point.
pub fn host_initialized() -> Self {
Self {
struct_size: size_of::<MqPluginApi>() as u32,
abi_major: 0,
abi_minor: 0,
plugin_metadata_wire: MqBytes::EMPTY,
}
}
}
/// A negotiated ABI version.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
pub struct AbiVersion {
/// Negotiated (host) major; always [`ABI_MAJOR`].
pub major: u32,
/// Negotiated minor, clamped to the host's supported minor.
pub minor: u32,
}
impl AbiVersion {
/// The ABI version implemented by this crate.
pub const fn current() -> Self {
Self {
major: ABI_MAJOR,
minor: ABI_MINOR,
}
}
/// Construct a version pair.
pub const fn new(major: u32, minor: u32) -> Self {
Self { major, minor }
}
}
impl std::fmt::Display for AbiVersion {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
write!(f, "{}.{}", self.major, self.minor)
}
}
/// Negotiate the ABI version with a plugin reporting `major`/`minor`.
///
/// Rules (see the header's "VERSION NEGOTIATION" section):
/// - a different major version is never negotiable: the load fails;
/// - a plugin minor greater than the host minor is accepted but clamped to
/// the host's supported minor; only features at that minor may be used.
pub fn negotiate(plugin_major: u32, plugin_minor: u32) -> Result<AbiVersion, PluginError> {
if plugin_major != ABI_MAJOR {
return Err(PluginError::abi(
"abi_major_mismatch",
format!(
"plugin ABI major {plugin_major} is incompatible with host ABI major {ABI_MAJOR}"
),
)
.with_detail(format!(
"plugin abi {plugin_major}.{plugin_minor}, host abi {ABI_MAJOR}.{ABI_MINOR}"
)));
}
// Clamp to the host's supported minor. `ABI_MINOR` is 0 today, so clippy
// sees the clamp as a no-op; it is required for future minor bumps.
#[allow(clippy::unnecessary_min_or_max)]
let negotiated_minor = plugin_minor.min(ABI_MINOR);
Ok(AbiVersion::new(plugin_major, negotiated_minor))
}
/// Check a host API table handed to a plugin (plugin-side validation).
///
/// A conforming v1.0 host provides `struct_size == sizeof(MqHostApi)`,
/// `abi_major == 1` and non-NULL alloc/free/register_function/
/// request_capability pointers.
///
/// # Safety
///
/// `host` must be a readable pointer to an `MqHostApi`.
pub unsafe fn check_host_api(host: *const MqHostApi) -> Result<AbiVersion, PluginError> {
if host.is_null() {
return Err(PluginError::abi(
"host_api_null",
"host passed a NULL MqHostApi pointer",
));
}
// SAFETY: non-NULL and readable per the caller contract.
let host = unsafe { &*host };
let min_size = size_of::<MqHostApi>() as u32;
if host.struct_size < min_size {
return Err(PluginError::abi(
"host_struct_size_too_small",
format!(
"host MqHostApi struct_size {} is smaller than the required {min_size}",
host.struct_size
),
));
}
let negotiated = negotiate(host.abi_major, host.abi_minor)?;
if host.alloc as usize == 0
|| host.free as usize == 0
|| host.register_function as usize == 0
|| host.request_capability as usize == 0
{
return Err(PluginError::abi(
"host_api_incomplete",
"host MqHostApi has NULL required function pointers",
));
}
Ok(negotiated)
}
/// Plugin metadata reported through `MqPluginApi::plugin_metadata_wire`.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct PluginMetadata {
/// Plugin package name (matches `plugin.yaml`).
pub name: String,
/// Plugin package semver (informational; manifests are authoritative).
pub version: String,
}
impl PluginMetadata {
/// Encode as `plugin_metadata_wire` JSON.
pub fn to_wire(&self) -> Result<Vec<u8>, PluginError> {
serde_json::to_vec(self).map_err(|error| {
PluginError::wire("metadata_encode_failed", "could not encode plugin metadata")
.with_detail(error.to_string())
})
}
/// Decode and validate `plugin_metadata_wire` bytes.
pub fn from_wire(bytes: &[u8]) -> Result<Self, PluginError> {
if bytes.is_empty() {
return Err(PluginError::wire(
"metadata_missing",
"plugin did not provide plugin_metadata_wire",
));
}
if bytes.len() > MAX_METADATA_WIRE_BYTES {
return Err(PluginError::wire(
"metadata_too_large",
format!(
"plugin metadata is {} bytes, limit is {MAX_METADATA_WIRE_BYTES}",
bytes.len()
),
));
}
let metadata: Self = serde_json::from_slice(bytes).map_err(|error| {
PluginError::wire(
"metadata_invalid",
"plugin_metadata_wire is not a valid metadata object",
)
.with_detail(error.to_string())
})?;
if metadata.name.trim().is_empty() {
return Err(PluginError::wire(
"metadata_invalid",
"plugin metadata name must not be empty",
));
}
Ok(metadata)
}
}
// Compile-time layout assertions. These are the frozen ABI contract.
#[cfg(target_pointer_width = "64")]
const _: () = {
assert!(size_of::<MqBytes>() == 16, "MqBytes must be 16 bytes");
assert!(align_of::<MqBytes>() == 8, "MqBytes must align to 8");
assert!(
size_of::<MqOwnedBytes>() == 16,
"MqOwnedBytes must be 16 bytes"
);
assert!(
align_of::<MqOwnedBytes>() == 8,
"MqOwnedBytes must align to 8"
);
assert!(
size_of::<MqPluginApi>() == 32,
"MqPluginApi must be 32 bytes"
);
assert!(
align_of::<MqPluginApi>() == 8,
"MqPluginApi must align to 8"
);
assert!(size_of::<MqHostApi>() == 56, "MqHostApi must be 56 bytes");
assert!(align_of::<MqHostApi>() == 8, "MqHostApi must align to 8");
assert!(
size_of::<MqPluginInvoke>() == 8,
"MqPluginInvoke must be 8 bytes"
);
};
#[cfg(target_pointer_width = "32")]
const _: () = {
assert!(size_of::<MqBytes>() == 8, "MqBytes must be 8 bytes");
assert!(
size_of::<MqOwnedBytes>() == 8,
"MqOwnedBytes must be 8 bytes"
);
assert!(
size_of::<MqPluginApi>() == 20,
"MqPluginApi must be 20 bytes"
);
assert!(size_of::<MqHostApi>() == 28, "MqHostApi must be 28 bytes");
};
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn layout_matches_c_header_on_64_bit() {
if cfg!(target_pointer_width = "64") {
assert_eq!(size_of::<MqBytes>(), 16);
assert_eq!(align_of::<MqBytes>(), 8);
assert_eq!(size_of::<MqOwnedBytes>(), 16);
assert_eq!(size_of::<MqPluginApi>(), 32);
assert_eq!(size_of::<MqHostApi>(), 56);
assert_eq!(align_of::<MqHostApi>(), 8);
}
}
#[test]
fn negotiation_accepts_same_major_and_clamps_minor() {
assert_eq!(negotiate(1, 0).expect("v1.0"), AbiVersion::new(1, 0));
assert_eq!(negotiate(1, 1).expect("v1.1"), AbiVersion::new(1, 0));
assert_eq!(negotiate(1, 99).expect("v1.99"), AbiVersion::new(1, 0));
}
#[test]
fn negotiation_rejects_other_majors() {
for major in [0, 2, 3, u32::MAX] {
let error = negotiate(major, 0).expect_err("major must be rejected");
assert_eq!(error.kind, crate::error::ErrorKind::Abi);
assert_eq!(error.code, "abi_major_mismatch");
}
}
#[test]
fn metadata_wire_roundtrip() {
let metadata = PluginMetadata {
name: "demo.solver".into(),
version: "1.2.3".into(),
};
let bytes = metadata.to_wire().expect("encode");
assert_eq!(PluginMetadata::from_wire(&bytes).expect("decode"), metadata);
}
#[test]
fn metadata_rejects_empty_and_invalid() {
assert_eq!(
PluginMetadata::from_wire(b"").expect_err("empty").code,
"metadata_missing"
);
assert_eq!(
PluginMetadata::from_wire(b"not-json")
.expect_err("invalid")
.code,
"metadata_invalid"
);
assert_eq!(
PluginMetadata::from_wire(br#"{"name":"","version":"1.0.0"}"#)
.expect_err("empty name")
.code,
"metadata_invalid"
);
}
}
+269
View File
@@ -0,0 +1,269 @@
//! Artifact target triples and content-hash verification.
//!
//! Native plugin artifacts are target-specific: the C ABI layout depends on
//! pointer width and endianness, so the host only loads an artifact built for
//! exactly its own target triple. Installed/verified does not mean trusted or
//! authorized; see the header's "A C ABI IS NOT A SANDBOX" section.
use std::fs;
use std::io::Read;
use std::path::Path;
use sha2::{Digest, Sha256};
use crate::error::PluginError;
/// Length of a lowercase hexadecimal sha256 digest.
pub const SHA256_HEX_LEN: usize = 64;
/// Compute the lowercase hexadecimal sha256 digest of `bytes`.
pub fn sha256_bytes(bytes: &[u8]) -> String {
let mut hasher = Sha256::new();
hasher.update(bytes);
hex::encode(hasher.finalize())
}
/// Compute the lowercase hexadecimal sha256 digest of a file.
pub fn sha256_file(path: &Path) -> Result<String, PluginError> {
if !path.is_file() {
return Err(PluginError::artifact(
"missing_artifact",
format!("artifact file `{}` does not exist", path.display()),
));
}
let mut file = fs::File::open(path).map_err(|error| {
PluginError::artifact(
"artifact_unreadable",
format!("artifact file `{}` could not be opened", path.display()),
)
.with_detail(error.to_string())
})?;
let mut hasher = Sha256::new();
let mut buffer = [0u8; 64 * 1024];
loop {
let read = file.read(&mut buffer).map_err(|error| {
PluginError::artifact(
"artifact_unreadable",
format!("artifact file `{}` could not be read", path.display()),
)
.with_detail(error.to_string())
})?;
if read == 0 {
break;
}
hasher.update(&buffer[..read]);
}
Ok(hex::encode(hasher.finalize()))
}
/// Validate that `digest` looks like a sha256 hex digest.
pub fn is_valid_sha256_hex(digest: &str) -> bool {
digest.len() == SHA256_HEX_LEN && digest.bytes().all(|byte| byte.is_ascii_hexdigit())
}
/// Verify a file's sha256 digest against `expected` (case-insensitive hex).
/// Manifests conventionally use lowercase hex.
///
/// A missing file yields `missing_artifact`; a digest mismatch yields
/// `hash_mismatch`. Verification is content-only: it proves the artifact is
/// the one described by the manifest, not that the plugin is trustworthy.
pub fn verify_sha256_file(path: &Path, expected: &str) -> Result<(), PluginError> {
if !is_valid_sha256_hex(expected) {
return Err(PluginError::artifact(
"invalid_sha256",
"manifest sha256 must be a 64-character hexadecimal digest",
));
}
let actual = sha256_file(path)?;
if !actual.eq_ignore_ascii_case(expected) {
return Err(PluginError::artifact(
"hash_mismatch",
format!(
"artifact `{}` content hash does not match the manifest",
path.display()
),
)
.with_detail(format!("expected {expected}, actual {actual}")));
}
Ok(())
}
/// A parsed target triple such as `x86_64-unknown-linux-gnu`.
#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
pub struct TargetTriple {
triple: String,
}
impl TargetTriple {
/// Parse and validate a target triple.
pub fn parse(triple: &str) -> Result<Self, PluginError> {
let parts: Vec<&str> = triple.split('-').collect();
if parts.len() < 3 || parts.len() > 4 {
return Err(PluginError::artifact(
"invalid_target_triple",
format!("`{triple}` is not a target triple"),
));
}
if parts.iter().any(|part| {
part.is_empty()
|| !part
.bytes()
.all(|byte| byte.is_ascii_alphanumeric() || byte == b'_')
}) {
return Err(PluginError::artifact(
"invalid_target_triple",
format!("`{triple}` contains an invalid target component"),
));
}
Ok(Self {
triple: triple.to_ascii_lowercase(),
})
}
/// The canonical triple string.
pub fn as_str(&self) -> &str {
&self.triple
}
/// The architecture component (`x86_64`, `aarch64`, ...).
pub fn arch(&self) -> &str {
self.triple.split('-').next().unwrap_or_default()
}
/// Pointer width in bytes implied by the architecture, if known.
pub fn word_size(&self) -> Option<u32> {
match self.arch() {
"x86_64" | "aarch64" | "arm64" | "powerpc64" | "powerpc64le" | "s390x" | "riscv64"
| "loongarch64" | "mips64" | "mips64el" | "sparc64" => Some(8),
"i386" | "i486" | "i586" | "i686" | "arm" | "armv5te" | "armv7" | "armv7a"
| "wasm32" | "mips" | "mipsel" | "riscv32" | "powerpc" | "sparc" => Some(4),
_ => None,
}
}
}
impl std::fmt::Display for TargetTriple {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
f.write_str(&self.triple)
}
}
/// The host's own build target.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct HostTarget {
triple: TargetTriple,
}
impl HostTarget {
/// Construct from an explicit triple (used by tests and cross-checking).
pub fn from_triple(triple: TargetTriple) -> Self {
Self { triple }
}
/// The target this process was compiled for.
pub fn current() -> Self {
Self {
triple: current_target_triple(),
}
}
/// The host target triple.
pub fn triple(&self) -> &TargetTriple {
&self.triple
}
/// The host pointer width in bytes.
pub fn word_size(&self) -> u32 {
usize::BITS / 8
}
}
/// Compute this process's target triple in the conventional 3/4-component
/// form used by Rust target triples.
pub fn current_target_triple() -> TargetTriple {
let arch = std::env::consts::ARCH;
let os = std::env::consts::OS;
let triple = match os {
"linux" => {
let environment = if cfg!(target_env = "musl") {
"musl"
} else if cfg!(target_env = "ohos") {
"ohos"
} else {
"gnu"
};
format!("{arch}-unknown-linux-{environment}")
}
"macos" => format!("{arch}-apple-darwin"),
"ios" => format!("{arch}-apple-ios"),
"windows" => format!("{arch}-pc-windows-msvc"),
"freebsd" => format!("{arch}-unknown-freebsd"),
"netbsd" => format!("{arch}-unknown-netbsd"),
"openbsd" => format!("{arch}-unknown-openbsd"),
"android" => format!("{arch}-linux-android"),
"wasi" => format!("{arch}-wasi-wasm"),
other => format!("{arch}-unknown-{other}"),
};
// The mapping above always yields a parseable triple.
TargetTriple::parse(&triple).unwrap_or_else(|_| TargetTriple {
triple: triple.to_ascii_lowercase(),
})
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn sha256_matches_known_vector() {
assert_eq!(
sha256_bytes(b""),
"e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
);
assert_eq!(
sha256_bytes(b"abc"),
"ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad"
);
}
#[test]
fn hex_validation_is_strict() {
assert!(is_valid_sha256_hex(&"a".repeat(64)));
assert!(!is_valid_sha256_hex(&"a".repeat(63)));
assert!(!is_valid_sha256_hex(&"g".repeat(64)));
}
#[test]
fn target_triple_parsing_and_word_size() {
let triple = TargetTriple::parse("x86_64-unknown-linux-gnu").expect("valid");
assert_eq!(triple.arch(), "x86_64");
assert_eq!(triple.word_size(), Some(8));
assert_eq!(
TargetTriple::parse("aarch64-apple-darwin")
.expect("valid")
.word_size(),
Some(8)
);
assert_eq!(
TargetTriple::parse("i686-unknown-linux-gnu")
.expect("valid")
.word_size(),
Some(4)
);
// Syntactically valid but unknown architecture: word size unknown.
assert_eq!(
TargetTriple::parse("not-a-triple")
.expect("syntactic triple")
.word_size(),
None
);
assert!(TargetTriple::parse("x86_64").is_err());
assert!(TargetTriple::parse("x86_64--linux-gnu").is_err());
}
#[test]
fn host_triple_is_parseable_and_matches_word_size() {
let target = HostTarget::current();
assert_eq!(target.triple().word_size(), Some(target.word_size()));
}
}
+187
View File
@@ -0,0 +1,187 @@
//! Structured plugin errors shared by host-side loading, manifest validation,
//! artifact verification, wire decoding and invocation.
//!
//! Errors are deliberately data, not opaque strings: the host CLI renders
//! them for humans, the wire protocol ships them to workers/plugins, and
//! tests assert on the stable machine-readable `code`.
use serde::{Deserialize, Serialize};
/// Stable error category.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum ErrorKind {
/// `plugin.yaml` could not be parsed or is semantically invalid.
Manifest,
/// ABI major/minor negotiation or ABI table mismatch.
Abi,
/// Artifact resolution, target triples and sha256 verification.
Artifact,
/// Dynamic library loading or entry-point resolution.
Load,
/// `wire_version` 1 JSON envelope is malformed or over the size limit.
Wire,
/// A requested host capability was not granted or failed.
Capability,
/// A plugin invocation failed or returned an invalid result.
Invoke,
/// A valid-but-unsupported feature (plugin kind, ABI requirement, ...).
Unsupported,
}
impl ErrorKind {
/// Stable snake_case name used on the wire.
pub const fn as_str(self) -> &'static str {
match self {
ErrorKind::Manifest => "manifest",
ErrorKind::Abi => "abi",
ErrorKind::Artifact => "artifact",
ErrorKind::Load => "load",
ErrorKind::Wire => "wire",
ErrorKind::Capability => "capability",
ErrorKind::Invoke => "invoke",
ErrorKind::Unsupported => "unsupported",
}
}
}
impl ErrorKind {
/// Parse a stable wire name back into an error category.
pub fn from_wire_name(name: &str) -> Option<Self> {
match name {
"manifest" => Some(ErrorKind::Manifest),
"abi" => Some(ErrorKind::Abi),
"artifact" => Some(ErrorKind::Artifact),
"load" => Some(ErrorKind::Load),
"wire" => Some(ErrorKind::Wire),
"capability" => Some(ErrorKind::Capability),
"invoke" => Some(ErrorKind::Invoke),
"unsupported" => Some(ErrorKind::Unsupported),
_ => None,
}
}
}
impl std::fmt::Display for ErrorKind {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
f.write_str(self.as_str())
}
}
/// Structured, serializable plugin error.
///
/// `kind` is the category, `code` is a stable machine-readable identifier
/// (e.g. `abi_major_mismatch`), `message` is human-readable and must never
/// contain secrets, and `detail` is optional extra context (paths, ABI
/// numbers, ...) that is equally safe to log.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, thiserror::Error)]
#[error("[{kind}] {code}: {message}")]
pub struct PluginError {
/// Error category.
pub kind: ErrorKind,
/// Stable machine-readable error code.
pub code: String,
/// Human-readable summary (never contains secrets).
pub message: String,
/// Optional non-sensitive detail for logs/diagnostics.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub detail: Option<String>,
/// Whether the caller may retry the operation.
#[serde(default, skip_serializing_if = "is_false")]
pub recoverable: bool,
}
fn is_false(value: &bool) -> bool {
!*value
}
impl PluginError {
/// Create an error with no detail.
pub fn new(kind: ErrorKind, code: impl Into<String>, message: impl Into<String>) -> Self {
Self {
kind,
code: code.into(),
message: message.into(),
detail: None,
recoverable: false,
}
}
/// Attach non-sensitive detail.
#[must_use]
pub fn with_detail(mut self, detail: impl Into<String>) -> Self {
self.detail = Some(detail.into());
self
}
/// Mark the operation as retryable.
#[must_use]
pub fn recoverable(mut self) -> Self {
self.recoverable = true;
self
}
/// A manifest parse/validation error.
pub fn manifest(code: impl Into<String>, message: impl Into<String>) -> Self {
Self::new(ErrorKind::Manifest, code, message)
}
/// An ABI negotiation/table error.
pub fn abi(code: impl Into<String>, message: impl Into<String>) -> Self {
Self::new(ErrorKind::Abi, code, message)
}
/// An artifact resolution/hash error.
pub fn artifact(code: impl Into<String>, message: impl Into<String>) -> Self {
Self::new(ErrorKind::Artifact, code, message)
}
/// A dynamic library/entry-point load error.
pub fn load(code: impl Into<String>, message: impl Into<String>) -> Self {
Self::new(ErrorKind::Load, code, message)
}
/// A wire envelope error.
pub fn wire(code: impl Into<String>, message: impl Into<String>) -> Self {
Self::new(ErrorKind::Wire, code, message)
}
/// A capability error.
pub fn capability(code: impl Into<String>, message: impl Into<String>) -> Self {
Self::new(ErrorKind::Capability, code, message)
}
/// An invocation error.
pub fn invoke(code: impl Into<String>, message: impl Into<String>) -> Self {
Self::new(ErrorKind::Invoke, code, message)
}
/// An unsupported-feature error.
pub fn unsupported(code: impl Into<String>, message: impl Into<String>) -> Self {
Self::new(ErrorKind::Unsupported, code, message)
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn error_is_serializable_roundtrip() {
let error = PluginError::abi("abi_major_mismatch", "host is ABI 1")
.with_detail("plugin reported ABI 2.0");
let json = serde_json::to_string(&error).expect("serialize");
assert!(json.contains("\"kind\":\"abi\""));
assert!(json.contains("\"code\":\"abi_major_mismatch\""));
let back: PluginError = serde_json::from_str(&json).expect("deserialize");
assert_eq!(back, error);
}
#[test]
fn optional_fields_are_omitted() {
let error = PluginError::manifest("bad_manifest", "missing plugin block");
let json = serde_json::to_string(&error).expect("serialize");
assert!(!json.contains("detail"));
assert!(!json.contains("recoverable"));
}
}
+49
View File
@@ -0,0 +1,49 @@
//! Versioned plugin C ABI v1 bindings, manifest validation and artifact
//! loading (host side).
//!
//! This crate is the host-side counterpart of
//! `include/marqdo_plugin_abi_v1.h` (the frozen C ABI) and of the
//! `marqdo-plugin-sdk` crate (the plugin-developer side). It implements the
//! blueprint section 10 contract:
//!
//! - stable `#[repr(C)]` Rust mirrors of the C types, with compile-time layout
//! assertions and major/minor negotiation ([`abi`]),
//! - `plugin.yaml` parsing and validation ([`manifest`]),
//! - target-triple artifact selection and sha256 verification ([`artifact`]),
//! - `wire_version` 1 JSON request/response envelopes with typed value tags
//! ([`wire`]),
//! - a native loader/invocation bridge built on `libloading` ([`loader`]),
//! - structured, serializable [`PluginError`]s ([`error`]).
//!
//! A C ABI is not a sandbox: native plugins run in-process and require an
//! explicit trust decision. This crate only validates and loads what the
//! caller already decided to trust; it never grants capabilities.
pub mod abi;
pub mod artifact;
pub mod error;
pub mod loader;
pub mod manifest;
pub mod wire;
pub use abi::result as result_code;
pub use abi::{
check_host_api, negotiate, AbiVersion, MqAllocFn, MqBytes, MqCallContext, MqFreeFn, MqHostApi,
MqOwnedBytes, MqPluginApi, MqPluginEntryV1, MqPluginInvoke, MqRegisterFunctionFn,
MqRequestCapabilityFn, PluginMetadata, ABI_MAJOR, ABI_MINOR, ABI_VERSION_STRING, ENTRY_SYMBOL,
};
pub use artifact::{
current_target_triple, is_valid_sha256_hex, sha256_bytes, sha256_file, verify_sha256_file,
HostTarget, TargetTriple,
};
pub use error::{ErrorKind, PluginError};
pub use loader::{CapabilityHandler, LoadOptions, LoadedPlugin, RegisteredExport};
pub use manifest::{
AbiRequirement, Artifact, Export, PackageVersion, PluginInfo, PluginKind, PluginManifest,
KNOWN_CAPABILITIES,
};
pub use marqdo_value::Value;
pub use wire::{
bool_from_value, int_from_value, text_from_value, to_wire_json, WireContext, WireErrorBody,
WireRequest, WireResponse, WIRE_VERSION,
};
+710
View File
@@ -0,0 +1,710 @@
//! Native dynamic-library loader and minimal invocation bridge.
//!
//! Lifecycle implemented here (blueprint section 10.5):
//! `validate manifest -> resolve artifact -> verify hash -> negotiate ABI ->
//! register exports -> load library -> verify metadata/exports -> invoke`.
//!
//! Capability *authorization* happens in the host layer before/around
//! [`LoadedPlugin::open`]; this module only exposes the `request_capability`
//! bridge so an already-authorized capability can be consumed.
use std::collections::BTreeMap;
use std::ffi::c_void;
use std::path::Path;
use std::ptr;
use libloading::{Library, Symbol};
use serde::Deserialize;
use crate::abi::{
check_host_api, negotiate, result, AbiVersion, MqBytes, MqCallContext, MqHostApi, MqOwnedBytes,
MqPluginApi, MqPluginEntryV1, MqPluginInvoke, PluginMetadata, ABI_MAJOR, ABI_MINOR,
ENTRY_SYMBOL, MAX_CAPABILITY_REPLY_BYTES, MAX_ERROR_WIRE_BYTES, MAX_EXPORT_NAME_BYTES,
MAX_RESULT_WIRE_BYTES, MAX_SIGNATURE_WIRE_BYTES,
};
use crate::artifact::HostTarget;
use crate::error::PluginError;
use crate::manifest::{PluginKind, PluginManifest};
use crate::wire::{WireRequest, WireResponse};
/// A callback the host installs to answer capability requests from a plugin.
///
/// The handler is invoked on the host invocation thread, one call at a time.
/// It must consult the host's authorization layer and must not perform
/// effects that the loaded plugin was not granted.
pub type CapabilityHandler = Box<dyn FnMut(&str, &[u8]) -> Result<Vec<u8>, PluginError> + 'static>;
/// Options for loading a native plugin.
pub struct LoadOptions {
/// Host target used to select the manifest artifact.
pub host_target: HostTarget,
/// Optional capability bridge; without one every request is denied.
pub capability_handler: Option<CapabilityHandler>,
}
impl Default for LoadOptions {
fn default() -> Self {
Self {
host_target: HostTarget::current(),
capability_handler: None,
}
}
}
impl std::fmt::Debug for LoadOptions {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
f.debug_struct("LoadOptions")
.field("host_target", &self.host_target)
.field(
"capability_handler",
&self.capability_handler.as_ref().map(|_| "<handler>"),
)
.finish()
}
}
/// One export registered by a loaded plugin.
#[derive(Debug, Clone)]
pub struct RegisteredExport {
/// Fully qualified export name.
pub name: String,
/// Signature string reported through `signature_wire`.
pub signature: String,
invoke: MqPluginInvoke,
}
impl RegisteredExport {
/// The registered export name.
pub fn name(&self) -> &str {
&self.name
}
/// The registered signature string.
pub fn signature(&self) -> &str {
&self.signature
}
}
/// Host state shared with the loaded plugin through `MqHostApi::host_data`
/// and each invocation's `MqCallContext`.
struct HostState {
registrations: Vec<RegisteredExport>,
capability_handler: Option<CapabilityHandler>,
}
/// A loaded, validated native plugin instance.
///
/// # Threading and unloading
///
/// A [`LoadedPlugin`] is single-threaded: every invocation must happen on the
/// thread that loaded it, one at a time. Dropping it unloads the native
/// library, so it must only be dropped after all calls have returned (the
/// `&mut self` receiver of [`LoadedPlugin::invoke`] enforces this within Rust).
/// ABI v1 has no hot-reload and no shutdown callback; dropping is a shutdown
/// operation, not a reload mechanism.
///
/// Because ABI v1 plugins may keep the host table in a process-global (the
/// single-threaded contract), do not load the same artifact path twice in one
/// process; use one instance per artifact instead.
pub struct LoadedPlugin {
/// Keeps the dynamic library mapped for as long as the plugin is alive.
_library: Library,
host_state: Box<HostState>,
/// Heap-allocated so the pointer handed to the plugin at entry time stays
/// valid for the plugin lifetime (the plugin may retain it, see header).
host_api: Box<MqHostApi>,
exports: BTreeMap<String, RegisteredExport>,
metadata: PluginMetadata,
abi: AbiVersion,
}
impl std::fmt::Debug for LoadedPlugin {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
f.debug_struct("LoadedPlugin")
.field("name", &self.metadata.name)
.field("version", &self.metadata.version)
.field("abi", &self.abi)
.field("exports", &self.exports.keys().collect::<Vec<_>>())
.finish()
}
}
/// Signature wire decoded from `MqHostApi::register_function`.
#[derive(Deserialize)]
struct SignatureWire {
signature: String,
}
impl LoadedPlugin {
/// Validate a manifest and load the matching native artifact from
/// `base_dir` (the directory containing `plugin.yaml`).
///
/// This runs the full local lifecycle: manifest validation, artifact
/// resolution/hash verification, dynamic library loading, ABI
/// negotiation, export registration and metadata cross-checking.
pub fn open(manifest: &PluginManifest, base_dir: &Path) -> Result<Self, PluginError> {
Self::open_with(manifest, base_dir, LoadOptions::default())
}
/// Like [`LoadedPlugin::open`] with explicit target and capability bridge.
pub fn open_with(
manifest: &PluginManifest,
base_dir: &Path,
options: LoadOptions,
) -> Result<Self, PluginError> {
manifest.validate()?;
if manifest.plugin.kind != PluginKind::Native {
return Err(PluginError::unsupported(
"plugin_kind_not_loadable_in_process",
format!(
"plugin kind `{}` cannot be loaded natively; use the isolated worker path",
manifest.plugin.kind.as_str()
),
));
}
let (path, _artifact) = manifest.verify_artifact(base_dir, &options.host_target)?;
// SAFETY: `Library::new` runs the platform loader against a path whose
// content hash was just verified. Loading native code is a trust
// decision made by the caller, not a sandbox.
let library = unsafe { Library::new(&path) }.map_err(|error| {
PluginError::load(
"library_load_failed",
format!("dynamic library `{}` could not be loaded", path.display()),
)
.with_detail(error.to_string())
})?;
let mut plugin_api = MqPluginApi::host_initialized();
let mut host_state = Box::new(HostState {
registrations: Vec::new(),
capability_handler: options.capability_handler,
});
let host_api = Box::new(MqHostApi {
struct_size: size_of::<MqHostApi>() as u32,
abi_major: ABI_MAJOR,
abi_minor: ABI_MINOR,
// The HostState Box is heap-allocated, so this pointer survives
// moves of the LoadedPlugin value.
host_data: (&mut *host_state) as *mut HostState as *mut c_void,
alloc: host_alloc,
free: host_free,
register_function: host_register_function,
request_capability: host_request_capability,
});
let entry_code = {
// SAFETY: symbol lookup in a library we just loaded; the symbol
// type is the documented ABI v1 entry signature.
let entry: Symbol<MqPluginEntryV1> =
unsafe { library.get(ENTRY_SYMBOL) }.map_err(|error| {
PluginError::load(
"missing_entry_symbol",
"plugin does not export `mq_plugin_entry_v1`",
)
.with_detail(error.to_string())
})?;
// SAFETY: entry point contract: one call, same thread, host table
// and plugin table valid for the duration of the call.
unsafe { entry(&*host_api as *const MqHostApi, &mut plugin_api) }
};
if entry_code != result::OK {
return Err(entry_failure(entry_code));
}
let required_size = size_of::<MqPluginApi>() as u32;
if plugin_api.struct_size < required_size {
return Err(PluginError::abi(
"plugin_api_struct_size_too_small",
format!(
"plugin reported MqPluginApi struct_size {}, host requires at least {required_size}",
plugin_api.struct_size
),
));
}
let abi = negotiate(plugin_api.abi_major, plugin_api.abi_minor)?;
// SAFETY: plugin-owned metadata is documented as valid for the entry
// call only; we copy it here, immediately after the call.
let metadata_bytes = unsafe { plugin_api.plugin_metadata_wire.as_slice() }
.map_err(|error| {
PluginError::wire(
"metadata_invalid",
"plugin metadata buffer violates the pointer/length contract",
)
.with_detail(error.to_string())
})?
.to_vec();
let metadata = PluginMetadata::from_wire(&metadata_bytes)?;
if metadata.name != manifest.plugin.name {
return Err(PluginError::manifest(
"metadata_name_mismatch",
format!(
"plugin reports name `{}` but manifest declares `{}`",
metadata.name, manifest.plugin.name
),
));
}
let package_version = manifest.package_version()?;
if metadata.version != package_version.raw {
return Err(PluginError::manifest(
"metadata_version_mismatch",
format!(
"plugin reports version `{}` but manifest declares `{}`",
metadata.version, package_version.raw
),
));
}
let registrations = std::mem::take(&mut host_state.registrations);
let exports = cross_check_exports(manifest, registrations)?;
Ok(Self {
_library: library,
host_state,
host_api,
exports,
metadata,
abi,
})
}
/// Negotiated ABI version.
pub fn abi_version(&self) -> AbiVersion {
self.abi
}
/// Plugin metadata reported by the plugin and cross-checked with the
/// manifest name/version.
pub fn metadata(&self) -> &PluginMetadata {
&self.metadata
}
/// Registered exports in name order.
pub fn exports(&self) -> impl Iterator<Item = &RegisteredExport> {
self.exports.values()
}
/// Invoke `request.function` with the request envelope.
///
/// The plugin must return exactly one wire response envelope. Plugin-side
/// failures are surfaced as structured [`PluginError`]s.
pub fn invoke(&mut self, request: &WireRequest) -> Result<WireResponse, PluginError> {
request.validate()?;
let args_wire = request.to_json_bytes()?;
let response_wire = self.invoke_raw(&request.function, &args_wire)?;
WireResponse::from_json_bytes(&response_wire)?.into_result()
}
/// Raw invocation bridge: call `function` with already-encoded request
/// bytes and return the raw response bytes on success.
///
/// This is primarily for ABI conformance tests; prefer
/// [`LoadedPlugin::invoke`] for normal use.
pub fn invoke_raw(&mut self, function: &str, args_wire: &[u8]) -> Result<Vec<u8>, PluginError> {
if args_wire.len() > crate::abi::MAX_REQUEST_WIRE_BYTES {
return Err(PluginError::wire(
"request_too_large",
format!(
"request wire is {} bytes, limit is {}",
args_wire.len(),
crate::abi::MAX_REQUEST_WIRE_BYTES
),
));
}
let invoke = self
.exports
.get(function)
.map(|export| export.invoke)
.ok_or_else(|| {
PluginError::invoke(
"unknown_export",
format!("plugin does not export `{function}`"),
)
})?;
let mut context =
MqCallContext::new((&mut *self.host_state) as *mut HostState as *mut c_void);
let mut result_wire = MqOwnedBytes::EMPTY;
let mut error_wire = MqOwnedBytes::EMPTY;
// SAFETY: invoking the plugin callback with valid buffers for the
// duration of the call; the plugin owns output allocation via the
// host allocator, which we free below after copying.
let code = unsafe {
invoke(
&mut context as *mut MqCallContext,
MqBytes::from_slice(args_wire),
&mut result_wire,
&mut error_wire,
)
};
let host_api: &MqHostApi = &self.host_api;
// SAFETY: result/error buffers are the plugin's outputs; copy and
// release them exactly once.
let (result_bytes, error_bytes) = unsafe {
(
take_host_buffer(host_api, &mut result_wire, MAX_RESULT_WIRE_BYTES, "result")?,
take_host_buffer(host_api, &mut error_wire, MAX_ERROR_WIRE_BYTES, "error")?,
)
};
if code != result::OK {
if error_bytes.is_empty() {
return Err(PluginError::invoke(
"plugin_call_failed",
format!(
"plugin returned result code {} without an error envelope",
result::name(code)
),
));
}
return match WireResponse::from_error_json_bytes(&error_bytes) {
Ok(response) => match response.into_result() {
Err(error) => Err(error),
Ok(_) => Err(PluginError::invoke(
"plugin_call_failed",
"plugin returned a success envelope with a failure code",
)),
},
Err(error) => Err(PluginError::invoke(
"plugin_call_failed",
format!(
"plugin returned result code {} with an invalid error envelope",
result::name(code)
),
)
.with_detail(error.to_string())),
};
}
if !error_bytes.is_empty() {
return Err(PluginError::invoke(
"unexpected_error_buffer",
"plugin returned success but filled error_wire",
));
}
if result_bytes.is_empty() {
return Err(PluginError::invoke(
"missing_result_buffer",
"plugin returned success but did not fill result_wire",
));
}
Ok(result_bytes)
}
}
fn entry_failure(code: i32) -> PluginError {
if code == result::ABI_MISMATCH {
PluginError::abi(
"plugin_rejected_host_abi",
"plugin rejected the host ABI table during the entry call",
)
.with_detail(format!("plugin returned `{}`", result::name(code)))
} else {
PluginError::load(
"entry_point_failed",
"plugin entry point returned a failure code",
)
.with_detail(format!(
"returned `{}` ({code}); {}",
result::name(code),
if code == result::REGISTRATION {
"an export could not be registered"
} else {
"see the plugin SDK for result-code semantics"
}
))
}
}
fn cross_check_exports(
manifest: &PluginManifest,
registrations: Vec<RegisteredExport>,
) -> Result<BTreeMap<String, RegisteredExport>, PluginError> {
let mut registered: BTreeMap<String, RegisteredExport> = BTreeMap::new();
for export in registrations {
if registered.insert(export.name.clone(), export).is_some() {
return Err(PluginError::load(
"duplicate_registered_export",
"plugin registered the same export more than once",
));
}
}
let declared: BTreeMap<&str, &str> = manifest
.plugin
.exports
.iter()
.map(|export| (export.name.as_str(), export.signature.as_str()))
.collect();
for (name, signature) in &declared {
let Some(registered_export) = registered.get(*name) else {
return Err(PluginError::load(
"export_not_registered",
format!("plugin did not register declared export `{name}`"),
));
};
if registered_export.signature.trim() != signature.trim() {
return Err(PluginError::load(
"export_signature_mismatch",
format!("export `{name}` signature differs between manifest and registration"),
)
.with_detail(format!(
"manifest `{signature}`, registered `{}`",
registered_export.signature
)));
}
}
for name in registered.keys() {
if !declared.contains_key(name.as_str()) {
return Err(PluginError::load(
"unexpected_export",
format!("plugin registered undeclared export `{name}`"),
));
}
}
Ok(registered)
}
/// Host allocator: `malloc`-like, with an internal size header so the matching
/// `free` needs no length argument. Returns NULL for `size == 0`.
unsafe extern "C" fn host_alloc(_host_data: *mut c_void, size: usize) -> *mut c_void {
const HEADER: usize = 16;
const ALIGN: usize = 16;
if size == 0 {
return ptr::null_mut();
}
let Some(total) = size.checked_add(HEADER) else {
return ptr::null_mut();
};
let Ok(layout) = std::alloc::Layout::from_size_align(total, ALIGN) else {
return ptr::null_mut();
};
// SAFETY: layout has non-zero size (size > 0), checked for overflow.
let base = unsafe { std::alloc::alloc(layout) };
if base.is_null() {
return ptr::null_mut();
}
// SAFETY: base has at least HEADER bytes and is 16-byte aligned.
unsafe { (base as *mut usize).write(size) };
// SAFETY: offset stays within the allocation.
unsafe { base.add(HEADER) as *mut c_void }
}
/// Host deallocator paired with [`host_alloc`].
unsafe extern "C" fn host_free(_host_data: *mut c_void, pointer: *mut c_void) {
const HEADER: usize = 16;
const ALIGN: usize = 16;
if pointer.is_null() {
return;
}
// SAFETY: only pointers returned by host_alloc are freed here (ABI
// contract); the header stores the original requested size.
unsafe {
let base = (pointer as *mut u8).sub(HEADER);
let size = (base as *const usize).read();
let layout = std::alloc::Layout::from_size_align_unchecked(size + HEADER, ALIGN);
std::alloc::dealloc(base, layout);
}
}
/// Host export-registration callback.
unsafe extern "C" fn host_register_function(
host_data: *mut c_void,
export_name: MqBytes,
signature_wire: MqBytes,
invoke: MqPluginInvoke,
) -> i32 {
let result = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
// SAFETY: host_data points at the HostState owned by the loading
// LoadedPlugin for the duration of the entry call.
unsafe { register_function_impl(host_data, export_name, signature_wire, invoke) }
}));
result.unwrap_or(result::INTERNAL)
}
unsafe fn register_function_impl(
host_data: *mut c_void,
export_name: MqBytes,
signature_wire: MqBytes,
invoke: MqPluginInvoke,
) -> i32 {
if host_data.is_null() {
return result::INVALID_ARGUMENT;
}
// SAFETY: non-NULL host_data per the ABI contract.
let state = unsafe { &mut *(host_data as *mut HostState) };
// SAFETY: borrowed buffers are valid for the duration of this callback.
let name_bytes = match unsafe { export_name.as_slice() } {
Ok(bytes) => bytes,
Err(_) => return result::INVALID_ARGUMENT,
};
if name_bytes.is_empty() || name_bytes.len() > MAX_EXPORT_NAME_BYTES {
return result::INVALID_ARGUMENT;
}
let Ok(name) = std::str::from_utf8(name_bytes) else {
return result::INVALID_ARGUMENT;
};
// SAFETY: borrowed buffers are valid for the duration of this callback.
let signature_bytes = match unsafe { signature_wire.as_slice() } {
Ok(bytes) => bytes,
Err(_) => return result::INVALID_ARGUMENT,
};
if signature_bytes.len() > MAX_SIGNATURE_WIRE_BYTES {
return result::INVALID_ARGUMENT;
}
let Ok(signature) = serde_json::from_slice::<SignatureWire>(signature_bytes) else {
return result::BAD_WIRE;
};
if signature.signature.trim().is_empty() {
return result::BAD_WIRE;
}
if state
.registrations
.iter()
.any(|registered| registered.name == name)
{
return result::REGISTRATION;
}
state.registrations.push(RegisteredExport {
name: name.to_string(),
signature: signature.signature,
invoke,
});
result::OK
}
/// Host capability-request callback.
unsafe extern "C" fn host_request_capability(
ctx: *mut MqCallContext,
name: MqBytes,
request_wire: MqBytes,
reply_wire: *mut MqOwnedBytes,
) -> i32 {
let result = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
// SAFETY: pointers follow the invocation ABI contract; buffers are
// borrowed for the duration of this callback.
unsafe { request_capability_impl(ctx, name, request_wire, reply_wire) }
}));
result.unwrap_or(result::INTERNAL)
}
unsafe fn request_capability_impl(
ctx: *mut MqCallContext,
name: MqBytes,
request_wire: MqBytes,
reply_wire: *mut MqOwnedBytes,
) -> i32 {
if ctx.is_null() || reply_wire.is_null() {
return result::INVALID_ARGUMENT;
}
// SAFETY: output pointer is non-NULL and host-provided.
unsafe { *reply_wire = MqOwnedBytes::EMPTY };
// SAFETY: ctx was minted by this host for the current invocation.
let state_pointer = unsafe { (*ctx).host_data() } as *mut HostState;
if state_pointer.is_null() {
return result::INVALID_ARGUMENT;
}
// SAFETY: borrowed buffers are valid for the duration of this callback.
let name_bytes = match unsafe { name.as_slice() } {
Ok(bytes) => bytes,
Err(_) => return result::INVALID_ARGUMENT,
};
let Ok(capability) = std::str::from_utf8(name_bytes) else {
return result::INVALID_ARGUMENT;
};
// SAFETY: borrowed buffers are valid for the duration of this callback.
let request = match unsafe { request_wire.as_slice() } {
Ok(bytes) => bytes.to_vec(),
Err(_) => return result::INVALID_ARGUMENT,
};
// SAFETY: state is owned by the live LoadedPlugin whose invocation is in
// progress; no other Rust reference is held across this callback.
let state = unsafe { &mut *state_pointer };
let Some(handler) = state.capability_handler.as_mut() else {
return result::CAPABILITY;
};
let reply = match handler(capability, &request) {
Ok(reply) => reply,
Err(_) => return result::CAPABILITY,
};
if reply.len() > MAX_CAPABILITY_REPLY_BYTES {
return result::BAD_WIRE;
}
if reply.is_empty() {
return result::OK;
}
// SAFETY: host_alloc is the allocator plugin code frees with host_free.
let pointer = unsafe { host_alloc(state_pointer as *mut c_void, reply.len()) };
if pointer.is_null() {
return result::OUT_OF_MEMORY;
}
// SAFETY: pointer has reply.len() bytes; reply is a distinct allocation.
unsafe {
std::ptr::copy_nonoverlapping(reply.as_ptr(), pointer as *mut u8, reply.len());
*reply_wire = MqOwnedBytes::new(pointer as *mut u8, reply.len());
}
result::OK
}
/// Copy a plugin output buffer into a `Vec`, enforce its size limit, and release
/// the buffer with the host allocator.
///
/// # Safety
///
/// `buffer` must be a plugin output buffer whose pointer (if non-NULL) was
/// allocated by the host allocator, and it must not have been freed yet.
unsafe fn take_host_buffer(
host_api: &MqHostApi,
buffer: &mut MqOwnedBytes,
limit: usize,
what: &str,
) -> Result<Vec<u8>, PluginError> {
// SAFETY: output pointer is host-owned and non-NULL.
let copy = unsafe { buffer.to_vec() }?;
let mut taken = MqOwnedBytes::EMPTY;
std::mem::swap(&mut taken, buffer);
if taken.len > limit {
// Free the oversized buffer before reporting the protocol violation.
// SAFETY: taken.data came from the host allocator.
unsafe { free_host_buffer(host_api, &taken) };
return Err(PluginError::wire(
"output_too_large",
format!(
"plugin {what} wire is {} bytes, limit is {limit}",
taken.len
),
));
}
// SAFETY: taken.data came from the host allocator.
unsafe { free_host_buffer(host_api, &taken) };
Ok(copy)
}
/// Release a host-allocated buffer.
///
/// # Safety
///
/// `buffer.data` must be NULL or a pointer previously returned by the host
/// allocator and not yet freed.
unsafe fn free_host_buffer(host_api: &MqHostApi, buffer: &MqOwnedBytes) {
if buffer.data.is_null() {
return;
}
// SAFETY: alloc/free pair and non-NULL pointer per the caller contract.
unsafe { (host_api.free)(host_api.host_data, buffer.data as *mut c_void) };
}
/// Validate a host API table (useful for tests and SDK conformance checks).
pub fn validate_host_table(host: &MqHostApi) -> Result<AbiVersion, PluginError> {
// SAFETY: we pass a valid reference converted to a pointer.
unsafe { check_host_api(host as *const MqHostApi) }
}
+704
View File
@@ -0,0 +1,704 @@
//! `plugin.yaml` manifest parsing and validation.
//!
//! A manifest is the declarative half of a plugin package: it names the
//! plugin, pins the ABI generation it targets, declares every export and
//! capability requirement, and lists content-addressed artifacts per target
//! triple. Installing a package never grants permissions; validation never
//! executes plugin code.
use std::path::{Component, Path, PathBuf};
use serde::{Deserialize, Serialize};
use crate::abi::{
AbiVersion, ABI_MAJOR, ABI_MINOR, MAX_EXPORT_NAME_BYTES, MAX_SIGNATURE_WIRE_BYTES,
};
use crate::artifact::{is_valid_sha256_hex, TargetTriple};
use crate::artifact::{verify_sha256_file, HostTarget};
use crate::error::PluginError;
/// Maximum number of exports a single plugin may register.
pub const MAX_EXPORTS: usize = 256;
/// Maximum number of declared capabilities.
pub const MAX_REQUIRES: usize = 64;
/// Maximum number of artifacts.
pub const MAX_ARTIFACTS: usize = 32;
/// Capability names the host knows about (blueprint section 10.5 whitelist).
pub const KNOWN_CAPABILITIES: &[&str] = &[
"log",
"math.compute",
"fs.read",
"fs.write",
"net.request",
"clock",
"random",
"artifact.record",
];
/// Function-name prefixes reserved by the language/host; plugins may not
/// shadow built-ins or other namespaces.
pub const RESERVED_EXPORT_PREFIXES: &[&str] = &["marqdo.", "builtin.", "core.", "std.", "host."];
/// Plugin deployment kind.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "lowercase")]
pub enum PluginKind {
/// Native dynamic library loaded in-process. Requires explicit trust.
Native,
/// Isolated plugin worker process (same logical plugin API).
Worker,
/// Wasm component (future direction; only recognized in v1).
Wasm,
}
impl PluginKind {
/// Stable manifest name.
pub const fn as_str(self) -> &'static str {
match self {
PluginKind::Native => "native",
PluginKind::Worker => "worker",
PluginKind::Wasm => "wasm",
}
}
}
/// One declared export.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct Export {
/// Dotted export name (e.g. `solver.add`).
pub name: String,
/// Marqdo-facing signature string (e.g. `($a: Int, $b: Int) -> Int`).
pub signature: String,
}
/// One target-specific artifact.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct Artifact {
/// Rust-style target triple (e.g. `x86_64-unknown-linux-gnu`).
pub target: String,
/// Relative path to the artifact inside the package.
pub file: String,
/// Lowercase hexadecimal sha256 of the artifact contents.
pub sha256: String,
}
impl Artifact {
/// Parse the artifact target triple.
pub fn target_triple(&self) -> Result<TargetTriple, PluginError> {
TargetTriple::parse(&self.target)
}
/// Resolve the artifact path below `base_dir`, rejecting absolute paths
/// and `..` traversal so a manifest can never point outside its package.
pub fn resolve_path(&self, base_dir: &Path) -> Result<PathBuf, PluginError> {
validate_artifact_file(&self.file)?;
Ok(base_dir.join(&self.file))
}
}
/// The `plugin:` block of `plugin.yaml`.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct PluginInfo {
/// Package name (dotted, e.g. `qdqc.solver`).
pub name: String,
/// Package version (semver-ish, e.g. `1.0.0`).
pub version: String,
/// Required plugin ABI range (e.g. `^1.0`).
pub abi: String,
/// Deployment kind.
pub kind: PluginKind,
/// Declared exports.
pub exports: Vec<Export>,
/// Declared capability requirements.
#[serde(default)]
pub requires: Vec<String>,
/// Declared artifacts.
pub artifacts: Vec<Artifact>,
}
/// Parsed `plugin.yaml`.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct PluginManifest {
/// The single `plugin:` block.
pub plugin: PluginInfo,
}
impl PluginManifest {
/// Parse a manifest from YAML text.
pub fn parse_str(yaml: &str) -> Result<Self, PluginError> {
serde_yaml::from_str(yaml).map_err(|error| {
PluginError::manifest("manifest_parse_failed", "plugin.yaml could not be parsed")
.with_detail(error.to_string())
})
}
/// Read and parse a manifest from disk.
pub fn load(path: &Path) -> Result<Self, PluginError> {
let text = std::fs::read_to_string(path).map_err(|error| {
PluginError::manifest(
"manifest_unreadable",
format!("manifest `{}` could not be read", path.display()),
)
.with_detail(error.to_string())
})?;
Self::parse_str(&text)
}
/// Validate every declared field and cross-field invariant.
///
/// This performs no filesystem access and executes no plugin code.
pub fn validate(&self) -> Result<(), PluginError> {
let plugin = &self.plugin;
validate_dotted_name(&plugin.name, MAX_EXPORT_NAME_BYTES, "plugin name")?;
if plugin.name.starts_with("marqdo.") || plugin.name.starts_with("builtin.") {
return Err(PluginError::manifest(
"reserved_name",
format!("plugin name `{}` uses a reserved namespace", plugin.name),
));
}
PackageVersion::parse(&plugin.version)?;
let requirement = AbiRequirement::parse(&plugin.abi)?;
if !requirement.is_compatible_with(AbiVersion::current()) {
return Err(PluginError::unsupported(
"abi_requirement_unsupported",
format!(
"plugin requires ABI `{}` but the host implements {ABI_MAJOR}.{ABI_MINOR}",
plugin.abi
),
));
}
if plugin.exports.is_empty() {
return Err(PluginError::manifest(
"no_exports",
"plugin must declare at least one export",
));
}
if plugin.exports.len() > MAX_EXPORTS {
return Err(PluginError::manifest(
"too_many_exports",
format!("plugin declares more than {MAX_EXPORTS} exports"),
));
}
let mut export_names = std::collections::BTreeSet::new();
for export in &plugin.exports {
validate_dotted_name(&export.name, MAX_EXPORT_NAME_BYTES, "export name")?;
if !export.name.contains('.') {
return Err(PluginError::manifest(
"invalid_export_name",
format!(
"export `{}` must be namespaced (e.g. `solver.add`)",
export.name
),
));
}
if let Some(prefix) = RESERVED_EXPORT_PREFIXES
.iter()
.find(|prefix| export.name.starts_with(**prefix))
{
return Err(PluginError::manifest(
"reserved_export_name",
format!("export `{}` uses reserved prefix `{prefix}`", export.name),
));
}
if !export_names.insert(export.name.clone()) {
return Err(PluginError::manifest(
"duplicate_export",
format!("export `{}` is declared more than once", export.name),
));
}
validate_signature(&export.name, &export.signature)?;
}
if plugin.requires.len() > MAX_REQUIRES {
return Err(PluginError::manifest(
"too_many_capabilities",
format!("plugin requires more than {MAX_REQUIRES} capabilities"),
));
}
let mut capabilities = std::collections::BTreeSet::new();
for capability in &plugin.requires {
if !KNOWN_CAPABILITIES.contains(&capability.as_str()) {
return Err(PluginError::manifest(
"unknown_capability",
format!("unknown capability `{capability}`"),
));
}
if !capabilities.insert(capability.clone()) {
return Err(PluginError::manifest(
"duplicate_capability",
format!("capability `{capability}` is declared more than once"),
));
}
}
if plugin.artifacts.is_empty() {
return Err(PluginError::manifest(
"no_artifacts",
"plugin must declare at least one artifact",
));
}
if plugin.artifacts.len() > MAX_ARTIFACTS {
return Err(PluginError::manifest(
"too_many_artifacts",
format!("plugin declares more than {MAX_ARTIFACTS} artifacts"),
));
}
let mut targets = std::collections::BTreeSet::new();
for artifact in &plugin.artifacts {
let triple = artifact.target_triple()?;
if !targets.insert(triple.clone()) {
return Err(PluginError::manifest(
"duplicate_artifact_target",
format!("target `{triple}` is declared more than once"),
));
}
validate_artifact_file(&artifact.file)?;
if !is_valid_sha256_hex(&artifact.sha256) {
return Err(PluginError::manifest(
"invalid_sha256",
format!(
"artifact `{}` sha256 must be 64 hexadecimal characters",
artifact.file
),
));
}
}
Ok(())
}
/// The parsed ABI requirement.
pub fn abi_requirement(&self) -> Result<AbiRequirement, PluginError> {
AbiRequirement::parse(&self.plugin.abi)
}
/// The parsed package version.
pub fn package_version(&self) -> Result<PackageVersion, PluginError> {
PackageVersion::parse(&self.plugin.version)
}
/// Resolve the artifact for `host`, requiring an exact target-triple match
/// with matching pointer width.
pub fn resolve_artifact<'a>(&'a self, host: &HostTarget) -> Result<&'a Artifact, PluginError> {
for artifact in &self.plugin.artifacts {
let triple = artifact.target_triple()?;
if triple == *host.triple() {
return Ok(artifact);
}
}
Err(PluginError::artifact(
"no_matching_artifact",
format!(
"plugin `{}` has no artifact for target `{}`",
self.plugin.name,
host.triple()
),
)
.with_detail(format!(
"declared targets: {}",
self.plugin
.artifacts
.iter()
.map(|artifact| artifact.target.as_str())
.collect::<Vec<_>>()
.join(", ")
)))
}
/// Resolve and verify the artifact for `host`, returning its path.
///
/// Verification proves the file matches the manifest sha256; it does not
/// grant trust or capability authorization.
pub fn verify_artifact(
&self,
base_dir: &Path,
host: &HostTarget,
) -> Result<(PathBuf, &Artifact), PluginError> {
let artifact = self.resolve_artifact(host)?;
let path = artifact.resolve_path(base_dir)?;
verify_sha256_file(&path, &artifact.sha256)?;
Ok((path, artifact))
}
}
/// Semver-ish package version (major.minor.patch with optional pre-release and
/// build metadata). Manifest validation is deliberately not a full SemVer
/// range resolver.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct PackageVersion {
/// Original string from the manifest.
pub raw: String,
/// Major component.
pub major: u64,
/// Minor component.
pub minor: u64,
/// Patch component.
pub patch: u64,
/// Optional pre-release suffix (without the leading `-`).
pub pre_release: Option<String>,
/// Optional build metadata (without the leading `+`).
pub build: Option<String>,
}
impl PackageVersion {
/// Parse a semver-ish version string.
pub fn parse(raw: &str) -> Result<Self, PluginError> {
let invalid = |detail: String| {
PluginError::manifest("invalid_version", format!("`{raw}` is not a valid version"))
.with_detail(detail)
};
let (without_build, build) = match raw.split_once('+') {
Some((left, right)) => {
validate_identifiers(right).map_err(&invalid)?;
(left, Some(right.to_string()))
}
None => (raw, None),
};
let (core, pre_release) = match without_build.split_once('-') {
Some((left, right)) => {
validate_identifiers(right).map_err(&invalid)?;
(left, Some(right.to_string()))
}
None => (without_build, None),
};
let numbers: Vec<&str> = core.split('.').collect();
if numbers.len() != 3 {
return Err(invalid("expected `major.minor.patch`".to_string()));
}
let mut parsed = [0u64; 3];
for (index, number) in numbers.iter().enumerate() {
if number.is_empty() || !number.bytes().all(|byte| byte.is_ascii_digit()) {
return Err(invalid(format!("component `{number}` is not numeric")));
}
if number.len() > 1 && number.starts_with('0') {
return Err(invalid(format!("component `{number}` has a leading zero")));
}
parsed[index] = number
.parse::<u64>()
.map_err(|_| invalid(format!("component `{number}` is too large")))?;
}
Ok(Self {
raw: raw.to_string(),
major: parsed[0],
minor: parsed[1],
patch: parsed[2],
pre_release,
build,
})
}
}
fn validate_identifiers(value: &str) -> Result<(), String> {
if value.is_empty() {
return Err("empty version suffix".to_string());
}
for segment in value.split('.') {
if segment.is_empty() {
return Err("empty version suffix segment".to_string());
}
if !segment
.bytes()
.all(|byte| byte.is_ascii_alphanumeric() || byte == b'-')
{
return Err(format!("invalid version suffix `{segment}`"));
}
}
Ok(())
}
/// A caret-style ABI requirement such as `^1.0`.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct AbiRequirement {
/// Required major.
pub major: u32,
/// Required minimum minor.
pub minor: u32,
/// Original string from the manifest.
pub raw: String,
}
impl AbiRequirement {
/// Parse `^1`, `^1.0`, `1`, or `1.0`.
pub fn parse(raw: &str) -> Result<Self, PluginError> {
let trimmed = raw.trim();
let numbers = trimmed.strip_prefix('^').unwrap_or(trimmed);
let mut parts = numbers.split('.');
let major = parts.next().unwrap_or_default();
let minor = parts.next().unwrap_or("0");
if parts.next().is_some() {
return Err(PluginError::manifest(
"invalid_abi_requirement",
format!("`{raw}` is not a supported ABI requirement"),
));
}
let parse_component = |component: &str| -> Result<u32, PluginError> {
if component.is_empty() || !component.bytes().all(|byte| byte.is_ascii_digit()) {
return Err(PluginError::manifest(
"invalid_abi_requirement",
format!("`{raw}` is not a supported ABI requirement"),
));
}
component.parse::<u32>().map_err(|_| {
PluginError::manifest(
"invalid_abi_requirement",
format!("`{raw}` contains an out-of-range ABI component"),
)
})
};
Ok(Self {
major: parse_component(major)?,
minor: parse_component(minor)?,
raw: raw.to_string(),
})
}
/// Caret compatibility: `^M.m` means `>=M.m` and `<M+1.0`
/// (with the SemVer `0.x` special case pinning the minor).
pub fn is_compatible_with(&self, host: AbiVersion) -> bool {
if self.major == 0 {
host.major == 0 && host.minor == self.minor
} else {
host.major == self.major && host.minor >= self.minor
}
}
}
fn validate_dotted_name(name: &str, max_len: usize, what: &str) -> Result<(), PluginError> {
if name.is_empty() {
return Err(PluginError::manifest(
"invalid_name",
format!("{what} must not be empty"),
));
}
if name.len() > max_len {
return Err(PluginError::manifest(
"invalid_name",
format!("{what} `{name}` is longer than {max_len} bytes"),
));
}
for segment in name.split('.') {
if segment.is_empty() {
return Err(PluginError::manifest(
"invalid_name",
format!("{what} `{name}` contains an empty segment"),
));
}
let mut bytes = segment.bytes();
let first = bytes.next().unwrap_or(b'a');
if !first.is_ascii_lowercase() {
return Err(PluginError::manifest(
"invalid_name",
format!("{what} `{name}` must start each segment with a lowercase letter"),
));
}
if !bytes.all(|byte| {
byte.is_ascii_lowercase() || byte.is_ascii_digit() || byte == b'-' || byte == b'_'
}) {
return Err(PluginError::manifest(
"invalid_name",
format!("{what} `{name}` may only contain lowercase letters, digits, `-` and `_`"),
));
}
}
Ok(())
}
fn validate_signature(export: &str, signature: &str) -> Result<(), PluginError> {
let trimmed = signature.trim();
if trimmed.is_empty() || trimmed.len() > MAX_SIGNATURE_WIRE_BYTES {
return Err(PluginError::manifest(
"invalid_signature",
format!("export `{export}` has an empty or oversized signature"),
));
}
if !trimmed.starts_with('(') || !trimmed.contains("->") {
return Err(PluginError::manifest(
"invalid_signature",
format!("export `{export}` signature must look like `(args) -> Return`"),
));
}
if trimmed.chars().any(char::is_control) {
return Err(PluginError::manifest(
"invalid_signature",
format!("export `{export}` signature contains control characters"),
));
}
Ok(())
}
fn validate_artifact_file(file: &str) -> Result<(), PluginError> {
if file.is_empty() || file.contains('\0') || file.len() > 256 {
return Err(PluginError::manifest(
"invalid_artifact_path",
"artifact file must be a non-empty relative path of at most 256 bytes",
));
}
let path = Path::new(file);
if path.is_absolute() {
return Err(PluginError::manifest(
"invalid_artifact_path",
format!("artifact file `{file}` must be relative"),
));
}
for component in path.components() {
match component {
Component::Normal(part) if !part.is_empty() => {}
Component::CurDir => {}
Component::ParentDir | Component::RootDir | Component::Prefix(_) => {
return Err(PluginError::manifest(
"invalid_artifact_path",
format!("artifact file `{file}` must not escape the package directory"),
));
}
Component::Normal(_) => {
return Err(PluginError::manifest(
"invalid_artifact_path",
format!("artifact file `{file}` contains an empty component"),
));
}
}
}
Ok(())
}
#[cfg(test)]
mod tests {
use super::*;
const VALID_YAML: &str = r#"
plugin:
name: demo.solver
version: 1.0.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"
"#;
fn valid_manifest() -> PluginManifest {
let manifest = PluginManifest::parse_str(VALID_YAML).expect("parse");
manifest.validate().expect("validate");
manifest
}
#[test]
fn valid_manifest_parses_and_validates() {
let manifest = valid_manifest();
assert_eq!(manifest.plugin.name, "demo.solver");
assert_eq!(manifest.plugin.kind, PluginKind::Native);
assert_eq!(manifest.abi_requirement().expect("abi").raw, "^1.0");
assert_eq!(manifest.package_version().expect("version").patch, 0);
}
#[test]
fn malformed_yaml_is_rejected() {
let error = PluginManifest::parse_str("plugin: [unclosed").expect_err("must fail");
assert_eq!(error.kind, crate::error::ErrorKind::Manifest);
assert_eq!(error.code, "manifest_parse_failed");
assert!(PluginManifest::parse_str("not_a_plugin: 1").is_err());
}
#[test]
fn invalid_fields_are_rejected() {
let cases = [
("name", "DemoSolver"),
("version", "1.0"),
("abi", "^2.0"),
("kind", "inprocess"),
("file", "../solver.so"),
("sha256", "xyz"),
];
for (field, value) in cases {
let yaml = match field {
"name" => VALID_YAML.replace("name: demo.solver", &format!("name: {value}")),
"version" => VALID_YAML.replace("version: 1.0.0", &format!("version: {value}")),
"abi" => VALID_YAML.replace("abi: \"^1.0\"", &format!("abi: \"{value}\"")),
"kind" => VALID_YAML.replace("kind: native", &format!("kind: {value}")),
"file" => VALID_YAML.replace("file: solver.so", &format!("file: {value}")),
"sha256" => VALID_YAML.replace(
"sha256: \"0000000000000000000000000000000000000000000000000000000000000000\"",
&format!("sha256: \"{value}\""),
),
_ => unreachable!(),
};
match PluginManifest::parse_str(&yaml) {
Ok(manifest) => assert!(
manifest.validate().is_err(),
"`{field}` = `{value}` should fail validation"
),
Err(error) => assert_eq!(
error.kind,
crate::error::ErrorKind::Manifest,
"`{field}` = `{value}` should fail manifest handling"
),
}
}
}
#[test]
fn duplicate_and_reserved_exports_are_rejected() {
let duplicate = VALID_YAML.replace(
" - name: solver.add\n signature: \"($a: Int, $b: Int) -> Int\"",
" - name: solver.add\n signature: \"($a: Int) -> Int\"\n - name: solver.add\n signature: \"($a: Int) -> Int\"",
);
let manifest = PluginManifest::parse_str(&duplicate).expect("parse");
assert_eq!(
manifest.validate().expect_err("duplicate").code,
"duplicate_export"
);
let reserved = VALID_YAML.replace("solver.add", "builtin.print");
let manifest = PluginManifest::parse_str(&reserved).expect("parse");
assert_eq!(
manifest.validate().expect_err("reserved").code,
"reserved_export_name"
);
}
#[test]
fn abi_requirement_caret_semantics() {
let v1 = AbiVersion::new(1, 0);
assert!(AbiRequirement::parse("^1.0")
.expect("parse")
.is_compatible_with(v1));
assert!(AbiRequirement::parse("^1")
.expect("parse")
.is_compatible_with(v1));
assert!(AbiRequirement::parse("1.0")
.expect("parse")
.is_compatible_with(v1));
assert!(!AbiRequirement::parse("^1.1")
.expect("parse")
.is_compatible_with(v1));
assert!(!AbiRequirement::parse("^2.0")
.expect("parse")
.is_compatible_with(v1));
assert!(!AbiRequirement::parse("^0.1")
.expect("parse")
.is_compatible_with(v1));
assert!(AbiRequirement::parse("nonsense").is_err());
}
#[test]
fn artifact_resolution_requires_exact_host_target() {
let manifest = valid_manifest();
let host = HostTarget::current();
if host.triple().as_str() == "x86_64-unknown-linux-gnu" {
let artifact = manifest.resolve_artifact(&host).expect("resolve");
assert_eq!(artifact.file, "solver.so");
} else {
assert_eq!(
manifest
.resolve_artifact(&host)
.expect_err("other target")
.code,
"no_matching_artifact"
);
}
}
}
+507
View File
@@ -0,0 +1,507 @@
//! `wire_version` 1 JSON request/response envelope used across the plugin ABI
//! and (logically identical) worker IPC.
//!
//! The envelope is intentionally small; the actual values inside `args` and
//! `value` use the canonical type-tagged representation from
//! [`marqdo_value::wire`] (`spec/value-wire.md`): integers are decimal
//! strings, special floats carry explicit tags, and every value is a JSON
//! object with a `type` field.
//!
//! ```json
//! {
//! "wire_version": 1,
//! "kind": "request",
//! "function": "solver.solve",
//! "args": {"a": {"type": "int", "decimal": "12345678901234567890"}},
//! "context": {"trace_id": "..."}
//! }
//! ```
use std::collections::BTreeMap;
use serde::{Deserialize, Serialize};
use serde_json::Value as Json;
use marqdo_value::wire::{from_wire_with_limits, to_wire, WireLimits};
use marqdo_value::Value;
use crate::abi::{MAX_ERROR_WIRE_BYTES, MAX_REQUEST_WIRE_BYTES, MAX_RESULT_WIRE_BYTES};
use crate::error::{ErrorKind, PluginError};
/// Wire protocol version (`wire_version` field).
pub const WIRE_VERSION: u32 = 1;
/// Envelope kind for requests.
pub const KIND_REQUEST: &str = "request";
/// Envelope kind for responses (success and error).
pub const KIND_RESPONSE: &str = "response";
/// Maximum number of request arguments.
pub const MAX_ARGS: usize = 1024;
/// Per-call context attached to a request. Contains no host secrets and no
/// reconstructable OS handles: only opaque, scoped identifiers.
#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
pub struct WireContext {
/// Opaque trace identifier for host logging.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub trace_id: Option<String>,
/// Opaque capability handle for this call; never a real OS handle.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub capability_handle: Option<String>,
}
/// A `kind: "request"` envelope.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct WireRequest {
/// Wire protocol version; must be [`WIRE_VERSION`].
pub wire_version: u32,
/// Envelope kind; must be [`KIND_REQUEST`].
pub kind: String,
/// Fully qualified exported function name (e.g. `solver.add`).
pub function: String,
/// Type-tagged argument values keyed by parameter name.
#[serde(default)]
pub args: BTreeMap<String, Json>,
/// Per-call context.
#[serde(default)]
pub context: WireContext,
}
impl WireRequest {
/// Start a request for `function`.
pub fn new(function: impl Into<String>) -> Self {
Self {
wire_version: WIRE_VERSION,
kind: KIND_REQUEST.to_string(),
function: function.into(),
args: BTreeMap::new(),
context: WireContext::default(),
}
}
/// Add a typed argument, encoding it with the canonical value wire tags.
#[must_use]
pub fn with_arg(mut self, name: impl Into<String>, value: &Value) -> Self {
self.args.insert(name.into(), to_wire(value));
self
}
/// Add an already-encoded type-tagged argument.
#[must_use]
pub fn with_raw_arg(mut self, name: impl Into<String>, value: Json) -> Self {
self.args.insert(name.into(), value);
self
}
/// Attach a trace identifier.
#[must_use]
pub fn with_trace_id(mut self, trace_id: impl Into<String>) -> Self {
self.context.trace_id = Some(trace_id.into());
self
}
/// Decode all arguments into typed [`Value`]s, enforcing wire limits.
pub fn typed_args(&self) -> Result<BTreeMap<String, Value>, PluginError> {
self.typed_args_with_limits(WireLimits::default())
}
/// Decode all arguments into typed [`Value`]s with explicit limits.
pub fn typed_args_with_limits(
&self,
limits: WireLimits,
) -> Result<BTreeMap<String, Value>, PluginError> {
let mut decoded = BTreeMap::new();
for (name, json) in &self.args {
let value = from_wire_with_limits(json, limits).map_err(|error| {
PluginError::wire(
"invalid_argument_wire",
format!("argument `{name}` is not a valid typed wire value"),
)
.with_detail(error.to_string())
})?;
decoded.insert(name.clone(), value);
}
Ok(decoded)
}
/// Encode the request as UTF-8 JSON bytes, enforcing the request size cap.
pub fn to_json_bytes(&self) -> Result<Vec<u8>, PluginError> {
let bytes = serde_json::to_vec(self).map_err(|error| {
PluginError::wire("request_encode_failed", "could not encode wire request")
.with_detail(error.to_string())
})?;
if bytes.len() > MAX_REQUEST_WIRE_BYTES {
return Err(PluginError::wire(
"request_too_large",
format!(
"request wire is {} bytes, limit is {MAX_REQUEST_WIRE_BYTES}",
bytes.len()
),
));
}
Ok(bytes)
}
/// Decode and validate a request envelope.
pub fn from_json_bytes(bytes: &[u8]) -> Result<Self, PluginError> {
if bytes.len() > MAX_REQUEST_WIRE_BYTES {
return Err(PluginError::wire(
"request_too_large",
format!(
"request wire is {} bytes, limit is {MAX_REQUEST_WIRE_BYTES}",
bytes.len()
),
));
}
let request: Self = serde_json::from_slice(bytes).map_err(|error| {
PluginError::wire("request_invalid", "wire request is not valid JSON")
.with_detail(error.to_string())
})?;
request.validate()?;
Ok(request)
}
/// Validate envelope invariants without touching the argument values.
pub fn validate(&self) -> Result<(), PluginError> {
if self.wire_version != WIRE_VERSION {
return Err(PluginError::wire(
"unsupported_wire_version",
format!(
"wire_version {} is not supported (host supports {WIRE_VERSION})",
self.wire_version
),
));
}
if self.kind != KIND_REQUEST {
return Err(PluginError::wire(
"unexpected_envelope_kind",
format!("expected kind `{KIND_REQUEST}`, got `{}`", self.kind),
));
}
if self.function.trim().is_empty() {
return Err(PluginError::wire(
"missing_function",
"wire request has an empty function name",
));
}
if self.args.len() > MAX_ARGS {
return Err(PluginError::wire(
"too_many_arguments",
format!("wire request has more than {MAX_ARGS} arguments"),
));
}
Ok(())
}
}
/// Structured error body inside an error response.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct WireErrorBody {
/// Error category (for example `invoke`, `capability`).
pub kind: String,
/// Stable machine-readable error code.
pub code: String,
/// Human-readable message (never contains secrets).
pub message: String,
/// Whether the caller may retry.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub recoverable: Option<bool>,
/// Optional non-sensitive detail.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub detail: Option<String>,
}
impl WireErrorBody {
/// Build a wire error body from a structured plugin error.
pub fn from_plugin_error(error: &PluginError) -> Self {
Self {
kind: error.kind.as_str().to_string(),
code: error.code.clone(),
message: error.message.clone(),
recoverable: error.recoverable.then_some(true),
detail: error.detail.clone(),
}
}
/// Convert back into a structured plugin error.
pub fn to_plugin_error(&self) -> PluginError {
PluginError {
kind: ErrorKind::from_wire_name(&self.kind).unwrap_or(ErrorKind::Invoke),
code: self.code.clone(),
message: self.message.clone(),
detail: self.detail.clone(),
recoverable: self.recoverable.unwrap_or(false),
}
}
}
/// A `kind: "response"` envelope: either `value` or `error`.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct WireResponse {
/// Wire protocol version; must be [`WIRE_VERSION`].
pub wire_version: u32,
/// Envelope kind; must be [`KIND_RESPONSE`].
pub kind: String,
/// Type-tagged result value, absent for unit results and errors.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub value: Option<Json>,
/// Structured error, absent for successful responses.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub error: Option<WireErrorBody>,
}
impl WireResponse {
/// Successful response carrying an optional typed value.
pub fn success(value: Option<Value>) -> Self {
Self {
wire_version: WIRE_VERSION,
kind: KIND_RESPONSE.to_string(),
value: value.as_ref().map(to_wire),
error: None,
}
}
/// Successful response carrying an already-encoded type-tagged value.
pub fn success_raw(value: Option<Json>) -> Self {
Self {
wire_version: WIRE_VERSION,
kind: KIND_RESPONSE.to_string(),
value,
error: None,
}
}
/// Error response.
pub fn from_error(error: &PluginError) -> Self {
Self {
wire_version: WIRE_VERSION,
kind: KIND_RESPONSE.to_string(),
value: None,
error: Some(WireErrorBody::from_plugin_error(error)),
}
}
/// Whether this response is an error.
pub fn is_error(&self) -> bool {
self.error.is_some()
}
/// Encode as UTF-8 JSON bytes, enforcing the result size cap.
pub fn to_json_bytes(&self) -> Result<Vec<u8>, PluginError> {
let bytes = serde_json::to_vec(self).map_err(|error| {
PluginError::wire("response_encode_failed", "could not encode wire response")
.with_detail(error.to_string())
})?;
if bytes.len() > MAX_RESULT_WIRE_BYTES {
return Err(PluginError::wire(
"response_too_large",
format!(
"response wire is {} bytes, limit is {MAX_RESULT_WIRE_BYTES}",
bytes.len()
),
));
}
Ok(bytes)
}
/// Decode and validate a response envelope.
pub fn from_json_bytes(bytes: &[u8]) -> Result<Self, PluginError> {
Self::decode(bytes, MAX_RESULT_WIRE_BYTES, "response")
}
/// Decode and validate an error envelope using the tighter error cap.
pub fn from_error_json_bytes(bytes: &[u8]) -> Result<Self, PluginError> {
Self::decode(bytes, MAX_ERROR_WIRE_BYTES, "error")
}
fn decode(bytes: &[u8], limit: usize, what: &str) -> Result<Self, PluginError> {
if bytes.len() > limit {
return Err(PluginError::wire(
"response_too_large",
format!("{what} wire is {} bytes, limit is {limit}", bytes.len()),
));
}
let response: Self = serde_json::from_slice(bytes).map_err(|error| {
PluginError::wire("response_invalid", format!("wire {what} is not valid JSON"))
.with_detail(error.to_string())
})?;
if response.wire_version != WIRE_VERSION {
return Err(PluginError::wire(
"unsupported_wire_version",
format!(
"wire_version {} is not supported (host supports {WIRE_VERSION})",
response.wire_version
),
));
}
if response.kind != KIND_RESPONSE {
return Err(PluginError::wire(
"unexpected_envelope_kind",
format!("expected kind `{KIND_RESPONSE}`, got `{}`", response.kind),
));
}
match (&response.value, &response.error) {
(Some(_), Some(_)) => Err(PluginError::wire(
"ambiguous_response",
"wire response must not contain both `value` and `error`",
)),
// A response with neither field is a successful no-value (unit)
// result; callers see `typed_value() == None`.
_ => Ok(response),
}
}
/// Convert an error response into a structured error.
pub fn into_result(self) -> Result<Self, PluginError> {
match self.error {
Some(error) => Err(error.to_plugin_error()),
None => Ok(self),
}
}
/// The successful value decoded into a typed [`Value`].
pub fn typed_value(&self) -> Result<Option<Value>, PluginError> {
match &self.value {
Some(json) => from_wire_with_limits(json, WireLimits::default())
.map(Some)
.map_err(|error| {
PluginError::wire(
"invalid_result_wire",
"response value is not a valid typed wire value",
)
.with_detail(error.to_string())
}),
None => Ok(None),
}
}
}
/// Encode a typed [`Value`] into its canonical type-tagged JSON form.
pub fn to_wire_json(value: &Value) -> Json {
to_wire(value)
}
/// Decode an `i64` from a typed wire value (returns `None` for any other type
/// or for integers outside the `i64` range).
pub fn int_from_value(value: &Value) -> Option<i64> {
match value {
Value::Int(integer) => integer.to_string().parse::<i64>().ok(),
_ => None,
}
}
/// Borrow the text from a typed wire value.
pub fn text_from_value(value: &Value) -> Option<&str> {
match value {
Value::Text(text) => Some(text),
_ => None,
}
}
/// Borrow the boolean from a typed wire value.
pub fn bool_from_value(value: &Value) -> Option<bool> {
match value {
Value::Bool(value) => Some(*value),
_ => None,
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn request_roundtrip_preserves_type_tags() {
let request = WireRequest::new("solver.add")
.with_arg("a", &Value::Int(i64::MAX.into()))
.with_arg("b", &Value::Int(2_i64.into()))
.with_trace_id("trace-1");
let bytes = request.to_json_bytes().expect("encode");
let text = String::from_utf8(bytes.clone()).expect("utf8");
assert!(text.contains("\"type\":\"int\""));
assert!(text.contains(&format!("\"decimal\":\"{}\"", i64::MAX)));
let decoded = WireRequest::from_json_bytes(&bytes).expect("decode");
assert_eq!(decoded, request);
let args = decoded.typed_args().expect("typed args");
assert_eq!(int_from_value(&args["a"]), Some(i64::MAX));
// Integers beyond i64 stay exact on the wire but are not coercible.
let big = WireRequest::new("solver.add").with_raw_arg(
"big",
serde_json::json!({"type": "int", "decimal": "123456789012345678901234567890"}),
);
let values = big.typed_args().expect("typed big");
assert_eq!(int_from_value(&values["big"]), None);
}
#[test]
fn request_rejects_wrong_version_or_kind() {
let mut request = WireRequest::new("solver.add");
request.wire_version = 2;
assert_eq!(
WireRequest::from_json_bytes(&serde_json::to_vec(&request).expect("json"))
.expect_err("version")
.code,
"unsupported_wire_version"
);
let mut request = WireRequest::new("solver.add");
request.kind = "response".to_string();
assert_eq!(
WireRequest::from_json_bytes(&serde_json::to_vec(&request).expect("json"))
.expect_err("kind")
.code,
"unexpected_envelope_kind"
);
}
#[test]
fn response_success_and_error_roundtrip() {
let success = WireResponse::success(Some(Value::Int(42_i64.into())));
let decoded = WireResponse::from_json_bytes(&success.to_json_bytes().expect("encode"))
.expect("decode");
assert_eq!(
decoded.typed_value().expect("typed"),
Some(Value::Int(42_i64.into()))
);
let error = PluginError::invoke("bad_arguments", "argument `a` is missing");
let response = WireResponse::from_error(&error);
let bytes = response.to_json_bytes().expect("encode");
assert!(String::from_utf8_lossy(&bytes).contains("\"error\""));
let decoded = WireResponse::from_error_json_bytes(&bytes).expect("decode");
assert_eq!(decoded.into_result().expect_err("error"), error);
}
#[test]
fn response_rejects_ambiguous_payloads_and_accepts_unit() {
let ambiguous = serde_json::json!({
"wire_version": 1,
"kind": "response",
"value": {"type": "int", "decimal": "1"},
"error": {"kind": "invoke", "code": "x", "message": "y"}
});
assert_eq!(
WireResponse::from_json_bytes(&serde_json::to_vec(&ambiguous).expect("json"))
.expect_err("ambiguous")
.code,
"ambiguous_response"
);
// A response without `value` or `error` is a successful unit result.
let unit = serde_json::json!({"wire_version": 1, "kind": "response"});
let decoded = WireResponse::from_json_bytes(&serde_json::to_vec(&unit).expect("json"))
.expect("unit response");
assert!(!decoded.is_error());
assert_eq!(decoded.typed_value().expect("typed"), None);
assert!(decoded.into_result().is_ok());
}
#[test]
fn oversized_wire_is_rejected_before_json_parsing() {
let oversized = vec![b' '; MAX_REQUEST_WIRE_BYTES + 1];
assert_eq!(
WireRequest::from_json_bytes(&oversized)
.expect_err("oversized")
.code,
"request_too_large"
);
}
}
@@ -0,0 +1,293 @@
//! ABI v1 conformance tests: compile the C example plugin, load it through
//! `libloading`, round-trip a wire request, and exercise the negative paths
//! required by blueprint section 10.7.
//!
//! These tests are `unix`-only, use `cc` to build the example, and skip with a
//! message when `cc` is unavailable.
#![cfg(unix)]
use std::path::{Path, PathBuf};
use std::process::Command;
use std::sync::atomic::{AtomicU32, Ordering};
use marqdo_plugin_abi::{
sha256_file, ErrorKind, HostTarget, LoadedPlugin, PluginManifest, Value, WireRequest,
};
static TEMP_COUNTER: AtomicU32 = AtomicU32::new(0);
/// Minimal dependency-free temporary directory.
struct TempDir {
path: PathBuf,
}
impl TempDir {
fn new(tag: &str) -> Self {
let unique = TEMP_COUNTER.fetch_add(1, Ordering::Relaxed);
let mut path = std::env::temp_dir();
path.push(format!(
"marqdo-plugin-abi-test-{}-{unique}-{tag}",
std::process::id()
));
std::fs::create_dir_all(&path).expect("create temp dir");
Self { path }
}
fn path(&self) -> &Path {
&self.path
}
}
impl Drop for TempDir {
fn drop(&mut self) {
let _ = std::fs::remove_dir_all(&self.path);
}
}
fn repo_root() -> PathBuf {
Path::new(env!("CARGO_MANIFEST_DIR"))
.parent()
.expect("crates dir")
.parent()
.expect("repo root")
.to_path_buf()
}
fn have_cc() -> bool {
Command::new("cc")
.arg("--version")
.output()
.map(|output| output.status.success())
.unwrap_or(false)
}
fn skip_without_cc(test_name: &str) -> bool {
if have_cc() {
return false;
}
eprintln!("skipping `{test_name}`: `cc` is not available in PATH");
true
}
fn compile_c(dir: &Path, source: &Path, output_name: &str, extra_flags: &[&str]) -> PathBuf {
let output = dir.join(output_name);
let mut command = Command::new("cc");
command
.arg("-std=c11")
.arg("-O2")
.arg("-shared")
.arg("-fPIC")
.arg("-I")
.arg(repo_root().join("include"))
.args(extra_flags)
.arg(source)
.arg("-o")
.arg(&output);
let result = command.output().expect("spawn cc");
assert!(
result.status.success(),
"cc failed for {}: {}",
source.display(),
String::from_utf8_lossy(&result.stderr)
);
output
}
fn compile_example(dir: &Path, extra_flags: &[&str]) -> PathBuf {
compile_c(
dir,
&repo_root().join("examples/plugin-demo/solver.c"),
"solver.so",
extra_flags,
)
}
fn manifest_yaml(target: &str, sha256: &str) -> String {
format!(
r#"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: {target}
file: solver.so
sha256: "{sha256}"
"#
)
}
fn write_manifest(dir: &Path, target: &str, sha256: &str) -> PathBuf {
let path = dir.join("plugin.yaml");
std::fs::write(&path, manifest_yaml(target, sha256)).expect("write manifest");
path
}
fn host_triple() -> String {
HostTarget::current().triple().to_string()
}
fn open_plugin(dir: &Path) -> Result<LoadedPlugin, marqdo_plugin_abi::PluginError> {
let manifest = PluginManifest::load(&dir.join("plugin.yaml"))?;
LoadedPlugin::open(&manifest, dir)
}
#[test]
fn c_plugin_roundtrips_wire_request() {
if skip_without_cc("c_plugin_roundtrips_wire_request") {
return;
}
let dir = TempDir::new("roundtrip");
let artifact = compile_example(dir.path(), &[]);
let sha256 = sha256_file(&artifact).expect("hash");
write_manifest(dir.path(), &host_triple(), &sha256);
let mut plugin = open_plugin(dir.path()).expect("load plugin");
assert_eq!(plugin.abi_version().major, 1);
assert_eq!(plugin.abi_version().minor, 0);
assert_eq!(plugin.metadata().name, "demo.solver");
assert_eq!(plugin.metadata().version, "0.1.0");
let exports: Vec<&str> = plugin.exports().map(|export| export.name()).collect();
assert_eq!(exports, vec!["solver.add"]);
let request = WireRequest::new("solver.add")
.with_arg("a", &Value::Int(20_i64.into()))
.with_arg("b", &Value::Int(22_i64.into()))
.with_trace_id("conformance-test");
let response = plugin.invoke(&request).expect("invoke");
let request_json = String::from_utf8(request.to_json_bytes().expect("encode")).expect("utf8");
assert!(request_json.contains("\"wire_version\":1"));
assert!(request_json.contains("\"type\":\"int\""));
assert_eq!(
response.typed_value().expect("typed value"),
Some(Value::Int(42_i64.into()))
);
// Plugin-side handler errors arrive as structured errors.
let bad_request = WireRequest::new("solver.add").with_arg("a", &Value::Int(1_i64.into()));
let error = plugin.invoke(&bad_request).expect_err("missing b");
assert_eq!(error.kind, ErrorKind::Invoke);
assert_eq!(error.code, "bad_arguments");
// Unknown exports are rejected by the host bridge before calling the plugin.
let unknown = WireRequest::new("solver.nope");
assert_eq!(
plugin.invoke(&unknown).expect_err("unknown export").code,
"unknown_export"
);
}
#[test]
fn wrong_abi_major_fails_load() {
if skip_without_cc("wrong_abi_major_fails_load") {
return;
}
let dir = TempDir::new("bad-abi");
let artifact = compile_example(dir.path(), &["-DMQ_SOLVER_REPORT_ABI_MAJOR=2"]);
let sha256 = sha256_file(&artifact).expect("hash");
write_manifest(dir.path(), &host_triple(), &sha256);
let error = open_plugin(dir.path()).expect_err("ABI 2 must not load");
assert_eq!(error.kind, ErrorKind::Abi);
assert_eq!(error.code, "abi_major_mismatch");
}
#[test]
fn missing_entry_symbol_fails_load() {
if skip_without_cc("missing_entry_symbol_fails_load") {
return;
}
let dir = TempDir::new("no-entry");
let source = dir.path().join("not_a_plugin.c");
std::fs::write(
&source,
"/* intentionally exports a different symbol */\n\
#include <stdint.h>\n\
int32_t mq_plugin_entry_v0(void) { return 0; }\n",
)
.expect("write source");
let artifact = compile_c(dir.path(), &source, "solver.so", &[]);
let sha256 = sha256_file(&artifact).expect("hash");
write_manifest(dir.path(), &host_triple(), &sha256);
let error = open_plugin(dir.path()).expect_err("missing symbol must fail");
assert_eq!(error.kind, ErrorKind::Load);
assert_eq!(error.code, "missing_entry_symbol");
}
#[test]
fn missing_artifact_file_fails_resolution() {
let dir = TempDir::new("missing-artifact");
// Declared artifact is never created.
write_manifest(dir.path(), &host_triple(), &"0".repeat(64));
let error = open_plugin(dir.path()).expect_err("missing artifact must fail");
assert_eq!(error.kind, ErrorKind::Artifact);
assert_eq!(error.code, "missing_artifact");
}
#[test]
fn sha256_mismatch_fails_verification() {
if skip_without_cc("sha256_mismatch_fails_verification") {
return;
}
let dir = TempDir::new("hash-mismatch");
compile_example(dir.path(), &[]);
write_manifest(dir.path(), &host_triple(), &"0".repeat(64));
let error = open_plugin(dir.path()).expect_err("hash mismatch must fail");
assert_eq!(error.kind, ErrorKind::Artifact);
assert_eq!(error.code, "hash_mismatch");
}
#[test]
fn malformed_manifest_is_rejected() {
let dir = TempDir::new("bad-manifest");
std::fs::write(dir.path().join("plugin.yaml"), "plugin: [unclosed").expect("write");
let error = PluginManifest::load(&dir.path().join("plugin.yaml")).expect_err("parse");
assert_eq!(error.kind, ErrorKind::Manifest);
assert_eq!(error.code, "manifest_parse_failed");
// Structurally valid YAML but semantically invalid manifest.
let invalid = manifest_yaml(&host_triple(), &"0".repeat(64))
.replace("version: 0.1.0", "version: 01.0.0")
.replace("name: solver.add", "name: not-namespaced");
let manifest = PluginManifest::parse_str(&invalid).expect("parse");
let error = manifest.validate().expect_err("invalid manifest");
assert_eq!(error.kind, ErrorKind::Manifest);
}
#[test]
fn artifact_target_must_match_host() {
let dir = TempDir::new("target-mismatch");
write_manifest(
dir.path(),
"definitely-not-the-host-target-triple",
&"0".repeat(64),
);
let error = open_plugin(dir.path()).expect_err("target mismatch must fail");
assert_eq!(error.kind, ErrorKind::Artifact);
// Either the target triple is rejected as invalid or it does not match.
assert!(
error.code == "invalid_target_triple" || error.code == "no_matching_artifact",
"unexpected code {}",
error.code
);
}
#[test]
fn example_manifest_parses_and_validates() {
let manifest = PluginManifest::load(&repo_root().join("examples/plugin-demo/plugin.yaml"))
.expect("demo manifest parses");
manifest.validate().expect("demo manifest validates");
assert_eq!(manifest.plugin.name, "demo.solver");
assert_eq!(manifest.package_version().expect("version").raw, "0.1.0");
assert_eq!(manifest.abi_requirement().expect("abi").raw, "^1.0");
}
+156
View File
@@ -0,0 +1,156 @@
//! Safe wrappers around the raw `MqBytes` / `MqOwnedBytes` ABI buffers.
//!
//! Ownership rules (see the canonical header):
//! - [`BytesRef`] is a borrowed, validated view of host input; it is only
//! valid for the call that produced it.
//! - [`HostBuffer`] is plugin output allocated with the host allocator and
//! handed back to the host, which frees it after copying.
use std::ffi::c_void;
use std::marker::PhantomData;
use std::ptr;
use marqdo_plugin_abi::abi::{MqBytes, MqHostApi, MqOwnedBytes};
use crate::PluginError;
/// Validated borrowed view of an ABI byte buffer (`MqBytes`).
pub struct BytesRef<'a> {
raw: MqBytes,
_marker: PhantomData<&'a [u8]>,
}
impl<'a> BytesRef<'a> {
/// Validate a raw borrowed buffer.
///
/// # Safety
///
/// If `raw.len > 0`, `raw.data` must point to `raw.len` initialized bytes
/// that stay alive for `'a`. Within the ABI, `'a` must not outlive the
/// call that produced the buffer.
pub unsafe fn from_raw(raw: MqBytes) -> Result<Self, PluginError> {
raw.validate()?;
Ok(Self {
raw,
_marker: PhantomData,
})
}
/// The underlying raw ABI view.
pub fn as_raw(&self) -> MqBytes {
self.raw
}
/// The bytes as a slice (valid for `'a`).
pub fn as_slice(&self) -> &'a [u8] {
if self.raw.len == 0 {
return &[];
}
// SAFETY: `from_raw` validated the pointer/length pair and `'a` is
// tied to the caller's borrow guarantee.
unsafe { std::slice::from_raw_parts(self.raw.data, self.raw.len) }
}
/// Length in bytes.
pub fn len(&self) -> usize {
self.raw.len
}
/// Whether the buffer is empty.
pub fn is_empty(&self) -> bool {
self.raw.len == 0
}
}
/// A byte buffer allocated with the host allocator and owned by the host.
///
/// The plugin writes its response/error wire into a [`HostBuffer`] and
/// transfers ownership through the ABI output parameter. The plugin must
/// never free this buffer itself; the host frees it after copying.
pub struct HostBuffer {
raw: MqOwnedBytes,
}
impl HostBuffer {
/// The empty buffer `{NULL, 0}`.
pub fn empty() -> Self {
Self {
raw: MqOwnedBytes::EMPTY,
}
}
/// Allocate a host buffer and copy `bytes` into it.
///
/// `host` must be the host API table provided to the entry point (the SDK
/// stores it for the plugin lifetime). Returns an out-of-memory error if
/// the host allocator returns NULL.
pub fn copy_from(host: &MqHostApi, bytes: &[u8]) -> Result<Self, PluginError> {
if bytes.is_empty() {
return Ok(Self::empty());
}
// SAFETY: host alloc/free pointers are non-NULL and valid for the
// plugin lifetime (validated during the entry call).
let pointer = unsafe { (host.alloc)(host.host_data, bytes.len()) };
if pointer.is_null() {
return Err(PluginError::invoke(
"out_of_memory",
"host allocator returned NULL for a plugin output buffer",
));
}
// SAFETY: pointer has bytes.len() writable bytes and does not overlap
// the source slice.
unsafe {
ptr::copy_nonoverlapping(bytes.as_ptr(), pointer as *mut u8, bytes.len());
}
Ok(Self {
raw: MqOwnedBytes::new(pointer as *mut u8, bytes.len()),
})
}
/// The raw owner-transfer buffer.
pub fn into_raw(self) -> MqOwnedBytes {
self.raw
}
/// Length in bytes.
pub fn len(&self) -> usize {
self.raw.len
}
/// Whether the buffer is empty.
pub fn is_empty(&self) -> bool {
self.raw.len == 0
}
}
/// Borrowed view of a capability reply or other host-allocated buffer.
///
/// The plugin copies what it needs and then must release the buffer with the
/// host allocator; use [`release_host_buffer`].
///
/// # Safety
///
/// `buffer` must be a host-allocated buffer that is still alive; the returned
/// slice must not outlive the release of that buffer.
pub unsafe fn reply_slice<'a>(buffer: MqOwnedBytes) -> &'a [u8] {
if buffer.len == 0 {
return &[];
}
// SAFETY: host-allocated buffer is initialized for `buffer.len` bytes; the
// caller must not retain the slice beyond the release point.
unsafe { std::slice::from_raw_parts(buffer.data, buffer.len) }
}
/// Release a host-allocated buffer through the host allocator.
///
/// # Safety
///
/// `buffer.data` must be NULL or a pointer returned by the host allocator
/// (`MqHostApi::alloc`) that has not been freed yet.
pub unsafe fn release_host_buffer(host: &MqHostApi, buffer: MqOwnedBytes) {
if buffer.data.is_null() {
return;
}
// SAFETY: alloc/free pair and non-NULL pointer per the caller contract.
unsafe { (host.free)(host.host_data, buffer.data as *mut c_void) };
}
+115
View File
@@ -0,0 +1,115 @@
//! Per-invocation context passed to plugin handlers.
//!
//! The context is valid only for the duration of one invocation. It exists to
//! carry host capabilities into the plugin: capability requests are answered
//! by the host's authorization layer and can never be escalated by plugin
//! code. Do not cache this value, its raw pointer or any capability token.
use marqdo_plugin_abi::abi::{
MqBytes, MqCallContext, MqHostApi, MqOwnedBytes, MAX_CAPABILITY_REPLY_BYTES,
};
use marqdo_plugin_abi::PluginError;
use crate::bytes;
/// Context for one plugin invocation.
pub struct CallContext {
raw: *mut MqCallContext,
host: &'static MqHostApi,
}
impl CallContext {
/// Wrap the host-provided context pointer.
///
/// # Safety
///
/// `raw` must be the context pointer provided by the host for the current
/// invocation, and `host` must be the validated host API table.
pub(crate) unsafe fn new(raw: *mut MqCallContext, host: &'static MqHostApi) -> Self {
Self { raw, host }
}
/// The host API table of this plugin instance.
pub fn host(&self) -> &'static MqHostApi {
self.host
}
/// Request an already-authorized host capability for this call.
///
/// `request` is a UTF-8 JSON capability request; the reply is opaque bytes
/// owned by the host. The SDK copies the reply and releases the host buffer.
pub fn capability_request(
&mut self,
name: &str,
request: &[u8],
) -> Result<Vec<u8>, PluginError> {
if self.raw.is_null() {
return Err(PluginError::capability(
"missing_call_context",
"capability request requires an active invocation context",
));
}
let mut reply = MqOwnedBytes::EMPTY;
// SAFETY: raw context and host table are valid for this invocation.
let code = unsafe {
(self.host.request_capability)(
self.raw,
MqBytes::from_slice(name.as_bytes()),
MqBytes::from_slice(request),
&mut reply,
)
};
// SAFETY: host-allocated reply is initialized for `reply.len` bytes.
let reply_bytes = unsafe { reply.to_vec() };
// SAFETY: the host allocated `reply` with its allocator for us; release
// it exactly once after copying.
unsafe { bytes::release_host_buffer(self.host, reply) };
let reply_bytes = reply_bytes.map_err(|error| {
PluginError::capability(
"invalid_capability_reply",
"host capability reply violates the buffer contract",
)
.with_detail(error.to_string())
})?;
if reply_bytes.len() > MAX_CAPABILITY_REPLY_BYTES {
return Err(PluginError::capability(
"capability_reply_too_large",
format!(
"capability reply is {} bytes, limit is {MAX_CAPABILITY_REPLY_BYTES}",
reply_bytes.len()
),
));
}
if code != crate::result_code::OK {
return Err(PluginError::capability(
"capability_request_failed",
format!("host rejected capability request `{name}`"),
)
.with_detail(format!(
"result code `{}` ({code})",
crate::result_code::name(code)
)));
}
Ok(reply_bytes)
}
/// Best-effort structured log through the `log` capability.
pub fn log(&mut self, level: &str, message: &str) -> Result<(), PluginError> {
let request = serde_json::json!({"level": level, "message": message});
let request = serde_json::to_vec(&request).map_err(|error| {
PluginError::capability("log_encode_failed", "could not encode log request")
.with_detail(error.to_string())
})?;
let _ = self.capability_request("log", &request)?;
Ok(())
}
}
impl std::fmt::Debug for CallContext {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
f.debug_struct("CallContext")
.field("raw", &self.raw)
.field("host", &(self.host as *const MqHostApi))
.finish()
}
}
+199
View File
@@ -0,0 +1,199 @@
//! Entry-point plumbing used by [`mq_plugin_entry!`](crate::mq_plugin_entry).
//!
//! These functions are the "runtime" of the SDK macro. They are public so the
//! macro can reference them through `$crate` from a plugin crate, but they are
//! not intended for direct use.
use std::panic::{catch_unwind, AssertUnwindSafe};
use std::sync::atomic::{AtomicPtr, Ordering};
use marqdo_plugin_abi::abi::{
check_host_api, result, MqBytes, MqCallContext, MqHostApi, MqOwnedBytes, MqPluginApi,
MqPluginInvoke, ABI_MAJOR, ABI_MINOR, MAX_ERROR_WIRE_BYTES, MAX_EXPORT_NAME_BYTES,
MAX_RESULT_WIRE_BYTES,
};
use marqdo_plugin_abi::{PluginError, WireResponse};
use crate::bytes::{release_host_buffer, HostBuffer};
use crate::call::CallContext;
use crate::HandlerFn;
/// Host API table captured by the entry point for the plugin lifetime.
static CURRENT_HOST: AtomicPtr<MqHostApi> = AtomicPtr::new(std::ptr::null_mut());
/// The host API table captured at load time, if a plugin is loaded.
pub(crate) fn current_host() -> Option<&'static MqHostApi> {
let pointer = CURRENT_HOST.load(Ordering::SeqCst);
if pointer.is_null() {
return None;
}
// SAFETY: the pointer was stored from a validated host table and the host
// guarantees it is valid for the plugin lifetime (single-threaded model).
Some(unsafe { &*pointer })
}
/// Initialize the ABI tables for the generated entry point.
///
/// # Safety
///
/// `host` and `plugin` must be the pointers provided by the host to
/// `mq_plugin_entry_v1` and must satisfy the header contract.
pub unsafe fn initialize(
host: *const MqHostApi,
plugin: *mut MqPluginApi,
metadata: &'static [u8],
) -> i32 {
if plugin.is_null() {
return result::INVALID_ARGUMENT;
}
// SAFETY: host pointer comes from the host and is checked before use.
let negotiated = match unsafe { check_host_api(host) } {
Ok(version) => version,
Err(_) => return result::ABI_MISMATCH,
};
if negotiated.major != ABI_MAJOR {
return result::ABI_MISMATCH;
}
CURRENT_HOST.store(host as *mut MqHostApi, Ordering::SeqCst);
// SAFETY: plugin table is host-provided, writable and valid for this call.
unsafe {
(*plugin).struct_size = std::mem::size_of::<MqPluginApi>() as u32;
(*plugin).abi_major = ABI_MAJOR;
(*plugin).abi_minor = ABI_MINOR;
(*plugin).plugin_metadata_wire = MqBytes::from_slice(metadata);
}
result::OK
}
/// Register one export through the host table.
///
/// # Safety
///
/// `host` must be the table validated by [`initialize`]; both strings must be
/// valid UTF-8 dotted export names/signatures declared in `plugin.yaml`.
pub unsafe fn register_export(
host: *const MqHostApi,
name: &str,
signature: &str,
invoke: MqPluginInvoke,
) -> i32 {
if host.is_null() || name.is_empty() || name.len() > MAX_EXPORT_NAME_BYTES {
return result::INVALID_ARGUMENT;
}
// SAFETY: host pointer is non-NULL and valid for the plugin lifetime.
let host = unsafe { &*host };
let signature_wire = match serde_json::to_vec(&serde_json::json!({"signature": signature})) {
Ok(bytes) => bytes,
Err(_) => return result::BAD_WIRE,
};
// SAFETY: host table was validated; strings outlive the call.
unsafe {
(host.register_function)(
host.host_data,
MqBytes::from_slice(name.as_bytes()),
MqBytes::from_slice(&signature_wire),
invoke,
)
}
}
/// Dispatch one invocation to a plugin handler and write the response.
///
/// # Safety
///
/// Must be called as the body of a `MqPluginInvoke` callback with the buffers
/// provided by the host for that invocation.
pub unsafe fn dispatch(
handler: HandlerFn,
ctx: *mut MqCallContext,
args: MqBytes,
result_out: *mut MqOwnedBytes,
error_out: *mut MqOwnedBytes,
) -> i32 {
if result_out.is_null() || error_out.is_null() {
return result::INVALID_ARGUMENT;
}
// SAFETY: output pointers are non-NULL host-provided out-parameters.
unsafe {
*result_out = MqOwnedBytes::EMPTY;
*error_out = MqOwnedBytes::EMPTY;
}
let Some(host) = current_host() else {
return result::INTERNAL;
};
// SAFETY: borrowed request buffer is valid for this callback.
let args_bytes = match unsafe { args.as_slice() } {
Ok(bytes) => bytes.to_vec(),
Err(_) => return result::INVALID_ARGUMENT,
};
// SAFETY: context pointer is the host-minted context for this invocation.
let mut context = unsafe { CallContext::new(ctx, host) };
let outcome = catch_unwind(AssertUnwindSafe(|| handler(&mut context, &args_bytes)));
let response = match outcome {
Ok(Ok(bytes)) => Ok(bytes),
Ok(Err(error)) => Err(error),
Err(_) => Err(PluginError::invoke(
"plugin_panic",
"plugin handler panicked; the panic was caught at the ABI boundary",
)),
};
match response {
Ok(bytes) => {
if bytes.len() > MAX_RESULT_WIRE_BYTES {
return write_error(
host,
error_out,
&PluginError::wire(
"result_too_large",
format!(
"plugin result is {} bytes, limit is {MAX_RESULT_WIRE_BYTES}",
bytes.len()
),
),
);
}
match HostBuffer::copy_from(host, &bytes) {
Ok(buffer) => {
// SAFETY: result_out is a valid out-parameter.
unsafe { *result_out = buffer.into_raw() };
result::OK
}
Err(error) => write_error(host, error_out, &error),
}
}
Err(error) => write_error(host, error_out, &error),
}
}
fn write_error(host: &'static MqHostApi, error_out: *mut MqOwnedBytes, error: &PluginError) -> i32 {
let encoded = match WireResponse::from_error(error).to_json_bytes() {
Ok(bytes) if bytes.len() <= MAX_ERROR_WIRE_BYTES => bytes,
_ => br#"{"wire_version":1,"kind":"response","error":{"kind":"invoke","code":"plugin_error","message":"plugin failed with an unencodable error"}}"#.to_vec(),
};
let code = match error.kind {
marqdo_plugin_abi::ErrorKind::Wire => result::BAD_WIRE,
marqdo_plugin_abi::ErrorKind::Capability => result::CAPABILITY,
marqdo_plugin_abi::ErrorKind::Unsupported => result::UNSUPPORTED,
_ => result::INTERNAL,
};
match HostBuffer::copy_from(host, &encoded) {
Ok(buffer) => {
// SAFETY: error_out is a valid out-parameter.
unsafe { *error_out = buffer.into_raw() };
code
}
Err(_) => result::OUT_OF_MEMORY,
}
}
/// Free a host-owned buffer (used by generated code/tests).
///
/// # Safety
///
/// `buffer` must have been allocated by the host allocator and not freed yet.
pub unsafe fn free_host_buffer(host: &MqHostApi, buffer: MqOwnedBytes) {
// SAFETY: caller guarantees the alloc/free pair.
unsafe { release_host_buffer(host, buffer) };
}
+143
View File
@@ -0,0 +1,143 @@
//! Rust SDK for writing Marqdo native plugins against plugin ABI v1.
//!
//! The SDK is the plugin-developer side of `include/marqdo_plugin_abi_v1.h`.
//! It hides the raw C layout behind safe wrappers and provides the
//! [`mq_plugin_entry!`] macro that exports the required
//! `mq_plugin_entry_v1` symbol:
//!
//! ```
//! use marqdo_plugin_sdk::{mq_plugin_entry, CallContext, PluginError, Value};
//!
//! fn add(_ctx: &mut CallContext, args: &[u8]) -> Result<Vec<u8>, PluginError> {
//! let request = marqdo_plugin_sdk::wire::decode_request(args)?;
//! let values = request.typed_args()?;
//! let a = marqdo_plugin_sdk::wire::int_arg(&values, "a")?;
//! let b = marqdo_plugin_sdk::wire::int_arg(&values, "b")?;
//! marqdo_plugin_sdk::wire::success(Some(Value::Int((a + b).into())))
//! }
//!
//! mq_plugin_entry! {
//! name: "demo.solver",
//! version: "0.1.0",
//! exports: {
//! "solver.add" => "($a: Int, $b: Int) -> Int" => add,
//! }
//! }
//! ```
//!
//! The SDK never depends on host-only crates: it only uses the shared ABI
//! types and the JSON wire envelope from `marqdo-plugin-abi`. Building a
//! plugin does not grant it any capability; authorization is a separate host
//! decision performed before loading.
#![deny(missing_docs)]
pub use marqdo_plugin_abi::abi::result as result_code;
pub use marqdo_plugin_abi::abi::{
MqBytes, MqCallContext, MqHostApi, MqOwnedBytes, MqPluginApi, MqPluginInvoke, ABI_MAJOR,
ABI_MINOR, ABI_VERSION_STRING, ENTRY_SYMBOL,
};
pub use marqdo_plugin_abi::{PluginError, Value, WireRequest, WireResponse, WIRE_VERSION};
pub mod bytes;
pub mod call;
pub mod entry;
pub mod wire;
pub use bytes::{BytesRef, HostBuffer};
pub use call::CallContext;
pub use wire::{
bool_arg, decode_request, error_response, int_arg, response_value, success, success_raw,
text_arg, value_arg,
};
/// Plugin handler signature.
///
/// A handler receives the per-call context (for capability requests and
/// logging) and the raw request envelope bytes, and returns the raw response
/// envelope bytes on success.
///
/// Use [`wire::decode_request`] and [`wire::success`] to build the response;
/// handlers should never panic: panics are caught by the SDK and converted
/// into a structured error, but the plugin process stays healthy only if the
/// panic does not corrupt plugin state.
pub type HandlerFn = fn(&mut CallContext, &[u8]) -> Result<Vec<u8>, PluginError>;
/// Declare a plugin and export `mq_plugin_entry_v1`.
///
/// ```ignore
/// marqdo_plugin_sdk::mq_plugin_entry! {
/// name: "demo.solver",
/// version: "0.1.0",
/// exports: {
/// "solver.add" => "($a: Int, $b: Int) -> Int" => add,
/// "solver.echo" => "($text: Text) -> Text" => echo,
/// }
/// }
/// ```
///
/// Each handler is a path (or non-capturing closure) with the [`HandlerFn`]
/// signature. The macro:
/// - validates the host ABI table (major version and `struct_size`),
/// - reports the plugin ABI version and a metadata envelope,
/// - registers every export and fails the load if registration fails.
#[macro_export]
macro_rules! mq_plugin_entry {
(
name: $name:literal,
version: $version:literal,
exports: {
$( $export_name:literal => $signature:literal => $handler:expr ),* $(,)?
}
) => {
/// Marqdo plugin ABI v1 entry point (generated by the SDK macro).
#[unsafe(no_mangle)]
pub unsafe extern "C" fn mq_plugin_entry_v1(
host: *const $crate::MqHostApi,
plugin: *mut $crate::MqPluginApi,
) -> i32 {
const METADATA: &[u8] = concat!(
"{\"name\":\"", $name, "\",\"version\":\"", $version, "\"}"
)
.as_bytes();
let metadata: &'static [u8] = METADATA;
// SAFETY: the host provides the ABI tables per the header contract.
let init = unsafe { $crate::entry::initialize(host, plugin, metadata) };
if init != 0 {
return init;
}
$(
{
extern "C" fn invoke(
ctx: *mut $crate::MqCallContext,
args: $crate::MqBytes,
result: *mut $crate::MqOwnedBytes,
error: *mut $crate::MqOwnedBytes,
) -> i32 {
// Expand the user's handler expression in a safe
// context (also required by `macro_metavars_in_unsafe`).
let handler: $crate::HandlerFn = $handler;
// SAFETY: the host owns the invocation buffers; the SDK
// validates them and never retains them.
unsafe {
$crate::entry::dispatch(handler, ctx, args, result, error)
}
}
let export_name: &str = $export_name;
let signature: &str = $signature;
// SAFETY: host table is valid for the plugin lifetime and
// was validated by `initialize`.
let code =
unsafe { $crate::entry::register_export(host, export_name, signature, invoke) };
if code != 0 {
return code;
}
}
)*
$crate::result_code::OK
}
};
}
#[cfg(test)]
mod tests;
+245
View File
@@ -0,0 +1,245 @@
//! End-to-end SDK tests: run the macro-generated entry point against a tiny
//! in-process host table and invoke the registered export.
use std::ffi::c_void;
use std::ptr;
use marqdo_plugin_abi::abi::{
result, MqBytes, MqCallContext, MqHostApi, MqOwnedBytes, MqPluginApi, MqPluginInvoke,
ABI_MAJOR, ABI_MINOR,
};
use crate::wire;
use crate::{CallContext, PluginError, Value, WireRequest, WireResponse};
/// ABI v1 is single-threaded: the generated plugin stores the host table in a
/// process-global. Serialize tests that call the entry point so they do not
/// race (the SDK's own contract, not a test-only limitation).
static ABI_TEST_LOCK: std::sync::Mutex<()> = std::sync::Mutex::new(());
fn abi_test_lock() -> std::sync::MutexGuard<'static, ()> {
ABI_TEST_LOCK
.lock()
.unwrap_or_else(std::sync::PoisonError::into_inner)
}
#[derive(Default)]
struct TestHostState {
registrations: Vec<(String, String, MqPluginInvoke)>,
}
unsafe extern "C" fn test_alloc(_host_data: *mut c_void, size: usize) -> *mut c_void {
const HEADER: usize = 16;
if size == 0 {
return ptr::null_mut();
}
let Ok(layout) = std::alloc::Layout::from_size_align(size + HEADER, 16) else {
return ptr::null_mut();
};
// SAFETY: non-zero layout.
let base = unsafe { std::alloc::alloc(layout) };
if base.is_null() {
return ptr::null_mut();
}
// SAFETY: allocation has room for the header.
unsafe { (base as *mut usize).write(size) };
// SAFETY: offset within the allocation.
unsafe { base.add(HEADER) as *mut c_void }
}
unsafe extern "C" fn test_free(_host_data: *mut c_void, pointer: *mut c_void) {
const HEADER: usize = 16;
if pointer.is_null() {
return;
}
// SAFETY: only pointers from test_alloc are freed.
unsafe {
let base = (pointer as *mut u8).sub(HEADER);
let size = (base as *const usize).read();
std::alloc::dealloc(
base,
std::alloc::Layout::from_size_align_unchecked(size + HEADER, 16),
);
}
}
unsafe extern "C" fn test_register(
host_data: *mut c_void,
export_name: MqBytes,
signature_wire: MqBytes,
invoke: MqPluginInvoke,
) -> i32 {
if host_data.is_null() {
return result::INVALID_ARGUMENT;
}
// SAFETY: host_data points at TestHostState for the test.
let state = unsafe { &mut *(host_data as *mut TestHostState) };
// SAFETY: buffers are valid for this callback.
let name = match unsafe { export_name.as_slice() } {
Ok(bytes) => String::from_utf8_lossy(bytes).into_owned(),
Err(_) => return result::INVALID_ARGUMENT,
};
// SAFETY: buffers are valid for this callback.
let signature = match unsafe { signature_wire.as_slice() } {
Ok(bytes) => String::from_utf8_lossy(bytes).into_owned(),
Err(_) => return result::INVALID_ARGUMENT,
};
state.registrations.push((name, signature, invoke));
result::OK
}
unsafe extern "C" fn test_capability(
_ctx: *mut MqCallContext,
_name: MqBytes,
_request: MqBytes,
reply: *mut MqOwnedBytes,
) -> i32 {
if !reply.is_null() {
// SAFETY: output pointer is non-NULL.
unsafe { *reply = MqOwnedBytes::EMPTY };
}
result::UNSUPPORTED
}
fn add(_ctx: &mut CallContext, args: &[u8]) -> Result<Vec<u8>, PluginError> {
let request = wire::decode_request(args)?;
let values = request.typed_args()?;
let a = wire::int_arg(&values, "a")?;
let b = wire::int_arg(&values, "b")?;
wire::success(Some(Value::Int((a + b).into())))
}
crate::mq_plugin_entry! {
name: "sdk.test",
version: "0.1.0",
exports: {
"test.add" => "($a: Int, $b: Int) -> Int" => add,
}
}
struct TestHost {
_state: Box<TestHostState>,
api: MqHostApi,
}
fn test_host() -> TestHost {
let mut state = Box::new(TestHostState::default());
let api = MqHostApi {
struct_size: std::mem::size_of::<MqHostApi>() as u32,
abi_major: ABI_MAJOR,
abi_minor: ABI_MINOR,
host_data: (&mut *state) as *mut TestHostState as *mut c_void,
alloc: test_alloc,
free: test_free,
register_function: test_register,
request_capability: test_capability,
};
TestHost { _state: state, api }
}
#[test]
fn macro_exports_and_registers() {
let _guard = abi_test_lock();
let host = test_host();
let mut plugin_api = MqPluginApi::host_initialized();
// SAFETY: test host table follows the ABI contract.
let code = unsafe { mq_plugin_entry_v1(&host.api as *const MqHostApi, &mut plugin_api) };
assert_eq!(code, result::OK);
assert_eq!(plugin_api.abi_major, ABI_MAJOR);
assert_eq!(plugin_api.abi_minor, ABI_MINOR);
// SAFETY: metadata is plugin static data valid during the entry call.
let metadata = unsafe { plugin_api.plugin_metadata_wire.as_slice() }.expect("metadata");
let metadata = String::from_utf8_lossy(metadata);
assert!(metadata.contains("\"name\":\"sdk.test\""));
assert_eq!(host._state.registrations.len(), 1);
assert_eq!(host._state.registrations[0].0, "test.add");
assert!(host._state.registrations[0]
.1
.contains("($a: Int, $b: Int) -> Int"));
}
#[test]
fn registered_export_roundtrips_wire_request() {
let _guard = abi_test_lock();
let host = test_host();
let mut plugin_api = MqPluginApi::host_initialized();
// SAFETY: test host table follows the ABI contract.
let code = unsafe { mq_plugin_entry_v1(&host.api as *const MqHostApi, &mut plugin_api) };
assert_eq!(code, result::OK);
let request = WireRequest::new("test.add")
.with_arg("a", &Value::Int(20_i64.into()))
.with_arg("b", &Value::Int(22_i64.into()));
let request_bytes = request.to_json_bytes().expect("request");
let (_, _, invoke) = &host._state.registrations[0];
let mut result_buffer = MqOwnedBytes::EMPTY;
let mut error_buffer = MqOwnedBytes::EMPTY;
// SAFETY: invoke is the SDK callback; null ctx is fine because the handler
// does not request a capability. Buffers are valid out-parameters.
let code = unsafe {
invoke(
ptr::null_mut(),
MqBytes::from_slice(&request_bytes),
&mut result_buffer,
&mut error_buffer,
)
};
assert_eq!(code, result::OK);
assert!(error_buffer.is_empty());
// SAFETY: result buffer was allocated by test_alloc for us.
let response_bytes = unsafe { result_buffer.to_vec() }.expect("result");
// SAFETY: allocated by test_alloc; release exactly once.
unsafe { test_free(ptr::null_mut(), result_buffer.data as *mut c_void) };
let response = WireResponse::from_json_bytes(&response_bytes).expect("response");
assert_eq!(
response.typed_value().expect("typed"),
Some(Value::Int(42_i64.into()))
);
}
#[test]
fn handler_error_is_written_as_error_envelope() {
let _guard = abi_test_lock();
let host = test_host();
let mut plugin_api = MqPluginApi::host_initialized();
// SAFETY: test host table follows the ABI contract.
let code = unsafe { mq_plugin_entry_v1(&host.api as *const MqHostApi, &mut plugin_api) };
assert_eq!(code, result::OK);
let request = WireRequest::new("test.add"); // missing arguments
let request_bytes = request.to_json_bytes().expect("request");
let (_, _, invoke) = &host._state.registrations[0];
let mut result_buffer = MqOwnedBytes::EMPTY;
let mut error_buffer = MqOwnedBytes::EMPTY;
// SAFETY: invoke is the SDK callback with valid out-parameters.
let code = unsafe {
invoke(
ptr::null_mut(),
MqBytes::from_slice(&request_bytes),
&mut result_buffer,
&mut error_buffer,
)
};
assert_ne!(code, result::OK);
assert!(result_buffer.is_empty());
// SAFETY: error buffer was allocated by test_alloc for us.
let error_bytes = unsafe { error_buffer.to_vec() }.expect("error");
// SAFETY: allocated by test_alloc; release exactly once.
unsafe { test_free(ptr::null_mut(), error_buffer.data as *mut c_void) };
let response = WireResponse::from_error_json_bytes(&error_bytes).expect("decode");
let error = response.into_result().expect_err("error");
assert_eq!(error.code, "missing_argument");
assert_eq!(error.kind, marqdo_plugin_abi::ErrorKind::Invoke);
}
#[test]
fn initialization_rejects_bad_host_major() {
let _guard = abi_test_lock();
let mut host = test_host();
host.api.abi_major = 2;
let mut plugin_api = MqPluginApi::host_initialized();
// SAFETY: intentionally inconsistent host table; entry must reject it.
let code = unsafe { mq_plugin_entry_v1(&host.api as *const MqHostApi, &mut plugin_api) };
assert_eq!(code, result::ABI_MISMATCH);
}
+98
View File
@@ -0,0 +1,98 @@
//! Wire envelope helpers for plugin handlers.
//!
//! The canonical envelope is defined by `marqdo-plugin-abi` and documented in
//! `spec/value-wire.md`: UTF-8 JSON, `wire_version == 1`, type-tagged values.
//! Handlers normally do:
//!
//! ```ignore
//! fn add(ctx: &mut CallContext, args: &[u8]) -> Result<Vec<u8>, PluginError> {
//! let request = decode_request(args)?;
//! let values = request.typed_args()?;
//! success(Some(Value::Int((int_arg(&values, "a")? + int_arg(&values, "b")?).into())))
//! }
//! ```
use std::collections::BTreeMap;
use marqdo_plugin_abi::{
bool_from_value, int_from_value, text_from_value, PluginError, Value, WireRequest, WireResponse,
};
use serde_json::Value as Json;
/// Decode and validate a request envelope received from the host.
pub fn decode_request(bytes: &[u8]) -> Result<WireRequest, PluginError> {
WireRequest::from_json_bytes(bytes)
}
/// Look up a typed argument by name.
pub fn value_arg<'a>(
values: &'a BTreeMap<String, Value>,
name: &str,
) -> Result<&'a Value, PluginError> {
values.get(name).ok_or_else(|| {
PluginError::invoke(
"missing_argument",
format!("required argument `{name}` is missing"),
)
})
}
/// Look up an integer argument (must fit in `i64`).
pub fn int_arg(values: &BTreeMap<String, Value>, name: &str) -> Result<i64, PluginError> {
let value = value_arg(values, name)?;
int_from_value(value).ok_or_else(|| {
PluginError::invoke(
"invalid_argument_type",
format!("argument `{name}` must be an Int"),
)
})
}
/// Look up a text argument.
pub fn text_arg<'a>(
values: &'a BTreeMap<String, Value>,
name: &str,
) -> Result<&'a str, PluginError> {
let value = value_arg(values, name)?;
text_from_value(value).ok_or_else(|| {
PluginError::invoke(
"invalid_argument_type",
format!("argument `{name}` must be Text"),
)
})
}
/// Look up a boolean argument.
pub fn bool_arg(values: &BTreeMap<String, Value>, name: &str) -> Result<bool, PluginError> {
let value = value_arg(values, name)?;
bool_from_value(value).ok_or_else(|| {
PluginError::invoke(
"invalid_argument_type",
format!("argument `{name}` must be Bool"),
)
})
}
/// Encode a successful response envelope.
pub fn success(value: Option<Value>) -> Result<Vec<u8>, PluginError> {
success_raw(value.as_ref().map(marqdo_plugin_abi::to_wire_json))
}
/// Encode a successful response with an already-encoded type-tagged value.
pub fn success_raw(value: Option<Json>) -> Result<Vec<u8>, PluginError> {
WireResponse::success_raw(value).to_json_bytes()
}
/// Encode an error response envelope.
///
/// The SDK's dispatch layer uses this automatically when a handler returns an
/// error; handlers may also build custom error responses with it.
pub fn error_response(error: &PluginError) -> Result<Vec<u8>, PluginError> {
WireResponse::from_error(error).to_json_bytes()
}
/// Decode a response value back into a typed [`Value`] (useful in tests and
/// plugins that compose calls).
pub fn response_value(bytes: &[u8]) -> Result<Option<Value>, PluginError> {
WireResponse::from_json_bytes(bytes)?.typed_value()
}
+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;
}
+472
View File
@@ -0,0 +1,472 @@
/*
* Marqdo plugin C ABI, generation v1.
* =====================================================================
*
* This header is the canonical, frozen description of the Marqdo native
* plugin ABI v1. It is an independent ABI generation: it is *not* the old
* `marqdo_abi.h` v2 interface and is neither source- nor binary-compatible
* with it. Only an explicit, separately tested adapter may ever bridge the
* two.
*
* This file defines stable-layout C types only:
*
* - fixed-width integers (`int32_t`, `uint32_t`) and `size_t`,
* - byte buffers represented as length + pointer (`MqBytes` /
* `MqOwnedBytes`),
* - opaque, host-owned handles (`MqCallContext`),
* - `extern "C"` function pointers.
*
* The following must NEVER cross this boundary:
*
* - Rust `String` / `Vec` / `Result` / trait objects / panics,
* - C++ exceptions, Go runtime objects or garbage-collected pointers,
* - raw pointers to host-internal structures (other than the opaque
* `MqCallContext *` minted for one invocation),
* - real filesystem handles, sockets, keys or OS resources; capabilities
* are requested symbolically through `MqHostApi::request_capability`.
*
* A C ABI IS NOT A SANDBOX
* ------------------------
* Native plugins are loaded into the host process. They are not isolated:
* a plugin can read host memory, call arbitrary syscalls, crash the process
* or corrupt the host. In-process native loading therefore requires an
* explicit user trust decision. Untrusted third-party plugins must run in an
* isolated worker process (same logical plugin API, length-prefixed IPC
* transport) or a Wasm component. Do not present this ABI as a security
* boundary.
*
* VERSIONS
* --------
* Three independent versions exist and must never be conflated:
*
* 1. Marqdo language / syntax / semantics version,
* 2. plugin ABI major.minor (this header, `MQ_ABI_MAJOR`/`MQ_ABI_MINOR`),
* 3. plugin package SemVer (declared in `plugin.yaml`).
*
* This header is ABI major 1, minor 0.
*
* TARGET AND WORD SIZE
* --------------------
* The layout below uses `size_t`, so it depends on the target triple and the
* pointer width. A plugin artifact is only loadable by a host built for the
* same target triple and the same pointer width (32-bit and 64-bit objects
* are never interchangeable). All struct fields use native endianness;
* host and plugin must share the target byte order. The JSON wire payloads
* are UTF-8 and endian-neutral.
*
* LAYOUT EXPECTATIONS (little/big-endian, size_t == 8 bytes)
* ---------------------------------------------------------
* sizeof(MqBytes) == 16, alignof == 8
* sizeof(MqOwnedBytes) == 16, alignof == 8
* sizeof(MqPluginApi) == 32, alignof == 8
* sizeof(MqHostApi) == 56, alignof == 8
* sizeof(MqPluginInvoke) == 8
* The same expectations are asserted in `crates/marqdo-plugin-abi`.
*
* BUFFER OWNERSHIP AND LIFETIMES
* ------------------------------
* There are three distinct kinds of byte buffer:
*
* (a) Host-owned input buffers (`args_wire`, capability `request_wire`,
* `export_name`, `signature_wire`, `plugin_metadata_wire` as watched by
* the host). The producer of the pointer keeps it valid only for the
* duration of the call in which it is passed. The consumer MUST NOT
* retain the pointer, MUST NOT free it and MUST copy any data it needs
* to keep. In particular the host copies plugin metadata, export names
* and signatures during the entry/registration call.
*
* (b) Host-allocated output buffers. The host owns `alloc`/`free`. A plugin
* that produces `MqOwnedBytes` output (`result_wire`, `error_wire`,
* capability `reply_wire`) MUST allocate the memory with
* `host->alloc(host->host_data, size)` and write the payload there. The
* consuming side (host for invoke results/errors, plugin for capability
* replies) copies what it needs and then releases the buffer with
* `host->free(host->host_data, data)`. The producer MUST NOT free the
* buffer itself and MUST NOT use `malloc`/`new`/GC memory for it.
*
* (c) Plugin-owned static metadata. During `mq_plugin_entry_v1` the plugin
* passes `plugin_metadata_wire` pointing at storage it owns (typically a
* static string). It only has to remain valid for the duration of the
* entry call; the host copies it.
*
* Zero-length semantics: a buffer with `len == 0` must have `data == NULL`
* (hosts and plugins must treat `{NULL, 0}` as the empty buffer). A buffer
* with `len > 0` must have a non-NULL `data`. Violations are protocol errors
* (`MQ_ERR_INVALID_ARGUMENT` / `MQ_ERR_BAD_WIRE`), never silent.
*
* SIZE LIMITS (enforced by the host; plugins should fail fast)
* -----------------------------------------------------------
* MQ_MAX_EXPORT_NAME_BYTES 256
* MQ_MAX_SIGNATURE_WIRE_BYTES 4096
* MQ_MAX_METADATA_WIRE_BYTES 65536
* MQ_MAX_REQUEST_WIRE_BYTES 16777216 (16 MiB)
* MQ_MAX_RESULT_WIRE_BYTES 67108864 (64 MiB)
* MQ_MAX_ERROR_WIRE_BYTES 1048576 (1 MiB)
* MQ_MAX_CAPABILITY_REPLY_BYTES 16777216 (16 MiB)
* JSON depth is additionally limited to 64 levels. Requests/results that
* exceed these limits are rejected with a structured error; they must not
* be truncated and reparsed.
*
* ERROR FIELD BEHAVIOUR
* ---------------------
* `mq_plugin_entry_v1` returns `MQ_OK` (0) on success, a non-zero
* `MQ_ERR_*` code on failure. On a non-zero return the host MUST NOT read
* `plugin_metadata_wire`, `plugin_api.abi_*` or any registered callback.
*
* `MqPluginInvoke` returns `MQ_OK` (0) on success and a non-zero code on
* failure:
* - on success, `*result_wire` holds exactly one UTF-8 JSON response
* envelope (see `spec/value-wire.md` / wire_version 1) and
* `*error_wire` MUST be `{NULL, 0}`;
* - on failure, `*error_wire` holds a UTF-8 JSON error envelope
* (`{ "wire_version": 1, "kind": "response", "error": {...} }`) and
* `*result_wire` MUST be `{NULL, 0}`. The host treats a missing error
* envelope as an unstructured plugin failure and still fails the call.
* Both output pointers MUST be non-NULL as provided by the host; writing
* through a NULL output pointer is a caller/plugin contract violation.
*
* OOM / NULL ALLOCATION: `host->alloc` returns NULL on failure (and for
* `size == 0`). A plugin that cannot allocate must return
* `MQ_ERR_OUT_OF_MEMORY` and must not write partial output buffers.
*
* THREAD MODEL
* ------------
* v1 is deliberately single-threaded and synchronous:
* - `mq_plugin_entry_v1` is called exactly once, by the loading thread;
* - every `MqPluginInvoke` and every host callback for a given loaded
* plugin instance runs on that same thread;
* - at most one invocation is in flight per instance; the host serializes
* calls. A plugin must not start its own threads that call back into
* `MqHostApi`, and must not invoke the host from a signal handler;
* - there is no async/parallel callback contract in v1. `MqCallContext`
* is valid only for the duration of the invocation it was minted for,
* must not be cached, and must not be used after the call returns.
*
* UNLOADING / SHUTDOWN
* --------------------
* v1 does not support hot-unload or reload of a loaded native library.
* A plugin lives for the lifetime of the process (or of the trusted loading
* scope); there is no `shutdown` callback in v1. Hosts must not unload a
* library while a call is in flight, and must keep all registered function
* pointers reachable until shutdown. Plugins must tolerate never being
* unloaded.
*
* VERSION NEGOTIATION
* -------------------
* The host fills `MqPluginApi::struct_size` with sizeof(MqPluginApi) before
* the entry call and zeroes the remaining fields; the plugin fills in
* `abi_major`, `abi_minor` and `plugin_metadata_wire`. The host then:
* - rejects the load if `plugin->abi_major != MQ_ABI_MAJOR` (major is
* never negotiated);
* - accepts a plugin minor greater than its own, but clamps to the host's
* supported minor and only uses features defined at that minor.
* The plugin mirrors the check against the host table:
* - reject if `host == NULL`, `plugin == NULL`,
* `host->struct_size < sizeof(MqHostApi)` (the exact size of the v1.0
* table it was built against) or `host->abi_major != MQ_ABI_MAJOR`.
* `struct_size` is the extension mechanism: a consumer must only read a
* field when `struct_size >= offsetof(field) + sizeof(field)`; a producer
* sets `struct_size = sizeof(its struct)` and may append new fields only in
* a later ABI minor while never reordering or resizing earlier fields.
* Fields appended in a later minor are ABSENT (not usable) when the
* negotiated minor is lower.
*
* EXCEPTIONS, PANICS, UNDEFINED BEHAVIOUR
* ---------------------------------------
* No panic, exception, longjmp or unwinding of any kind may cross the ABI
* boundary. Rust plugins should call `extern "C"` entry points from
* panic-aborting builds or catch panics inside the SDK; C++ plugins must
* catch all exceptions inside their invocation function. The host treats a
* process crash as a host process crash: this ABI cannot contain it.
*
* WIRE FORMAT
* -----------
* All payloads are UTF-8 JSON, `wire_version == 1`. See the canonical
* `spec/value-wire.md` (type-tagged values: every value is an object with a
* `type` tag; 64-bit-and-beyond integers use decimal strings; NaN/Infinity
* use explicit tags). Names:
* - request : {"wire_version":1,"kind":"request","function":...,
* "args":{...},"context":{...}}
* - response : {"wire_version":1,"kind":"response","value":{...}}
* - error : {"wire_version":1,"kind":"response","error":
* {"kind":"...","code":"...","message":"...",...}}
* `export_name` and capability `name` are UTF-8 byte strings (not JSON).
* `signature_wire` is the JSON object {"signature":"<signature string>"}.
* `plugin_metadata_wire` is the JSON object
* {"name":"<plugin name>","version":"<semver>"} (extra fields ignored).
*/
#ifndef MARQDO_PLUGIN_ABI_V1_H
#define MARQDO_PLUGIN_ABI_V1_H
#include <stddef.h>
#include <stdint.h>
#ifdef __cplusplus
extern "C" {
#endif
/* ------------------------------------------------------------------ */
/* Version and result codes */
/* ------------------------------------------------------------------ */
/** Plugin ABI major version. Major mismatches always fail the load. */
#define MQ_ABI_MAJOR 1u
/** Plugin ABI minor version implemented by this header. */
#define MQ_ABI_MINOR 0u
/** Human-readable ABI version of this header. */
#define MQ_ABI_VERSION_STRING "1.0"
/** Required exported symbol name. */
#define MQ_PLUGIN_ENTRY_SYMBOL "mq_plugin_entry_v1"
/** Success. */
#define MQ_OK 0
/** Malformed argument (NULL pointer, bad pointer/length pair, ...). */
#define MQ_ERR_INVALID_ARGUMENT 1
/** ABI major mismatch or incompatible struct_size. */
#define MQ_ERR_ABI_MISMATCH 2
/** A required export could not be registered. */
#define MQ_ERR_REGISTRATION 3
/** Operation/type/capability not supported by this version. */
#define MQ_ERR_UNSUPPORTED 4
/** Host allocation failed. */
#define MQ_ERR_OUT_OF_MEMORY 5
/** Payload is not valid wire_version 1 JSON. */
#define MQ_ERR_BAD_WIRE 6
/** Unexpected internal plugin failure (including caught panics). */
#define MQ_ERR_INTERNAL 7
/** Capability request failed or was denied by the host. */
#define MQ_ERR_CAPABILITY 8
/* ------------------------------------------------------------------ */
/* Size limits */
/* ------------------------------------------------------------------ */
#define MQ_MAX_EXPORT_NAME_BYTES 256u
#define MQ_MAX_SIGNATURE_WIRE_BYTES 4096u
#define MQ_MAX_METADATA_WIRE_BYTES 65536u
#define MQ_MAX_REQUEST_WIRE_BYTES (16u * 1024u * 1024u)
#define MQ_MAX_RESULT_WIRE_BYTES (64u * 1024u * 1024u)
#define MQ_MAX_ERROR_WIRE_BYTES (1024u * 1024u)
#define MQ_MAX_CAPABILITY_REPLY_BYTES (16u * 1024u * 1024u)
/* ------------------------------------------------------------------ */
/* Stable-layout buffer types */
/* ------------------------------------------------------------------ */
/**
* Borrowed, immutable byte view.
*
* Ownership stays with the producer; the pointer is valid only for the
* duration of the call that received it. `{NULL, 0}` is the empty buffer.
* A non-NULL `data` with `len == 0` is tolerated by neither side.
*/
typedef struct {
const uint8_t *data;
size_t len;
} MqBytes;
/**
* Mutable byte buffer ownership transfer.
*
* The producer allocates with `MqHostApi::alloc` and passes ownership to the
* consumer, which copies the bytes and then calls `MqHostApi::free` on
* `data`. `{NULL, 0}` is the empty buffer. A buffer left non-empty when the
* call returns is owned by the documented consumer; it is never freed by
* the producer.
*/
typedef struct {
uint8_t *data;
size_t len;
} MqOwnedBytes;
/**
* Opaque, host-owned invocation context.
*
* The plugin only ever receives a pointer to this type and must pass the
* same pointer back to `request_capability`. Its layout is private to the
* host and may change between ABI minors without notice. It is valid only
* during the invocation it was minted for and must not be cached, copied or
* inspected. Never dereference this pointer from a plugin.
*/
typedef struct MqCallContext MqCallContext;
/* ------------------------------------------------------------------ */
/* Function pointer types */
/* ------------------------------------------------------------------ */
/**
* Plugin invocation callback, registered once per export.
*
* Contract: see the ERROR FIELD BEHAVIOUR section above. The callback runs
* on the host invocation thread, with at most one call in flight per plugin
* instance. It must be reentrant-safe with respect to its own state because
* repeated invocations may occur sequentially. It must not panic/throw.
*
* @param ctx Opaque host context for this call (may be NULL only
* if the host could not mint one; then the plugin should
* fail with MQ_ERR_INVALID_ARGUMENT).
* @param args_wire Borrowed UTF-8 JSON request envelope.
* @param result_wire Host-provided out-parameter; on success must be
* filled with a host-allocated UTF-8 JSON response
* envelope. Must not be NULL.
* @param error_wire Host-provided out-parameter; on failure must be filled
* with a host-allocated UTF-8 JSON error envelope. Must
* not be NULL.
* @return MQ_OK on success, a non-zero MQ_ERR_* code otherwise.
*/
typedef int32_t (*MqPluginInvoke)(
MqCallContext *ctx,
MqBytes args_wire,
MqOwnedBytes *result_wire,
MqOwnedBytes *error_wire
);
/* ------------------------------------------------------------------ */
/* Host API table */
/* ------------------------------------------------------------------ */
/**
* Host-provided function table, valid for the whole life of the plugin
* instance. All function pointers are non-NULL in ABI v1.0.
*
* `host_data` is an opaque host-owned pointer that must be passed back to
* every function that takes it. Plugins must not interpret it.
*/
typedef struct {
/**
* sizeof(MqHostApi) as seen by the host. Consumers must check this
* against their own required size before reading any field (see VERSION
* NEGOTIATION). Producers never shrink the table; fields are only
* appended and never reordered.
*/
uint32_t struct_size;
/** Host-supported ABI major (must be MQ_ABI_MAJOR). */
uint32_t abi_major;
/** Host-supported ABI minor (features above this are unavailable). */
uint32_t abi_minor;
/** Opaque host state; pass back to every callback that accepts it. */
void *host_data;
/**
* Host allocator. Returns NULL on failure and for `size == 0`.
* The returned memory is at least `size` bytes and suitably aligned for
* byte buffers. The matching `free` must be used; never free with
* malloc/new/free() from the plugin runtime.
*/
void *(*alloc)(void *host_data, size_t size);
/**
* Host deallocator; must be called exactly once for a pointer returned by
* `alloc` (including capability replies allocated by the host). Passing
* NULL is a no-op.
*/
void (*free)(void *host_data, void *ptr);
/**
* Register one plugin export during `mq_plugin_entry_v1`.
*
* `export_name` is a UTF-8 dotted name, already namespaced by the
* manifest validation (e.g. "solver.add"). `signature_wire` is UTF-8
* JSON: {"signature":"(...)"}. Name and signature are copied by the
* host during this call. Returns MQ_OK or a non-zero MQ_ERR_* code; on
* failure the export must be considered not registered.
*
* Export names must not shadow Marqdo built-ins and must match the
* manifest exports exactly.
*/
int32_t (*register_function)(
void *host_data,
MqBytes export_name,
MqBytes signature_wire,
MqPluginInvoke invoke
);
/**
* Request a whitelisted capability from the host for the current call.
*
* `name` is a UTF-8 capability name (e.g. "math.compute", "fs.read",
* "clock"). `request_wire` is a UTF-8 JSON capability request whose shape
* is defined per capability. On success the host allocates
* `reply_wire` (with `alloc`) and the plugin must copy and then free it
* with `free`. On failure `reply_wire` is `{NULL, 0}` and the call
* returns a non-zero code.
*
* Capabilities are granted structurally by the host's authorization
* layer before the plugin is loaded; this function only consumes a grant
* and can never escalate privileges. `ctx` must be the context of the
* current invocation only.
*/
int32_t (*request_capability)(
MqCallContext *ctx,
MqBytes name,
MqBytes request_wire,
MqOwnedBytes *reply_wire
);
} MqHostApi;
/* ------------------------------------------------------------------ */
/* Plugin API table (host-filled, plugin-filled) */
/* ------------------------------------------------------------------ */
/**
* Plugin-side version/metadata table.
*
* The host initializes `struct_size` to sizeof(MqPluginApi) and zeroes the
* rest before calling the entry point. The plugin must set `abi_major`,
* `abi_minor` and `plugin_metadata_wire` and must not change
* `struct_size` (it may only be larger in a future ABI minor; consumers
* check it).
*/
typedef struct {
/** sizeof(MqPluginApi) as initialized by the host. */
uint32_t struct_size;
/** Plugin ABI major; must equal MQ_ABI_MAJOR for the load to proceed. */
uint32_t abi_major;
/** Plugin ABI minor; the host clamps and negotiates down as needed. */
uint32_t abi_minor;
/**
* Plugin metadata JSON, plugin-owned static storage, valid only for the
* duration of the entry call. Format:
* {"name":"<plugin name>","version":"<semver>"}
* The host copies it during the call. Must be a non-empty, valid UTF-8
* JSON object.
*/
MqBytes plugin_metadata_wire;
} MqPluginApi;
/**
* Required exported entry point. Exactly one per plugin artifact.
*
* @param host Host API table, host-owned, valid for the plugin lifetime.
* Must be non-NULL.
* @param plugin Plugin API table, host-provided. The plugin must fill it in
* and may not retain it. Must be non-NULL.
* @return MQ_OK on success, a non-zero MQ_ERR_* code on failure.
*
* The host calls this exactly once on the loading thread. The plugin
* registers every export through `host->register_function` during this call
* and must return MQ_OK only after all exports are registered successfully.
*/
typedef int32_t (*MqPluginEntryV1)(const MqHostApi *host, MqPluginApi *plugin);
#ifdef __cplusplus
} /* extern "C" */
#endif
/*
* Compile-time layout checks for the canonical 64-bit target. On other word
* sizes the expected sizes are smaller (every pointer/size_t shrinks by 4
* bytes); the Rust side asserts the corresponding architecture-specific
* values.
*/
#if defined(__STDC_VERSION__) && __STDC_VERSION__ >= 201112L
#if defined(__LP64__) || defined(_LP64)
_Static_assert(sizeof(MqBytes) == 16, "MqBytes layout must stay 16 bytes on 64-bit");
_Static_assert(sizeof(MqOwnedBytes) == 16, "MqOwnedBytes layout must stay 16 bytes on 64-bit");
_Static_assert(sizeof(MqPluginApi) == 32, "MqPluginApi layout must stay 32 bytes on 64-bit");
_Static_assert(sizeof(MqHostApi) == 56, "MqHostApi layout must stay 56 bytes on 64-bit");
#endif
#endif
#endif /* MARQDO_PLUGIN_ABI_V1_H */