zc2 0.0.52

P2P compute broker with yen-denominated billing, WAL, and broker mesh support
//! The agent's jobs journal behind `GET /v2/jobs` and `jobs.live` in summary
//! v2 (ADR ZC-0019 §2, §4).
//!
//! What the agent can observe today is its own workers through the local
//! broker's `GET /workers`: how many requests each one has in flight, and how
//! many it served in the last five hours. A *job* here is one busy span of
//! one worker: it starts on the tick a worker goes from no request in flight
//! to at least one, and finishes on the tick it goes back to none (or
//! disappears). `requests` is how many requests it served in that span.
//!
//! `source` and `squad` are always `null` for now: the broker does not say
//! where a request came from yet (spaces, a peer, hub serving, ...). That
//! attribution arrives with the unified admission queue (zc#514). The filter
//! parameters are accepted already, so a client written against the ADR
//! keeps working when it does.
//!
//! Bounded: the last [`DONE_KEPT`] finished jobs are kept, in `jobs.json`
//! next to `state.json`. A job that was live when the agent stopped is not
//! carried over: the next run starts it again if the worker is still busy.

use crate::agent::files;
use crate::agent::supervisor::BrokerWorker;
use chrono::{DateTime, SecondsFormat, Utc};
use serde::{Deserialize, Serialize};
use std::collections::{BTreeMap, VecDeque};
use std::path::{Path, PathBuf};

/// How many finished jobs the journal keeps.
pub const DONE_KEPT: usize = 200;

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct Job {
    pub id: String,
    /// `live` | `done`.
    pub state: String,
    /// Always `null` until the broker attributes requests (zc#514).
    pub source: Option<String>,
    /// Always `null` until squads exist (zc#517).
    pub squad: Option<String>,
    /// The worker's name, as the agent named it (`<node>-w<i>`).
    pub worker: String,
    pub started_at: String,
    pub finished_at: Option<String>,
    /// Requests served in this span so far.
    pub requests: u64,
}

/// `job.started` or `job.finished`, with the job as it is at that moment.
#[derive(Debug, Clone, PartialEq)]
pub struct JobEvent {
    pub kind: &'static str,
    pub job: Job,
}

#[derive(Debug, Default, Serialize, Deserialize)]
struct Persisted {
    v: u32,
    next: u64,
    done: VecDeque<Job>,
}

struct Live {
    job: Job,
    /// The worker's `requests_5h` when the span started.
    base: u64,
}

pub struct Journal {
    path: Option<PathBuf>,
    next: u64,
    live: BTreeMap<String, Live>,
    done: VecDeque<Job>,
}

fn ts(t: DateTime<Utc>) -> String {
    t.to_rfc3339_opts(SecondsFormat::Secs, true)
}

impl Journal {
    /// The journal in `<dir>/jobs.json`, or an empty one when it is missing
    /// or unreadable.
    pub fn load(dir: &Path) -> Self {
        let path = dir.join(files::JOBS_FILE);
        let p: Persisted = files::load_json(&path)
            .filter(|p: &Persisted| p.v == 1)
            .unwrap_or_default();
        Self {
            path: Some(path),
            next: p.next.max(1),
            live: BTreeMap::new(),
            done: p.done,
        }
    }

    #[cfg(test)]
    pub fn in_memory() -> Self {
        Self {
            path: None,
            next: 1,
            live: BTreeMap::new(),
            done: VecDeque::new(),
        }
    }

    fn save(&self) {
        if let Some(path) = &self.path {
            let p = Persisted {
                v: 1,
                next: self.next,
                done: self.done.clone(),
            };
            let _ = files::save_json(path, &p);
        }
    }

    /// Fold one observation of this node's workers in. `None` means this
    /// tick could not see them (the broker is starting, or `GET /workers`
    /// failed): nothing starts or finishes on an unknown.
    pub fn observe(
        &mut self,
        workers: Option<&[BrokerWorker]>,
        now: DateTime<Utc>,
    ) -> Vec<JobEvent> {
        let Some(workers) = workers else {
            return vec![];
        };
        let mut events = vec![];
        // Finish first, so a worker that went idle and busy again between two
        // ticks is still one span (it never reads as idle here).
        let names: Vec<String> = self.live.keys().cloned().collect();
        for name in names {
            let seen = workers.iter().find(|w| w.name == name);
            if seen.is_some_and(|w| w.active_requests > 0) {
                continue;
            }
            let mut live = self.live.remove(&name).expect("key just listed");
            // At least the one that made it busy, even when the counter
            // didn't move (or the worker went away before we saw it).
            let served = seen.map_or(0, |w| w.requests_5h.saturating_sub(live.base));
            live.job.requests = served.max(live.job.requests).max(1);
            live.job.state = "done".into();
            live.job.finished_at = Some(ts(now));
            events.push(JobEvent {
                kind: "job.finished",
                job: live.job.clone(),
            });
            if self.done.len() == DONE_KEPT {
                self.done.pop_front();
            }
            self.done.push_back(live.job);
        }
        for w in workers.iter().filter(|w| w.active_requests > 0) {
            if let Some(live) = self.live.get_mut(&w.name) {
                live.job.requests = w.requests_5h.saturating_sub(live.base);
                continue;
            }
            let job = Job {
                id: format!("j{}", self.next),
                state: "live".into(),
                source: None,
                squad: None,
                worker: w.name.clone(),
                started_at: ts(now),
                finished_at: None,
                requests: 0,
            };
            self.next += 1;
            events.push(JobEvent {
                kind: "job.started",
                job: job.clone(),
            });
            self.live.insert(
                w.name.clone(),
                Live {
                    job,
                    // The request now in flight is not counted in requests_5h
                    // until it completes, so the span's count starts here.
                    base: w.requests_5h,
                },
            );
        }
        if !events.is_empty() {
            self.save();
        }
        events
    }

    pub fn live(&self) -> Vec<Job> {
        self.live.values().map(|l| l.job.clone()).collect()
    }

    /// Finished jobs whose `finished_at` is at or after `since`.
    pub fn done_since(&self, since: DateTime<Utc>) -> usize {
        self.done
            .iter()
            .filter(|j| {
                j.finished_at
                    .as_deref()
                    .and_then(|t| DateTime::parse_from_rfc3339(t).ok())
                    .is_some_and(|t| t >= since)
            })
            .count()
    }

    /// `GET /v2/jobs`: live ones first (oldest first), then finished ones,
    /// newest first.
    pub fn query(&self, q: &Query) -> Vec<Job> {
        let mut out: Vec<Job> = vec![];
        if q.state.as_deref() != Some("done") {
            out.extend(self.live());
        }
        if q.state.as_deref() != Some("live") {
            out.extend(self.done.iter().rev().cloned());
        }
        out.retain(|j| {
            q.source
                .as_ref()
                .is_none_or(|s| j.source.as_ref() == Some(s))
                && q.squad.as_ref().is_none_or(|s| j.squad.as_ref() == Some(s))
                && q.since.is_none_or(|since| {
                    DateTime::parse_from_rfc3339(&j.started_at).is_ok_and(|t| t >= since)
                        || j.finished_at
                            .as_deref()
                            .and_then(|t| DateTime::parse_from_rfc3339(t).ok())
                            .is_some_and(|t| t >= since)
                })
        });
        out
    }
}

/// The sources ADR ZC-0019 §2 names for `?source=`.
pub const SOURCES: &[&str] = &[
    "spaces",
    "env_guest",
    "hub_serving",
    "atelier",
    "peer",
    "test",
];

#[derive(Debug, Default, Clone, PartialEq)]
pub struct Query {
    pub state: Option<String>,
    pub source: Option<String>,
    pub squad: Option<String>,
    pub since: Option<DateTime<Utc>>,
}

impl Query {
    /// Validate the raw query parameters; `Err` is the 400 message.
    pub fn parse(
        state: Option<String>,
        source: Option<String>,
        squad: Option<String>,
        since: Option<String>,
    ) -> Result<Self, String> {
        let empty = |o: Option<String>| o.filter(|s| !s.is_empty());
        let state = empty(state);
        if let Some(s) = &state {
            if s != "live" && s != "done" {
                return Err(format!(r#"state must be "live" or "done", got {s:?}"#));
            }
        }
        let source = empty(source);
        if let Some(s) = &source {
            if !SOURCES.contains(&s.as_str()) {
                return Err(format!(
                    "source must be one of {}, got {s:?}",
                    SOURCES.join(", ")
                ));
            }
        }
        let since = match empty(since) {
            None => None,
            Some(s) => Some(
                DateTime::parse_from_rfc3339(&s)
                    .map_err(|_| format!("since must be an RFC 3339 timestamp, got {s:?}"))?
                    .with_timezone(&Utc),
            ),
        };
        Ok(Self {
            state,
            source,
            squad: empty(squad),
            since,
        })
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use chrono::TimeZone;

    fn w(name: &str, active: u32, served: u64) -> BrokerWorker {
        BrokerWorker {
            id: format!("id-{name}"),
            name: name.into(),
            status: "healthy".into(),
            active_requests: active,
            requests_5h: served,
            requests_1w: served,
        }
    }

    fn at(s: i64) -> DateTime<Utc> {
        Utc.timestamp_opt(1_790_000_000 + s, 0).unwrap()
    }

    #[test]
    fn a_busy_span_is_one_job_from_start_to_finish() {
        let mut j = Journal::in_memory();
        assert!(j.observe(Some(&[w("n-w0", 0, 5)]), at(0)).is_empty());
        let ev = j.observe(Some(&[w("n-w0", 1, 5)]), at(2));
        assert_eq!(ev.len(), 1);
        assert_eq!((ev[0].kind, ev[0].job.id.as_str()), ("job.started", "j1"));
        assert_eq!(j.live().len(), 1);
        // Still busy, one more served: no event, the count moves.
        assert!(j.observe(Some(&[w("n-w0", 2, 6)]), at(4)).is_empty());
        assert_eq!(j.live()[0].requests, 1);
        // Unknown tick: nothing finishes.
        assert!(j.observe(None, at(6)).is_empty());
        let ev = j.observe(Some(&[w("n-w0", 0, 8)]), at(8));
        assert_eq!(ev[0].kind, "job.finished");
        assert_eq!(ev[0].job.requests, 3);
        assert_eq!(
            ev[0].job.finished_at.as_deref(),
            Some("2026-09-21T14:13:28Z")
        );
        assert!(j.live().is_empty());
        assert_eq!(j.done_since(at(0)), 1);
        assert_eq!(j.done_since(at(9)), 0);
    }

    #[test]
    fn a_worker_that_disappears_finishes_its_job_with_at_least_one_request() {
        let mut j = Journal::in_memory();
        j.observe(Some(&[w("a", 1, 0), w("b", 1, 0)]), at(0));
        let ev = j.observe(Some(&[w("b", 1, 0)]), at(2));
        assert_eq!(ev.len(), 1);
        assert_eq!((ev[0].job.worker.as_str(), ev[0].job.requests), ("a", 1));
        assert_eq!(j.live().len(), 1);
    }

    #[test]
    fn query_filters_by_state_and_since_and_validates_its_input() {
        let mut j = Journal::in_memory();
        j.observe(Some(&[w("a", 1, 0)]), at(0));
        j.observe(Some(&[w("a", 0, 1)]), at(10));
        j.observe(Some(&[w("a", 1, 1)]), at(20));
        let all = j.query(&Query::default());
        assert_eq!(
            all.iter()
                .map(|j| (j.id.as_str(), j.state.as_str()))
                .collect::<Vec<_>>(),
            vec![("j2", "live"), ("j1", "done")]
        );
        let q = |s: Option<&str>, since: Option<&str>| {
            Query::parse(s.map(Into::into), None, None, since.map(Into::into)).unwrap()
        };
        assert_eq!(j.query(&q(Some("live"), None)).len(), 1);
        assert_eq!(j.query(&q(Some("done"), None))[0].id, "j1");
        assert_eq!(j.query(&q(None, Some("2026-09-21T14:13:35Z")))[0].id, "j2");
        assert!(Query::parse(Some("running".into()), None, None, None).is_err());
        assert!(Query::parse(None, Some("bitcoin".into()), None, None).is_err());
        assert!(Query::parse(None, None, None, Some("yesterday".into())).is_err());
        let by_source = Query::parse(None, Some("peer".into()), None, None).unwrap();
        assert!(j.query(&by_source).is_empty(), "no job is attributed yet");
    }

    #[test]
    fn the_journal_keeps_finished_jobs_across_restarts_and_stays_bounded() {
        let d = crate::agent::files::tests::tmp("jobs");
        crate::agent::files::ensure_dir(&d).unwrap();
        let mut j = Journal::load(&d);
        for i in 0..(DONE_KEPT as i64 + 5) {
            j.observe(Some(&[w("a", 1, 0)]), at(i * 2));
            j.observe(Some(&[w("a", 0, 1)]), at(i * 2 + 1));
        }
        assert_eq!(j.done.len(), DONE_KEPT);
        let again = Journal::load(&d);
        assert_eq!(again.done.len(), DONE_KEPT);
        assert_eq!(again.next, DONE_KEPT as u64 + 6, "ids are never reused");
        assert!(again.live().is_empty());
    }
}