Skip to main content

graphrt_wasm/
plugin.rs

1//! Loading plugins and exposing their node kinds.
2
3use std::collections::HashSet;
4use std::fmt;
5use std::path::Path;
6use std::sync::Arc;
7
8use futures::future::BoxFuture;
9use graphrt_core::catalog::{Handles, NodeDescriptor};
10use graphrt_core::dsl::NodeDoc;
11use graphrt_core::event::Usage;
12use graphrt_core::node::{
13    ConfigError, Node, NodeContext, NodeError, NodeFactory, NodeOutcome, NodeOutput, NodeResult, NodeRole,
14    PauseRequest, Registry,
15};
16use graphrt_core::pool::Selector;
17use graphrt_core::value::Value;
18
19use crate::abi::{Manifest, ResumeData, RunRequest, RunResponse};
20use crate::error::WasmError;
21use crate::host::{Call, CallOutput, Compiled, LogLine};
22use crate::limits::WasmLimits;
23use crate::resolve::{collect_selectors, resolve_config};
24
25struct Inner {
26    compiled: Compiled,
27    manifest: Manifest,
28}
29
30/// A loaded WebAssembly plugin. Cheap to clone; safe to share across runs and threads.
31#[derive(Clone)]
32pub struct WasmPlugin {
33    inner: Arc<Inner>,
34}
35
36impl fmt::Debug for WasmPlugin {
37    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
38        let kinds: Vec<&str> = self.inner.manifest.nodes.iter().map(|n| n.kind.as_str()).collect();
39        f.debug_struct("WasmPlugin").field("name", &self.inner.manifest.name).field("kinds", &kinds).finish()
40    }
41}
42
43impl WasmPlugin {
44    /// Validate, compile and describe a module from memory.
45    pub fn load(bytes: &[u8], limits: WasmLimits) -> Result<Self, WasmError> {
46        let compiled = Compiled::new(bytes, limits)?;
47        let out = compiled.call(Call::Describe, None)?;
48        let mut manifest: Manifest =
49            serde_json::from_slice(&out.bytes).map_err(|e| WasmError::Manifest(e.to_string()))?;
50        validate_manifest(&mut manifest)?;
51        Ok(Self { inner: Arc::new(Inner { compiled, manifest }) })
52    }
53
54    /// Read and load a `.wasm` file.
55    pub fn load_file(path: impl AsRef<Path>, limits: WasmLimits) -> Result<Self, WasmError> {
56        let path = path.as_ref();
57        let io = |e: std::io::Error| WasmError::Io { path: path.display().to_string(), message: e.to_string() };
58        let size = std::fs::metadata(path).map_err(io)?.len();
59        if usize::try_from(size).map_or(true, |s| s > limits.module_bytes) {
60            return Err(WasmError::ModuleTooLarge {
61                size: usize::try_from(size).unwrap_or(usize::MAX),
62                limit: limits.module_bytes,
63            });
64        }
65        let bytes = std::fs::read(path).map_err(io)?;
66        Self::load(&bytes, limits)
67    }
68
69    /// The plugin manifest.
70    pub fn manifest(&self) -> &Manifest {
71        &self.inner.manifest
72    }
73
74    /// Catalog descriptors of every node kind in the plugin.
75    pub fn descriptors(&self) -> Vec<NodeDescriptor> {
76        self.inner.manifest.nodes.clone()
77    }
78
79    /// Limits applied to calls.
80    pub fn limits(&self) -> &WasmLimits {
81        self.inner.compiled.limits()
82    }
83
84    /// Register every node kind (with its descriptor) in `registry`.
85    ///
86    /// Fails, registering nothing, when any kind already exists: a module never
87    /// replaces a built-in node or another plugin's node.
88    pub fn register(&self, registry: &mut Registry) -> Result<(), WasmError> {
89        if let Some(taken) = self.inner.manifest.nodes.iter().find(|d| registry.contains(&d.kind)) {
90            return Err(WasmError::KindConflict(taken.kind.clone()));
91        }
92        for descriptor in &self.inner.manifest.nodes {
93            let factory = self.make_factory(descriptor);
94            registry.register_described(descriptor.clone(), move |doc| factory(doc));
95        }
96        Ok(())
97    }
98
99    /// Factory for one node kind.
100    pub fn factory(&self, kind: &str) -> Result<NodeFactory, WasmError> {
101        let descriptor = self
102            .inner
103            .manifest
104            .nodes
105            .iter()
106            .find(|d| d.kind == kind)
107            .ok_or_else(|| WasmError::UnknownKind(kind.to_owned()))?;
108        Ok(self.make_factory(descriptor))
109    }
110
111    fn make_factory(&self, descriptor: &NodeDescriptor) -> NodeFactory {
112        let inner = self.inner.clone();
113        let kind = descriptor.kind.clone();
114        let role = if matches!(descriptor.handles, Handles::Single) { NodeRole::Executable } else { NodeRole::Branch };
115        let fixed_handles = match &descriptor.handles {
116            Handles::Fixed { handles } => Some(handles.clone()),
117            _ => None,
118        };
119        Arc::new(move |doc: &NodeDoc| -> Result<Arc<dyn Node>, ConfigError> {
120            let config = serde_json::Value::Object(doc.config.clone());
121            let mut selectors = Vec::new();
122            collect_selectors(&config, &mut selectors);
123            Ok(Arc::new(WasmNode {
124                inner: inner.clone(),
125                kind: kind.clone(),
126                node_id: doc.id.clone(),
127                config,
128                role,
129                fixed_handles: fixed_handles.clone(),
130                selectors,
131            }))
132        })
133    }
134}
135
136fn validate_manifest(manifest: &mut Manifest) -> Result<(), WasmError> {
137    if manifest.name.trim().is_empty() {
138        return Err(WasmError::Manifest("`name` must not be empty".into()));
139    }
140    if manifest.nodes.is_empty() {
141        return Err(WasmError::Manifest("plugin declares no node kinds".into()));
142    }
143    let mut seen = HashSet::new();
144    let prefix = format!("{}.", manifest.name);
145    for node in &mut manifest.nodes {
146        if node.kind.trim().is_empty() || node.kind.contains(char::is_whitespace) {
147            return Err(WasmError::Manifest(format!("invalid node kind `{}`", node.kind)));
148        }
149        // Kinds are either plain names or `<module name>.<kind>`: a module cannot
150        // claim another plugin's namespace.
151        if node.kind.contains('.') && !node.kind.starts_with(&prefix) {
152            return Err(WasmError::Manifest(format!(
153                "node kind `{}` uses another namespace; namespaced kinds must start with `{prefix}`",
154                node.kind
155            )));
156        }
157        if !seen.insert(node.kind.clone()) {
158            return Err(WasmError::DuplicateKind(node.kind.clone()));
159        }
160        if node.container {
161            return Err(WasmError::Manifest(format!(
162                "`{}`: container nodes are not supported by wasm plugins",
163                node.kind
164            )));
165        }
166        if node.source.is_empty() {
167            node.source = format!("wasm:{}", manifest.name);
168        }
169    }
170    Ok(())
171}
172
173/// A node implemented by a guest module.
174struct WasmNode {
175    inner: Arc<Inner>,
176    kind: String,
177    node_id: String,
178    config: serde_json::Value,
179    role: NodeRole,
180    fixed_handles: Option<Vec<String>>,
181    selectors: Vec<Selector>,
182}
183
184impl fmt::Debug for WasmNode {
185    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
186        f.debug_struct("WasmNode").field("kind", &self.kind).field("node_id", &self.node_id).finish()
187    }
188}
189
190impl Node for WasmNode {
191    fn role(&self) -> NodeRole {
192        self.role
193    }
194
195    fn inputs(&self) -> Vec<Selector> {
196        self.selectors.clone()
197    }
198
199    fn run(&self, ctx: NodeContext) -> BoxFuture<'_, NodeResult> {
200        Box::pin(async move {
201            let limits = self.inner.compiled.limits();
202            let config = resolve_config(&self.config, &ctx.pool, limits.expose_secrets);
203            let resume = ctx.resume.as_ref().map(|r| ResumeData {
204                state: r.state.clone(),
205                input: r.input.as_ref().map(Value::to_json).unwrap_or(serde_json::Value::Null),
206            });
207            let request = RunRequest {
208                kind: self.kind.clone(),
209                node_id: self.node_id.clone(),
210                config,
211                attempt: ctx.attempt,
212                resume,
213            };
214            let input = serde_json::to_vec(&request)
215                .map_err(|e| NodeError::fatal("wasm_internal", format!("encoding request: {e}")))?;
216            let output = execute(self.inner.clone(), input, ctx).await?;
217            let logs = output.logs.clone();
218            // Guest-reported errors get the guest's own log lines, like traps do.
219            self.decode(output).map_err(|e| with_logs(e, &logs))
220        })
221    }
222}
223
224impl WasmNode {
225    fn decode(&self, output: CallOutput) -> NodeResult {
226        let response: RunResponse = serde_json::from_slice(&output.bytes)
227            .map_err(|e| NodeError::from(WasmError::InvalidOutput(format!("response is not valid JSON: {e}"))))?;
228        if let Some(err) = response.error {
229            let kind = if err.kind.trim().is_empty() { "plugin_error".to_owned() } else { err.kind };
230            let mut e = NodeError::new(kind, err.message);
231            e.retryable = err.retryable;
232            return Err(e);
233        }
234        if let Some(pause) = response.pause {
235            return Ok(NodeOutcome::Paused(PauseRequest {
236                kind: pause.kind,
237                data: Value::from_json(pause.data),
238                state: pause.state,
239            }));
240        }
241        let Some(outputs) = response.outputs else {
242            return Err(WasmError::InvalidOutput("response has none of `outputs`, `pause` or `error`".into()).into());
243        };
244        let mut out = NodeOutput::new();
245        for (key, value) in outputs {
246            out.outputs.insert(key, Value::from_json(value));
247        }
248        match (self.role, response.branch) {
249            (NodeRole::Branch, None) => {
250                return Err(
251                    WasmError::InvalidOutput(format!("branching node `{}` returned no `branch`", self.kind)).into()
252                );
253            }
254            (NodeRole::Branch, Some(handle)) => {
255                if let Some(allowed) = &self.fixed_handles {
256                    if !allowed.contains(&handle) {
257                        return Err(WasmError::InvalidOutput(format!(
258                            "branch `{handle}` is not one of the declared handles {allowed:?}"
259                        ))
260                        .into());
261                    }
262                }
263                out.branch = Some(handle);
264            }
265            // Non-branching nodes always take every edge; a stray `branch` is ignored.
266            (_, _) => {}
267        }
268        if let Some(u) = response.usage {
269            out.usage = Some(Usage {
270                prompt_tokens: u.prompt_tokens,
271                completion_tokens: u.completion_tokens,
272                total_tokens: u.total_tokens.max(u.prompt_tokens.saturating_add(u.completion_tokens)),
273            });
274        }
275        for (key, value) in response.metadata.unwrap_or_default() {
276            out.metadata.insert(key, Value::from_json(value));
277        }
278        if !output.logs.is_empty() {
279            out.metadata.insert("logs".into(), logs_value(&output.logs));
280        }
281        if output.dropped_logs > 0 {
282            out.metadata
283                .insert("dropped_logs".into(), Value::Int(i64::try_from(output.dropped_logs).unwrap_or(i64::MAX)));
284        }
285        Ok(NodeOutcome::Completed(out))
286    }
287}
288
289fn logs_value(logs: &[LogLine]) -> Value {
290    Value::array(logs.iter().map(|l| {
291        let level = ["trace", "debug", "info", "warn", "error"].get(usize::from(l.level)).copied().unwrap_or("info");
292        Value::object([("level", Value::from(level)), ("message", Value::from(l.message.as_str()))])
293    }))
294}
295
296/// Append the last guest log lines to an error message.
297fn with_logs(mut err: NodeError, logs: &[LogLine]) -> NodeError {
298    const TAIL: usize = 5;
299    if logs.is_empty() {
300        return err;
301    }
302    let tail: Vec<String> =
303        logs.iter().skip(logs.len().saturating_sub(TAIL)).map(|l| l.message.chars().take(500).collect()).collect();
304    err.message = format!("{} (guest log: {})", err.message, tail.join(" | "));
305    err
306}
307
308/// Run the guest call. Inside a tokio runtime (feature `tokio`, on by default) the
309/// interpreter runs on the blocking pool so it never stalls other nodes or their
310/// timeouts; otherwise it runs inline. Either way the call is bounded by fuel.
311async fn execute(inner: Arc<Inner>, input: Vec<u8>, ctx: NodeContext) -> Result<CallOutput, NodeError> {
312    let into_error = |f: crate::host::CallFailure| with_logs(NodeError::from(f.error), &f.logs);
313    #[cfg(feature = "tokio")]
314    {
315        if tokio::runtime::Handle::try_current().is_ok() {
316            let joined =
317                tokio::task::spawn_blocking(move || inner.compiled.call_logged(Call::Run(&input), Some(ctx))).await;
318            return match joined {
319                Ok(result) => result.map_err(into_error),
320                Err(e) => Err(NodeError::fatal("wasm_internal", format!("guest task failed: {e}"))),
321            };
322        }
323    }
324    inner.compiled.call_logged(Call::Run(&input), Some(ctx)).map_err(into_error)
325}