uni_plugin_extism/
lib.rs

1//! Extism loader for the uni-db plugin framework.
2//!
3//! `uni-plugin-extism` is the **user-facing** WASM loader. It sits
4//! parallel to `uni-plugin-wasm` (the Component Model loader). It follows
5//! the "Option C" hybrid pattern:
6//!
7//! - **Component Model** (`uni-plugin-wasm`) — typed WIT contracts,
8//!   capability gating by linker absence, used for the Lua-host, trusted
9//!   built-ins, and plugins where soundness is load-bearing.
10//! - **Extism** (this crate) — bytes-in / bytes-out, runtime-checked
11//!   capabilities, used for user-authored UDFs that benefit from
12//!   Extism's mature 13-language host SDK story.
13//!
14//! Trust is a property of the granted [`CapabilitySet`], not of which
15//! ABI a plugin happens to use. A user can author a "trusted" plugin in
16//! Extism by granting it broad capabilities; a built-in can author
17//! against Extism if the structural advantages of CM aren't load-bearing
18//! for its use case. The framework intentionally decouples ABI choice
19//! from trust tier.
20//!
21//! # Crate status
22//!
23//! Loader is wired through the `extism-sdk`. `ExtismLoader::load` runs a
24//! two-pass instantiation (manifest probe, then plugin build) and
25//! surfaces failures as [`ExtismError::Instantiate`]. The host-fn
26//! registration surface ([`HostFnRegistry`]) and capability gating model
27//! are in place; the `NotYetImplemented` placeholder has been retired.
28//!
29//! # Why two WASM loaders
30//!
31//! The proposal's loader matrix (§5.1) keeps the four authoring
32//! categories (compile-time Rust, WASM, PyO3, Lua) but splits the WASM
33//! row into two ABIs. Both ABIs converge on the same `PluginRegistrar`
34//! — the executor cannot tell whether a registered `ScalarPluginFn` was
35//! authored against WIT or Extism. The two loaders share the wasmtime
36//! runtime (Extism is itself wasmtime-backed), so the runtime cost is
37//! one wasmtime process, not two.
38//!
39//! [`CapabilitySet`]: uni_plugin::CapabilitySet
40
41// Rust guideline compliant
42#![warn(missing_docs)]
43#![warn(rust_2018_idioms)]
44#![warn(missing_debug_implementations)]
45
46pub mod error;
47pub mod host_fns;
48
49/// Arrow IPC bridge — re-exported from `uni-plugin-wasm-rt`.
50///
51/// Lifted to the shared crate in M6.shared. The public API
52/// (`encode_batch`, `decode_batch`, `encode_batches`, `decode_batches`)
53/// stays at `uni_plugin_extism::ipc::*` for backwards-compatibility;
54/// the implementation lives once, in `uni-plugin-wasm-rt`.
55pub mod ipc {
56    pub use uni_plugin_wasm_rt::ipc::{decode_batch, decode_batches, encode_batch, encode_batches};
57}
58
59#[cfg(feature = "extism-runtime")]
60pub mod adapter;
61#[cfg(feature = "extism-runtime")]
62pub mod adapter_aggregate;
63#[cfg(feature = "extism-runtime")]
64pub mod adapter_common;
65#[cfg(feature = "extism-runtime")]
66pub mod adapter_procedure;
67
68/// Instance pool — re-exported from `uni-plugin-wasm-rt`.
69///
70/// Type-aliased so `ExtismInstancePool<extism::Plugin>` and
71/// `PooledInstance<extism::Plugin>` keep working unchanged downstream.
72#[cfg(feature = "extism-runtime")]
73pub mod pool {
74    pub use uni_plugin_wasm_rt::pool::{PoolConfig, PoolMetrics};
75
76    /// Type alias — generic `InstancePool` parameterized with
77    /// [`crate::ExtismError`].
78    pub type ExtismInstancePool<T> = uni_plugin_wasm_rt::pool::InstancePool<T, crate::ExtismError>;
79
80    /// Type alias — generic `PooledInstance` parameterized with
81    /// [`crate::ExtismError`].
82    pub type PooledInstance<T> = uni_plugin_wasm_rt::pool::PooledInstance<T, crate::ExtismError>;
83}
84#[cfg(feature = "extism-runtime")]
85pub mod exports;
86#[cfg(feature = "extism-runtime")]
87pub mod host_svc;
88#[cfg(feature = "extism-runtime")]
89pub mod loader;
90#[cfg(feature = "extism-runtime")]
91pub mod wire_translate;
92
93#[doc(inline)]
94pub use error::ExtismError;
95#[doc(inline)]
96pub use host_fns::HostFnRegistry;
97
98#[cfg(feature = "extism-runtime")]
99#[doc(inline)]
100pub use adapter::ExtismScalarFn;
101#[cfg(feature = "extism-runtime")]
102#[doc(inline)]
103pub use adapter_aggregate::ExtismAggregateFn;
104#[cfg(feature = "extism-runtime")]
105#[doc(inline)]
106pub use adapter_procedure::ExtismProcedure;
107#[cfg(feature = "extism-runtime")]
108#[doc(inline)]
109pub use exports::{
110    RegistrationEntry, RegistrationManifest, WireArgType, WireFnSignature, parse_manifest_json,
111    parse_registration_json, read_manifest_export, read_register_export,
112};
113#[cfg(feature = "extism-runtime")]
114#[doc(inline)]
115pub use host_svc::register_default_host_svc;
116#[cfg(feature = "extism-runtime")]
117#[doc(inline)]
118pub use loader::ExtismLoader;
119#[cfg(feature = "extism-runtime")]
120#[doc(inline)]
121pub use wire_translate::{
122    arrow_name_to_datatype, wire_arg_to_internal, wire_fn_sig_to_internal,
123    wire_null_handling_to_internal, wire_volatility_to_internal,
124};
uni_plugin_extism/lib.rs

uni_plugin_extism/
lib.rs
