Skip to main content

astrs_cli/command/
topic.rs

1//! `astrs topic echo/hz/info/pub` (blueprint §13, §17).
2//!
3//! ```text
4//!   astrs topic echo cam/frames   ─► TopicSubscribe ─► pushed `Data` frames ─► decode+print
5//!   astrs topic hz   cam/frames   ─► TopicSubscribe ─► pushed `Data` frames ─► windowed rate
6//!   astrs topic info cam/frames   ─► GetNodeInfo (+ optional --manifest)   ─► type/subscribers
7//!   astrs topic pub  src/out '1'  ─► a dynamic-node attach, one `send_batch`
8//! ```
9//!
10//! # Why `echo`/`hz` need `debug: true`
11//!
12//! A tap is a *copy* of a local output the daemon must keep seeing bytes
13//! for, which is only cheap because it is opt-in
14//! ([`crate::command::param`]'s sibling module doc has nothing to say about
15//! this — see `astrs-daemon`'s `tap` module and blueprint §13 instead). The
16//! coordinator refuses `TopicSubscribe` for a dataflow whose manifest never
17//! set `debug: true`; this module surfaces that refusal exactly as the
18//! coordinator worded it ([`crate::error::CliError::Refused`]) rather than
19//! inventing a second message.
20//!
21//! # `pub` attaches, it does not inject
22//!
23//! There is no wire verb that hands the coordinator a byte string to splice
24//! into a running edge — see `astrs-coordinator`'s `handlers::logs::topic_publish`
25//! for why that gap is deliberate. `astrs topic pub` instead does what
26//! blueprint §8.3's `path: dynamic` exists for: it connects to the local
27//! daemon *as* the named node (which the manifest must have declared with
28//! `path: dynamic`) and publishes through the ordinary node API. The
29//! "topic" a user names is therefore the *producer* port
30//! (`dynamic_node/output`), not a consumer's input — exactly the shape
31//! `astrs topic echo` already expects a port reference in.
32
33use std::collections::VecDeque;
34use std::io::Write;
35use std::time::{Duration, Instant};
36
37use astrs_data::builder::{BinaryBuilder, BooleanBuilder, Float64Builder};
38use astrs_data::ipc::decode_payload;
39use astrs_data::record_batch::RecordBatch;
40use astrs_data::urn::layout_of;
41use astrs_data::{DataType, IntoArrayRef};
42use astrs_node_api::NodeBuilder;
43use astrs_wire::{
44    ControlReply, ControlRequest, DataFrame, DataflowId, FrameKind, Metadata, NodeInfo, PortRef,
45    TopicQuery, TypeUrn, WireDecode,
46};
47
48use crate::command::client::{
49    Client, DataflowRef, Endpoint, new_subscription_id, reply_name, runtime,
50};
51use crate::command::param::parse_value as parse_parameter_value;
52use crate::command::signals::Signals;
53use crate::error::CliError;
54
55/// Arguments shared by `echo` and `hz`: a port reference, which dataflow it
56/// belongs to (defaulting to the cluster's sole one), and how to reach the
57/// coordinator.
58#[derive(Debug, Clone)]
59pub struct TopicStreamArgs {
60    /// The port to tap, as `node/output`.
61    pub topic: String,
62    /// The dataflow it belongs to; `None` means "the only one running".
63    pub dataflow: Option<String>,
64    /// Emit JSON rather than human-readable lines.
65    pub json: bool,
66    /// Stop after this many data frames instead of streaming until
67    /// interrupted (`ros2 topic echo --once` for a count of one).
68    ///
69    /// Mainly for scripts and tests: a bounded `echo`/`hz` is a function
70    /// that returns rather than a process a caller must signal, which is
71    /// what makes either one assertable without touching `SIGTERM` from a
72    /// test.
73    pub count: Option<u32>,
74}
75
76/// Parses the `node/output` shorthand every topic verb takes.
77///
78/// # Errors
79///
80/// [`CliError::BadArgument`] when the text has no separator, more than one,
81/// or either half fails the identifier grammar.
82pub fn parse_port(text: &str) -> Result<PortRef, CliError> {
83    text.parse()
84        .map_err(|error: astrs_wire::IdError| CliError::BadArgument {
85            flag: "topic",
86            value: text.to_owned(),
87            reason: error.to_string(),
88        })
89}
90
91/// Resolves which dataflow a topic verb targets: the one named, or the
92/// cluster's sole running one when none was.
93///
94/// # Errors
95///
96/// As [`Client::resolve`]/[`Client::sole_dataflow`].
97async fn resolve_dataflow(
98    client: &mut Client,
99    dataflow: Option<&str>,
100) -> Result<DataflowId, CliError> {
101    match dataflow {
102        Some(text) => client.resolve(&DataflowRef::parse(text)).await,
103        None => client.sole_dataflow(true).await,
104    }
105}
106
107/// What `echo`/`hz` did.
108#[derive(Debug, Clone, Copy, PartialEq, Eq)]
109pub struct StreamReport {
110    /// How many data frames were printed (or folded into a rate).
111    pub received: usize,
112}
113
114/// `astrs topic echo`: prints every message on a port as it arrives.
115///
116/// Runs until the coordinator closes the connection (the cluster went
117/// down), [`TopicStreamArgs::count`] frames have been printed, or the
118/// process is interrupted — at which point the subscription is closed
119/// explicitly (in the latter two cases) — the same shape as `astrs logs
120/// -f` — before this returns.
121///
122/// # Errors
123///
124/// - [`CliError::BadArgument`] for an unparsable `node/output`.
125/// - [`CliError::Refused`] when the dataflow's manifest never set
126///   `debug: true`.
127/// - As [`Client::connect`]/[`Client::request`] otherwise.
128pub fn echo(
129    out: &mut dyn Write,
130    endpoint: &Endpoint,
131    args: &TopicStreamArgs,
132) -> Result<StreamReport, CliError> {
133    let port = parse_port(&args.topic)?;
134    let runtime = runtime()?;
135    runtime.block_on(async move {
136        let mut client = Client::connect(endpoint).await?;
137        let dataflow = resolve_dataflow(&mut client, args.dataflow.as_deref()).await?;
138        let subscription = new_subscription_id();
139        client
140            .request_ok(
141                "topic echo",
142                &ControlRequest::TopicSubscribe {
143                    dataflow,
144                    port: port.clone(),
145                    query: TopicQuery::new(),
146                    subscription,
147                },
148            )
149            .await?;
150
151        let mut signals = Signals::install();
152        let mut received = 0usize;
153        let mut stopped_early = false;
154        loop {
155            tokio::select! {
156                frame = client.next_frame() => match frame? {
157                    Some(frame) => {
158                        if let Some(data) = decode_data_frame(&frame) {
159                            print_echo(out, &data, args.json);
160                            received += 1;
161                            if args.count.is_some_and(|limit| received >= limit as usize) {
162                                stopped_early = true;
163                                break;
164                            }
165                        }
166                    }
167                    None => break,
168                },
169                () = signals.next() => {
170                    stopped_early = true;
171                    break;
172                }
173            }
174        }
175        // A bound reached is the same kind of deliberate stop as an
176        // interrupt (as opposed to the coordinator closing the
177        // connection): the subscription is still live and worth ending
178        // explicitly rather than leaving it to the daemon's tap to notice
179        // this session went away.
180        if stopped_early {
181            let _ = client
182                .request_ok(
183                    "topic echo",
184                    &ControlRequest::TopicUnsubscribe { subscription },
185                )
186                .await;
187        }
188        Ok(StreamReport { received })
189    })
190}
191
192/// `astrs topic hz`: reports a port's observed message rate, recomputed
193/// every time a frame arrives from a trailing window (blueprint §17).
194///
195/// # Errors
196///
197/// As [`echo`].
198pub fn hz(
199    out: &mut dyn Write,
200    endpoint: &Endpoint,
201    args: &TopicStreamArgs,
202    window: Duration,
203) -> Result<StreamReport, CliError> {
204    let port = parse_port(&args.topic)?;
205    let runtime = runtime()?;
206    runtime.block_on(async move {
207        let mut client = Client::connect(endpoint).await?;
208        let dataflow = resolve_dataflow(&mut client, args.dataflow.as_deref()).await?;
209        let subscription = new_subscription_id();
210        client
211            .request_ok(
212                "topic hz",
213                &ControlRequest::TopicSubscribe {
214                    dataflow,
215                    port: port.clone(),
216                    query: TopicQuery::new(),
217                    subscription,
218                },
219            )
220            .await?;
221
222        let mut rate = HzWindow::new(window);
223        let mut signals = Signals::install();
224        let mut received = 0usize;
225        let mut stopped_early = false;
226        loop {
227            tokio::select! {
228                frame = client.next_frame() => match frame? {
229                    Some(frame) => {
230                        if frame.kind() == FrameKind::Data {
231                            let now = Instant::now();
232                            rate.record(now);
233                            received += 1;
234                            print_hz(out, &rate, now, args.json);
235                            if args.count.is_some_and(|limit| received >= limit as usize) {
236                                stopped_early = true;
237                                break;
238                            }
239                        }
240                    }
241                    None => break,
242                },
243                () = signals.next() => {
244                    stopped_early = true;
245                    break;
246                }
247            }
248        }
249        if stopped_early {
250            let _ = client
251                .request_ok(
252                    "topic hz",
253                    &ControlRequest::TopicUnsubscribe { subscription },
254                )
255                .await;
256        }
257        Ok(StreamReport { received })
258    })
259}
260
261/// A trailing window of arrival instants, for `astrs topic hz`'s rate math.
262///
263/// Pure and independent of any socket, so the rate computation is tested
264/// without a live cluster.
265#[derive(Debug, Clone)]
266pub struct HzWindow {
267    /// How far back an arrival still counts.
268    window: Duration,
269    /// Arrival instants, oldest first.
270    arrivals: VecDeque<Instant>,
271}
272
273impl HzWindow {
274    /// A window that keeps arrivals for `window`.
275    #[must_use]
276    pub fn new(window: Duration) -> Self {
277        Self {
278            window,
279            arrivals: VecDeque::new(),
280        }
281    }
282
283    /// Records one arrival at `now`, dropping anything that has aged out.
284    pub fn record(&mut self, now: Instant) {
285        self.arrivals.push_back(now);
286        self.evict(now);
287    }
288
289    /// Drops arrivals older than [`Self::window`] relative to `now`.
290    fn evict(&mut self, now: Instant) {
291        while let Some(&oldest) = self.arrivals.front() {
292            if now.saturating_duration_since(oldest) > self.window {
293                self.arrivals.pop_front();
294            } else {
295                break;
296            }
297        }
298    }
299
300    /// How many arrivals are currently inside the window.
301    #[must_use]
302    pub fn count(&self) -> usize {
303        self.arrivals.len()
304    }
305
306    /// The observed rate, in messages per second, as of `now`.
307    ///
308    /// `None` before any arrival, or while the observed span is too short
309    /// to divide by without an inflated result — the span used is the
310    /// window itself once at least two arrivals separate by less than it,
311    /// and the actual oldest-to-`now` span otherwise, which is what keeps
312    /// the very first arrival from reading as "infinite Hz".
313    #[must_use]
314    pub fn rate_per_sec(&self, now: Instant) -> Option<f64> {
315        let oldest = *self.arrivals.front()?;
316        let span = now
317            .saturating_duration_since(oldest)
318            .as_secs_f64()
319            .max(f64::EPSILON);
320        if self.arrivals.len() < 2 {
321            return None;
322        }
323        Some((self.arrivals.len() - 1) as f64 / span)
324    }
325}
326
327/// Prints one `astrs topic hz` update.
328fn print_hz(out: &mut dyn Write, rate: &HzWindow, now: Instant, json: bool) {
329    let value = rate.rate_per_sec(now);
330    if json {
331        let _ = writeln!(
332            out,
333            "{}",
334            serde_json::json!({ "count": rate.count(), "hz": value })
335        );
336    } else {
337        match value {
338            Some(hz) => {
339                let _ = writeln!(out, "{hz:.2} Hz ({} in window)", rate.count());
340            }
341            None => {
342                let _ = writeln!(out, "… ({} in window)", rate.count());
343            }
344        }
345    }
346    let _ = out.flush();
347}
348
349/// Decodes a pushed frame as a [`DataFrame`], returning `None` for anything
350/// that is not one — a stray `Log` push on a session that also has a log
351/// subscription open, or a malformed frame, neither of which should end an
352/// otherwise-healthy tail.
353fn decode_data_frame(frame: &astrs_wire::Frame) -> Option<DataFrame> {
354    if frame.kind() != FrameKind::Data {
355        return None;
356    }
357    DataFrame::decode_exact(frame.payload()).ok()
358}
359
360/// Builds the line (or JSON object) `echo` prints for one frame.
361fn print_echo(out: &mut dyn Write, frame: &DataFrame, json: bool) {
362    let summary = summarize_payload(&frame.payload);
363    if json {
364        let _ = writeln!(
365            out,
366            "{}",
367            serde_json::json!({
368                "source": frame.source.to_string(),
369                "bytes": frame.payload.len(),
370                "summary": summary,
371            })
372        );
373    } else {
374        let _ = writeln!(out, "[{}] {summary}", frame.source);
375    }
376    let _ = out.flush();
377}
378
379/// Summarizes a payload for a human: the Arrow schema when it decodes,
380/// raw hex otherwise (blueprint §17: "raw hex fallback").
381///
382/// Not URN-aware on its own — a bare payload carries no type marker, only
383/// its Arrow schema (blueprint §6.1) — but [`info`] resolves the port's
384/// *declared* URN separately and prints it alongside this summary, which is
385/// the honest split: what the bytes say, and what the manifest says they
386/// should be.
387#[must_use]
388pub fn summarize_payload(payload: &[u8]) -> String {
389    match decode_payload(payload) {
390        Ok(batch) => summarize_batch(&batch),
391        Err(_) => format!(
392            "{} bytes (not decodable as Arrow IPC): {}",
393            payload.len(),
394            hex(payload)
395        ),
396    }
397}
398
399/// A one-line summary of a decoded batch: row count and each column's name
400/// and Arrow type.
401fn summarize_batch(batch: &RecordBatch) -> String {
402    let columns: Vec<String> = batch
403        .schema()
404        .fields()
405        .iter()
406        .map(|field| format!("{}:{:?}", field.name(), field.data_type()))
407        .collect();
408    format!(
409        "{} row(s), {} column(s) [{}]",
410        batch.num_rows(),
411        batch.num_columns(),
412        columns.join(", ")
413    )
414}
415
416/// Renders `bytes` as lowercase hex, truncated with a marker past
417/// [`HEX_PREVIEW_LIMIT`] bytes so one giant malformed payload cannot flood
418/// a terminal.
419const HEX_PREVIEW_LIMIT: usize = 64;
420
421/// See `HEX_PREVIEW_LIMIT`.
422#[must_use]
423pub fn hex(bytes: &[u8]) -> String {
424    let shown = &bytes[..bytes.len().min(HEX_PREVIEW_LIMIT)];
425    let mut text = String::with_capacity(shown.len() * 2 + 4);
426    for byte in shown {
427        text.push_str(&format!("{byte:02x}"));
428    }
429    if bytes.len() > HEX_PREVIEW_LIMIT {
430        text.push_str("...");
431    }
432    text
433}
434
435/// `astrs topic info`: a port's declared type, its subscriber list (when a
436/// manifest is given), and a best-effort observed schema hash — obtained by
437/// opening a tap for `INFO_PEEK_TIMEOUT` and reporting whatever the first
438/// frame (if any) says, since a bare port carries no type marker of its own
439/// (blueprint §6.1).
440///
441/// # Errors
442///
443/// As [`echo`], plus manifest parse/expand/graph-build errors when
444/// `manifest_path` is given.
445pub fn info(
446    out: &mut dyn Write,
447    endpoint: &Endpoint,
448    topic: &str,
449    dataflow: Option<&str>,
450    manifest_path: Option<&std::path::Path>,
451    json: bool,
452) -> Result<InfoReport, CliError> {
453    let port = parse_port(topic)?;
454    let runtime = runtime()?;
455    let report = runtime.block_on(async move {
456        let mut client = Client::connect(endpoint).await?;
457        let dataflow_id = resolve_dataflow(&mut client, dataflow).await?;
458        let node_info = match client
459            .request(
460                "topic info",
461                &ControlRequest::GetNodeInfo {
462                    dataflow: dataflow_id,
463                    node: port.node().clone(),
464                },
465            )
466            .await?
467        {
468            ControlReply::NodeInfo { nodes } => nodes.into_iter().next(),
469            other => {
470                return Err(CliError::UnexpectedReply {
471                    request: "topic info",
472                    reply: reply_name(&other),
473                });
474            }
475        };
476        let type_urn = node_info
477            .as_ref()
478            .and_then(|info: &NodeInfo| info.outputs.get(port.port()))
479            .and_then(|urn| urn.clone());
480
481        let observed = peek_one_frame(&mut client, dataflow_id, port.clone()).await;
482        let (observed_schema, schema_hash) = match observed {
483            Some((summary, hash)) => (Some(summary), hash),
484            None => (None, None),
485        };
486        Ok(InfoReport {
487            port: port.clone(),
488            type_urn,
489            observed_schema,
490            schema_hash,
491            subscribers: manifest_path
492                .map(|path| subscribers_of(path, &port))
493                .transpose()?
494                .unwrap_or_default(),
495        })
496    })?;
497    print_info(out, &report, json);
498    Ok(report)
499}
500
501/// How long `info` waits for one tapped frame before giving up.
502const INFO_PEEK_TIMEOUT: Duration = Duration::from_millis(800);
503
504/// As [`summarize_payload`], but also returns the [`astrs_data::SchemaHash`]
505/// blueprint §6.1 defines, when the payload decodes as Arrow IPC — `info`'s
506/// own concern (`echo`/`hz` never need the hash, so `summarize_payload`
507/// itself, and every test already written against its `String`-only
508/// signature, stays exactly as it is).
509fn summarize_with_hash(payload: &[u8]) -> (String, Option<astrs_data::SchemaHash>) {
510    match astrs_data::ipc::decode_payload(payload) {
511        Ok(batch) => (
512            summarize_batch(&batch),
513            Some(astrs_data::SchemaHash::of(batch.schema())),
514        ),
515        // The same payload fails the same way through `summarize_payload`'s
516        // own decode attempt — reusing it here keeps the hex-fallback
517        // rendering defined in exactly one place.
518        Err(_) => (summarize_payload(payload), None),
519    }
520}
521
522/// Opens a short-lived tap, returns the first frame's payload summary and
523/// schema hash (if one arrives before [`INFO_PEEK_TIMEOUT`]), and always
524/// unsubscribes before returning.
525async fn peek_one_frame(
526    client: &mut Client,
527    dataflow: DataflowId,
528    port: PortRef,
529) -> Option<(String, Option<astrs_data::SchemaHash>)> {
530    let subscription = new_subscription_id();
531    client
532        .request_ok(
533            "topic info",
534            &ControlRequest::TopicSubscribe {
535                dataflow,
536                port,
537                query: TopicQuery::new(),
538                subscription,
539            },
540        )
541        .await
542        .ok()?;
543
544    let observed = tokio::time::timeout(INFO_PEEK_TIMEOUT, async {
545        loop {
546            match client.next_frame().await.ok()? {
547                Some(frame) => {
548                    if let Some(data) = decode_data_frame(&frame) {
549                        return Some(summarize_with_hash(&data.payload));
550                    }
551                }
552                None => return None,
553            }
554        }
555    })
556    .await
557    .ok()
558    .flatten();
559
560    let _ = client
561        .request_ok(
562            "topic info",
563            &ControlRequest::TopicUnsubscribe { subscription },
564        )
565        .await;
566    observed
567}
568
569/// Every `node/input` that reads from `port`, from a manifest on disk.
570///
571/// `astrs-coordinator`'s `GetManifest` (a running dataflow's *expanded*
572/// manifest) has no answering reply yet — see this crate's final report —
573/// so this reads the same manifest a user would pass to `astrs graph`
574/// rather than the live one, exactly the pattern `command::graph::run`
575/// already uses.
576///
577/// Matches [`astrs_manifest::node::io::Input::source`] textually against
578/// `port`'s own `node/output` rendering rather than building an
579/// `astrs-graph` graph — [`astrs_manifest::Node::inputs`] already *is* the
580/// edge list this needs, one `BTreeMap<String, Input>` per node, and going
581/// through it directly avoids a second identifier system
582/// (`astrs-graph::NodeId`/`PortName` wrap the same strings independently,
583/// precisely so this crate's callers cannot mix the two up by accident —
584/// which also means there is no free conversion the other way).
585///
586/// # Errors
587///
588/// As `command::graph::run`'s manifest pipeline.
589fn subscribers_of(path: &std::path::Path, port: &PortRef) -> Result<Vec<PortRef>, CliError> {
590    let content = std::fs::read_to_string(path).map_err(|err| CliError::io(path, err))?;
591    let manifest = astrs_manifest::Manifest::from_yaml_str(&content)?;
592    manifest.validate()?;
593    let base_dir = path
594        .parent()
595        .map(std::path::Path::to_path_buf)
596        .unwrap_or_default();
597    let loader = astrs_manifest::expand::FsModuleLoader;
598    let expanded = manifest.expand(&base_dir, &loader)?;
599    expanded.validate()?;
600
601    let wanted = port.to_string();
602    let mut subscribers = Vec::new();
603    for node in &expanded.nodes {
604        let Ok(consumer) = astrs_wire::NodeId::new(&node.id) else {
605            continue;
606        };
607        for (input_name, input) in &node.inputs {
608            if input.source != wanted {
609                continue;
610            }
611            if let Ok(input_id) = astrs_wire::DataId::new(input_name) {
612                subscribers.push(PortRef::new(consumer.clone(), input_id));
613            }
614        }
615    }
616    Ok(subscribers)
617}
618
619/// `astrs topic info`'s report.
620#[derive(Debug, Clone)]
621pub struct InfoReport {
622    /// The port inspected.
623    pub port: PortRef,
624    /// Its declared type, when the manifest annotated it.
625    pub type_urn: Option<TypeUrn>,
626    /// A summary of one observed frame's actual Arrow schema, when one
627    /// arrived inside `INFO_PEEK_TIMEOUT`.
628    pub observed_schema: Option<String>,
629    /// That frame's [`astrs_data::SchemaHash`] (blueprint §6.1) — the same
630    /// fingerprint a real receiver caches decoded schemas against, so this
631    /// is not only a summary but the literal identity a `_schema_hash`
632    /// metadata entry would carry. `None` exactly when `observed_schema`
633    /// is `None`, or when a frame arrived but was not decodable as Arrow
634    /// IPC (raw bytes have no schema to hash).
635    pub schema_hash: Option<astrs_data::SchemaHash>,
636    /// Every `node/input` wired from this port, when `--manifest` was
637    /// given; empty otherwise.
638    pub subscribers: Vec<PortRef>,
639}
640
641/// Prints an [`InfoReport`].
642fn print_info(out: &mut dyn Write, report: &InfoReport, json: bool) {
643    if json {
644        let _ = writeln!(
645            out,
646            "{}",
647            serde_json::json!({
648                "port": report.port.to_string(),
649                "type_urn": report.type_urn.as_ref().map(ToString::to_string),
650                "plane": report.observed_schema.as_ref().map(|_| "daemon-mediated (tapped)"),
651                "observed_schema": report.observed_schema,
652                "schema_hash": report.schema_hash.as_ref().map(ToString::to_string),
653                "subscribers": report.subscribers.iter().map(ToString::to_string).collect::<Vec<_>>(),
654            })
655        );
656    } else {
657        let _ = writeln!(out, "{}", report.port);
658        let _ = writeln!(
659            out,
660            "  type: {}",
661            report
662                .type_urn
663                .as_ref()
664                .map_or_else(|| "(untyped)".to_owned(), ToString::to_string)
665        );
666        match &report.observed_schema {
667            Some(schema) => {
668                let _ = writeln!(out, "  plane: daemon-mediated (tapped)");
669                let _ = writeln!(out, "  observed: {schema}");
670                match &report.schema_hash {
671                    Some(hash) => {
672                        let _ = writeln!(out, "  schema_hash: {hash}");
673                    }
674                    None => {
675                        let _ = writeln!(out, "  schema_hash: (not decodable as Arrow IPC)");
676                    }
677                }
678            }
679            None => {
680                let _ = writeln!(out, "  plane: unknown (no frame observed)");
681            }
682        }
683        if report.subscribers.is_empty() {
684            let _ = writeln!(out, "  subscribers: (pass --manifest to list them)");
685        } else {
686            let _ = writeln!(out, "  subscribers:");
687            for subscriber in &report.subscribers {
688                let _ = writeln!(out, "    {subscriber}");
689            }
690        }
691    }
692    let _ = out.flush();
693}
694
695/// `astrs topic pub`: publishes one message through a dynamic-node attach
696/// (see this module's own docs for why `pub` cannot inject into an
697/// arbitrary running edge).
698///
699/// # Errors
700///
701/// - [`CliError::BadArgument`] for an unparsable `node/output` or a
702///   message JSON `--typed` cannot coerce to the port's declared type.
703/// - [`CliError::Node`] if the daemon refuses the attach (the manifest
704///   node named is not `path: dynamic`, or is already attached).
705/// - As [`echo`] for the coordinator half (resolving the dataflow, reading
706///   the declared type).
707pub fn publish(
708    out: &mut dyn Write,
709    endpoint: &Endpoint,
710    args: &PublishArgs,
711) -> Result<PublishReport, CliError> {
712    let port = parse_port(&args.topic)?;
713    let runtime = runtime()?;
714    let lookup_port = port.clone();
715    let (dataflow, type_urn) = runtime.block_on(async move {
716        let mut client = Client::connect(endpoint).await?;
717        let dataflow = resolve_dataflow(&mut client, args.dataflow.as_deref()).await?;
718        let type_urn = match client
719            .request(
720                "topic pub",
721                &ControlRequest::GetNodeInfo {
722                    dataflow,
723                    node: lookup_port.node().clone(),
724                },
725            )
726            .await
727        {
728            Ok(ControlReply::NodeInfo { nodes }) => nodes
729                .into_iter()
730                .next()
731                .and_then(|info| info.outputs.get(lookup_port.port()).cloned())
732                .flatten(),
733            // A node the coordinator has no record of yet (or any other
734            // read failure) is not fatal here: the untyped fallback below
735            // still lets the attach itself be the real test of whether the
736            // node exists and is dynamic.
737            _ => None,
738        };
739        Ok::<_, CliError>((dataflow, type_urn))
740    })?;
741
742    let batch = encode_message(&args.message, type_urn.as_ref())?;
743
744    let repeat = args.rate.filter(|hz| *hz > 0.0);
745    let attach_port = port.clone();
746    let sent = runtime.block_on(async move {
747        let builder = NodeBuilder::new()
748            .dataflow(dataflow)
749            .node_id(attach_port.node().as_str())?
750            .dynamic(true)
751            .output(attach_port.port().as_str())?
752            .auth(endpoint.token.clone());
753        // `connect_async`, not `connect`: this whole block already runs
754        // inside `runtime`'s own `block_on` (a *current-thread* runtime —
755        // see `command::client::runtime`), and `NodeBuilder::connect`'s
756        // sync form blocks that runtime's one worker to drive its own
757        // dial — a deadlock `astrs-node-api` refuses outright rather than
758        // hang on. `spawn_blocking` does not sidestep that refusal: a
759        // blocking-pool thread still reports the *enclosing* runtime's
760        // flavor to `NodeRuntime::acquire`, so `connect()` still sees
761        // "current-thread" and still refuses. Calling the async form
762        // directly is not a workaround, it is the correct call from
763        // inside an already-async context.
764        let (mut node, _events) = builder.connect_async().await?;
765        let mut output = node.raw_output(attach_port.port().as_str())?;
766        output.send_batch(&batch, Metadata::new(node.hlc_now()))?;
767        let mut sent = 1usize;
768
769        if let Some(hz) = repeat {
770            let mut signals = Signals::install();
771            let interval = Duration::from_secs_f64(1.0 / hz);
772            loop {
773                tokio::select! {
774                    () = tokio::time::sleep(interval) => {
775                        output.send_batch(&batch, Metadata::new(node.hlc_now()))?;
776                        sent += 1;
777                    }
778                    () = signals.next() => break,
779                }
780            }
781        }
782        // `shutdown`, not the bare `close_outputs` this line used to
783        // call: only `shutdown` also queues the writer's own shutdown
784        // sentinel (`request_drain`), which is what lets the writer task
785        // *end* — and therefore what lets `flush_outputs` below observe
786        // it ending — the moment everything is flushed, rather than
787        // idling until `flush_outputs`'s own timeout gives up on it.
788        let _ = node.shutdown();
789        // Queuing the close is not sending it: `flush_outputs` awaits the
790        // writer task actually putting every queued frame (this publish,
791        // and the close itself) on the wire before the node — and the
792        // runtime under it — go away. Without this, a single-shot
793        // `astrs topic pub` racing its own current-thread runtime's
794        // teardown could return "sent" for a message the daemon never
795        // saw (see `Node::flush_outputs`'s own docs for the mechanism).
796        node.flush_outputs().await;
797        Ok::<_, CliError>(sent)
798    })?;
799
800    let report = PublishReport { port, sent };
801    if args.json {
802        let _ = writeln!(
803            out,
804            "{}",
805            serde_json::json!({ "port": report.port.to_string(), "sent": report.sent })
806        );
807    } else {
808        let _ = writeln!(
809            out,
810            "published {} message(s) on {}",
811            report.sent, report.port
812        );
813    }
814    let _ = out.flush();
815    Ok(report)
816}
817
818/// Arguments for [`publish`].
819#[derive(Debug, Clone)]
820pub struct PublishArgs {
821    /// The port to publish onto, as `node/output`.
822    pub topic: String,
823    /// The message, as JSON.
824    pub message: String,
825    /// The dataflow it belongs to; `None` means "the only one running".
826    pub dataflow: Option<String>,
827    /// Repeat at this rate (Hz) instead of publishing once.
828    pub rate: Option<f64>,
829    /// Emit JSON rather than a human-readable line.
830    pub json: bool,
831}
832
833/// What [`publish`] did.
834#[derive(Debug, Clone)]
835pub struct PublishReport {
836    /// The port published onto.
837    pub port: PortRef,
838    /// How many messages were sent.
839    pub sent: usize,
840}
841
842/// Encodes a JSON message as a one-row [`RecordBatch`], typed by `urn`'s
843/// layout when it names a scalar this function knows how to build, and as
844/// a single raw `Binary` column of the message's UTF-8 bytes otherwise
845/// (blueprint §17: "typed via URN layout when annotated, bytes otherwise").
846///
847/// `urn` is [`astrs_wire::TypeUrn`] — the validated-string form a manifest
848/// annotation carries over the wire — and is re-parsed here into
849/// [`astrs_data::urn::TypeUrn`], the richer form [`layout_of`] resolves a
850/// [`DataType`] from; the two are distinct types in distinct crates (the
851/// wire family does not depend on `astrs-data`), and this is the one seam
852/// that bridges them.
853///
854/// # Errors
855///
856/// [`CliError::BadArgument`] when `urn` names a scalar layout but
857/// `message` is not JSON of a shape [`crate::command::param::parse_value`]
858/// can coerce to it.
859fn encode_message(message: &str, urn: Option<&TypeUrn>) -> Result<RecordBatch, CliError> {
860    if let Some(urn) = urn
861        && let Ok(data_urn) = astrs_data::urn::TypeUrn::parse(urn.as_str())
862        && let Ok(layout) = layout_of(&data_urn)
863        && let Some(batch) = typed_batch(message, &layout)?
864    {
865        return Ok(batch);
866    }
867    let mut builder = BinaryBuilder::with_capacity(1, message.len());
868    builder.append_value(message.as_bytes());
869    Ok(RecordBatch::from_payload(builder.finish().into_array_ref()))
870}
871
872/// Builds a one-row batch of `layout`, or `None` for a layout this
873/// CLI-side encoder does not attempt (anything beyond the plain scalars a
874/// parameter value already covers — struct/list/tensor layouts need the
875/// node's own schema, not a guess from one JSON scalar).
876fn typed_batch(message: &str, layout: &DataType) -> Result<Option<RecordBatch>, CliError> {
877    use astrs_data::builder::{Int64Builder, StringBuilder};
878    use astrs_wire::Parameter;
879
880    let mismatch = || CliError::BadArgument {
881        flag: "message",
882        value: message.to_owned(),
883        reason: format!("the port's declared type needs a {layout:?}, which that value is not"),
884    };
885
886    let batch = match layout {
887        DataType::Bool => {
888            let Parameter::Bool(value) = parse_parameter_value(message)? else {
889                return Err(mismatch());
890            };
891            let mut builder = BooleanBuilder::with_capacity(1);
892            builder.append_value(value);
893            RecordBatch::from_payload(builder.finish().into_array_ref())
894        }
895        DataType::Float64 => {
896            let value = match parse_parameter_value(message)? {
897                Parameter::Float(value) => value,
898                #[allow(clippy::cast_precision_loss)]
899                Parameter::Integer(value) => value as f64,
900                _ => return Err(mismatch()),
901            };
902            let mut builder = Float64Builder::with_capacity(1);
903            builder.append_value(value);
904            RecordBatch::from_payload(builder.finish().into_array_ref())
905        }
906        DataType::Int64 => {
907            let Parameter::Integer(value) = parse_parameter_value(message)? else {
908                return Err(mismatch());
909            };
910            let mut builder = Int64Builder::with_capacity(1);
911            builder.append_value(value);
912            RecordBatch::from_payload(builder.finish().into_array_ref())
913        }
914        DataType::Utf8 => {
915            let Parameter::String(value) = parse_parameter_value(message)? else {
916                return Err(mismatch());
917            };
918            let mut builder = StringBuilder::with_capacity(1, value.len());
919            builder.append_value(&value);
920            RecordBatch::from_payload(builder.finish().into_array_ref())
921        }
922        _ => return Ok(None),
923    };
924    Ok(Some(batch))
925}
926
927#[cfg(test)]
928mod tests {
929    #![allow(clippy::unwrap_used, clippy::expect_used, clippy::panic)]
930
931    use super::*;
932
933    #[test]
934    fn a_port_reference_parses_node_and_output() {
935        let port = parse_port("camera/frames").unwrap();
936        assert_eq!(port.node().as_str(), "camera");
937        assert_eq!(port.port().as_str(), "frames");
938    }
939
940    #[test]
941    fn a_port_reference_with_no_separator_is_refused() {
942        let error = parse_port("camera").unwrap_err();
943        assert!(matches!(error, CliError::BadArgument { flag: "topic", .. }));
944    }
945
946    #[test]
947    fn hz_window_is_empty_before_any_arrival() {
948        let window = HzWindow::new(Duration::from_secs(5));
949        let now = Instant::now();
950        assert_eq!(window.count(), 0);
951        assert_eq!(window.rate_per_sec(now), None);
952    }
953
954    #[test]
955    fn hz_window_reports_none_on_a_single_arrival() {
956        let mut window = HzWindow::new(Duration::from_secs(5));
957        let now = Instant::now();
958        window.record(now);
959        assert_eq!(window.count(), 1);
960        assert_eq!(window.rate_per_sec(now), None);
961    }
962
963    #[test]
964    fn hz_window_computes_the_rate_across_evenly_spaced_arrivals() {
965        let mut window = HzWindow::new(Duration::from_secs(10));
966        let start = Instant::now();
967        for step in 0..5u64 {
968            window.record(start + Duration::from_millis(step * 100));
969        }
970        let now = start + Duration::from_millis(400);
971        // 5 arrivals spanning 400ms is 4 intervals over 0.4s = 10 Hz.
972        let hz = window.rate_per_sec(now).unwrap();
973        assert!((hz - 10.0).abs() < 1e-6, "{hz}");
974    }
975
976    #[test]
977    fn hz_window_evicts_arrivals_older_than_the_window() {
978        let mut window = HzWindow::new(Duration::from_millis(500));
979        let start = Instant::now();
980        window.record(start);
981        window.record(start + Duration::from_millis(100));
982        window.record(start + Duration::from_secs(2));
983        // The first two arrivals are more than 500ms behind the third.
984        assert_eq!(window.count(), 1);
985    }
986
987    #[test]
988    fn a_valid_arrow_payload_summarizes_with_its_schema() {
989        use astrs_data::builder::Int64Builder;
990        use astrs_data::ipc::encode_payload;
991
992        let mut builder = Int64Builder::with_capacity(3);
993        builder.append_value(1);
994        builder.append_value(2);
995        builder.append_value(3);
996        let batch = RecordBatch::from_payload(builder.finish().into_array_ref());
997        let encoded = encode_payload(&batch).expect("a valid batch encodes");
998
999        let summary = summarize_payload(encoded.as_ref());
1000        assert!(summary.contains("3 row(s)"), "{summary}");
1001        assert!(summary.contains("1 column(s)"), "{summary}");
1002        assert!(summary.contains("Int64"), "{summary}");
1003        assert!(
1004            !summary.contains("not decodable"),
1005            "a real Arrow payload must not fall back to hex: {summary}"
1006        );
1007    }
1008
1009    #[test]
1010    fn a_non_arrow_payload_summarizes_as_hex() {
1011        let summary = summarize_payload(b"not arrow at all");
1012        assert!(summary.contains("not decodable"), "{summary}");
1013        assert!(summary.contains("6e6f7420"), "{summary}");
1014    }
1015
1016    #[test]
1017    fn a_valid_arrow_payload_also_carries_its_schema_hash() {
1018        use astrs_data::builder::Int64Builder;
1019        use astrs_data::ipc::encode_payload;
1020
1021        let mut builder = Int64Builder::with_capacity(1);
1022        builder.append_value(1);
1023        let batch = RecordBatch::from_payload(builder.finish().into_array_ref());
1024        let encoded = encode_payload(&batch).expect("a valid batch encodes");
1025
1026        let (summary, hash) = summarize_with_hash(encoded.as_ref());
1027        assert!(summary.contains("Int64"), "{summary}");
1028        let hash = hash.expect("a decodable batch has a schema to hash");
1029        assert_eq!(
1030            hash,
1031            astrs_data::SchemaHash::of(batch.schema()),
1032            "`info` must hash exactly the schema blueprint §6.1 defines, \
1033             not a summary of it"
1034        );
1035    }
1036
1037    #[test]
1038    fn a_non_arrow_payload_has_no_schema_hash_but_still_summarizes() {
1039        let (summary, hash) = summarize_with_hash(b"not arrow at all");
1040        assert!(summary.contains("not decodable"), "{summary}");
1041        assert!(hash.is_none(), "raw bytes have no schema to hash");
1042    }
1043
1044    #[test]
1045    fn hex_truncates_long_payloads_with_a_marker() {
1046        let bytes = vec![0xAB; HEX_PREVIEW_LIMIT + 10];
1047        let text = hex(&bytes);
1048        assert!(text.ends_with("..."));
1049        assert_eq!(text.len(), HEX_PREVIEW_LIMIT * 2 + 3);
1050    }
1051
1052    #[test]
1053    fn an_untyped_message_encodes_as_a_binary_column() {
1054        let batch = encode_message("hello", None).unwrap();
1055        assert_eq!(batch.num_rows(), 1);
1056        assert_eq!(batch.schema().fields()[0].data_type(), &DataType::Binary);
1057    }
1058
1059    #[test]
1060    fn a_float_urn_encodes_a_plain_number_as_float64() {
1061        let urn = TypeUrn::new("std/core/v1/Float64").unwrap();
1062        let batch = encode_message("1.5", Some(&urn)).unwrap();
1063        assert_eq!(batch.schema().fields()[0].data_type(), &DataType::Float64);
1064    }
1065
1066    #[test]
1067    fn a_bool_urn_rejects_a_non_boolean_value() {
1068        let urn = TypeUrn::new("std/core/v1/Bool").unwrap();
1069        let error = encode_message("\"left\"", Some(&urn)).unwrap_err();
1070        assert!(matches!(
1071            error,
1072            CliError::BadArgument {
1073                flag: "message",
1074                ..
1075            }
1076        ));
1077    }
1078
1079    #[test]
1080    fn every_topic_verb_reports_a_dead_cluster_rather_than_hanging() {
1081        let endpoint = Endpoint::new(
1082            std::net::SocketAddr::from(([127, 0, 0, 1], 1)),
1083            astrs_wire::AuthToken::ZERO,
1084        );
1085        let stream_args = TopicStreamArgs {
1086            topic: "camera/frames".to_owned(),
1087            dataflow: None,
1088            json: false,
1089            count: None,
1090        };
1091        let echo_error = echo(&mut Vec::new(), &endpoint, &stream_args).unwrap_err();
1092        assert!(
1093            matches!(echo_error, CliError::NoCluster { .. }),
1094            "{echo_error}"
1095        );
1096
1097        let hz_error = hz(
1098            &mut Vec::new(),
1099            &endpoint,
1100            &stream_args,
1101            Duration::from_secs(5),
1102        )
1103        .unwrap_err();
1104        assert!(matches!(hz_error, CliError::NoCluster { .. }), "{hz_error}");
1105
1106        let info_error = info(
1107            &mut Vec::new(),
1108            &endpoint,
1109            "camera/frames",
1110            None,
1111            None,
1112            false,
1113        )
1114        .unwrap_err();
1115        assert!(
1116            matches!(info_error, CliError::NoCluster { .. }),
1117            "{info_error}"
1118        );
1119
1120        let publish_args = PublishArgs {
1121            topic: "camera/frames".to_owned(),
1122            message: "1".to_owned(),
1123            dataflow: None,
1124            rate: None,
1125            json: false,
1126        };
1127        let publish_error = publish(&mut Vec::new(), &endpoint, &publish_args).unwrap_err();
1128        assert!(
1129            matches!(publish_error, CliError::NoCluster { .. }),
1130            "{publish_error}"
1131        );
1132    }
1133}