Skip to main content

Module stream

Module stream 

Source
Expand description

taskfast events stream — long-running WebSocket tail on /socket/agent.

§Contract

Stdout is JSONL. Each line is either an event payload (matching the AsyncAPI components.messages shape) or a sentinel frame:

  • {"sentinel":"connected"} — initial join succeeded.
  • {"sentinel":"reconnecting"} — transport dropped; backoff started.
  • {"sentinel":"resumed"} — reconnect succeeded; backlog drains.
  • {"sentinel":"closing"} — SIGINT/SIGTERM received; exiting 0.
  • {"sentinel":"auth_failed"} — server rejected the API key; exits 2.
  • {"sentinel":"acked","event_id":"…"} — server confirmed an ack sent via --ack-stdin.

§Auth

The API key is sent via the Sec-WebSocket-Protocol handshake header (taskfast.v1, bearer.<key>). Keeping credentials off the URL line keeps them out of proxy access logs and browser history-like caches.

§Ack mechanic

The server keeps one event in flight and pushes the next only after the current one is acked as an ack message on this channel — there is no HTTP ack route, and a second socket would kick this one (one socket per agent). With --ack-stdin the stream reads event ids from stdin, one per line, and sends each as [join_ref, ref, "agent:me", "ack", {"event_id": id}]. Write the id after handling the event to keep at-least-once delivery.

The server only replies to an ack for the in-flight event; a stale id gets no reply and no acked sentinel. Ids written while the socket is down wait in the pipe until rejoin. An ack lost with a dying socket is harmless: the server replays from its ack cursor on rejoin, so the event is redelivered and can be acked again.

§Protocol

Phoenix Channels v2 JSON envelope: [join_ref, msg_ref, topic, event, payload]. The server pushes marketplace events as event == "event". Heartbeat every 30s on topic "phoenix". Reconnect uses exponential backoff (1s → 2s → 4s → … → 30s cap); same backlog replays from cursor on resume (server-side state).

Structs§

StreamArgs

Functions§

run
Entry point. Returns a process exit code because the stream sidesteps the envelope wrapper: error envelopes would contaminate the JSONL stream and swallow stdout buffering semantics.