Files
cflmy 6da206a906 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.
2026-11-20 10:43:59 +08:00

157 lines
4.9 KiB
Rust

//! 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) };
}