astrs_node_api/output/arrow.rs
1//! `send_arrow` — publishing arrow-rs data straight onto an output
2//! (blueprint §9.1's `send_arrow(ArrayRef) [arrow-interop]`), behind this
3//! crate's `arrow-interop` feature.
4//!
5//! ```text
6//! arrow_array::RecordBatch ──TryFrom──► astrs_data::RecordBatch ──► send_batch
7//! (astrs-data's `arrow-interop` bridge)
8//! ```
9//!
10//! Nothing here re-implements a conversion: every byte of the mapping already
11//! lives in `astrs_data::interop`, and this module is the two lines that put
12//! its output on the wire.
13//!
14//! # Why the argument is generic rather than `arrow_array::ArrayRef`
15//!
16//! Because `astrs-node-api` must not become a direct parent of arrow-rs. The
17//! workspace's `deny.toml` bans the four `arrow-*` crates outright and then
18//! re-admits them through a `wrappers` list naming exactly one crate —
19//! `astrs-data` — so the whole workspace has a single, auditable arrow-rs
20//! edge (blueprint §6.1, §18.1). Adding `arrow-array` to this crate's
21//! manifest would create a second one and fail `cargo deny check bans` on any
22//! run that activates the feature.
23//!
24//! A crate that does not depend on arrow-rs cannot *name* an arrow-rs type,
25//! so the parameter is named by the **conversion** instead: any `A` for which
26//! `astrs-data`'s bridge provides `RecordBatch: TryFrom<&A>`. Today that is
27//! precisely `arrow_array::RecordBatch`, so the call site reads exactly as it
28//! would with a concrete signature —
29//!
30//! ```ignore
31//! out.send_arrow(&arrow_batch, meta)?;
32//! ```
33//!
34//! — while this crate's dependency graph stays arrow-free. A single
35//! `arrow_array::ArrayRef` reaches the same path through
36//! [`RawOutput::send_array`](crate::output::RawOutput::send_array) after
37//! `astrs_data::interop::from_arrow_array`, or by wrapping it in a one-column
38//! `arrow_array::RecordBatch`.
39//!
40//! # Why its own error type
41//!
42//! The conversion fails with `astrs_data::interop::InteropError`, which
43//! [`NodeError`] has no variant for — deliberately: `NodeError` is the
44//! *default* build's public surface, and a variant that exists only under a
45//! non-default feature would make the enum's shape feature-dependent. So the
46//! two failure modes are kept apart in [`ArrowSendError`], which is
47//! `#[error(transparent)]` on both arms: the rendered message is the
48//! underlying error's own, and `source()` reaches it, so nothing is hidden by
49//! the extra layer.
50
51use astrs_data::RecordBatch;
52use astrs_data::interop::InteropError;
53use astrs_wire::Metadata;
54
55use crate::error::NodeError;
56use crate::output::{Output, RawOutput};
57
58/// Either half of a `send_arrow` can fail: the conversion, or the send.
59///
60/// See the [module docs](self) for why this is a separate type rather than a
61/// [`NodeError`] variant.
62#[derive(Debug, thiserror::Error)]
63#[non_exhaustive]
64pub enum ArrowSendError {
65 /// The arrow-rs value could not be mapped onto AstRS's closed columnar
66 /// type set (blueprint §6.1) — an arrow `DataType` outside the P0 set, a
67 /// non-nanosecond timestamp, and so on.
68 #[error(transparent)]
69 Interop(#[from] InteropError),
70
71 /// The converted batch could not be published.
72 #[error(transparent)]
73 Send(#[from] NodeError),
74}
75
76/// Result alias for the `send_arrow` family.
77pub type ArrowSendResult<T = ()> = core::result::Result<T, ArrowSendError>;
78
79/// Converts `value` through `astrs-data`'s arrow bridge and publishes the
80/// result on `raw`.
81///
82/// The one implementation both [`RawOutput::send_arrow`] and
83/// [`Output::send_arrow`] call.
84fn send_arrow_through<A>(raw: &mut RawOutput, value: &A, metadata: Metadata) -> ArrowSendResult<()>
85where
86 A: ?Sized,
87 for<'a> RecordBatch: TryFrom<&'a A, Error = InteropError>,
88{
89 let batch = RecordBatch::try_from(value)?;
90 raw.send_batch(&batch, metadata)?;
91 Ok(())
92}
93
94impl RawOutput {
95 /// Publishes an arrow-rs value (blueprint §9.1's `send_arrow`).
96 ///
97 /// `A` is any type `astrs-data`'s `arrow-interop` bridge can convert into
98 /// a [`RecordBatch`] — in practice `arrow_array::RecordBatch`. See the
99 /// [module docs](self) for why the bound is written that way instead of
100 /// naming the arrow type.
101 ///
102 /// # Errors
103 ///
104 /// [`ArrowSendError::Interop`] when the arrow value's layout has no AstRS
105 /// counterpart, [`ArrowSendError::Send`] for whatever
106 /// [`RawOutput::send_batch`] reports.
107 #[cfg_attr(docsrs, doc(cfg(feature = "arrow-interop")))]
108 pub fn send_arrow<A>(&mut self, value: &A, metadata: Metadata) -> ArrowSendResult<()>
109 where
110 A: ?Sized,
111 for<'a> RecordBatch: TryFrom<&'a A, Error = InteropError>,
112 {
113 send_arrow_through(self, value, metadata)
114 }
115}
116
117impl<T> Output<T> {
118 /// Publishes an arrow-rs value, bypassing the type.
119 ///
120 /// As [`RawOutput::send_arrow`]; the typed skin offers it for the same
121 /// reason it offers [`Output::send_batch`] — a typed handle should not be
122 /// a reason to go and fetch the raw one.
123 ///
124 /// # Errors
125 ///
126 /// As [`RawOutput::send_arrow`].
127 #[cfg_attr(docsrs, doc(cfg(feature = "arrow-interop")))]
128 pub fn send_arrow<A>(&mut self, value: &A, metadata: Metadata) -> ArrowSendResult<()>
129 where
130 A: ?Sized,
131 for<'a> RecordBatch: TryFrom<&'a A, Error = InteropError>,
132 {
133 send_arrow_through(self.raw_mut(), value, metadata)
134 }
135}