fidius-macro::host_interface
Rust
Code generation for #[host_interface] — the plugin → host callback channel (the reverse direction of #[plugin_interface]).
From one trait, generates both ends of the channel:
- Plugin side (
<Trait>Client+ companion statics): a once-bindable table cell, thebindshim the host installs aHostFunctionTablethrough (with defensive hash/version re-validation), aHostImportDescriptorregistered with the plugin’s host-import registry, and a typed client whose methods bincode-encode arguments and dispatch through the bound table. - Host side (
<Trait>Binding): a dispatch shim that decodes arguments, calls anArc<dyn Trait>implementation with a panic catch, and encodes results; plus bind entry points for dynamically loaded libraries (bind, feature"host") and in-process plugins (bind_in_process).
Both plugin runtimes are served: dylib plugins receive a
function-pointer table at bind time (gated at load), and wasm plugins
dispatch through the fidius:host-call component import (gated on every
call by the identity triple the client sends). The table/bind machinery
is #[cfg(not(target_family = "wasm"))]; the wasm client is
#[cfg(target_family = "wasm")]. See the macro’s rustdoc in lib.rs
for the threading/reentrancy contract.
Structs
Section titled “Structs”struct HostInterfaceAttrs
Section titled “struct HostInterfaceAttrs”pub
Parsed attributes from #[host_interface(version = N)].
Fields
Section titled “Fields”| Name | Type | Description |
|---|---|---|
version |
u32 |
|
crate_path |
Path |
Path to the fidius crate (crate = "my_crate::fidius"); defaults to fidius. |
Functions
Section titled “Functions”fn generate_host_interface
Section titled “fn generate_host_interface”pub
fn generate_host_interface( attrs: &HostInterfaceAttrs, item: &ItemTrait,) -> syn::Result<TokenStream>Generate all code for a #[host_interface] invocation.
Source
pub fn generate_host_interface( attrs: &HostInterfaceAttrs, item: &ItemTrait,) -> syn::Result<TokenStream> { let trait_name = &item.ident; let crate_path = &attrs.crate_path;
if !item.generics.params.is_empty() { return Err(syn::Error::new( item.generics.span(), "host interface traits cannot be generic", )); } // The table is shared across plugin threads: require the trait itself to // promise thread-safety, exactly like `#[plugin_interface]` traits do. let has_send = item .supertraits .iter() .any(|b| matches!(b, syn::TypeParamBound::Trait(t) if t.path.is_ident("Send"))); let has_sync = item .supertraits .iter() .any(|b| matches!(b, syn::TypeParamBound::Trait(t) if t.path.is_ident("Sync"))); if !has_send || !has_sync { return Err(syn::Error::new( item.ident.span(), "host interface traits must declare `Send + Sync` supertraits — plugin threads \ call host functions concurrently", )); }
let mut methods = Vec::new(); for trait_item in &item.items { if let TraitItem::Fn(m) = trait_item { methods.push(parse_method(m)?); } } if methods.is_empty() { return Err(syn::Error::new( item.ident.span(), "host interface traits must declare at least one method", )); }
let sigs: Vec<&str> = methods .iter() .map(|m| m.signature_string.as_str()) .collect(); let hash_value = fidius_core::hash::interface_hash(&sigs); let version_val = attrs.version; let fn_count = methods.len() as u32;
let companion_mod = format_ident!("__fidius_host_{}", trait_name); let hash_name = format_ident!("{}_HOST_INTERFACE_HASH", trait_name); let version_name = format_ident!("{}_HOST_INTERFACE_VERSION", trait_name); let count_name = format_ident!("{}_HOST_FN_COUNT", trait_name); let client_name = format_ident!("{}Client", trait_name); let binding_name = format_ident!("{}Binding", trait_name); let trait_name_str = trait_name.to_string();
// Per-method dispatch index constants. let index_consts: Vec<TokenStream> = methods .iter() .enumerate() .map(|(i, m)| { let const_name = format_ident!("HOST_FN_{}", m.name.to_string().to_uppercase()); let i = i as u32; let doc = format!("Dispatch index for `{}`.", m.name); quote! { #[doc = #doc] pub const #const_name: u32 = #i; } }) .collect();
// ── Host-side dispatch arms ───────────────────────────────────────────── let dispatch_arms: Vec<TokenStream> = methods .iter() .enumerate() .map(|(i, m)| { let i = i as u32; let mname = &m.name; let arg_names = &m.arg_names; let arg_types = &m.arg_types;
let output_handling = if m.result_ok.is_some() { quote! { match __output { ::core::result::Result::Ok(val) => { match #crate_path::wire::serialize(&val) { Ok(v) => (v, #crate_path::status::STATUS_OK), Err(_) => return #crate_path::status::STATUS_SERIALIZATION_ERROR, } } ::core::result::Result::Err(err) => { match #crate_path::wire::serialize(&err) { Ok(v) => (v, #crate_path::status::STATUS_PLUGIN_ERROR), Err(_) => return #crate_path::status::STATUS_SERIALIZATION_ERROR, } } } } } else { quote! { match #crate_path::wire::serialize(&__output) { Ok(v) => (v, #crate_path::status::STATUS_OK), Err(_) => return #crate_path::status::STATUS_SERIALIZATION_ERROR, } } };
quote! { #i => { let (#(#arg_names,)*) = match #crate_path::wire::deserialize::<(#(#arg_types,)*)>(__in_slice) { Ok(v) => v, Err(_) => return #crate_path::status::STATUS_SERIALIZATION_ERROR, }; let __output = __host.#mname(#(#arg_names),*); let (__bytes, __status) = #output_handling; let __boxed: ::std::boxed::Box<[u8]> = __bytes.into_boxed_slice(); let __len = __boxed.len(); let __ptr = ::std::boxed::Box::into_raw(__boxed) as *mut u8; unsafe { *out_ptr = __ptr; *out_len = __len as u32; } __status } } }) .collect();
// ── Plugin-side client methods ────────────────────────────────────────── let client_methods: Vec<TokenStream> = methods .iter() .enumerate() .map(|(i, m)| { let i = i as u32; let mname = &m.name; let arg_names = &m.arg_names; let arg_types = &m.arg_types; let ok_ty = match (&m.result_ok, &m.return_type) { (Some(ok), _) => quote! { #ok }, (None, Some(rt)) => quote! { #rt }, (None, None) => quote! { () }, }; let err_doc = if m.result_ok.is_some() { "A host-raised `PluginError` arrives as `HostCallError::Host`; " } else { "" }; let doc = format!( "Call the host's `{mname}`. {err_doc}transport-level failures \ (unbound interface, host panic, serialization) arrive as the other \ `HostCallError` variants." ); quote! { #[doc = #doc] pub fn #mname( &self, #(#arg_names: &#arg_types,)* ) -> ::std::result::Result<#ok_ty, #crate_path::host_ffi::HostCallError> { let __input = #crate_path::wire::serialize(&(#(#arg_names,)*)) .map_err(|e| #crate_path::host_ffi::HostCallError::Serialization(e.to_string()))?; let __out = #crate_path::host_ffi::call_host_fn(self.table, #i, &__input)?; #crate_path::wire::deserialize(&__out) .map_err(|e| #crate_path::host_ffi::HostCallError::Deserialization(e.to_string())) } } }) .collect();
// ── Plugin-side client methods, wasm variant ──────────────────────────── // Same signatures; dispatch goes through the `fidius:host-call` import, // carrying the identity triple so the host gates every call. let wasm_client_methods: Vec<TokenStream> = methods .iter() .enumerate() .map(|(i, m)| { let i = i as u32; let mname = &m.name; let arg_names = &m.arg_names; let arg_types = &m.arg_types; let ok_ty = match (&m.result_ok, &m.return_type) { (Some(ok), _) => quote! { #ok }, (None, Some(rt)) => quote! { #rt }, (None, None) => quote! { () }, }; let doc = format!( "Call the host's `{mname}` through the `fidius:host-call` import. \ The host gates the call on this interface's version + signature \ hash before dispatching." ); quote! { #[doc = #doc] pub fn #mname( &self, #(#arg_names: &#arg_types,)* ) -> ::std::result::Result<#ok_ty, #crate_path::host_ffi::HostCallError> { let __input = #crate_path::wire::serialize(&(#(#arg_names,)*)) .map_err(|e| #crate_path::host_ffi::HostCallError::Serialization(e.to_string()))?; let __out = #crate_path::host_call::call( #trait_name_str, #companion_mod::#version_name, #companion_mod::#hash_name, #i, &__input, )?; #crate_path::wire::deserialize(&__out) .map_err(|e| #crate_path::host_ffi::HostCallError::Deserialization(e.to_string())) } } }) .collect();
let cleaned_trait = strip_helper_attrs(item);
let client_doc = format!( "Typed plugin-side client for the `{trait_name_str}` host interface.\n\n\ Obtain with [`{client_name}::bound()`] from inside plugin code after the host \ has installed its function table (at plugin load/bind time). Calls are \ synchronous; see the `#[fidius::host_interface]` threading contract for what a \ host implementation may assume about the calling thread." ); let binding_doc = format!( "Host-side binding for the `{trait_name_str}` host interface.\n\n\ Wraps a host implementation (`Arc<dyn {trait_name_str}>`) in a C-ABI \ function table and installs it into a plugin. Each successful bind \ intentionally leaks one table and one `Arc` clone (a few dozen bytes, \ once per loaded library) so in-flight plugin calls can never observe a \ dangling table." );
Ok(quote! { #cleaned_trait
/// Generated companion module for the host interface (plugin → host /// callback channel): identity constants, the plugin-side table cell + /// bind shim + import descriptor, and the host-side dispatch machinery. #[allow(non_snake_case, non_upper_case_globals, dead_code)] pub mod #companion_mod { use super::*;
/// FNV-1a hash of this host interface's method signatures. pub const #hash_name: u64 = #hash_value; /// Declared `#[host_interface(version = N)]`. pub const #version_name: u32 = #version_val; /// Number of host functions in the table. pub const #count_name: u32 = #fn_count; #(#index_consts)*
const __FIDIUS_HOST_IFACE_NAME: &::std::ffi::CStr = unsafe { ::std::ffi::CStr::from_bytes_with_nul_unchecked( concat!(#trait_name_str, "\0").as_bytes(), ) };
// ── Plugin side ────────────────────────────────────────────────
/// The once-bindable cell holding the host's function table. #[cfg(not(target_family = "wasm"))] pub static __FIDIUS_HOST_TABLE: #crate_path::host_ffi::HostTableCell = #crate_path::host_ffi::HostTableCell::new();
/// Bind shim the host installs its table through. Re-validates /// ABI/hash/version/fn_count defensively before storing — a /// mismatched table can never become callable. #[cfg(not(target_family = "wasm"))] pub unsafe extern "C" fn __fidius_host_bind( table: *const #crate_path::host_ffi::HostFunctionTable, ) -> i32 { let result = ::std::panic::catch_unwind(|| { if table.is_null() { return #crate_path::host_ffi::BIND_ERR_NULL; } let t = unsafe { &*table }; if t.abi_version != #crate_path::descriptor::ABI_VERSION { return #crate_path::host_ffi::BIND_ERR_ABI; } if t.interface_hash != #hash_name { return #crate_path::host_ffi::BIND_ERR_HASH_MISMATCH; } if t.interface_version != #version_name { return #crate_path::host_ffi::BIND_ERR_VERSION_MISMATCH; } if t.fn_count != #count_name { return #crate_path::host_ffi::BIND_ERR_FN_COUNT; } // SAFETY: validated above; the table has process lifetime // per the HostFunctionTable contract. unsafe { __FIDIUS_HOST_TABLE.bind(table) } }); match result { ::core::result::Result::Ok(s) => s, ::core::result::Result::Err(_) => #crate_path::host_ffi::BIND_ERR_PANIC, } }
/// This plugin's declaration that it can consume the interface. #[cfg(not(target_family = "wasm"))] pub static HOST_IMPORT_DESCRIPTOR: #crate_path::host_ffi::HostImportDescriptor = #crate_path::host_ffi::HostImportDescriptor { descriptor_size: ::std::mem::size_of::< #crate_path::host_ffi::HostImportDescriptor, >() as u32, abi_version: #crate_path::descriptor::ABI_VERSION, interface_name: __FIDIUS_HOST_IFACE_NAME.as_ptr(), interface_hash: #hash_name, interface_version: #version_name, bind: __fidius_host_bind, };
// Advertise the import through the plugin's (optional) // `fidius_get_host_imports` export. #[cfg(not(target_family = "wasm"))] #crate_path::inventory::submit! { #crate_path::host_registry::HostImportEntry { descriptor: &HOST_IMPORT_DESCRIPTOR, } }
// ── Host side ──────────────────────────────────────────────────
#[cfg(not(target_family = "wasm"))] unsafe extern "C" fn __fidius_host_dispatch( ctx: *mut ::core::ffi::c_void, index: u32, in_ptr: *const u8, in_len: u32, out_ptr: *mut *mut u8, out_len: *mut u32, ) -> i32 { let result = ::std::panic::catch_unwind(::std::panic::AssertUnwindSafe(|| { let __depth = #crate_path::host_ffi::CallbackDepthGuard::new(); let __host: &::std::sync::Arc<dyn #trait_name> = unsafe { &*(ctx as *const ::std::sync::Arc<dyn #trait_name>) }; let __in_slice = unsafe { ::std::slice::from_raw_parts(in_ptr, in_len as usize) }; match index { #(#dispatch_arms)* _ => #crate_path::status::STATUS_INVALID_INDEX, } })); match result { ::core::result::Result::Ok(status) => status, ::core::result::Result::Err(panic_payload) => { let msg = panic_payload .downcast_ref::<&str>() .map(|s| s.to_string()) .or_else(|| panic_payload.downcast_ref::<String>().cloned()) .unwrap_or_else(|| "unknown panic".to_string()); if let Ok(msg_bytes) = #crate_path::wire::serialize(&msg) { let boxed: ::std::boxed::Box<[u8]> = msg_bytes.into_boxed_slice(); let len = boxed.len(); let ptr = ::std::boxed::Box::into_raw(boxed) as *mut u8; unsafe { *out_ptr = ptr; *out_len = len as u32; } } #crate_path::status::STATUS_PANIC } } }
#[cfg(not(target_family = "wasm"))] unsafe extern "C" fn __fidius_host_free(ptr: *mut u8, len: usize) { if !ptr.is_null() && len > 0 { // Reconstruct the Box<[u8]>: dispatch always allocates // output via into_boxed_slice, so cap == len. unsafe { let slice = ::std::slice::from_raw_parts_mut(ptr, len); drop(::std::boxed::Box::from_raw(slice as *mut [u8])); } } }
/// Build a process-lifetime `HostFunctionTable` wrapping `host`. /// The table and the boxed `Arc` are intentionally leaked. #[cfg(not(target_family = "wasm"))] pub fn __fidius_build_host_table( host: ::std::sync::Arc<dyn #trait_name>, ) -> *const #crate_path::host_ffi::HostFunctionTable { let ctx = ::std::boxed::Box::into_raw(::std::boxed::Box::new(host)) as *mut ::core::ffi::c_void; ::std::boxed::Box::into_raw(::std::boxed::Box::new( #crate_path::host_ffi::HostFunctionTable { table_size: ::std::mem::size_of::< #crate_path::host_ffi::HostFunctionTable, >() as u32, abi_version: #crate_path::descriptor::ABI_VERSION, interface_name: __FIDIUS_HOST_IFACE_NAME.as_ptr(), interface_hash: #hash_name, interface_version: #version_name, fn_count: #count_name, ctx, dispatch: __fidius_host_dispatch, free_buffer: __fidius_host_free, }, )) } }
#[doc = #client_doc] #[cfg(not(target_family = "wasm"))] pub struct #client_name { table: &'static #crate_path::host_ffi::HostFunctionTable, }
#[cfg(not(target_family = "wasm"))] impl #client_name { /// The bound host functions, or `HostCallError::NotBound` if the /// host application never installed a table for this interface. pub fn bound() -> ::std::result::Result<Self, #crate_path::host_ffi::HostCallError> { match #companion_mod::__FIDIUS_HOST_TABLE.get() { ::core::option::Option::Some(table) => Ok(Self { table }), ::core::option::Option::None => { Err(#crate_path::host_ffi::HostCallError::NotBound { interface: #trait_name_str, }) } } }
/// Whether the host has bound this interface. pub fn is_bound() -> bool { #companion_mod::__FIDIUS_HOST_TABLE.get().is_some() }
#(#client_methods)* }
#[doc = #binding_doc] #[cfg(not(target_family = "wasm"))] pub struct #binding_name;
#[cfg(not(target_family = "wasm"))] impl #binding_name { /// The interface's FNV-1a signature hash (what a plugin must have /// been built against for a bind to succeed). pub const INTERFACE_HASH: u64 = #companion_mod::#hash_name; /// The interface's declared version. pub const INTERFACE_VERSION: u32 = #companion_mod::#version_name; /// The interface (trait) name plugins import it under. pub const INTERFACE_NAME: &'static str = #trait_name_str;
/// Build a process-lifetime function table wrapping `host` (leaks /// one table + `Arc` clone). Prefer [`Self::bind`] / /// [`Self::bind_in_process`], which validate and install it. pub fn table( host: ::std::sync::Arc<dyn #trait_name>, ) -> *const #crate_path::host_ffi::HostFunctionTable { #companion_mod::__fidius_build_host_table(host) }
/// Bind `host` for a plugin linked into the current process (an /// in-process `#[plugin_impl]`, e.g. in tests). The dynamic-load /// path is [`Self::bind`]. pub fn bind_in_process( host: ::std::sync::Arc<dyn #trait_name>, ) -> ::std::result::Result<(), #crate_path::host_ffi::HostBindError> { let table = Self::table(host); // SAFETY: `table` is freshly built with process lifetime. let status = unsafe { #companion_mod::__fidius_host_bind(table) }; #crate_path::host_ffi::bind_status_to_result(#trait_name_str, status) }
/// Bind `host` into a dynamically loaded plugin library, gating on /// the host-interface version and signature hash the plugin was /// built against. /// /// Returns `Ok(true)` when the table was installed, `Ok(false)` /// when the plugin does not import this interface (older plugin, /// or one that simply doesn't use host functions) — callers that /// *require* the plugin to consume the interface should treat /// `false` as an error. A version or hash mismatch fails loudly /// with `LoadError::HostInterfaceVersionMismatch` / /// `LoadError::HostInterfaceHashMismatch` and installs nothing, /// so a mismatched surface can never mis-dispatch. #[cfg(feature = "host")] pub fn bind( library: &#crate_path::LoadedLibrary, host: ::std::sync::Arc<dyn #trait_name>, ) -> ::std::result::Result<bool, #crate_path::LoadError> { #crate_path::host_import::bind_host_interface( &library.library, #trait_name_str, #companion_mod::#hash_name, #companion_mod::#version_name, || Self::table(host), ) }
/// Like [`Self::bind`], for a `LoadedPlugin` (the value /// `PluginHost::load` returns). Binding is per-**library**: if a /// dylib contains several plugins they share the one table. #[cfg(feature = "host")] pub fn bind_plugin( plugin: &#crate_path::LoadedPlugin, host: ::std::sync::Arc<dyn #trait_name>, ) -> ::std::result::Result<bool, #crate_path::LoadError> { #crate_path::host_import::bind_host_interface( &plugin.library, #trait_name_str, #companion_mod::#hash_name, #companion_mod::#version_name, || Self::table(host), ) }
/// Bind `host` into a **WASM-backed** `PluginHandle` — the wasm /// variant of [`Self::bind`]. The guest dispatches host functions /// through the `fidius:host-call` import, which gates **every** /// call on this interface's version + signature hash (the wasm /// counterpart of the dylib bind-time gate): a plugin built /// against a different revision gets a typed /// `HostCallError::VersionMismatch` / `HashMismatch` on its first /// call, never a bincode mis-dispatch. Once-only per handle. /// /// Requires the interface crate's `host` and `wasm` features /// (forwarding to `fidius/host` + `fidius/wasm`). #[cfg(all(feature = "host", feature = "wasm"))] pub fn bind_wasm( handle: &#crate_path::PluginHandle, host: ::std::sync::Arc<dyn #trait_name>, ) -> ::std::result::Result<(), #crate_path::LoadError> { // SAFETY: `table` builds a fresh, intentionally-leaked // (process-lifetime) table — exactly the bind contract. unsafe { handle.bind_wasm_host_table(Self::table(host)) } } }
#[doc = #client_doc] #[cfg(target_family = "wasm")] pub struct #client_name { _priv: (), }
#[cfg(target_family = "wasm")] impl #client_name { /// The host functions, if the host bound a matching table. /// Probes the `fidius:host-call` import: an unbound interface /// returns `HostCallError::NotBound`; a host providing a /// different revision returns the typed /// `VersionMismatch`/`HashMismatch` error. pub fn bound() -> ::std::result::Result<Self, #crate_path::host_ffi::HostCallError> { #crate_path::host_call::probe( #trait_name_str, #companion_mod::#version_name, #companion_mod::#hash_name, )?; Ok(Self { _priv: () }) }
/// Whether the host has bound a matching table for this interface. pub fn is_bound() -> bool { #crate_path::host_call::probe( #trait_name_str, #companion_mod::#version_name, #companion_mod::#hash_name, ) .is_ok() }
#(#wasm_client_methods)* } })}