Skip to main content

hopr_transport_session/balancer/
controller.rs

1use std::{
2    collections::VecDeque,
3    sync::{
4        Arc,
5        atomic::{AtomicBool, AtomicU8, AtomicU64},
6    },
7    time::{Duration, Instant},
8};
9
10use futures::{StreamExt, pin_mut};
11use hopr_crypto_packet::prelude::{PacketSignal, PacketSignals};
12use hopr_utils::runtime::AbortHandle;
13use tracing::{Instrument, instrument};
14
15use super::{
16    AtomicSurbFlowEstimator, BalancerControllerBounds, MIN_BALANCER_SAMPLING_INTERVAL, SimpleSurbFlowEstimator,
17    SurbBalancerController, SurbFlowController, SurbFlowEstimator,
18};
19use crate::SessionId;
20
21#[cfg(all(feature = "telemetry", not(test)))]
22lazy_static::lazy_static! {
23    static ref METRIC_TARGET_ERROR_ESTIMATE: hopr_api::types::telemetry::MultiGauge =
24        hopr_api::types::telemetry::MultiGauge::new(
25            "hopr_surb_balancer_target_error_estimate",
26            "Target error estimation by the SURB balancer",
27            &["session_id"]
28    ).unwrap();
29    static ref METRIC_CONTROL_OUTPUT: hopr_api::types::telemetry::MultiGauge =
30        hopr_api::types::telemetry::MultiGauge::new(
31            "hopr_surb_balancer_control_output",
32            "Control output of the SURB balancer",
33            &["session_id"]
34    ).unwrap();
35    static ref METRIC_CURRENT_BUFFER: hopr_api::types::telemetry::MultiGauge =
36        hopr_api::types::telemetry::MultiGauge::new(
37            "hopr_surb_balancer_current_buffer_estimate",
38            "Estimated number of SURBs in the buffer",
39            &["session_id"]
40    ).unwrap();
41    static ref METRIC_CURRENT_TARGET: hopr_api::types::telemetry::MultiGauge =
42        hopr_api::types::telemetry::MultiGauge::new(
43            "hopr_surb_balancer_current_buffer_target",
44            "Current target (setpoint) number of SURBs in the buffer",
45            &["session_id"]
46    ).unwrap();
47    static ref METRIC_SURB_RATE: hopr_api::types::telemetry::MultiGauge =
48        hopr_api::types::telemetry::MultiGauge::new(
49            "hopr_surb_balancer_surbs_rate",
50            "Estimation of SURB rate per second (positive is buffer surplus, negative is buffer loss)",
51            &["session_id"]
52    ).unwrap();
53}
54
55/// Configuration for the `SurbBalancer`.
56#[derive(Clone, Copy, Debug, PartialEq, smart_default::SmartDefault)]
57pub struct SurbBalancerConfig {
58    /// The desired number of SURBs to be always kept as a buffer locally or at the Session counterparty.
59    ///
60    /// The `SurbBalancer` will try to maintain approximately this number of SURBs
61    /// locally or remotely (at the counterparty) at all times.
62    ///
63    /// The local buffer is maintained by regulating (`SurbFlowController`) the egress from the Session.
64    /// The remote buffer (at session counterparty) is maintained by regulating the flow of non-organic SURBs via
65    /// keep-alive messages.
66    ///
67    /// It does not make sense to set this value higher than the [`max_surb_buffer_size`](crate::SessionManagerConfig)
68    /// configuration at the counterparty.
69    ///
70    /// Default is 7000 SURBs.
71    #[default(7_000)]
72    pub target_surb_buffer_size: u64,
73    /// Maximum outflow of SURBs.
74    ///
75    /// - In the context of the local SURB buffer (Entry), this is the maximum egress Session traffic (= SURB
76    ///   consumption).
77    /// - In the context of the remote SURB buffer (Exit), this is the maximum egress of keep-alive messages to the
78    ///   counterparty (= artificial SURB production).
79    ///
80    /// The default is 5000 (which is 2500 packets/second currently)
81    #[default(5_000)]
82    pub max_surbs_per_sec: u64,
83
84    /// Sets what percentage of the target buffer size should be discarded at each window.
85    ///
86    /// The `SurbBalancer` will discard the given percentage of `target_surb_buffer_size` at each
87    /// window with the given `Duration`.
88    ///
89    /// The default is `(60, 0.05)` (5% of the target buffer size is discarded every 60 seconds).
90    #[default(_code = "Some((Duration::from_secs(60), 0.05))")]
91    pub surb_decay: Option<(Duration, f64)>,
92}
93
94impl SurbBalancerConfig {
95    /// Convenience function to convert the [`SurbBalancerConfig`] into `BalancerControllerBounds`.
96    #[inline]
97    pub fn as_controller_bounds(&self) -> BalancerControllerBounds {
98        BalancerControllerBounds::new(self.target_surb_buffer_size, self.max_surbs_per_sec)
99    }
100}
101
102/// Runtime state of the `SurbBalancer`.
103#[derive(Debug, Default)]
104pub struct BalancerStateValues {
105    pub target_surb_buffer_size: AtomicU64,
106    pub max_surbs_per_sec: AtomicU64,
107    pub decay_duration_msec: AtomicU64,
108    pub decay_volume_pct: AtomicU8,
109    pub buffer_level: AtomicU64,
110    /// SURBs counted in [`buffer_level`](Self::buffer_level), held in the counterparty's store, whose
111    /// return path runs through a relayer judged dead on any hop, and their share of what is outstanding:
112    /// count in the high and share (of `u32::MAX`) in the low 32 bits, so both are read together.
113    invalid_surbs: AtomicU64,
114    /// How many SURBs the counterparty can physically hold, or 0 when unknown.
115    ///
116    /// The level estimate is `produced - consumed - evicted`. The Exit observes its own store's
117    /// evictions first-hand (`num_evicted_surbs` on each incoming packet) and counts them, so the
118    /// level it reports tracks what the store actually holds instead of growing without bound when a
119    /// return path drops replies -- consumption alone is observed only once a reply arrives, and
120    /// before evictions were counted the belief ran away (measured during an outage: 51 917 believed
121    /// against a 15 000-entry store).
122    ///
123    /// This capacity still bounds the level, as defense-in-depth, via the `max(capacity, target)`
124    /// clamp below: it covers the paths that cannot see evictions -- the Entry's own
125    /// `produced - consumed` belief between the Exit's reports, and any session whose capacity is
126    /// unknown. The bound is `max(capacity, target)` rather than `capacity` so a target above the
127    /// counterparty's real store does not pin the error permanently negative and hold production at
128    /// maximum forever.
129    ///
130    /// ## When the store is smaller than the target
131    ///
132    /// With an accurate level, a counterparty whose store is *smaller* than the target reports a level
133    /// that plateaus at its real capacity and never reaches target, which on its own would leave
134    /// organic production running and the full buffer evicting. That corner is closed by
135    /// [`observed_counterparty_capacity`](Self::observed_counterparty_capacity), which infers the real
136    /// capacity from the plateau and caps the effective target there. It is unreachable with
137    /// homogeneous configuration (`target <= 2/3` of the store) in any case; it needs the Entry's store
138    /// to exceed ~1.5x the Exit's.
139    pub counterparty_buffer_capacity: AtomicU64,
140    /// Whether the counterparty's last packet said it was running low on SURBs of its own.
141    ///
142    /// A plain flag with no deadline: a distress flag that is never withdrawn merely keeps organic
143    /// production at one SURB per packet — the behaviour that predates the gate — so it does not
144    /// need to expire.
145    ///
146    /// It clears on its own in the normal case: the counterparty recomputes both SURB signals on
147    /// every return packet and strips them once its pool recovers, so the next healthy packet
148    /// resets this.
149    pub counterparty_in_surb_distress: AtomicBool,
150    /// The counterparty's real store capacity, inferred from where its reported level plateaus, or
151    /// `0` when not yet inferred.
152    ///
153    /// Closes the `capacity < target` corner noted on
154    /// [`counterparty_buffer_capacity`](Self::counterparty_buffer_capacity): when the reported level
155    /// stops rising while the Entry is still minting toward the target and the counterparty is not in
156    /// distress, its store is full at a level below the target, and that level is its real capacity.
157    /// [`organic_surbs_per_packet`](Self::organic_surbs_per_packet) then stops production at
158    /// `min(target, this)` instead of a target the store can never reach.
159    ///
160    /// Biased hard against firing, since a false positive under-supplies the counterparty (see the
161    /// destructive-recovery note in the SURB balancer gotchas): it takes several consecutive
162    /// non-rising reports (see [`observe_reported_level`](Self::observe_reported_level)), and a
163    /// [`SurbDistress`](hopr_crypto_packet::prelude::PacketSignal::SurbDistress) signal discards it
164    /// outright -- a counterparty short of SURBs is not full. Set back to `0` (re-probe) if the level
165    /// later rises above it.
166    pub observed_counterparty_capacity: AtomicU64,
167    /// Consecutive reported levels that did not rise while below target -- the plateau hysteresis
168    /// behind [`observed_counterparty_capacity`](Self::observed_counterparty_capacity).
169    pub capacity_plateau_count: AtomicU64,
170    /// Set by [`on_counterparty_wiped`](Self::on_counterparty_wiped), consumed by the next balancer
171    /// update: the counterparty dropped its whole stock, so that update restarts the level estimate
172    /// from empty.
173    ///
174    /// A flag rather than a plain store of `0` into [`buffer_level`](Self::buffer_level) because the
175    /// level has another writer: the update in flight, which would write back the level it loaded
176    /// before the reset. (The counterparty's keep-alive is the other, which may still carry its
177    /// pre-wipe level; [`observe_reported_level`](Self::observe_reported_level) drops such a report
178    /// while the refill is paced.)
179    counterparty_wiped: AtomicBool,
180    /// Paces the refill after a wipe: the rate in SURBs per second in the high 32 bits and the
181    /// milliseconds it still holds for in the low 32 bits, so both are read together. Zero is
182    /// inactive. See `REFILL_PACING_SECS`.
183    refill_pacing: AtomicU64,
184    /// This side's `produced` count as it was `REPORT_LAG` before the last balancer update, published by
185    /// every update from [`ProducedHistory`]: what a counterparty report arriving now cannot have seen
186    /// yet is the production since then. `0` until the first update.
187    produced_before_lag: AtomicU64,
188    /// This side's `produced` count at the last balancer update, published with
189    /// [`produced_before_lag`](Self::produced_before_lag). What is produced after it is the next update's
190    /// to add, so a report adopted in between takes as in flight only the production up to it.
191    produced_at_update: AtomicU64,
192    /// Set when a report lowered the believed level, consumed by the next balancer update: that
193    /// update's output is held to the pacing rate, so that a correction never turns into a burst.
194    correction_cap: AtomicBool,
195    /// The instant [`last_heard`](Self::last_heard) and [`last_sent`](Self::last_sent) count from.
196    epoch: ActivityEpoch,
197    /// When the counterparty was last heard from, in milliseconds since `epoch` plus one, so that `0`
198    /// is "never". Any packet from it counts, and so does a reply the estimator counted as consumed.
199    /// Entry-side only; see [`silence_sustain`](Self::silence_sustain).
200    last_heard: AtomicU64,
201    /// When a Session data packet last went out, in the same unit as [`last_heard`](Self::last_heard).
202    last_sent: AtomicU64,
203    /// When the current run of unanswered data began, in the same unit as [`last_heard`](Self::last_heard):
204    /// the first packet sent after the counterparty was last heard. See
205    /// [`silence_sustain`](Self::silence_sustain).
206    sending_since: AtomicU64,
207    /// When the run of data before the current one ended, in the same unit as [`last_heard`](Self::last_heard):
208    /// its last packet. The reply stream is judged against it; see [`silence_sustain`](Self::silence_sustain).
209    previous_run_ended: AtomicU64,
210    /// When a reply the estimator counted as consumed last came home, in the same unit as
211    /// [`last_heard`](Self::last_heard): what tells a reply stream that stopped from one that never was.
212    last_reply_heard: AtomicU64,
213    /// Entry-side: the SURBs the estimator counted as consumed for the counterparty's keep-alives rather
214    /// than for replies to data. Only ever grows.
215    keep_alives_consumed: AtomicU64,
216    /// The fewest SURBs per second the paced fill and refill may be held to: one keep-alive's worth,
217    /// set by the Session that owns the balancer. `0` until set. See [`pacing_cap`](Self::pacing_cap).
218    pacing_floor: AtomicU64,
219    /// Exit-side: whether the Entry has shown that it refills this side's SURB stock. See
220    /// [`counterparty_refills`](Self::counterparty_refills).
221    counterparty_refills: AtomicBool,
222}
223
224/// The instant the activity stamps of a [`BalancerStateValues`] count from: when it was made.
225#[derive(Debug, Clone, Copy)]
226struct ActivityEpoch(std::time::Instant);
227
228impl Default for ActivityEpoch {
229    fn default() -> Self {
230        Self(std::time::Instant::now())
231    }
232}
233
234/// How long data can go out with nothing at all coming back before the Entry sustains the
235/// counterparty's SURBs on its own: three seconds.
236///
237/// A counterparty that was replying replies at the rate of the data it receives, so three seconds of
238/// data going out and nothing coming back, neither a reply, nor a report, nor any other packet, means
239/// that its consumption is invisible: its stock may be draining into a return path that delivers
240/// nothing, and the balancer, which learns the level from those replies and reports, cannot see it
241/// and would mint nothing. Reports alone do not tell that: the Exit sends one every
242/// `surb_balance_notify_period`, 15 s by default, so a Session the Exit does not answer (an upload)
243/// is quiet for most of every period without anything being wrong. Hence the sustain needs a reply
244/// stream that stopped; see [`REPLY_STREAM_WINDOW`] and
245/// [`silence_sustain`](BalancerStateValues::silence_sustain).
246pub const SILENCE_SUSTAIN_AFTER: Duration = Duration::from_secs(3);
247
248/// How recent the last reply must be, relative to the last data packet before the current run of unanswered
249/// data, for a silence to be a reply stream that stopped rather than a Session that gets no replies: one
250/// default notify period.
251pub const REPLY_STREAM_WINDOW: Duration = Duration::from_secs(15);
252
253/// How long the refill that follows a wipe of the counterparty's stock is paced for, at a rate of
254/// one fifth of the target per second (at least one keep-alive's worth, never above
255/// `max_surbs_per_sec`; see `pacing_cap`), so the refill takes about as many seconds.
256///
257/// After a wipe the level is zero against the target, and left alone the PID commands its output
258/// limit (`max_surbs_per_sec`; the prototype hit 4975 per second against a ceiling of 5000 per
259/// second in the integration cluster) until the level is
260/// back. On a path through two or three relayers on one machine that burst congests the relays
261/// themselves, the replies it is meant to restore arrive late, and late replies are what the
262/// verdicts are made of. The organic gate is open for the whole refill anyway, so spreading it over
263/// a few seconds costs little: the SURBs of the next data packets arrive in the meantime.
264///
265/// The start of a session at the Entry is the same state: the counterparty holds nothing, the level
266/// estimate says so, and the PID would command its ceiling from the first tick. That flood lost
267/// replies at session start (one flush tick about three seconds in: 1037 expected, 201 observed),
268/// the corroborated verdict judged the two slowest relayers dead on those, and wiped the fresh
269/// stock; hoprnet#8484's cold burst was the same flood seen from the data path. The Entry arms the
270/// same pacing when its balancer starts ([`BalancerStateValues::arm_refill_pacing`]), and the fill
271/// reaches the target in about five seconds instead of one and a half, sparing the relays.
272///
273/// While the window lasts the PID does not run: the balancer commands the cap while the level is
274/// below the target and nothing from the moment it is reached. A cap applied to the PID's output
275/// instead would let it integrate the full error for the whole window and answer a level at or past
276/// the target with its ceiling when the window ends. The controller is rebuilt with its own gains and
277/// bounds when the window ends, so that it starts from the current error. Neither `max_surbs_per_sec`
278/// nor the bounds [`SurbBalancer::start_control_loop`] rebuilds the PID from change.
279pub const REFILL_PACING_SECS: u64 = 5;
280
281/// How long a counterparty's SURB level report is assumed to have been on its way: the production
282/// of this long before a report arrives is added to the level it carries.
283///
284/// A report says what the counterparty held when it was written, before the SURBs that were in
285/// flight to it reached it, so taken as it stands it pulls the believed level below the truth by
286/// that much. One second covers the one-way latency of a multi-hop return path with mixing; a lag
287/// taken too long errs on the high side, which the counterparty's distress signal corrects within a
288/// packet, where a lag taken too short errs low and is corrected only by the next report. (The much
289/// larger lag measured after a bump, a whole notify period, was the keep-alive stream sampling the
290/// level when the rate limiter pulled the item rather than when it released it; that is fixed at the
291/// source in `spawn_keep_alive_stream` and no longer something this constant has to cover.)
292pub const REPORT_LAG: Duration = Duration::from_secs(1);
293
294/// Consecutive non-rising reported levels (below target, no distress) before the counterparty's
295/// store capacity is inferred. Small, but greater than one: a single flat sample is ordinary churn,
296/// and the cost of a false inference is under-supplying the counterparty, so the bar errs high.
297pub(crate) const CAPACITY_PLATEAU_THRESHOLD: u64 = 3;
298
299impl BalancerStateValues {
300    /// Constructor from a [`SurbBalancerConfig`].
301    pub fn new(cfg: SurbBalancerConfig) -> Self {
302        let state = Self::default();
303        state.update(&cfg);
304        state
305    }
306
307    /// Performs update of the [`BalancerStateValues`] from the [`SurbBalancerConfig`] and
308    /// enables it.
309    pub fn update(&self, cfg: &SurbBalancerConfig) {
310        self.target_surb_buffer_size
311            .store(cfg.target_surb_buffer_size, std::sync::atomic::Ordering::Relaxed);
312        self.max_surbs_per_sec
313            .store(cfg.max_surbs_per_sec, std::sync::atomic::Ordering::Relaxed);
314        self.decay_duration_msec.store(
315            cfg.surb_decay
316                .map(|(d, _)| d.as_millis().min(u64::MAX as u128) as u64)
317                .unwrap_or_default(),
318            std::sync::atomic::Ordering::Relaxed,
319        );
320        self.decay_volume_pct.store(
321            cfg.surb_decay
322                .map(|(_, p)| (p.clamp(0.0, 1.0) * 100.0).round() as u8)
323                .unwrap_or_default(),
324            std::sync::atomic::Ordering::Relaxed,
325        );
326    }
327
328    /// Declares how many SURBs the counterparty's store can hold, bounding the level estimate.
329    ///
330    /// Taken from the session manager's `maximum_surb_buffer_size`, which is the same capacity
331    /// already used to clamp a counterparty's requested target. Zero leaves the estimate unbounded.
332    pub fn set_counterparty_buffer_capacity(&self, capacity: u64) {
333        self.counterparty_buffer_capacity
334            .store(capacity, std::sync::atomic::Ordering::Relaxed);
335    }
336
337    /// Caps `level` at what the counterparty can actually hold.
338    ///
339    /// Never below the configured target: a target above the counterparty's capacity is
340    /// unreachable by construction, and clamping to capacity there would hold the error permanently
341    /// negative and pin production at maximum forever -- a worse failure than the unbounded
342    /// estimate this exists to prevent. In that configuration the capacity figure is simply not
343    /// usable for this session.
344    fn clamp_to_counterparty_capacity(&self, level: u64) -> u64 {
345        match self
346            .counterparty_buffer_capacity
347            .load(std::sync::atomic::Ordering::Relaxed)
348        {
349            0 => level,
350            capacity => {
351                level.min(capacity.max(self.target_surb_buffer_size.load(std::sync::atomic::Ordering::Relaxed)))
352            }
353        }
354    }
355
356    /// Records what the counterparty's latest packet said about *its own* SURB supply.
357    ///
358    /// Takes the whole signal set rather than a `bool` so the containment rule lives here: `OutOfSurbs`
359    /// is a superset of `SurbDistress` on the wire, so `contains` catches both, whereas an equality
360    /// match against `SurbDistress` would silently ignore the more severe of the two.
361    pub fn observe_counterparty_signals(&self, signals: PacketSignals) {
362        // Any packet from the counterparty carries them, so this is the Entry hearing the Exit.
363        self.note_heard();
364        let distress = signals.contains(PacketSignal::SurbDistress);
365        self.counterparty_in_surb_distress
366            .store(distress, std::sync::atomic::Ordering::Relaxed);
367
368        if distress {
369            // A counterparty short of SURBs is not full: discard any inferred capacity so the Entry
370            // resumes producing toward the full target and re-probes once distress clears. This is the
371            // corrective that keeps a too-low capacity guess from starving the counterparty.
372            self.observed_counterparty_capacity
373                .store(0, std::sync::atomic::Ordering::Relaxed);
374            self.capacity_plateau_count
375                .store(0, std::sync::atomic::Ordering::Relaxed);
376        }
377    }
378
379    /// Records the SURB level the counterparty reported, net of the production it cannot have seen
380    /// yet, and infers its real store capacity from a plateau in that level.
381    ///
382    /// Called on every `BalancerState` keep-alive, including one that repeats the last value -- a
383    /// level that stops rising while the Entry is still minting toward the target is the plateau
384    /// signal. See [`observed_counterparty_capacity`](Self::observed_counterparty_capacity).
385    ///
386    /// The report was written `REPORT_LAG` or less ago, so the SURBs produced since then were still on
387    /// their way when it was written and are added to it: adopting a report as it stands pulls the
388    /// level below the truth by exactly that production. Only the production up to the last balancer
389    /// update is added here, though: the next update adds everything produced after that one to the
390    /// level in any case, and adding it here as well would count it twice. A report that still lowers
391    /// the believed level marks the next balancer update so that its output is held to the pacing
392    /// rate: a correction, not a deficit to burst for.
393    ///
394    /// While the refill after a wipe is paced, every report is dropped, stored by neither the level
395    /// nor the plateau bookkeeping: a report above the believed level is the counterparty reporting
396    /// the stock it had before it saw the new SURB generation, and one below it is the stock it had
397    /// before the refill in flight reached it, thousands short at the pacing rate. The level believed
398    /// here during the window is the production since the reset, which is the truth by construction.
399    pub fn observe_reported_level(&self, new_level: u64) {
400        use std::sync::atomic::Ordering::Relaxed;
401
402        // Heard even when the report is dropped below: it is the Exit speaking.
403        self.note_heard();
404        let prev = self.buffer_level.load(Relaxed);
405        if self.refill_pacing_active() {
406            tracing::debug!(
407                reported = new_level,
408                believed = prev,
409                "dropping a counterparty SURB level report while the refill after a wipe is paced"
410            );
411            return;
412        }
413        let in_flight = self
414            .produced_at_update
415            .load(Relaxed)
416            .saturating_sub(self.produced_before_lag.load(Relaxed));
417        let level = new_level.saturating_add(in_flight);
418        let target = self.target_surb_buffer_size.load(Relaxed);
419        let distress = self.counterparty_in_surb_distress.load(Relaxed);
420        let inferred = self.observed_counterparty_capacity.load(Relaxed);
421
422        if inferred != 0 && level > inferred {
423            // The counterparty is holding more than we inferred, so the store is larger than the
424            // plateau suggested (or has grown). Forget the guess and probe again.
425            self.observed_counterparty_capacity.store(0, Relaxed);
426            self.capacity_plateau_count.store(0, Relaxed);
427        } else if inferred == 0 && !distress && level > 0 && level < target && level <= prev {
428            // Below target with no distress, yet the level is not rising: the Entry is minting toward
429            // the target but the counterparty is not accepting more, so its store is full at a level
430            // below the target. Require several consecutive such reports before acting.
431            let plateau = self.capacity_plateau_count.fetch_add(1, Relaxed) + 1;
432            if plateau >= CAPACITY_PLATEAU_THRESHOLD {
433                self.observed_counterparty_capacity.store(level, Relaxed);
434            }
435        } else {
436            // Rising, at/above target, in distress, or refilling below an inferred cap: not a plateau.
437            self.capacity_plateau_count.store(0, Relaxed);
438        }
439
440        if level < prev {
441            tracing::debug!(
442                reported = new_level,
443                in_flight,
444                believed = prev,
445                adopted = level,
446                "a counterparty SURB level report lowered the believed level; the next update is paced"
447            );
448            self.correction_cap.store(true, Relaxed);
449        }
450        self.buffer_level.store(level, Relaxed);
451    }
452
453    /// Publishes this side's `produced` count as it was `REPORT_LAG` before this update and as it is at
454    /// this update, for [`observe_reported_level`](Self::observe_reported_level). Called by every
455    /// balancer update.
456    pub(crate) fn publish_production(&self, before_lag: u64, at_update: u64) {
457        self.produced_before_lag
458            .store(before_lag, std::sync::atomic::Ordering::Relaxed);
459        self.produced_at_update
460            .store(at_update, std::sync::atomic::Ordering::Relaxed);
461    }
462
463    /// Takes the one-shot request to hold the next output to the pacing rate, if there is one.
464    fn take_correction_cap(&self) -> bool {
465        self.correction_cap.swap(false, std::sync::atomic::Ordering::Relaxed)
466    }
467
468    /// The rate the fill and the refill after a wipe are held to: `target / REFILL_PACING_SECS` SURBs
469    /// per second, at least one keep-alive's worth ([`set_pacing_floor`](Self::set_pacing_floor)) and
470    /// at least one, and never above `max_surbs_per_sec`.
471    ///
472    /// The floor matters at small targets only: a keep-alive carries a fixed number of SURBs, so a
473    /// fifth of a target of 11 is two SURBs a second, a keep-alive every four seconds, and a Session
474    /// that waited for a quarter of its target opened after four seconds instead of under one. The
475    /// ceiling is the bound the PID output had: the pacing replaces that output for its window, and
476    /// must not exceed what the client configured the balancer to mint.
477    pub(crate) fn pacing_cap(&self) -> u64 {
478        use std::sync::atomic::Ordering::Relaxed;
479
480        (self.target_surb_buffer_size.load(Relaxed) / REFILL_PACING_SECS)
481            .max(self.pacing_floor.load(Relaxed))
482            .max(1)
483            .min(self.max_surbs_per_sec.load(Relaxed))
484            .min(u64::from(u32::MAX))
485    }
486
487    /// Sets the fewest SURBs per second the pacing may be held to: one keep-alive's worth of SURBs, so
488    /// that a paced fill sends at least one keep-alive a second. See `pacing_cap`.
489    pub fn set_pacing_floor(&self, surbs_per_sec: u64) {
490        self.pacing_floor
491            .store(surbs_per_sec, std::sync::atomic::Ordering::Relaxed);
492    }
493
494    /// How many SURBs an outgoing Session data packet should carry along with its payload.
495    ///
496    /// Entry-side only. [`BalancerStateValues`] is shared by both ends of a Session, but only the
497    /// initiator mints SURBs for its counterparty, so on the Exit this answer is meaningless.
498    ///
499    /// Returning `0` is the point: a SURB delivered to a counterparty that is already at its target
500    /// evicts the oldest one it holds, and under PIX that destroys an SSA share rather than merely
501    /// wasting a SURB. Production resumes at one per packet as soon as the estimate falls back below
502    /// target, or immediately if the counterparty signals it is running low.
503    ///
504    /// This uses the usable level: SURBs the counterparty holds through a relayer judged dead do not
505    /// hold the gate shut.
506    pub fn organic_surbs_per_packet(&self) -> usize {
507        // Not defensive boilerplate: nothing rejects a `SurbBalancerConfig` with a zero target, and
508        // without this branch `level >= 0` would hold forever and shut organic production off
509        // permanently — while a PID with a zero output limit produces nothing either.
510        if self.is_disabled() {
511            return 1;
512        }
513
514        if self
515            .counterparty_in_surb_distress
516            .load(std::sync::atomic::Ordering::Relaxed)
517        {
518            return 1;
519        }
520
521        // Stop at the counterparty's real capacity when it is known to be smaller than the target:
522        // filling past a store that cannot grow only evicts, which under PIX destroys SSA shares.
523        let target = self.target_surb_buffer_size.load(std::sync::atomic::Ordering::Relaxed);
524        let effective_target = match self
525            .observed_counterparty_capacity
526            .load(std::sync::atomic::Ordering::Relaxed)
527        {
528            0 => target,
529            capacity => target.min(capacity),
530        };
531
532        if self.usable_level(self.buffer_level()) >= effective_target {
533            0
534        } else {
535            1
536        }
537    }
538
539    /// Records that the counterparty was heard from now.
540    pub(crate) fn note_heard(&self) {
541        self.stamp(&self.last_heard, std::time::Instant::now());
542    }
543
544    /// Records that the counterparty refills this side's SURB stock. The Exit calls it on a keep-alive
545    /// from the Entry other than a manual ping: only an Entry's SURB balancer runs a keep-alive stream.
546    pub(crate) fn note_counterparty_refills(&self) {
547        self.counterparty_refills
548            .store(true, std::sync::atomic::Ordering::Relaxed);
549    }
550
551    /// Whether the counterparty has shown that it refills this side's SURB stock (see
552    /// [`note_counterparty_refills`](Self::note_counterparty_refills)). An Entry without a SURB
553    /// balancer never does: it attaches one SURB to each data packet and sends no keep-alives of its own,
554    /// only the odd manual ping (an Entry that predates `ManualPing` and pings by hand still sets it).
555    pub(crate) fn counterparty_refills(&self) -> bool {
556        self.counterparty_refills.load(std::sync::atomic::Ordering::Relaxed)
557    }
558
559    /// Records that a Session data packet is going out now. The first one since the counterparty was
560    /// last heard starts a new run of unanswered data, and the last packet before it ended the previous one.
561    pub(crate) fn note_sent(&self) {
562        use std::sync::atomic::Ordering::Relaxed;
563
564        let now = std::time::Instant::now();
565        if self.sending_since.load(Relaxed) <= self.last_heard.load(Relaxed) {
566            self.previous_run_ended.fetch_max(self.last_sent.load(Relaxed), Relaxed);
567            self.stamp(&self.sending_since, now);
568        }
569        self.stamp(&self.last_sent, now);
570    }
571
572    /// Records that a reply the estimator counted as consumed came home now.
573    pub(crate) fn note_reply_heard(&self) {
574        self.stamp(&self.last_reply_heard, std::time::Instant::now());
575    }
576
577    /// Counts a SURB consumed by a counterparty keep-alive, not by a reply, in the `estimator` too.
578    ///
579    /// The keep-alive count is written before `consumed` is released, and the estimator acquires `consumed`
580    /// when read, so a reader that sees the SURB also sees its keep-alive.
581    pub(crate) fn note_keep_alive_consumed(&self, estimator: &AtomicSurbFlowEstimator) {
582        self.keep_alives_consumed
583            .fetch_add(1, std::sync::atomic::Ordering::Relaxed);
584        estimator.consumed.fetch_add(1, std::sync::atomic::Ordering::Release);
585    }
586
587    /// The number of consumed SURBs that were spent on counterparty keep-alives. See
588    /// [`note_keep_alive_consumed`](Self::note_keep_alive_consumed).
589    pub(crate) fn keep_alives_consumed(&self) -> u64 {
590        self.keep_alives_consumed.load(std::sync::atomic::Ordering::Relaxed)
591    }
592
593    /// Test hook: as if the counterparty had last been heard from `ago` ago.
594    ///
595    /// The stamps count from the instant the state was made, so for one to lie in the past the epoch
596    /// has to be moved back before it.
597    #[cfg(test)]
598    pub(crate) fn last_heard_ago(self, ago: Duration) -> Self {
599        let state = self.last_heard_only_ago(ago);
600        let at = std::time::Instant::now()
601            .checked_sub(ago)
602            .expect("monotonic clock younger than `ago`");
603        // What it was heard on was a reply: a reply stream that stopped `ago` ago.
604        state.stamp(&state.last_reply_heard, at);
605        state
606    }
607
608    /// Test hook: as if the counterparty had last been heard from `ago` ago, by a report or a packet that
609    /// was no reply, and had never replied.
610    #[cfg(test)]
611    pub(crate) fn last_heard_only_ago(mut self, ago: Duration) -> Self {
612        let now = std::time::Instant::now();
613        self.epoch = ActivityEpoch(
614            now.checked_sub(ago + Duration::from_secs(60))
615                .expect("monotonic clock younger than the heard-ago offset"),
616        );
617        self.stamp(
618            &self.last_heard,
619            now.checked_sub(ago).expect("monotonic clock younger than `ago`"),
620        );
621        self
622    }
623
624    /// Test hook: as if data had been going out unanswered since `ago` ago, the first packet of the run
625    /// sent then. Takes the epoch [`last_heard_ago`](Self::last_heard_ago) set, so it comes after it.
626    #[cfg(test)]
627    pub(crate) fn sending_since_ago(self, ago: Duration) -> Self {
628        use std::sync::atomic::Ordering::Relaxed;
629
630        let at = std::time::Instant::now()
631            .checked_sub(ago)
632            .expect("monotonic clock younger than `ago`");
633        // As `note_sent` does: a run that starts after the counterparty was heard ends the previous one.
634        if self.sending_since.load(Relaxed) <= self.last_heard.load(Relaxed) {
635            self.previous_run_ended.fetch_max(self.last_sent.load(Relaxed), Relaxed);
636        }
637        self.stamp(&self.sending_since, at);
638        self.stamp(&self.last_sent, at);
639        self
640    }
641
642    /// Test hook: as if the last data packet had gone out `ago` ago, without starting a run. Takes the epoch
643    /// [`last_heard_ago`](Self::last_heard_ago) set, so it comes after it.
644    #[cfg(test)]
645    pub(crate) fn last_sent_ago(self, ago: Duration) -> Self {
646        let at = std::time::Instant::now()
647            .checked_sub(ago)
648            .expect("monotonic clock younger than `ago`");
649        self.stamp(&self.last_sent, at);
650        self
651    }
652
653    /// Test hook: as if the counterparty had been heard again `ago` ago, by a report or a packet that was
654    /// no reply. Takes the epoch [`last_heard_ago`](Self::last_heard_ago) set, so it comes after it.
655    #[cfg(test)]
656    pub(crate) fn heard_again_ago(self, ago: Duration) -> Self {
657        let at = std::time::Instant::now()
658            .checked_sub(ago)
659            .expect("monotonic clock younger than `ago`");
660        self.stamp(&self.last_heard, at);
661        self
662    }
663
664    /// Stamps `slot` with `at`, never moving it back.
665    fn stamp(&self, slot: &AtomicU64, at: std::time::Instant) {
666        let ms = u64::try_from(at.saturating_duration_since(self.epoch.0).as_millis()).unwrap_or(u64::MAX - 1);
667        slot.fetch_max(ms.saturating_add(1), std::sync::atomic::Ordering::Relaxed);
668    }
669
670    /// Whether data is going out into silence: the balancer is enabled, the counterparty was heard from
671    /// at least once, and data has been going out for more than [`SILENCE_SUSTAIN_AFTER`] since the first
672    /// packet sent after the last time it was. The window starts at that first unanswered packet, not at
673    /// the last word heard: an idle stretch leaves nothing unanswered, and the Exit gets the grace to
674    /// answer the data that ends it.
675    ///
676    /// The Entry then keeps one SURB in each data packet it sends even though its level estimate is at
677    /// or above the target (see `cap_organic_surbs` in the session manager). The estimate is fed by the
678    /// Exit's reports and replies; with none arriving it stays where it was, while the Exit goes on
679    /// answering the data it gets, one SURB for each reply, into a return path that may be delivering
680    /// nothing. The estimate then never falls below the target and the Entry mints nothing, until the
681    /// Exit's stock is empty. The balancer's own `surb_decay` is the exception: on by default (5 % of
682    /// the target per 60 s) it erodes the estimate each window, so at a data rate low enough that the
683    /// sustain's one-SURB-per-packet production does not outpace it, the estimate falls below the
684    /// target within a decay window or two and the gate reopens without the sustain. One SURB per data
685    /// packet is what the Exit can be expected to spend and no more: the sustain is bounded by the rate
686    /// of the data, makes no burst, and wipes nothing. It ends at the first packet or reply from the
687    /// Exit.
688    ///
689    /// Only a reply stream that stopped counts: the last reply must be within [`REPLY_STREAM_WINDOW`] of
690    /// the last data packet before the current run, that is, the Exit answered the data that went out
691    /// before. A Session the Exit does not answer hears only its reports, one per notify period, and
692    /// sustaining it would put one SURB in every data packet into a stock nothing spends, up to the
693    /// store's capacity. The reports that arrive while nothing goes out do not age the reply stream: a
694    /// Session that was answered, went quiet, and whose return path failed meanwhile still gets the
695    /// sustain once it sends again.
696    ///
697    /// Judged between the stamps, not against the clock, so that the answer is about the packet being
698    /// sent: it takes [`note_sent`](Self::note_sent) for that packet first.
699    pub(crate) fn silence_sustain(&self) -> bool {
700        use std::sync::atomic::Ordering::Relaxed;
701
702        if self.is_disabled() {
703            return false;
704        }
705        match (self.last_heard.load(Relaxed), self.last_reply_heard.load(Relaxed)) {
706            (0, _) | (_, 0) => false,
707            (heard, replied) => {
708                let after = u64::try_from(SILENCE_SUSTAIN_AFTER.as_millis()).unwrap_or(u64::MAX);
709                let window = u64::try_from(REPLY_STREAM_WINDOW.as_millis()).unwrap_or(u64::MAX);
710                let since = self.sending_since.load(Relaxed);
711                // A reply stream that stopped, not a Session the counterparty does not answer, and data
712                // going out unanswered for longer than the grace, not the first packet after a pause.
713                replied.saturating_add(window) >= self.previous_run_ended.load(Relaxed)
714                    && since > heard
715                    && self.last_sent.load(Relaxed) > since.saturating_add(after)
716            }
717        }
718    }
719
720    /// Tells the state that the counterparty dropped every SURB it held, because the SURB generation
721    /// of the session advanced and the counterparty clears its store on the first batch of the new one.
722    ///
723    /// The level estimate restarts from empty at the next balancer update, and for
724    /// `REFILL_PACING_SECS` the refill is held to the pacing rate: a fifth of the target a second, at
725    /// least one keep-alive's worth and never above `max_surbs_per_sec` (see `pacing_cap`).
726    /// The counterparty's own reports follow suit once the first SURBs of the new generation reach
727    /// it. Until then it may still report the level it had before, and then the level before the
728    /// refill in flight reached it; for the paced window every report is dropped (see
729    /// [`observe_reported_level`](Self::observe_reported_level)).
730    pub fn on_counterparty_wiped(&self) {
731        use std::sync::atomic::Ordering::Release;
732
733        self.buffer_level.store(0, Release);
734        self.counterparty_wiped.store(true, Release);
735        self.arm_refill_pacing();
736    }
737
738    /// Holds the refill of an empty counterparty to the pacing rate (`pacing_cap`: a fifth of the target
739    /// a second, at least one keep-alive's worth, never above `max_surbs_per_sec`) for
740    /// `REFILL_PACING_SECS`, whatever the PID would command. A disabled balancer arms nothing.
741    ///
742    /// The second half of [`on_counterparty_wiped`](Self::on_counterparty_wiped), and what the Entry
743    /// calls when its balancer starts: a session that has just been opened is in the same state as one
744    /// that has just been wiped, the counterparty holds nothing and the level estimate says so, and
745    /// the PID would command its ceiling just the same. Unlike a wipe it resets nothing: the estimate
746    /// is already empty, and what the first tick produced is the new session's.
747    pub fn arm_refill_pacing(&self) {
748        use std::sync::atomic::Ordering::Relaxed;
749
750        if self.is_disabled() {
751            return;
752        }
753        let cap = self.pacing_cap();
754        self.refill_pacing
755            .store((cap << 32) | (REFILL_PACING_SECS * 1000), Relaxed);
756    }
757
758    /// Takes the one-shot request to restart the level estimate from empty, if there is one.
759    fn take_counterparty_wiped(&self) -> bool {
760        self.counterparty_wiped.swap(false, std::sync::atomic::Ordering::AcqRel)
761    }
762
763    /// Whether the refill after a wipe is still paced. Read-only: unlike [`pace_refill`](Self::pace_refill)
764    /// it does not use up any of the window.
765    pub(crate) fn refill_pacing_active(&self) -> bool {
766        self.refill_pacing.load(std::sync::atomic::Ordering::Relaxed) & u64::from(u32::MAX) > 0
767    }
768
769    /// The cap on the control output while the refill after a wipe is paced, in SURBs per second, and
770    /// uses up `elapsed` of the pacing window. `None` when no pacing is active.
771    fn pace_refill(&self, elapsed: Duration) -> Option<u64> {
772        const REMAINING: u64 = u32::MAX as u64;
773
774        let elapsed_ms = elapsed.as_millis().min(u128::from(u32::MAX)) as u64;
775        self.refill_pacing
776            .fetch_update(
777                std::sync::atomic::Ordering::Relaxed,
778                std::sync::atomic::Ordering::Relaxed,
779                |packed| {
780                    let remaining = packed & REMAINING;
781                    (remaining > 0).then(|| match remaining.saturating_sub(elapsed_ms) {
782                        0 => 0,
783                        left => (packed & !REMAINING) | left,
784                    })
785                },
786            )
787            .ok()
788            .map(|packed| packed >> 32)
789    }
790
791    /// Sets how many stored SURBs are invalid and their share of what is outstanding.
792    pub fn set_invalid_surbs(&self, count: u64, share: f64) {
793        let share = (share.clamp(0.0, 1.0) * f64::from(u32::MAX)).round() as u64;
794        self.invalid_surbs.store(
795            count.min(u64::from(u32::MAX)) << 32 | share,
796            std::sync::atomic::Ordering::Relaxed,
797        );
798    }
799
800    /// The part of `level` that can still bring a reply home.
801    fn usable_level(&self, level: u64) -> u64 {
802        let packed = self.invalid_surbs.load(std::sync::atomic::Ordering::Relaxed);
803        let (count, share) = (
804            packed >> 32,
805            (packed & u64::from(u32::MAX)) as f64 / f64::from(u32::MAX),
806        );
807        // The count can overstate what the counterparty still holds; the share caps it by its level.
808        level.saturating_sub(count.min((level as f64 * share).round() as u64))
809    }
810
811    /// Extracts the [`SurbBalancerConfig`] from the [`BalancerStateValues`].
812    pub fn as_config(&self) -> SurbBalancerConfig {
813        SurbBalancerConfig {
814            target_surb_buffer_size: self.target_surb_buffer_size.load(std::sync::atomic::Ordering::Relaxed),
815            max_surbs_per_sec: self.max_surbs_per_sec.load(std::sync::atomic::Ordering::Relaxed),
816            surb_decay: self.surb_decay(),
817        }
818    }
819
820    /// Checks if SURB balancing is disabled (no target buffer size set).
821    pub fn is_disabled(&self) -> bool {
822        self.target_surb_buffer_size.load(std::sync::atomic::Ordering::Relaxed) == 0
823    }
824
825    /// Extracts the SURB decay configuration from the [`BalancerStateValues`].
826    pub fn surb_decay(&self) -> Option<(Duration, f64)> {
827        Some((
828            self.decay_duration_msec.load(std::sync::atomic::Ordering::Relaxed),
829            self.decay_volume_pct.load(std::sync::atomic::Ordering::Relaxed),
830        ))
831        .filter(|&(d, p)| d > 0 && p > 0)
832        .map(|(d, p)| (Duration::from_millis(d), p as f64 / 100.0))
833    }
834
835    /// Gets the current estimated SURB buffer level.
836    #[inline]
837    pub fn buffer_level(&self) -> u64 {
838        self.buffer_level.load(std::sync::atomic::Ordering::Relaxed)
839    }
840
841    /// Returns the current `BalancerControllerBounds` from the [`BalancerStateValues`].
842    #[inline]
843    pub fn controller_bounds(&self) -> BalancerControllerBounds {
844        BalancerControllerBounds::new(
845            self.target_surb_buffer_size.load(std::sync::atomic::Ordering::Relaxed),
846            self.max_surbs_per_sec.load(std::sync::atomic::Ordering::Relaxed),
847        )
848    }
849}
850
851impl From<SurbBalancerConfig> for BalancerStateValues {
852    fn from(cfg: SurbBalancerConfig) -> Self {
853        Self::new(cfg)
854    }
855}
856
857/// This side's `produced` count over the last `REPORT_LAG`, one sample per balancer update, so
858/// that a counterparty report can be read net of the production it cannot have seen yet.
859#[derive(Debug, Default)]
860struct ProducedHistory {
861    samples: VecDeque<(Instant, u64)>,
862}
863
864impl ProducedHistory {
865    /// Records `produced` as of `now` and returns the count as it was `REPORT_LAG` ago: the newest
866    /// sample at least that old, or the oldest one there is while the history is still shorter than
867    /// the lag (so that the correction never exceeds what this history has seen).
868    fn record(&mut self, now: Instant, produced: u64) -> u64 {
869        self.samples.push_back((now, produced));
870        let horizon = now.checked_sub(REPORT_LAG);
871        while self.samples.len() >= 2 && horizon.is_some_and(|h| self.samples[1].0 <= h) {
872            self.samples.pop_front();
873        }
874        self.samples.front().map_or(produced, |(_, p)| *p)
875    }
876}
877
878/// Runs a continuous process that attempts to [evaluate](SurbFlowEstimator) and
879/// [regulate](SurbFlowController) the flow of SURBs to the Session counterparty,
880/// to keep the number of SURBs locally or at the counterparty at a certain level.
881///
882/// Internally, the Balancer uses an implementation of [`SurbBalancerController`] to
883/// control the rate of SURBs consumed or sent to the counterparty
884/// each time the [`update`](SurbBalancer::update) method is called:
885///
886/// 1. The size of the SURB buffer at locally or at the counterparty is estimated using [`SurbFlowEstimator`].
887/// 2. Error against a set-point given in [`SurbBalancerConfig`] is evaluated in the `SurbBalancerController`.
888/// 3. The `SurbBalancerController` applies a new SURB flow rate value using the [`SurbFlowController`].
889///
890/// In the local context, the `SurbFlowController` might simply regulate the egress traffic from the
891/// Session, slowing it down to avoid fast SURB drainage.
892///
893/// In the remote context, the `SurbFlowController` might regulate the flow of non-organic SURBs via
894/// Start protocol's `KeepAlive` messages to deliver additional
895/// SURBs to the counterparty.
896pub struct SurbBalancer<C, E, F> {
897    session_id: SessionId,
898    controller: C,
899    surb_estimator: E,
900    flow_control: F,
901    state: Arc<BalancerStateValues>,
902    last_estimator_state: SimpleSurbFlowEstimator,
903    replies_seen: u64,
904    last_update: std::time::Instant,
905    last_decay: std::time::Instant,
906    was_below_target: bool,
907    /// Whether the previous update ran inside the refill pacing window of a wipe, to notice the one
908    /// in which the window ends.
909    was_pacing: bool,
910    /// DIAGNOSTIC: when the last balancer-state line was emitted, to rate-limit it.
911    last_report: std::time::Instant,
912    /// `produced` over the last `REPORT_LAG`, published to the state at every update.
913    produced_history: ProducedHistory,
914}
915
916impl<C, E, F> SurbBalancer<C, E, F>
917where
918    C: SurbBalancerController + Send + Sync + 'static,
919    E: SurbFlowEstimator + Send + Sync + 'static,
920    F: SurbFlowController + Send + Sync + 'static,
921{
922    pub fn new(
923        session_id: SessionId,
924        mut controller: C,
925        surb_estimator: E,
926        flow_control: F,
927        state: Arc<BalancerStateValues>,
928    ) -> Self {
929        #[cfg(all(feature = "telemetry", not(test)))]
930        {
931            let sid: &str = session_id.as_ref();
932            METRIC_TARGET_ERROR_ESTIMATE.set(&[sid], 0.0);
933            METRIC_CONTROL_OUTPUT.set(&[sid], 0.0);
934        }
935
936        controller.set_target_and_limit(state.controller_bounds());
937
938        Self {
939            surb_estimator,
940            flow_control,
941            controller,
942            session_id,
943            state,
944            last_estimator_state: Default::default(),
945            replies_seen: 0,
946            last_update: std::time::Instant::now(),
947            last_decay: std::time::Instant::now(),
948            was_below_target: true,
949            was_pacing: false,
950            last_report: std::time::Instant::now(),
951            produced_history: ProducedHistory::default(),
952        }
953    }
954
955    /// Computes the next control update and adjusts the [`SurbFlowController`] rate accordingly.
956    #[tracing::instrument(level = "trace", skip_all)]
957    fn update(&mut self) -> u64 {
958        let dt = self.last_update.elapsed();
959
960        // Load the updated current buffer level
961        let mut current = self.state.buffer_level.load(std::sync::atomic::Ordering::Acquire);
962
963        if dt < Duration::from_millis(10) {
964            tracing::debug!("time elapsed since last update is too short, skipping update");
965            return current;
966        }
967
968        self.last_update = std::time::Instant::now();
969
970        // Take a snapshot of the active SURB estimator and calculate the balance change
971        let snapshot = SimpleSurbFlowEstimator::from(&self.surb_estimator);
972        let Some(target_buffer_change) = snapshot.estimated_surb_buffer_change(&self.last_estimator_state) else {
973            tracing::error!("non-monotonic change in SURB estimators");
974            return current;
975        };
976
977        // What a counterparty report arriving before the next update cannot have seen yet: the production
978        // from REPORT_LAG before this update up to it. What comes after it, the next update adds.
979        let produced_before_lag = self.produced_history.record(self.last_update, snapshot.produced);
980        self.state.publish_production(produced_before_lag, snapshot.produced);
981
982        // The estimator counted a consumed SURB since the last tick, so the counterparty was heard, by a
983        // reply or a keep-alive, whether or not any of its packets reached the hooks that record it.
984        if snapshot.consumed > self.last_estimator_state.consumed {
985            self.state.note_heard();
986        }
987
988        // Only replies count towards the reply stream. The keep-alive count is written before `consumed` is
989        // released and the snapshot acquired `consumed` before this read, so the difference never
990        // over-counts replies; its maximum is what is tracked.
991        let replies = snapshot.consumed.saturating_sub(self.state.keep_alives_consumed());
992        if replies > self.replies_seen {
993            self.replies_seen = replies;
994            self.state.note_reply_heard();
995        }
996
997        self.last_estimator_state = snapshot;
998        if self.state.take_counterparty_wiped() {
999            // The counterparty dropped everything it held, so what this tick's production and
1000            // consumption add to the level belongs to the stock that is gone: restart from empty.
1001            tracing::debug!(
1002                believed = current,
1003                delta = target_buffer_change,
1004                "counterparty SURBs were wiped, restarting the level estimate from empty"
1005            );
1006            current = 0;
1007        } else {
1008            current = current.saturating_add_signed(target_buffer_change);
1009        }
1010
1011        // If SURB decaying is enabled, check if the decay window has elapsed
1012        // and calculate the number of SURBs that will be discarded
1013        if let Some(num_decayed_surbs) = self
1014            .state
1015            .surb_decay()
1016            .filter(|(decay_window, _)| &self.last_decay.elapsed() >= decay_window)
1017            .map(|(_, decay_coeff)| (self.controller.bounds().target() as f64 * decay_coeff).round() as u64)
1018        {
1019            current = current.saturating_sub(num_decayed_surbs);
1020            self.last_decay = std::time::Instant::now();
1021            tracing::trace!(num_decayed_surbs, "SURBs were discarded due to automatic decay");
1022        }
1023
1024        // Believing a level the counterparty cannot hold keeps production throttled long after
1025        // the surplus was evicted on arrival, so the estimate is bounded by the store it describes.
1026        let believed = current;
1027        current = self.state.clamp_to_counterparty_capacity(current);
1028        if current != believed {
1029            // Not the configured capacity: the bound applied is `max(capacity, target)`, so name
1030            // the clamped level and the capacity separately rather than conflating them.
1031            tracing::debug!(
1032                believed,
1033                clamped_to = current,
1034                counterparty_capacity = self
1035                    .state
1036                    .counterparty_buffer_capacity
1037                    .load(std::sync::atomic::Ordering::Relaxed),
1038                "counterparty SURB estimate exceeded its store; the surplus was never held"
1039            );
1040        }
1041
1042        self.state
1043            .buffer_level
1044            .store(current, std::sync::atomic::Ordering::Release);
1045
1046        // Invalid SURBs are held but cannot bring a reply home, so the balancer replaces them.
1047        let usable = self.state.usable_level(current);
1048
1049        // Error from the desired target SURB buffer size at counterparty
1050        let error = usable as i64 - self.controller.bounds().target() as i64;
1051
1052        if self.was_below_target && error >= 0 {
1053            tracing::trace!(current, "reached target SURB buffer size");
1054            self.was_below_target = false;
1055        } else if !self.was_below_target && error < 0 {
1056            tracing::trace!(current, "SURB buffer size is below target");
1057            self.was_below_target = true;
1058        }
1059
1060        tracing::trace!(
1061            ?dt,
1062            delta = target_buffer_change,
1063            rate = target_buffer_change as f64 / dt.as_secs_f64(),
1064            current,
1065            error,
1066            "estimated SURB buffer change"
1067        );
1068
1069        // After a wipe the level is far below the target and the PID would command its output limit
1070        // until it is back. Hold the refill to a pace the return paths can carry instead. The PID does
1071        // not run at all while the window lasts: clamping its output would still let it integrate the
1072        // full error for the whole window, and when the window ends it would answer a level at or past
1073        // the target with the ceiling. The refill stops by itself the moment the target is reached. The
1074        // controller's bounds are not touched.
1075        let refill_cap = self.state.pace_refill(dt);
1076        let output = match refill_cap {
1077            Some(cap) => {
1078                if usable >= self.controller.bounds().target() {
1079                    0
1080                } else {
1081                    cap
1082                }
1083            }
1084            None => {
1085                if self.was_pacing {
1086                    // The window just ended. Start the controller from the current error rather than
1087                    // from whatever it had accumulated before the wipe, which no longer describes
1088                    // anything: setting the bounds it already has rebuilds it with its own gains.
1089                    self.controller.set_target_and_limit(self.controller.bounds());
1090                    tracing::debug!(
1091                        current,
1092                        "refill pacing is over, the controller restarts from the current level"
1093                    );
1094                }
1095                let output = self.controller.next_control_output(usable);
1096                if self.state.take_correction_cap() {
1097                    // A report just lowered the believed level. What the controller sees as a deficit
1098                    // is a correction of the estimate, not SURBs the counterparty is missing, and the
1099                    // tick is held to the pacing rate so that it does not answer with a burst.
1100                    let capped = output.min(self.state.pacing_cap());
1101                    tracing::debug!(output, capped, "holding the output after a level correction");
1102                    capped
1103                } else {
1104                    output
1105                }
1106            }
1107        };
1108        self.was_pacing = refill_cap.is_some();
1109        tracing::trace!(output, "next balancer control output for session");
1110
1111        // Both ends run this same loop -- the Entry with the PID driving production, the Exit with
1112        // the proportional controller gating egress -- so one line covers both and the session id
1113        // tells them apart. Rate-limited to one per second so it can run under a full-rate session.
1114        //
1115        // At `debug` rather than `info`: one line per session per second is fine for a handful of
1116        // sessions and is a lot of formatting work for a node carrying many, none of which an
1117        // operator needs to see during healthy operation.
1118        if self.last_report.elapsed() >= Duration::from_secs(1) {
1119            self.last_report = std::time::Instant::now();
1120            tracing::debug!(
1121                session = %self.session_id,
1122                level = current,
1123                invalid = current - usable,
1124                target = self.controller.bounds().target(),
1125                output,
1126                refill_cap = refill_cap.unwrap_or(0),
1127                produced = self.surb_estimator.estimate_surbs_produced(),
1128                consumed = self.surb_estimator.estimate_surbs_consumed(),
1129                distress = self
1130                    .state
1131                    .counterparty_in_surb_distress
1132                    .load(std::sync::atomic::Ordering::Relaxed),
1133                silent = self.state.silence_sustain(),
1134                "surb balancer state"
1135            );
1136        }
1137
1138        self.flow_control.adjust_surb_flow(output as usize);
1139
1140        #[cfg(all(feature = "telemetry", not(test)))]
1141        {
1142            let sid: &str = self.session_id.as_ref();
1143            METRIC_CURRENT_BUFFER.set(&[sid], current as f64);
1144            METRIC_CURRENT_TARGET.set(&[sid], self.controller.bounds().target() as f64);
1145            METRIC_TARGET_ERROR_ESTIMATE.set(&[sid], error as f64);
1146            METRIC_CONTROL_OUTPUT.set(&[sid], output as f64);
1147            METRIC_SURB_RATE.set(&[sid], target_buffer_change as f64 / dt.as_secs_f64());
1148        }
1149
1150        current
1151    }
1152
1153    /// Spawns a new task that performs updates of the given [`SurbBalancer`] at the given `sampling_interval`.
1154    ///
1155    /// If `cfg_feedback` is given, [`SurbBalancerConfig`] can be queried for updates and also updated
1156    /// if the underlying [`SurbBalancerController`] also does target updates.
1157    ///
1158    /// Returns a stream of current estimated buffer levels, and also an `AbortHandle`
1159    /// to terminate the loop. If `abort_reg` was given, the returned `AbortHandle` corresponds
1160    /// to it.
1161    #[instrument(level = "debug", skip(self), fields(session_id = %self.session_id))]
1162    pub fn start_control_loop(
1163        mut self,
1164        sampling_interval: Duration,
1165    ) -> (impl futures::Stream<Item = u64>, AbortHandle) {
1166        let (abort_handle, abort_reg) = AbortHandle::new_pair();
1167
1168        // Start an interval stream at which the balancer will sample and perform updates
1169
1170        // DropAbortable not needed because the stream only generates items when polled
1171        let sampling_stream = futures::stream::Abortable::new(
1172            futures_time::stream::interval(sampling_interval.max(MIN_BALANCER_SAMPLING_INTERVAL).into()),
1173            abort_reg,
1174        );
1175
1176        let balancer_level_capacity = std::env::var("HOPR_INTERNAL_SESSION_BALANCER_LEVEL_CAPACITY")
1177            .ok()
1178            .and_then(|s| s.trim().parse::<usize>().ok())
1179            .filter(|&c| c > 0)
1180            .unwrap_or(32_768);
1181
1182        tracing::debug!(
1183            capacity = balancer_level_capacity,
1184            "Creating session balancer level channel"
1185        );
1186        let (mut level_tx, level_rx) = futures::channel::mpsc::channel(balancer_level_capacity);
1187        hopr_utils::runtime::prelude::spawn(
1188            async move {
1189                pin_mut!(sampling_stream);
1190                while sampling_stream.next().await.is_some() {
1191                    // Check if the balancer controller needs to be reconfigured
1192                    let current_bounds = self.state.controller_bounds();
1193                    if current_bounds != self.controller.bounds() {
1194                        self.controller.set_target_and_limit(current_bounds);
1195                        tracing::debug!(new_cfg = ?self.state.as_config(), "surb balancer has been reconfigured");
1196                    }
1197
1198                    // Perform controller update (this internally samples the SurbFlowEstimator)
1199                    // and send an update about the current level to the outgoing stream.
1200                    // If the other party has closed the stream, we don't care about the update.
1201                    let level = self.update();
1202                    if !level_tx.is_closed()
1203                        && let Err(error) = level_tx.try_send(level)
1204                    {
1205                        tracing::error!(%error, "cannot send balancer level update");
1206                    }
1207                }
1208
1209                tracing::debug!("balancer done");
1210            }
1211            .in_current_span(),
1212        );
1213
1214        (level_rx, abort_handle)
1215    }
1216}
1217
1218#[cfg(test)]
1219mod tests {
1220    use std::sync::{Arc, atomic::AtomicU64};
1221
1222    use hopr_api::types::{crypto_random::Randomizable, internal::prelude::HoprPseudonym};
1223
1224    use super::*;
1225    use crate::balancer::{AtomicSurbFlowEstimator, MockSurbFlowController, pid::PidBalancerController};
1226
1227    #[test]
1228    fn surb_balancer_config_should_be_convertible_to_atomics() {
1229        let cfg = SurbBalancerConfig::default();
1230        let state_data = BalancerStateValues::new(cfg);
1231        assert_eq!(cfg, state_data.as_config());
1232    }
1233
1234    #[test]
1235    fn surb_balancer_config_default_snapshot() {
1236        let cfg = SurbBalancerConfig::default();
1237        insta::assert_debug_snapshot!(cfg);
1238    }
1239
1240    #[test]
1241    fn surb_balancer_config_as_controller_bounds() {
1242        let cfg = SurbBalancerConfig {
1243            target_surb_buffer_size: 1000,
1244            max_surbs_per_sec: 500,
1245            surb_decay: None,
1246        };
1247        let bounds = cfg.as_controller_bounds();
1248        assert_eq!(bounds.target(), 1000);
1249        assert_eq!(bounds.output_limit(), 500);
1250    }
1251
1252    #[test]
1253    fn balancer_state_values_disabled_when_target_is_zero() {
1254        let cfg = SurbBalancerConfig {
1255            target_surb_buffer_size: 0,
1256            max_surbs_per_sec: 0,
1257            surb_decay: None,
1258        };
1259        let state = BalancerStateValues::new(cfg);
1260        assert!(state.is_disabled());
1261    }
1262
1263    #[test]
1264    fn balancer_state_values_enabled_when_target_is_nonzero() {
1265        let state = BalancerStateValues::new(SurbBalancerConfig::default());
1266        assert!(!state.is_disabled());
1267    }
1268
1269    #[test]
1270    fn balancer_state_values_update_propagates_all_fields() {
1271        let state = BalancerStateValues::default();
1272        let cfg = SurbBalancerConfig {
1273            target_surb_buffer_size: 3000,
1274            max_surbs_per_sec: 1500,
1275            surb_decay: Some((Duration::from_secs(30), 0.10)),
1276        };
1277        state.update(&cfg);
1278        assert_eq!(state.as_config(), cfg);
1279        assert_eq!(state.controller_bounds(), cfg.as_controller_bounds());
1280    }
1281
1282    #[test]
1283    fn balancer_state_values_surb_decay_none_maps_to_none() {
1284        let cfg = SurbBalancerConfig {
1285            target_surb_buffer_size: 1000,
1286            max_surbs_per_sec: 500,
1287            surb_decay: None,
1288        };
1289        let state = BalancerStateValues::new(cfg);
1290        assert!(state.surb_decay().is_none());
1291    }
1292
1293    #[test]
1294    fn balancer_state_values_buffer_level_default_is_zero() {
1295        let state = BalancerStateValues::default();
1296        assert_eq!(state.buffer_level(), 0);
1297    }
1298
1299    #[test]
1300    fn balancer_state_values_buffer_level_can_be_updated() {
1301        let state = BalancerStateValues::default();
1302        state.buffer_level.store(42, std::sync::atomic::Ordering::Relaxed);
1303        assert_eq!(state.buffer_level(), 42);
1304    }
1305
1306    /// State with a given target sitting at a given level, for the organic-gate tests below.
1307    fn gate_state(target: u64, buffer_level: u64) -> BalancerStateValues {
1308        let state = BalancerStateValues::new(SurbBalancerConfig {
1309            target_surb_buffer_size: target,
1310            max_surbs_per_sec: 5_000,
1311            ..Default::default()
1312        });
1313        state
1314            .buffer_level
1315            .store(buffer_level, std::sync::atomic::Ordering::Relaxed);
1316        state
1317    }
1318
1319    #[test]
1320    fn organic_surbs_should_be_produced_while_the_counterparty_is_below_target() {
1321        assert_eq!(1, gate_state(100, 99).organic_surbs_per_packet());
1322        assert_eq!(1, gate_state(100, 0).organic_surbs_per_packet());
1323    }
1324
1325    /// The `>=` boundary: at target is already too many, because the next SURB is the one that
1326    /// evicts. Pinned at exactly the target and well past it.
1327    #[test]
1328    fn organic_surbs_should_stop_once_the_counterparty_reaches_its_target() {
1329        assert_eq!(0, gate_state(100, 100).organic_surbs_per_packet());
1330        assert_eq!(0, gate_state(100, 200).organic_surbs_per_packet());
1331    }
1332
1333    /// The safety valve. Our level estimate counts SURBs as delivered when they are *sent*, so
1334    /// forward-path loss inflates it — the counterparty's own word about its supply has to win over
1335    /// an estimate that can be wrong in exactly that direction.
1336    #[test]
1337    fn organic_surbs_should_resume_at_one_when_the_counterparty_signals_distress() {
1338        let state = gate_state(100, 200);
1339        assert_eq!(0, state.organic_surbs_per_packet(), "precondition: gate is closed");
1340
1341        state.observe_counterparty_signals(PacketSignal::SurbDistress.into());
1342        assert_eq!(1, state.organic_surbs_per_packet());
1343    }
1344
1345    /// `OutOfSurbs` is `0b11` and `SurbDistress` is `0b01`, so the former *contains* the latter.
1346    /// Matching on equality instead of containment would ignore the more severe of the two signals
1347    /// and leave production shut off for a counterparty that has nothing left to reply with.
1348    #[test]
1349    fn out_of_surbs_should_count_as_distress() {
1350        let state = gate_state(100, 200);
1351        state.observe_counterparty_signals(PacketSignal::OutOfSurbs.into());
1352        assert_eq!(1, state.organic_surbs_per_packet());
1353    }
1354
1355    /// Distress is not sticky once the counterparty recovers: it recomputes both signals per return
1356    /// packet and strips them when its pool is healthy, so the next such packet re-arms the gate.
1357    #[test]
1358    fn a_recovered_counterparty_should_clear_distress() {
1359        let state = gate_state(100, 200);
1360        state.observe_counterparty_signals(PacketSignal::OutOfSurbs.into());
1361        assert_eq!(1, state.organic_surbs_per_packet(), "precondition: distress is set");
1362
1363        state.observe_counterparty_signals(PacketSignals::default());
1364        assert_eq!(0, state.organic_surbs_per_packet());
1365    }
1366
1367    /// A zero target means "no balancing", not "the target is already met". Nothing rejects such a
1368    /// config, so without the explicit branch `level >= 0` would hold forever and starve the session
1369    /// of organic SURBs permanently — while a PID with a zero output limit produces none either.
1370    #[test]
1371    fn a_disabled_balancer_should_keep_producing_organic_surbs() {
1372        let state = gate_state(0, 0);
1373        assert!(state.is_disabled(), "precondition: a zero target disables balancing");
1374        assert_eq!(1, state.organic_surbs_per_packet());
1375    }
1376
1377    /// Sessions opened without SURB management hold a default state and route their outgoing packets
1378    /// through the same policy as balanced ones, relying on it to answer 1. A `Default` that ever
1379    /// gained a non-zero target would silently stop those sessions producing organic SURBs, with
1380    /// nothing at the call site to show why.
1381    #[test]
1382    fn a_default_state_should_keep_producing_organic_surbs() {
1383        assert_eq!(1, BalancerStateValues::default().organic_surbs_per_packet());
1384    }
1385
1386    #[test]
1387    fn balancer_state_values_from_config() {
1388        let cfg = SurbBalancerConfig {
1389            target_surb_buffer_size: 5000,
1390            max_surbs_per_sec: 2500,
1391            surb_decay: Some((Duration::from_secs(60), 0.05)),
1392        };
1393        let state: BalancerStateValues = cfg.into();
1394        assert_eq!(state.as_config(), cfg);
1395    }
1396
1397    #[test]
1398    fn balancer_state_values_decay_zero_duration_should_map_to_none() {
1399        let cfg = SurbBalancerConfig {
1400            surb_decay: Some((Duration::ZERO, 0.10)),
1401            ..Default::default()
1402        };
1403        let state = BalancerStateValues::new(cfg);
1404        assert!(
1405            state.surb_decay().is_none(),
1406            "zero duration decay should be filtered out"
1407        );
1408    }
1409
1410    #[test]
1411    fn balancer_state_values_decay_zero_percent_should_map_to_none() {
1412        let cfg = SurbBalancerConfig {
1413            surb_decay: Some((Duration::from_secs(60), 0.0)),
1414            ..Default::default()
1415        };
1416        let state = BalancerStateValues::new(cfg);
1417        assert!(
1418            state.surb_decay().is_none(),
1419            "zero percent decay should be filtered out"
1420        );
1421    }
1422
1423    #[test]
1424    fn balancer_state_values_decay_should_clamp_above_one() {
1425        let cfg = SurbBalancerConfig {
1426            surb_decay: Some((Duration::from_secs(1), 1.5)), // > 1.0 should be clamped
1427            ..Default::default()
1428        };
1429        let state = BalancerStateValues::new(cfg);
1430        let (_, pct) = state.surb_decay().expect("decay should be present");
1431        assert!((pct - 1.0).abs() < f64::EPSILON, "percentage should be clamped to 1.0");
1432    }
1433
1434    #[test_log::test]
1435    fn surb_balancer_should_start_increase_level_when_below_target() {
1436        let production_rate = Arc::new(AtomicU64::new(0));
1437        let consumption_rate = 100;
1438        let steps = 3;
1439        let step_duration = std::time::Duration::from_millis(1000);
1440
1441        let mut controller = MockSurbFlowController::new();
1442        let production_rate_clone = production_rate.clone();
1443        controller
1444            .expect_adjust_surb_flow()
1445            .times(steps)
1446            .with(mockall::predicate::ge(100))
1447            .returning(move |r| {
1448                production_rate_clone.store(r as u64, std::sync::atomic::Ordering::Relaxed);
1449            });
1450
1451        let surb_estimator = AtomicSurbFlowEstimator::default();
1452        let mut balancer = SurbBalancer::new(
1453            HoprPseudonym::random(),
1454            PidBalancerController::default(),
1455            surb_estimator.clone(),
1456            controller,
1457            Arc::new(
1458                SurbBalancerConfig {
1459                    target_surb_buffer_size: 5_000,
1460                    max_surbs_per_sec: 2500,
1461                    surb_decay: None,
1462                }
1463                .into(),
1464            ),
1465        );
1466
1467        let mut last_update = 0;
1468        for i in 0..steps {
1469            std::thread::sleep(step_duration);
1470            surb_estimator.produced.fetch_add(
1471                production_rate.load(std::sync::atomic::Ordering::Relaxed) * step_duration.as_secs(),
1472                std::sync::atomic::Ordering::Relaxed,
1473            );
1474            surb_estimator.consumed.fetch_add(
1475                consumption_rate * step_duration.as_secs(),
1476                std::sync::atomic::Ordering::Relaxed,
1477            );
1478
1479            let next_update = balancer.update();
1480            assert!(
1481                i == 0 || next_update > last_update,
1482                "{next_update} should be greater than {last_update}"
1483            );
1484            last_update = next_update;
1485        }
1486    }
1487
1488    #[test_log::test]
1489    fn surb_balancer_should_start_decrease_level_when_above_target() {
1490        let production_rate = Arc::new(AtomicU64::new(11_000));
1491        let consumption_rate = 100;
1492        let steps = 3;
1493        let step_duration = std::time::Duration::from_millis(1000);
1494
1495        let mut controller = MockSurbFlowController::new();
1496        let production_rate_clone = production_rate.clone();
1497        controller
1498            .expect_adjust_surb_flow()
1499            .times(steps)
1500            .with(mockall::predicate::ge(0))
1501            .returning(move |r| {
1502                production_rate_clone.store(r as u64, std::sync::atomic::Ordering::Relaxed);
1503            });
1504
1505        let surb_estimator = AtomicSurbFlowEstimator::default();
1506        let mut balancer = SurbBalancer::new(
1507            HoprPseudonym::random(),
1508            PidBalancerController::default(),
1509            surb_estimator.clone(),
1510            controller,
1511            Arc::new(
1512                SurbBalancerConfig {
1513                    surb_decay: None,
1514                    ..Default::default()
1515                }
1516                .into(),
1517            ),
1518        );
1519
1520        let mut last_update = 0;
1521        for i in 0..steps {
1522            std::thread::sleep(step_duration);
1523            surb_estimator.produced.fetch_add(
1524                production_rate.load(std::sync::atomic::Ordering::Relaxed) * step_duration.as_secs(),
1525                std::sync::atomic::Ordering::Relaxed,
1526            );
1527            surb_estimator.consumed.fetch_add(
1528                consumption_rate * step_duration.as_secs(),
1529                std::sync::atomic::Ordering::Relaxed,
1530            );
1531
1532            let next_update = balancer.update();
1533            assert!(
1534                i == 0 || next_update < last_update,
1535                "{next_update} should be greater than {last_update}"
1536            );
1537            last_update = next_update;
1538        }
1539    }
1540
1541    /// A balancer whose production follows its own control output, as it does in a live Session.
1542    ///
1543    /// Returns the balancer, the shared estimator and the latest control output. Production must be
1544    /// fed back rather than held constant: with production pinned to consumption the buffer never
1545    /// fills, maximum output is the correct answer, and every phase of the test reads the same.
1546    #[allow(clippy::type_complexity)]
1547    fn balancer_with_feedback(
1548        cfg: SurbBalancerConfig,
1549    ) -> (
1550        SurbBalancer<PidBalancerController, AtomicSurbFlowEstimator, MockSurbFlowController>,
1551        AtomicSurbFlowEstimator,
1552        Arc<BalancerStateValues>,
1553        Arc<AtomicU64>,
1554    ) {
1555        let output = Arc::new(AtomicU64::new(0));
1556        let output_clone = output.clone();
1557        let mut controller = MockSurbFlowController::new();
1558        controller.expect_adjust_surb_flow().returning(move |r| {
1559            output_clone.store(r as u64, std::sync::atomic::Ordering::Relaxed);
1560        });
1561
1562        let surb_estimator = AtomicSurbFlowEstimator::default();
1563        let state: Arc<BalancerStateValues> = Arc::new(cfg.into());
1564        let balancer = SurbBalancer::new(
1565            HoprPseudonym::random(),
1566            PidBalancerController::default(),
1567            surb_estimator.clone(),
1568            controller,
1569            state.clone(),
1570        );
1571
1572        (balancer, surb_estimator, state, output)
1573    }
1574
1575    /// One sampling interval: mint at the rate last commanded, and consume `consumed` of them.
1576    fn tick(
1577        balancer: &mut SurbBalancer<PidBalancerController, AtomicSurbFlowEstimator, MockSurbFlowController>,
1578        surb_estimator: &AtomicSurbFlowEstimator,
1579        output: &AtomicU64,
1580        consumed: u64,
1581    ) {
1582        let step = Duration::from_millis(50);
1583        std::thread::sleep(step);
1584
1585        let minted = output.load(std::sync::atomic::Ordering::Relaxed) * step.as_millis() as u64 / 1000;
1586        surb_estimator
1587            .produced
1588            .fetch_add(minted, std::sync::atomic::Ordering::Relaxed);
1589        surb_estimator
1590            .consumed
1591            .fetch_add(consumed, std::sync::atomic::Ordering::Relaxed);
1592        balancer.update();
1593    }
1594
1595    /// SURBs the counterparty spends per interval while it is answering normally.
1596    const REPLIES_PER_TICK: u64 = 40;
1597
1598    /// Drives a balancer through a healthy stretch, then through one where no reply comes back.
1599    ///
1600    /// Returns the control output at the end of each stretch.
1601    fn drive_until_replies_stop(cfg: SurbBalancerConfig) -> (u64, u64) {
1602        let (mut balancer, surb_estimator, _state, output) = balancer_with_feedback(cfg);
1603
1604        for _ in 0..40 {
1605            tick(&mut balancer, &surb_estimator, &output, REPLIES_PER_TICK);
1606        }
1607        let healthy = output.load(std::sync::atomic::Ordering::Relaxed);
1608
1609        // Replies stop while production continues.
1610        for _ in 0..20 {
1611            tick(&mut balancer, &surb_estimator, &output, 0);
1612        }
1613
1614        (healthy, output.load(std::sync::atomic::Ordering::Relaxed))
1615    }
1616
1617    fn small_target_config() -> SurbBalancerConfig {
1618        SurbBalancerConfig {
1619            // Small enough that the healthy phase actually reaches the setpoint and backs off
1620            // within the test's tick budget; saturated-at-maximum makes every phase read alike.
1621            target_surb_buffer_size: 1_000,
1622            max_surbs_per_sec: 2_500,
1623            surb_decay: None,
1624        }
1625    }
1626
1627    /// A peer with nothing to say really is filling up, so throttling it is correct.
1628    ///
1629    /// This is the case that makes the estimate impossible to fix locally: it is byte-for-byte the
1630    /// same observation as a dead return path.
1631    #[test_log::test]
1632    fn surb_balancer_should_throttle_when_a_quiet_counterparty_stops_consuming() {
1633        let (healthy, quiet) = drive_until_replies_stop(small_target_config());
1634
1635        assert!(healthy > 0, "a balanced session must keep minting");
1636        assert!(
1637            quiet < healthy,
1638            "an idle counterparty accumulates SURBs, so production must back off: healthy={healthy}/s, idle={quiet}/s"
1639        );
1640    }
1641
1642    /// The estimate must not claim a level the counterparty's store could never have held.
1643    ///
1644    /// `produced - consumed` only decreases when a reply arrives, so production that nobody is
1645    /// seen to consume accumulates without bound. The counterparty's store is a ring buffer that
1646    /// evicts the oldest entry on overflow, so everything above its capacity was discarded on
1647    /// arrival. Measured during a live outage: 51 917 believed against a 15 000-entry store, which
1648    /// keeps the controller throttling against a buffer that is in fact draining.
1649    #[test_log::test]
1650    fn surb_balancer_should_not_believe_a_level_the_counterparty_cannot_hold() {
1651        const CAPACITY: u64 = 2_000;
1652
1653        let cfg = small_target_config();
1654        let (mut balancer, surb_estimator, state, output) = balancer_with_feedback(cfg);
1655        state.set_counterparty_buffer_capacity(CAPACITY);
1656
1657        for _ in 0..40 {
1658            tick(&mut balancer, &surb_estimator, &output, REPLIES_PER_TICK);
1659        }
1660
1661        // Replies stop, while production continues from a source the controller does not drive --
1662        // keep-alives mint on their own schedule, which is how the live estimate ran away.
1663        for _ in 0..20 {
1664            surb_estimator
1665                .produced
1666                .fetch_add(500, std::sync::atomic::Ordering::Relaxed);
1667            tick(&mut balancer, &surb_estimator, &output, 0);
1668        }
1669
1670        let believed = state.buffer_level.load(std::sync::atomic::Ordering::Relaxed);
1671        assert!(
1672            believed <= CAPACITY,
1673            "the estimate must be bounded by the counterparty's store: believed {believed} against a {CAPACITY}-entry \
1674             buffer"
1675        );
1676    }
1677
1678    /// The bound must not become the setpoint: a store larger than the target changes nothing.
1679    #[test_log::test]
1680    fn surb_balancer_should_leave_a_healthy_session_untouched_by_the_capacity_bound() {
1681        let cfg = small_target_config();
1682        let (mut balancer, surb_estimator, state, output) = balancer_with_feedback(cfg);
1683        state.set_counterparty_buffer_capacity(cfg.target_surb_buffer_size * 10);
1684
1685        for _ in 0..40 {
1686            tick(&mut balancer, &surb_estimator, &output, REPLIES_PER_TICK);
1687        }
1688
1689        let level = state.buffer_level.load(std::sync::atomic::Ordering::Relaxed);
1690        assert!(
1691            level >= cfg.target_surb_buffer_size / 2,
1692            "a capacity well above the target must not hold the session below its setpoint: level {level}, target {}",
1693            cfg.target_surb_buffer_size
1694        );
1695    }
1696
1697    /// Exit side, common case: with evictions counted, the reported level equals what the store
1698    /// actually holds -- it rises only to the real capacity during an overflow, and falls back to
1699    /// empty as the overflow drains, rather than staying inflated by the discarded surplus.
1700    ///
1701    /// The sibling test above bounds an eviction-blind estimate with the clamp; this one asserts the
1702    /// stronger property the eviction term buys: the level *tracks* occupancy instead of merely being
1703    /// capped by it.
1704    #[test_log::test]
1705    fn surb_balancer_level_tracks_true_occupancy_once_evictions_are_counted() {
1706        use std::sync::atomic::Ordering;
1707
1708        const CAPACITY: u64 = 2_000;
1709        let cfg = small_target_config();
1710        let (mut balancer, est, state, _output) = balancer_with_feedback(cfg);
1711        state.set_counterparty_buffer_capacity(CAPACITY);
1712
1713        // Overflow the store: each receive is mirrored into the estimator the way the Exit rx does --
1714        // the batch into `produced`, the overflow into `evicted`.
1715        let mut occupancy = 0u64;
1716        for _ in 0..10 {
1717            let batch = 500u64;
1718            let evicted = (occupancy + batch).saturating_sub(CAPACITY);
1719            occupancy = (occupancy + batch).min(CAPACITY);
1720            est.produced.fetch_add(batch, Ordering::Relaxed);
1721            est.evicted.fetch_add(evicted, Ordering::Relaxed);
1722            std::thread::sleep(Duration::from_millis(12));
1723            balancer.update();
1724        }
1725        assert_eq!(occupancy, CAPACITY, "the model store is full");
1726        assert_eq!(
1727            state.buffer_level.load(Ordering::Relaxed),
1728            CAPACITY,
1729            "the level equals the full store, not the {} SURBs received",
1730            10 * 500
1731        );
1732
1733        // Drain the store: every spent SURB leaves the buffer.
1734        for _ in 0..(CAPACITY / 200) {
1735            est.consumed.fetch_add(200, Ordering::Relaxed);
1736            occupancy -= 200;
1737            std::thread::sleep(Duration::from_millis(12));
1738            balancer.update();
1739        }
1740        assert_eq!(occupancy, 0, "the model store is empty");
1741        assert_eq!(
1742            state.buffer_level.load(Ordering::Relaxed),
1743            0,
1744            "the level falls back to empty as the store drains; the evicted surplus is not held forever"
1745        );
1746    }
1747
1748    /// Exit side of the capacity<target case: when the store is smaller than the target, an accurate
1749    /// level plateaus at the real capacity and never reaches the target. That plateau is the input the
1750    /// Entry infers its counterparty's capacity from (see
1751    /// `a_plateau_below_target_infers_the_counterparty_capacity`), which is what stops the Entry
1752    /// minting into a full store below its target.
1753    #[test_log::test]
1754    fn surb_balancer_level_plateaus_at_capacity_when_store_is_smaller_than_target() {
1755        use std::sync::atomic::Ordering;
1756
1757        const CAPACITY: u64 = 500;
1758        let cfg = SurbBalancerConfig {
1759            target_surb_buffer_size: 2_000,
1760            max_surbs_per_sec: 2_500,
1761            surb_decay: None,
1762        };
1763        let (mut balancer, est, state, _output) = balancer_with_feedback(cfg);
1764        state.set_counterparty_buffer_capacity(CAPACITY);
1765
1766        let mut occupancy = 0u64;
1767        for _ in 0..20 {
1768            let batch = 200u64;
1769            let evicted = (occupancy + batch).saturating_sub(CAPACITY);
1770            occupancy = (occupancy + batch).min(CAPACITY);
1771            est.produced.fetch_add(batch, Ordering::Relaxed);
1772            est.evicted.fetch_add(evicted, Ordering::Relaxed);
1773            std::thread::sleep(Duration::from_millis(12));
1774            balancer.update();
1775        }
1776
1777        let believed = state.buffer_level.load(Ordering::Relaxed);
1778        assert_eq!(occupancy, CAPACITY);
1779        assert_eq!(
1780            believed, CAPACITY,
1781            "the level reflects the real store, capped at its true capacity"
1782        );
1783        assert!(
1784            believed < cfg.target_surb_buffer_size,
1785            "an accurate level cannot reach a target above the store's capacity: {believed} < {}",
1786            cfg.target_surb_buffer_size
1787        );
1788    }
1789
1790    /// A state at the given target with no capacity inferred yet, ready to receive reported levels.
1791    fn capacity_probe_state(target: u64) -> BalancerStateValues {
1792        BalancerStateValues::new(SurbBalancerConfig {
1793            target_surb_buffer_size: target,
1794            ..Default::default()
1795        })
1796    }
1797
1798    /// Feed a level that repeats (a plateau) below target with no distress: after the threshold, the
1799    /// real capacity is inferred and organic production stops there instead of chasing an unreachable
1800    /// target.
1801    #[test]
1802    fn a_plateau_below_target_infers_the_counterparty_capacity() {
1803        use std::sync::atomic::Ordering;
1804
1805        const TARGET: u64 = 2_000;
1806        const CAPACITY: u64 = 500;
1807        let state = capacity_probe_state(TARGET);
1808
1809        // Fill up to the store's ceiling.
1810        for level in [100, 300, CAPACITY] {
1811            state.observe_reported_level(level);
1812            assert_eq!(
1813                1,
1814                state.organic_surbs_per_packet(),
1815                "still below capacity, keep minting"
1816            );
1817        }
1818
1819        // The level now plateaus at the ceiling: the store is full below the target.
1820        for _ in 0..CAPACITY_PLATEAU_THRESHOLD {
1821            state.observe_reported_level(CAPACITY);
1822        }
1823
1824        assert_eq!(
1825            CAPACITY,
1826            state.observed_counterparty_capacity.load(Ordering::Relaxed),
1827            "the plateau level is inferred as the real capacity"
1828        );
1829        assert_eq!(
1830            0,
1831            state.organic_surbs_per_packet(),
1832            "production stops at the real capacity, not the unreachable target"
1833        );
1834    }
1835
1836    /// One flat report is churn, not a plateau: the capacity must not be inferred from it.
1837    #[test]
1838    fn a_single_flat_report_does_not_infer_capacity() {
1839        use std::sync::atomic::Ordering;
1840
1841        let state = capacity_probe_state(2_000);
1842        state.observe_reported_level(500);
1843        state.observe_reported_level(500);
1844
1845        assert_eq!(0, state.observed_counterparty_capacity.load(Ordering::Relaxed));
1846        assert_eq!(
1847            1,
1848            state.organic_surbs_per_packet(),
1849            "one flat sample must not stop production"
1850        );
1851    }
1852
1853    /// A level that rises again resets the plateau: a counterparty still accepting SURBs is not full.
1854    #[test]
1855    fn a_rising_level_resets_the_plateau() {
1856        use std::sync::atomic::Ordering;
1857
1858        let state = capacity_probe_state(2_000);
1859        state.observe_reported_level(500);
1860        state.observe_reported_level(500);
1861        // A rise before the threshold clears the count.
1862        state.observe_reported_level(600);
1863        state.observe_reported_level(600);
1864
1865        assert_eq!(
1866            0,
1867            state.observed_counterparty_capacity.load(Ordering::Relaxed),
1868            "the plateau restarted at the higher level, so nothing is inferred yet"
1869        );
1870    }
1871
1872    /// Distress discards an inferred capacity: a counterparty short of SURBs is not full, so the Entry
1873    /// must resume producing toward the full target.
1874    #[test]
1875    fn distress_discards_the_inferred_capacity() {
1876        use std::sync::atomic::Ordering;
1877
1878        const CAPACITY: u64 = 500;
1879        let state = capacity_probe_state(2_000);
1880        for _ in 0..CAPACITY_PLATEAU_THRESHOLD + 1 {
1881            state.observe_reported_level(CAPACITY);
1882        }
1883        assert_eq!(CAPACITY, state.observed_counterparty_capacity.load(Ordering::Relaxed));
1884
1885        state.observe_counterparty_signals(PacketSignal::SurbDistress.into());
1886
1887        assert_eq!(
1888            0,
1889            state.observed_counterparty_capacity.load(Ordering::Relaxed),
1890            "distress clears the inferred capacity"
1891        );
1892        assert_eq!(1, state.organic_surbs_per_packet(), "and production resumes");
1893    }
1894
1895    /// After inference, the counterparty draining and refilling toward the inferred capacity must not
1896    /// clear it -- only a level rising *above* the inferred capacity means the store can hold more.
1897    #[test]
1898    fn refilling_below_the_inferred_capacity_keeps_it_but_a_higher_level_clears_it() {
1899        use std::sync::atomic::Ordering;
1900
1901        const CAPACITY: u64 = 500;
1902        let state = capacity_probe_state(2_000);
1903        for _ in 0..CAPACITY_PLATEAU_THRESHOLD + 1 {
1904            state.observe_reported_level(CAPACITY);
1905        }
1906        assert_eq!(CAPACITY, state.observed_counterparty_capacity.load(Ordering::Relaxed));
1907
1908        // Drain and refill toward the cap: the inference stands.
1909        state.observe_reported_level(300);
1910        state.observe_reported_level(450);
1911        assert_eq!(
1912            CAPACITY,
1913            state.observed_counterparty_capacity.load(Ordering::Relaxed),
1914            "a refill up to the inferred capacity does not forget it"
1915        );
1916
1917        // A level above the inferred capacity means the store grew: re-probe.
1918        state.observe_reported_level(CAPACITY + 200);
1919        assert_eq!(
1920            0,
1921            state.observed_counterparty_capacity.load(Ordering::Relaxed),
1922            "a level above the inferred capacity forgets it"
1923        );
1924    }
1925
1926    /// Reproduces the balancer state seen in the `gnosis_vpn-20260824-101952.log` outage (India
1927    /// exit `0x1062..8106`): under sustained return-path loss the entry's counterparty-buffer
1928    /// estimate (`produced - consumed`, clamped to the store) pins at/above target because
1929    /// `consumed` stops advancing -- the replies that would retire it never arrive -- and the PID
1930    /// winds production down to zero. The live `surb balancer state` lines read
1931    /// `level=15000 target=9766 output=0 degraded=false` for the whole 15-minute session.
1932    ///
1933    /// Scope: this guards only the entry-side balancer behaviour the logs show directly -- the
1934    /// estimate pinning and the output collapse. It deliberately makes no claim about the exit's
1935    /// real SURB store or whether the counterparty starves. The estimate is not a proxy for that
1936    /// store: `update` documents that `produced - consumed` "reads as a filling buffer precisely
1937    /// when it is emptying" during return-path loss, so a pinned `level` says nothing about how
1938    /// many SURBs the exit actually holds. Whether the throttle-to-zero contributes to the outage
1939    /// is a separate question this test does not address; it only nails down the observed state so
1940    /// a change in it is noticed.
1941    #[test_log::test]
1942    fn surb_balancer_pins_estimate_and_collapses_output_under_return_path_loss() {
1943        use std::sync::atomic::Ordering;
1944
1945        // The live 15 000-entry counterparty store the estimate is clamped to.
1946        const COUNTERPARTY_CAPACITY: u64 = 15_000;
1947
1948        // The configuration a gnosis_vpn tunnel session actually ran with: SURB balancing on.
1949        let cfg = small_target_config();
1950        let (mut balancer, surb_estimator, state, output) = balancer_with_feedback(cfg);
1951        state.set_counterparty_buffer_capacity(COUNTERPARTY_CAPACITY);
1952
1953        // Healthy stretch: replies arrive, and the buffer holds at the setpoint.
1954        for _ in 0..40 {
1955            tick(&mut balancer, &surb_estimator, &output, REPLIES_PER_TICK);
1956        }
1957
1958        // Replies stop arriving (`consumed` no longer advances). The entry keeps minting what its
1959        // controller last commanded; with `consumed` frozen the estimate climbs to the store cap
1960        // and the PID drives the commanded rate down to zero.
1961        let step = Duration::from_millis(50);
1962        for _ in 0..60 {
1963            std::thread::sleep(step);
1964            let minted = output.load(Ordering::Relaxed) * step.as_millis() as u64 / 1000;
1965            surb_estimator.produced.fetch_add(minted, Ordering::Relaxed);
1966            // `consumed` stays flat: nothing comes back over the dead return path.
1967            balancer.update();
1968        }
1969
1970        // The field `level >= target`: the estimate is pinned at/above target.
1971        assert!(
1972            state.buffer_level.load(Ordering::Relaxed) >= cfg.target_surb_buffer_size,
1973            "the counterparty-buffer estimate must pin at/above target while replies are lost, reproducing the field \
1974             `level >= target` state: level={}",
1975            state.buffer_level.load(Ordering::Relaxed)
1976        );
1977
1978        // The field `output=0`: production has collapsed to zero.
1979        assert_eq!(
1980            output.load(Ordering::Relaxed),
1981            0,
1982            "production must collapse to zero once the estimate pins above target, reproducing the field `output=0` \
1983             state"
1984        );
1985    }
1986
1987    #[test_log::test(tokio::test)]
1988    async fn surb_balancer_should_start_decrease_level_when_above_target_and_decay_enabled() {
1989        const NUM_STEPS: usize = 5;
1990        let session_id = HoprPseudonym::random();
1991        let cfg = SurbBalancerConfig {
1992            target_surb_buffer_size: 5_000,
1993            max_surbs_per_sec: 2500,
1994            surb_decay: Some((Duration::from_millis(200), 0.05)),
1995        };
1996
1997        let mut mock_flow_ctl = MockSurbFlowController::new();
1998        mock_flow_ctl
1999            .expect_adjust_surb_flow()
2000            .times(NUM_STEPS)
2001            .returning(|_| ());
2002
2003        let balancer = SurbBalancer::new(
2004            session_id,
2005            PidBalancerController::default(),
2006            SimpleSurbFlowEstimator::default(),
2007            mock_flow_ctl,
2008            Arc::new(cfg.into()),
2009        );
2010
2011        balancer
2012            .state
2013            .buffer_level
2014            .store(5000, std::sync::atomic::Ordering::Relaxed);
2015
2016        let (stream, handle) = balancer.start_control_loop(Duration::from_millis(100));
2017        let levels = stream.take(NUM_STEPS).collect::<Vec<_>>().await;
2018        handle.abort();
2019
2020        assert_eq!(levels.len(), NUM_STEPS);
2021        assert!(
2022            levels.windows(2).all(|w| w[1] <= w[0]),
2023            "buffer levels should be monotonic non-increasing: {levels:?}"
2024        );
2025        assert!(
2026            levels.last().is_some_and(|last| *last < 5_000),
2027            "expected at least one decay step: {levels:?}"
2028        );
2029    }
2030
2031    /// SURBs through a relayer judged dead are held, and reported, but cannot bring a reply home,
2032    /// so a counterparty above target on paper is below it in fact.
2033    #[test]
2034    fn organic_surbs_should_be_produced_while_invalid_surbs_hide_a_shortfall() {
2035        let state = gate_state(100, 150);
2036        assert_eq!(0, state.organic_surbs_per_packet(), "precondition: above target");
2037        state.set_invalid_surbs(80, 0.9);
2038        assert_eq!(1, state.organic_surbs_per_packet(), "80 of 150 invalid");
2039        state.set_invalid_surbs(80, 0.2);
2040        assert_eq!(0, state.organic_surbs_per_packet(), "the share caps it at 30");
2041        state.set_invalid_surbs(10_000, 0.5);
2042        assert_eq!(
2043            1,
2044            state.organic_surbs_per_packet(),
2045            "the count no more than the share of 75"
2046        );
2047        assert_eq!(150, state.buffer_level(), "the held level itself is unchanged");
2048        state.set_invalid_surbs(u64::MAX, 1.0);
2049        assert_eq!(1, state.organic_surbs_per_packet(), "a saturated count writes off all");
2050        state.set_invalid_surbs(0, 0.0);
2051        assert_eq!(0, state.organic_surbs_per_packet(), "clearing restores the held level");
2052    }
2053
2054    /// The Exit counts a return packet's SURB as it hands the packet on, and gives it back when routing
2055    /// resolution drops the packet for want of one, a sample or more later. While the level is at zero
2056    /// the count saturates away, so a refund the balancer added back would be a SURB nobody holds,
2057    /// carried into the egress rate and the level reports. The held count, which saturates only when it
2058    /// is read, takes the refund; the level does not.
2059    #[test]
2060    fn a_refund_should_not_raise_the_balancer_level() {
2061        use hopr_protocol_app::prelude::SurbRefund;
2062
2063        use crate::balancer::{SurbFlowEstimator, simple::SimpleBalancerController};
2064
2065        let mut controller = MockSurbFlowController::new();
2066        controller.expect_adjust_surb_flow().return_const(());
2067        let surb_estimator = AtomicSurbFlowEstimator::default();
2068        let state = Arc::new(BalancerStateValues::new(SurbBalancerConfig {
2069            target_surb_buffer_size: 100,
2070            surb_decay: None,
2071            ..Default::default()
2072        }));
2073        let mut balancer = SurbBalancer::new(
2074            HoprPseudonym::random(),
2075            SimpleBalancerController::default(),
2076            surb_estimator.clone(),
2077            controller,
2078            state.clone(),
2079        );
2080        let sample = |balancer: &mut SurbBalancer<_, _, _>| {
2081            std::thread::sleep(Duration::from_millis(20));
2082            balancer.update()
2083        };
2084
2085        // The Exit holds nothing; a level report goes out regardless and is counted.
2086        surb_estimator
2087            .consumed
2088            .fetch_add(1, std::sync::atomic::Ordering::Relaxed);
2089        let refund = SurbRefund::to(surb_estimator.refunded.clone());
2090        assert_eq!(0, sample(&mut balancer), "the count saturates at an empty level");
2091
2092        refund.give_back();
2093        assert_eq!(
2094            0,
2095            sample(&mut balancer),
2096            "the refund adds no SURB the Exit does not hold"
2097        );
2098        assert_eq!(0, surb_estimator.saturating_diff());
2099
2100        surb_estimator
2101            .produced
2102            .fetch_add(3, std::sync::atomic::Ordering::Relaxed);
2103        assert_eq!(3, sample(&mut balancer), "SURBs that do arrive count as before");
2104        assert_eq!(
2105            3,
2106            surb_estimator.saturating_diff(),
2107            "and the starved count no longer holds the held count one low"
2108        );
2109    }
2110    type TestBalancer = SurbBalancer<PidBalancerController, AtomicSurbFlowEstimator, MockSurbFlowController>;
2111
2112    /// One sampling interval of `dt`, without waiting for it: the balancer's clock is wound back instead.
2113    fn tick_for(balancer: &mut TestBalancer, dt: Duration) {
2114        balancer.last_update = std::time::Instant::now()
2115            .checked_sub(dt)
2116            .expect("monotonic clock too young");
2117        balancer.update();
2118    }
2119
2120    /// The configuration of a session at the client's usual target, against the usual mint ceiling.
2121    fn paced_refill_config() -> SurbBalancerConfig {
2122        SurbBalancerConfig {
2123            target_surb_buffer_size: 7_000,
2124            max_surbs_per_sec: 5_000,
2125            surb_decay: None,
2126        }
2127    }
2128
2129    /// A wipe means the counterparty holds nothing, whatever the estimate says, and the estimate must
2130    /// say so at the next update: not the update that was already running, nor the production that was
2131    /// in flight when the SURB generation advanced, and not a report from the counterparty that has
2132    /// not seen the new generation yet may bring it back.
2133    #[test_log::test]
2134    fn a_wipe_should_restart_the_estimate_from_empty_and_survive_the_next_tick() {
2135        use std::sync::atomic::Ordering::Relaxed;
2136
2137        let (mut balancer, estimator, state, _output) = balancer_with_feedback(paced_refill_config());
2138        let step = Duration::from_millis(50);
2139
2140        state.observe_reported_level(7_000);
2141        tick_for(&mut balancer, step);
2142        assert_eq!(
2143            7_000,
2144            state.buffer_level(),
2145            "precondition: the counterparty is at target"
2146        );
2147
2148        // 300 SURBs were minted for the old generation just before it advanced.
2149        estimator.produced.fetch_add(300, Relaxed);
2150        state.on_counterparty_wiped();
2151        assert_eq!(0, state.buffer_level(), "the level is reset at once");
2152
2153        // The counterparty reports what it held until its first SURB of the new generation lands.
2154        state.observe_reported_level(7_000);
2155        assert_eq!(0, state.buffer_level(), "a report above the believed level is dropped");
2156
2157        // An update that was already running writes back the level it loaded before the reset.
2158        state.buffer_level.store(7_000, Relaxed);
2159        tick_for(&mut balancer, step);
2160        assert_eq!(
2161            0,
2162            state.buffer_level(),
2163            "the stale level and the old generation's production must not survive the first update"
2164        );
2165
2166        // From then on the estimate counts what is minted for the new generation, and is not reset again.
2167        estimator.produced.fetch_add(200, Relaxed);
2168        tick_for(&mut balancer, step);
2169        assert_eq!(200, state.buffer_level());
2170        estimator.consumed.fetch_add(50, Relaxed);
2171        tick_for(&mut balancer, step);
2172        assert_eq!(150, state.buffer_level(), "the reset is one-shot");
2173    }
2174
2175    /// The counterparty keeps reporting the stock it had until the first SURB of the new generation
2176    /// reaches it, and then the stock it had before the refill in flight landed. A report that lands
2177    /// after the first update, when the level is already rebuilding, must neither put the level back
2178    /// at the target, which would shut the organic gate and silence the PID while the counterparty
2179    /// holds nothing, nor pull it below the production since the reset, which is the truth. Every
2180    /// report is dropped for the window, and taken again once it is over.
2181    #[test_log::test]
2182    fn no_report_should_move_the_level_while_the_refill_after_a_wipe_is_paced() {
2183        use std::sync::atomic::Ordering::Relaxed;
2184
2185        let (mut balancer, estimator, state, _output) = balancer_with_feedback(paced_refill_config());
2186        let step = Duration::from_millis(50);
2187
2188        state.observe_reported_level(7_000);
2189        tick_for(&mut balancer, step);
2190        state.on_counterparty_wiped();
2191        tick_for(&mut balancer, step);
2192        assert_eq!(0, state.buffer_level(), "precondition: restarted from empty");
2193
2194        estimator.produced.fetch_add(200, Relaxed);
2195        tick_for(&mut balancer, step);
2196        assert_eq!(
2197            200,
2198            state.buffer_level(),
2199            "precondition: 200 SURBs of the new generation sent"
2200        );
2201
2202        state.observe_reported_level(7_000);
2203        assert_eq!(
2204            200,
2205            state.buffer_level(),
2206            "the pre-wipe level is dropped for the window"
2207        );
2208        assert_eq!(
2209            1,
2210            state.organic_surbs_per_packet(),
2211            "the organic gate stays open while the counterparty holds almost nothing"
2212        );
2213
2214        state.observe_reported_level(150);
2215        assert_eq!(
2216            200,
2217            state.buffer_level(),
2218            "a report below the belief is the stock before the refill in flight landed, and is dropped too"
2219        );
2220
2221        // Past the window (5 s of 50 ms ticks, and then some) a report is taken as it comes, net of
2222        // the production it cannot have seen yet.
2223        for _ in 0..110 {
2224            tick_for(&mut balancer, step);
2225        }
2226        let in_flight = state.produced_at_update.load(Relaxed) - state.produced_before_lag.load(Relaxed);
2227        state.observe_reported_level(7_000);
2228        assert_eq!(
2229            7_000 + in_flight,
2230            state.buffer_level(),
2231            "after the window the counterparty is believed again"
2232        );
2233    }
2234
2235    /// What a freshly built controller commands for `level`: the answer the first tick after the pacing
2236    /// window has to give, and the one a wound-up integral would corrupt.
2237    fn fresh_controller_output(cfg: SurbBalancerConfig, level: u64) -> u64 {
2238        let mut controller = PidBalancerController::default();
2239        controller.set_target_and_limit(cfg.as_controller_bounds());
2240        controller.next_control_output(level)
2241    }
2242
2243    /// A report says what the counterparty held when it was written; the SURBs produced since then
2244    /// were on their way and are added to it, so that adopting it does not discard them.
2245    #[test]
2246    fn a_report_is_adopted_net_of_the_production_it_cannot_have_seen() {
2247        let state = capacity_probe_state(7_000);
2248        state.publish_production(1_000, 1_600);
2249
2250        state.observe_reported_level(5_000);
2251        assert_eq!(
2252            5_600,
2253            state.buffer_level(),
2254            "600 SURBs were in flight when the report was written"
2255        );
2256
2257        state.publish_production(1_000, 1_000);
2258        state.observe_reported_level(5_000);
2259        assert_eq!(
2260            5_000,
2261            state.buffer_level(),
2262            "nothing produced between the lag and the update, nothing in flight"
2263        );
2264    }
2265
2266    /// A report adopted between two updates takes as in flight only what was produced up to the first
2267    /// of them: the second adds what came after, and that must not be counted twice.
2268    #[test]
2269    fn production_after_an_update_should_be_counted_once_when_a_report_lands_before_the_next() {
2270        use std::sync::atomic::Ordering;
2271
2272        let cfg = SurbBalancerConfig {
2273            target_surb_buffer_size: 5_000,
2274            max_surbs_per_sec: 2_000,
2275            surb_decay: None,
2276        };
2277        let (mut balancer, est, state, _output) = balancer_with_feedback(cfg);
2278
2279        est.produced.store(1_000, Ordering::Relaxed);
2280        std::thread::sleep(Duration::from_millis(15));
2281        balancer.update();
2282        assert_eq!(1_000, state.buffer_level.load(Ordering::Relaxed), "the first update");
2283
2284        // Produced after that update, then a report written before any of it reached the counterparty.
2285        est.produced.fetch_add(300, Ordering::Relaxed);
2286        state.observe_reported_level(800);
2287        assert_eq!(
2288            800,
2289            state.buffer_level.load(Ordering::Relaxed),
2290            "nothing was in flight up to the update"
2291        );
2292
2293        std::thread::sleep(Duration::from_millis(15));
2294        balancer.update();
2295        assert_eq!(
2296            1_100,
2297            state.buffer_level.load(Ordering::Relaxed),
2298            "the 300 produced after the first update are counted once, by the second"
2299        );
2300    }
2301
2302    /// The history answers with the newest sample at least the lag old, and with the oldest sample
2303    /// there is while it is still shorter than the lag.
2304    #[test]
2305    fn the_produced_history_should_answer_with_the_count_from_before_the_lag() {
2306        let mut history = ProducedHistory::default();
2307        let t0 = Instant::now();
2308        // In twentieths of the lag, so the test follows the constant.
2309        let at = |twentieths: u32| t0 + REPORT_LAG * twentieths / 20;
2310
2311        assert_eq!(100, history.record(at(0), 100), "a lone sample is its own past");
2312        assert_eq!(100, history.record(at(10), 300));
2313        assert_eq!(
2314            100,
2315            history.record(at(25), 500),
2316            "1.25 lags in, the sample one lag ago is still the first"
2317        );
2318        assert_eq!(
2319            300,
2320            history.record(at(31), 600),
2321            "1.55 lags in, the 0.5 sample is one lag old"
2322        );
2323        assert_eq!(300, history.record(at(44), 700));
2324        assert_eq!(500, history.record(at(46), 800), "the 1.25 sample is now one lag old");
2325        assert_eq!(
2326            4,
2327            history.samples.len(),
2328            "the lagged sample and the three newer ones, nothing older"
2329        );
2330    }
2331
2332    /// A report that lowers the believed level is a correction of the estimate, not SURBs the
2333    /// counterparty is missing: the next update is held to the pacing rate instead of answering the
2334    /// apparent deficit with the controller's ceiling, and the one after runs free.
2335    #[test_log::test]
2336    fn the_update_after_a_report_lowered_the_level_should_be_held_to_the_pacing_rate() {
2337        use std::sync::atomic::Ordering::Relaxed;
2338
2339        let cfg = paced_refill_config();
2340        let (mut balancer, _estimator, state, output) = balancer_with_feedback(cfg);
2341        let step = Duration::from_millis(50);
2342        let cap = cfg.target_surb_buffer_size / REFILL_PACING_SECS;
2343
2344        state.observe_reported_level(7_000);
2345        tick_for(&mut balancer, step);
2346        assert_eq!(0, output.load(Relaxed), "precondition: at target, nothing to mint");
2347
2348        // A lagging report, 1 800 below what is believed.
2349        state.observe_reported_level(5_200);
2350        assert_eq!(5_200, state.buffer_level());
2351        tick_for(&mut balancer, step);
2352        let held = output.load(Relaxed);
2353        assert!(
2354            held > 0 && held <= cap,
2355            "the update after the correction is held to the pacing rate {cap}: {held}"
2356        );
2357
2358        tick_for(&mut balancer, step);
2359        assert!(
2360            output.load(Relaxed) > cap,
2361            "the next update answers the deficit as the controller sees it: {}",
2362            output.load(Relaxed)
2363        );
2364    }
2365
2366    /// After a wipe the PID would command its output limit until the level is back. The refill is held
2367    /// to a fifth of the target per second for five seconds, and left alone after that.
2368    #[test_log::test]
2369    fn a_wipe_should_cap_output_for_the_pacing_window() {
2370        let cfg = paced_refill_config();
2371        let (mut balancer, _estimator, state, output) = balancer_with_feedback(cfg);
2372        let step = Duration::from_millis(50);
2373        let cap = cfg.target_surb_buffer_size / REFILL_PACING_SECS;
2374        assert_eq!(1_400, cap);
2375
2376        state.on_counterparty_wiped();
2377
2378        // Nothing is minted, so the level stays empty and the PID asks for everything it may.
2379        let mut outputs = Vec::new();
2380        for _ in 0..120 {
2381            tick_for(&mut balancer, step);
2382            outputs.push(output.load(std::sync::atomic::Ordering::Relaxed));
2383        }
2384
2385        // Margins of half a second either side of the five-second window, so that a slow tick cannot
2386        // move the edge into the assertion.
2387        let window = (REFILL_PACING_SECS * 1000 / step.as_millis() as u64) as usize;
2388        assert!(
2389            outputs[..window - 10].iter().all(|output| *output == cap),
2390            "the output must be the cap, {cap}, for the window: {outputs:?}"
2391        );
2392        assert!(
2393            outputs[window + 10..].iter().all(|output| *output > cap),
2394            "after the window the controller runs free: {outputs:?}"
2395        );
2396
2397        // The first free tick is a fresh controller's answer to the level, not an accumulated one. At
2398        // an empty level that is as much as the controller may command: one tick of its proportional
2399        // and integral terms already exceeds the limit.
2400        let first_free = outputs
2401            .iter()
2402            .position(|output| *output != cap)
2403            .expect("the window ends");
2404        assert_eq!(fresh_controller_output(cfg, 0), outputs[first_free]);
2405    }
2406
2407    /// The PID does not run while the refill is paced, so it integrates nothing. Whatever it had
2408    /// accumulated before the wipe (here, an integral wound up to its limit by a stretch at an empty
2409    /// level) is dropped when the window ends, and the first free tick answers the level the refill
2410    /// reached with a fresh controller's output. An integral carried through would answer the same
2411    /// level with the ceiling, and a level at or past the target with a burst.
2412    #[test_log::test]
2413    fn the_first_tick_after_the_pacing_window_should_start_from_the_current_level() {
2414        use std::sync::atomic::Ordering::Relaxed;
2415
2416        let cfg = paced_refill_config();
2417        let (mut balancer, estimator, state, output) = balancer_with_feedback(cfg);
2418        let step = Duration::from_millis(50);
2419
2420        // The PID winds its integral up against an empty counterparty.
2421        for _ in 0..20 {
2422            tick_for(&mut balancer, step);
2423        }
2424        assert_eq!(
2425            cfg.max_surbs_per_sec,
2426            output.load(Relaxed),
2427            "precondition: at the ceiling"
2428        );
2429
2430        // A wipe, and a refill that reaches 80 % of the target inside the window.
2431        state.on_counterparty_wiped();
2432        for _ in 0..20 {
2433            tick_for(&mut balancer, step);
2434        }
2435        let level = cfg.target_surb_buffer_size * 4 / 5;
2436        estimator.produced.fetch_add(level, Relaxed);
2437        while state.refill_pacing_active() {
2438            tick_for(&mut balancer, step);
2439            assert!(
2440                state.refill_pacing_active() || state.buffer_level() == level,
2441                "the level is the refill's"
2442            );
2443        }
2444
2445        tick_for(&mut balancer, step);
2446        let first_free = output.load(Relaxed);
2447        assert_eq!(fresh_controller_output(cfg, level), first_free);
2448        assert!(
2449            first_free < cfg.max_surbs_per_sec,
2450            "a level at 80 % of the target is not met with the ceiling: {first_free}"
2451        );
2452    }
2453
2454    /// A session that has just been opened is in the state a wipe leaves: the counterparty holds nothing
2455    /// and the PID would command its ceiling at once. The Entry arms the same pacing when its balancer
2456    /// starts, and the output is the cap, a fifth of the target, for the whole window, whatever the PID
2457    /// would say; then a fresh controller answers the level the fill reached. Nothing is reset on the
2458    /// way in: what was minted before the first tick is the new session's.
2459    #[test_log::test]
2460    fn a_fresh_entry_balancer_should_pace_its_initial_fill() {
2461        use std::sync::atomic::Ordering::Relaxed;
2462
2463        let cfg = paced_refill_config();
2464        let (mut balancer, estimator, state, output) = balancer_with_feedback(cfg);
2465        let step = Duration::from_millis(50);
2466        let cap = cfg.target_surb_buffer_size / REFILL_PACING_SECS;
2467        assert_eq!(1_400, cap);
2468        assert!(!state.refill_pacing_active(), "precondition: a new state paces nothing");
2469
2470        // What the Entry does as its balancer starts; some SURBs are already on their way.
2471        state.arm_refill_pacing();
2472        estimator.produced.fetch_add(100, Relaxed);
2473
2474        let mut outputs = Vec::new();
2475        tick_for(&mut balancer, step);
2476        outputs.push(output.load(Relaxed));
2477        assert_eq!(100, state.buffer_level(), "starting paced does not reset the estimate");
2478
2479        // The fill reaches 80 % of the target inside the window; the PID, if it ran, would still ask for
2480        // everything it may.
2481        let level = cfg.target_surb_buffer_size * 4 / 5;
2482        estimator.produced.fetch_add(level - 100, Relaxed);
2483        while state.refill_pacing_active() {
2484            tick_for(&mut balancer, step);
2485            outputs.push(output.load(Relaxed));
2486            assert!(outputs.len() < 200, "the window must end");
2487        }
2488
2489        // The window is five seconds of 50 ms ticks; margins of half a second either side, so that a slow
2490        // tick cannot move the edge into the assertion.
2491        let window = (REFILL_PACING_SECS * 1000 / step.as_millis() as u64) as usize;
2492        assert!(
2493            outputs.len().abs_diff(window) <= 10,
2494            "the window lasts about {window} ticks: {}",
2495            outputs.len()
2496        );
2497        assert!(
2498            outputs.iter().all(|output| *output == cap),
2499            "the output is the cap, {cap}, on every tick of the window: {outputs:?}"
2500        );
2501
2502        tick_for(&mut balancer, step);
2503        let first_free = output.load(Relaxed);
2504        assert_eq!(fresh_controller_output(cfg, level), first_free);
2505        assert!(
2506            first_free < cfg.max_surbs_per_sec,
2507            "a level at 80 % of the target is not met with the ceiling: {first_free}"
2508        );
2509    }
2510
2511    /// Arming does nothing for a balancer that is switched off.
2512    #[test]
2513    fn arming_the_pacing_of_a_disabled_balancer_should_do_nothing() {
2514        let state = BalancerStateValues::default();
2515        state.arm_refill_pacing();
2516        assert!(!state.refill_pacing_active());
2517    }
2518
2519    /// The refill stops by itself the moment the target is reached, and stays stopped until the window
2520    /// ends, when the controller, fresh, answers a level at the target with nothing.
2521    #[test_log::test]
2522    fn pacing_should_stop_the_refill_once_the_target_is_reached_inside_the_window() {
2523        use std::sync::atomic::Ordering::Relaxed;
2524
2525        let cfg = paced_refill_config();
2526        let (mut balancer, estimator, state, output) = balancer_with_feedback(cfg);
2527        let step = Duration::from_millis(50);
2528        let cap = cfg.target_surb_buffer_size / REFILL_PACING_SECS;
2529
2530        state.on_counterparty_wiped();
2531        for _ in 0..60 {
2532            tick_for(&mut balancer, step);
2533            assert_eq!(cap, output.load(Relaxed), "refilling at the cap while below the target");
2534        }
2535
2536        // Three seconds in, the refill has delivered the target.
2537        estimator.produced.fetch_add(cfg.target_surb_buffer_size, Relaxed);
2538        let mut after_target = Vec::new();
2539        for _ in 0..30 {
2540            tick_for(&mut balancer, step);
2541            after_target.push(output.load(Relaxed));
2542        }
2543        assert_eq!(cfg.target_surb_buffer_size, state.buffer_level());
2544        assert!(
2545            after_target.iter().all(|output| *output == 0),
2546            "nothing more is commanded once the target is reached, inside the window or at its end: {after_target:?}"
2547        );
2548
2549        // And on past the window's end, which the level holds at the target through.
2550        while state.refill_pacing_active() {
2551            tick_for(&mut balancer, step);
2552            assert_eq!(0, output.load(Relaxed));
2553        }
2554        tick_for(&mut balancer, step);
2555        assert_eq!(
2556            0,
2557            output.load(Relaxed),
2558            "the first free tick at the target commands nothing"
2559        );
2560    }
2561
2562    /// The pacing is a rate the balancer commands, not a bound. The PID is rebuilt whenever the state's
2563    /// bounds differ from its own, which would discard its integral, so the pacing must not be
2564    /// implemented as a bound.
2565    #[test_log::test]
2566    fn pacing_must_not_reconfigure_the_controller_bounds() {
2567        let cfg = paced_refill_config();
2568        let (mut balancer, _estimator, state, _output) = balancer_with_feedback(cfg);
2569        let bounds = state.controller_bounds();
2570        assert_eq!(bounds, balancer.controller.bounds(), "precondition: in step");
2571
2572        state.on_counterparty_wiped();
2573        for _ in 0..120 {
2574            tick_for(&mut balancer, Duration::from_millis(50));
2575            assert_eq!(
2576                bounds,
2577                state.controller_bounds(),
2578                "the state's bounds are what the control loop compares the controller's against"
2579            );
2580            assert_eq!(bounds, balancer.controller.bounds());
2581        }
2582        assert_eq!(cfg, state.as_config());
2583    }
2584
2585    /// With no target there is no balancing, and nothing to hold back.
2586    #[test]
2587    fn a_wipe_of_a_disabled_balancer_should_arm_no_pacing() {
2588        let state = BalancerStateValues::default();
2589        state.on_counterparty_wiped();
2590        assert_eq!(None, state.pace_refill(Duration::from_millis(50)));
2591    }
2592
2593    // -----------------------------------------------------------------------
2594    // Sustaining the counterparty's SURBs through a silence
2595    // -----------------------------------------------------------------------
2596
2597    /// The sustain is about data going out into a silence. Without data going out for more than the grace
2598    /// since the first packet after the last time the counterparty was heard, there is nothing to sustain,
2599    /// and neither is there before it was heard at all, or while there is no balancer.
2600    #[test]
2601    fn silence_without_outgoing_data_should_not_sustain() {
2602        let state = gate_state(100, 200).last_heard_ago(Duration::from_secs(10));
2603        assert!(
2604            !state.silence_sustain(),
2605            "heard 10 s ago, and nothing has been sent since"
2606        );
2607
2608        // A packet that goes out inside the grace after the last time it was heard is not a silence yet.
2609        let state = state.sending_since_ago(Duration::from_secs(8));
2610        assert!(!state.silence_sustain(), "sent 2 s after it was heard");
2611
2612        let never_heard = gate_state(100, 200);
2613        never_heard.note_sent();
2614        assert!(
2615            !never_heard.silence_sustain(),
2616            "nothing was ever heard, so nothing has gone quiet"
2617        );
2618
2619        let disabled = gate_state(0, 0).last_heard_ago(Duration::from_secs(10));
2620        disabled.note_sent();
2621        assert!(!disabled.silence_sustain(), "no balancer, no sustain");
2622
2623        let silent = gate_state(100, 200)
2624            .last_heard_ago(Duration::from_secs(10))
2625            .sending_since_ago(Duration::from_secs(8));
2626        silent.note_sent();
2627        assert!(
2628            silent.silence_sustain(),
2629            "data going out since 8 s ago, 2 s after the last word, is a silence"
2630        );
2631
2632        let unanswered = gate_state(100, 200).last_heard_only_ago(Duration::from_secs(10));
2633        unanswered.note_sent();
2634        assert!(
2635            !unanswered.silence_sustain(),
2636            "a Session the counterparty never answered has no reply stream to lose: heard only by its reports, it is \
2637             quiet by design"
2638        );
2639    }
2640
2641    /// An idle stretch is no silence: nothing went out, so nothing was left unanswered. The window starts at
2642    /// the first packet after the counterparty was last heard, and the Exit gets the grace to answer it.
2643    #[test]
2644    fn the_first_packet_after_an_idle_stretch_should_not_sustain() {
2645        let idle = gate_state(100, 200).last_heard_ago(Duration::from_secs(10));
2646        idle.note_sent();
2647        assert!(
2648            !idle.silence_sustain(),
2649            "the first packet after 10 s with nothing sent and nothing heard"
2650        );
2651
2652        let sending = gate_state(100, 200)
2653            .last_heard_ago(Duration::from_secs(10))
2654            .sending_since_ago(Duration::from_secs(8));
2655        sending.note_sent();
2656        assert!(sending.silence_sustain(), "8 s of data going out, nothing coming back");
2657
2658        sending.note_heard();
2659        sending.note_sent();
2660        assert!(
2661            !sending.silence_sustain(),
2662            "heard again, and the packet after it starts a new run"
2663        );
2664    }
2665
2666    /// The reply stream is judged against the data before the current run, not against the last word heard:
2667    /// reports that arrive while nothing goes out do not age it. A Session that was answered, went quiet and
2668    /// whose return path failed meanwhile is a silence once it sends again; one that kept sending through the
2669    /// reports without an answer is an upload and is not.
2670    #[test]
2671    fn reports_during_a_quiet_stretch_should_not_age_the_reply_stream() {
2672        // Data answered until 40 s ago, then nothing either way but the Exit's reports, the last one 5 s
2673        // ago; data going out again since 4 s ago, unanswered.
2674        let paused = gate_state(100, 200)
2675            .last_heard_ago(Duration::from_secs(40))
2676            .last_sent_ago(Duration::from_secs(40))
2677            .heard_again_ago(Duration::from_secs(5))
2678            .sending_since_ago(Duration::from_secs(4));
2679        paused.note_sent();
2680        assert!(
2681            paused.silence_sustain(),
2682            "the data before the pause was answered and the data after it is not: a return path that failed"
2683        );
2684
2685        // The same reply and reports, but data kept going out through them, the last packet just before
2686        // the last report: unanswered for 35 s, an upload.
2687        let upload = gate_state(100, 200)
2688            .last_heard_ago(Duration::from_secs(40))
2689            .last_sent_ago(Duration::from_millis(5_010))
2690            .heard_again_ago(Duration::from_secs(5))
2691            .sending_since_ago(Duration::from_secs(4));
2692        upload.note_sent();
2693        assert!(
2694            !upload.silence_sustain(),
2695            "data went out unanswered for 35 s before the last report: there is no reply stream to lose"
2696        );
2697    }
2698
2699    /// Driven through the state's own stamps rather than the time-travel hooks: an answered packet, a quiet
2700    /// stretch with a report in it, then data again. The report alone starts nothing, and the first packet
2701    /// after it starts the run that is judged against the answered packet before the pause.
2702    #[test]
2703    fn the_run_after_a_quiet_stretch_should_be_judged_against_the_data_before_it() {
2704        use std::sync::atomic::Ordering::Relaxed;
2705
2706        let state = gate_state(100, 200).last_heard_ago(Duration::from_secs(30));
2707        state.note_sent();
2708        let answered = state.last_sent.load(Relaxed);
2709        state.note_heard();
2710        state.note_reply_heard();
2711        state.note_heard(); // a report during the quiet stretch
2712        assert_eq!(0, state.previous_run_ended.load(Relaxed), "a report starts no run");
2713        state.note_sent();
2714        assert_eq!(
2715            answered,
2716            state.previous_run_ended.load(Relaxed),
2717            "the run after the report ends the one that held the answered packet"
2718        );
2719    }
2720
2721    /// Whatever the Exit says is heard: a report of its level, and any packet at all, whose signals are
2722    /// all the Entry reads of it.
2723    #[test]
2724    fn a_report_or_any_packet_from_the_counterparty_should_count_as_heard() {
2725        let state = gate_state(100, 200);
2726        assert_eq!(
2727            0,
2728            state.last_heard.load(std::sync::atomic::Ordering::Relaxed),
2729            "nothing heard yet"
2730        );
2731
2732        state.observe_counterparty_signals(PacketSignals::default());
2733        let after_a_packet = state.last_heard.load(std::sync::atomic::Ordering::Relaxed);
2734        assert!(after_a_packet > 0, "a packet from the Exit");
2735
2736        let state = gate_state(100, 200);
2737        state.observe_reported_level(50);
2738        assert!(
2739            state.last_heard.load(std::sync::atomic::Ordering::Relaxed) > 0,
2740            "a level report"
2741        );
2742    }
2743
2744    /// Reports arriving every second keep the Entry out of `silence_sustain`, and its level follows them.
2745    ///
2746    /// This is the Entry half of the Exit's degraded cadence (hoprnet#8596), and it is the reason the
2747    /// Entry needs no change of its own. The sustain engages after [`SILENCE_SUSTAIN_AFTER`] of data
2748    /// going out with nothing coming back, and it would then put one SURB in every data packet. A
2749    /// degraded Exit reports once a second, so nothing is ever silent long enough for it — and what
2750    /// the Entry reads is the Exit's real level, which is a better input for its balancer than the
2751    /// sustain's guess that the return path is gone.
2752    ///
2753    /// Every case is the same dark forward path, so that only the reports differ: without them it is
2754    /// a silence (the negative control), with one in the last second it is not, and one older than
2755    /// the grace no longer holds the sustain off.
2756    #[test]
2757    fn reports_every_second_keep_the_entry_out_of_the_silence_sustain() {
2758        // The forward path went dark 10 s ago: the reply stream stopped then, and data has been going
2759        // out unanswered since 8 s ago.
2760        let dark = || {
2761            gate_state(100, 200)
2762                .last_heard_ago(Duration::from_secs(10))
2763                .sending_since_ago(Duration::from_secs(8))
2764        };
2765
2766        let unreported = dark();
2767        unreported.note_sent();
2768        assert!(
2769            unreported.silence_sustain(),
2770            "fixture: without the reports, the same dark forward path must be a silence"
2771        );
2772
2773        // A report comes in: the Entry reads the Exit's level, and the data after it starts a new run.
2774        let reported = dark();
2775        reported.observe_reported_level(500);
2776        reported.note_sent();
2777        assert!(!reported.silence_sustain(), "a report has just come in");
2778        assert_eq!(
2779            500,
2780            reported.buffer_level(),
2781            "the Entry must track the Exit's reports while the forward path is dark"
2782        );
2783
2784        // Just before the next report, a second after the last: the data since the last one has been
2785        // going out for under a second, well inside the grace.
2786        let between_reports = dark()
2787            .heard_again_ago(Duration::from_secs(1))
2788            .sending_since_ago(Duration::from_millis(990));
2789        between_reports.note_sent();
2790        assert!(
2791            !between_reports.silence_sustain(),
2792            "a report a second is not a silence, so the Entry must not sustain on its own"
2793        );
2794
2795        // A report older than the grace no longer holds the sustain off: it is the cadence that does.
2796        let stale_report = dark()
2797            .heard_again_ago(SILENCE_SUSTAIN_AFTER + Duration::from_secs(1))
2798            .sending_since_ago(SILENCE_SUSTAIN_AFTER + Duration::from_millis(990));
2799        stale_report.note_sent();
2800        assert!(
2801            stale_report.silence_sustain(),
2802            "data unanswered for longer than the grace since the last report is a silence"
2803        );
2804    }
2805
2806    /// A keep-alive is counted by the estimator as a consumed SURB: it is the counterparty being heard, but
2807    /// it is not a reply, and a reply after it still is one.
2808    #[test]
2809    fn a_keep_alive_counted_as_consumed_should_be_heard_but_not_as_a_reply() {
2810        use std::sync::atomic::Ordering::Relaxed;
2811        let (mut balancer, estimator, state, output) = balancer_with_feedback(SurbBalancerConfig {
2812            target_surb_buffer_size: 1_000,
2813            max_surbs_per_sec: 2_500,
2814            surb_decay: None,
2815        });
2816
2817        // The keep-alive is processed as the session manager does: level first, then the consumed SURB.
2818        state.observe_counterparty_signals(PacketSignals::default());
2819        state.observe_reported_level(1_000);
2820        state.note_keep_alive_consumed(&estimator);
2821        tick(&mut balancer, &estimator, &output, 0);
2822        assert!(
2823            state.last_heard.load(Relaxed) > 0,
2824            "a keep-alive is the counterparty being heard"
2825        );
2826        assert_eq!(0, state.last_reply_heard.load(Relaxed), "a keep-alive is not a reply");
2827
2828        estimator.consumed.fetch_add(1, Relaxed);
2829        tick(&mut balancer, &estimator, &output, 0);
2830        assert!(
2831            state.last_reply_heard.load(Relaxed) > 0,
2832            "a reply after a keep-alive still counts"
2833        );
2834    }
2835
2836    /// Keep-alives counted while the balancer ticks must never look like a reply: the keep-alive count is
2837    /// written before `consumed` and read after it.
2838    #[test]
2839    fn keep_alives_racing_the_balancer_should_never_count_as_a_reply() -> anyhow::Result<()> {
2840        use std::sync::atomic::Ordering::Relaxed;
2841        const PER_WRITER: u64 = 100_000;
2842        let (mut balancer, estimator, state, _output) = balancer_with_feedback(SurbBalancerConfig {
2843            target_surb_buffer_size: 1_000,
2844            max_surbs_per_sec: 2_500,
2845            surb_decay: None,
2846        });
2847
2848        let writers: Vec<_> = (0..2)
2849            .map(|_| {
2850                let (state, estimator) = (state.clone(), estimator.clone());
2851                std::thread::spawn(move || (0..PER_WRITER).for_each(|_| state.note_keep_alive_consumed(&estimator)))
2852            })
2853            .collect();
2854        while !writers.iter().all(|w| w.is_finished()) {
2855            tick_for(&mut balancer, Duration::from_millis(50));
2856        }
2857        for w in writers {
2858            w.join().map_err(|_| anyhow::anyhow!("keep-alive writer panicked"))?;
2859        }
2860        tick_for(&mut balancer, Duration::from_millis(50));
2861
2862        assert_eq!(0, state.last_reply_heard.load(Relaxed), "keep-alives are not replies");
2863        assert_eq!(2 * PER_WRITER, estimator.consumed.load(Relaxed));
2864        assert_eq!(2 * PER_WRITER, state.keep_alives_consumed());
2865
2866        estimator.consumed.fetch_add(1, Relaxed);
2867        tick_for(&mut balancer, Duration::from_millis(50));
2868        assert!(
2869            state.last_reply_heard.load(Relaxed) > 0,
2870            "a reply after them still counts"
2871        );
2872        Ok(())
2873    }
2874
2875    /// A sample taken between a keep-alive's two counts sees one reply fewer than came home. The SURB of
2876    /// that keep-alive, when it lands, must not count as a reply, and a reply it hid must count once it
2877    /// lands.
2878    #[test]
2879    fn a_keep_alive_sampled_halfway_should_neither_pass_for_a_reply_nor_lose_one() {
2880        use std::sync::atomic::Ordering::{Relaxed, Release};
2881        let (mut balancer, estimator, state, _output) = balancer_with_feedback(SurbBalancerConfig {
2882            target_surb_buffer_size: 1_000,
2883            max_surbs_per_sec: 2_500,
2884            surb_decay: None,
2885        });
2886
2887        estimator.consumed.fetch_add(1, Relaxed);
2888        tick_for(&mut balancer, Duration::from_millis(50));
2889        assert!(state.last_reply_heard.load(Relaxed) > 0, "a reply counts");
2890        state.last_reply_heard.store(0, Relaxed);
2891
2892        state.keep_alives_consumed.fetch_add(1, Relaxed);
2893        tick_for(&mut balancer, Duration::from_millis(50));
2894        estimator.consumed.fetch_add(1, Release);
2895        tick_for(&mut balancer, Duration::from_millis(50));
2896        assert_eq!(
2897            0,
2898            state.last_reply_heard.load(Relaxed),
2899            "the SURB of a keep-alive sampled halfway is not a reply"
2900        );
2901
2902        state.keep_alives_consumed.fetch_add(1, Relaxed);
2903        estimator.consumed.fetch_add(1, Relaxed);
2904        tick_for(&mut balancer, Duration::from_millis(50));
2905        assert_eq!(
2906            0,
2907            state.last_reply_heard.load(Relaxed),
2908            "a reply sampled with a keep-alive halfway is hidden"
2909        );
2910        estimator.consumed.fetch_add(1, Release);
2911        tick_for(&mut balancer, Duration::from_millis(50));
2912        assert!(
2913            state.last_reply_heard.load(Relaxed) > 0,
2914            "and counts once the keep-alive's SURB lands"
2915        );
2916    }
2917
2918    /// A reply home is the Exit answering, counted by the estimator as a SURB consumed, even where none of
2919    /// its packets reached the hooks that record it. Production minted and nothing consumed is not.
2920    #[test_log::test]
2921    fn a_reply_counted_as_consumed_should_count_as_heard() {
2922        let (mut balancer, estimator, state, output) = balancer_with_feedback(small_target_config());
2923        let heard = || state.last_heard.load(std::sync::atomic::Ordering::Relaxed);
2924
2925        for _ in 0..5 {
2926            tick(&mut balancer, &estimator, &output, 0);
2927        }
2928        assert_eq!(0, heard(), "SURBs minted and none consumed: nobody has answered");
2929
2930        tick(&mut balancer, &estimator, &output, 3);
2931        assert!(heard() > 0, "three replies came home in that tick");
2932    }
2933
2934    /// A fifth of a small target is a SURB or two a second, and a keep-alive carries several: the fill
2935    /// would send one keep-alive every few seconds and the Session wait for it. One keep-alive's worth a
2936    /// second is the floor.
2937    #[test]
2938    fn the_pacing_should_carry_at_least_one_keep_alive_a_second() {
2939        let state = BalancerStateValues::new(SurbBalancerConfig {
2940            target_surb_buffer_size: 11,
2941            ..Default::default()
2942        });
2943        assert_eq!(2, state.pacing_cap(), "a fifth of the target, without a floor");
2944        state.set_pacing_floor(8);
2945        assert_eq!(8, state.pacing_cap(), "one keep-alive of 8 SURBs a second");
2946
2947        let large = BalancerStateValues::new(SurbBalancerConfig {
2948            target_surb_buffer_size: 6_887,
2949            ..Default::default()
2950        });
2951        large.set_pacing_floor(8);
2952        assert_eq!(
2953            1_377,
2954            large.pacing_cap(),
2955            "a large target is paced at a fifth, as before"
2956        );
2957    }
2958
2959    /// The pacing replaces the PID output for its window, and must not mint more than the client
2960    /// configured the balancer to.
2961    #[test]
2962    fn the_pacing_should_never_exceed_the_configured_ceiling() {
2963        let state = BalancerStateValues::new(SurbBalancerConfig {
2964            target_surb_buffer_size: 30_000,
2965            max_surbs_per_sec: 5_000,
2966            ..Default::default()
2967        });
2968        assert_eq!(
2969            5_000,
2970            state.pacing_cap(),
2971            "a fifth of 30 000 is 6 000, above the ceiling"
2972        );
2973
2974        let organic_only = BalancerStateValues::new(SurbBalancerConfig {
2975            target_surb_buffer_size: 7_000,
2976            max_surbs_per_sec: 0,
2977            ..Default::default()
2978        });
2979        organic_only.set_pacing_floor(8);
2980        assert_eq!(0, organic_only.pacing_cap(), "a ceiling of nothing paces nothing");
2981    }
2982}