wasm_link/
plugin.rs

1//! Plugin metadata types and traits.
2//!
3//! A plugin is a WASM component that implements one interface (its **plug**) and
4//! may depend on zero or more other interfaces (its **sockets**). The plug declares
5//! what the plugin exports; sockets declare what the plugin expects to import from
6//! other plugins.
7
8use wasmtime::Engine ;
9use wasmtime::component::{ Component, ResourceTable } ;
10
11/// Trait for accessing a [`ResourceTable`] from the store's data type.
12///
13/// Resources that flow between plugins need to be wrapped to track ownership.
14/// This trait provides access to the table where those wrapped resources are stored.
15///
16/// # Example
17///
18/// ```
19/// use wasmtime::component::ResourceTable ;
20/// use wasm_link::PluginCtxView ;
21///
22/// struct MyPluginData {
23///     resource_table: ResourceTable,
24///     // ... other fields
25/// }
26///
27/// impl PluginCtxView for MyPluginData {
28///     fn resource_table( &mut self ) -> &mut ResourceTable {
29///         &mut self.resource_table
30///     }
31/// }
32/// ```
33pub trait PluginCtxView {
34    /// Returns a mutable reference to the resource table.
35    fn resource_table( &mut self ) -> &mut ResourceTable ;
36}
37
38/// Trait for accessing plugin metadata and WASM binaries from a user-defined source.
39///
40/// Implement this trait to define how plugins are discovered, how their metadata
41/// is read, and how their WASM binaries are loaded.
42///
43/// Each plugin declares:
44/// - A **plug**: the interface it implements (what it exports)
45/// - Zero or more **sockets**: interfaces it depends on (what it imports)
46///
47/// During loading, the framework uses this information to build the dependency graph
48/// and link plugins together.
49///
50/// # Associated Types
51///
52/// - `Id`: Unique identifier type for plugins (e.g., `String`, `Uuid`, `PathBuf`)
53/// - `InterfaceId`: Must match the `Id` type used by your [`InterfaceData`]( crate::InterfaceData ) implementation
54/// - `Error`: The error type returned when metadata access or compilation fails
55/// - `SocketIter`: Iterator over the interface IDs this plugin depends on
56pub trait PluginData: Sized + Send + PluginCtxView {
57
58    /// A type used as a unique identifier for a plugin
59    type Id: Clone + std::hash::Hash + Eq + std::fmt::Debug + Send + Sync ;
60    /// A type used as a unique identifier for an interface
61    type InterfaceId: Clone + std::hash::Hash + Eq + std::fmt::Display ;
62    /// Error type for metadata access and compilation failures.
63    type Error: std::error::Error ;
64    /// Iterator over interface IDs this plugin depends on (its sockets).
65    type SocketIter<'a>: IntoIterator<Item = &'a Self::InterfaceId> where Self: 'a ;
66
67    /// Returns this plugin's unique identifier.
68    ///
69    /// # Errors
70    /// Implementations may fail if the underlying data source is unavailable.
71    fn id( &self ) -> Result<&Self::Id, Self::Error> ;
72
73    /// Returns the interface ID that this plugin implements (its plug).
74    ///
75    /// The plug declares which interface this plugin provides an implementation for.
76    /// The plugin must export all functions declared by this interface.
77    ///
78    /// # Errors
79    /// Implementations may fail if the underlying data source is unavailable.
80    fn plug( &self ) -> Result<&Self::InterfaceId, Self::Error> ;
81
82    /// Returns the interface IDs that this plugin depends on (its sockets).
83    ///
84    /// Each socket is an interface the plugin expects to call into. During linking,
85    /// these calls are wired to the plugin(s) implementing each interface.
86    ///
87    /// # Errors
88    /// Implementations may fail if the underlying data source is unavailable.
89    fn sockets( &self ) -> Result<Self::SocketIter<'_>, Self::Error> ;
90
91    /// Compiles this plugin's WASM binary into a wasmtime Component.
92    ///
93    /// Called during [`PluginTree::load`]( crate::PluginTree::load ) to compile the plugin. The implementation
94    /// is responsible for locating and reading the WASM binary.
95    ///
96    /// # Errors
97    /// May fail due to I/O errors reading the WASM source, or wasmtime compilation
98    /// errors if the binary is invalid or incompatible.
99    fn component( &self, engine: &Engine ) -> Result<Component, Self::Error> ;
100
101}
wasm_link/plugin.rs

wasm_link/
plugin.rs
