Skip to main content

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}