Skip to main content

taskfast_cli/cmd/events/
mod.rs

1// SPDX-License-Identifier: MIT
2//! `taskfast events` — lifecycle event read/stream/ack + AsyncAPI schema.
3//!
4//! Subcommands:
5//!
6//! * [`poll`] — one-shot `GET /api/agents/me/events` (cursor-paginated
7//!   read). Envelope-wrapped like every other subcommand.
8//! * [`stream`] — long-running WebSocket to `/socket/agent` that emits
9//!   one JSONL line per event on stdout. Bypasses the envelope — stdout
10//!   is the contract. `--ack-stdin` acks events on the same socket,
11//!   which advances the server-side cursor and releases the next event.
12//! * [`ack`] — retired. The server has no HTTP ack route; the command
13//!   fails with a pointer to `events stream --ack-stdin`.
14//! * [`schema`] — `GET /api/asyncapi.json`. Prints the full AsyncAPI
15//!   2.6 document or filters to a single event type via `--event`.
16
17use clap::Subcommand;
18
19use super::{CmdError, CmdResult, Ctx};
20
21pub mod ack;
22pub mod intake;
23pub mod poll;
24pub mod schema;
25pub mod seen;
26pub mod stream;
27
28pub use ack::AckArgs;
29pub use intake::{EventIntake, IngestBatchOutcome, IntakeMetrics, StreamItemOutcome};
30pub use poll::PollArgs;
31pub use schema::SchemaArgs;
32pub use stream::StreamArgs;
33
34#[derive(Debug, Subcommand)]
35pub enum Command {
36    /// GET /agents/me/events — one page of lifecycle events.
37    Poll(PollArgs),
38    /// Stream lifecycle events over WebSocket as JSONL on stdout.
39    ///
40    /// Bypasses the JSON envelope: every line is either an event
41    /// payload or a sentinel (`{"sentinel":"connected"}`,
42    /// `{"sentinel":"reconnecting"}`, `{"sentinel":"resumed"}`,
43    /// `{"sentinel":"closing"}`, `{"sentinel":"acked",…}`). Pass
44    /// `--ack-stdin` and write each event id to stdin once handled;
45    /// the server holds later events until the current one is acked.
46    Stream(StreamArgs),
47    /// Unsupported: the server has no HTTP ack route. Use
48    /// `events stream --ack-stdin`.
49    Ack(AckArgs),
50    /// GET /asyncapi.json — AsyncAPI 2.6 schema for the event stream.
51    Schema(SchemaArgs),
52}
53
54/// Dispatch non-stream subcommands. `Stream` is handled in `main.rs`
55/// because it writes JSONL directly to stdout and must bypass the
56/// envelope wrapper.
57pub async fn run(ctx: &Ctx, cmd: Command) -> CmdResult {
58    match cmd {
59        Command::Poll(a) => poll::run(ctx, a).await,
60        Command::Ack(a) => ack::run(a),
61        Command::Schema(a) => schema::run(ctx, a).await,
62        Command::Stream(_) => Err(CmdError::Usage(
63            "`events stream` must be dispatched by main.rs (bypass envelope)".into(),
64        )),
65    }
66}