1use std::time::{Duration, Instant};
5
6use parking_lot::Mutex;
7
8use crate::{Capabilities, Capability, supervision::telemetry::PixAdmissionRejection};
9
10pub const DEFAULT_REFUSAL_REPLY_BURST: u32 = 32;
13
14pub const DEFAULT_REFUSAL_REPLY_REFILL_PERIOD: Duration = Duration::from_secs(1);
16
17pub const MIN_REFUSAL_REPLY_REFILL_PERIOD: Duration = Duration::from_millis(1);
19
20#[derive(Clone, Copy, Debug, PartialEq, Eq, smart_default::SmartDefault, serde::Serialize, serde::Deserialize)]
30#[serde(default, deny_unknown_fields)]
31pub struct RefusalReplyBudget {
32 #[default(DEFAULT_REFUSAL_REPLY_BURST)]
36 pub burst: u32,
37
38 #[default(DEFAULT_REFUSAL_REPLY_REFILL_PERIOD)]
43 #[serde(with = "humantime_serde")]
44 pub refill_period: Duration,
45}
46
47#[derive(Debug)]
48struct BucketState {
49 tokens: u32,
50 refilled_at: Instant,
52}
53
54#[derive(Debug)]
56pub(crate) struct RefusalReplyBucket {
57 budget: RefusalReplyBudget,
58 state: Mutex<BucketState>,
59}
60
61impl RefusalReplyBucket {
62 pub(crate) fn new(budget: RefusalReplyBudget) -> Self {
64 Self::new_at(budget, Instant::now())
65 }
66
67 fn new_at(mut budget: RefusalReplyBudget, now: Instant) -> Self {
68 budget.refill_period = budget.refill_period.max(MIN_REFUSAL_REPLY_REFILL_PERIOD);
69 Self {
70 budget,
71 state: Mutex::new(BucketState {
72 tokens: budget.burst,
73 refilled_at: now,
74 }),
75 }
76 }
77
78 pub(crate) fn try_take(&self) -> bool {
80 self.try_take_at(Instant::now())
81 }
82
83 fn try_take_at(&self, now: Instant) -> bool {
85 let mut state = self.state.lock();
86 self.refill(&mut state, now);
87
88 if state.tokens == 0 {
89 return false;
90 }
91 if state.tokens == self.budget.burst {
93 state.refilled_at = now;
94 }
95 state.tokens -= 1;
96 true
97 }
98
99 fn refill(&self, state: &mut BucketState, now: Instant) {
100 let period = self.budget.refill_period.as_nanos().max(1);
101 let elapsed = now.saturating_duration_since(state.refilled_at).as_nanos();
102 let periods = u32::try_from(elapsed / period).unwrap_or(u32::MAX);
103 if periods == 0 {
104 return;
105 }
106
107 state.tokens = state.tokens.saturating_add(periods).min(self.budget.burst);
108 if state.tokens == self.budget.burst {
109 state.refilled_at = now;
110 } else {
111 state.refilled_at = self
113 .budget
114 .refill_period
115 .checked_mul(periods)
116 .and_then(|advance| state.refilled_at.checked_add(advance))
117 .unwrap_or(now);
118 }
119 }
120}
121
122#[derive(Clone, Copy, Debug, PartialEq, Eq, strum::Display)]
126#[strum(serialize_all = "snake_case")]
127pub(crate) enum ExitControlKind {
128 RefusalDirectReturnPath,
130 RefusalNoPixSupport,
132 RefusalUnacceptableParams,
134 RefusalTargetPolicy,
136 RefusalLiveCycleCapacity,
138 RefusalNoSessionSlot,
140 RefusalBusy,
142 SurbReport,
144 PixFill,
146 SessionEstablished,
148 SsaRequest,
150 SsaRequestResend,
152 CommitmentRetransmissionRequest,
154 SessionError,
156}
157
158impl From<PixAdmissionRejection> for ExitControlKind {
159 fn from(rejection: PixAdmissionRejection) -> Self {
160 match rejection {
161 PixAdmissionRejection::NoPixSupport => Self::RefusalNoPixSupport,
162 PixAdmissionRejection::UnacceptableParams => Self::RefusalUnacceptableParams,
163 PixAdmissionRejection::TargetPolicy => Self::RefusalTargetPolicy,
164 PixAdmissionRejection::LiveCycleCapacity => Self::RefusalLiveCycleCapacity,
165 PixAdmissionRejection::NoSessionSlot => Self::RefusalNoSessionSlot,
166 PixAdmissionRejection::Busy => Self::RefusalBusy,
167 PixAdmissionRejection::DirectReturnPath => Self::RefusalDirectReturnPath,
168 }
169 }
170}
171
172#[derive(Clone, Copy, Debug, PartialEq, Eq, strum::Display)]
174#[strum(serialize_all = "snake_case")]
175pub(crate) enum ExitSessionKind {
176 Pix,
178 Plain,
180}
181
182impl ExitSessionKind {
183 pub(crate) fn of(capabilities: Capabilities) -> Self {
185 if capabilities.contains(Capability::UsePIX) {
186 Self::Pix
187 } else {
188 Self::Plain
189 }
190 }
191}
192
193#[derive(Clone, Copy, Debug, PartialEq, Eq, strum::Display)]
195#[strum(serialize_all = "snake_case")]
196pub(crate) enum ExitControlOutcome {
197 Sent,
199 DroppedBudget,
201 SendFailed,
203}
204
205pub(crate) fn record_exit_control(kind: ExitControlKind, session: ExitSessionKind, outcome: ExitControlOutcome) {
207 #[cfg(feature = "telemetry")]
208 crate::telemetry::exit_control::record(kind, session, outcome);
209 #[cfg(test)]
210 crate::supervision::telemetry::probe::add(&format!("exit_control/{kind}/{session}/{outcome}"), 1);
211 #[cfg(not(any(feature = "telemetry", test)))]
212 let _ = (kind, session, outcome);
213}
214
215#[cfg(test)]
216mod tests {
217 use super::*;
218
219 const SECOND: Duration = Duration::from_secs(1);
220
221 fn bucket(burst: u32, refill_period: Duration, now: Instant) -> RefusalReplyBucket {
222 RefusalReplyBucket::new_at(RefusalReplyBudget { burst, refill_period }, now)
223 }
224
225 #[test]
226 fn a_fresh_bucket_answers_its_burst_and_then_nothing() {
227 let t0 = Instant::now();
228 let bucket = bucket(3, SECOND, t0);
229
230 assert!((0..3).all(|_| bucket.try_take_at(t0)));
231 assert!(!bucket.try_take_at(t0));
232 assert!(!bucket.try_take_at(t0 + SECOND / 2));
233 }
234
235 #[test]
236 fn an_empty_bucket_earns_one_reply_per_refill_period() {
237 let t0 = Instant::now();
238 let bucket = bucket(2, SECOND, t0);
239 assert!(bucket.try_take_at(t0));
240 assert!(bucket.try_take_at(t0));
241
242 assert!(bucket.try_take_at(t0 + SECOND * 3 / 2));
244 assert!(!bucket.try_take_at(t0 + SECOND * 3 / 2));
245
246 assert!(!bucket.try_take_at(t0 + SECOND * 19 / 10));
248 assert!(bucket.try_take_at(t0 + SECOND * 2));
249 assert!(!bucket.try_take_at(t0 + SECOND * 2));
250 }
251
252 #[test]
253 fn a_bucket_never_banks_more_than_its_burst() {
254 let t0 = Instant::now();
255 let bucket = bucket(3, SECOND, t0);
256
257 let later = t0 + SECOND * 1000;
258 assert!((0..3).all(|_| bucket.try_take_at(later)));
259 assert!(!bucket.try_take_at(later));
260 }
261
262 #[test]
263 fn a_zero_burst_never_answers() {
264 let t0 = Instant::now();
265 let bucket = bucket(0, SECOND, t0);
266
267 assert!(!bucket.try_take_at(t0));
268 assert!(!bucket.try_take_at(t0 + SECOND * 1000));
269 }
270
271 #[test]
272 fn an_instant_before_the_last_refill_adds_nothing() {
273 let t0 = Instant::now() + SECOND * 10;
274 let bucket = bucket(1, SECOND, t0);
275 assert!(bucket.try_take_at(t0));
276
277 assert!(!bucket.try_take_at(t0 - SECOND * 5));
278 assert!(bucket.try_take_at(t0 + SECOND));
279 }
280
281 #[test]
282 fn a_refill_period_below_the_minimum_is_raised_to_it() {
283 let t0 = Instant::now();
284 let bucket = bucket(1, Duration::ZERO, t0);
285 assert!(bucket.try_take_at(t0));
286
287 assert!(!bucket.try_take_at(t0));
288 assert!(bucket.try_take_at(t0 + MIN_REFUSAL_REPLY_REFILL_PERIOD));
289 }
290
291 #[test]
292 fn the_refusal_reply_budget_defaults_to_a_burst_of_32_and_one_reply_a_second() {
293 let budget = RefusalReplyBudget::default();
294
295 assert_eq!(32, budget.burst);
296 assert_eq!(Duration::from_secs(1), budget.refill_period);
297 }
298
299 #[test]
300 fn every_admission_rejection_maps_to_a_distinct_refusal_kind() {
301 let rejections = [
302 PixAdmissionRejection::NoPixSupport,
303 PixAdmissionRejection::UnacceptableParams,
304 PixAdmissionRejection::TargetPolicy,
305 PixAdmissionRejection::LiveCycleCapacity,
306 PixAdmissionRejection::NoSessionSlot,
307 PixAdmissionRejection::Busy,
308 PixAdmissionRejection::DirectReturnPath,
309 ];
310
311 let labels: std::collections::BTreeSet<String> = rejections
312 .into_iter()
313 .map(|rejection| ExitControlKind::from(rejection).to_string())
314 .collect();
315
316 assert_eq!(rejections.len(), labels.len());
317 assert!(labels.iter().all(|label| label.starts_with("refusal_")));
318 }
319}