Plugins API Reference¶

This page is the precise API surface for loading plugins into a Uni instance. For the conceptual model see Concepts; for the permission model see Trust & Capabilities; for per-runtime loading guides see Loaders.

The Python load methods are instance-scoped: a plugin loaded through Uni / AsyncUni is visible to every session on that instance until the instance is dropped.

Python API¶

Both the sync Uni and async AsyncUni expose the same two load methods. They are gated behind the cargo features wasm-plugins (for load_wasm_component) and extism-plugins (for load_wasm_extism). The default wheel bundles wasmtime and ships both; some variant wheels omit one or both — if a method is absent at runtime, the wheel was built without the corresponding feature.

grants is an optional list of capability/grant variant names (see Capability names). When omitted it defaults to the surface grants ScalarFn, AggregateFn, Procedure. The same list drives both the surface-registration gate (which kinds the plugin may register) and the host-fn grant set (which capability-gated host imports are linked in).

def load_wasm_component(
    self,
    wasm_bytes: bytes,
    grants: list[str] | None = None,
) -> dict: ...

def load_wasm_extism(
    self,
    wasm_bytes: bytes,
    grants: list[str] | None = None,
) -> dict: ...

from uni_db import Uni

db = Uni.open("graph.uni")
outcome = db.load_wasm_component(
    wasm_bytes,
    grants=["ScalarFn", "AggregateFn"],
)
print(outcome["plugin_id"], outcome["scalars_registered"])

async def load_wasm_component(
    self,
    wasm_bytes: bytes,
    grants: list[str] | None = None,
) -> dict: ...

async def load_wasm_extism(
    self,
    wasm_bytes: bytes,
    grants: list[str] | None = None,
) -> dict: ...

from uni_db import AsyncUni

async with AsyncUni.open("graph.uni") as db:
    outcome = await db.load_wasm_component(
        wasm_bytes,
        grants=["ScalarFn"],
    )

Returned dict¶

Both methods return a dict with the following keys:

Rhai and Python (PyO3) loads¶

The Rhai and PyO3 loaders are also Python-callable, but on different objects and with different signatures from the two WASM methods above:

Session also exposes the decorator surface — @session.scalar_fn(...) / @session.aggregate_fn(...) / @session.procedure(...) plus session.finalize_plugin(plugin_id, version=None, grants=None) -> dict — as an alternative to loading from a source string. All of these return a dict with plugin_id, version, scalars_registered, aggregates_registered, procedures_registered, and denied_capabilities (note: no effective_capabilities key, unlike the two WASM methods). See Rhai and PyO3 for usage.

Rust host API¶

The Rust host owns the loaders explicitly: you construct a WasmLoader / ExtismLoader, pass the plugin bytes plus the grant list, and receive a LoadOutcome. host_grants gates which host fns are linked into the plugin's import table; registrar_caps gates which registration surfaces the plugin may use.

#[cfg(feature = "wasm-plugins")]
pub fn load_wasm_component(
    &self,
    loader: &uni_plugin_wasm::WasmLoader,
    bytes: &[u8],
    host_grants: &[String],
    registrar_caps: &uni_plugin::CapabilitySet,
) -> Result<uni_plugin_wasm::loader::LoadOutcome>;

#[cfg(feature = "extism-plugins")]
pub fn load_wasm_extism(
    &self,
    loader: &uni_plugin_extism::ExtismLoader,
    bytes: &[u8],
    host_grants: &[String],
    registrar_caps: &uni_plugin::CapabilitySet,
) -> Result<uni_plugin_extism::loader::LoadOutcome>;

For typed, in-process plugins use add_plugin:

pub fn add_plugin<P: uni_plugin::Plugin>(&self, plugin: P) -> Result<()>;

add_plugin is where the host signature trust policy is enforced today: the plugin's manifest is checked against the configured PluginTrustConfig before any registration runs. The default policy (SignaturePolicy::Disabled) accepts everything; RequireSigned rejects an unsigned manifest or one signed by an untrusted key. Compile-time built-in plugins are implicitly trusted.

The trust policy is set at build time:

pub fn plugin_trust(mut self, cfg: plugin_trust::PluginTrustConfig) -> Self;

let db = Uni::open("graph.uni")
    .plugin_trust(PluginTrustConfig::new(SignaturePolicy::RequireSigned, trust_root))
    .build()
    .await?;

See Trust & Capabilities for the full trust model.

LoadOutcome¶

uni_plugin_wasm::loader::LoadOutcome and uni_plugin_extism::loader::LoadOutcome share the same observable shape (the two differ only in the concrete instance-pool type, which is held internally to keep adapters alive):

The Python load methods project every field except pool into the returned dict.

Capability names¶

Grant strings (Python grants, Rust host_grants) and the entries in effective_capabilities / denied_capabilities use the variant names of uni_plugin::Capability. The authoritative set follows; see Trust & Capabilities for how declared capabilities, host grants, and the effective (intersected) set interact.

Host-import surfaces¶

These gate capability-backed host functions. Most carry attenuation data in Rust; as plain grant strings they request the variant.

Extension surfaces¶

These gate the registrar methods — which kinds of extension the plugin may register.

The Python load methods default to ScalarFn, AggregateFn, Procedure when grants is omitted.

Resource quotas¶

Quota variants carry a numeric bound.

Today FuelPerCall and MemoryBytes are enforced (Rhai from the granted capability; the WASM Component Model and Extism loaders from their manifest fields). The remaining quota variants are recognized but not yet enforced.

See also¶

• Concepts — the plugin model and lifecycle.
• Trust & Capabilities — the permission and trust model.
• Loaders — per-runtime loading guides.
• Authoring — writing your own plugin.
• Generated API docs: Python API, Rust API.