Skip to main content

astrs_node_api/output/
mod.rs

1//! Publishing: [`RawOutput`], [`Output<T>`](Output) and [`OutputSample`]
2//! (blueprint §9.1, §6.2, §6.3).
3//!
4//! ```text
5//!   output.send(value, meta)      typed   ─┐
6//!   output.send_batch(batch, …)   columnar ├─► encode ─► send_slice
7//!   output.send_bytes(bytes, …)   raw     ─┘                 │
8//!                                                            ▼
9//!                              len ≥ threshold and route upgraded?
10//!                                    yes │            │ no
11//!                                        ▼            ▼
12//!                              SHM slot (no copy)   inline frame
13//!   output.allocate(len)  ────────────────┘   (writes straight into the slot)
14//! ```
15//!
16//! # The threshold
17//!
18//! Blueprint §6.2: *"A heap payload ≥ threshold (default 4 KiB,
19//! `ASTRS_ZERO_COPY_THRESHOLD`) is copied once into a slot; below threshold it
20//! rides the UDS control channel."* A 200-byte pose does not repay a ring
21//! slot, and a 4-megapixel frame does not survive a control channel.
22//!
23//! # Never sleep-retry
24//!
25//! When the ring has no reclaimable slot, the send does **not** wait. It falls
26//! back to the daemon path and increments the `shm_fallback_total` counter
27//! ([`crate::session::SessionStats::shm_fallbacks`]) — the exact lesson §6.2
28//! records from dora's PR-2366.
29//!
30//! # Why the handles take `&mut self`
31//!
32//! An output owns its shared-memory [`astrs_shm::Producer`], because
33//! `astrs-shm` allows exactly one writer per ring and its `allocate` needs
34//! `&mut`. That ownership is what makes `allocate(len) -> SampleMut` — the
35//! genuinely zero-copy path §9.1 promises — expressible in safe Rust at all.
36
37/// Publishing arrow-rs values through `astrs-data`'s `arrow-interop` bridge
38/// (blueprint §9.1's `send_arrow(ArrayRef) [arrow-interop]`).
39#[cfg(feature = "arrow-interop")]
40#[cfg_attr(docsrs, doc(cfg(feature = "arrow-interop")))]
41pub mod arrow;
42pub mod sample;
43pub mod typed;
44
45use std::sync::Arc;
46
47use astrs_data::ipc::encode_payload;
48use astrs_data::{ArrayRef, RecordBatch};
49use astrs_shm::Producer;
50use astrs_wire::{DataId, Metadata, NodeRequest, OutputPayload, PortRef, ShmSegmentSpec};
51
52use crate::error::{NodeError, Result};
53use crate::session::SessionShared;
54use crate::session::routes::{RoutePlane, RouteSlot, RouteUpdate};
55
56#[cfg(feature = "arrow-interop")]
57#[cfg_attr(docsrs, doc(cfg(feature = "arrow-interop")))]
58pub use arrow::{ArrowSendError, ArrowSendResult};
59pub use sample::{OutputSample, SampleBuffer};
60pub use typed::Output;
61
62/// An untyped publishing handle for one of the node's outputs.
63pub struct RawOutput {
64    /// The session this publishes through.
65    shared: Arc<SessionShared>,
66    /// The output's id.
67    id: DataId,
68    /// The route hand-off point (§6.3).
69    slot: Arc<RouteSlot>,
70    /// The shared-memory producer, once the route was upgraded.
71    producer: Option<Producer>,
72    /// The segment that producer writes into.
73    segment: Option<ShmSegmentSpec>,
74    /// The consumers the daemon reported at upgrade time.
75    consumers: Vec<PortRef>,
76    /// Set by [`RawOutput::close`].
77    closed: bool,
78}
79
80impl core::fmt::Debug for RawOutput {
81    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
82        f.debug_struct("RawOutput")
83            .field("id", &self.id)
84            .field("plane", &self.plane())
85            .field("consumers", &self.consumers.len())
86            .field("closed", &self.closed)
87            .finish_non_exhaustive()
88    }
89}
90
91impl RawOutput {
92    /// A handle for `id` on `shared`.
93    #[must_use]
94    pub fn new(shared: Arc<SessionShared>, id: DataId) -> Self {
95        let slot = shared.routes.slot(&id);
96        Self {
97            shared,
98            id,
99            slot,
100            producer: None,
101            segment: None,
102            consumers: Vec::new(),
103            closed: false,
104        }
105    }
106
107    /// The output's id.
108    #[must_use]
109    pub const fn id(&self) -> &DataId {
110        &self.id
111    }
112
113    /// The plane this output is publishing on right now (§6.3).
114    #[must_use]
115    pub fn plane(&self) -> RoutePlane {
116        if self.producer.is_some() {
117            RoutePlane::Shm
118        } else {
119            RoutePlane::Daemon
120        }
121    }
122
123    /// The segment this output publishes into, once upgraded.
124    #[must_use]
125    pub const fn segment(&self) -> Option<&ShmSegmentSpec> {
126        self.segment.as_ref()
127    }
128
129    /// The consumers the daemon reported at upgrade time.
130    #[must_use]
131    pub fn consumers(&self) -> &[PortRef] {
132        &self.consumers
133    }
134
135    /// The byte count at or above which a payload takes the zero-copy plane.
136    #[must_use]
137    pub fn zero_copy_threshold(&self) -> u64 {
138        self.shared.zero_copy_threshold
139    }
140
141    /// Applies any pending route change (§6.3).
142    ///
143    /// Called before every publish; also public so a node can observe a
144    /// transition at a moment of its choosing.
145    pub fn refresh(&mut self) {
146        match self.slot.take() {
147            RouteUpdate::Idle => {}
148            RouteUpdate::Upgrade {
149                producer,
150                segment,
151                consumers,
152            } => {
153                self.producer = Some(*producer);
154                self.segment = Some(segment);
155                self.consumers = consumers;
156                self.slot.set_plane(RoutePlane::Shm);
157            }
158            RouteUpdate::Downgrade { .. } => {
159                // Dropping the producer closes this end of the ring; the
160                // daemon has already told the consumers.
161                self.producer = None;
162                self.segment = None;
163                self.consumers.clear();
164                self.slot.set_plane(RoutePlane::Daemon);
165            }
166        }
167    }
168
169    /// Publishes raw payload bytes, which must already be an Arrow IPC stream
170    /// (§6.1).
171    ///
172    /// # Errors
173    ///
174    /// [`NodeError::PayloadTooLarge`] over the negotiated frame budget,
175    /// [`NodeError::DaemonGone`] once the session has ended, and
176    /// [`NodeError::UnknownOutput`] after [`RawOutput::close`].
177    pub fn send_bytes(&mut self, bytes: impl AsRef<[u8]>, metadata: Metadata) -> Result<()> {
178        self.send_slice(bytes.as_ref(), metadata)
179    }
180
181    /// Encodes and publishes a record batch (§6.1).
182    ///
183    /// # Errors
184    ///
185    /// [`NodeError::Ipc`] when the batch cannot be encoded, plus whatever
186    /// [`RawOutput::send_bytes`] reports.
187    pub fn send_batch(&mut self, batch: &RecordBatch, metadata: Metadata) -> Result<()> {
188        let encoded = encode_payload(batch)?;
189        self.send_slice(encoded.as_slice(), metadata)
190    }
191
192    /// Publishes one column as a whole payload (§6.1's single-payload-column
193    /// convention).
194    ///
195    /// The shorthand behind blueprint §9.1's `send_arrow(ArrayRef)` for a
196    /// caller that already holds a single [`ArrayRef`] — including one an
197    /// arrow-rs array became through
198    /// `astrs_data::interop::from_arrow_array`, which is how an
199    /// `arrow_array::ArrayRef` reaches this output without this crate
200    /// depending on arrow-rs (see [`arrow`]'s module docs). Unfeatured,
201    /// because nothing about it needs the bridge.
202    ///
203    /// # Errors
204    ///
205    /// As [`RawOutput::send_batch`].
206    pub fn send_array(&mut self, array: ArrayRef, metadata: Metadata) -> Result<()> {
207        self.send_batch(&RecordBatch::from_payload(array), metadata)
208    }
209
210    /// Publishes an already-encoded payload.
211    ///
212    /// The one place both planes meet: everything above funnels here.
213    ///
214    /// # Errors
215    ///
216    /// As [`RawOutput::send_bytes`].
217    pub fn send_slice(&mut self, bytes: &[u8], metadata: Metadata) -> Result<()> {
218        self.check_open()?;
219        self.check_size(bytes.len())?;
220        self.refresh();
221
222        if self.should_use_shm(bytes.len())
223            && let Some(payload) = self.write_into_slot(bytes, &metadata)?
224        {
225            self.shared.count_zero_copy_send();
226            return self.publish(payload, metadata);
227        }
228        self.shared.count_inline_send();
229        self.publish(OutputPayload::inline(bytes.to_vec()), metadata)
230    }
231
232    /// Reserves `len` bytes to write into, without copying (§9.1).
233    ///
234    /// On the zero-copy plane the returned buffer *is* the ring slot; on the
235    /// daemon path it is an owned heap buffer that the same
236    /// [`OutputSample::send`] publishes inline. A node therefore writes one
237    /// code path and gets the best plane available at that instant.
238    ///
239    /// # Errors
240    ///
241    /// [`NodeError::PayloadTooLarge`] over the frame budget, and
242    /// [`NodeError::UnknownOutput`] after [`RawOutput::close`].
243    pub fn allocate(&mut self, len: usize) -> Result<OutputSample<'_>> {
244        self.check_open()?;
245        self.check_size(len)?;
246        self.refresh();
247
248        let shared = Arc::clone(&self.shared);
249        let id = self.id.clone();
250        let segment = self
251            .segment
252            .as_ref()
253            .map(|segment| (segment.name.clone(), segment.generation));
254
255        if self.should_use_shm(len)
256            && let Some(producer) = self.producer.as_mut()
257        {
258            match producer.try_allocate(len) {
259                Ok(window) => {
260                    return Ok(OutputSample::shm(window, shared, id, segment));
261                }
262                Err(_) => {
263                    // §6.2: never sleep-retry. Fall back to the heap and let
264                    // the daemon path carry it.
265                    shared.count_shm_fallback();
266                }
267            }
268        }
269        Ok(OutputSample::heap(vec![0; len], shared, id))
270    }
271
272    /// Tells the daemon this output will produce nothing further, as a
273    /// deliberate call from a node that goes on running (§7.3
274    /// [`NodeRequest::OutputDone`]).
275    ///
276    /// Idempotent.
277    ///
278    /// # What the daemon does with it, and why the spelling matters
279    ///
280    /// `OutputDone` is what blueprint §12 calls *an explicit output-close on a
281    /// live process*: the daemon tells this port's consumers
282    /// `ProducerFinished` at once, because nothing about the call predicts the
283    /// node's exit and making a live graph wait for one would stall it.
284    ///
285    /// [`RawOutput::drop`] deliberately does **not** use this spelling — see
286    /// its own documentation.
287    ///
288    /// # Errors
289    ///
290    /// [`NodeError::DaemonGone`] once the session has ended.
291    pub fn close(&mut self) -> Result<()> {
292        let request = NodeRequest::OutputDone {
293            output: self.id.clone(),
294        };
295        self.close_with(request)
296    }
297
298    /// The closure a *disappearing handle* sends: §7.3's
299    /// [`NodeRequest::CloseOutputs`], the request the protocol defines as
300    /// "what a node does as it exits".
301    ///
302    /// Idempotent, and the same local teardown as [`RawOutput::close`] — only
303    /// the frame differs, and that difference is the whole of §12's truthful
304    /// producer-failure rule: the daemon holds a teardown closure until the
305    /// reap says whether the process finished or crashed.
306    fn close_on_drop(&mut self) -> Result<()> {
307        let request = NodeRequest::CloseOutputs {
308            outputs: vec![self.id.clone()],
309        };
310        self.close_with(request)
311    }
312
313    /// Retires the local half of the output and sends `request`, once.
314    fn close_with(&mut self, request: NodeRequest) -> Result<()> {
315        if self.closed {
316            return Ok(());
317        }
318        self.closed = true;
319        if let Some(producer) = self.producer.as_mut() {
320            producer.close();
321        }
322        self.producer = None;
323        self.slot.set_plane(RoutePlane::Daemon);
324        self.shared.send_request(request)
325    }
326
327    /// Whether [`RawOutput::close`] has been called.
328    #[must_use]
329    pub const fn is_closed(&self) -> bool {
330        self.closed
331    }
332
333    /// A fresh metadata block stamped with this node's clock (§4.3).
334    #[must_use]
335    pub fn metadata(&self) -> Metadata {
336        Metadata::new(self.shared.hlc_now())
337    }
338
339    /// The session this output publishes through.
340    #[must_use]
341    pub fn session(&self) -> &Arc<SessionShared> {
342        &self.shared
343    }
344
345    /// Whether a payload of `len` bytes should take the zero-copy plane.
346    fn should_use_shm(&self, len: usize) -> bool {
347        self.producer.is_some() && len as u64 >= self.shared.zero_copy_threshold
348    }
349
350    /// Writes into a ring slot, returning the reference to publish.
351    ///
352    /// `Ok(None)` means the ring could not take it and the caller should use
353    /// the daemon path — never an error, because a full ring is a capacity
354    /// condition rather than a fault (§6.2).
355    fn write_into_slot(
356        &mut self,
357        bytes: &[u8],
358        metadata: &Metadata,
359    ) -> Result<Option<OutputPayload>> {
360        let Some((name, generation)) = self
361            .segment
362            .as_ref()
363            .map(|segment| (segment.name.clone(), segment.generation))
364        else {
365            return Ok(None);
366        };
367        let meta_bytes = encode_metadata(metadata)?;
368        let Some(producer) = self.producer.as_mut() else {
369            return Ok(None);
370        };
371        let mut window = match producer.try_allocate(bytes.len()) {
372            Ok(window) => window,
373            Err(_) => {
374                self.shared.count_shm_fallback();
375                return Ok(None);
376            }
377        };
378        let slot = window.slot_index();
379        window.as_mut_slice().copy_from_slice(bytes);
380        match window.commit(&meta_bytes) {
381            Ok(_seq) => Ok(Some(OutputPayload::Shm {
382                segment: name,
383                slot,
384                len: bytes.len() as u64,
385                generation,
386            })),
387            Err(_) => {
388                self.shared.count_shm_fallback();
389                Ok(None)
390            }
391        }
392    }
393
394    /// Hands the publish to the session.
395    fn publish(&self, payload: OutputPayload, metadata: Metadata) -> Result<()> {
396        self.shared.send_request(NodeRequest::SendMessage {
397            output: self.id.clone(),
398            metadata,
399            payload,
400        })
401    }
402
403    /// Refuses a publish on a closed output.
404    fn check_open(&self) -> Result<()> {
405        if self.closed {
406            return Err(NodeError::UnknownOutput {
407                output: self.id.clone(),
408            });
409        }
410        if self.shared.is_closed() {
411            return Err(NodeError::DaemonGone);
412        }
413        Ok(())
414    }
415
416    /// Refuses a payload the wire cannot carry.
417    fn check_size(&self, len: usize) -> Result<()> {
418        let max = self
419            .shared
420            .limits
421            .max_payload_bytes()
422            .min(astrs_data::MAX_PAYLOAD_BYTES);
423        if len > max {
424            return Err(NodeError::PayloadTooLarge { len, max });
425        }
426        Ok(())
427    }
428}
429
430impl Drop for RawOutput {
431    /// Closing an output on drop is what makes a node that simply returns
432    /// from `main` produce an `InputClosed` downstream rather than a
433    /// mysterious silence.
434    ///
435    /// It sends [`NodeRequest::CloseOutputs`] rather than
436    /// [`NodeRequest::OutputDone`], and the difference is not cosmetic. A
437    /// handle that is going away because its owner is going away carries no
438    /// evidence about *how* the process ends: a node that publishes, returns
439    /// from `main` and exits non-zero drops this handle first, and calling
440    /// that "the producer finished" tells every consumer the opposite of what
441    /// happened. §12's rule is written on exactly this distinction — the
442    /// daemon holds a teardown closure until the reap resolves the exit
443    /// status, and then closes with `ProducerCrashed` or `ProducerFinished`
444    /// accordingly. Sending the explicit spelling here would make
445    /// `ProducerCrashed` unreachable for every node that closes on the way
446    /// out, which is every node written in the §9.1 style.
447    fn drop(&mut self) {
448        let _ = self.close_on_drop();
449    }
450}
451
452/// Encodes metadata for a shared-memory slot's metadata region.
453///
454/// # Errors
455///
456/// [`NodeError::Wire`] when the metadata cannot be encoded.
457pub fn encode_metadata(metadata: &Metadata) -> Result<Vec<u8>> {
458    use astrs_wire::WireEncode;
459    Ok(metadata.encode_to_vec()?)
460}
461
462#[cfg(test)]
463mod tests {
464    #![allow(clippy::unwrap_used, clippy::expect_used, clippy::panic)]
465
466    use super::*;
467    use crate::events::{Event, EventSource, QueuedEvent};
468    use crate::payload::Payload;
469    use crate::runtime::NodeRuntime;
470    use crate::session::{OUTGOING_CAPACITY, Outgoing};
471    use astrs_data::array::{Float64Array, IntoArrayRef};
472    use astrs_time::HlcTimestamp;
473    use astrs_wire::{
474        DataflowId, DurationMs, FrameLimits, InputSpec, NodeId, NodeSource, NodeSpawnSpec,
475        OutputSpec, SessionId,
476    };
477    use tokio::sync::mpsc;
478
479    fn session() -> (Arc<SessionShared>, mpsc::Receiver<Outgoing>) {
480        let (sender, receiver) = mpsc::channel(OUTGOING_CAPACITY);
481        let spec = Arc::new(
482            NodeSpawnSpec::new(
483                DataflowId::from_u128(1),
484                NodeId::new("camera").unwrap(),
485                0,
486                NodeSource::Dynamic,
487            )
488            .with_output(OutputSpec::new(DataId::new("image").unwrap())),
489        );
490        let shared = Arc::new(SessionShared::new(
491            spec,
492            SessionId::from_u128(1),
493            sender,
494            Arc::new(EventSource::new()),
495            NodeRuntime::acquire().unwrap(),
496            4096,
497            FrameLimits::uds(),
498        ));
499        (shared, receiver)
500    }
501
502    fn output(shared: &Arc<SessionShared>) -> RawOutput {
503        RawOutput::new(Arc::clone(shared), DataId::new("image").unwrap())
504    }
505
506    fn take_send(receiver: &mut mpsc::Receiver<Outgoing>) -> (Metadata, OutputPayload) {
507        loop {
508            let Ok(Outgoing::Request(request)) = receiver.try_recv() else {
509                panic!("expected a request");
510            };
511            if let NodeRequest::SendMessage {
512                metadata, payload, ..
513            } = *request
514            {
515                return (metadata, payload);
516            }
517        }
518    }
519
520    /// §11.3 end to end: publishing through the real
521    /// [`RawOutput::send_bytes`] → [`SessionShared::send_request`] path
522    /// closes whatever input-to-output deadline measurement is open on the
523    /// session's own [`EventSource`] — the seam
524    /// [`SessionShared::send_request`]'s own docs describe.
525    #[test]
526    fn a_publish_finishes_an_open_deadline_measurement() {
527        let (shared, mut receiver) = session();
528
529        // A real, deadline-bearing input, registered exactly as
530        // `node::init::register_with` registers every `spec.inputs` entry.
531        let mut spec = InputSpec::new(
532            DataId::new("frames").unwrap(),
533            PortRef::from_parts("upstream", "frames").unwrap(),
534        );
535        // A zero budget: any real elapsed time between the input landing
536        // and the publish below is already "over", so this needs no sleep
537        // to be deterministic.
538        spec.deadline = Some(DurationMs::new(0));
539        shared.source.register_input(&spec).unwrap();
540        shared.source.push_input(
541            &spec.id,
542            QueuedEvent::Input {
543                source: PortRef::from_parts("upstream", "frames").unwrap(),
544                metadata: Metadata::new(HlcTimestamp::new(1, 0)),
545                payload: Payload::inline(vec![9]),
546            },
547        );
548        assert!(
549            shared.source.try_next().unwrap().is_input(),
550            "the input opened a measurement"
551        );
552        assert_eq!(shared.source.stats().deadline_violations, 0, "not yet");
553
554        let mut out = output(&shared);
555        out.send_bytes(vec![1, 2, 3], out.metadata()).unwrap();
556        let _ = take_send(&mut receiver);
557
558        assert_eq!(
559            shared.source.stats().deadline_violations,
560            1,
561            "the publish above must have finished the open measurement"
562        );
563        let event = shared
564            .source
565            .try_next()
566            .expect("the violation reached the control lane");
567        assert!(matches!(event, Event::Error(_)), "{event:?}");
568    }
569
570    /// The companion case: a publish with nothing open behaves exactly as
571    /// it always has — no violation appears out of nowhere.
572    #[test]
573    fn a_publish_with_no_open_deadline_is_unaffected() {
574        let (shared, mut receiver) = session();
575        let mut out = output(&shared);
576        out.send_bytes(vec![1, 2, 3], out.metadata()).unwrap();
577        let _ = take_send(&mut receiver);
578        assert_eq!(shared.source.stats().deadline_violations, 0);
579    }
580
581    #[test]
582    fn a_fresh_output_publishes_on_the_daemon_path() {
583        let (shared, mut receiver) = session();
584        let mut out = output(&shared);
585        assert_eq!(out.plane(), RoutePlane::Daemon);
586        assert_eq!(out.id().as_str(), "image");
587        assert!(out.segment().is_none());
588        assert!(out.consumers().is_empty());
589        assert_eq!(out.zero_copy_threshold(), 4096);
590
591        out.send_bytes(vec![1, 2, 3], out.metadata()).unwrap();
592        let (_, payload) = take_send(&mut receiver);
593        assert_eq!(payload.bytes(), Some(&[1, 2, 3][..]));
594        assert_eq!(shared.stats().sends_inline, 1);
595    }
596
597    #[test]
598    fn a_record_batch_is_encoded_before_it_is_sent() {
599        let (shared, mut receiver) = session();
600        let mut out = output(&shared);
601        let batch =
602            RecordBatch::from_payload(Float64Array::from_values([1.0, 2.0]).into_array_ref());
603        out.send_batch(&batch, out.metadata()).unwrap();
604        let (_, payload) = take_send(&mut receiver);
605        let bytes = payload.bytes().unwrap();
606        let decoded = astrs_data::ipc::decode_payload(bytes).unwrap();
607        assert_eq!(decoded, batch);
608    }
609
610    #[test]
611    fn allocate_falls_back_to_the_heap_without_a_producer() {
612        let (shared, mut receiver) = session();
613        let mut out = output(&shared);
614        let mut sample = out.allocate(8).unwrap();
615        assert_eq!(sample.len(), 8);
616        assert!(!sample.is_zero_copy());
617        sample.as_mut_slice().copy_from_slice(&[7; 8]);
618        let metadata = Metadata::new(shared.hlc_now());
619        sample.send(metadata).unwrap();
620
621        let (_, payload) = take_send(&mut receiver);
622        assert_eq!(payload.bytes(), Some(&[7; 8][..]));
623    }
624
625    #[test]
626    fn an_oversized_payload_is_refused_before_it_is_copied() {
627        let (shared, _receiver) = session();
628        let mut out = output(&shared);
629        let max = shared
630            .limits
631            .max_payload_bytes()
632            .min(astrs_data::MAX_PAYLOAD_BYTES);
633        let error = out.check_size(max + 1).unwrap_err();
634        assert!(matches!(error, NodeError::PayloadTooLarge { .. }));
635        assert!(out.allocate(max + 1).is_err());
636    }
637
638    #[test]
639    fn closing_is_idempotent_and_refuses_later_sends() {
640        let (shared, mut receiver) = session();
641        let mut out = output(&shared);
642        out.close().unwrap();
643        out.close().unwrap();
644        assert!(out.is_closed());
645
646        let error = out.send_bytes(vec![1], Metadata::default()).unwrap_err();
647        assert!(matches!(error, NodeError::UnknownOutput { .. }));
648
649        let mut closes = 0;
650        while let Ok(Outgoing::Request(request)) = receiver.try_recv() {
651            if matches!(*request, NodeRequest::OutputDone { .. }) {
652                closes += 1;
653            }
654        }
655        assert_eq!(closes, 1, "one OutputDone, however many close() calls");
656    }
657
658    #[test]
659    fn dropping_an_output_closes_it_as_a_teardown() {
660        // Blueprint §12: a disappearing handle sends `CloseOutputs`, not
661        // `OutputDone`, so the daemon can wait for the exit status before
662        // deciding whether the producer finished or crashed. Sending the
663        // explicit spelling here would make `ProducerCrashed` unreachable for
664        // every node that closes on the way out.
665        let (shared, mut receiver) = session();
666        let id = output(&shared).id.clone();
667        drop(output(&shared));
668        let Ok(Outgoing::Request(request)) = receiver.try_recv() else {
669            panic!("expected a request");
670        };
671        match &*request {
672            NodeRequest::CloseOutputs { outputs } => assert_eq!(outputs, &[id]),
673            other => panic!("expected CloseOutputs, got {other:?}"),
674        }
675    }
676
677    #[test]
678    fn an_explicit_close_stays_an_output_done() {
679        // The other half of the same rule: a node that closes a port and goes
680        // on running must not have its consumers wait for an exit.
681        let (shared, mut receiver) = session();
682        let mut out = output(&shared);
683        out.close().unwrap();
684        let Ok(Outgoing::Request(request)) = receiver.try_recv() else {
685            panic!("expected a request");
686        };
687        assert!(matches!(*request, NodeRequest::OutputDone { .. }));
688    }
689
690    #[test]
691    fn a_closed_session_refuses_publishing() {
692        let (shared, _receiver) = session();
693        let mut out = output(&shared);
694        shared.close();
695        assert!(matches!(
696            out.send_bytes(vec![1], Metadata::default()),
697            Err(NodeError::DaemonGone)
698        ));
699    }
700
701    #[test]
702    fn a_route_downgrade_is_picked_up_on_the_next_publish() {
703        let (shared, _receiver) = session();
704        let mut out = output(&shared);
705        shared
706            .routes
707            .slot(&DataId::new("image").unwrap())
708            .offer_downgrade(astrs_wire::RouteDowngradeReason::ConsumerDetached {
709                consumer: PortRef::from_parts("detect", "frames").unwrap(),
710            });
711        out.refresh();
712        assert_eq!(out.plane(), RoutePlane::Daemon);
713        assert!(out.segment().is_none());
714    }
715
716    #[test]
717    fn metadata_is_stamped_with_the_node_clock() {
718        let (shared, _receiver) = session();
719        let out = output(&shared);
720        let first = out.metadata();
721        let second = out.metadata();
722        assert!(second.timestamp >= first.timestamp);
723        assert!(format!("{out:?}").contains("image"));
724    }
725
726    #[test]
727    fn metadata_encodes_for_a_slot() {
728        let metadata = Metadata::default();
729        assert!(!encode_metadata(&metadata).unwrap().is_empty());
730    }
731}