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    let mut intake = super::intake::EventIntake::from_ctx(ctx, None);
119
120    loop {
121        if shutdown.is_cancelled() {
122            emit_sentinel("closing");
123            return ExitCode::SUCCESS;
124        }
125
126        match run_once(
127            &ws_url,
128            &api_key,
129            first_connect,
130            args.once,
131            &shutdown,
132            ack_lines.as_mut(),
133            &mut intake,
134        )
135        .await
136        {
137            ConnectOutcome::AuthFailed => {
138                emit_sentinel("auth_failed");
139                return ExitCode::from(2);
140            }
141            ConnectOutcome::Shutdown => {
142                emit_sentinel("closing");
143                return ExitCode::SUCCESS;
144            }
145            ConnectOutcome::OnceDone => {
146                return ExitCode::SUCCESS;
147            }
148            ConnectOutcome::Disconnected => {
149                // Fall through to reconnect loop below.
150            }
151        }
152
153        if args.no_reconnect {
154            // Surface the drop as a non-zero exit so supervisors (systemd,
155            // k8s) see it as a failure and respawn under their own policy.
156            return ExitCode::from(1);
157        }
158
159        emit_sentinel("reconnecting");
160        let wait = backoff;
161        tokio::select! {
162            () = sleep(wait) => {},
163            () = shutdown.cancelled() => {
164                emit_sentinel("closing");
165                return ExitCode::SUCCESS;
166            }
167        }
168        backoff = (backoff * 2).min(RECONNECT_CAP);
169        first_connect = false;
170    }
171}
172
173enum ConnectOutcome {
174    AuthFailed,
175    Shutdown,
176    OnceDone,
177    Disconnected,
178}
179
180async fn run_once(
181    ws_url: &str,
182    api_key: &str,
183    first_connect: bool,
184    once: bool,
185    shutdown: &ShutdownToken,
186    mut ack_lines: Option<&mut UnboundedReceiver<String>>,
187    intake: &mut super::intake::EventIntake,
188) -> ConnectOutcome {
189    let req = match build_request(ws_url, api_key) {
190        Ok(r) => r,
191        Err(_) => return ConnectOutcome::Disconnected,
192    };
193
194    let (ws, resp) = match tokio_tungstenite::connect_async(req).await {
195        Ok(v) => v,
196        Err(e) => {
197            if is_auth_error(&e) {
198                return ConnectOutcome::AuthFailed;
199            }
200            return ConnectOutcome::Disconnected;
201        }
202    };
203
204    // Server must select `taskfast.v1`. If it didn't, either the socket
205    // rejected us or a middlebox rewrote the handshake — treat as auth.
206    if !has_taskfast_subprotocol(&resp) {
207        return ConnectOutcome::AuthFailed;
208    }
209
210    let (mut sink, mut source) = ws.split();
211
212    // Phoenix join
213    let join_msg = phx_frame(JOIN_REF, JOIN_REF, TOPIC, "phx_join", json!({}));
214    if sink.send(Message::Text(join_msg.into())).await.is_err() {
215        return ConnectOutcome::Disconnected;
216    }
217
218    // Await join reply before announcing connected.
219    let mut join_acked = false;
220    let mut msg_ref: u64 = 1;
221    let mut heartbeat_next = Instant::now() + HEARTBEAT_INTERVAL;
222
223    loop {
224        tokio::select! {
225            () = shutdown.cancelled() => {
226                let _ = sink.send(Message::Close(None)).await;
227                return ConnectOutcome::Shutdown;
228            }
229            () = sleep_until(heartbeat_next) => {
230                msg_ref += 1;
231                let hb = phx_frame_null_join(&msg_ref.to_string(), "phoenix", "heartbeat", json!({}));
232                if sink.send(Message::Text(hb.into())).await.is_err() {
233                    return ConnectOutcome::Disconnected;
234                }
235                heartbeat_next = Instant::now() + HEARTBEAT_INTERVAL;
236            }
237            // Acks only make sense on a joined channel.
238            line = next_ack(&mut ack_lines), if join_acked => match line {
239                Some(id) => {
240                    let id = id.trim();
241                    if id.is_empty() {
242                        continue;
243                    }
244                    msg_ref += 1;
245                    let ack = phx_frame(JOIN_REF, &msg_ref.to_string(), TOPIC, "ack", json!({ "event_id": id }));
246                    if sink.send(Message::Text(ack.into())).await.is_err() {
247                        return ConnectOutcome::Disconnected;
248                    }
249                }
250                // EOF or unreadable stdin: stop reading, keep streaming.
251                None => ack_lines = None,
252            },
253            frame = source.next() => {
254                match frame {
255                    Some(Ok(Message::Text(text))) => {
256                        let parsed: Value = match serde_json::from_str(&text) {
257                            Ok(v) => v,
258                            Err(e) => {
259                                tracing::warn!(
260                                    target: "taskfast::events",
261                                    error = %e,
262                                    "WS text frame was not valid JSON; surfacing as unparseable"
263                                );
264                                intake.record_unparseable();
265                                emit_unparseable(&text, &e.to_string());
266                                continue;
267                            }
268                        };
269                        match classify_frame(&parsed) {
270                            FrameKind::JoinOk => {
271                                if !join_acked {
272                                    join_acked = true;
273                                    let sentinel = if first_connect { "connected" } else { "resumed" };
274                                    emit_sentinel(sentinel);
275                                }
276                            }
277                            FrameKind::JoinError => {
278                                return ConnectOutcome::AuthFailed;
279                            }
280                            FrameKind::Event(payload) => {
281                                match intake.ingest_stream_payload(&payload) {
282                                    super::intake::StreamItemOutcome::Duplicate { event_id } => {
283                                        // Duplicate (replay after a lost ack): re-ack so the
284                                        // server moves on, print nothing.
285                                        msg_ref += 1;
286                                        let ack = phx_frame(JOIN_REF, &msg_ref.to_string(), TOPIC, "ack", json!({ "event_id": event_id }));
287                                        if sink.send(Message::Text(ack.into())).await.is_err() {
288                                            return ConnectOutcome::Disconnected;
289                                        }
290                                    }
291                                    super::intake::StreamItemOutcome::Accepted { .. } => {
292                                        emit_event(&payload);
293                                        if once {
294                                            let _ = sink.send(Message::Close(None)).await;
295                                            return ConnectOutcome::OnceDone;
296                                        }
297                                    }
298                                    super::intake::StreamItemOutcome::Malformed { error } => {
299                                        emit_unparseable(&payload.to_string(), &error);
300                                        if once {
301                                            let _ = sink.send(Message::Close(None)).await;
302                                            return ConnectOutcome::OnceDone;
303                                        }
304                                    }
305                                }
306                            }
307                            FrameKind::Acked(id) => {
308                                emit_event(&json!({ "sentinel": "acked", "event_id": id }));
309                            }
310                            FrameKind::Ignored => {}
311                        }
312                    }
313                    Some(Ok(Message::Ping(payload))) => {
314                        let _ = sink.send(Message::Pong(payload)).await;
315                    }
316                    Some(Ok(Message::Close(_))) | None => {
317                        return ConnectOutcome::Disconnected;
318                    }
319                    Some(Err(_)) => {
320                        return ConnectOutcome::Disconnected;
321                    }
322                    _ => {}
323                }
324            }
325        }
326    }
327}
328
329/// Read stdin on a plain thread. tokio's stdin read can't be cancelled, so
330/// a pending read would hold the runtime open at exit for as long as the
331/// host keeps the pipe open; a detached thread doesn't.
332fn spawn_stdin_reader() -> UnboundedReceiver<String> {
333    let (tx, rx) = unbounded_channel();
334    std::thread::spawn(move || {
335        for line in std::io::stdin().lock().lines().map_while(Result::ok) {
336            if tx.send(line).is_err() {
337                break;
338            }
339        }
340    });
341    rx
342}
343
344/// Next ack id from stdin; never resolves once stdin is closed (`None`).
345async fn next_ack(rx: &mut Option<&mut UnboundedReceiver<String>>) -> Option<String> {
346    match rx {
347        Some(rx) => rx.recv().await,
348        None => std::future::pending().await,
349    }
350}
351
352async fn sleep_until(deadline: Instant) {
353    let now = Instant::now();
354    if deadline <= now {
355        return;
356    }
357    sleep(deadline - now).await;
358}
359
360enum FrameKind {
361    JoinOk,
362    JoinError,
363    Acked(String),
364    Event(Value),
365    Ignored,
366}
367
368fn classify_frame(frame: &Value) -> FrameKind {
369    let arr = match frame.as_array() {
370        Some(a) if a.len() == 5 => a,
371        _ => return FrameKind::Ignored,
372    };
373    let topic = arr[2].as_str().unwrap_or("");
374    let event = arr[3].as_str().unwrap_or("");
375    let payload = &arr[4];
376
377    if event == "phx_reply" && topic == TOPIC {
378        // Any ref other than the join's answers an ack we sent. Its error
379        // replies must not reach the JoinError → auth_failed path.
380        if arr[1].as_str() != Some(JOIN_REF) {
381            return payload
382                .pointer("/response/event_id")
383                .and_then(Value::as_str)
384                .map_or(FrameKind::Ignored, |id| FrameKind::Acked(id.to_string()));
385        }
386        let status = payload.get("status").and_then(|v| v.as_str()).unwrap_or("");
387        return match status {
388            "ok" => FrameKind::JoinOk,
389            "error" => FrameKind::JoinError,
390            _ => FrameKind::Ignored,
391        };
392    }
393    if event == "event" && topic == TOPIC {
394        return FrameKind::Event(payload.clone());
395    }
396    FrameKind::Ignored
397}
398
399fn phx_frame(join_ref: &str, msg_ref: &str, topic: &str, event: &str, payload: Value) -> String {
400    serde_json::to_string(&json!([join_ref, msg_ref, topic, event, payload]))
401        .expect("phoenix frame must serialize")
402}
403
404fn phx_frame_null_join(msg_ref: &str, topic: &str, event: &str, payload: Value) -> String {
405    serde_json::to_string(&json!([Value::Null, msg_ref, topic, event, payload]))
406        .expect("phoenix frame must serialize")
407}
408
409fn build_request(
410    ws_url: &str,
411    api_key: &str,
412) -> Result<tokio_tungstenite::tungstenite::handshake::client::Request, CmdError> {
413    let uri: Uri =
414        ws_url
415            .parse()
416            .map_err(|e: tokio_tungstenite::tungstenite::http::uri::InvalidUri| {
417                CmdError::Usage(format!("invalid ws url {ws_url:?}: {e}"))
418            })?;
419    let builder = ClientRequestBuilder::new(uri)
420        .with_sub_protocol("taskfast.v1")
421        .with_sub_protocol(format!("bearer.{api_key}"));
422    builder
423        .into_client_request()
424        .map_err(|e| CmdError::Usage(format!("ws request build failed: {e}")))
425}
426
427fn has_taskfast_subprotocol(
428    resp: &tokio_tungstenite::tungstenite::handshake::client::Response,
429) -> bool {
430    resp.headers()
431        .get("sec-websocket-protocol")
432        .and_then(|v| v.to_str().ok())
433        .is_some_and(|s| s.split(',').any(|tok| tok.trim() == "taskfast.v1"))
434}
435
436fn is_auth_error(e: &tokio_tungstenite::tungstenite::Error) -> bool {
437    use tokio_tungstenite::tungstenite::Error as TE;
438    match e {
439        TE::Http(resp) => matches!(resp.status().as_u16(), 401 | 403),
440        _ => false,
441    }
442}
443
444fn ws_url_from_base(base: &str) -> Result<String, CmdError> {
445    let trimmed = base.trim_end_matches('/');
446    let swapped = if let Some(rest) = trimmed.strip_prefix("https://") {
447        format!("wss://{rest}")
448    } else if let Some(rest) = trimmed.strip_prefix("http://") {
449        format!("ws://{rest}")
450    } else if trimmed.starts_with("wss://") || trimmed.starts_with("ws://") {
451        trimmed.to_string()
452    } else {
453        return Err(CmdError::Usage(format!(
454            "base url must start with http(s):// or ws(s)://, got {base:?}"
455        )));
456    };
457    Ok(format!("{swapped}/socket/agent/websocket?vsn=2.0.0"))
458}
459
460fn emit_sentinel(kind: &str) {
461    let line = format!("{}\n", json!({ "sentinel": kind }));
462    let stdout = std::io::stdout();
463    let mut guard = stdout.lock();
464    let _ = guard.write_all(line.as_bytes());
465    let _ = guard.flush();
466}
467
468fn emit_event(payload: &Value) {
469    let mut buf = match serde_json::to_vec(payload) {
470        Ok(b) => b,
471        Err(_) => return,
472    };
473    buf.push(b'\n');
474    let stdout = std::io::stdout();
475    let mut guard = stdout.lock();
476    let _ = guard.write_all(&buf);
477    let _ = guard.flush();
478}
479
480/// Surface a malformed WS text frame on the `--json` path instead of
481/// swallowing it. The `type: "unparseable"` tag keeps consumers' stream
482/// parsers from mistaking it for a regular event.
483fn emit_unparseable(raw: &str, error: &str) {
484    let payload = json!({ "type": "unparseable", "raw": raw, "error": error });
485    emit_event(&payload);
486}
487
488fn emit_error_envelope(ctx: &Ctx, err: &CmdError) {
489    if ctx.quiet {
490        return;
491    }
492    crate::envelope::Envelope::error(ctx.environment, ctx.dry_run, err).emit();
493}
494
495#[derive(Clone)]
496struct ShutdownToken {
497    inner: Arc<tokio::sync::Notify>,
498    flag: Arc<std::sync::atomic::AtomicBool>,
499}
500
501impl ShutdownToken {
502    fn new() -> Self {
503        Self {
504            inner: Arc::new(tokio::sync::Notify::new()),
505            flag: Arc::new(std::sync::atomic::AtomicBool::new(false)),
506        }
507    }
508
509    fn trigger(&self) {
510        self.flag.store(true, std::sync::atomic::Ordering::SeqCst);
511        self.inner.notify_waiters();
512    }
513
514    fn is_cancelled(&self) -> bool {
515        self.flag.load(std::sync::atomic::Ordering::SeqCst)
516    }
517
518    async fn cancelled(&self) {
519        if self.is_cancelled() {
520            return;
521        }
522        self.inner.notified().await;
523    }
524}
525
526fn install_shutdown_signal() -> ShutdownToken {
527    let token = ShutdownToken::new();
528    let tclone = token.clone();
529    tokio::spawn(async move {
530        #[cfg(unix)]
531        {
532            use tokio::signal::unix::{signal, SignalKind};
533            let mut term = match signal(SignalKind::terminate()) {
534                Ok(s) => s,
535                Err(_) => {
536                    let _ = tokio::signal::ctrl_c().await;
537                    tclone.trigger();
538                    return;
539                }
540            };
541            tokio::select! {
542                _ = term.recv() => {}
543                _ = tokio::signal::ctrl_c() => {}
544            }
545        }
546        #[cfg(not(unix))]
547        {
548            let _ = tokio::signal::ctrl_c().await;
549        }
550        tclone.trigger();
551    });
552    token
553}
554
555#[cfg(test)]
556mod tests {
557    use super::*;
558
559    #[test]
560    fn ws_url_swaps_http_to_ws() {
561        assert_eq!(
562            ws_url_from_base("http://localhost:4000").unwrap(),
563            "ws://localhost:4000/socket/agent/websocket?vsn=2.0.0"
564        );
565    }
566
567    #[test]
568    fn ws_url_swaps_https_to_wss() {
569        assert_eq!(
570            ws_url_from_base("https://api.taskfast.app/").unwrap(),
571            "wss://api.taskfast.app/socket/agent/websocket?vsn=2.0.0"
572        );
573    }
574
575    #[test]
576    fn ws_url_passthrough_ws_scheme() {
577        assert_eq!(
578            ws_url_from_base("ws://localhost:4000").unwrap(),
579            "ws://localhost:4000/socket/agent/websocket?vsn=2.0.0"
580        );
581    }
582
583    #[test]
584    fn ws_url_rejects_unknown_scheme() {
585        assert!(ws_url_from_base("ftp://x").is_err());
586    }
587
588    #[test]
589    fn classify_recognizes_join_ok() {
590        let f = json!(["1", "1", "agent:me", "phx_reply", { "status": "ok", "response": {} }]);
591        assert!(matches!(classify_frame(&f), FrameKind::JoinOk));
592    }
593
594    #[test]
595    fn classify_recognizes_join_error() {
596        let f = json!(["1", "1", "agent:me", "phx_reply", { "status": "error" }]);
597        assert!(matches!(classify_frame(&f), FrameKind::JoinError));
598    }
599
600    #[test]
601    fn classify_recognizes_event_push() {
602        let f =
603            json!(["1", null, "agent:me", "event", { "event_id": "x", "event": "task_assigned" }]);
604        match classify_frame(&f) {
605            FrameKind::Event(p) => assert_eq!(p["event"], "task_assigned"),
606            _ => panic!("expected Event"),
607        }
608    }
609
610    #[test]
611    fn classify_recognizes_ack_reply() {
612        let f = json!(["1", "2", "agent:me", "phx_reply", { "status": "ok", "response": { "event_id": "x" } }]);
613        match classify_frame(&f) {
614            FrameKind::Acked(id) => assert_eq!(id, "x"),
615            _ => panic!("expected Acked"),
616        }
617    }
618
619    #[test]
620    fn classify_ignores_non_join_error_reply() {
621        let f = json!(["1", "2", "agent:me", "phx_reply", { "status": "error", "response": { "reason": "event_id required" } }]);
622        assert!(matches!(classify_frame(&f), FrameKind::Ignored));
623    }
624
625    #[test]
626    fn classify_ignores_other_topics() {
627        let f = json!([null, "2", "phoenix", "phx_reply", { "status": "ok" }]);
628        assert!(matches!(classify_frame(&f), FrameKind::Ignored));
629    }
630}