taskfast_agent/events.rs
1// SPDX-License-Identifier: MIT
2//! Cursor-paginated event polling exposed as a `futures::Stream`.
3//!
4//! Two entry points:
5//!
6//! - [`list_events_page`] — single-page `GET /agents/me/events`; useful for
7//! CLI `events poll --cursor …` invocations that want manual control.
8//! - [`stream_events`] — long-running [`Stream`] of [`AgentEvent`] that
9//! chases `has_more` without sleeping and falls back to `poll_interval`
10//! only when it hits the page tip.
11//!
12//! # Cursor discipline
13//!
14//! When the server returns `next_cursor: null`, we've reached the tip.
15//! On the next poll we reuse the **last-known cursor** — sending `None`
16//! again would risk reprocessing the entire backlog. The server treats
17//! the cursor as opaque; the client must too.
18
19use std::collections::VecDeque;
20use std::time::Duration;
21
22use futures::stream::unfold;
23use futures::Stream;
24use taskfast_client::api::types::{AgentEvent, AgentEventListResponse, PaginatedMeta};
25use taskfast_client::{map_api_error, Error, Result, TaskFastClient};
26use tokio::time::sleep;
27
28/// One unparseable event carried alongside the decoded page so callers
29/// can surface partial success instead of failing the whole batch.
30#[derive(Debug, Clone)]
31pub struct UnparseableEvent {
32 /// Raw JSON as the server sent it. Kept so operators can diff
33 /// against the expected schema off-line.
34 pub raw: serde_json::Value,
35 /// serde decode error message in canonical form.
36 pub error: String,
37}
38
39/// Event page tolerant of per-item decode failures.
40///
41/// `meta` is still parsed strictly — if the pagination envelope breaks,
42/// the whole call fails (we cannot advance the cursor without it).
43/// Only individual `data[]` entries are allowed to fail independently.
44#[derive(Debug, Clone)]
45pub struct TolerantEventPage {
46 pub events: Vec<AgentEvent>,
47 pub unparseable: Vec<UnparseableEvent>,
48 pub meta: PaginatedMeta,
49}
50
51/// Default knobs. Page size of 100 matches the server's ceiling for this
52/// endpoint; a 5-second sleep at the tip balances liveness vs. quota
53/// pressure on long-idle agents.
54pub const DEFAULT_POLL_INTERVAL: Duration = Duration::from_secs(5);
55pub const DEFAULT_PAGE_LIMIT: i64 = 100;
56
57#[derive(Debug, Clone, Copy)]
58pub struct PollOptions {
59 pub poll_interval: Duration,
60 pub page_limit: i64,
61}
62
63impl Default for PollOptions {
64 fn default() -> Self {
65 Self {
66 poll_interval: DEFAULT_POLL_INTERVAL,
67 page_limit: DEFAULT_PAGE_LIMIT,
68 }
69 }
70}
71
72/// One-shot `GET /agents/me/events?cursor=…&limit=…`.
73pub async fn list_events_page(
74 client: &TaskFastClient,
75 cursor: Option<&str>,
76 limit: Option<i64>,
77) -> Result<AgentEventListResponse> {
78 // progenitor 0.14 / typify generates `limit` as `Option<NonZeroU64>`
79 // (the spec's `minimum: 1` now lives in the type).
80 let limit = limit.and_then(taskfast_client::page_limit);
81 match client.inner().list_agent_events(cursor, limit).await {
82 Ok(v) => Ok(v.into_inner()),
83 Err(e) => Err(map_api_error(e).await),
84 }
85}
86
87/// Tolerant variant of [`list_events_page`].
88///
89/// Tries the strict progenitor decode first. On [`Error::Decode`] (the
90/// only failure mode a schema-drift-shaped single event can produce),
91/// falls back to a raw JSON fetch and decodes `data[]` item-by-item so
92/// one malformed event does not poison the whole page.
93///
94/// The pagination envelope (`meta`) is always strict — without it we
95/// cannot advance the cursor, so bailing is the only safe choice.
96///
97/// Cost: two HTTP round-trips on the Decode path (strict then raw).
98/// Acceptable because Decode only fires on schema drift — hot path is
99/// one request. Do **not** "optimize" by making raw the default; the
100/// strict path keeps type safety for the common case.
101pub async fn list_events_page_tolerant(
102 client: &TaskFastClient,
103 cursor: Option<&str>,
104 limit: Option<i64>,
105) -> Result<TolerantEventPage> {
106 match list_events_page(client, cursor, limit).await {
107 Ok(page) => Ok(TolerantEventPage {
108 events: page.data,
109 unparseable: Vec::new(),
110 meta: page.meta,
111 }),
112 Err(Error::Decode(_)) => decode_raw_page(client, cursor, limit).await,
113 Err(e) => Err(e),
114 }
115}
116
117async fn decode_raw_page(
118 client: &TaskFastClient,
119 cursor: Option<&str>,
120 limit: Option<i64>,
121) -> Result<TolerantEventPage> {
122 let raw = client.list_agent_events_raw(cursor, limit).await?;
123 // serde_json::from_value on Null produces a proper serde_json::Error,
124 // which Error::Decode converts via #[from]. Meta is strict by design:
125 // a broken envelope means we cannot advance the cursor.
126 let meta_v = raw.get("meta").cloned().unwrap_or(serde_json::Value::Null);
127 let meta: PaginatedMeta = serde_json::from_value(meta_v)?;
128 let data = raw
129 .get("data")
130 .and_then(|v| v.as_array())
131 .cloned()
132 .unwrap_or_default();
133
134 let mut events = Vec::with_capacity(data.len());
135 let mut unparseable = Vec::new();
136 for item in data {
137 match serde_json::from_value::<AgentEvent>(item.clone()) {
138 Ok(ev) => events.push(ev),
139 Err(e) => unparseable.push(UnparseableEvent {
140 raw: item,
141 error: e.to_string(),
142 }),
143 }
144 }
145 Ok(TolerantEventPage {
146 events,
147 unparseable,
148 meta,
149 })
150}
151
152/// Internal state threaded through [`unfold`]. Kept private — callers
153/// should treat the returned [`Stream`] as opaque.
154struct StreamState {
155 cursor: Option<String>,
156 buffer: VecDeque<AgentEvent>,
157 /// Sleep gate. Flipped on when the last fetch returned
158 /// `has_more=false` (tip reached). Starts `false` so the very first
159 /// fetch is eager, and stays `false` across multi-page backfills so
160 /// we drain as fast as the network allows.
161 sleep_before_next_fetch: bool,
162}
163
164/// Long-running event stream. The returned [`Stream`] never ends on its
165/// own — drop it when the consumer is done. Each [`Result`] item is
166/// independent: the stream surfaces transient errors but does not abort,
167/// so consumers can `.next()` again to retry.
168pub fn stream_events(
169 client: &TaskFastClient,
170 start_cursor: Option<String>,
171 opts: PollOptions,
172) -> impl Stream<Item = Result<AgentEvent>> + '_ {
173 let state = StreamState {
174 cursor: start_cursor,
175 buffer: VecDeque::new(),
176 sleep_before_next_fetch: false,
177 };
178
179 unfold(state, move |mut state| async move {
180 loop {
181 if let Some(ev) = state.buffer.pop_front() {
182 return Some((Ok(ev), state));
183 }
184
185 if state.sleep_before_next_fetch {
186 sleep(opts.poll_interval).await;
187 }
188
189 match list_events_page(client, state.cursor.as_deref(), Some(opts.page_limit)).await {
190 Ok(page) => {
191 state.buffer.extend(page.data);
192 // Retain the last-known cursor when the server
193 // signals "no more" with a null next_cursor —
194 // sending None would re-stream old events.
195 state.cursor = page.meta.next_cursor.or(state.cursor);
196 state.sleep_before_next_fetch = !page.meta.has_more;
197 // Loop: either the buffer now has events to yield,
198 // or we just got an empty page and the next turn
199 // of the loop will sleep before fetching again.
200 }
201 Err(e) => {
202 // Surface the error but keep state intact so the
203 // consumer can retry by calling `.next()` again.
204 // Sleep before the retry to avoid hammering a
205 // failing server.
206 state.sleep_before_next_fetch = true;
207 return Some((Err(e), state));
208 }
209 }
210 }
211 })
212}
213
214#[cfg(test)]
215mod tests {
216 use super::*;
217
218 #[test]
219 fn default_poll_options_are_sane() {
220 let opts = PollOptions::default();
221 assert_eq!(opts.poll_interval, Duration::from_secs(5));
222 assert_eq!(opts.page_limit, 100);
223 }
224}