Skip to main content

astrs_node_api/testing/
daemon.rs

1//! [`MockDaemon`] — the daemon side of §7.3, in this process.
2//!
3//! Blueprint §9.1 lists `init_testing (in-process daemon for unit tests)` as
4//! part of the node API's surface. This is that daemon. It is **not** a stub:
5//! it speaks the real greeting (§7.2), the real `NodeRequest`/`NodeEvent`
6//! families (§7.3), over the real frame codec (§7.1), on both ends of a
7//! `tokio::io::duplex` pair. A node under test cannot tell it from a socket,
8//! which is the entire point — a test that passes here is a test of the code
9//! that ships.
10//!
11//! ```text
12//!   Node ──► real greeting ──► real frames ──► MockDaemon
13//!                                                  │
14//!                                        routing table from the specs
15//!                                                  │
16//!   another Node ◄── real NodeEvent frames ◄───────┘
17//! ```
18//!
19//! # What it does
20//!
21//! | Request | Answer |
22//! |---|---|
23//! | `Register` | `Registered { spec, session }` |
24//! | `Subscribe` | Recorded; inputs start flowing |
25//! | `SendMessage` | Recorded, **and routed** to every consumer whose `InputSpec::source` names that port |
26//! | `OutputDone` / `CloseOutputs` | `InputClosed` to those consumers |
27//! | `ExtStore` / `ExtLoad` / `ExtDrop` | An in-memory extension table; `ExtLoad` answers `ExtValue` |
28//! | `RouteUpgradeAck` | Recorded, so a test can assert the §6.3 handshake completed |
29//!
30//! The routing is what makes a *two-node* test possible: connect a producer
31//! and a consumer whose input names the producer's port, and a `send` on one
32//! arrives as an `Event::Input` on the other, through the wire, exactly as it
33//! would through a daemon.
34
35use std::collections::HashMap;
36use std::sync::atomic::{AtomicU64, Ordering};
37use std::sync::{Arc, Mutex, MutexGuard};
38use std::time::{Duration, Instant};
39
40use astrs_transport::accept;
41use astrs_wire::messages::control::types::ParamScope;
42use astrs_wire::metadata::Parameter;
43use astrs_wire::{
44    Acceptor, AuthToken, DataId, DataflowId, ExtensionKey, FrameKind, FrameLimits, LogRecord,
45    Metadata, NodeEvent, NodeId, NodeRequest, NodeSpawnSpec, OutputPayload, ParamKey, PortRef,
46    RoleSet, RouteCloseReason, RouteDowngradeReason, SessionAssignment, SessionId, ShmSegmentSpec,
47    StopCause, WireMessage,
48};
49use tokio::sync::mpsc;
50
51use crate::error::{NodeError, Result};
52use crate::node::NodeBuilder;
53use crate::runtime::NodeRuntime;
54use crate::session::connect::{NodeLink, wrap_stream};
55use crate::signal::{Signal, WaitOutcome};
56
57/// The duplex buffer each mock connection gets.
58///
59/// Generous on purpose: a test that fills it would be measuring the buffer
60/// rather than the node.
61pub const DUPLEX_BUFFER: usize = 1024 * 1024;
62
63/// How long the mock greeting is allowed to take.
64pub const HANDSHAKE_TIMEOUT: Duration = Duration::from_secs(5);
65
66/// One request the daemon received, with the node it came from.
67#[derive(Debug, Clone)]
68pub struct RecordedRequest {
69    /// Which node sent it.
70    pub node: NodeId,
71    /// What it was.
72    pub request: NodeRequest,
73}
74
75/// One message a node published.
76#[derive(Debug, Clone)]
77pub struct RecordedSend {
78    /// Which node published it.
79    pub node: NodeId,
80    /// On which output.
81    pub output: DataId,
82    /// The metadata beside it.
83    pub metadata: Metadata,
84    /// The payload, inline or as a shared-memory reference.
85    pub payload: OutputPayload,
86}
87
88impl RecordedSend {
89    /// The payload bytes, when it was carried inline.
90    #[must_use]
91    pub fn bytes(&self) -> Option<&[u8]> {
92        self.payload.bytes()
93    }
94
95    /// The port this message came from.
96    #[must_use]
97    pub fn port(&self) -> PortRef {
98        PortRef::new(self.node.clone(), self.output.clone())
99    }
100}
101
102/// The per-node state the mock daemon keeps.
103struct NodeState {
104    /// The specification the node registered with.
105    spec: NodeSpawnSpec,
106    /// The channel the serving task writes events from.
107    events: mpsc::UnboundedSender<NodeEvent>,
108    /// Whether the node has subscribed yet.
109    subscribed: bool,
110}
111
112/// The daemon's shared state.
113struct DaemonInner {
114    /// The dataflow every node joins.
115    dataflow: DataflowId,
116    /// The token the greeting requires.
117    auth: AuthToken,
118    /// Connected nodes.
119    nodes: Mutex<HashMap<NodeId, NodeState>>,
120    /// The extension table (§7.3).
121    extensions: Mutex<HashMap<String, Vec<u8>>>,
122    /// Every request received, in order.
123    requests: Mutex<Vec<RecordedRequest>>,
124    /// Every message published, in order.
125    sends: Mutex<Vec<RecordedSend>>,
126    /// Every log record received.
127    logs: Mutex<Vec<LogRecord>>,
128    /// Wakes [`MockDaemon::wait_for`].
129    signal: Signal,
130    /// Hands out session ids.
131    next_session: AtomicU64,
132}
133
134impl DaemonInner {
135    /// Records a request and wakes the waiters.
136    fn record_request(&self, node: &NodeId, request: &NodeRequest) {
137        lock(&self.requests).push(RecordedRequest {
138            node: node.clone(),
139            request: request.clone(),
140        });
141        self.signal.notify();
142    }
143
144    /// Sends an event to one node.
145    fn deliver(&self, node: &NodeId, event: NodeEvent) -> bool {
146        let nodes = lock(&self.nodes);
147        let Some(state) = nodes.get(node) else {
148            return false;
149        };
150        state.events.send(event).is_ok()
151    }
152
153    /// Every `(node, input)` that reads from `port`.
154    fn consumers_of(&self, port: &PortRef) -> Vec<(NodeId, DataId)> {
155        lock(&self.nodes)
156            .iter()
157            .flat_map(|(id, state)| {
158                state
159                    .spec
160                    .inputs
161                    .iter()
162                    .filter(|input| &input.source == port)
163                    .map(move |input| (id.clone(), input.id.clone()))
164            })
165            .collect()
166    }
167}
168
169/// An in-process daemon for unit tests.
170#[derive(Clone)]
171pub struct MockDaemon {
172    /// The shared state.
173    inner: Arc<DaemonInner>,
174    /// The runtime the serving tasks run on.
175    runtime: NodeRuntime,
176}
177
178impl core::fmt::Debug for MockDaemon {
179    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
180        f.debug_struct("MockDaemon")
181            .field("dataflow", &self.inner.dataflow)
182            .field("nodes", &self.node_ids())
183            .field("requests", &lock(&self.inner.requests).len())
184            .finish_non_exhaustive()
185    }
186}
187
188impl MockDaemon {
189    /// Starts a daemon on a runtime of its own choosing.
190    ///
191    /// # Errors
192    ///
193    /// [`NodeError::Runtime`] when no runtime is running and one cannot be
194    /// built.
195    pub fn start() -> Result<Self> {
196        Self::start_with(
197            NodeRuntime::acquire()?,
198            DataflowId::from_u128(1),
199            AuthToken::ZERO,
200        )
201    }
202
203    /// Starts a daemon with an explicit runtime, dataflow and token.
204    ///
205    /// # Errors
206    ///
207    /// Nothing today; the signature is fallible so a future backing store can
208    /// report a failure without a breaking change.
209    pub fn start_with(runtime: NodeRuntime, dataflow: DataflowId, auth: AuthToken) -> Result<Self> {
210        Ok(Self {
211            inner: Arc::new(DaemonInner {
212                dataflow,
213                auth,
214                nodes: Mutex::new(HashMap::new()),
215                extensions: Mutex::new(HashMap::new()),
216                requests: Mutex::new(Vec::new()),
217                sends: Mutex::new(Vec::new()),
218                logs: Mutex::new(Vec::new()),
219                signal: Signal::new(),
220                next_session: AtomicU64::new(1),
221            }),
222            runtime,
223        })
224    }
225
226    /// The dataflow every node joins.
227    #[must_use]
228    pub fn dataflow(&self) -> DataflowId {
229        self.inner.dataflow
230    }
231
232    /// The token the greeting requires.
233    #[must_use]
234    pub fn auth(&self) -> AuthToken {
235        self.inner.auth.clone()
236    }
237
238    /// The runtime the serving tasks run on.
239    #[must_use]
240    pub fn runtime(&self) -> &NodeRuntime {
241        &self.runtime
242    }
243
244    /// The nodes currently connected.
245    #[must_use]
246    pub fn node_ids(&self) -> Vec<NodeId> {
247        let mut ids: Vec<NodeId> = lock(&self.inner.nodes).keys().cloned().collect();
248        ids.sort_unstable();
249        ids
250    }
251
252    /// Connects a node with the given specification.
253    ///
254    /// # Errors
255    ///
256    /// [`NodeError::Testing`] when the greeting or registration fails, plus
257    /// whatever [`NodeBuilder::finish`] reports.
258    pub fn connect_node(&self, spec: NodeSpawnSpec) -> Result<(crate::Node, crate::EventStream)> {
259        let daemon = self.clone();
260        let runtime = self.runtime.clone();
261        runtime.block_on(
262            "MockDaemon::connect_node",
263            "MockDaemon::connect_node_async",
264            async move { daemon.connect_node_async(spec).await },
265        )?
266    }
267
268    /// The async form of [`MockDaemon::connect_node`].
269    ///
270    /// # Errors
271    ///
272    /// As [`MockDaemon::connect_node`].
273    pub async fn connect_node_async(
274        &self,
275        spec: NodeSpawnSpec,
276    ) -> Result<(crate::Node, crate::EventStream)> {
277        let node_id = spec.node.clone();
278        let (node_io, daemon_io) = tokio::io::duplex(DUPLEX_BUFFER);
279        let (event_sender, event_receiver) = mpsc::unbounded_channel();
280
281        lock(&self.inner.nodes).insert(
282            node_id.clone(),
283            NodeState {
284                spec: spec.clone(),
285                events: event_sender,
286                subscribed: false,
287            },
288        );
289
290        let session = SessionId::from_u128(u128::from(
291            self.inner.next_session.fetch_add(1, Ordering::Relaxed),
292        ));
293        let inner = Arc::clone(&self.inner);
294        let served = node_id.clone();
295        let sender = lock(&inner.nodes)
296            .get(&served)
297            .map(|state| state.events.clone());
298        let _task = self.runtime.spawn(async move {
299            let Some(sender) = sender else { return };
300            serve(
301                inner,
302                daemon_io,
303                Some(served),
304                sender,
305                event_receiver,
306                session,
307            )
308            .await;
309        });
310
311        let mut duplex = wrap_stream(node_io, FrameLimits::uds());
312        let params = crate::session::connect::node_handshake_params(
313            self.inner.auth.clone(),
314            Some(node_id.as_str().to_owned()),
315        );
316        let greeting = astrs_transport::initiate(&mut duplex, &params, HANDSHAKE_TIMEOUT)
317            .await
318            .map_err(|error| NodeError::Testing(format!("mock greeting failed: {error}")))?;
319
320        let builder = NodeBuilder::new()
321            .node_id(node_id.as_str())?
322            .dataflow(self.inner.dataflow)
323            .orphan_guard(false)
324            .type_check(crate::env::TypeCheckMode::Warn)
325            .zero_copy_threshold(astrs_wire::DEFAULT_ZERO_COPY_THRESHOLD);
326        let handshake =
327            astrs_wire::NodeHandshake::new(self.inner.dataflow, node_id, spec.generation)
328                .with_pid(std::process::id());
329        let link = NodeLink {
330            duplex,
331            session: greeting.session,
332            endpoint: "mock://in-process".to_owned(),
333        };
334        builder.finish(link, handshake, self.runtime.clone()).await
335    }
336
337    // ------------------------------------------------------------- driving
338
339    /// Sends an arbitrary event to a node.
340    ///
341    /// # Errors
342    ///
343    /// [`NodeError::Testing`] when no such node is connected.
344    pub fn send_event(&self, node: &NodeId, event: NodeEvent) -> Result<()> {
345        if self.inner.deliver(node, event) {
346            Ok(())
347        } else {
348            Err(NodeError::Testing(format!("no node `{node}` is connected")))
349        }
350    }
351
352    /// Delivers one input message to a node.
353    ///
354    /// # Errors
355    ///
356    /// As [`MockDaemon::send_event`].
357    pub fn send_input(
358        &self,
359        node: &NodeId,
360        input: &DataId,
361        metadata: Metadata,
362        payload: Vec<u8>,
363    ) -> Result<()> {
364        let source = lock(&self.inner.nodes)
365            .get(node)
366            .and_then(|state| state.spec.input(input).map(|spec| spec.source.clone()))
367            .unwrap_or_else(|| PortRef::new(node.clone(), input.clone()));
368        self.send_event(
369            node,
370            NodeEvent::Input {
371                id: input.clone(),
372                source,
373                metadata,
374                payload,
375            },
376        )
377    }
378
379    /// Closes one of a node's inputs.
380    ///
381    /// # Errors
382    ///
383    /// As [`MockDaemon::send_event`].
384    pub fn close_input(
385        &self,
386        node: &NodeId,
387        input: &DataId,
388        reason: RouteCloseReason,
389    ) -> Result<()> {
390        let source = lock(&self.inner.nodes)
391            .get(node)
392            .and_then(|state| state.spec.input(input).map(|spec| spec.source.clone()))
393            .unwrap_or_else(|| PortRef::new(node.clone(), input.clone()));
394        self.send_event(
395            node,
396            NodeEvent::InputClosed {
397                id: input.clone(),
398                source,
399                reason,
400            },
401        )
402    }
403
404    /// Stops one node.
405    ///
406    /// # Errors
407    ///
408    /// As [`MockDaemon::send_event`].
409    pub fn stop(&self, node: &NodeId, cause: StopCause) -> Result<()> {
410        self.send_event(node, NodeEvent::Stop { cause, grace: None })
411    }
412
413    /// Stops every connected node.
414    pub fn stop_all(&self, cause: StopCause) {
415        for node in self.node_ids() {
416            let _ = self.stop(&node, cause.clone());
417        }
418    }
419
420    /// Pushes a parameter update to a node (§17 `param set`).
421    ///
422    /// # Errors
423    ///
424    /// As [`MockDaemon::send_event`].
425    pub fn set_param(&self, node: &NodeId, key: ParamKey, value: Parameter) -> Result<()> {
426        self.send_event(
427            node,
428            NodeEvent::ParamUpdate {
429                scope: ParamScope::node(self.inner.dataflow, node.clone()),
430                key,
431                value,
432            },
433        )
434    }
435
436    /// Offers a node a route upgrade (§6.3).
437    ///
438    /// # Errors
439    ///
440    /// As [`MockDaemon::send_event`].
441    pub fn upgrade_route(
442        &self,
443        node: &NodeId,
444        output: &DataId,
445        segment: ShmSegmentSpec,
446        consumers: Vec<PortRef>,
447    ) -> Result<()> {
448        self.send_event(
449            node,
450            NodeEvent::RouteUpgrade {
451                output: output.clone(),
452                segment,
453                consumers,
454            },
455        )
456    }
457
458    /// Takes a node's route back to the daemon path (§6.3).
459    ///
460    /// # Errors
461    ///
462    /// As [`MockDaemon::send_event`].
463    pub fn downgrade_route(
464        &self,
465        node: &NodeId,
466        output: &DataId,
467        reason: RouteDowngradeReason,
468    ) -> Result<()> {
469        self.send_event(
470            node,
471            NodeEvent::RouteDowngrade {
472                output: output.clone(),
473                reason,
474            },
475        )
476    }
477
478    // ---------------------------------------------------------- inspection
479
480    /// Every request the daemon has received.
481    #[must_use]
482    pub fn requests(&self) -> Vec<RecordedRequest> {
483        lock(&self.inner.requests).clone()
484    }
485
486    /// Every message the daemon has seen published.
487    #[must_use]
488    pub fn sends(&self) -> Vec<RecordedSend> {
489        lock(&self.inner.sends).clone()
490    }
491
492    /// The messages one node published on one output.
493    #[must_use]
494    pub fn sends_on(&self, node: &NodeId, output: &DataId) -> Vec<RecordedSend> {
495        lock(&self.inner.sends)
496            .iter()
497            .filter(|send| &send.node == node && &send.output == output)
498            .cloned()
499            .collect()
500    }
501
502    /// Every log record the daemon has received.
503    #[must_use]
504    pub fn logs(&self) -> Vec<LogRecord> {
505        lock(&self.inner.logs).clone()
506    }
507
508    /// One entry of the extension table.
509    #[must_use]
510    pub fn extension(&self, key: &ExtensionKey) -> Option<Vec<u8>> {
511        lock(&self.inner.extensions).get(&key.to_string()).cloned()
512    }
513
514    /// Whether a node has subscribed to its inputs.
515    #[must_use]
516    pub fn is_subscribed(&self, node: &NodeId) -> bool {
517        lock(&self.inner.nodes)
518            .get(node)
519            .is_some_and(|state| state.subscribed)
520    }
521
522    /// Waits until `predicate` holds over the recorded requests.
523    ///
524    /// The synchronisation primitive a test needs when the node's own thread
525    /// is doing the work: assert on *what the daemon saw*, not on a sleep.
526    ///
527    /// # Errors
528    ///
529    /// [`NodeError::Timeout`] when it never holds.
530    pub fn wait_for(
531        &self,
532        timeout: Duration,
533        mut predicate: impl FnMut(&[RecordedRequest]) -> bool,
534    ) -> Result<()> {
535        let deadline = Instant::now() + timeout;
536        loop {
537            let ticket = self.inner.signal.ticket();
538            if predicate(&lock(&self.inner.requests)) {
539                return Ok(());
540            }
541            let Some(remaining) = deadline.checked_duration_since(Instant::now()) else {
542                return Err(NodeError::Timeout {
543                    operation: "MockDaemon::wait_for",
544                    millis: u64::try_from(timeout.as_millis()).unwrap_or(u64::MAX),
545                });
546            };
547            if self.inner.signal.wait_blocking(ticket, Some(remaining)) == WaitOutcome::Closed {
548                return Err(NodeError::Testing("the mock daemon stopped".to_owned()));
549            }
550        }
551    }
552
553    /// Waits until `node` has sent at least `count` messages on `output`.
554    ///
555    /// # Errors
556    ///
557    /// As [`MockDaemon::wait_for`].
558    pub fn wait_for_sends(
559        &self,
560        node: &NodeId,
561        output: &DataId,
562        count: usize,
563        timeout: Duration,
564    ) -> Result<Vec<RecordedSend>> {
565        let inner = Arc::clone(&self.inner);
566        let wanted_node = node.clone();
567        let wanted_output = output.clone();
568        self.wait_for(timeout, move |_| {
569            lock(&inner.sends)
570                .iter()
571                .filter(|send| send.node == wanted_node && send.output == wanted_output)
572                .count()
573                >= count
574        })?;
575        Ok(self.sends_on(node, output))
576    }
577
578    /// Listens on a real Unix-domain socket, the way a daemon actually does
579    /// (§4.2).
580    ///
581    /// Every other entry point here hands a node one end of an in-process
582    /// duplex; this one exercises the dial, the socket and the greeting a
583    /// deployed node performs. Nodes that connect this way are admitted from
584    /// their `Register` handshake, so a `path: dynamic` node (§8.3) can attach
585    /// itself with nothing pre-arranged.
586    ///
587    /// # Errors
588    ///
589    /// [`NodeError::Testing`] when the socket cannot be bound.
590    #[cfg(unix)]
591    pub fn listen_unix(&self, path: impl AsRef<std::path::Path>) -> Result<UnixEndpoint> {
592        let path = path.as_ref().to_path_buf();
593        // A stale socket from a crashed run would make `bind` fail; removing
594        // it is what a daemon does at start-up too.
595        let _ = std::fs::remove_file(&path);
596        let bound = path.clone();
597        let listener = self
598            .runtime
599            .block_on(
600                "MockDaemon::listen_unix",
601                "MockDaemon::listen_unix",
602                async move { tokio::net::UnixListener::bind(bound) },
603            )?
604            .map_err(|error| {
605                NodeError::Testing(format!("cannot bind {}: {error}", path.display()))
606            })?;
607
608        let inner = Arc::clone(&self.inner);
609        let task = self.runtime.spawn(async move {
610            loop {
611                let Ok((stream, _addr)) = listener.accept().await else {
612                    break;
613                };
614                let session = SessionId::from_u128(u128::from(
615                    inner.next_session.fetch_add(1, Ordering::Relaxed),
616                ));
617                let (sender, receiver) = mpsc::unbounded_channel();
618                let served = Arc::clone(&inner);
619                let _connection = tokio::spawn(async move {
620                    serve(served, stream, None, sender, receiver, session).await;
621                });
622            }
623        });
624        Ok(UnixEndpoint { path, task })
625    }
626
627    /// Stops the daemon: every waiter wakes and every node's link ends.
628    pub fn shutdown(&self) {
629        lock(&self.inner.nodes).clear();
630        self.inner.signal.close();
631    }
632}
633
634/// A listening Unix-domain socket, unlinked when it is dropped.
635#[cfg(unix)]
636#[derive(Debug)]
637pub struct UnixEndpoint {
638    /// Where it listens.
639    path: std::path::PathBuf,
640    /// The accept loop.
641    task: tokio::task::JoinHandle<()>,
642}
643
644#[cfg(unix)]
645impl UnixEndpoint {
646    /// The socket's path.
647    #[must_use]
648    pub fn path(&self) -> &std::path::Path {
649        &self.path
650    }
651
652    /// The endpoint string a node dials.
653    #[must_use]
654    pub fn endpoint(&self) -> String {
655        format!("uds://{}", self.path.display())
656    }
657}
658
659#[cfg(unix)]
660impl Drop for UnixEndpoint {
661    fn drop(&mut self) {
662        self.task.abort();
663        let _ = std::fs::remove_file(&self.path);
664    }
665}
666
667/// Serves one node's connection.
668///
669/// `node` is `Some` when the daemon already knows who is dialling — the
670/// in-process path, where [`MockDaemon::connect_node`] registered the
671/// specification first — and `None` for a connection that arrived on a
672/// listening socket, where the node's identity is learned from its
673/// `Register` (§7.3) exactly as a real daemon learns it.
674async fn serve<S>(
675    inner: Arc<DaemonInner>,
676    io: S,
677    node: Option<NodeId>,
678    sender: mpsc::UnboundedSender<NodeEvent>,
679    mut events: mpsc::UnboundedReceiver<NodeEvent>,
680    session: SessionId,
681) where
682    S: tokio::io::AsyncRead + tokio::io::AsyncWrite + Send + Unpin + 'static,
683{
684    let mut duplex = wrap_stream(io, FrameLimits::uds());
685    let acceptor = Acceptor::new(inner.auth.clone()).with_accepted_roles(RoleSet::NODES);
686    if accept(
687        &mut duplex,
688        &acceptor,
689        SessionAssignment::Fresh(session),
690        HANDSHAKE_TIMEOUT,
691    )
692    .await
693    .is_err()
694    {
695        return;
696    }
697
698    let mut current = node;
699    let (mut reader, mut writer) = duplex.into_halves();
700    loop {
701        tokio::select! {
702            frame = reader.recv_frame() => {
703                let Ok(Some(frame)) = frame else { break };
704                match frame.kind() {
705                    FrameKind::NodeRequest => {
706                        let Ok(request) = NodeRequest::from_frame(&frame.as_view()) else {
707                            continue;
708                        };
709                        if let NodeRequest::Register(handshake) = &request {
710                            current = Some(admit(&inner, handshake, &sender));
711                        }
712                        let Some(node) = current.clone() else {
713                            // Nothing before `Register` can be attributed to a
714                            // node, so there is nothing sensible to do with it.
715                            continue;
716                        };
717                        if let Some(answer) = handle_request(&inner, &node, &request, session)
718                            && writer.send_message(&answer).await.is_err()
719                        {
720                            break;
721                        }
722                    }
723                    FrameKind::Log => {
724                        if let Ok(log) =
725                            astrs_wire::LogFrame::from_frame(&frame.as_view())
726                        {
727                            lock(&inner.logs).push(log.record);
728                            inner.signal.notify();
729                        }
730                    }
731                    _ => {}
732                }
733            }
734            event = events.recv() => {
735                let Some(event) = event else { break };
736                if writer.send_message(&event).await.is_err() {
737                    break;
738                }
739            }
740        }
741    }
742    let _ = writer.shutdown().await;
743    if let Some(node) = current {
744        let _removed = lock(&inner.nodes).remove(&node);
745    }
746}
747
748/// Admits a registering node, inventing a specification for one the daemon
749/// has never heard of.
750///
751/// A `path: dynamic` node (§8.3) declares its own ports in the handshake and
752/// is spawned by nobody, so this is the only place its wiring comes from.
753fn admit(
754    inner: &Arc<DaemonInner>,
755    handshake: &astrs_wire::NodeHandshake,
756    sender: &mpsc::UnboundedSender<NodeEvent>,
757) -> NodeId {
758    let node = handshake.node.clone();
759    let mut nodes = lock(&inner.nodes);
760    if nodes.contains_key(&node) {
761        return node;
762    }
763    let mut spec = NodeSpawnSpec::new(
764        handshake.dataflow,
765        node.clone(),
766        handshake.generation,
767        astrs_wire::NodeSource::Dynamic,
768    );
769    for input in &handshake.inputs {
770        // A dynamic node names its inputs but not their producers; the port
771        // it reads from is the one the graph will wire, and until then it
772        // reads from a port of its own name.
773        spec = spec.with_input(astrs_wire::InputSpec::new(
774            input.clone(),
775            PortRef::new(node.clone(), input.clone()),
776        ));
777    }
778    for output in &handshake.outputs {
779        spec = spec.with_output(astrs_wire::OutputSpec::new(output.clone()));
780    }
781    let _previous = nodes.insert(
782        node.clone(),
783        NodeState {
784            spec,
785            events: sender.clone(),
786            subscribed: false,
787        },
788    );
789    node
790}
791
792/// Applies one request, returning the immediate answer when there is one.
793fn handle_request(
794    inner: &Arc<DaemonInner>,
795    node: &NodeId,
796    request: &NodeRequest,
797    session: SessionId,
798) -> Option<NodeEvent> {
799    inner.record_request(node, request);
800    match request {
801        NodeRequest::Register(_) => {
802            let spec = lock(&inner.nodes)
803                .get(node)
804                .map(|state| state.spec.clone())?;
805            Some(NodeEvent::Registered {
806                spec: Box::new(spec),
807                session,
808            })
809        }
810        NodeRequest::Subscribe { .. } => {
811            if let Some(state) = lock(&inner.nodes).get_mut(node) {
812                state.subscribed = true;
813            }
814            None
815        }
816        NodeRequest::SendMessage {
817            output,
818            metadata,
819            payload,
820        } => {
821            lock(&inner.sends).push(RecordedSend {
822                node: node.clone(),
823                output: output.clone(),
824                metadata: metadata.clone(),
825                payload: payload.clone(),
826            });
827            inner.signal.notify();
828            route(inner, node, output, metadata, payload);
829            None
830        }
831        NodeRequest::OutputDone { output } => {
832            close_route(inner, node, output);
833            None
834        }
835        NodeRequest::CloseOutputs { outputs } => {
836            let all: Vec<DataId> = if outputs.is_empty() {
837                lock(&inner.nodes)
838                    .get(node)
839                    .map(|state| {
840                        state
841                            .spec
842                            .outputs
843                            .iter()
844                            .map(|out| out.id.clone())
845                            .collect()
846                    })
847                    .unwrap_or_default()
848            } else {
849                outputs.clone()
850            };
851            for output in &all {
852                close_route(inner, node, output);
853            }
854            None
855        }
856        NodeRequest::ExtStore { key, value, .. } => {
857            let _previous = lock(&inner.extensions).insert(key.to_string(), value.clone());
858            None
859        }
860        NodeRequest::ExtLoad { key } => {
861            let value = lock(&inner.extensions).get(&key.to_string()).cloned();
862            Some(NodeEvent::ExtValue {
863                key: key.clone(),
864                value,
865            })
866        }
867        NodeRequest::ExtDrop { key } => {
868            let _removed = lock(&inner.extensions).remove(&key.to_string());
869            None
870        }
871        // `NextEvent`, `EventStreamDropped` and `RouteUpgradeAck` are recorded
872        // above; none of them has an answer.
873        _ => None,
874    }
875}
876
877/// Delivers one published message to every consumer of its port.
878fn route(
879    inner: &Arc<DaemonInner>,
880    node: &NodeId,
881    output: &DataId,
882    metadata: &Metadata,
883    payload: &OutputPayload,
884) {
885    let port = PortRef::new(node.clone(), output.clone());
886    let bytes = payload.bytes().unwrap_or_default().to_vec();
887    for (consumer, input) in inner.consumers_of(&port) {
888        let _delivered = inner.deliver(
889            &consumer,
890            NodeEvent::Input {
891                id: input,
892                source: port.clone(),
893                metadata: metadata.clone(),
894                payload: bytes.clone(),
895            },
896        );
897    }
898}
899
900/// Tells every consumer of a port that it has closed.
901fn close_route(inner: &Arc<DaemonInner>, node: &NodeId, output: &DataId) {
902    let port = PortRef::new(node.clone(), output.clone());
903    for (consumer, input) in inner.consumers_of(&port) {
904        let _delivered = inner.deliver(
905            &consumer,
906            NodeEvent::InputClosed {
907                id: input,
908                source: port.clone(),
909                reason: RouteCloseReason::ProducerFinished,
910            },
911        );
912    }
913}
914
915/// Locks a mutex, recovering from a poisoning panic elsewhere.
916fn lock<T>(mutex: &Mutex<T>) -> MutexGuard<'_, T> {
917    mutex
918        .lock()
919        .unwrap_or_else(std::sync::PoisonError::into_inner)
920}
921
922#[cfg(test)]
923mod tests {
924    #![allow(clippy::unwrap_used, clippy::expect_used, clippy::panic)]
925
926    use super::*;
927    use crate::Event;
928    use astrs_wire::{InputSpec, NodeSource, OutputSpec};
929
930    fn producer_spec(daemon: &MockDaemon) -> NodeSpawnSpec {
931        NodeSpawnSpec::new(
932            daemon.dataflow(),
933            NodeId::new("camera").unwrap(),
934            0,
935            NodeSource::Dynamic,
936        )
937        .with_output(OutputSpec::new(DataId::new("image").unwrap()))
938    }
939
940    fn consumer_spec(daemon: &MockDaemon) -> NodeSpawnSpec {
941        NodeSpawnSpec::new(
942            daemon.dataflow(),
943            NodeId::new("detect").unwrap(),
944            0,
945            NodeSource::Dynamic,
946        )
947        .with_input(InputSpec::new(
948            DataId::new("frames").unwrap(),
949            PortRef::from_parts("camera", "image").unwrap(),
950        ))
951    }
952
953    #[test]
954    fn a_node_registers_and_subscribes() {
955        let daemon = MockDaemon::start().unwrap();
956        let (node, _events) = daemon.connect_node(consumer_spec(&daemon)).unwrap();
957        let id = node.id().clone();
958
959        daemon
960            .wait_for(Duration::from_secs(5), |requests| {
961                requests
962                    .iter()
963                    .any(|entry| matches!(entry.request, NodeRequest::Subscribe { .. }))
964            })
965            .unwrap();
966        assert!(daemon.is_subscribed(&id));
967        assert_eq!(daemon.node_ids(), vec![id]);
968
969        let kinds: Vec<&str> = daemon
970            .requests()
971            .iter()
972            .map(|entry| entry.request.variant_name())
973            .collect();
974        assert_eq!(kinds, vec!["Register", "Subscribe"]);
975        assert!(format!("{daemon:?}").contains("detect"));
976    }
977
978    #[test]
979    fn one_nodes_output_becomes_anothers_input() {
980        let daemon = MockDaemon::start().unwrap();
981        let (mut producer, _pe) = daemon.connect_node(producer_spec(&daemon)).unwrap();
982        let (_consumer, mut events) = daemon.connect_node(consumer_spec(&daemon)).unwrap();
983
984        let mut image = producer.raw_output("image").unwrap();
985        image
986            .send_bytes(vec![1, 2, 3], producer.metadata())
987            .unwrap();
988
989        let event = events
990            .recv_timeout(Duration::from_secs(5))
991            .unwrap()
992            .expect("the routed input");
993        let Some((id, _, data)) = event.into_input() else {
994            panic!("expected an input");
995        };
996        assert_eq!(id.as_str(), "frames");
997        assert_eq!(data.to_vec(), vec![1, 2, 3]);
998
999        let sends = daemon.sends_on(
1000            &NodeId::new("camera").unwrap(),
1001            &DataId::new("image").unwrap(),
1002        );
1003        assert_eq!(sends.len(), 1);
1004        assert_eq!(sends[0].bytes(), Some(&[1, 2, 3][..]));
1005        assert_eq!(sends[0].port().to_string(), "camera/image");
1006    }
1007
1008    #[test]
1009    fn closing_an_output_closes_the_consumer_input() {
1010        let daemon = MockDaemon::start().unwrap();
1011        let (mut producer, _pe) = daemon.connect_node(producer_spec(&daemon)).unwrap();
1012        let (_consumer, mut events) = daemon.connect_node(consumer_spec(&daemon)).unwrap();
1013
1014        let mut image = producer.raw_output("image").unwrap();
1015        image.close().unwrap();
1016
1017        let event = events
1018            .recv_timeout(Duration::from_secs(5))
1019            .unwrap()
1020            .expect("the close");
1021        assert!(matches!(event, Event::InputClosed { .. }));
1022    }
1023
1024    #[test]
1025    fn the_daemon_can_drive_a_node_directly() {
1026        let daemon = MockDaemon::start().unwrap();
1027        let (node, mut events) = daemon.connect_node(consumer_spec(&daemon)).unwrap();
1028        let id = node.id().clone();
1029        daemon
1030            .send_input(
1031                &id,
1032                &DataId::new("frames").unwrap(),
1033                Metadata::default(),
1034                vec![9],
1035            )
1036            .unwrap();
1037        let event = events
1038            .recv_timeout(Duration::from_secs(5))
1039            .unwrap()
1040            .unwrap();
1041        assert_eq!(event.payload().map(crate::Payload::len), Some(1));
1042
1043        daemon.stop(&id, StopCause::Requested).unwrap();
1044        let event = events
1045            .recv_timeout(Duration::from_secs(5))
1046            .unwrap()
1047            .unwrap();
1048        assert!(event.is_stop());
1049        assert!(events.is_fused());
1050    }
1051
1052    #[test]
1053    fn an_unknown_node_is_reported() {
1054        let daemon = MockDaemon::start().unwrap();
1055        let error = daemon
1056            .stop(&NodeId::new("ghost").unwrap(), StopCause::Requested)
1057            .unwrap_err();
1058        assert!(matches!(error, NodeError::Testing(_)), "{error}");
1059    }
1060
1061    #[test]
1062    fn waiting_for_something_that_never_happens_times_out() {
1063        let daemon = MockDaemon::start().unwrap();
1064        let error = daemon
1065            .wait_for(Duration::from_millis(50), |_| false)
1066            .unwrap_err();
1067        assert!(matches!(error, NodeError::Timeout { .. }), "{error}");
1068    }
1069
1070    #[test]
1071    fn the_documented_constants_are_stable() {
1072        assert_eq!(DUPLEX_BUFFER, 1024 * 1024);
1073        assert_eq!(HANDSHAKE_TIMEOUT, Duration::from_secs(5));
1074    }
1075}