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/// 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}