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/// Decode a single event JSON value tolerantly into an [`AgentEvent`].
88pub fn decode_event_item(
89 item: serde_json::Value,
90) -> std::result::Result<AgentEvent, UnparseableEvent> {
91 match serde_json::from_value::<AgentEvent>(item.clone()) {
92 Ok(ev) => Ok(ev),
93 Err(e) => Err(UnparseableEvent {
94 raw: item,
95 error: e.to_string(),
96 }),
97 }
98}
99
100/// Tolerant variant of [`list_events_page`].
101///
102/// Tries the strict progenitor decode first. On [`Error::Decode`] (the
103/// only failure mode a schema-drift-shaped single event can produce),
104/// falls back to a raw JSON fetch and decodes `data[]` item-by-item so
105/// one malformed event does not poison the whole page.
106///
107/// The pagination envelope (`meta`) is always strict — without it we
108/// cannot advance the cursor, so bailing is the only safe choice.
109///
110/// Cost: two HTTP round-trips on the Decode path (strict then raw).
111/// Acceptable because Decode only fires on schema drift — hot path is
112/// one request. Do **not** "optimize" by making raw the default; the
113/// strict path keeps type safety for the common case.
114pub async fn list_events_page_tolerant(
115 client: &TaskFastClient,
116 cursor: Option<&str>,
117 limit: Option<i64>,
118) -> Result<TolerantEventPage> {
119 match list_events_page(client, cursor, limit).await {
120 Ok(page) => Ok(TolerantEventPage {
121 events: page.data,
122 unparseable: Vec::new(),
123 meta: page.meta,
124 }),
125 Err(Error::Decode(_)) => decode_raw_page(client, cursor, limit).await,
126 Err(e) => Err(e),
127 }
128}
129
130async fn decode_raw_page(
131 client: &TaskFastClient,
132 cursor: Option<&str>,
133 limit: Option<i64>,
134) -> Result<TolerantEventPage> {
135 let raw = client.list_agent_events_raw(cursor, limit).await?;
136 // serde_json::from_value on Null produces a proper serde_json::Error,
137 // which Error::Decode converts via #[from]. Meta is strict by design:
138 // a broken envelope means we cannot advance the cursor.
139 let meta_v = raw.get("meta").cloned().unwrap_or(serde_json::Value::Null);
140 let meta: PaginatedMeta = serde_json::from_value(meta_v)?;
141 let data = raw
142 .get("data")
143 .and_then(|v| v.as_array())
144 .cloned()
145 .unwrap_or_default();
146
147 let mut events = Vec::with_capacity(data.len());
148 let mut unparseable = Vec::new();
149 for item in data {
150 match decode_event_item(item) {
151 Ok(ev) => events.push(ev),
152 Err(e) => unparseable.push(e),
153 }
154 }
155 Ok(TolerantEventPage {
156 events,
157 unparseable,
158 meta,
159 })
160}
161
162/// Internal state threaded through [`unfold`]. Kept private — callers
163/// should treat the returned [`Stream`] as opaque.
164struct StreamState {
165 cursor: Option<String>,
166 buffer: VecDeque<AgentEvent>,
167 /// Sleep gate. Flipped on when the last fetch returned
168 /// `has_more=false` (tip reached). Starts `false` so the very first
169 /// fetch is eager, and stays `false` across multi-page backfills so
170 /// we drain as fast as the network allows.
171 sleep_before_next_fetch: bool,
172}
173
174/// Long-running event stream. The returned [`Stream`] never ends on its
175/// own — drop it when the consumer is done. Each [`Result`] item is
176/// independent: the stream surfaces transient errors but does not abort,
177/// so consumers can `.next()` again to retry.
178pub fn stream_events(
179 client: &TaskFastClient,
180 start_cursor: Option<String>,
181 opts: PollOptions,
182) -> impl Stream<Item = Result<AgentEvent>> + '_ {
183 let state = StreamState {
184 cursor: start_cursor,
185 buffer: VecDeque::new(),
186 sleep_before_next_fetch: false,
187 };
188
189 unfold(state, move |mut state| async move {
190 loop {
191 if let Some(ev) = state.buffer.pop_front() {
192 return Some((Ok(ev), state));
193 }
194
195 if state.sleep_before_next_fetch {
196 sleep(opts.poll_interval).await;
197 }
198
199 match list_events_page(client, state.cursor.as_deref(), Some(opts.page_limit)).await {
200 Ok(page) => {
201 state.buffer.extend(page.data);
202 // Retain the last-known cursor when the server
203 // signals "no more" with a null next_cursor —
204 // sending None would re-stream old events.
205 state.cursor = page.meta.next_cursor.or(state.cursor);
206 state.sleep_before_next_fetch = !page.meta.has_more;
207 // Loop: either the buffer now has events to yield,
208 // or we just got an empty page and the next turn
209 // of the loop will sleep before fetching again.
210 }
211 Err(e) => {
212 // Surface the error but keep state intact so the
213 // consumer can retry by calling `.next()` again.
214 // Sleep before the retry to avoid hammering a
215 // failing server.
216 state.sleep_before_next_fetch = true;
217 return Some((Err(e), state));
218 }
219 }
220 }
221 })
222}
223
224#[cfg(test)]
225mod tests {
226 use super::*;
227
228 #[test]
229 fn default_poll_options_are_sane() {
230 let opts = PollOptions::default();
231 assert_eq!(opts.poll_interval, Duration::from_secs(5));
232 assert_eq!(opts.page_limit, 100);
233 }
234}