diff --git a/crates/marqdo-plugin-abi/Cargo.toml b/crates/marqdo-plugin-abi/Cargo.toml index fd18f85..e3466cb 100644 --- a/crates/marqdo-plugin-abi/Cargo.toml +++ b/crates/marqdo-plugin-abi/Cargo.toml @@ -16,4 +16,5 @@ serde_json = { workspace = true } serde_yaml = { workspace = true } thiserror = { workspace = true } libloading = { workspace = true } - +sha2 = { workspace = true } +hex = { workspace = true } diff --git a/crates/marqdo-plugin-abi/src/abi.rs b/crates/marqdo-plugin-abi/src/abi.rs new file mode 100644 index 0000000..9988aa3 --- /dev/null +++ b/crates/marqdo-plugin-abi/src/abi.rs @@ -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, 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::() 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 { + 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 { + 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::() 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, 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 { + 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::() == 16, "MqBytes must be 16 bytes"); + assert!(align_of::() == 8, "MqBytes must align to 8"); + assert!( + size_of::() == 16, + "MqOwnedBytes must be 16 bytes" + ); + assert!( + align_of::() == 8, + "MqOwnedBytes must align to 8" + ); + assert!( + size_of::() == 32, + "MqPluginApi must be 32 bytes" + ); + assert!( + align_of::() == 8, + "MqPluginApi must align to 8" + ); + assert!(size_of::() == 56, "MqHostApi must be 56 bytes"); + assert!(align_of::() == 8, "MqHostApi must align to 8"); + assert!( + size_of::() == 8, + "MqPluginInvoke must be 8 bytes" + ); +}; + +#[cfg(target_pointer_width = "32")] +const _: () = { + assert!(size_of::() == 8, "MqBytes must be 8 bytes"); + assert!( + size_of::() == 8, + "MqOwnedBytes must be 8 bytes" + ); + assert!( + size_of::() == 20, + "MqPluginApi must be 20 bytes" + ); + assert!(size_of::() == 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::(), 16); + assert_eq!(align_of::(), 8); + assert_eq!(size_of::(), 16); + assert_eq!(size_of::(), 32); + assert_eq!(size_of::(), 56); + assert_eq!(align_of::(), 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" + ); + } +} diff --git a/crates/marqdo-plugin-abi/src/artifact.rs b/crates/marqdo-plugin-abi/src/artifact.rs new file mode 100644 index 0000000..bd4195e --- /dev/null +++ b/crates/marqdo-plugin-abi/src/artifact.rs @@ -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 { + 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 { + 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 { + 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())); + } +} diff --git a/crates/marqdo-plugin-abi/src/error.rs b/crates/marqdo-plugin-abi/src/error.rs new file mode 100644 index 0000000..32e784c --- /dev/null +++ b/crates/marqdo-plugin-abi/src/error.rs @@ -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 { + 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, + /// 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, message: impl Into) -> 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) -> 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, message: impl Into) -> Self { + Self::new(ErrorKind::Manifest, code, message) + } + + /// An ABI negotiation/table error. + pub fn abi(code: impl Into, message: impl Into) -> Self { + Self::new(ErrorKind::Abi, code, message) + } + + /// An artifact resolution/hash error. + pub fn artifact(code: impl Into, message: impl Into) -> Self { + Self::new(ErrorKind::Artifact, code, message) + } + + /// A dynamic library/entry-point load error. + pub fn load(code: impl Into, message: impl Into) -> Self { + Self::new(ErrorKind::Load, code, message) + } + + /// A wire envelope error. + pub fn wire(code: impl Into, message: impl Into) -> Self { + Self::new(ErrorKind::Wire, code, message) + } + + /// A capability error. + pub fn capability(code: impl Into, message: impl Into) -> Self { + Self::new(ErrorKind::Capability, code, message) + } + + /// An invocation error. + pub fn invoke(code: impl Into, message: impl Into) -> Self { + Self::new(ErrorKind::Invoke, code, message) + } + + /// An unsupported-feature error. + pub fn unsupported(code: impl Into, message: impl Into) -> 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")); + } +} diff --git a/crates/marqdo-plugin-abi/src/lib.rs b/crates/marqdo-plugin-abi/src/lib.rs new file mode 100644 index 0000000..811e068 --- /dev/null +++ b/crates/marqdo-plugin-abi/src/lib.rs @@ -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, +}; diff --git a/crates/marqdo-plugin-abi/src/loader.rs b/crates/marqdo-plugin-abi/src/loader.rs new file mode 100644 index 0000000..739244b --- /dev/null +++ b/crates/marqdo-plugin-abi/src/loader.rs @@ -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 Result, 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, +} + +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(|_| ""), + ) + .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, + capability_handler: Option, +} + +/// 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, + /// 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, + exports: BTreeMap, + 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::>()) + .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::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 { + 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::() 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 = + 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::() 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 { + 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 { + 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, 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, +) -> Result, PluginError> { + let mut registered: BTreeMap = 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::(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, 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 { + // SAFETY: we pass a valid reference converted to a pointer. + unsafe { check_host_api(host as *const MqHostApi) } +} diff --git a/crates/marqdo-plugin-abi/src/manifest.rs b/crates/marqdo-plugin-abi/src/manifest.rs new file mode 100644 index 0000000..956b43c --- /dev/null +++ b/crates/marqdo-plugin-abi/src/manifest.rs @@ -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::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 { + 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, + /// Declared capability requirements. + #[serde(default)] + pub requires: Vec, + /// Declared artifacts. + pub artifacts: Vec, +} + +/// 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 { + 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 { + 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::parse(&self.plugin.abi) + } + + /// The parsed package version. + pub fn package_version(&self) -> Result { + 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::>() + .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, + /// Optional build metadata (without the leading `+`). + pub build: Option, +} + +impl PackageVersion { + /// Parse a semver-ish version string. + pub fn parse(raw: &str) -> Result { + 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::() + .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 { + 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 { + 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::().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 ` 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" + ); + } + } +} diff --git a/crates/marqdo-plugin-abi/src/wire.rs b/crates/marqdo-plugin-abi/src/wire.rs new file mode 100644 index 0000000..8eff482 --- /dev/null +++ b/crates/marqdo-plugin-abi/src/wire.rs @@ -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, + /// Opaque capability handle for this call; never a real OS handle. + #[serde(default, skip_serializing_if = "Option::is_none")] + pub capability_handle: Option, +} + +/// 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, + /// Per-call context. + #[serde(default)] + pub context: WireContext, +} + +impl WireRequest { + /// Start a request for `function`. + pub fn new(function: impl Into) -> 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, 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, 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) -> 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, 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, 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, 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 { + 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, + /// Optional non-sensitive detail. + #[serde(default, skip_serializing_if = "Option::is_none")] + pub detail: Option, +} + +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, + /// Structured error, absent for successful responses. + #[serde(default, skip_serializing_if = "Option::is_none")] + pub error: Option, +} + +impl WireResponse { + /// Successful response carrying an optional typed value. + pub fn success(value: Option) -> 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) -> 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, 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::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::decode(bytes, MAX_ERROR_WIRE_BYTES, "error") + } + + fn decode(bytes: &[u8], limit: usize, what: &str) -> Result { + 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 { + 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, 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 { + match value { + Value::Int(integer) => integer.to_string().parse::().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 { + 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" + ); + } +} diff --git a/crates/marqdo-plugin-abi/tests/loader_unix.rs b/crates/marqdo-plugin-abi/tests/loader_unix.rs new file mode 100644 index 0000000..5729400 --- /dev/null +++ b/crates/marqdo-plugin-abi/tests/loader_unix.rs @@ -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 { + 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 \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"); +} diff --git a/crates/marqdo-plugin-sdk/src/bytes.rs b/crates/marqdo-plugin-sdk/src/bytes.rs new file mode 100644 index 0000000..90b3a4f --- /dev/null +++ b/crates/marqdo-plugin-sdk/src/bytes.rs @@ -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 { + 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 { + 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) }; +} diff --git a/crates/marqdo-plugin-sdk/src/call.rs b/crates/marqdo-plugin-sdk/src/call.rs new file mode 100644 index 0000000..a484e91 --- /dev/null +++ b/crates/marqdo-plugin-sdk/src/call.rs @@ -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, 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() + } +} diff --git a/crates/marqdo-plugin-sdk/src/entry.rs b/crates/marqdo-plugin-sdk/src/entry.rs new file mode 100644 index 0000000..84743e5 --- /dev/null +++ b/crates/marqdo-plugin-sdk/src/entry.rs @@ -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 = 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::() 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) }; +} diff --git a/crates/marqdo-plugin-sdk/src/lib.rs b/crates/marqdo-plugin-sdk/src/lib.rs new file mode 100644 index 0000000..5833938 --- /dev/null +++ b/crates/marqdo-plugin-sdk/src/lib.rs @@ -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, 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, 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; diff --git a/crates/marqdo-plugin-sdk/src/tests.rs b/crates/marqdo-plugin-sdk/src/tests.rs new file mode 100644 index 0000000..2483884 --- /dev/null +++ b/crates/marqdo-plugin-sdk/src/tests.rs @@ -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, 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, + api: MqHostApi, +} + +fn test_host() -> TestHost { + let mut state = Box::new(TestHostState::default()); + let api = MqHostApi { + struct_size: std::mem::size_of::() 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); +} diff --git a/crates/marqdo-plugin-sdk/src/wire.rs b/crates/marqdo-plugin-sdk/src/wire.rs new file mode 100644 index 0000000..9266abb --- /dev/null +++ b/crates/marqdo-plugin-sdk/src/wire.rs @@ -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, 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::from_json_bytes(bytes) +} + +/// Look up a typed argument by name. +pub fn value_arg<'a>( + values: &'a BTreeMap, + 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, name: &str) -> Result { + 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, + 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, name: &str) -> Result { + 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) -> Result, 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) -> Result, 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, 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, PluginError> { + WireResponse::from_json_bytes(bytes)?.typed_value() +} diff --git a/examples/plugin-demo/README.md b/examples/plugin-demo/README.md new file mode 100644 index 0000000..899176e --- /dev/null +++ b/examples/plugin-demo/README.md @@ -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. diff --git a/examples/plugin-demo/build.sh b/examples/plugin-demo/build.sh new file mode 100755 index 0000000..0935707 --- /dev/null +++ b/examples/plugin-demo/build.sh @@ -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" diff --git a/examples/plugin-demo/plugin.yaml b/examples/plugin-demo/plugin.yaml new file mode 100644 index 0000000..c9bc297 --- /dev/null +++ b/examples/plugin-demo/plugin.yaml @@ -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" diff --git a/examples/plugin-demo/solver.c b/examples/plugin-demo/solver.c new file mode 100644 index 0000000..636d20c --- /dev/null +++ b/examples/plugin-demo/solver.c @@ -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 +#include +#include +#include + +#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; +} diff --git a/include/marqdo_plugin_abi_v1.h b/include/marqdo_plugin_abi_v1.h new file mode 100644 index 0000000..0dab78a --- /dev/null +++ b/include/marqdo_plugin_abi_v1.h @@ -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":""}. + * `plugin_metadata_wire` is the JSON object + * {"name":"","version":""} (extra fields ignored). + */ + +#ifndef MARQDO_PLUGIN_ABI_V1_H +#define MARQDO_PLUGIN_ABI_V1_H + +#include +#include + +#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":"","version":""} + * 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 */