Skip to main content

khive_db/pool/
note_search_routes.rs

1//! Pool-lifetime accounting for the runtime's note-search vector route.
2
3use std::sync::atomic::{AtomicU64, Ordering};
4
5use super::ConnectionPool;
6
7/// Why note search selected its exact vector fallback.
8#[derive(Debug, Clone, Copy, PartialEq, Eq)]
9pub enum NoteSearchFallbackCause {
10    /// No default embedding model is configured at route selection.
11    NoModel,
12    /// No installed provider serves the actual opened backend.
13    NoProvider,
14    /// The provider has no eligible graph for this model and consumer.
15    NoEligibleGraph,
16}
17
18/// Note-search routes selected for this opened pool, shared by all its handles.
19///
20/// Values reset only when the pool is reconstructed. A fallback counts the
21/// selected route even if the exact search then fails. Embedding and provider
22/// errors before a route is selected do not count. Concurrent reads are relaxed
23/// snapshots; the fallback total is the saturating sum of the captured causes.
24#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, serde::Serialize)]
25pub struct NoteSearchRouteSnapshot {
26    /// ANN provider successes, including empty candidate results.
27    pub ann_route_total: u64,
28    /// Exact routes selected, the saturating sum of the captured causes.
29    pub fallback_route_total: u64,
30    /// Exact routes selected without a default embedding model.
31    pub fallback_no_model_total: u64,
32    /// Exact routes selected without a provider for this backend.
33    pub fallback_no_provider_total: u64,
34    /// Exact routes selected after the provider returned no eligible graph.
35    pub fallback_no_eligible_graph_total: u64,
36}
37
38#[derive(Default)]
39pub(super) struct NoteSearchRouteCounters {
40    ann: AtomicU64,
41    no_model: AtomicU64,
42    no_provider: AtomicU64,
43    no_eligible_graph: AtomicU64,
44}
45
46fn increment(counter: &AtomicU64) {
47    let _ = counter.fetch_update(Ordering::Relaxed, Ordering::Relaxed, |value| {
48        Some(value.saturating_add(1))
49    });
50}
51
52impl NoteSearchRouteCounters {
53    fn record_ann(&self) {
54        increment(&self.ann);
55    }
56
57    fn record_fallback(&self, cause: NoteSearchFallbackCause) {
58        increment(match cause {
59            NoteSearchFallbackCause::NoModel => &self.no_model,
60            NoteSearchFallbackCause::NoProvider => &self.no_provider,
61            NoteSearchFallbackCause::NoEligibleGraph => &self.no_eligible_graph,
62        });
63    }
64
65    fn snapshot(&self) -> NoteSearchRouteSnapshot {
66        let no_model = self.no_model.load(Ordering::Relaxed);
67        let no_provider = self.no_provider.load(Ordering::Relaxed);
68        let no_eligible_graph = self.no_eligible_graph.load(Ordering::Relaxed);
69        NoteSearchRouteSnapshot {
70            ann_route_total: self.ann.load(Ordering::Relaxed),
71            fallback_route_total: no_model
72                .saturating_add(no_provider)
73                .saturating_add(no_eligible_graph),
74            fallback_no_model_total: no_model,
75            fallback_no_provider_total: no_provider,
76            fallback_no_eligible_graph_total: no_eligible_graph,
77        }
78    }
79}
80
81impl ConnectionPool {
82    /// Record an ANN route on the actual opened backend serving note search.
83    pub fn record_note_search_ann_route(&self) {
84        self.note_search_routes.record_ann();
85    }
86
87    /// Record one exact fallback route and its cause on this opened backend.
88    pub fn record_note_search_fallback_route(&self, cause: NoteSearchFallbackCause) {
89        self.note_search_routes.record_fallback(cause);
90    }
91
92    /// Snapshot this pool's note-search route counters without resetting them.
93    pub fn note_search_route_snapshot(&self) -> NoteSearchRouteSnapshot {
94        self.note_search_routes.snapshot()
95    }
96}
97
98#[cfg(test)]
99mod tests {
100    use super::*;
101
102    #[test]
103    fn route_snapshot_counts_each_fallback_cause() {
104        let counters = NoteSearchRouteCounters::default();
105        counters.record_ann();
106        counters.record_ann();
107        counters.record_fallback(NoteSearchFallbackCause::NoModel);
108        for _ in 0..2 {
109            counters.record_fallback(NoteSearchFallbackCause::NoProvider);
110        }
111        for _ in 0..3 {
112            counters.record_fallback(NoteSearchFallbackCause::NoEligibleGraph);
113        }
114        let expected = NoteSearchRouteSnapshot {
115            ann_route_total: 2,
116            fallback_route_total: 6,
117            fallback_no_model_total: 1,
118            fallback_no_provider_total: 2,
119            fallback_no_eligible_graph_total: 3,
120        };
121        assert_eq!(counters.snapshot(), expected);
122        assert_eq!(
123            counters.snapshot(),
124            expected,
125            "snapshots must not reset counts"
126        );
127    }
128
129    #[test]
130    fn route_counters_and_fallback_sum_saturate() {
131        let counters = NoteSearchRouteCounters::default();
132        counters.ann.store(u64::MAX, Ordering::Relaxed);
133        counters.no_model.store(u64::MAX, Ordering::Relaxed);
134        counters.record_ann();
135        counters.record_fallback(NoteSearchFallbackCause::NoModel);
136        counters.record_fallback(NoteSearchFallbackCause::NoProvider);
137        counters.record_fallback(NoteSearchFallbackCause::NoEligibleGraph);
138        assert_eq!(
139            counters.snapshot(),
140            NoteSearchRouteSnapshot {
141                ann_route_total: u64::MAX,
142                fallback_route_total: u64::MAX,
143                fallback_no_model_total: u64::MAX,
144                fallback_no_provider_total: 1,
145                fallback_no_eligible_graph_total: 1,
146            }
147        );
148    }
149}