1use std::collections::HashMap;
16use std::sync::Mutex;
17
18fn day_of(ts: jiff::Timestamp) -> i64 {
20 ts.as_second().div_euclid(86_400)
21}
22
23#[derive(Debug, Clone, Copy, PartialEq, Eq)]
25pub enum Skip {
26 NotSampled,
28 BudgetExhausted,
30}
31
32#[derive(Debug, Default)]
34pub struct ShadowLedger {
35 inner: Mutex<HashMap<(String, usize), (i64, f64)>>, }
37
38impl ShadowLedger {
39 #[must_use]
41 pub fn new() -> Self {
42 Self::default()
43 }
44
45 pub fn may_spend(
53 &self,
54 tenant: &str,
55 route_ix: usize,
56 max_usd_per_day: f64,
57 now: jiff::Timestamp,
58 ) -> bool {
59 if max_usd_per_day <= 0.0 {
60 return false;
61 }
62 let today = day_of(now);
63 let mut g = match self.inner.lock() {
64 Ok(g) => g,
65 Err(_) => return false,
68 };
69 let e = g
70 .entry((tenant.to_owned(), route_ix))
71 .or_insert((today, 0.0));
72 if e.0 != today {
73 *e = (today, 0.0); }
75 e.1 < max_usd_per_day
76 }
77
78 pub fn debit(&self, tenant: &str, route_ix: usize, usd: f64, now: jiff::Timestamp) {
80 if !usd.is_finite() || usd <= 0.0 {
81 return;
82 }
83 let today = day_of(now);
84 if let Ok(mut g) = self.inner.lock() {
85 let e = g
86 .entry((tenant.to_owned(), route_ix))
87 .or_insert((today, 0.0));
88 if e.0 != today {
89 *e = (today, 0.0);
90 }
91 e.1 += usd;
92 }
93 }
94
95 pub fn seed(
99 &self,
100 tenant: &str,
101 route_ix: usize,
102 usd: f64,
103 at: jiff::Timestamp,
104 now: jiff::Timestamp,
105 ) {
106 if day_of(at) == day_of(now) {
107 self.debit(tenant, route_ix, usd, now);
108 }
109 }
110
111 #[must_use]
113 pub fn spent_today(&self, tenant: &str, route_ix: usize, now: jiff::Timestamp) -> f64 {
114 let today = day_of(now);
115 self.inner
116 .lock()
117 .ok()
118 .and_then(|g| g.get(&(tenant.to_owned(), route_ix)).copied())
119 .filter(|(d, _)| *d == today)
120 .map_or(0.0, |(_, spent)| spent)
121 }
122}
123
124#[cfg(test)]
125mod tests {
126 use super::*;
127
128 #[test]
130 fn seed_counts_only_spend_from_the_same_utc_day() {
131 let now: jiff::Timestamp = "2026-10-31T12:00:00Z".parse().unwrap();
132 let earlier_today: jiff::Timestamp = "2026-10-31T00:00:01Z".parse().unwrap();
133 let yesterday: jiff::Timestamp = "2026-10-30T23:59:59Z".parse().unwrap();
134 let l = ShadowLedger::new();
135 l.seed("t", 0, 0.75, yesterday, now);
136 l.seed("t", 0, 0.60, earlier_today, now);
137 l.seed("t", 0, 0.50, earlier_today, now);
138 assert!((l.spent_today("t", 0, now) - 1.10).abs() < 1e-12);
139 assert!(
140 !l.may_spend("t", 0, 1.0, now),
141 "seeded spend counts toward the cap"
142 );
143 assert!(l.may_spend("other", 0, 1.0, now), "per tenant");
144 }
145
146 fn ts(secs: i64) -> jiff::Timestamp {
147 jiff::Timestamp::from_second(secs).unwrap()
148 }
149
150 #[test]
151 fn spending_stops_at_the_ceiling() {
152 let l = ShadowLedger::new();
153 let now = ts(1_000_000);
154 assert!(
155 l.may_spend("t", 0, 1.00, now),
156 "fresh budget must allow the first call"
157 );
158 l.debit("t", 0, 0.60, now);
159 assert!(
160 l.may_spend("t", 0, 1.00, now),
161 "0.60 of 1.00 spent — still under"
162 );
163 l.debit("t", 0, 0.50, now);
164 assert!(
165 !l.may_spend("t", 0, 1.00, now),
166 "1.10 of 1.00 spent — must refuse, or the ceiling is decoration"
167 );
168 }
169
170 #[test]
173 fn budget_resets_on_a_new_utc_day() {
174 let l = ShadowLedger::new();
175 let day1 = ts(86_400 * 100);
176 l.debit("t", 0, 5.0, day1);
177 assert!(!l.may_spend("t", 0, 1.0, day1));
178 let day2 = ts(86_400 * 101);
179 assert!(
180 l.may_spend("t", 0, 1.0, day2),
181 "new UTC day must restore the budget"
182 );
183 assert!((l.spent_today("t", 0, day2) - 0.0).abs() < f64::EPSILON);
184 }
185
186 #[test]
188 fn budgets_are_isolated_per_tenant_and_route() {
189 let l = ShadowLedger::new();
190 let now = ts(1_000_000);
191 l.debit("noisy", 0, 99.0, now);
192 assert!(!l.may_spend("noisy", 0, 1.0, now));
193 assert!(
194 l.may_spend("quiet", 0, 1.0, now),
195 "another tenant's budget was consumed"
196 );
197 assert!(
198 l.may_spend("noisy", 1, 1.0, now),
199 "another route's budget was consumed"
200 );
201 }
202
203 #[test]
206 fn non_positive_ceiling_never_spends() {
207 let l = ShadowLedger::new();
208 let now = ts(1_000_000);
209 assert!(!l.may_spend("t", 0, 0.0, now));
210 assert!(!l.may_spend("t", 0, -5.0, now));
211 }
212
213 #[test]
214 fn nonsense_debits_are_ignored() {
215 let l = ShadowLedger::new();
216 let now = ts(1_000_000);
217 for bad in [f64::NAN, f64::INFINITY, -1.0, 0.0] {
218 l.debit("t", 0, bad, now);
219 }
220 assert!((l.spent_today("t", 0, now) - 0.0).abs() < f64::EPSILON);
221 assert!(l.may_spend("t", 0, 1.0, now));
222 }
223}