fidius-host::host
Rust
PluginHost builder and plugin discovery.
Structs
Section titled “Structs”struct PluginHost
Section titled “struct PluginHost”pub
Host for loading and managing plugins.
Methods
Section titled “Methods”builder
Section titled “builder”pub
fn builder() -> PluginHostBuilderCreate a new builder.
Source
pub fn builder() -> PluginHostBuilder { PluginHostBuilder::new() }discover
Section titled “discover”pub
fn discover(&self) -> Result<Vec<PluginInfo>, LoadError>Discover all valid plugins in the configured search paths.
Scans each path for both:
- dylib files (cdylib plugins, the existing path), and
- subdirectories containing a
package.tomlwithruntime = "python"(when thepythonfeature is enabled).
Returns owned PluginInfo for every valid plugin found, with
PluginInfo::runtime distinguishing the two kinds.
Source
pub fn discover(&self) -> Result<Vec<PluginInfo>, LoadError> { #[cfg(feature = "tracing")] tracing::info!(search_paths = ?self.search_paths, "discovering plugins");
let mut plugins = Vec::new();
for search_path in &self.search_paths { if !search_path.is_dir() { continue; }
let entries = std::fs::read_dir(search_path)?; for entry in entries { let entry = entry?; let path = entry.path();
if is_dylib(&path) { self.discover_cdylib(&path, &mut plugins); } else if path.is_dir() && path.join("package.toml").exists() { self.discover_package(&path, &mut plugins); } } }
Ok(plugins) }pub
fn load(&self, name: &str) -> Result<LoadedPlugin, LoadError>Load a specific plugin by name.
Searches all configured paths for a dylib containing a plugin with the given name. Returns the loaded plugin ready for calling.
Source
pub fn load(&self, name: &str) -> Result<LoadedPlugin, LoadError> { #[cfg(feature = "tracing")] tracing::info!(plugin_name = name, "loading plugin");
for search_path in &self.search_paths { if !search_path.is_dir() { continue; }
let entries = std::fs::read_dir(search_path)?; for entry in entries { let entry = entry?; let path = entry.path();
if !is_dylib(&path) { continue; }
// Verify signature if required — always enforced regardless of LoadPolicy if self.require_signature { signing::verify_signature(&path, &self.trusted_keys)?; }
match loader::load_library(&path) { Ok(loaded) => { for plugin in loaded.plugins { if plugin.info.name == name { loader::validate_against_interface( &plugin, self.expected_hash, self.expected_strategy, )?; return Ok(plugin); } } } Err(_) => continue, } } }
Err(LoadError::PluginNotFound { name: name.to_string(), }) }find_python_package
Section titled “find_python_package”pub
fn find_python_package(&self, name: &str) -> Result<PathBuf, LoadError>Find a python plugin package directory by name across the configured search paths. The plugin name is matched against package.toml’s [package].name. Returns the directory path on success.
Source
pub fn find_python_package(&self, name: &str) -> Result<PathBuf, LoadError> { for search_path in &self.search_paths { if !search_path.is_dir() { continue; } let entries = std::fs::read_dir(search_path)?; for entry in entries { let entry = entry?; let path = entry.path(); if !path.is_dir() { continue; } if !path.join("package.toml").exists() { continue; } let Ok(manifest) = fidius_core::package::load_manifest_untyped(&path) else { continue; }; if matches!( manifest.package.runtime(), fidius_core::package::PackageRuntime::Python ) && manifest.package.name == name { return Ok(path); } } } Err(LoadError::PluginNotFound { name: name.to_string(), }) }load_python
Section titled “load_python”pub
fn load_python( &self, name: &str, descriptor: &'static fidius_core::python_descriptor::PythonInterfaceDescriptor,) -> Result<crate::handle::PluginHandle, LoadError>Load a Python plugin package by name and validate it against the supplied interface descriptor.
The caller passes the static <TraitName>_PYTHON_DESCRIPTOR emitted
by the interface crate’s #[plugin_interface] macro — that’s the
out-of-band hint the loader needs to map method names to vtable
indices and to check the interface hash.
Available only when fidius-host is built with the python feature.
Source
pub fn load_python( &self, name: &str, descriptor: &'static fidius_core::python_descriptor::PythonInterfaceDescriptor, ) -> Result<crate::handle::PluginHandle, LoadError> { let dir = self.find_python_package(name)?; // Signature policy — enforced identically to cdylib/WASM loads. if self.require_signature { signing::verify_package_signature(&dir, &self.trusted_keys)?; } let manifest = fidius_core::package::load_manifest_untyped(&dir) .map_err(|e| LoadError::PythonLoad(e.to_string()))?; let py = fidius_python::load_python_plugin(&dir, descriptor) .map_err(|e| LoadError::PythonLoad(e.to_string()))?; // Build the host-facing metadata from the manifest header + the // interface descriptor. `capabilities`/`buffer_strategy` are cdylib // concepts and take their no-op defaults for Python. let info = crate::types::PluginInfo { name: manifest.package.name.clone(), interface_name: descriptor.interface_name.to_string(), interface_hash: descriptor.interface_hash, interface_version: manifest.package.interface_version, capabilities: 0, buffer_strategy: fidius_core::descriptor::BufferStrategyKind::PluginAllocated, runtime: crate::types::PluginRuntimeKind::Python, }; Ok(crate::handle::PluginHandle::from_python(py, info)) }load_python_configured
Section titled “load_python_configured”pub
fn load_python_configured<C: serde::Serialize>( &self, name: &str, descriptor: &'static fidius_core::python_descriptor::PythonInterfaceDescriptor, config: &C,) -> Result<crate::handle::PluginHandle, LoadError>Load a configured Python plugin (FIDIUS-A-0006 / CI.4): serialize config and bind it once via the module’s __fidius_configure__(config) -> instance; methods then run on the configured instance. N differently-configured instances coexist. Available only with the python feature.
Source
pub fn load_python_configured<C: serde::Serialize>( &self, name: &str, descriptor: &'static fidius_core::python_descriptor::PythonInterfaceDescriptor, config: &C, ) -> Result<crate::handle::PluginHandle, LoadError> { let dir = self.find_python_package(name)?; if self.require_signature { signing::verify_package_signature(&dir, &self.trusted_keys)?; } let manifest = fidius_core::package::load_manifest_untyped(&dir) .map_err(|e| LoadError::PythonLoad(e.to_string()))?; let cfg = serde_json::to_value(config) .map_err(|e| LoadError::PythonLoad(format!("config serialize: {e}")))?; let py = fidius_python::load_python_plugin_configured(&dir, descriptor, &cfg) .map_err(|e| LoadError::PythonLoad(e.to_string()))?; let info = crate::types::PluginInfo { name: manifest.package.name.clone(), interface_name: descriptor.interface_name.to_string(), interface_hash: descriptor.interface_hash, interface_version: manifest.package.interface_version, capabilities: 0, buffer_strategy: fidius_core::descriptor::BufferStrategyKind::PluginAllocated, runtime: crate::types::PluginRuntimeKind::Python, }; Ok(crate::handle::PluginHandle::from_python(py, info)) }find_wasm_package
Section titled “find_wasm_package”pub
fn find_wasm_package(&self, name: &str) -> Result<PathBuf, LoadError>Find a WASM package directory by name across the search paths (matches package.toml [package].name with runtime = "wasm").
Source
pub fn find_wasm_package(&self, name: &str) -> Result<PathBuf, LoadError> { for search_path in &self.search_paths { if !search_path.is_dir() { continue; } for entry in std::fs::read_dir(search_path)? { let entry = entry?; let path = entry.path(); if !path.is_dir() || !path.join("package.toml").exists() { continue; } let Ok(manifest) = fidius_core::package::load_manifest_untyped(&path) else { continue; }; if matches!( manifest.package.runtime(), fidius_core::package::PackageRuntime::Wasm ) && manifest.package.name == name { return Ok(path); } } } Err(LoadError::PluginNotFound { name: name.to_string(), }) }load_wasm
Section titled “load_wasm”pub
fn load_wasm( &self, name: &str, descriptor: &'static fidius_core::wasm_descriptor::WasmInterfaceDescriptor,) -> Result<crate::handle::PluginHandle, LoadError>Load a WASM component plugin package by name and validate it against the supplied interface descriptor (the <TraitName>_WASM_DESCRIPTOR the interface crate emits). Returns a unified crate::handle::PluginHandle.
The component is sandboxed: WASI is wired into the Linker but the guest
gets a zero-grant WasiCtx (no FS preopens, no env, no sockets). The
capability allow-list in [wasm].capabilities is applied in T-0104.
Outbound HTTP is governed by the host’s egress policy: a guest that
declares the http capability gets wasi:http only when the host was
given a policy (via PluginHostBuilder::egress or
Self::load_wasm_with_egress) — otherwise it fails closed.
Available only with the wasm feature.
Source
pub fn load_wasm( &self, name: &str, descriptor: &'static fidius_core::wasm_descriptor::WasmInterfaceDescriptor, ) -> Result<crate::handle::PluginHandle, LoadError> { self.load_wasm_impl(name, descriptor, self.egress.clone(), None, None) }load_wasm_configured
Section titled “load_wasm_configured”pub
fn load_wasm_configured<C: serde::Serialize>( &self, name: &str, descriptor: &'static fidius_core::wasm_descriptor::WasmInterfaceDescriptor, config: &C,) -> Result<crate::handle::PluginHandle, LoadError>Load a configured WASM plugin (FIDIUS-A-0006 / CI.3): serialize config and bind it once via the guest’s fidius-configure export. The component then runs on a persistent store, so methods dispatch on the configured instance and config crosses the sandbox boundary exactly once. Available only with the wasm feature.
Source
pub fn load_wasm_configured<C: serde::Serialize>( &self, name: &str, descriptor: &'static fidius_core::wasm_descriptor::WasmInterfaceDescriptor, config: &C, ) -> Result<crate::handle::PluginHandle, LoadError> { let cfg = fidius_core::wire::serialize(config) .map_err(|e| LoadError::WasmLoad(format!("config serialize: {e}")))?; self.load_wasm_impl(name, descriptor, self.egress.clone(), Some(&cfg), None) }load_wasm_configured_with_grants
Section titled “load_wasm_configured_with_grants”pub
fn load_wasm_configured_with_grants<C: serde::Serialize>( &self, name: &str, descriptor: &'static fidius_core::wasm_descriptor::WasmInterfaceDescriptor, config: &C, capabilities: Vec<String>, egress: Option<Arc<dyn crate::executor::wasm::EgressPolicy>>,) -> Result<crate::handle::PluginHandle, LoadError>Load a configured WASM plugin with a caller-supplied capability allow-list and egress policy, overriding the package manifest’s [wasm].capabilities (FIDIUS-I-0033 / cloacina constructor grants).
This is the entry point for embedders that authorize a plugin’s host
access at load time rather than trusting the (signed-but-author-chosen)
manifest caps — e.g. cloacina’s tenant-granted constructor capabilities,
where the filesystem path / env key / http+tcp intent are decided by the
deploying tenant, not the plugin author. capabilities fully replaces
the manifest list (it is not merged): pass exactly what the tenant
granted. Default-closed falls out naturally — an empty capabilities
builds a zero-grant WasiCtx, and egress: None denies all brokered
HTTP/TCP (the two-key gate’s host key is absent).
capabilities uses the same vocabulary as [wasm].capabilities
(http, tcp, udp, network/sockets, fs:ro:<path>/fs:rw:<path>,
env:<NAME>, …) and is validated identically; an unknown or coarse
(env / fs) entry fails the load.
Available only with the wasm feature.
Source
pub fn load_wasm_configured_with_grants<C: serde::Serialize>( &self, name: &str, descriptor: &'static fidius_core::wasm_descriptor::WasmInterfaceDescriptor, config: &C, capabilities: Vec<String>, egress: Option<Arc<dyn crate::executor::wasm::EgressPolicy>>, ) -> Result<crate::handle::PluginHandle, LoadError> { let cfg = fidius_core::wire::serialize(config) .map_err(|e| LoadError::WasmLoad(format!("config serialize: {e}")))?; self.load_wasm_impl(name, descriptor, egress, Some(&cfg), Some(capabilities)) }load_wasm_with_egress
Section titled “load_wasm_with_egress”pub
fn load_wasm_with_egress( &self, name: &str, descriptor: &'static fidius_core::wasm_descriptor::WasmInterfaceDescriptor, egress: impl crate::executor::wasm::EgressPolicy,) -> Result<crate::handle::PluginHandle, LoadError>Like Self::load_wasm but with a per-plugin wasi:http egress policy that overrides any host-wide default (FIDIUS-I-0027). This is the right primitive for isolating connectors: a host-wide policy only sees the outbound request, not which plugin issued it, so per-plugin policies are how you bound connector A to one set of hosts and connector B to another.
Source
pub fn load_wasm_with_egress( &self, name: &str, descriptor: &'static fidius_core::wasm_descriptor::WasmInterfaceDescriptor, egress: impl crate::executor::wasm::EgressPolicy, ) -> Result<crate::handle::PluginHandle, LoadError> { self.load_wasm_impl(name, descriptor, Some(Arc::new(egress)), None, None) }struct PluginHostBuilder
Section titled “struct PluginHostBuilder”pub
Builder for configuring a PluginHost.
Methods
Section titled “Methods”egress
Section titled “egress”pub
fn egress( mut self, policy: impl crate::executor::wasm::EgressPolicy,) -> SelfSet a host-wide default wasi:http egress policy (FIDIUS-I-0027). Every load_wasm then enables outbound HTTP for a guest that declares the http capability, routing each request through policy. Without this (and without a per-load policy), wasi:http is never linked and a guest that imports it fails closed. Available only with the wasm feature.
Source
pub fn egress(mut self, policy: impl crate::executor::wasm::EgressPolicy) -> Self { self.egress = Some(Arc::new(policy)); self }egress_policy
Section titled “egress_policy”pub
fn egress_policy( mut self, policy: Arc<dyn crate::executor::wasm::EgressPolicy>,) -> SelfLike Self::egress but accepts an already-erased Arc<dyn EgressPolicy> — for a policy that is shared across hosts, or selected/constructed at runtime (where the concrete type isn’t known at the call site). Threads through load_wasm exactly like egress. Available only with the wasm feature.
Source
pub fn egress_policy(mut self, policy: Arc<dyn crate::executor::wasm::EgressPolicy>) -> Self { self.egress = Some(policy); self }search_path
Section titled “search_path”pub
fn search_path(mut self, path: impl Into<PathBuf>) -> SelfAdd a directory to search for plugin dylibs.
Source
pub fn search_path(mut self, path: impl Into<PathBuf>) -> Self { self.search_paths.push(path.into()); self }load_policy
Section titled “load_policy”pub
fn load_policy(mut self, policy: LoadPolicy) -> SelfSet the load policy (Strict or Lenient).
Source
pub fn load_policy(mut self, policy: LoadPolicy) -> Self { self.load_policy = policy; self }require_signature
Section titled “require_signature”pub
fn require_signature(mut self, require: bool) -> SelfRequire plugins to have valid signatures.
Source
pub fn require_signature(mut self, require: bool) -> Self { self.require_signature = require; self }trusted_keys
Section titled “trusted_keys”pub
fn trusted_keys(mut self, keys: &[VerifyingKey]) -> SelfSet trusted Ed25519 public keys for signature verification.
Source
pub fn trusted_keys(mut self, keys: &[VerifyingKey]) -> Self { self.trusted_keys = keys.to_vec(); self }interface_hash
Section titled “interface_hash”pub
fn interface_hash(mut self, hash: u64) -> SelfSet the expected interface hash for validation.
Source
pub fn interface_hash(mut self, hash: u64) -> Self { self.expected_hash = Some(hash); self }buffer_strategy
Section titled “buffer_strategy”pub
fn buffer_strategy(mut self, strategy: BufferStrategyKind) -> SelfSet the expected buffer strategy for validation.
Source
pub fn buffer_strategy(mut self, strategy: BufferStrategyKind) -> Self { self.expected_strategy = Some(strategy); self }pub
fn build(self) -> Result<PluginHost, LoadError>Build the PluginHost.
Source
pub fn build(self) -> Result<PluginHost, LoadError> { Ok(PluginHost { search_paths: self.search_paths, load_policy: self.load_policy, require_signature: self.require_signature, trusted_keys: self.trusted_keys, expected_hash: self.expected_hash, expected_strategy: self.expected_strategy, #[cfg(feature = "wasm")] egress: self.egress, }) }