relay-knowledge 1.1.10

Graph-database-based knowledge graph project.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95

use serde::{Deserialize, Serialize};

/// Per-file staleness hint attached to retrieval hits at query time.
///
/// Encodes the freshness relationship between the indexed graph snapshot and
/// the live file state. Query-time freshness diagnostics can distinguish an
/// answer served from an older completed scope while a matching refresh task is
/// still pending from a scope that is simply stale.
///
/// New variants may be added in future releases; match exhaustively or use a
/// wildcard to remain forward-compatible.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case", tag = "state")]
#[non_exhaustive]
pub enum StalenessHint {
    Fresh,
    /// A matching index task is queued, running, or retrying for this query.
    PendingIndex {},
    /// Indexed snapshot is older than the latest file modification.
    Stale {},
}

impl StalenessHint {
    pub fn requires_source_verification(&self) -> bool {
        !matches!(self, StalenessHint::Fresh)
    }

    pub fn should_replace(&self, current: Option<&Self>) -> bool {
        current.is_none_or(|current| self.priority() > current.priority())
    }

    fn priority(&self) -> u8 {
        match self {
            StalenessHint::Fresh => 0,
            StalenessHint::Stale {} => 1,
            StalenessHint::PendingIndex {} => 2,
        }
    }
}

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

    #[test]
    fn fresh_serializes_with_tag() {
        let hint = StalenessHint::Fresh;
        let json = serde_json::to_string(&hint).unwrap();
        assert_eq!(json, "{\"state\":\"fresh\"}");
        let parsed: StalenessHint = serde_json::from_str(&json).unwrap();
        assert_eq!(parsed, StalenessHint::Fresh);
    }

    #[test]
    fn stale_round_trips() {
        let hint = StalenessHint::Stale {};
        let json = serde_json::to_string(&hint).unwrap();
        assert!(json.contains("\"state\":\"stale\""));
        let parsed: StalenessHint = serde_json::from_str(&json).unwrap();
        assert_eq!(parsed, StalenessHint::Stale {});
    }

    #[test]
    fn pending_index_round_trips() {
        let hint = StalenessHint::PendingIndex {};
        let json = serde_json::to_string(&hint).unwrap();
        assert_eq!(json, "{\"state\":\"pending_index\"}");
        let parsed: StalenessHint = serde_json::from_str(&json).unwrap();
        assert_eq!(parsed, StalenessHint::PendingIndex {});
    }

    #[test]
    fn pending_index_requires_source_verification_without_being_plain_stale() {
        let hint = StalenessHint::PendingIndex {};
        assert!(hint.requires_source_verification());
        assert_ne!(hint, StalenessHint::Stale {});
    }

    #[test]
    fn pending_index_replaces_plain_stale_on_merge() {
        let pending = StalenessHint::PendingIndex {};
        assert!(pending.should_replace(Some(&StalenessHint::Stale {})));
    }

    #[test]
    fn discriminants_are_distinct() {
        use std::mem::discriminant;
        let fresh = StalenessHint::Fresh;
        let pending = StalenessHint::PendingIndex {};
        let stale = StalenessHint::Stale {};
        assert_ne!(discriminant(&fresh), discriminant(&stale));
        assert_ne!(discriminant(&fresh), discriminant(&pending));
        assert_ne!(discriminant(&pending), discriminant(&stale));
    }
}