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}