Skip to main content

taskfast_cli/cmd/events/
stream.rs

1// SPDX-License-Identifier: MIT
2//! `taskfast events stream` — long-running WebSocket tail on `/socket/agent`.
3//!
4//! # Contract
5//!
6//! Stdout is JSONL. Each line is either an event payload (matching the
7//! AsyncAPI `components.messages` shape) or a sentinel frame:
8//!
9//! * `{"sentinel":"connected"}`    — initial join succeeded.
10//! * `{"sentinel":"reconnecting"}` — transport dropped; backoff started.
11//! * `{"sentinel":"resumed"}`      — reconnect succeeded; backlog drains.
12//! * `{"sentinel":"closing"}`      — SIGINT/SIGTERM received; exiting 0.
13//! * `{"sentinel":"auth_failed"}`  — server rejected the API key; exits 2.
14//! * `{"sentinel":"acked","event_id":"…"}` — server confirmed an ack sent
15//!   via `--ack-stdin`.
16//!
17//! # Auth
18//!
19//! The API key is sent via the `Sec-WebSocket-Protocol` handshake header
20//! (`taskfast.v1, bearer.<key>`). Keeping credentials off the URL line
21//! keeps them out of proxy access logs and browser history-like caches.
22//!
23//! # Ack mechanic
24//!
25//! The server keeps one event in flight and pushes the next only after the
26//! current one is acked as an `ack` message on this channel — there is no
27//! HTTP ack route, and a second socket would kick this one (one socket per
28//! agent). With `--ack-stdin` the stream reads event ids from stdin, one
29//! per line, and sends each as `[join_ref, ref, "agent:me", "ack",
30//! {"event_id": id}]`. Write the id after handling the event to keep
31//! at-least-once delivery.
32//!
33//! The server only replies to an ack for the in-flight event; a stale id
34//! gets no reply and no `acked` sentinel. Ids written while the socket is
35//! down wait in the pipe until rejoin. An ack lost with a dying socket is
36//! harmless: the server replays from its ack cursor on rejoin, so the
37//! event is redelivered and can be acked again.
38//!
39//! # Protocol
40//!
41//! Phoenix Channels v2 JSON envelope: `[join_ref, msg_ref, topic, event, payload]`.
42//! The server pushes marketplace events as `event == "event"`. Heartbeat
43//! every 30s on topic `"phoenix"`. Reconnect uses exponential backoff
44//! (1s → 2s → 4s → … → 30s cap); same backlog replays from cursor on
45//! resume (server-side state).
46
47use std::io::{BufRead, Write};
48use std::process::ExitCode;
49use std::sync::Arc;
50use std::time::Duration;
51
52use clap::Parser;
53use futures_util::{SinkExt, StreamExt};
54use serde_json::{json, Value};
55use tokio::sync::mpsc::{unbounded_channel, UnboundedReceiver};
56use tokio::time::{sleep, Instant};
57use tokio_tungstenite::tungstenite::client::IntoClientRequest;
58use tokio_tungstenite::tungstenite::http::Uri;
59use tokio_tungstenite::tungstenite::protocol::Message;
60use tokio_tungstenite::tungstenite::ClientRequestBuilder;
61
62use super::super::{CmdError, Ctx};
63
64#[derive(Debug, Parser)]
65pub struct StreamArgs {
66    /// Exit after the first backlog drain (join + any pushes delivered
67    /// before an idle moment). Intended for integration tests; production
68    /// callers leave this off and the stream runs until SIGTERM/SIGINT.
69    #[arg(long)]
70    pub once: bool,
71
72    /// Exit on first transport drop instead of reconnecting. Reverts to the
73    /// pre-auto-reconnect behaviour for callers that own the respawn loop
74    /// themselves (e.g. systemd unit with `Restart=on-failure`).
75    #[arg(long)]
76    pub no_reconnect: bool,
77
78    /// Read event ids from stdin, one per line, and ack each on this
79    /// stream's socket. The server holds every later event until the
80    /// in-flight one is acked, so write the id after handling the event.
81    #[arg(long)]
82    pub ack_stdin: bool,
83}
84
85/// Topic the CLI joins on the socket.
86const TOPIC: &str = "agent:me";
87/// Ref of the `phx_join` push; its reply carries the same ref.
88const JOIN_REF: &str = "1";
89/// Phoenix heartbeat cadence. Matches the server default.
90const HEARTBEAT_INTERVAL: Duration = Duration::from_secs(30);
91/// Reconnect backoff ceiling.
92const RECONNECT_CAP: Duration = Duration::from_secs(30);
93
94/// Entry point. Returns a process exit code because the stream sidesteps
95/// the envelope wrapper: error envelopes would contaminate the JSONL
96/// stream and swallow stdout buffering semantics.
97pub async fn run(ctx: &Ctx, args: StreamArgs) -> ExitCode {
98    let api_key = match ctx.api_key.as_deref() {
99        Some(k) => k.to_string(),
100        None => {
101            emit_error_envelope(ctx, &CmdError::MissingApiKey);
102            return CmdError::MissingApiKey.exit_code().into();
103        }
104    };
105    let ws_url = match ws_url_from_base(ctx.base_url()) {
106        Ok(u) => u,
107        Err(e) => {
108            emit_error_envelope(ctx, &e);
109            return e.exit_code().into();
110        }
111    };
112
113    let mut backoff = Duration::from_secs(1);
114    let mut first_connect = true;
115
116    let shutdown = install_shutdown_signal();
117    let mut ack_lines = args.ack_stdin.then(spawn_stdin_reader);
118
119    loop {
120        if shutdown.is_cancelled() {
121            emit_sentinel("closing");
122            return ExitCode::SUCCESS;
123        }
124
125        match run_once(
126            &ws_url,
127            &api_key,
128            first_connect,
129            args.once,
130            &shutdown,
131            ack_lines.as_mut(),
132        )
133        .await
134        {
135            ConnectOutcome::AuthFailed => {
136                emit_sentinel("auth_failed");
137                return ExitCode::from(2);
138            }
139            ConnectOutcome::Shutdown => {
140                emit_sentinel("closing");
141                return ExitCode::SUCCESS;
142            }
143            ConnectOutcome::OnceDone => {
144                return ExitCode::SUCCESS;
145            }
146            ConnectOutcome::Disconnected => {
147                // Fall through to reconnect loop below.
148            }
149        }
150
151        if args.no_reconnect {
152            // Surface the drop as a non-zero exit so supervisors (systemd,
153            // k8s) see it as a failure and respawn under their own policy.
154            return ExitCode::from(1);
155        }
156
157        emit_sentinel("reconnecting");
158        let wait = backoff;
159        tokio::select! {
160            () = sleep(wait) => {},
161            () = shutdown.cancelled() => {
162                emit_sentinel("closing");
163                return ExitCode::SUCCESS;
164            }
165        }
166        backoff = (backoff * 2).min(RECONNECT_CAP);
167        first_connect = false;
168    }
169}
170
171enum ConnectOutcome {
172    AuthFailed,
173    Shutdown,
174    OnceDone,
175    Disconnected,
176}
177
178async fn run_once(
179    ws_url: &str,
180    api_key: &str,
181    first_connect: bool,
182    once: bool,
183    shutdown: &ShutdownToken,
184    mut ack_lines: Option<&mut UnboundedReceiver<String>>,
185) -> ConnectOutcome {
186    let req = match build_request(ws_url, api_key) {
187        Ok(r) => r,
188        Err(_) => return ConnectOutcome::Disconnected,
189    };
190
191    let (ws, resp) = match tokio_tungstenite::connect_async(req).await {
192        Ok(v) => v,
193        Err(e) => {
194            if is_auth_error(&e) {
195                return ConnectOutcome::AuthFailed;
196            }
197            return ConnectOutcome::Disconnected;
198        }
199    };
200
201    // Server must select `taskfast.v1`. If it didn't, either the socket
202    // rejected us or a middlebox rewrote the handshake — treat as auth.
203    if !has_taskfast_subprotocol(&resp) {
204        return ConnectOutcome::AuthFailed;
205    }
206
207    let (mut sink, mut source) = ws.split();
208
209    // Phoenix join
210    let join_msg = phx_frame(JOIN_REF, JOIN_REF, TOPIC, "phx_join", json!({}));
211    if sink.send(Message::Text(join_msg.into())).await.is_err() {
212        return ConnectOutcome::Disconnected;
213    }
214
215    // Await join reply before announcing connected.
216    let mut join_acked = false;
217    let mut msg_ref: u64 = 1;
218    let mut heartbeat_next = Instant::now() + HEARTBEAT_INTERVAL;
219
220    loop {
221        tokio::select! {
222            () = shutdown.cancelled() => {
223                let _ = sink.send(Message::Close(None)).await;
224                return ConnectOutcome::Shutdown;
225            }
226            () = sleep_until(heartbeat_next) => {
227                msg_ref += 1;
228                let hb = phx_frame_null_join(&msg_ref.to_string(), "phoenix", "heartbeat", json!({}));
229                if sink.send(Message::Text(hb.into())).await.is_err() {
230                    return ConnectOutcome::Disconnected;
231                }
232                heartbeat_next = Instant::now() + HEARTBEAT_INTERVAL;
233            }
234            // Acks only make sense on a joined channel.
235            line = next_ack(&mut ack_lines), if join_acked => match line {
236                Some(id) => {
237                    let id = id.trim();
238                    if id.is_empty() {
239                        continue;
240                    }
241                    msg_ref += 1;
242                    let ack = phx_frame(JOIN_REF, &msg_ref.to_string(), TOPIC, "ack", json!({ "event_id": id }));
243                    if sink.send(Message::Text(ack.into())).await.is_err() {
244                        return ConnectOutcome::Disconnected;
245                    }
246                }
247                // EOF or unreadable stdin: stop reading, keep streaming.
248                None => ack_lines = None,
249            },
250            frame = source.next() => {
251                match frame {
252                    Some(Ok(Message::Text(text))) => {
253                        let parsed: Value = match serde_json::from_str(&text) {
254                            Ok(v) => v,
255                            Err(e) => {
256                                tracing::warn!(
257                                    target: "taskfast::events",
258                                    error = %e,
259                                    "WS text frame was not valid JSON; surfacing as unparseable"
260                                );
261                                emit_unparseable(&text, &e.to_string());
262                                continue;
263                            }
264                        };
265                        match classify_frame(&parsed) {
266                            FrameKind::JoinOk => {
267                                if !join_acked {
268                                    join_acked = true;
269                                    let sentinel = if first_connect { "connected" } else { "resumed" };
270                                    emit_sentinel(sentinel);
271                                }
272                            }
273                            FrameKind::JoinError => {
274                                return ConnectOutcome::AuthFailed;
275                            }
276                            FrameKind::Event(payload) => {
277                                emit_event(&payload);
278                                if once {
279                                    let _ = sink.send(Message::Close(None)).await;
280                                    return ConnectOutcome::OnceDone;
281                                }
282                            }
283                            FrameKind::Acked(id) => {
284                                emit_event(&json!({ "sentinel": "acked", "event_id": id }));
285                            }
286                            FrameKind::Ignored => {}
287                        }
288                    }
289                    Some(Ok(Message::Ping(payload))) => {
290                        let _ = sink.send(Message::Pong(payload)).await;
291                    }
292                    Some(Ok(Message::Close(_))) | None => {
293                        return ConnectOutcome::Disconnected;
294                    }
295                    Some(Err(_)) => {
296                        return ConnectOutcome::Disconnected;
297                    }
298                    _ => {}
299                }
300            }
301        }
302    }
303}
304
305/// Read stdin on a plain thread. tokio's stdin read can't be cancelled, so
306/// a pending read would hold the runtime open at exit for as long as the
307/// host keeps the pipe open; a detached thread doesn't.
308fn spawn_stdin_reader() -> UnboundedReceiver<String> {
309    let (tx, rx) = unbounded_channel();
310    std::thread::spawn(move || {
311        for line in std::io::stdin().lock().lines().map_while(Result::ok) {
312            if tx.send(line).is_err() {
313                break;
314            }
315        }
316    });
317    rx
318}
319
320/// Next ack id from stdin; never resolves once stdin is closed (`None`).
321async fn next_ack(rx: &mut Option<&mut UnboundedReceiver<String>>) -> Option<String> {
322    match rx {
323        Some(rx) => rx.recv().await,
324        None => std::future::pending().await,
325    }
326}
327
328async fn sleep_until(deadline: Instant) {
329    let now = Instant::now();
330    if deadline <= now {
331        return;
332    }
333    sleep(deadline - now).await;
334}
335
336enum FrameKind {
337    JoinOk,
338    JoinError,
339    Acked(String),
340    Event(Value),
341    Ignored,
342}
343
344fn classify_frame(frame: &Value) -> FrameKind {
345    let arr = match frame.as_array() {
346        Some(a) if a.len() == 5 => a,
347        _ => return FrameKind::Ignored,
348    };
349    let topic = arr[2].as_str().unwrap_or("");
350    let event = arr[3].as_str().unwrap_or("");
351    let payload = &arr[4];
352
353    if event == "phx_reply" && topic == TOPIC {
354        // Any ref other than the join's answers an ack we sent. Its error
355        // replies must not reach the JoinError → auth_failed path.
356        if arr[1].as_str() != Some(JOIN_REF) {
357            return payload
358                .pointer("/response/event_id")
359                .and_then(Value::as_str)
360                .map_or(FrameKind::Ignored, |id| FrameKind::Acked(id.to_string()));
361        }
362        let status = payload.get("status").and_then(|v| v.as_str()).unwrap_or("");
363        return match status {
364            "ok" => FrameKind::JoinOk,
365            "error" => FrameKind::JoinError,
366            _ => FrameKind::Ignored,
367        };
368    }
369    if event == "event" && topic == TOPIC {
370        return FrameKind::Event(payload.clone());
371    }
372    FrameKind::Ignored
373}
374
375fn phx_frame(join_ref: &str, msg_ref: &str, topic: &str, event: &str, payload: Value) -> String {
376    serde_json::to_string(&json!([join_ref, msg_ref, topic, event, payload]))
377        .expect("phoenix frame must serialize")
378}
379
380fn phx_frame_null_join(msg_ref: &str, topic: &str, event: &str, payload: Value) -> String {
381    serde_json::to_string(&json!([Value::Null, msg_ref, topic, event, payload]))
382        .expect("phoenix frame must serialize")
383}
384
385fn build_request(
386    ws_url: &str,
387    api_key: &str,
388) -> Result<tokio_tungstenite::tungstenite::handshake::client::Request, CmdError> {
389    let uri: Uri =
390        ws_url
391            .parse()
392            .map_err(|e: tokio_tungstenite::tungstenite::http::uri::InvalidUri| {
393                CmdError::Usage(format!("invalid ws url {ws_url:?}: {e}"))
394            })?;
395    let builder = ClientRequestBuilder::new(uri)
396        .with_sub_protocol("taskfast.v1")
397        .with_sub_protocol(format!("bearer.{api_key}"));
398    builder
399        .into_client_request()
400        .map_err(|e| CmdError::Usage(format!("ws request build failed: {e}")))
401}
402
403fn has_taskfast_subprotocol(
404    resp: &tokio_tungstenite::tungstenite::handshake::client::Response,
405) -> bool {
406    resp.headers()
407        .get("sec-websocket-protocol")
408        .and_then(|v| v.to_str().ok())
409        .is_some_and(|s| s.split(',').any(|tok| tok.trim() == "taskfast.v1"))
410}
411
412fn is_auth_error(e: &tokio_tungstenite::tungstenite::Error) -> bool {
413    use tokio_tungstenite::tungstenite::Error as TE;
414    match e {
415        TE::Http(resp) => matches!(resp.status().as_u16(), 401 | 403),
416        _ => false,
417    }
418}
419
420fn ws_url_from_base(base: &str) -> Result<String, CmdError> {
421    let trimmed = base.trim_end_matches('/');
422    let swapped = if let Some(rest) = trimmed.strip_prefix("https://") {
423        format!("wss://{rest}")
424    } else if let Some(rest) = trimmed.strip_prefix("http://") {
425        format!("ws://{rest}")
426    } else if trimmed.starts_with("wss://") || trimmed.starts_with("ws://") {
427        trimmed.to_string()
428    } else {
429        return Err(CmdError::Usage(format!(
430            "base url must start with http(s):// or ws(s)://, got {base:?}"
431        )));
432    };
433    Ok(format!("{swapped}/socket/agent/websocket?vsn=2.0.0"))
434}
435
436fn emit_sentinel(kind: &str) {
437    let line = format!("{}\n", json!({ "sentinel": kind }));
438    let stdout = std::io::stdout();
439    let mut guard = stdout.lock();
440    let _ = guard.write_all(line.as_bytes());
441    let _ = guard.flush();
442}
443
444fn emit_event(payload: &Value) {
445    let mut buf = match serde_json::to_vec(payload) {
446        Ok(b) => b,
447        Err(_) => return,
448    };
449    buf.push(b'\n');
450    let stdout = std::io::stdout();
451    let mut guard = stdout.lock();
452    let _ = guard.write_all(&buf);
453    let _ = guard.flush();
454}
455
456/// Surface a malformed WS text frame on the `--json` path instead of
457/// swallowing it. The `type: "unparseable"` tag keeps consumers' stream
458/// parsers from mistaking it for a regular event.
459fn emit_unparseable(raw: &str, error: &str) {
460    let payload = json!({ "type": "unparseable", "raw": raw, "error": error });
461    emit_event(&payload);
462}
463
464fn emit_error_envelope(ctx: &Ctx, err: &CmdError) {
465    if ctx.quiet {
466        return;
467    }
468    crate::envelope::Envelope::error(ctx.environment, ctx.dry_run, err).emit();
469}
470
471#[derive(Clone)]
472struct ShutdownToken {
473    inner: Arc<tokio::sync::Notify>,
474    flag: Arc<std::sync::atomic::AtomicBool>,
475}
476
477impl ShutdownToken {
478    fn new() -> Self {
479        Self {
480            inner: Arc::new(tokio::sync::Notify::new()),
481            flag: Arc::new(std::sync::atomic::AtomicBool::new(false)),
482        }
483    }
484
485    fn trigger(&self) {
486        self.flag.store(true, std::sync::atomic::Ordering::SeqCst);
487        self.inner.notify_waiters();
488    }
489
490    fn is_cancelled(&self) -> bool {
491        self.flag.load(std::sync::atomic::Ordering::SeqCst)
492    }
493
494    async fn cancelled(&self) {
495        if self.is_cancelled() {
496            return;
497        }
498        self.inner.notified().await;
499    }
500}
501
502fn install_shutdown_signal() -> ShutdownToken {
503    let token = ShutdownToken::new();
504    let tclone = token.clone();
505    tokio::spawn(async move {
506        #[cfg(unix)]
507        {
508            use tokio::signal::unix::{signal, SignalKind};
509            let mut term = match signal(SignalKind::terminate()) {
510                Ok(s) => s,
511                Err(_) => {
512                    let _ = tokio::signal::ctrl_c().await;
513                    tclone.trigger();
514                    return;
515                }
516            };
517            tokio::select! {
518                _ = term.recv() => {}
519                _ = tokio::signal::ctrl_c() => {}
520            }
521        }
522        #[cfg(not(unix))]
523        {
524            let _ = tokio::signal::ctrl_c().await;
525        }
526        tclone.trigger();
527    });
528    token
529}
530
531#[cfg(test)]
532mod tests {
533    use super::*;
534
535    #[test]
536    fn ws_url_swaps_http_to_ws() {
537        assert_eq!(
538            ws_url_from_base("http://localhost:4000").unwrap(),
539            "ws://localhost:4000/socket/agent/websocket?vsn=2.0.0"
540        );
541    }
542
543    #[test]
544    fn ws_url_swaps_https_to_wss() {
545        assert_eq!(
546            ws_url_from_base("https://api.taskfast.app/").unwrap(),
547            "wss://api.taskfast.app/socket/agent/websocket?vsn=2.0.0"
548        );
549    }
550
551    #[test]
552    fn ws_url_passthrough_ws_scheme() {
553        assert_eq!(
554            ws_url_from_base("ws://localhost:4000").unwrap(),
555            "ws://localhost:4000/socket/agent/websocket?vsn=2.0.0"
556        );
557    }
558
559    #[test]
560    fn ws_url_rejects_unknown_scheme() {
561        assert!(ws_url_from_base("ftp://x").is_err());
562    }
563
564    #[test]
565    fn classify_recognizes_join_ok() {
566        let f = json!(["1", "1", "agent:me", "phx_reply", { "status": "ok", "response": {} }]);
567        assert!(matches!(classify_frame(&f), FrameKind::JoinOk));
568    }
569
570    #[test]
571    fn classify_recognizes_join_error() {
572        let f = json!(["1", "1", "agent:me", "phx_reply", { "status": "error" }]);
573        assert!(matches!(classify_frame(&f), FrameKind::JoinError));
574    }
575
576    #[test]
577    fn classify_recognizes_event_push() {
578        let f =
579            json!(["1", null, "agent:me", "event", { "event_id": "x", "event": "task_assigned" }]);
580        match classify_frame(&f) {
581            FrameKind::Event(p) => assert_eq!(p["event"], "task_assigned"),
582            _ => panic!("expected Event"),
583        }
584    }
585
586    #[test]
587    fn classify_recognizes_ack_reply() {
588        let f = json!(["1", "2", "agent:me", "phx_reply", { "status": "ok", "response": { "event_id": "x" } }]);
589        match classify_frame(&f) {
590            FrameKind::Acked(id) => assert_eq!(id, "x"),
591            _ => panic!("expected Acked"),
592        }
593    }
594
595    #[test]
596    fn classify_ignores_non_join_error_reply() {
597        let f = json!(["1", "2", "agent:me", "phx_reply", { "status": "error", "response": { "reason": "event_id required" } }]);
598        assert!(matches!(classify_frame(&f), FrameKind::Ignored));
599    }
600
601    #[test]
602    fn classify_ignores_other_topics() {
603        let f = json!([null, "2", "phoenix", "phx_reply", { "status": "ok" }]);
604        assert!(matches!(classify_frame(&f), FrameKind::Ignored));
605    }
606}