1use std::any::{Any, TypeId};
11use std::collections::HashMap;
12use std::fmt;
13use std::sync::{Arc, OnceLock};
14use std::time::Duration;
15
16use futures::future::BoxFuture;
17use indexmap::IndexMap;
18
19use crate::dsl::NodeDoc;
20use crate::event::{Event, FrameId, PauseReason, Usage};
21use crate::pool::{Selector, VariablePool};
22use crate::snapshot::FrameSnapshot;
23use crate::value::Value;
24
25#[derive(Clone, Copy, Debug, PartialEq, Eq)]
27#[non_exhaustive]
28pub enum NodeRole {
29 Root,
31 ScopeStart,
33 Executable,
35 Branch,
37 Response,
39 Container,
41}
42
43#[derive(Clone, Debug, PartialEq, thiserror::Error)]
45#[error("{kind}: {message}")]
46pub struct NodeError {
47 pub kind: String,
49 pub message: String,
50 pub retryable: bool,
52 pub retry_after_ms: Option<u64>,
56}
57
58impl NodeError {
59 pub fn new(kind: impl Into<String>, message: impl Into<String>) -> Self {
60 Self { kind: kind.into(), message: message.into(), retryable: true, retry_after_ms: None }
61 }
62
63 pub fn fatal(kind: impl Into<String>, message: impl Into<String>) -> Self {
65 Self { kind: kind.into(), message: message.into(), retryable: false, retry_after_ms: None }
66 }
67
68 pub fn with_retry_after(mut self, retry_after_ms: Option<u64>) -> Self {
70 self.retry_after_ms = retry_after_ms;
71 self
72 }
73
74 pub fn with_message(mut self, message: impl Into<String>) -> Self {
76 self.message = message.into();
77 self
78 }
79
80 pub fn invalid_input(message: impl Into<String>) -> Self {
81 Self::fatal("invalid_input", message)
82 }
83
84 pub fn timeout(after: Duration) -> Self {
85 Self::new("timeout", format!("node timed out after {} ms", after.as_millis()))
86 }
87}
88
89#[derive(Clone, Debug, PartialEq, Eq, thiserror::Error)]
91#[error("node `{node_id}` ({kind}): {message}")]
92pub struct ConfigError {
93 pub node_id: String,
94 pub kind: String,
95 pub message: String,
96}
97
98impl ConfigError {
99 pub fn new(doc: &NodeDoc, message: impl Into<String>) -> Self {
100 Self { node_id: doc.id.clone(), kind: doc.kind.clone(), message: message.into() }
101 }
102}
103
104#[derive(Clone, Debug, Default, PartialEq)]
106pub struct NodeOutput {
107 pub outputs: IndexMap<String, Value>,
109 pub branch: Option<String>,
111 pub writes: Vec<(Selector, Value)>,
113 pub usage: Option<Usage>,
114 pub metadata: IndexMap<String, Value>,
116}
117
118impl NodeOutput {
119 pub fn new() -> Self {
120 Self::default()
121 }
122
123 pub fn with(mut self, key: impl Into<String>, value: impl Into<Value>) -> Self {
124 self.outputs.insert(key.into(), value.into());
125 self
126 }
127
128 pub fn branch(mut self, handle: impl Into<String>) -> Self {
129 self.branch = Some(handle.into());
130 self
131 }
132
133 pub fn write(mut self, selector: Selector, value: Value) -> Self {
134 self.writes.push((selector, value));
135 self
136 }
137
138 pub fn usage(mut self, usage: Usage) -> Self {
139 self.usage = Some(usage);
140 self
141 }
142
143 pub fn meta(mut self, key: impl Into<String>, value: impl Into<Value>) -> Self {
144 self.metadata.insert(key.into(), value.into());
145 self
146 }
147}
148
149#[derive(Clone, Debug, PartialEq)]
151pub struct PauseRequest {
152 pub kind: String,
154 pub data: Value,
156 pub state: serde_json::Value,
158}
159
160#[derive(Clone, Debug, PartialEq)]
162pub enum NodeOutcome {
163 Completed(NodeOutput),
164 Paused(PauseRequest),
165}
166
167impl From<NodeOutput> for NodeOutcome {
168 fn from(o: NodeOutput) -> Self {
169 NodeOutcome::Completed(o)
170 }
171}
172
173#[derive(Clone, Debug, PartialEq)]
175pub struct Resume {
176 pub state: serde_json::Value,
178 pub input: Option<Value>,
180}
181
182pub type NodeResult = Result<NodeOutcome, NodeError>;
184
185pub trait Node: Send + Sync + fmt::Debug {
187 fn role(&self) -> NodeRole {
189 NodeRole::Executable
190 }
191
192 fn run(&self, ctx: NodeContext) -> BoxFuture<'_, NodeResult>;
194
195 fn inputs(&self) -> Vec<Selector> {
201 Vec::new()
202 }
203}
204
205pub fn merge_writes(acc: &mut Vec<(Selector, Value)>, new: impl IntoIterator<Item = (Selector, Value)>) {
212 for (selector, value) in new {
213 if let Some(pos) = acc.iter().position(|(s, _)| *s == selector) {
214 acc.remove(pos);
215 }
216 acc.push((selector, value));
217 }
218}
219
220#[derive(Debug)]
222pub struct SubgraphRequest {
223 pub index: usize,
225 pub pool: VariablePool,
228 pub resume: Option<FrameSnapshot>,
230}
231
232#[derive(Debug)]
237#[allow(clippy::large_enum_variant)]
238pub enum SubgraphResult {
239 Completed {
240 pool: VariablePool,
242 outputs: IndexMap<String, Value>,
244 writes: Vec<(Selector, Value)>,
247 usage: Usage,
248 broke: bool,
250 },
251 Failed {
252 error: NodeError,
253 usage: Usage,
254 },
255 Paused {
256 snapshot: FrameSnapshot,
257 reasons: Vec<PauseReason>,
258 },
259}
260
261pub trait Subgraph: Send + Sync + fmt::Debug {
263 fn run(&self, request: SubgraphRequest) -> BoxFuture<'_, SubgraphResult>;
264}
265
266pub trait Clock: Send + Sync + fmt::Debug {
268 fn now_ms(&self) -> u64;
270 fn sleep(&self, duration: Duration) -> BoxFuture<'static, ()>;
272 fn supports_timers(&self) -> bool {
274 true
275 }
276}
277
278#[derive(Debug, Default, Clone, Copy)]
281pub struct NoTimerClock;
282
283impl Clock for NoTimerClock {
284 fn now_ms(&self) -> u64 {
285 system_now_ms()
286 }
287 fn sleep(&self, _duration: Duration) -> BoxFuture<'static, ()> {
288 Box::pin(futures::future::ready(()))
289 }
290 fn supports_timers(&self) -> bool {
291 false
292 }
293}
294
295#[cfg(not(all(target_arch = "wasm32", target_os = "unknown")))]
301fn system_now_ms() -> u64 {
302 std::time::SystemTime::now()
303 .duration_since(std::time::UNIX_EPOCH)
304 .map(|d| u64::try_from(d.as_millis()).unwrap_or(u64::MAX))
305 .unwrap_or(0)
306}
307
308#[cfg(all(target_arch = "wasm32", target_os = "unknown"))]
309fn system_now_ms() -> u64 {
310 use std::sync::atomic::{AtomicU64, Ordering};
311 static COUNTER: AtomicU64 = AtomicU64::new(0);
312 COUNTER.fetch_add(1, Ordering::Relaxed)
313}
314
315#[cfg(feature = "tokio")]
317#[derive(Debug, Default, Clone, Copy)]
318pub struct TokioClock;
319
320#[cfg(feature = "tokio")]
321impl Clock for TokioClock {
322 fn now_ms(&self) -> u64 {
323 NoTimerClock.now_ms()
324 }
325 fn sleep(&self, duration: Duration) -> BoxFuture<'static, ()> {
330 if tokio::runtime::Handle::try_current().is_ok() {
331 Box::pin(tokio::time::sleep(duration))
332 } else {
333 Box::pin(futures::future::ready(()))
334 }
335 }
336
337 fn supports_timers(&self) -> bool {
339 tokio::runtime::Handle::try_current().is_ok()
340 }
341}
342
343pub fn default_clock() -> Arc<dyn Clock> {
345 #[cfg(feature = "tokio")]
346 {
347 Arc::new(TokioClock)
348 }
349 #[cfg(not(feature = "tokio"))]
350 {
351 Arc::new(NoTimerClock)
352 }
353}
354
355#[derive(Default, Clone)]
359pub struct Services {
360 map: HashMap<TypeId, Arc<dyn Any + Send + Sync>>,
361}
362
363impl fmt::Debug for Services {
364 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
365 write!(f, "Services({} entries)", self.map.len())
366 }
367}
368
369impl Services {
370 pub fn new() -> Self {
371 Self::default()
372 }
373
374 pub fn insert<T: Any + Send + Sync>(&mut self, service: T) -> &mut Self {
376 self.map.insert(TypeId::of::<T>(), Arc::new(service));
377 self
378 }
379
380 pub fn with<T: Any + Send + Sync>(mut self, service: T) -> Self {
382 self.insert(service);
383 self
384 }
385
386 pub fn get<T: Any + Send + Sync>(&self) -> Option<&T> {
387 self.map.get(&TypeId::of::<T>()).and_then(|s| s.downcast_ref::<T>())
388 }
389}
390
391pub type EventSink = Arc<dyn Fn(Event) + Send + Sync>;
393
394#[derive(Clone)]
396pub struct NodeContext {
397 pub node_id: Arc<str>,
398 pub exec_id: Arc<str>,
399 pub frame: FrameId,
400 pub attempt: u32,
402 pub pool: VariablePool,
404 pub services: Arc<Services>,
405 pub clock: Arc<dyn Clock>,
406 pub resume: Option<Resume>,
408 pub subgraph: Option<Arc<dyn Subgraph>>,
410 pub deadline_ms: Option<u64>,
413 sink: EventSink,
414}
415
416impl fmt::Debug for NodeContext {
417 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
418 f.debug_struct("NodeContext")
419 .field("node_id", &self.node_id)
420 .field("exec_id", &self.exec_id)
421 .field("frame", &self.frame)
422 .field("attempt", &self.attempt)
423 .finish_non_exhaustive()
424 }
425}
426
427impl NodeContext {
428 #[allow(clippy::too_many_arguments)]
430 pub fn new(
431 node_id: impl Into<Arc<str>>,
432 exec_id: impl Into<Arc<str>>,
433 frame: FrameId,
434 attempt: u32,
435 pool: VariablePool,
436 services: Arc<Services>,
437 clock: Arc<dyn Clock>,
438 sink: EventSink,
439 ) -> Self {
440 Self {
441 node_id: node_id.into(),
442 exec_id: exec_id.into(),
443 frame,
444 attempt,
445 pool,
446 services,
447 clock,
448 resume: None,
449 subgraph: None,
450 deadline_ms: None,
451 sink,
452 }
453 }
454
455 pub fn for_test(node_id: &str, pool: VariablePool) -> Self {
457 Self::new(
458 node_id,
459 format!("{node_id}-exec"),
460 Arc::from(""),
461 1,
462 pool,
463 Arc::new(Services::new()),
464 Arc::new(NoTimerClock),
465 Arc::new(|_| {}),
466 )
467 }
468
469 pub fn with_services(mut self, services: Arc<Services>) -> Self {
470 self.services = services;
471 self
472 }
473
474 pub fn with_sink(mut self, sink: EventSink) -> Self {
475 self.sink = sink;
476 self
477 }
478
479 pub fn with_resume(mut self, resume: Option<Resume>) -> Self {
480 self.resume = resume;
481 self
482 }
483
484 pub fn with_subgraph(mut self, subgraph: Option<Arc<dyn Subgraph>>) -> Self {
485 self.subgraph = subgraph;
486 self
487 }
488
489 pub fn with_deadline(mut self, deadline_ms: Option<u64>) -> Self {
490 self.deadline_ms = deadline_ms;
491 self
492 }
493
494 pub fn remaining(&self) -> Option<Duration> {
498 self.deadline_ms.map(|deadline| Duration::from_millis(deadline.saturating_sub(self.clock.now_ms())))
499 }
500
501 pub fn service<T: Any + Send + Sync>(&self) -> Option<&T> {
503 self.services.get::<T>()
504 }
505
506 pub fn require_service<T: Any + Send + Sync>(&self, what: &str) -> Result<&T, NodeError> {
508 self.services.get::<T>().ok_or_else(|| NodeError::fatal("missing_service", format!("no {what} configured")))
509 }
510
511 pub fn get(&self, selector: &Selector) -> Option<Value> {
513 self.pool.get(selector)
514 }
515
516 pub fn chunk(&self, field: &str, chunk: impl Into<String>) {
518 (self.sink)(Event::NodeChunk {
519 frame: self.frame.clone(),
520 node_id: Arc::clone(&self.node_id),
521 exec_id: Arc::clone(&self.exec_id),
522 field: field.to_owned(),
523 chunk: chunk.into(),
524 });
525 }
526
527 pub fn progress(&self, name: &str, data: Value) {
529 (self.sink)(Event::NodeProgress {
530 frame: self.frame.clone(),
531 node_id: Arc::clone(&self.node_id),
532 exec_id: Arc::clone(&self.exec_id),
533 name: name.to_owned(),
534 data,
535 });
536 }
537
538 pub fn sink(&self) -> &EventSink {
540 &self.sink
541 }
542}
543
544pub type NodeFactory = Arc<dyn Fn(&NodeDoc) -> Result<Arc<dyn Node>, ConfigError> + Send + Sync>;
546
547pub type DescriptorFn = fn() -> crate::catalog::NodeDescriptor;
549
550#[derive(Clone)]
557enum DescriptorSlot {
558 Ready(Box<crate::catalog::NodeDescriptor>),
559 Lazy(Arc<LazyDescriptor>),
560}
561
562struct LazyDescriptor {
563 build: DescriptorFn,
564 built: OnceLock<crate::catalog::NodeDescriptor>,
565}
566
567#[derive(Clone, Default)]
569pub struct Registry {
570 factories: HashMap<String, NodeFactory>,
571 descriptors: HashMap<String, DescriptorSlot>,
572}
573
574impl fmt::Debug for Registry {
575 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
576 let mut kinds: Vec<&String> = self.factories.keys().collect();
577 kinds.sort();
578 f.debug_struct("Registry").field("kinds", &kinds).finish()
579 }
580}
581
582impl Registry {
583 pub fn new() -> Self {
585 Self::default()
586 }
587
588 pub fn with_builtins() -> Self {
590 let mut r = Self::new();
591 crate::nodes::register_builtins(&mut r);
592 r
593 }
594
595 pub fn register<F>(&mut self, kind: &str, factory: F) -> &mut Self
597 where
598 F: Fn(&NodeDoc) -> Result<Arc<dyn Node>, ConfigError> + Send + Sync + 'static,
599 {
600 self.factories.insert(kind.to_owned(), Arc::new(factory));
601 self
602 }
603
604 pub fn register_described<F>(&mut self, descriptor: crate::catalog::NodeDescriptor, factory: F) -> &mut Self
607 where
608 F: Fn(&NodeDoc) -> Result<Arc<dyn Node>, ConfigError> + Send + Sync + 'static,
609 {
610 let kind = descriptor.kind.clone();
611 self.factories.insert(kind.clone(), Arc::new(factory));
612 self.descriptors.insert(kind, DescriptorSlot::Ready(Box::new(descriptor)));
613 self
614 }
615
616 pub fn register_lazily_described<F>(&mut self, kind: &str, descriptor: DescriptorFn, factory: F) -> &mut Self
621 where
622 F: Fn(&NodeDoc) -> Result<Arc<dyn Node>, ConfigError> + Send + Sync + 'static,
623 {
624 self.factories.insert(kind.to_owned(), Arc::new(factory));
625 let slot = LazyDescriptor { build: descriptor, built: OnceLock::new() };
626 self.descriptors.insert(kind.to_owned(), DescriptorSlot::Lazy(Arc::new(slot)));
627 self
628 }
629
630 pub fn describe(&mut self, descriptor: crate::catalog::NodeDescriptor) -> &mut Self {
632 if self.factories.contains_key(&descriptor.kind) {
633 self.descriptors.insert(descriptor.kind.clone(), DescriptorSlot::Ready(Box::new(descriptor)));
634 }
635 self
636 }
637
638 pub fn descriptor(&self, kind: &str) -> Option<crate::catalog::NodeDescriptor> {
640 if !self.factories.contains_key(kind) {
641 return None;
642 }
643 let descriptor = match self.descriptors.get(kind) {
644 None => crate::catalog::NodeDescriptor::bare(kind),
645 Some(DescriptorSlot::Ready(descriptor)) => (**descriptor).clone(),
646 Some(DescriptorSlot::Lazy(slot)) => slot.built.get_or_init(slot.build).clone(),
647 };
648 Some(descriptor)
649 }
650
651 pub fn descriptors(&self) -> Vec<crate::catalog::NodeDescriptor> {
653 let mut kinds: Vec<&String> = self.factories.keys().collect();
654 kinds.sort();
655 kinds.into_iter().filter_map(|k| self.descriptor(k)).collect()
656 }
657
658 pub fn alias(&mut self, alias: &str, kind: &str) -> &mut Self {
660 if let Some(f) = self.factories.get(kind).cloned() {
661 self.factories.insert(alias.to_owned(), f);
662 }
663 self
664 }
665
666 pub fn contains(&self, kind: &str) -> bool {
667 self.factories.contains_key(kind)
668 }
669
670 pub fn kinds(&self) -> impl Iterator<Item = &str> {
671 self.factories.keys().map(String::as_str)
672 }
673
674 pub fn build(&self, doc: &NodeDoc) -> Result<Arc<dyn Node>, ConfigError> {
676 let factory = self
677 .factories
678 .get(&doc.kind)
679 .ok_or_else(|| ConfigError::new(doc, format!("unknown node type `{}`", doc.kind)))?;
680 factory(doc)
681 }
682}
683
684pub fn parse_config<T: serde::de::DeserializeOwned>(doc: &NodeDoc) -> Result<T, ConfigError> {
686 doc.parse_config::<T>().map_err(|e| ConfigError::new(doc, e.to_string()))
687}