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}