Skip to main content

hopr_transport_session/
exit_control.rs

1//! What the Exit pays for on a peer's behalf, and the bounds put on it: the refusal reply budget and
2//! the labels of `hopr_exit_control_packets_total`.
3
4use std::time::{Duration, Instant};
5
6use parking_lot::Mutex;
7
8use crate::{Capabilities, Capability, supervision::telemetry::PixAdmissionRejection};
9
10/// The default [`RefusalReplyBudget::burst`]: the most replies a flood can make the Exit pay for back
11/// to back, while a briefly busy Exit still answers the Entries that arrive together.
12pub const DEFAULT_REFUSAL_REPLY_BURST: u32 = 32;
13
14/// The default [`RefusalReplyBudget::refill_period`].
15pub const DEFAULT_REFUSAL_REPLY_REFILL_PERIOD: Duration = Duration::from_secs(1);
16
17/// The shortest [`RefusalReplyBudget::refill_period`] accepted; a zero period would be no budget.
18pub const MIN_REFUSAL_REPLY_REFILL_PERIOD: Duration = Duration::from_millis(1);
19
20/// How many refusal replies an Exit sends, shared by every reason it refuses a `StartSession`.
21///
22/// A reply travels over a SURB the requester chose, and a multi-hop one costs the Exit a ticket while
23/// the request reaches it for free, so unbounded replies let a flood drain the Exit's funds. One
24/// budget covers all reasons because a peer picks whichever is cheapest to provoke.
25///
26/// A token bucket: up to [`burst`](Self::burst) replies at once, then one every
27/// [`refill_period`](Self::refill_period). A refusal that finds it empty gets no reply and the
28/// requester times out.
29#[derive(Clone, Copy, Debug, PartialEq, Eq, smart_default::SmartDefault, serde::Serialize, serde::Deserialize)]
30#[serde(default, deny_unknown_fields)]
31pub struct RefusalReplyBudget {
32    /// The bucket's capacity. Zero never answers a refusal.
33    ///
34    /// Default is [`DEFAULT_REFUSAL_REPLY_BURST`].
35    #[default(DEFAULT_REFUSAL_REPLY_BURST)]
36    pub burst: u32,
37
38    /// How long it takes to earn one more reply once the burst is spent. Floored at
39    /// [`MIN_REFUSAL_REPLY_REFILL_PERIOD`] by the manager.
40    ///
41    /// Default is [`DEFAULT_REFUSAL_REPLY_REFILL_PERIOD`].
42    #[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    /// The instant the tokens were last topped up to, which is the start of the period now running.
51    refilled_at: Instant,
52}
53
54/// A token bucket over a [`RefusalReplyBudget`], shared by every clone of the manager.
55#[derive(Debug)]
56pub(crate) struct RefusalReplyBucket {
57    budget: RefusalReplyBudget,
58    state: Mutex<BucketState>,
59}
60
61impl RefusalReplyBucket {
62    /// Creates a bucket that starts full, raising a too-short refill period to the minimum.
63    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    /// Takes one reply from the bucket, returning whether there was one.
79    pub(crate) fn try_take(&self) -> bool {
80        self.try_take_at(Instant::now())
81    }
82
83    /// [`try_take`](Self::try_take) at a given instant, for tests without sleeping.
84    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        // A full bucket has no partial period to keep.
92        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            // Advance by whole periods only, keeping partial progress so the long-run rate is exact.
112            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/// What a packet the Exit sent on a peer's behalf was for, as `hopr_exit_control_packets_total`
123/// labels it. Closed, so no call site can invent a label value. `Refusal*` kinds answer a declined
124/// `StartSession`; the rest are sent for admitted Sessions.
125#[derive(Clone, Copy, Debug, PartialEq, Eq, strum::Display)]
126#[strum(serialize_all = "snake_case")]
127pub(crate) enum ExitControlKind {
128    /// Refused: PIX offered over a direct (0-hop) return path.
129    RefusalDirectReturnPath,
130    /// Refused: no PIX support installed.
131    RefusalNoPixSupport,
132    /// Refused: unacceptable PIX parameters.
133    RefusalUnacceptableParams,
134    /// Refused: the session server did not admit the target.
135    RefusalTargetPolicy,
136    /// Refused: the live-cycle budget cannot cover the Session.
137    RefusalLiveCycleCapacity,
138    /// Refused: no Session slot.
139    RefusalNoSessionSlot,
140    /// Refused: the node could not decide right now.
141    RefusalBusy,
142    /// The SURB-level report of how many SURBs the Exit holds. Backs off on idle Sessions.
143    SurbReport,
144    /// A PIX fill packet, sent above the report rate.
145    PixFill,
146    /// The `SessionEstablished` answering an admitted `StartSession`.
147    SessionEstablished,
148    /// The request for the Entry's SSA commitments.
149    SsaRequest,
150    /// The SSA request, re-sent for want of an answer.
151    SsaRequestResend,
152    /// A request for commitment parts that never arrived.
153    CommitmentRetransmissionRequest,
154    /// A `SessionError` for an established Session, over its return path.
155    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/// Whether the Session a packet belongs to offers PIX, as `hopr_exit_control_packets_total` labels it.
173#[derive(Clone, Copy, Debug, PartialEq, Eq, strum::Display)]
174#[strum(serialize_all = "snake_case")]
175pub(crate) enum ExitSessionKind {
176    /// Offers PIX.
177    Pix,
178    /// Does not.
179    Plain,
180}
181
182impl ExitSessionKind {
183    /// The kind of a Session with these capabilities.
184    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/// What became of a packet, as `hopr_exit_control_packets_total` labels it.
194#[derive(Clone, Copy, Debug, PartialEq, Eq, strum::Display)]
195#[strum(serialize_all = "snake_case")]
196pub(crate) enum ExitControlOutcome {
197    /// Handed to the transport.
198    Sent,
199    /// Not sent: the budget was spent.
200    DroppedBudget,
201    /// The transport refused it or timed out.
202    SendFailed,
203}
204
205/// Counts one packet the Exit sent, or declined to send, on a peer's behalf.
206pub(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        // 1.5 periods in: one earned, half a period kept.
243        assert!(bucket.try_take_at(t0 + SECOND * 3 / 2));
244        assert!(!bucket.try_take_at(t0 + SECOND * 3 / 2));
245
246        // The kept half completes at 2 s.
247        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}