wasm_link/
binding.rs

1//! Binding specification and metadata types.
2//!
3//! A [`Binding`] defines an abstract contract specifying what plugins must implement
4//! (via plugs) or what they could depend on (via sockets). It bundles one or more WIT
5//! [`Interface`]s under a single identifier.
6
7use std::sync::{ Arc, Mutex };
8use std::collections::HashMap ;
9use wasmtime::component::{ Linker, Val };
10
11use crate::{ Interface, PluginContext };
12use crate::cardinality::{ Any, AtLeastOne, AtMostOne, Cardinality, ExactlyOne };
13use crate::plugin_instance::PluginInstance ;
14
15
16
17type PluginSockets<PluginId, Ctx, Plugins> =
18	<Plugins as Cardinality<PluginId, PluginInstance<Ctx>>>::Rebind<Mutex<PluginInstance<Ctx>>> ;
19
20type DispatchResults<PluginId, Ctx, Plugins> =
21	<PluginSockets<PluginId, Ctx, Plugins> as Cardinality<PluginId, Mutex<PluginInstance<Ctx>>>>::Rebind<
22		Result<wasmtime::component::Val, crate::DispatchError>
23	>;
24
25type DispatchVals<PluginId, Ctx, Plugins> =
26	<PluginSockets<PluginId, Ctx, Plugins> as Cardinality<PluginId, Mutex<PluginInstance<Ctx>>>>::Rebind<
27		wasmtime::component::Val
28	>;
29
30struct BindingData<PluginId, Ctx, Plugins>
31where
32	PluginId: std::hash::Hash + Eq + Clone + Send + Sync + 'static,
33	Ctx: PluginContext + 'static,
34	Plugins: Cardinality<PluginId, PluginInstance<Ctx>>,
35	PluginSockets<PluginId, Ctx, Plugins>: Send + Sync,
36{
37	package_name: String,
38	interfaces: HashMap<String, Interface>,
39	plugins: PluginSockets<PluginId, Ctx, Plugins>,
40}
41
42/// An abstract contract specifying what plugins must implement (via plugs) or what
43/// they could depend on (via sockets). It bundles one or more WIT [`Interface`]s
44/// under a single package name.
45///
46/// `Binding` is a handle to shared state. Cloning a `Binding` creates another handle
47/// to the same underlying binding, enabling shared dependencies where multiple
48/// plugins depend on the same binding.
49///
50/// ```
51/// # use std::collections::{ HashMap, HashSet };
52/// # use wasm_link::{ Binding, Interface, Function, FunctionKind, ReturnKind, Plugin, Engine, Component, Linker, ResourceTable };
53/// # use wasm_link::cardinality::ExactlyOne ;
54/// # struct Ctx { resource_table: ResourceTable }
55/// # impl wasm_link::PluginContext for Ctx {
56/// # 	fn resource_table( &mut self ) -> &mut ResourceTable { &mut self.resource_table }
57/// # }
58/// # fn example() -> Result<(), Box<dyn std::error::Error>> {
59/// # let engine = Engine::default();
60/// # let linker = Linker::new( &engine );
61/// # let plugin = Plugin::new( Component::new( &engine, "(component)" )?, Ctx { resource_table: ResourceTable::new() }).instantiate( &engine, &linker )?;
62/// let binding: Binding<String, Ctx> = Binding::new(
63/// 	"my:package",
64/// 	HashMap::from([
65/// 		( "api".to_string(), Interface::new(
66/// 			HashMap::from([( "get-value".into(), Function::new(
67/// 				FunctionKind::Freestanding,
68/// 				ReturnKind::MayContainResources,
69/// 			))]),
70/// 			HashSet::from([ "my-resource".to_string() ]),
71/// 		)),
72/// 	]),
73/// 	ExactlyOne( "my-plugin".to_string(), plugin ),
74/// );
75///
76/// // Clone for shared dependencies - both refer to the same binding
77/// let binding_clone = binding.clone();
78/// # Ok(())
79/// # }
80/// ```
81///
82/// # Type Parameters
83/// - `PluginId`: Unique identifier type for plugins (e.g., `String`, `UUID`)
84pub struct Binding<PluginId, Ctx, Plugins = ExactlyOne<PluginId, PluginInstance<Ctx>>>(Arc<BindingData<PluginId, Ctx, Plugins>>)
85where
86	PluginId: std::hash::Hash + Eq + Clone + Send + Sync + 'static,
87	Ctx: PluginContext + 'static,
88	Plugins: Cardinality<PluginId, PluginInstance<Ctx>> + 'static,
89	PluginSockets<PluginId, Ctx, Plugins>: Send + Sync;
90
91impl<PluginId, Ctx, Plugins> Clone for Binding<PluginId, Ctx, Plugins>
92where
93	PluginId: std::hash::Hash + Eq + Clone + Send + Sync + 'static,
94	Ctx: PluginContext + 'static,
95	Plugins: Cardinality<PluginId, PluginInstance<Ctx>> + 'static,
96	PluginSockets<PluginId, Ctx, Plugins>: Send + Sync,
97{
98	fn clone( &self ) -> Self {
99		Self( Arc::clone( &self.0 ))
100	}
101}
102
103impl<PluginId, Ctx, Plugins> std::fmt::Debug for Binding<PluginId, Ctx, Plugins>
104where
105	PluginId: std::hash::Hash + Eq + Clone + Send + Sync + std::fmt::Debug + 'static,
106	Ctx: PluginContext + std::fmt::Debug + 'static,
107	Plugins: Cardinality<PluginId, PluginInstance<Ctx>> + 'static,
108	PluginSockets<PluginId, Ctx, Plugins>: Send + Sync,
109	PluginSockets<PluginId, Ctx, Plugins>: std::fmt::Debug,
110{
111	fn fmt( &self, f: &mut std::fmt::Formatter<'_> ) -> std::fmt::Result {
112		f.debug_struct( "Binding" )
113			.field( "package_name", &self.0.package_name )
114			.field( "interfaces", &self.0.interfaces )
115			.field( "plugins", &self.0.plugins )
116			.finish()
117	}
118}
119
120impl<PluginId, Ctx, Plugins> Binding<PluginId, Ctx, Plugins>
121where
122	PluginId: std::hash::Hash + Eq + Clone + Send + Sync + 'static,
123	Ctx: PluginContext + 'static,
124	Plugins: Cardinality<PluginId, PluginInstance<Ctx>> + 'static,
125	PluginSockets<PluginId, Ctx, Plugins>: Cardinality<PluginId, Mutex<PluginInstance<Ctx>>>,
126	PluginSockets<PluginId, Ctx, Plugins>: Send + Sync,
127{
128
129	/// Creates a new binding specification.
130	pub fn new(
131		package_name: impl Into<String>,
132		interfaces: HashMap<String, Interface>,
133		plugins: Plugins
134	) -> Self {
135		Self( Arc::new( BindingData {
136			package_name: package_name.into(),
137			interfaces,
138			plugins: plugins.map_mut( Mutex::new ),
139		}))
140	}
141
142	pub(crate) fn add_to_linker( binding: &Binding<PluginId, Ctx, Plugins>, linker: &mut Linker<Ctx> ) -> Result<(), wasmtime::Error>
143	where
144		PluginId: Into<Val>,
145		DispatchVals<PluginId, Ctx, Plugins>: Into<Val>,
146	{
147		binding.0.interfaces.iter().try_for_each(|( name, interface )| {
148			let interface_ident = format!( "{}/{}", binding.0.package_name, name );
149			interface.add_to_linker( linker, &interface_ident, binding )
150		})
151	}
152
153	pub(crate) fn plugins( &self ) -> &PluginSockets<PluginId, Ctx, Plugins> {
154		&self.0.plugins
155	}
156
157	/// Dispatches a function call to all plugins implementing this binding.
158	///
159	/// This is used for external dispatch (calling into the plugin graph from outside).
160	/// The result is wrapped in a type matching the binding's cardinality.
161	///
162	/// # Arguments
163	/// * `interface_name` - The interface name within this binding (e.g., "example")
164	/// * `function_name` - The function name within the interface (e.g., "get-value")
165	/// * `args` - Arguments to pass to the function
166	///
167	/// # Returns
168	/// A cardinality wrapper containing `Result<Val, DispatchError>` for each plugin.
169	/// For [`ReturnKind::Void`]( crate::ReturnKind::Void ), the value is an empty tuple
170	/// (`Val::Tuple( vec![] )`) placeholder.
171	///
172	/// # Errors
173	/// Returns an error if the interface or function is not found in this binding.
174	pub fn dispatch(
175		&self,
176		interface_name: &str,
177		function_name: &str,
178		args: &[wasmtime::component::Val],
179	) -> Result<DispatchResults<PluginId, Ctx, Plugins>, crate::DispatchError> {
180
181		let interface = self.0.interfaces.get( interface_name )
182			.ok_or_else(|| crate::DispatchError::InvalidInterfacePath( format!( "{}/{}", self.0.package_name, interface_name )))?;
183
184		let function = interface.function( function_name )
185			.ok_or_else(|| crate::DispatchError::InvalidFunction( function_name.to_string() ))?;
186
187		let interface_path = format!( "{}/{}", self.0.package_name, interface_name );
188
189		Ok( self.0.plugins.map(| _, plugin | plugin
190			.lock().map_err(|_| crate::DispatchError::LockRejected )
191			.and_then(| mut lock | lock.dispatch(
192				&interface_path,
193				function_name,
194				function,
195				args,
196			))
197		))
198
199	}
200
201}
202
203/// Type-erased binding wrapper for heterogeneous socket lists.
204///
205/// Use when a plugin's sockets include bindings with different cardinalities.
206#[derive( Debug, Clone )]
207pub enum BindingAny<PluginId, Ctx>
208where
209	PluginId: std::hash::Hash + Eq + Clone + Send + Sync + 'static,
210	Ctx: PluginContext + 'static,
211{
212	/// Exactly one plugin implementation.
213	ExactlyOne( Binding<PluginId, Ctx, ExactlyOne<PluginId, PluginInstance<Ctx>>> ),
214	/// Zero or one plugin implementation.
215	AtMostOne( Binding<PluginId, Ctx, AtMostOne<PluginId, PluginInstance<Ctx>>> ),
216	/// One or more plugin implementations.
217	AtLeastOne( Binding<PluginId, Ctx, AtLeastOne<PluginId, PluginInstance<Ctx>>> ),
218	/// Zero or more plugin implementations.
219	Any( Binding<PluginId, Ctx, Any<PluginId, PluginInstance<Ctx>>> ),
220}
221
222impl<PluginId, Ctx> BindingAny<PluginId, Ctx>
223where
224	PluginId: std::hash::Hash + Eq + Clone + Send + Sync + Into<Val> + 'static,
225	Ctx: PluginContext + 'static,
226{
227	pub(crate) fn add_to_linker( &self, linker: &mut Linker<Ctx> ) -> Result<(), wasmtime::Error> {
228		match self {
229			Self::ExactlyOne( binding ) => Binding::add_to_linker( binding, linker ),
230			Self::AtMostOne( binding ) => Binding::add_to_linker( binding, linker ),
231			Self::AtLeastOne( binding ) => Binding::add_to_linker( binding, linker ),
232			Self::Any( binding ) => Binding::add_to_linker( binding, linker ),
233		}
234	}
235}
236
237impl<PluginId, Ctx> From<Binding<PluginId, Ctx, ExactlyOne<PluginId, PluginInstance<Ctx>>>> for BindingAny<PluginId, Ctx>
238where
239	PluginId: std::hash::Hash + Eq + Clone + Send + Sync + 'static,
240	Ctx: PluginContext + 'static,
241{
242	fn from( binding: Binding<PluginId, Ctx, ExactlyOne<PluginId, PluginInstance<Ctx>>> ) -> Self {
243		Self::ExactlyOne( binding )
244	}
245}
246
247impl<PluginId, Ctx> From<Binding<PluginId, Ctx, AtMostOne<PluginId, PluginInstance<Ctx>>>> for BindingAny<PluginId, Ctx>
248where
249	PluginId: std::hash::Hash + Eq + Clone + Send + Sync + 'static,
250	Ctx: PluginContext + 'static,
251{
252	fn from( binding: Binding<PluginId, Ctx, AtMostOne<PluginId, PluginInstance<Ctx>>> ) -> Self {
253		Self::AtMostOne( binding )
254	}
255}
256
257impl<PluginId, Ctx> From<Binding<PluginId, Ctx, AtLeastOne<PluginId, PluginInstance<Ctx>>>> for BindingAny<PluginId, Ctx>
258where
259	PluginId: std::hash::Hash + Eq + Clone + Send + Sync + 'static,
260	Ctx: PluginContext + 'static,
261{
262	fn from( binding: Binding<PluginId, Ctx, AtLeastOne<PluginId, PluginInstance<Ctx>>> ) -> Self {
263		Self::AtLeastOne( binding )
264	}
265}
266
267impl<PluginId, Ctx> From<Binding<PluginId, Ctx, Any<PluginId, PluginInstance<Ctx>>>> for BindingAny<PluginId, Ctx>
268where
269	PluginId: std::hash::Hash + Eq + Clone + Send + Sync + 'static,
270	Ctx: PluginContext + 'static,
271{
272	fn from( binding: Binding<PluginId, Ctx, Any<PluginId, PluginInstance<Ctx>>> ) -> Self {
273		Self::Any( binding )
274	}
275}
276
277impl<PluginId, Ctx, Plugins> Binding<PluginId, Ctx, Plugins>
278where
279	PluginId: std::hash::Hash + Eq + Clone + Send + Sync + 'static,
280	Ctx: PluginContext + 'static,
281	Plugins: Cardinality<PluginId, PluginInstance<Ctx>>,
282	PluginSockets<PluginId, Ctx, Plugins>: Send + Sync,
283	BindingAny<PluginId, Ctx>: From<Binding<PluginId, Ctx, Plugins>>,
284{
285	/// Converts this binding into a type-erased [`BindingAny`] for heterogeneous socket lists.
286	pub fn into_any( self ) -> BindingAny<PluginId, Ctx> {
287		self.into()
288	}
289}
wasm_link/binding.rs

wasm_link/
binding.rs
