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