fraiseql_functions/observer/mod.rs
1//! Function observer for executing functions in response to events.
2
3#[cfg(test)]
4mod tests;
5
6use std::{collections::HashMap, sync::Arc};
7
8use fraiseql_error::Result;
9
10use crate::{
11 HostContext,
12 runtime::FunctionRuntime,
13 types::{EventPayload, FunctionModule, FunctionResult, ResourceLimits, RuntimeType},
14};
15
16/// Executes functions in response to trigger events.
17///
18/// This observer integrates with the fraiseql-observers action execution pipeline.
19/// It receives trigger events, looks up the corresponding function module,
20/// selects the appropriate runtime, and executes the function.
21pub struct FunctionObserver {
22 runtimes: HashMap<RuntimeType, Arc<dyn std::any::Any + Send + Sync>>,
23}
24
25impl FunctionObserver {
26 /// Create a new function observer.
27 #[must_use]
28 pub fn new() -> Self {
29 Self {
30 runtimes: HashMap::new(),
31 }
32 }
33
34 /// Register a runtime for a specific runtime type.
35 ///
36 /// # Errors
37 ///
38 /// Returns `Err` if runtime registration fails.
39 pub fn register_runtime<R: FunctionRuntime + 'static>(
40 &mut self,
41 runtime_type: RuntimeType,
42 runtime: R,
43 ) {
44 self.runtimes.insert(runtime_type, Arc::new(runtime));
45 }
46
47 /// Execute a function module in response to an event.
48 ///
49 /// Dispatches to the appropriate runtime based on the module's `runtime` field.
50 ///
51 /// # Errors
52 ///
53 /// Returns `Err` if:
54 /// - No runtime is registered for the module's runtime type
55 /// - The runtime fails to execute the module
56 pub async fn invoke<H>(
57 &self,
58 module: &FunctionModule,
59 #[allow(unused_variables)] // Reason: used only when runtime features are enabled
60 event: EventPayload,
61 #[allow(unused_variables)] // Reason: used only when runtime features are enabled
62 host: &H,
63 #[allow(unused_variables)] // Reason: used only when runtime features are enabled
64 limits: ResourceLimits,
65 ) -> Result<FunctionResult>
66 where
67 H: HostContext + ?Sized,
68 {
69 #[allow(unused_variables)] // Reason: used only when runtime features are enabled
70 let runtime_box = self.runtimes.get(&module.runtime).ok_or_else(|| {
71 fraiseql_error::FraiseQLError::Unsupported {
72 message: format!("No runtime registered for {:?}", module.runtime),
73 }
74 })?;
75
76 // Dispatch based on runtime type
77 #[allow(unreachable_patterns)] // Reason: pattern reachability depends on features
78 match module.runtime {
79 RuntimeType::Wasm => {
80 #[cfg(feature = "runtime-wasm")]
81 {
82 let runtime = runtime_box
83 .downcast_ref::<crate::runtime::wasm::WasmRuntime>()
84 .ok_or_else(|| fraiseql_error::FraiseQLError::Unsupported {
85 message: "Invalid WASM runtime".to_string(),
86 })?;
87 runtime.invoke(module, event, host, limits).await
88 }
89 #[cfg(not(feature = "runtime-wasm"))]
90 {
91 Err(fraiseql_error::FraiseQLError::Unsupported {
92 message: "WASM runtime not enabled".to_string(),
93 })
94 }
95 },
96 RuntimeType::Deno => {
97 #[cfg(feature = "runtime-deno")]
98 {
99 let runtime = runtime_box
100 .downcast_ref::<crate::runtime::deno::DenoRuntime>()
101 .ok_or_else(|| fraiseql_error::FraiseQLError::Unsupported {
102 message: "Invalid Deno runtime".to_string(),
103 })?;
104 runtime.invoke(module, event, host, limits).await
105 }
106 #[cfg(not(feature = "runtime-deno"))]
107 {
108 Err(fraiseql_error::FraiseQLError::Unsupported {
109 message: "Deno runtime not enabled".to_string(),
110 })
111 }
112 },
113 }
114 }
115
116 /// Find all `after:mutation` triggers that match a given entity event.
117 ///
118 /// Returns the list of matching [`AfterMutationTrigger`]s from `registry`.
119 /// Used by after-mutation dispatchers to know which functions to invoke.
120 /// This method is allocation-free when no triggers match.
121 ///
122 /// [`AfterMutationTrigger`]: crate::triggers::mutation::AfterMutationTrigger
123 #[must_use]
124 pub fn find_after_mutation_triggers(
125 &self,
126 registry: &crate::triggers::registry::TriggerRegistry,
127 event: &crate::triggers::mutation::EntityEvent,
128 ) -> Vec<crate::triggers::mutation::AfterMutationTrigger> {
129 registry.after_mutation_triggers.find(&event.entity, event.event_kind)
130 }
131
132 /// Execute a WASM module with a full I/O-capable host context.
133 ///
134 /// Unlike [`invoke`](Self::invoke) — which snapshots the host into a
135 /// sync-only `HostContextSnapshot` and so returns `Unsupported` for async
136 /// I/O — this routes to
137 /// [`WasmRuntime::invoke_with_context`](crate::runtime::wasm::WasmRuntime::invoke_with_context),
138 /// giving the guest live HTTP / query / storage access through `host`. The
139 /// after:mutation dispatcher uses this so side-effecting functions (webhooks,
140 /// external provisioning) can reach the network.
141 ///
142 /// Only the WASM runtime is supported on this path; an event whose module
143 /// targets another runtime returns `Unsupported`.
144 ///
145 /// # Errors
146 ///
147 /// Returns `Err` if no WASM runtime is registered, the registered runtime is
148 /// not a [`WasmRuntime`](crate::runtime::wasm::WasmRuntime), or guest
149 /// execution fails.
150 #[cfg(feature = "runtime-wasm")]
151 pub async fn invoke_with_context(
152 &self,
153 module: &FunctionModule,
154 event: EventPayload,
155 host: Arc<dyn crate::runtime::wasm::host_bridge::DynHostContext>,
156 limits: ResourceLimits,
157 ) -> Result<FunctionResult> {
158 let runtime_box = self.runtimes.get(&RuntimeType::Wasm).ok_or_else(|| {
159 fraiseql_error::FraiseQLError::Unsupported {
160 message: "No WASM runtime registered for after:mutation dispatch".to_string(),
161 }
162 })?;
163 let runtime =
164 runtime_box.downcast_ref::<crate::runtime::wasm::WasmRuntime>().ok_or_else(|| {
165 fraiseql_error::FraiseQLError::Unsupported {
166 message: "Invalid WASM runtime".to_string(),
167 }
168 })?;
169 runtime.invoke_with_context(module, event, host, limits).await
170 }
171}
172
173impl Default for FunctionObserver {
174 fn default() -> Self {
175 Self::new()
176 }
177}