fidius-guest::descriptor
Rust
FFI descriptor and registry types for the Fidius plugin framework.
These types form the stable C ABI contract between host and plugin.
All types use #[repr(C)] layout and are read directly from dylib memory.
Structs
Section titled “Structs”struct MetaKv
Section titled “struct MetaKv”pub
Static key/value pair for method-level or trait-level metadata.
Both key and value point to null-terminated UTF-8 C strings with
'static lifetime (typically string literals embedded in the plugin’s
.rodata). Fidius treats values as opaque — hosts define conventions
via their own metadata schemas. See ADR/spec for the fidius.*
reserved namespace.
Fields
Section titled “Fields”| Name | Type | Description |
|---|---|---|
key |
*const c_char |
Null-terminated UTF-8 key. Never null. |
value |
*const c_char |
Null-terminated UTF-8 value. Never null (may be empty string). |
struct MethodMetaEntry
Section titled “struct MethodMetaEntry”pub
Per-method metadata entry. One entry per method in declaration order, stored in the array referenced by PluginDescriptor::method_metadata.
Methods with no #[method_meta(...)] annotations have kvs: null and
kv_count: 0 — the entry exists but is empty, so hosts can index
uniformly by method index.
Fields
Section titled “Fields”| Name | Type | Description |
|---|---|---|
kvs |
*const MetaKv |
Pointer to an array of kv_count MetaKv entries, or null if this method has no metadata. |
kv_count |
u32 |
Number of key/value pairs for this method. Zero when kvs is null. |
struct PluginRegistry
Section titled “struct PluginRegistry”pub
Top-level registry exported by every Fidius plugin dylib.
Each dylib exports exactly one FIDIUS_PLUGIN_REGISTRY static symbol
pointing to this struct. The registry contains pointers to one or more
PluginDescriptors (supporting multiple plugins per dylib).
Safety
descriptorsmust point to a valid array ofplugin_countpointers.- Each pointer in the array must point to a valid
PluginDescriptor. - All pointed-to data must have
'staticlifetime (typically link-time constants).
Fields
Section titled “Fields”| Name | Type | Description |
|---|---|---|
magic |
[u8; 8] |
Magic bytes — must equal FIDIUS_MAGIC (b"FIDIUS\0\0"). |
registry_version |
u32 |
Layout version of this struct. Must equal REGISTRY_VERSION. |
plugin_count |
u32 |
Number of plugin descriptors in this registry. |
descriptors |
*const *const PluginDescriptor |
Pointer to an array of plugin_count descriptor pointers. |
struct PluginDescriptor
Section titled “struct PluginDescriptor”pub
Metadata descriptor for a single plugin within a dylib.
Contains all information the host needs to validate and call the plugin without executing any plugin code. All string fields are pointers to static, null-terminated C strings embedded in the dylib.
Safety
interface_nameandplugin_namemust point to valid, null-terminated, UTF-8 C strings with'staticlifetime.vtablemust point to a valid#[repr(C)]vtable struct matching the interface identified byinterface_nameandinterface_hash.- When
buffer_strategy == PluginAllocated,free_buffermust beSome. - All pointed-to data must outlive any
PluginHandlederived from this descriptor.
Fields
Section titled “Fields”| Name | Type | Description |
|---|---|---|
descriptor_size |
u32 |
Size in bytes of this descriptor struct at plugin build time. The host reads this field FIRST (it’s at offset 0) before trusting any other offset calculation. Any field whose offset is >= descriptor_size is not present in this plugin’s build — the plugin was compiled against an older fidius version that didn’t have that field yet.Enables post-1.0 minor releases to add new fields at the end of this struct without breaking older plugins. See ADR-0002. |
abi_version |
u32 |
Descriptor struct layout version. Must equal ABI_VERSION. |
interface_name |
*const c_char |
Null-terminated name of the trait this plugin implements (e.g., "ImageFilter"). |
interface_hash |
u64 |
FNV-1a hash of the required method signatures. Detects ABI drift. |
interface_version |
u32 |
User-specified interface version from #[plugin_interface(version = N)]. |
capabilities |
u64 |
Bitfield where bit N indicates optional method N is implemented. Supports up to 64 optional methods per interface. |
buffer_strategy |
u8 |
Buffer management strategy this plugin’s vtable expects. |
plugin_name |
*const c_char |
Null-terminated human-readable name for this plugin implementation. |
vtable |
*const c_void |
Opaque pointer to the interface-specific #[repr(C)] vtable struct. |
free_buffer |
Option<unsafe extern "C" fn(*mut u8, usize)> |
Deallocation function for plugin-allocated buffers. Must be Some when buffer_strategy == PluginAllocated. The host calls this after reading output data to free the plugin’s allocation. |
method_count |
u32 |
Total number of methods in the vtable (required + optional). Used for bounds checking in call_method. |
method_metadata |
*const MethodMetaEntry |
Pointer to an array of method_count MethodMetaEntry structs, one per method in declaration order. Each entry may be empty (kvs=null, kv_count=0) if the method declared no metadata.Null if the interface used no #[method_meta(...)] annotations at all (optimization for the common case). |
trait_metadata |
*const MetaKv |
Pointer to an array of trait_metadata_count MetaKv entries for trait-level metadata (declared via #[trait_meta(...)]).Null if no trait-level metadata was declared. |
trait_metadata_count |
u32 |
Number of entries in trait_metadata. Zero when trait_metadata is null. |
construct |
Option<unsafe extern "C" fn(*const u8, u32) -> *mut c_void> |
Construct a plugin instance from serialized config bytes (FIDIUS-A-0006). cfg_ptr/cfg_len carry bincode of the plugin’s config type, or an empty slice for a zero-config plugin (singleton = construct-with-()). Returns an opaque, owning instance pointer the host passes to every vtable method and releases via destroy. Null = construction failed (e.g. a config deserialize error). |
destroy |
Option<unsafe extern "C" fn(*mut c_void)> |
Release an instance previously returned by construct. |
Methods
Section titled “Methods”interface_name_str
Section titled “interface_name_str”pub unsafe
unsafe fn interface_name_str(&self) -> &strRead the interface_name field as a Rust &str.
Safety
interface_name must point to a valid, null-terminated, UTF-8 C string
that outlives the returned reference.
Source
pub unsafe fn interface_name_str(&self) -> &str { let cstr = unsafe { std::ffi::CStr::from_ptr(self.interface_name) }; cstr.to_str().expect("interface_name is not valid UTF-8") }plugin_name_str
Section titled “plugin_name_str”pub unsafe
unsafe fn plugin_name_str(&self) -> &strRead the plugin_name field as a Rust &str.
Safety
plugin_name must point to a valid, null-terminated, UTF-8 C string
that outlives the returned reference.
Source
pub unsafe fn plugin_name_str(&self) -> &str { let cstr = unsafe { std::ffi::CStr::from_ptr(self.plugin_name) }; cstr.to_str().expect("plugin_name is not valid UTF-8") }buffer_strategy_kind
Section titled “buffer_strategy_kind”pub
fn buffer_strategy_kind(&self) -> Result<BufferStrategyKind, u8>Returns the buffer_strategy field as a BufferStrategyKind.
Returns Err(value) if the discriminant is unknown. This can happen
with malformed plugins — callers should reject rather than panic.
Source
pub fn buffer_strategy_kind(&self) -> Result<BufferStrategyKind, u8> { match self.buffer_strategy { 1 => Ok(BufferStrategyKind::PluginAllocated), 2 => Ok(BufferStrategyKind::Arena), v => Err(v), } }has_capability
Section titled “has_capability”pub
fn has_capability(&self, bit: u32) -> boolCheck if the given optional method capability bit is set.
Returns false for bit indices >= 64 rather than panicking.
Source
pub fn has_capability(&self, bit: u32) -> bool { if bit >= 64 { return false; } self.capabilities & (1u64 << bit) != 0 }struct DescriptorPtr
Section titled “struct DescriptorPtr”pub
A Sync wrapper for a raw pointer to a PluginDescriptor.
Used in static contexts where a *const PluginDescriptor needs to live
in a static variable (which requires Sync). The pointed-to descriptor
must have 'static lifetime.
Fields
Section titled “Fields”| Name | Type | Description |
|---|---|---|
0 |
*const PluginDescriptor |
enum BufferStrategyKind
Section titled “enum BufferStrategyKind”pub
Buffer management strategy for an interface.
Selected per-trait via #[plugin_interface(buffer = ...)].
Determines the FFI function pointer signatures in the vtable.
Discriminant value 0 is reserved (previously CallerAllocated, removed
in 0.1.0 — its value proposition was subsumed by PluginAllocated).
Variants
Section titled “Variants”-
PluginAllocated- Plugin allocates output; host frees viaPluginDescriptor::free_buffer. VTable fns:(in_ptr, in_len, out_ptr, out_len) -> i32. -
Arena- Host provides a pre-allocated arena buffer; plugin writes its serialized output into the buffer. ReturnsSTATUS_BUFFER_TOO_SMALL(with needed size written toout_len) if the arena is too small; host grows and retries. Data is valid only until the next call.VTable fns:
(in_ptr, in_len, arena_ptr, arena_cap, out_offset, out_len) -> i32.Arena is allocation-avoidance, not zero-copy. The plugin still serializes its output (bincode-encoded by default) and copies the bytes into the host-provided buffer; what Arena saves is the per-call
Box<[u8]>allocation that PluginAllocated incurs. For true byte passthrough — the bytes themselves cross the boundary without an encoding step — annotate the trait method with#[wire(raw)]. Raw wire mode composes with both buffer strategies.
Constants
Section titled “Constants”| Name | Type | Value | Description |
|---|---|---|---|
FIDIUS_MAGIC |
[u8; 8] |
*b"FIDIUS\0\0" |
Magic bytes identifying a Fidius plugin registry. |
REGISTRY_VERSION |
u32 |
1 |
Current version of the PluginRegistry struct layout. |
ABI_VERSION |
u32 |
if CRATE_MAJOR == 0 { CRATE_MAJOR * 10000 + CRATE_MINOR *... |
Current version of the PluginDescriptor struct layout. Derived from the fidius-core crate version per ADR-0002. |