Skip to main content

astrs_node_api/
payload.rs

1//! [`Payload`] — the bytes of one input, decoded only if the node looks.
2//!
3//! A payload arrives one of two ways (blueprint §6.2, §6.3):
4//!
5//! * **Inline**, as bytes the daemon put in an `astrs_wire::NodeEvent::Input`
6//!   frame — the
7//!   reliable path every route starts on, and the one small messages stay on
8//!   forever because a 200-byte pose does not repay a shared-memory slot.
9//! * **Zero-copy**, as an [`astrs_shm::Sample`] pinned in a ring slot. Nothing
10//!   was copied to get here and nothing is copied to read it: [`Payload::bytes`]
11//!   hands back the mapped region itself, 128-byte aligned per §6.1 so it is
12//!   directly usable as a SIMD source.
13//!
14//! Both are the same thing to a node: an Arrow IPC stream (§6.1). The
15//! difference is *where the bytes live*, which is why [`Payload::is_zero_copy`]
16//! exists but almost nothing else needs to care.
17//!
18//! # Where a zero-copy payload comes from
19//!
20//! From the session, without the node asking. When the daemon says an input
21//! now reads from a ring ([`astrs_wire::NodeEvent::InputRouteUpgrade`]),
22//! [`crate::session::inputs`] attaches to the segment and every message that
23//! ring carries arrives here as a [`Payload::zero_copy`]. Nothing about the
24//! node's loop changes: the same `Event::Input`, the same [`Payload::batch`],
25//! and [`Payload::is_zero_copy`] turning true.
26//!
27//! Not every message on an upgraded route is zero copy. §6.2 keeps the
28//! threshold rule — below it a payload rides the daemon's control channel —
29//! and a ring that is momentarily full falls back the same way (§6.2: *never
30//! sleep-retry*). Both arrive as [`PayloadKind::Inline`] on the same input,
31//! which is exactly why a node reads [`Payload::bytes`] and not the plane.
32//!
33//! [`Payload::zero_copy`] stays public for a caller that brokers a segment
34//! itself — a recorder replaying into a ring, an embedder outside the daemon's
35//! graph. A normal pipeline does not need it.
36//!
37//! # Decoding is lazy, and happens once
38//!
39//! A node that forwards a payload, records it, or drops it on a queue-policy
40//! decision must not pay for a decode it never uses. [`Payload::batch`] decodes
41//! on first call and caches the result in a [`OnceLock`], so:
42//!
43//! ```text
44//!   payload.bytes()      →  no decode, ever
45//!   payload.batch()      →  decodes once; later calls are a pointer read
46//!   payload.view::<T>()  →  batch(), then one typed conversion
47//! ```
48//!
49//! # Holding a zero-copy payload holds a slot
50//!
51//! A zero-copy payload pins the ring slot it points at for
52//! as long as it lives — that is what makes reading it safe, and it is also
53//! why a node that stashes payloads in a `Vec` will eventually stall its
54//! producer. [`Payload::detach`] copies out and releases the slot, which is
55//! the right move for anything that outlives the current event.
56//!
57//! # Examples
58//!
59//! ```
60//! use astrs_data::prelude::*;
61//! use astrs_node_api::Payload;
62//!
63//! let batch = RecordBatch::from_payload(Float64Array::from_values([1.5, 2.5]).into_array_ref());
64//! let bytes = encode_payload(&batch)?.to_vec();
65//!
66//! let payload = Payload::inline(bytes);
67//! assert!(!payload.is_zero_copy());
68//! assert_eq!(payload.batch()?.num_rows(), 2);
69//! assert_eq!(
70//!     payload.view::<astrs_node_api::message::ScalarRun<f64>>()?.as_slice(),
71//!     &[1.5, 2.5]
72//! );
73//! # Ok::<(), Box<dyn std::error::Error>>(())
74//! ```
75
76use std::sync::OnceLock;
77
78use astrs_data::ipc::decode_payload;
79use astrs_data::{ArrayRef, RecordBatch, SchemaHash};
80use astrs_shm::Sample;
81
82use crate::error::{NodeError, Result};
83use crate::message::FromPayload;
84
85/// Where a zero-copy payload sits in its ring (§6.2).
86///
87/// Everything needed to *prove* the bytes were never copied, which is what
88/// blueprint §21's M1 row asks a probe to demonstrate rather than assert:
89///
90/// * [`SlotLocation::is_inside_mapping`] — the payload address lies within the
91///   mapped segment, so it is not a heap buffer.
92/// * [`SlotLocation::is_at_layout_offset`] — and it lies exactly where the
93///   segment's layout puts that slot, computed from the mapping base rather
94///   than from the pointer being checked.
95/// * [`SlotLocation::slot`] and [`SlotLocation::sequence`] — which slot of the
96///   ring, and which message. Over a long run the slots must *cycle*: a
97///   copying path would hand out a fresh address every time.
98#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
99#[non_exhaustive]
100pub struct SlotLocation {
101    /// The ring slot the message occupies.
102    pub slot: u32,
103    /// The message's sequence number within the ring.
104    pub sequence: u64,
105    /// The address the payload bytes actually start at.
106    pub address: usize,
107    /// The address the segment's layout puts this slot's payload at.
108    pub layout_address: usize,
109    /// The first byte of the mapping.
110    pub mapping_base: usize,
111    /// How many bytes are mapped.
112    pub mapping_len: usize,
113}
114
115impl SlotLocation {
116    /// Whether the payload starts where the layout says this slot's payload
117    /// starts.
118    #[must_use]
119    pub const fn is_at_layout_offset(&self) -> bool {
120        self.address == self.layout_address
121    }
122
123    /// Whether the payload address is inside the mapping.
124    #[must_use]
125    pub const fn is_inside_mapping(&self) -> bool {
126        self.address >= self.mapping_base
127            && self.address < self.mapping_base.saturating_add(self.mapping_len)
128    }
129
130    /// The payload's offset from the start of the mapping.
131    ///
132    /// The portable form of "the same place": two processes map the same ring
133    /// at whatever addresses their `mmap` chose, so the *addresses* differ
134    /// between them and the offsets do not.
135    #[must_use]
136    pub const fn offset_in_mapping(&self) -> usize {
137        self.address.saturating_sub(self.mapping_base)
138    }
139}
140
141/// Where a payload's bytes live.
142#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
143#[non_exhaustive]
144pub enum PayloadKind {
145    /// Bytes owned by this process, carried on the control channel.
146    Inline,
147    /// A pinned slot in a shared-memory ring (§6.2).
148    ZeroCopy,
149}
150
151impl PayloadKind {
152    /// A stable name for metrics labels and logs.
153    #[must_use]
154    pub const fn as_str(self) -> &'static str {
155        match self {
156            Self::Inline => "inline",
157            Self::ZeroCopy => "zero_copy",
158        }
159    }
160
161    /// Whether reading this payload copies nothing.
162    #[must_use]
163    pub const fn is_zero_copy(self) -> bool {
164        matches!(self, Self::ZeroCopy)
165    }
166}
167
168impl core::fmt::Display for PayloadKind {
169    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
170        f.write_str(self.as_str())
171    }
172}
173
174/// The bytes themselves, in whichever form they arrived.
175#[derive(Debug)]
176enum PayloadSource {
177    /// Owned bytes.
178    Inline(Vec<u8>),
179    /// A pinned shared-memory slot. Dropping this releases the pin.
180    Shm(Box<Sample>),
181}
182
183/// One message's payload: raw Arrow IPC bytes plus a decode cached on demand.
184#[derive(Debug)]
185pub struct Payload {
186    /// The bytes.
187    source: PayloadSource,
188    /// The decoded batch, filled by the first [`Payload::batch`] call.
189    decoded: OnceLock<RecordBatch>,
190}
191
192impl Payload {
193    /// A payload over bytes this process owns.
194    #[must_use]
195    pub fn inline(bytes: Vec<u8>) -> Self {
196        Self {
197            source: PayloadSource::Inline(bytes),
198            decoded: OnceLock::new(),
199        }
200    }
201
202    /// An empty payload.
203    #[must_use]
204    pub fn empty() -> Self {
205        Self::inline(Vec::new())
206    }
207
208    /// A payload over a pinned shared-memory slot (§6.2).
209    ///
210    /// The slot stays pinned — and therefore unavailable to the producer —
211    /// until this payload is dropped or [`Payload::detach`]ed.
212    #[must_use]
213    pub fn zero_copy(sample: Sample) -> Self {
214        Self {
215            source: PayloadSource::Shm(Box::new(sample)),
216            decoded: OnceLock::new(),
217        }
218    }
219
220    /// A payload holding an already-decoded batch, for a node that produced
221    /// one locally (the testing harness, the replay node).
222    ///
223    /// # Errors
224    ///
225    /// [`NodeError::Data`] when the batch cannot be encoded, which is what
226    /// keeps [`Payload::bytes`] total for every payload however it was built.
227    pub fn from_batch(batch: RecordBatch) -> Result<Self> {
228        let bytes = astrs_data::ipc::encode_payload(&batch)?.to_vec();
229        let payload = Self::inline(bytes);
230        // The encode above proves the batch is well formed, so seeding the
231        // cache with it saves the round trip a later `batch()` would pay.
232        let _ = payload.decoded.set(batch);
233        Ok(payload)
234    }
235
236    /// Which plane this payload came in on.
237    #[must_use]
238    pub const fn kind(&self) -> PayloadKind {
239        match self.source {
240            PayloadSource::Inline(_) => PayloadKind::Inline,
241            PayloadSource::Shm(_) => PayloadKind::ZeroCopy,
242        }
243    }
244
245    /// Whether reading this payload copies nothing.
246    #[must_use]
247    pub const fn is_zero_copy(&self) -> bool {
248        self.kind().is_zero_copy()
249    }
250
251    /// The raw Arrow IPC bytes, without decoding anything.
252    #[must_use]
253    pub fn bytes(&self) -> &[u8] {
254        match &self.source {
255            PayloadSource::Inline(bytes) => bytes,
256            PayloadSource::Shm(sample) => sample.payload(),
257        }
258    }
259
260    /// How many bytes the payload holds.
261    #[must_use]
262    pub fn len(&self) -> usize {
263        self.bytes().len()
264    }
265
266    /// Whether the payload is empty.
267    #[must_use]
268    pub fn is_empty(&self) -> bool {
269        self.bytes().is_empty()
270    }
271
272    /// The payload's base address, for a caller that wants to assert the
273    /// §6.1 128-byte alignment contract itself.
274    #[must_use]
275    pub fn address(&self) -> usize {
276        self.bytes().as_ptr() as usize
277    }
278
279    /// Whether the payload's base address satisfies `alignment`.
280    ///
281    /// # Examples
282    ///
283    /// ```
284    /// use astrs_node_api::Payload;
285    ///
286    /// // An inline payload makes no alignment promise; a zero-copy one does.
287    /// let payload = Payload::empty();
288    /// let _ = payload.is_aligned_to(128);
289    /// ```
290    #[must_use]
291    pub fn is_aligned_to(&self, alignment: usize) -> bool {
292        alignment != 0 && alignment.is_power_of_two() && self.address().is_multiple_of(alignment)
293    }
294
295    /// Copies the bytes out.
296    #[must_use]
297    pub fn to_vec(&self) -> Vec<u8> {
298        self.bytes().to_vec()
299    }
300
301    /// Releases any shared-memory slot, copying the bytes into this process.
302    ///
303    /// A no-op for an inline payload. Call this before stashing a payload
304    /// beyond the event that delivered it: a pinned slot the producer cannot
305    /// reclaim is the one way a well-behaved consumer can stall a ring.
306    ///
307    /// The decoded batch, if one was cached, survives — it never pointed into
308    /// the mapping in the first place, since decoding copies buffers into
309    /// aligned owned memory.
310    #[must_use]
311    pub fn detach(self) -> Self {
312        match self.source {
313            PayloadSource::Inline(_) => self,
314            PayloadSource::Shm(ref sample) => {
315                let bytes = sample.payload().to_vec();
316                let decoded = self.decoded;
317                Self {
318                    source: PayloadSource::Inline(bytes),
319                    decoded,
320                }
321            }
322        }
323    }
324
325    /// The decoded record batch, decoding on the first call only.
326    ///
327    /// # Errors
328    ///
329    /// [`NodeError::Data`] when the bytes are not a valid one-batch Arrow IPC
330    /// stream (§6.1).
331    pub fn batch(&self) -> Result<&RecordBatch> {
332        if let Some(batch) = self.decoded.get() {
333            return Ok(batch);
334        }
335        let batch = decode_payload(self.bytes())?;
336        // A concurrent caller may have won the race; either value is the same
337        // decode of the same bytes, so whichever landed first is kept.
338        let _ = self.decoded.set(batch);
339        self.decoded
340            .get()
341            .ok_or(NodeError::Data(astrs_data::DataError::AllocationFailed {
342                bytes: 0,
343            }))
344    }
345
346    /// The decoded batch, consuming the payload and releasing any slot.
347    ///
348    /// # Errors
349    ///
350    /// As [`Payload::batch`].
351    pub fn into_batch(self) -> Result<RecordBatch> {
352        let Self { source, decoded } = self;
353        if let Some(batch) = decoded.into_inner() {
354            return Ok(batch);
355        }
356        let bytes = match &source {
357            PayloadSource::Inline(bytes) => bytes.as_slice(),
358            PayloadSource::Shm(sample) => sample.payload(),
359        };
360        Ok(decode_payload(bytes)?)
361    }
362
363    /// The single top-level `"data"` column of the payload (§6.1).
364    ///
365    /// # Errors
366    ///
367    /// [`NodeError::Data`] when the payload does not decode, or carries no
368    /// column at all.
369    pub fn column(&self) -> Result<&ArrayRef> {
370        let batch = self.batch()?;
371        batch
372            .payload_column()
373            .or_else(|| batch.column(0))
374            .ok_or(NodeError::Data(
375                astrs_data::DataError::ColumnCountMismatch {
376                    fields: 1,
377                    columns: 0,
378                },
379            ))
380    }
381
382    /// How many rows the payload's batch holds.
383    ///
384    /// # Errors
385    ///
386    /// As [`Payload::batch`].
387    pub fn num_rows(&self) -> Result<usize> {
388        Ok(self.batch()?.num_rows())
389    }
390
391    /// The payload's schema fingerprint (§6.1), for cheap type-drift
392    /// detection.
393    ///
394    /// # Errors
395    ///
396    /// As [`Payload::batch`].
397    pub fn schema_hash(&self) -> Result<SchemaHash> {
398        Ok(SchemaHash::of(self.batch()?.schema()))
399    }
400
401    /// Reads the payload as a typed value (§9.1 `data.view()?`).
402    ///
403    /// # Errors
404    ///
405    /// [`NodeError::Data`] when the payload does not decode, or when its
406    /// columnar layout is not the one `T` expects.
407    ///
408    /// # Examples
409    ///
410    /// ```
411    /// use astrs_node_api::message::{AstrsMessage, Scalar};
412    /// use astrs_node_api::Payload;
413    ///
414    /// let payload = Payload::from_batch(Scalar::from(42_i64).to_record_batch()?)?;
415    /// assert_eq!(payload.view::<Scalar<i64>>()?.into_inner(), 42);
416    /// # Ok::<(), Box<dyn std::error::Error>>(())
417    /// ```
418    pub fn view<T: FromPayload>(&self) -> Result<T> {
419        Ok(T::from_batch(self.batch()?)?)
420    }
421
422    /// The sequence number of the ring slot this payload occupies, when it
423    /// came in on the zero-copy plane.
424    #[must_use]
425    pub fn sequence(&self) -> Option<u64> {
426        match &self.source {
427            PayloadSource::Inline(_) => None,
428            PayloadSource::Shm(sample) => Some(sample.seq()),
429        }
430    }
431
432    /// Where this payload sits in its ring, when it came in on the zero-copy
433    /// plane (§6.2).
434    ///
435    /// `None` for an inline payload, which sits in this process's heap and has
436    /// no slot at all.
437    ///
438    /// # Examples
439    ///
440    /// ```
441    /// use astrs_node_api::Payload;
442    ///
443    /// // An inline payload occupies no ring slot.
444    /// assert!(Payload::empty().slot().is_none());
445    /// ```
446    #[must_use]
447    pub fn slot(&self) -> Option<SlotLocation> {
448        match &self.source {
449            PayloadSource::Inline(_) => None,
450            PayloadSource::Shm(sample) => Some(SlotLocation {
451                slot: sample.slot_index(),
452                sequence: sample.seq(),
453                address: sample.payload_address(),
454                layout_address: sample.layout_payload_address(),
455                mapping_base: sample.mapping_base(),
456                mapping_len: sample.mapping_len(),
457            }),
458        }
459    }
460
461    /// The metadata bytes that rode beside a zero-copy payload in its slot.
462    ///
463    /// `None` for an inline payload, whose metadata travelled in the frame as
464    /// a decoded [`astrs_wire::Metadata`] instead.
465    #[must_use]
466    pub fn slot_metadata(&self) -> Option<&[u8]> {
467        match &self.source {
468            PayloadSource::Inline(_) => None,
469            PayloadSource::Shm(sample) => Some(sample.metadata()),
470        }
471    }
472}
473
474impl AsRef<[u8]> for Payload {
475    fn as_ref(&self) -> &[u8] {
476        self.bytes()
477    }
478}
479
480impl From<Vec<u8>> for Payload {
481    fn from(bytes: Vec<u8>) -> Self {
482        Self::inline(bytes)
483    }
484}
485
486impl From<Sample> for Payload {
487    fn from(sample: Sample) -> Self {
488        Self::zero_copy(sample)
489    }
490}
491
492impl core::fmt::Display for Payload {
493    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
494        write!(f, "{} byte(s) ({})", self.len(), self.kind())
495    }
496}
497
498#[cfg(test)]
499mod tests {
500    #![allow(clippy::unwrap_used, clippy::expect_used, clippy::panic)]
501
502    use super::*;
503    use astrs_data::array::{Float64Array, IntoArrayRef};
504    use astrs_data::ipc::encode_payload;
505
506    fn sample_batch() -> RecordBatch {
507        RecordBatch::from_payload(Float64Array::from_values([1.5, 2.5, 3.5]).into_array_ref())
508    }
509
510    fn sample_bytes() -> Vec<u8> {
511        encode_payload(&sample_batch()).unwrap().to_vec()
512    }
513
514    #[test]
515    fn an_inline_payload_reports_its_bytes_without_decoding() {
516        let bytes = sample_bytes();
517        let payload = Payload::inline(bytes.clone());
518        assert_eq!(payload.kind(), PayloadKind::Inline);
519        assert!(!payload.is_zero_copy());
520        assert_eq!(payload.bytes(), bytes.as_slice());
521        assert_eq!(payload.len(), bytes.len());
522        assert!(!payload.is_empty());
523        assert_eq!(payload.to_vec(), bytes);
524        assert_eq!(payload.sequence(), None);
525        assert_eq!(payload.slot_metadata(), None);
526        assert!(payload.to_string().contains("inline"));
527    }
528
529    #[test]
530    fn decoding_happens_once_and_is_cached() {
531        let payload = Payload::inline(sample_bytes());
532        let first = payload.batch().unwrap();
533        let first_address = std::ptr::from_ref(first) as usize;
534        let second = payload.batch().unwrap();
535        assert_eq!(std::ptr::from_ref(second) as usize, first_address);
536        assert_eq!(second.num_rows(), 3);
537        assert_eq!(payload.num_rows().unwrap(), 3);
538    }
539
540    #[test]
541    fn a_payload_built_from_a_batch_skips_the_first_decode() {
542        let payload = Payload::from_batch(sample_batch()).unwrap();
543        assert_eq!(payload.batch().unwrap(), &sample_batch());
544        assert_eq!(payload.bytes(), sample_bytes().as_slice());
545        assert_eq!(payload.into_batch().unwrap(), sample_batch());
546    }
547
548    #[test]
549    fn an_empty_payload_is_empty_and_does_not_decode() {
550        let payload = Payload::empty();
551        assert!(payload.is_empty());
552        assert_eq!(payload.len(), 0);
553        assert!(payload.batch().is_err(), "no bytes is not a valid stream");
554    }
555
556    #[test]
557    fn corrupt_bytes_are_reported_not_guessed() {
558        let mut bytes = sample_bytes();
559        bytes[4] ^= 0xFF;
560        let payload = Payload::inline(bytes);
561        let error = payload.batch().unwrap_err();
562        assert_eq!(error.kind_name(), "ipc");
563    }
564
565    #[test]
566    fn the_payload_column_is_the_data_column() {
567        let payload = Payload::inline(sample_bytes());
568        let column = payload.column().unwrap();
569        assert_eq!(column.len(), 3);
570        assert_eq!(column.data_type(), &astrs_data::DataType::Float64);
571    }
572
573    #[test]
574    fn detaching_an_inline_payload_is_a_no_op() {
575        let payload = Payload::inline(sample_bytes());
576        let bytes = payload.to_vec();
577        let detached = payload.detach();
578        assert_eq!(detached.to_vec(), bytes);
579        assert_eq!(detached.kind(), PayloadKind::Inline);
580    }
581
582    #[test]
583    fn schema_hashes_agree_for_identical_layouts() {
584        let left = Payload::inline(sample_bytes());
585        let right = Payload::from_batch(sample_batch()).unwrap();
586        assert_eq!(left.schema_hash().unwrap(), right.schema_hash().unwrap());
587    }
588
589    #[test]
590    fn conversions_and_as_ref_agree_with_bytes() {
591        let bytes = sample_bytes();
592        let payload: Payload = bytes.clone().into();
593        assert_eq!(payload.as_ref(), bytes.as_slice());
594    }
595
596    #[test]
597    fn alignment_is_reported_honestly() {
598        let payload = Payload::inline(sample_bytes());
599        assert!(payload.is_aligned_to(1));
600        assert!(!payload.is_aligned_to(0), "zero is not an alignment");
601        assert!(!payload.is_aligned_to(3), "only powers of two are");
602    }
603
604    #[test]
605    fn payload_kinds_describe_themselves() {
606        assert_eq!(PayloadKind::Inline.as_str(), "inline");
607        assert_eq!(PayloadKind::ZeroCopy.as_str(), "zero_copy");
608        assert!(PayloadKind::ZeroCopy.is_zero_copy());
609        assert!(!PayloadKind::Inline.is_zero_copy());
610        assert_eq!(PayloadKind::Inline.to_string(), "inline");
611    }
612
613    #[test]
614    fn payloads_cross_thread_boundaries() {
615        const fn assert_send_sync<T: Send + Sync>() {}
616        assert_send_sync::<Payload>();
617    }
618}