Crate fidius 

Fidius — a Rust plugin framework for trait-to-dylib plugin systems.

This is the facade crate. Interface crates should depend on fidius only. It re-exports everything needed to define interfaces and implement plugins.

For interface crate authors

pub use fidius::{plugin_impl, PluginError};

#[fidius::plugin_interface(version = 1, buffer = PluginAllocated)]
pub trait MyPlugin: Send + Sync {
    fn process(&self, input: String) -> String;
}

For plugin crate authors

use my_interface::{plugin_impl, MyPlugin, PluginError};

pub struct MyImpl;

#[plugin_impl(MyPlugin)]
impl MyPlugin for MyImpl {
    fn process(&self, input: String) -> String {
        format!("processed: {input}")
    }
}

fidius::fidius_plugin_registry!();

What fidius does not provide: timeouts and cancellation

Fidius has no built-in timeout, deadline, or cancellation mechanism for plugin method calls. A call to PluginHandle::call_method (or call_method_raw) runs to completion, panics, or — in the case of a truly stuck plugin — never returns. There is no PluginError::Timeout variant and the framework will not interrupt a misbehaving plugin.

This is a deliberate consequence of the cdylib + in-process architecture: plugin code runs synchronously on the host’s calling thread, and Rust cannot safely interrupt a thread mid-FFI-call. Any honest timeout implementation requires running the plugin in a separate, killable process — out of scope for the current framework.

If your threat model includes runaway plugins, you must add a watchdog yourself. The usual pattern is to run the host process itself with a supervisor that can SIGKILL it on deadline; per-call timeouts inside a single host process are not safely achievable for arbitrary plugin code.

Future work: the fidius-python initiative is the natural carrier for a real subprocess-isolated execution tier, which would be the only path by which fidius could grow first-class timeout semantics.

Re-exports

pub use fidius_core::inventory;

Modules

descriptor

FFI descriptor and registry types for the Fidius plugin framework.

error

Error types for the Fidius plugin framework.

hash

FNV-1a interface hashing for compile-time ABI drift detection.

python_descriptor

Compile-time descriptor of a fidius interface used by the Python loader.

registry

Plugin registry assembly for multi-plugin dylibs.

status

FFI status codes returned by plugin method shims.

stream_ffi

cdylib server-streaming FFI handle (FIDIUS-I-0026 Phase 3 / CS.1, T-0138).

stream_marker

The fidius::Stream<T> server-streaming return marker (FIDIUS-I-0026, D4).

wasm_descriptor

Compile-time descriptor of a fidius interface used by the WASM loader.

wire

Wire format serialization for Fidius plugin FFI boundary.

Macros

fidius_plugin_registry

Emit the fidius_get_registry export function.

Structs

PluginDescriptor

Metadata descriptor for a single plugin within a dylib.

PluginError

Error returned by plugin method implementations to signal business logic failures.

PluginRegistry

Top-level registry exported by every Fidius plugin dylib.

Stream

The fidius::Stream<T> server-streaming return marker — write it as a method’s return type in a #[plugin_interface] trait to declare a server-streaming method. See fidius_core::stream_marker::Stream. Marker type a plugin interface uses to declare a server-streaming method:

ValueError

The neutral value model + (de)serialization helpers host consumers use to decode ChunkStream items and dynamic Values. Error produced while converting to or from Value.

Enums

BufferStrategyKind

Buffer management strategy for an interface.

Value

The neutral value model + (de)serialization helpers host consumers use to decode ChunkStream items and dynamic Values. A self-describing value crossing the plugin-call boundary.

Constants

ABI_VERSION

Current version of the PluginDescriptor struct layout. Derived from the fidius-core crate version per ADR-0002.

FIDIUS_MAGIC

Magic bytes identifying a Fidius plugin registry.

REGISTRY_VERSION

Current version of the PluginRegistry struct layout.

Functions

fnv1a

Compute the FNV-1a 64-bit hash of a byte slice.

from_value

The neutral value model + (de)serialization helpers host consumers use to decode ChunkStream items and dynamic Values. Convert a Value into any Deserialize type.

interface_hash

Compute the interface hash from a set of method signatures.

to_value

The neutral value model + (de)serialization helpers host consumers use to decode ChunkStream items and dynamic Values. Convert any Serialize type into a Value.

Attribute Macros

plugin_impl

Implement a plugin interface for a concrete type.

plugin_interface

Define a plugin interface from a trait.