didbot_policy_records/

last_good.rs

//! The operator source's last-good-revision state, held across rebuilds.
//!
//! From the owner: *"the PDS keeps the current policy it knows about until
//! a new one replaces it. So you can see what WAS working vs. what won't
//! compile."* The three ways a bad new revision could be handled are not
//! symmetric -- dropping the policy widens what an agent may do, and
//! denying everything it covers turns a typo into an outage -- so
//! [`crate::merge::build`] keeps enforcing the last revision of a policy
//! that *did* compile, for exactly as long as its successor keeps failing.
//!
//! # What this is not
//!
//! Not a cache of compiled artifacts: [`LastGoodPolicies`] holds the last
//! [`ParsedPolicy`] that compiled cleanly, and [`crate::merge::build`]
//! recompiles it fresh on every rebuild via
//! [`crate::compile::resolve_predicate`] -- cheap, and exactly the
//! "idempotent and re-runnable" property `didbot_policy::Evaluator::compile`
//! already has to have for an out-of-process evaluator restarting with
//! nothing. Not a revision-ordering mechanism either: this is the layer
//! above whatever produced the current view, deciding what to enforce when
//! the newest observation does not compile.
//!
//! # The two states an operator must be able to tell apart
//!
//! - **Was working, new revision will not compile.** The last good
//!   revision is enforced; the new one exists and failed. An edit that did
//!   not land, not an outage -- reported as [`crate::merge::LastGoodFallback`].
//! - **Never compiled.** Nothing to fall back to -- this id has no entry
//!   here yet. Reported the ordinary, loud way,
//!   [`crate::compile::ScopedDenial`], because a first-publish typo denying
//!   its own coverage is a real gap the operator gets no protection from,
//!   and must see.

use std::collections::HashMap;
use std::sync::Mutex;

use didbot_policy::Revision;

use crate::record::ParsedPolicy;

/// One id's last successfully-compiled revision, held across rebuilds.
#[derive(Debug, Clone)]
struct Good {
    revision: Revision,
    policy: ParsedPolicy,
}

/// The operator source's last-good-revision state. Empty and legitimate at
/// startup -- nothing has compiled yet, which is the "never compiled" state
/// every id starts in, not an error.
///
/// Held by whoever repeatedly rebuilds the tree from a fresh view of the
/// operator's records, the same way that view itself is held -- long-lived,
/// across many
/// [`crate::merge::build`] calls, never reconstructed per rebuild, or there
/// would be nothing to fall back to.
#[derive(Default)]
pub struct LastGoodPolicies {
    good: Mutex<HashMap<String, Good>>,
}

impl LastGoodPolicies {
    /// No id has a last-good revision yet.
    #[must_use]
    pub fn new() -> Self {
        Self::default()
    }

    /// The last successfully-compiled [`ParsedPolicy`] for `id`, and the
    /// revision it was observed at, if this id has ever compiled.
    pub(crate) fn get(&self, id: &str) -> Option<(Revision, ParsedPolicy)> {
        self.good
            .lock()
            .expect("LastGoodPolicies mutex poisoned")
            .get(id)
            .map(|good| (good.revision, good.policy.clone()))
    }

    /// Record that `policy` (at `id`) compiled successfully at its own
    /// revision -- the new last-good, replacing whatever was stored before.
    pub(crate) fn record_success(&self, id: &str, policy: &ParsedPolicy) {
        self.good
            .lock()
            .expect("LastGoodPolicies mutex poisoned")
            .insert(
                id.to_string(),
                Good {
                    revision: policy.revision,
                    policy: policy.clone(),
                },
            );
    }

    /// Drop every id not present in `current` -- a record the current view
    /// no longer holds at all (deleted, or
    /// never re-observed after a source outage recovered onto a view that
    /// no longer names it) has nothing left to fall back *to*, and keeping
    /// it here would let a stale policy affect a future id that happens to
    /// reuse the same at-uri. Called once per rebuild, after every id in
    /// `current` has had a chance to update its own entry via
    /// [`record_success`](Self::record_success).
    pub(crate) fn prune(&self, current: &HashMap<String, ParsedPolicy>) {
        self.good
            .lock()
            .expect("LastGoodPolicies mutex poisoned")
            .retain(|id, _| current.contains_key(id));
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use didbot_policy::{ActionSet, Applicability, KindSet, Scope, Staleness};
    use serde_json::json;

    fn policy(revision: u64) -> ParsedPolicy {
        ParsedPolicy {
            applicability: Applicability::Write {
                kinds: KindSet::ALL,
                collections: Scope::Any,
                actions: ActionSet::ALL,
                path_prefixes: Scope::Any,
            },
            observes: Applicability::Write {
                kinds: KindSet::ALL,
                collections: Scope::Any,
                actions: ActionSet::ALL,
                path_prefixes: Scope::Any,
            },
            staleness: Staleness::Linearized,
            language: "regex".to_string(),
            predicate: json!({}),
            revision: Revision(revision),
            lookups: Vec::new(),
        }
    }

    #[test]
    fn nothing_is_stored_until_a_success_is_recorded() {
        let good = LastGoodPolicies::new();
        assert!(good.get("id-1").is_none());
    }

    #[test]
    fn a_recorded_success_is_retrievable_by_id() {
        let good = LastGoodPolicies::new();
        good.record_success("id-1", &policy(1));
        let (revision, stored) = good.get("id-1").expect("recorded");
        assert_eq!(revision, Revision(1));
        assert_eq!(stored.revision, Revision(1));
    }

    /// A later success replaces the earlier one -- this is the state a bad
    /// N+1 falls back past to reach the good N, and a good N+2 later
    /// replacing N is exactly the ordinary "policy got fixed" case.
    #[test]
    fn a_newer_success_replaces_the_prior_one() {
        let good = LastGoodPolicies::new();
        good.record_success("id-1", &policy(1));
        good.record_success("id-1", &policy(2));
        let (revision, _) = good.get("id-1").expect("recorded");
        assert_eq!(revision, Revision(2));
    }

    /// An id absent from a fresh `current` view is pruned, not left to
    /// linger for a future, unrelated record that happens to reuse the
    /// same at-uri.
    #[test]
    fn pruning_drops_ids_absent_from_the_current_view() {
        let good = LastGoodPolicies::new();
        good.record_success("id-1", &policy(1));
        good.record_success("id-2", &policy(1));

        let mut current = HashMap::new();
        current.insert("id-1".to_string(), policy(2));
        good.prune(&current);

        assert!(good.get("id-1").is_some());
        assert!(good.get("id-2").is_none());
    }
}