astrs_node_api/session/routes.rs
1//! The slow-start route handshake, node side (blueprint §6.3).
2//!
3//! > Every output starts on the **reliable daemon path**. When the daemon has
4//! > confirmed that *all* static same-host consumers attached to the ring […]
5//! > it issues `RouteUpgrade` to the producer, which switches to direct SHM
6//! > publishing. Any consumer crash/downgrade flips the route back.
7//!
8//! Two things have to be true for that to be safe, and this module is where
9//! both are arranged:
10//!
11//! 1. **No message may fall between the planes.** The daemon keeps brokering
12//! the route until it sees `RouteUpgradeAck`, so the node acknowledges
13//! *after* it has opened the segment, never before.
14//! 2. **A producer belongs to exactly one writer.** `astrs-shm` enforces one
15//! [`astrs_shm::Producer`] per mapping, and its `allocate` needs
16//! `&mut`. So the producer is *handed off* through a [`RouteSlot`] to the
17//! output handle that owns it, rather than shared behind a lock — which is
18//! also what makes `allocate(len) -> SampleMut` expressible at all (§9.1).
19//!
20//! ```text
21//! reader task RouteSlot RawOutput
22//! ─────────── ───────── ─────────
23//! RouteUpgrade ──► Upgrade(Producer) ──► takes it, publishes zero-copy
24//! RouteDowngrade──► Downgrade ──► drops it, back to the daemon
25//! ```
26//!
27//! # This is the producer end; [`super::inputs`] is the other one
28//!
29//! Everything here is the **producer** side: the upgrade is accepted or
30//! refused, the producer is handed off, the downgrade takes the output back.
31//!
32//! The consumer side used to have no counterpart, because the frozen §24.1
33//! family had no message for it — [`astrs_wire::NodeEvent::RouteUpgrade`] names
34//! an `output: DataId`, which a consumer cannot act on, since what moves for a
35//! consumer is an **input**. §7.2's append-only rule made the fix a tail
36//! append rather than a break, and
37//! [`astrs_wire::NodeEvent::InputRouteUpgrade`] /
38//! [`astrs_wire::NodeEvent::InputRouteDowngrade`] are it. [`super::inputs`]
39//! acts on them: it attaches the segment, reads samples in place and detaches
40//! on any fault, so a consumer needs no more code than a producer does.
41//!
42//! The two ends are sequenced, and the order matters: the consumer is told
43//! first, because §6.3 only offers the producer its upgrade once the daemon has
44//! *observed* every consumer in the segment's consumer table — which cannot
45//! happen before one attaches.
46//!
47//! # How the mapping is obtained
48//!
49//! Through the daemon's **segment broker**, whose socket travels in
50//! [`astrs_wire::NodeConfig::shm_broker`] and reaches this module as
51//! [`crate::session::SessionShared::shm_broker`]. §6.2 puts the daemon in that
52//! position deliberately ("the daemon *knows* attachment state because it
53//! brokers the segment fds"), and it is also the only path that works
54//! everywhere: a segment created with the default
55//! [`astrs_shm::Backing::Auto`] is an anonymous `memfd` on Linux, with no name
56//! for [`astrs_shm::Segment::open_named`] to open. Opening by name remains the
57//! fallback for a node whose daemon published no broker — the in-process test
58//! harness, and any embedder that disabled the plane socket.
59//!
60//! The name the daemon sends is the segment's **canonical** identity
61//! (`{dataflow}/{node}/{output}/{generation}` — what
62//! [`astrs_wire::ShmSegmentSpec::name`] documents itself to carry); the hashed
63//! short name `shm_open` takes is derived from the key here, where it is
64//! needed, and never travels on the wire.
65//!
66//! # When the segment cannot be opened
67//!
68//! The node answers `RouteUpgradeAck { accepted: false, reason }` and stays on
69//! the daemon path. That is the honest outcome — a node that cannot map the
70//! segment (a permissions problem, a stale generation, a platform without the
71//! plane) must not pretend otherwise, and §6.2's rule is *never sleep-retry*.
72
73use std::collections::HashMap;
74use std::path::Path;
75use std::sync::atomic::{AtomicU64, Ordering};
76use std::sync::{Arc, Mutex, MutexGuard};
77
78use astrs_shm::{Producer, Segment, SegmentClient, SegmentKey};
79use astrs_wire::{DataId, DataflowId, NodeId, PortRef, RouteDowngradeReason, ShmSegmentSpec};
80
81use crate::error::{NodeError, Result};
82
83/// Which plane an output publishes on right now.
84#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
85#[non_exhaustive]
86pub enum RoutePlane {
87 /// The reliable path: payloads ride the daemon connection (§6.3's
88 /// starting state).
89 Daemon,
90 /// The zero-copy path: payloads are written straight into a ring slot.
91 Shm,
92}
93
94impl RoutePlane {
95 /// A stable name for metrics labels.
96 #[must_use]
97 pub const fn as_str(self) -> &'static str {
98 match self {
99 Self::Daemon => "daemon",
100 Self::Shm => "shm",
101 }
102 }
103
104 /// Whether publishing on this plane copies nothing.
105 #[must_use]
106 pub const fn is_zero_copy(self) -> bool {
107 matches!(self, Self::Shm)
108 }
109}
110
111impl core::fmt::Display for RoutePlane {
112 fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
113 f.write_str(self.as_str())
114 }
115}
116
117/// A route change waiting to be picked up by the output handle that owns the
118/// route.
119#[derive(Debug)]
120pub enum RouteUpdate {
121 /// Nothing has changed since the handle last looked.
122 Idle,
123 /// Switch to the zero-copy plane with this producer (§6.3).
124 Upgrade {
125 /// The producer, already opened and verified.
126 producer: Box<Producer>,
127 /// The segment it writes into.
128 segment: ShmSegmentSpec,
129 /// The consumers the daemon says are attached.
130 consumers: Vec<PortRef>,
131 },
132 /// Go back to the daemon path.
133 Downgrade {
134 /// Why.
135 reason: RouteDowngradeReason,
136 },
137}
138
139impl RouteUpdate {
140 /// Whether this update leaves the plane unchanged.
141 #[must_use]
142 pub const fn is_idle(&self) -> bool {
143 matches!(self, Self::Idle)
144 }
145}
146
147/// The hand-off point for one output's route.
148///
149/// The reader task writes; the output handle reads and takes. A slot never
150/// holds more than one pending update — a downgrade that lands on top of an
151/// unclaimed upgrade replaces it, which is correct: the daemon's latest word
152/// is the one that matters.
153#[derive(Debug)]
154pub struct RouteSlot {
155 /// The pending update.
156 pending: Mutex<RouteUpdate>,
157 /// The plane the handle is currently publishing on.
158 plane: Mutex<RoutePlane>,
159 /// How many upgrades this route has seen.
160 upgrades: AtomicU64,
161 /// How many downgrades this route has seen.
162 downgrades: AtomicU64,
163}
164
165impl Default for RouteSlot {
166 fn default() -> Self {
167 Self::new()
168 }
169}
170
171impl RouteSlot {
172 /// A slot on the daemon path with nothing pending.
173 #[must_use]
174 pub fn new() -> Self {
175 Self {
176 pending: Mutex::new(RouteUpdate::Idle),
177 plane: Mutex::new(RoutePlane::Daemon),
178 upgrades: AtomicU64::new(0),
179 downgrades: AtomicU64::new(0),
180 }
181 }
182
183 /// Publishes an upgrade for the owning handle to pick up.
184 pub fn offer_upgrade(
185 &self,
186 producer: Producer,
187 segment: ShmSegmentSpec,
188 consumers: Vec<PortRef>,
189 ) {
190 *lock(&self.pending) = RouteUpdate::Upgrade {
191 producer: Box::new(producer),
192 segment,
193 consumers,
194 };
195 self.upgrades.fetch_add(1, Ordering::Relaxed);
196 }
197
198 /// Publishes a downgrade for the owning handle to pick up.
199 pub fn offer_downgrade(&self, reason: RouteDowngradeReason) {
200 *lock(&self.pending) = RouteUpdate::Downgrade { reason };
201 self.downgrades.fetch_add(1, Ordering::Relaxed);
202 }
203
204 /// Takes whatever is pending, leaving the slot idle.
205 #[must_use]
206 pub fn take(&self) -> RouteUpdate {
207 core::mem::replace(&mut lock(&self.pending), RouteUpdate::Idle)
208 }
209
210 /// Whether an update is waiting.
211 #[must_use]
212 pub fn has_update(&self) -> bool {
213 !lock(&self.pending).is_idle()
214 }
215
216 /// The plane the owning handle reports it is publishing on.
217 #[must_use]
218 pub fn plane(&self) -> RoutePlane {
219 *lock(&self.plane)
220 }
221
222 /// Records the plane the owning handle switched to.
223 pub fn set_plane(&self, plane: RoutePlane) {
224 *lock(&self.plane) = plane;
225 }
226
227 /// How many upgrades and downgrades this route has seen.
228 #[must_use]
229 pub fn transitions(&self) -> (u64, u64) {
230 (
231 self.upgrades.load(Ordering::Relaxed),
232 self.downgrades.load(Ordering::Relaxed),
233 )
234 }
235}
236
237/// Every output's route slot, keyed by output id.
238#[derive(Debug, Default)]
239pub struct RouteTable {
240 /// The slots.
241 slots: Mutex<HashMap<DataId, Arc<RouteSlot>>>,
242}
243
244impl RouteTable {
245 /// An empty table.
246 #[must_use]
247 pub fn new() -> Self {
248 Self {
249 slots: Mutex::new(HashMap::new()),
250 }
251 }
252
253 /// The slot for `output`, creating it if this is the first look.
254 #[must_use]
255 pub fn slot(&self, output: &DataId) -> Arc<RouteSlot> {
256 let mut slots = lock(&self.slots);
257 Arc::clone(
258 slots
259 .entry(output.clone())
260 .or_insert_with(|| Arc::new(RouteSlot::new())),
261 )
262 }
263
264 /// The slot for `output`, if one exists.
265 #[must_use]
266 pub fn existing(&self, output: &DataId) -> Option<Arc<RouteSlot>> {
267 lock(&self.slots).get(output).map(Arc::clone)
268 }
269
270 /// The plane every known output is publishing on.
271 #[must_use]
272 pub fn planes(&self) -> Vec<(DataId, RoutePlane)> {
273 let mut planes: Vec<(DataId, RoutePlane)> = lock(&self.slots)
274 .iter()
275 .map(|(id, slot)| (id.clone(), slot.plane()))
276 .collect();
277 planes.sort_by(|left, right| left.0.cmp(&right.0));
278 planes
279 }
280
281 /// How many outputs are on the zero-copy plane.
282 #[must_use]
283 pub fn upgraded_count(&self) -> usize {
284 lock(&self.slots)
285 .values()
286 .filter(|slot| slot.plane().is_zero_copy())
287 .count()
288 }
289}
290
291/// Opens the segment a [`RouteUpgrade`](astrs_wire::NodeEvent::RouteUpgrade)
292/// names and claims it as this node's producer.
293///
294/// The segment's identity is checked twice over: the name the daemon sent must
295/// be the one the key derived from *this* node's own
296/// `(dataflow, node, output, generation)` describes, and the mapped header's
297/// digest and generation must match that key too. A stale segment from a
298/// previous incarnation therefore cannot be written into, which is the §6.2
299/// crash-safety property from the producer's side.
300///
301/// # How the mapping is obtained
302///
303/// Through the daemon's segment broker when there is one — `broker` is the
304/// socket path from [`astrs_wire::NodeConfig::shm_broker`] — because that is
305/// the path §6.2 specifies ("the daemon **knows** attachment state because it
306/// brokers the segment fds") and the only one that works on every platform: a
307/// segment created with the default [`astrs_shm::Backing::Auto`] is an
308/// anonymous `memfd` on Linux, with no name to open at all. Opening by name is
309/// kept as the fallback for a node whose daemon published no broker (the
310/// in-process test harness, and any embedder that disabled the plane socket).
311///
312/// # Errors
313///
314/// [`NodeError::Shm`] when the segment cannot be opened, verified or claimed,
315/// and [`NodeError::Pattern`] when the daemon's name does not describe the key
316/// this node would derive.
317pub fn open_producer(
318 dataflow: DataflowId,
319 node: &NodeId,
320 output: &DataId,
321 segment: &ShmSegmentSpec,
322 broker: Option<&Path>,
323) -> Result<Producer> {
324 let key = SegmentKey::new(dataflow, node.clone(), output.clone(), segment.generation);
325 // `ShmSegmentSpec::name` is the *canonical* identity
326 // (`{dataflow}/{node}/{output}/{generation}`, its own documentation:
327 // "embedding `{dataflow_id}/{node_id}/{generation}`"), not the hashed
328 // short name `shm_open` takes — that one is derived from the key here,
329 // where it is needed, and never travels on the wire.
330 let canonical = key.canonical();
331 if canonical != segment.name {
332 return Err(NodeError::Pattern(format!(
333 "route upgrade for `{output}` names segment `{}`, but this node's own key is `{canonical}`",
334 segment.name,
335 )));
336 }
337
338 let mapped = match broker {
339 Some(path) => SegmentClient::connect(path)?.attach(&key)?,
340 None => {
341 let name = key.os_name();
342 Segment::open_named(&name, Some(&key))?
343 }
344 };
345 Producer::new(Arc::new(mapped)).map_err(NodeError::Shm)
346}
347
348/// Locks a mutex, recovering from a poisoning panic elsewhere.
349fn lock<T>(mutex: &Mutex<T>) -> MutexGuard<'_, T> {
350 mutex
351 .lock()
352 .unwrap_or_else(std::sync::PoisonError::into_inner)
353}
354
355#[cfg(test)]
356mod tests {
357 #![allow(clippy::unwrap_used, clippy::expect_used, clippy::panic)]
358
359 use super::*;
360
361 fn output() -> DataId {
362 DataId::new("image").unwrap()
363 }
364
365 #[test]
366 fn a_fresh_route_is_on_the_daemon_path() {
367 let table = RouteTable::new();
368 let slot = table.slot(&output());
369 assert_eq!(slot.plane(), RoutePlane::Daemon);
370 assert!(!slot.has_update());
371 assert!(slot.take().is_idle());
372 assert_eq!(slot.transitions(), (0, 0));
373 assert_eq!(table.upgraded_count(), 0);
374 }
375
376 #[test]
377 fn the_table_hands_out_one_slot_per_output() {
378 let table = RouteTable::new();
379 let first = table.slot(&output());
380 let second = table.slot(&output());
381 assert!(Arc::ptr_eq(&first, &second));
382 assert!(table.existing(&output()).is_some());
383 assert!(table.existing(&DataId::new("other").unwrap()).is_none());
384 }
385
386 #[test]
387 fn downgrades_are_offered_and_taken_once() {
388 let table = RouteTable::new();
389 let slot = table.slot(&output());
390 slot.offer_downgrade(RouteDowngradeReason::ConsumerDetached {
391 consumer: PortRef::from_parts("detect", "frames").unwrap(),
392 });
393 assert!(slot.has_update());
394 assert_eq!(slot.transitions(), (0, 1));
395
396 let update = slot.take();
397 assert!(matches!(update, RouteUpdate::Downgrade { .. }));
398 assert!(!slot.has_update(), "an update is delivered once");
399 assert!(slot.take().is_idle());
400 }
401
402 #[test]
403 fn the_plane_a_handle_reports_is_remembered() {
404 let table = RouteTable::new();
405 let slot = table.slot(&output());
406 slot.set_plane(RoutePlane::Shm);
407 assert_eq!(slot.plane(), RoutePlane::Shm);
408 assert_eq!(table.upgraded_count(), 1);
409 assert_eq!(table.planes(), vec![(output(), RoutePlane::Shm)]);
410 slot.set_plane(RoutePlane::Daemon);
411 assert_eq!(table.upgraded_count(), 0);
412 }
413
414 #[test]
415 fn planes_describe_themselves() {
416 assert_eq!(RoutePlane::Daemon.as_str(), "daemon");
417 assert_eq!(RoutePlane::Shm.to_string(), "shm");
418 assert!(RoutePlane::Shm.is_zero_copy());
419 assert!(!RoutePlane::Daemon.is_zero_copy());
420 }
421
422 #[test]
423 fn a_segment_name_that_does_not_match_the_key_is_refused() {
424 let spec = ShmSegmentSpec::new("astrs-not-our-segment", 3, 8, 4096);
425 let error = open_producer(
426 DataflowId::from_u128(1),
427 &NodeId::new("camera").unwrap(),
428 &output(),
429 &spec,
430 None,
431 )
432 .unwrap_err();
433 assert!(matches!(error, NodeError::Pattern(_)), "{error}");
434 assert!(error.to_string().contains("this node's own key is"));
435 }
436
437 /// The daemon sends the *canonical* identity, which is what the node
438 /// compares against — the hashed `shm_open` name is derived locally and
439 /// never travels (see `astrs-daemon`'s `SegmentRegistry`, which fills the
440 /// spec from `SegmentKey::canonical`).
441 #[test]
442 fn the_canonical_name_is_what_the_daemon_sends() {
443 let dataflow = DataflowId::from_u128(0x7777);
444 let node = NodeId::new("camera").unwrap();
445 let key = SegmentKey::new(dataflow, node.clone(), output(), 2);
446 assert!(key.canonical().ends_with("/camera/image/2"));
447
448 // The hashed form is refused, because it is not what §6.2's wire
449 // vocabulary carries.
450 let hashed = ShmSegmentSpec::new(key.os_name().as_str(), 2, 8, 4096);
451 assert!(open_producer(dataflow, &node, &output(), &hashed, None).is_err());
452 }
453
454 #[cfg(unix)]
455 #[test]
456 fn a_real_segment_is_opened_verified_and_claimed() {
457 use astrs_shm::{Backing, SegmentConfig};
458
459 let dataflow = DataflowId::from_u128(0x5150);
460 let node = NodeId::new("camera").unwrap();
461 let key = SegmentKey::new(dataflow, node.clone(), output(), 4);
462 // Named explicitly: this test exercises the *no broker* fallback,
463 // which opens by name, and the default backing is an anonymous
464 // `memfd` on Linux with no name to open.
465 let config = SegmentConfig::new(4, 1024)
466 .unwrap()
467 .with_backing(Backing::Named);
468 let Ok(segment) = Segment::create(key.clone(), config) else {
469 // A sandbox without a usable shared-memory backing is not a test
470 // failure; the plane is an optimisation (§6.2).
471 return;
472 };
473 let spec = ShmSegmentSpec::new(key.canonical(), 4, 4, 1024);
474 let producer = open_producer(dataflow, &node, &output(), &spec, None);
475 assert!(producer.is_ok(), "{:?}", producer.err());
476
477 // A generation the node does not believe in is refused by the name
478 // check before any mapping happens.
479 let stale = ShmSegmentSpec::new(key.canonical(), 5, 4, 1024);
480 assert!(open_producer(dataflow, &node, &output(), &stale, None).is_err());
481
482 drop(producer);
483 let _ = segment.unlink();
484 }
485}