Skip to main content

astrs_operator_api/
output.rs

1//! [`OpOutput`] — the buffered send side of an [`crate::Operator`].
2//!
3//! An operator does not hold a live connection to the daemon; it hands
4//! finished messages to `out: &mut OpOutput` inside
5//! [`crate::Operator::on_event`] (and the lifecycle hooks), and the runtime
6//! host drains the buffer after the call returns (blueprint §9.3's "each
7//! operator runs on its own thread over a bounded channel" — the buffer is
8//! what crosses that channel). Every buffered send already carries Arrow
9//! IPC-encoded bytes, matching the wire's own `NodeEvent::Input { payload:
10//! Vec<u8>, .. }` convention (blueprint §6.1), so the host never has to
11//! re-encode what an operator already finished.
12
13use astrs_data::ipc::encode_payload;
14use astrs_data::{AstrsMessage, RecordBatch};
15use astrs_wire::{DataId, Metadata};
16
17use crate::error::{OpError, OpResult};
18
19/// One buffered send, ready for the runtime host to deliver.
20#[derive(Debug, Clone, PartialEq)]
21pub struct OpSend {
22    id: DataId,
23    metadata: Metadata,
24    payload: Vec<u8>,
25}
26
27impl OpSend {
28    /// The output this send targets.
29    #[must_use]
30    pub const fn id(&self) -> &DataId {
31        &self.id
32    }
33
34    /// The metadata riding beside the payload.
35    #[must_use]
36    pub const fn metadata(&self) -> &Metadata {
37        &self.metadata
38    }
39
40    /// The encoded payload bytes (an Arrow IPC stream).
41    #[must_use]
42    pub fn payload(&self) -> &[u8] {
43        &self.payload
44    }
45
46    /// Consumes the send, returning its three parts.
47    #[must_use]
48    pub fn into_parts(self) -> (DataId, Metadata, Vec<u8>) {
49        (self.id, self.metadata, self.payload)
50    }
51}
52
53/// The buffered output side an [`crate::Operator`] writes through.
54///
55/// Sends accumulate in the order they were made and are read out with
56/// [`OpOutput::drain`]; nothing is delivered until the host does that, so an
57/// operator can call `send`/`send_batch`/`send_bytes` any number of times
58/// within one [`crate::Operator::on_event`] call without touching a
59/// connection.
60///
61/// ```
62/// use astrs_data::prelude::*;
63/// use astrs_operator_api::OpOutput;
64/// use astrs_time::HlcTimestamp;
65/// use astrs_wire::Metadata;
66///
67/// #[derive(Debug, PartialEq)]
68/// struct Ping;
69///
70/// impl astrs_data::AstrsMessage for Ping {
71///     const URN: &'static str = "std/core/v1/PingMsg";
72///     fn data_type() -> DataType {
73///         DataType::strukt([Field::required("tick", DataType::UInt8)])
74///     }
75///     fn to_record_batch(&self) -> astrs_data::Result<RecordBatch> {
76///         let DataType::Struct(fields) = Self::data_type() else { unreachable!() };
77///         let column = UInt8Array::from_values([1u8]).into_array_ref();
78///         let strukt = StructArray::try_new(fields, vec![column], None)?;
79///         Ok(RecordBatch::from_payload(strukt.into_array_ref()))
80///     }
81///     fn from_record_batch(_: &RecordBatch) -> astrs_data::Result<Self> {
82///         Ok(Self)
83///     }
84/// }
85///
86/// let mut out = OpOutput::new();
87/// assert!(out.is_empty());
88/// out.send("tick", Metadata::new(HlcTimestamp::EPOCH), &Ping)?;
89/// assert_eq!(out.len(), 1);
90///
91/// let sends = out.drain();
92/// assert_eq!(sends[0].id().as_str(), "tick");
93/// assert!(out.is_empty(), "drain empties the buffer");
94/// # Ok::<(), Box<dyn std::error::Error>>(())
95/// ```
96#[derive(Debug, Default)]
97pub struct OpOutput {
98    pending: Vec<OpSend>,
99}
100
101impl OpOutput {
102    /// An empty output buffer.
103    #[must_use]
104    pub fn new() -> Self {
105        Self {
106            pending: Vec::new(),
107        }
108    }
109
110    /// Buffers a send of already-encoded bytes.
111    ///
112    /// The escape hatch for a payload an operator built itself (or is
113    /// forwarding unchanged from an input) — `send`/`send_batch` are the
114    /// typed front doors that end up calling this.
115    ///
116    /// # Errors
117    ///
118    /// [`OpError::InvalidOutputId`] when `id` is not a valid
119    /// [`astrs_wire::DataId`].
120    pub fn send_bytes(&mut self, id: &str, metadata: Metadata, payload: Vec<u8>) -> OpResult<()> {
121        let id = DataId::new(id).map_err(|source| OpError::invalid_output_id(id, source))?;
122        self.pending.push(OpSend {
123            id,
124            metadata,
125            payload,
126        });
127        Ok(())
128    }
129
130    /// Buffers a send of an already-built [`RecordBatch`].
131    ///
132    /// # Errors
133    ///
134    /// [`OpError::InvalidOutputId`] as [`OpOutput::send_bytes`], or
135    /// [`OpError::Ipc`] when Arrow IPC encoding fails (blueprint §6.1's
136    /// 256 MB payload cap, for example).
137    pub fn send_batch(
138        &mut self,
139        id: &str,
140        metadata: Metadata,
141        batch: &RecordBatch,
142    ) -> OpResult<()> {
143        let bytes = encode_payload(batch)?.to_vec();
144        self.send_bytes(id, metadata, bytes)
145    }
146
147    /// Buffers a send of a typed [`AstrsMessage`] value.
148    ///
149    /// Encodes `message` to its one-row [`RecordBatch`] and then to Arrow
150    /// IPC bytes — the same two steps a hand-written `send_batch` call
151    /// would make, saved for the common case of sending a
152    /// `#[derive(AstrsMessage)]` type directly.
153    ///
154    /// # Errors
155    ///
156    /// [`OpError::InvalidOutputId`] as [`OpOutput::send_bytes`],
157    /// [`OpError::Encode`] when [`AstrsMessage::to_record_batch`] fails, or
158    /// [`OpError::Ipc`] as [`OpOutput::send_batch`].
159    pub fn send<M: AstrsMessage>(
160        &mut self,
161        id: &str,
162        metadata: Metadata,
163        message: &M,
164    ) -> OpResult<()> {
165        let batch = message.to_record_batch()?;
166        self.send_batch(id, metadata, &batch)
167    }
168
169    /// Removes and returns every buffered send, oldest first.
170    pub fn drain(&mut self) -> Vec<OpSend> {
171        std::mem::take(&mut self.pending)
172    }
173
174    /// Number of buffered sends.
175    #[must_use]
176    pub fn len(&self) -> usize {
177        self.pending.len()
178    }
179
180    /// Whether nothing has been buffered (or everything was drained).
181    #[must_use]
182    pub fn is_empty(&self) -> bool {
183        self.pending.is_empty()
184    }
185}
186
187#[cfg(test)]
188mod tests {
189    #![allow(clippy::unwrap_used, clippy::expect_used, clippy::panic)]
190
191    use super::*;
192    use astrs_data::prelude::*;
193    use astrs_time::HlcTimestamp;
194
195    #[derive(Debug, PartialEq)]
196    struct Ping {
197        tick: u8,
198    }
199
200    impl AstrsMessage for Ping {
201        const URN: &'static str = "std/core/v1/PingMsg";
202
203        fn data_type() -> DataType {
204            DataType::strukt([Field::required("tick", DataType::UInt8)])
205        }
206
207        fn to_record_batch(&self) -> astrs_data::Result<RecordBatch> {
208            let DataType::Struct(fields) = Self::data_type() else {
209                unreachable!()
210            };
211            let column = UInt8Array::from_values([self.tick]).into_array_ref();
212            let strukt = StructArray::try_new(fields, vec![column], None)?;
213            Ok(RecordBatch::from_payload(strukt.into_array_ref()))
214        }
215
216        fn from_record_batch(batch: &RecordBatch) -> astrs_data::Result<Self> {
217            let column =
218                batch
219                    .payload_column()
220                    .ok_or(astrs_data::DataError::ColumnCountMismatch {
221                        fields: 1,
222                        columns: 0,
223                    })?;
224            let strukt = column.try_downcast::<StructArray>()?;
225            let tick = strukt.columns()[0]
226                .try_downcast::<UInt8Array>()?
227                .get(0)
228                .ok_or(astrs_data::DataError::RequiredFieldIsNull {
229                    field: "tick".to_owned(),
230                    row: 0,
231                })?;
232            Ok(Self { tick })
233        }
234    }
235
236    fn meta() -> Metadata {
237        Metadata::new(HlcTimestamp::EPOCH)
238    }
239
240    #[test]
241    fn new_output_is_empty() {
242        let out = OpOutput::new();
243        assert!(out.is_empty());
244        assert_eq!(out.len(), 0);
245    }
246
247    #[test]
248    fn send_bytes_buffers_and_drain_empties() {
249        let mut out = OpOutput::new();
250        out.send_bytes("frames", meta(), vec![1, 2, 3]).unwrap();
251        assert_eq!(out.len(), 1);
252        assert!(!out.is_empty());
253
254        let sends = out.drain();
255        assert_eq!(sends.len(), 1);
256        assert_eq!(sends[0].id().as_str(), "frames");
257        assert_eq!(sends[0].payload(), &[1, 2, 3]);
258        assert!(out.is_empty(), "drain empties the buffer");
259    }
260
261    #[test]
262    fn send_bytes_rejects_an_invalid_id() {
263        let mut out = OpOutput::new();
264        let err = out.send_bytes("bad id", meta(), vec![]).unwrap_err();
265        assert!(matches!(err, OpError::InvalidOutputId { .. }));
266        assert!(out.is_empty());
267    }
268
269    #[test]
270    fn send_batch_encodes_a_record_batch() {
271        let mut out = OpOutput::new();
272        let batch = Ping { tick: 7 }.to_record_batch().unwrap();
273        out.send_batch("tick", meta(), &batch).unwrap();
274        let sends = out.drain();
275        assert_eq!(sends.len(), 1);
276
277        let decoded = astrs_data::ipc::decode_payload(sends[0].payload()).unwrap();
278        assert_eq!(Ping::from_record_batch(&decoded).unwrap(), Ping { tick: 7 });
279    }
280
281    #[test]
282    fn send_encodes_a_typed_message_round_trippably() {
283        let mut out = OpOutput::new();
284        out.send("tick", meta(), &Ping { tick: 42 }).unwrap();
285        let sends = out.drain();
286
287        let decoded = astrs_data::ipc::decode_payload(sends[0].payload()).unwrap();
288        assert_eq!(
289            Ping::from_record_batch(&decoded).unwrap(),
290            Ping { tick: 42 }
291        );
292        assert_eq!(sends[0].metadata(), &meta());
293    }
294
295    #[test]
296    fn multiple_sends_accumulate_in_order() {
297        let mut out = OpOutput::new();
298        out.send_bytes("a", meta(), vec![1]).unwrap();
299        out.send_bytes("b", meta(), vec![2]).unwrap();
300        out.send_bytes("c", meta(), vec![3]).unwrap();
301        let sends = out.drain();
302        let ids: Vec<&str> = sends.iter().map(|s| s.id().as_str()).collect();
303        assert_eq!(ids, ["a", "b", "c"]);
304    }
305
306    #[test]
307    fn into_parts_returns_the_three_fields() {
308        let mut out = OpOutput::new();
309        out.send_bytes("x", meta(), vec![7]).unwrap();
310        let (id, metadata, payload) = out.drain().remove(0).into_parts();
311        assert_eq!(id.as_str(), "x");
312        assert_eq!(metadata, meta());
313        assert_eq!(payload, vec![7]);
314    }
315}