scepter 0.1.5

Composable primitives for planet-scale time-series routing, indexing, and aggregation.
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
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142

/// Type of degradation observed while executing a distributed query.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum IssueKind {
    /// A zone missed its soft deadline and was skipped.
    PrunedZone,
    /// A child timed out.
    TimedOut,
    /// Configuration was served from a stale cache.
    StaleConfig,
    /// No usable replica was found for a requested range.
    MissingReplica,
    /// A child returned incomplete data.
    IncompleteData,
}

/// One child-level query health issue.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ChildIssue<ChildId> {
    /// Affected child, such as a zone or leaf ID.
    pub child: ChildId,
    /// Issue kind.
    pub kind: IssueKind,
    /// Human-readable detail suitable for logs or user-facing diagnostics.
    pub detail: String,
}

impl<ChildId> ChildIssue<ChildId> {
    /// Creates a child issue.
    pub fn new(child: ChildId, kind: IssueKind, detail: impl Into<String>) -> Self {
        Self {
            child,
            kind,
            detail: detail.into(),
        }
    }
}

/// Health metadata for a distributed query result.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct QueryHealth<ChildId> {
    expected_children: usize,
    completed_children: usize,
    issues: Vec<ChildIssue<ChildId>>,
}

impl<ChildId> Default for QueryHealth<ChildId> {
    fn default() -> Self {
        Self {
            expected_children: 0,
            completed_children: 0,
            issues: Vec::new(),
        }
    }
}

impl<ChildId> QueryHealth<ChildId> {
    /// Creates empty health metadata.
    pub fn new() -> Self {
        Self::default()
    }

    /// Creates health metadata with an expected child count.
    pub fn with_expected_children(expected_children: usize) -> Self {
        Self {
            expected_children,
            completed_children: 0,
            issues: Vec::new(),
        }
    }

    /// Returns the expected child count.
    pub fn expected_children(&self) -> usize {
        self.expected_children
    }

    /// Returns the completed child count.
    pub fn completed_children(&self) -> usize {
        self.completed_children
    }

    /// Returns all recorded issues.
    pub fn issues(&self) -> &[ChildIssue<ChildId>] {
        &self.issues
    }

    /// Records a completed child response.
    pub fn record_completed(&mut self) {
        self.completed_children += 1;
    }

    /// Records an issue.
    pub fn record_issue(&mut self, issue: ChildIssue<ChildId>) {
        self.issues.push(issue);
    }

    /// Records an issue by parts.
    pub fn push_issue(&mut self, child: ChildId, kind: IssueKind, detail: impl Into<String>) {
        self.record_issue(ChildIssue::new(child, kind, detail));
    }

    /// Returns true if any issue has been recorded or some expected children
    /// did not complete.
    pub fn is_partial(&self) -> bool {
        !self.issues.is_empty() || self.completed_children < self.expected_children
    }

    /// Returns the completed-child ratio in `0.0..=1.0`.
    pub fn completeness(&self) -> f64 {
        if self.expected_children == 0 {
            return 1.0;
        }
        (self.completed_children as f64 / self.expected_children as f64).min(1.0)
    }
}

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

    #[test]
    fn query_health_tracks_partial_results() {
        let mut health = QueryHealth::with_expected_children(3);
        health.record_completed();
        health.push_issue("zone-a", IssueKind::PrunedZone, "soft deadline elapsed");

        assert!(health.is_partial());
        assert_eq!(health.expected_children(), 3);
        assert_eq!(health.completed_children(), 1);
        assert_eq!(health.completeness(), 1.0 / 3.0);
        assert_eq!(health.issues()[0].kind, IssueKind::PrunedZone);
    }

    #[test]
    fn query_health_is_complete_when_all_children_finish_without_issues() {
        let mut health = QueryHealth::<&str>::with_expected_children(2);
        health.record_completed();
        health.record_completed();

        assert!(!health.is_partial());
        assert_eq!(health.completeness(), 1.0);
    }
}