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