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.
200 lines
7.1 KiB
Rust
200 lines
7.1 KiB
Rust
//! 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) };
|
|
}
|