diff --git a/oxa/oxa-work/src/events.rs b/oxa/oxa-work/src/events.rs index 8d480a0d..c5ce9496 100644 --- a/oxa/oxa-work/src/events.rs +++ b/oxa/oxa-work/src/events.rs @@ -8,6 +8,9 @@ use serde::{Deserialize, Serialize}; use serde_json::Value; use std::path::Path; +mod digest; +pub use digest::{Digest, DigestChanges, DigestGap}; + const CURRENT: &str = "events.jsonl"; const PREVIOUS: &str = "events.previous.jsonl"; const STATE: &str = "facts.json"; @@ -300,11 +303,14 @@ impl Facts { self.recover().map(|(_, snapshot, _)| snapshot) } pub fn events_after(&self, after: u64, limit: usize) -> Result { + self.read_window(after, limit).map(|(_, page)| page) + } + fn read_window(&self, after: u64, limit: usize) -> Result<(Snapshot, EventPage)> { if !(1..=64).contains(&limit) { return Err("event page limit must be between 1 and 64".into()); } let _lock = self.root.lock(LOCK)?; - let (state, _, journal) = self.recover()?; + let (state, snapshot, journal) = self.recover()?; if after > state.last_seq { return Err("event cursor is ahead of the journal".into()); } @@ -343,7 +349,7 @@ impl Facts { page.events.push(event); } page.to_json().map_err(|error| error.to_string())?; - Ok(page) + Ok((snapshot, page)) } fn journal(&self, pending: bool) -> Result { // The only allowed missing current file is an interrupted, durably reserved rotation. diff --git a/oxa/oxa-work/src/events/digest.rs b/oxa/oxa-work/src/events/digest.rs new file mode 100644 index 00000000..d30f0247 --- /dev/null +++ b/oxa/oxa-work/src/events/digest.rs @@ -0,0 +1,94 @@ +//! A bounded, deterministic digest of facts observed since an owner's cursor. +use super::{Facts, Result}; +use oxa_proto::work::{Blocked, Fact, Incident, IncidentKind, Landed, Snapshot, Subject}; + +#[derive(Debug, PartialEq, Eq)] +pub enum Digest { + Quiet { through: u64 }, + Changes(DigestChanges), + SnapshotOnly { snapshot: Snapshot, reason: DigestGap }, +} + +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +pub enum DigestGap { + Retention, + PageLimit, +} + +#[derive(Debug, PartialEq, Eq)] +pub struct DigestChanges { + pub after: u64, + pub through: u64, + pub merged: Vec, + pub blocked: Vec, + pub cleared: Vec, + /// These events establish an observed stall, not that a worker is still stalled. + pub observed_stalls: Vec, + pub asks_waiting: usize, +} + +impl Facts { + /// Read one coherent bounded window. Callers can show the fresh snapshot when + /// the complete interval is unavailable, without representing it as a delta. + pub fn digest_since(&self, after: u64) -> Result { + let (snapshot, page) = self.read_window(after, 64)?; + if page.gap || page.next != snapshot.as_of_seq { + return Ok(Digest::SnapshotOnly { + reason: if page.gap { + DigestGap::Retention + } else { + DigestGap::PageLimit + }, + snapshot, + }); + } + let mut changes = DigestChanges { + after, + through: page.next, + merged: Vec::new(), + blocked: Vec::new(), + cleared: Vec::new(), + observed_stalls: Vec::new(), + asks_waiting: snapshot.asks.len(), + }; + let mut asks_changed = false; + for event in page.events { + match event.fact { + Fact::PrMerged(landed) => { + changes.merged.retain(|prior| prior.pr.number != landed.pr.number); + changes.merged.push(landed); + } + Fact::Blocked(block) => { + changes.cleared.retain(|subject| *subject != block.subject); + changes.blocked.retain(|prior| prior.subject != block.subject); + changes.blocked.push(block); + } + Fact::Unblocked(subject) => { + changes.blocked.retain(|prior| prior.subject != subject); + changes.cleared.retain(|prior| *prior != subject); + changes.cleared.push(subject); + } + Fact::AskOpened(_) | Fact::AskClosed(_) => asks_changed = true, + Fact::StandingChanged(standing) => { + asks_changed |= standing.ask_opened.is_some() || standing.ask_closed.is_some(); + } + Fact::Incident(incident) if incident.kind == IncidentKind::WorkerStalled => { + changes + .observed_stalls + .retain(|prior| prior.subject != incident.subject); + changes.observed_stalls.push(incident); + } + _ => {} + } + } + if changes.merged.is_empty() + && changes.blocked.is_empty() + && changes.cleared.is_empty() + && changes.observed_stalls.is_empty() + && !asks_changed + { + return Ok(Digest::Quiet { through: page.next }); + } + Ok(Digest::Changes(changes)) + } +} diff --git a/oxa/oxa-work/src/events/tests.rs b/oxa/oxa-work/src/events/tests.rs index 6101e27a..3119b52b 100644 --- a/oxa/oxa-work/src/events/tests.rs +++ b/oxa/oxa-work/src/events/tests.rs @@ -818,3 +818,80 @@ fn artifacts_are_private_and_source_capacity_does_not_consume_a_sequence() { assert!(facts.append(checkpoint("too-many", 1), 0, mechanical()).is_err()); assert_eq!(facts.situation().unwrap().as_of_seq, MAX_SOURCES as u64); } + +#[test] +fn digest_uses_durable_changes_and_the_current_ask_count() { + let fixture = Fixture::new(); + let facts = fixture.facts(); + let pr = PullRequest { + number: 3, + head: "a".repeat(40), + }; + let subject = Subject::PullRequest(pr.number); + let merged = Landed { + pr, + merge_commit: "b".repeat(40), + merged_at_ms: 4, + }; + let observations = [ + mechanical(), + Fact::Blocked(Blocked { + subject: subject.clone(), + code: "waiting".into(), + ask_id: None, + }), + Fact::Unblocked(subject.clone()), + Fact::PrMerged(merged.clone()), + Fact::AskOpened(Ask { + id: "fixture-ask".into(), + subject: Subject::Repository, + question: "Choose one option".into(), + }), + ]; + for (index, fact) in observations.into_iter().enumerate() { + let revision = index as u64 + 1; + facts + .append(checkpoint("digest", revision), revision, fact) + .unwrap(); + } + let reopened = Facts::open(&fixture.root()).unwrap(); + let Digest::Changes(changes) = reopened.digest_since(1).unwrap() else { + panic!("complete retained interval must produce a digest"); + }; + assert_eq!(changes.after, 1); + assert_eq!(changes.through, 5); + assert_eq!(changes.merged, [merged]); + assert!(changes.blocked.is_empty()); + assert_eq!(changes.cleared, [subject]); + assert_eq!(changes.asks_waiting, 1); + facts.append(checkpoint("digest", 6), 6, mechanical()).unwrap(); + assert_eq!(reopened.digest_since(5).unwrap(), Digest::Quiet { through: 6 }); +} + +#[test] +fn digest_reports_a_fresh_snapshot_for_incomplete_intervals() { + let fixture = Fixture::new(); + let mut facts = fixture.facts(); + for revision in 1..=65 { + facts + .append(checkpoint("digest", revision), revision, mechanical()) + .unwrap(); + } + assert!(matches!( + facts.digest_since(0).unwrap(), + Digest::SnapshotOnly { snapshot, reason: DigestGap::PageLimit } if snapshot.as_of_seq == 65 + )); + + let fixture = Fixture::new(); + facts = fixture.facts(); + facts.journal_bytes = 512; + for revision in 1..=20 { + facts + .append(checkpoint("digest", revision), revision, mechanical()) + .unwrap(); + } + assert!(matches!( + facts.digest_since(0).unwrap(), + Digest::SnapshotOnly { snapshot, reason: DigestGap::Retention } if snapshot.as_of_seq == 20 + )); +}