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#[derive(Clone, Copy, Debug, PartialEq, smart_default::SmartDefault)]
57pub struct SurbBalancerConfig {
58 #[default(7_000)]
72 pub target_surb_buffer_size: u64,
73 #[default(5_000)]
82 pub max_surbs_per_sec: u64,
83
84 #[default(_code = "Some((Duration::from_secs(60), 0.05))")]
91 pub surb_decay: Option<(Duration, f64)>,
92}
93
94impl SurbBalancerConfig {
95 #[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#[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 invalid_surbs: AtomicU64,
114 pub counterparty_buffer_capacity: AtomicU64,
140 pub counterparty_in_surb_distress: AtomicBool,
150 pub observed_counterparty_capacity: AtomicU64,
167 pub capacity_plateau_count: AtomicU64,
170 counterparty_wiped: AtomicBool,
180 refill_pacing: AtomicU64,
184 produced_before_lag: AtomicU64,
188 produced_at_update: AtomicU64,
192 correction_cap: AtomicBool,
195 epoch: ActivityEpoch,
197 last_heard: AtomicU64,
201 last_sent: AtomicU64,
203 sending_since: AtomicU64,
207 previous_run_ended: AtomicU64,
210 last_reply_heard: AtomicU64,
213 keep_alives_consumed: AtomicU64,
216 pacing_floor: AtomicU64,
219 counterparty_refills: AtomicBool,
222}
223
224#[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
234pub const SILENCE_SUSTAIN_AFTER: Duration = Duration::from_secs(3);
247
248pub const REPLY_STREAM_WINDOW: Duration = Duration::from_secs(15);
252
253pub const REFILL_PACING_SECS: u64 = 5;
280
281pub const REPORT_LAG: Duration = Duration::from_secs(1);
293
294pub(crate) const CAPACITY_PLATEAU_THRESHOLD: u64 = 3;
298
299impl BalancerStateValues {
300 pub fn new(cfg: SurbBalancerConfig) -> Self {
302 let state = Self::default();
303 state.update(&cfg);
304 state
305 }
306
307 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 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 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 pub fn observe_counterparty_signals(&self, signals: PacketSignals) {
362 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 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 pub fn observe_reported_level(&self, new_level: u64) {
400 use std::sync::atomic::Ordering::Relaxed;
401
402 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 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 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 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 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 fn take_correction_cap(&self) -> bool {
465 self.correction_cap.swap(false, std::sync::atomic::Ordering::Relaxed)
466 }
467
468 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 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 pub fn organic_surbs_per_packet(&self) -> usize {
507 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 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 pub(crate) fn note_heard(&self) {
541 self.stamp(&self.last_heard, std::time::Instant::now());
542 }
543
544 pub(crate) fn note_counterparty_refills(&self) {
547 self.counterparty_refills
548 .store(true, std::sync::atomic::Ordering::Relaxed);
549 }
550
551 pub(crate) fn counterparty_refills(&self) -> bool {
556 self.counterparty_refills.load(std::sync::atomic::Ordering::Relaxed)
557 }
558
559 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 pub(crate) fn note_reply_heard(&self) {
574 self.stamp(&self.last_reply_heard, std::time::Instant::now());
575 }
576
577 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 pub(crate) fn keep_alives_consumed(&self) -> u64 {
590 self.keep_alives_consumed.load(std::sync::atomic::Ordering::Relaxed)
591 }
592
593 #[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 state.stamp(&state.last_reply_heard, at);
605 state
606 }
607
608 #[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 #[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 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 #[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 #[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 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 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 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 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 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 fn take_counterparty_wiped(&self) -> bool {
760 self.counterparty_wiped.swap(false, std::sync::atomic::Ordering::AcqRel)
761 }
762
763 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 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 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 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 level.saturating_sub(count.min((level as f64 * share).round() as u64))
809 }
810
811 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 pub fn is_disabled(&self) -> bool {
822 self.target_surb_buffer_size.load(std::sync::atomic::Ordering::Relaxed) == 0
823 }
824
825 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 #[inline]
837 pub fn buffer_level(&self) -> u64 {
838 self.buffer_level.load(std::sync::atomic::Ordering::Relaxed)
839 }
840
841 #[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#[derive(Debug, Default)]
860struct ProducedHistory {
861 samples: VecDeque<(Instant, u64)>,
862}
863
864impl ProducedHistory {
865 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
878pub 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 was_pacing: bool,
910 last_report: std::time::Instant,
912 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 #[tracing::instrument(level = "trace", skip_all)]
957 fn update(&mut self) -> u64 {
958 let dt = self.last_update.elapsed();
959
960 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 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 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 if snapshot.consumed > self.last_estimator_state.consumed {
985 self.state.note_heard();
986 }
987
988 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 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 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 let believed = current;
1027 current = self.state.clamp_to_counterparty_capacity(current);
1028 if current != believed {
1029 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 let usable = self.state.usable_level(current);
1048
1049 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 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 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 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 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 #[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 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 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 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 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 #[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 #[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 #[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 #[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 #[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 #[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)), ..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 #[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 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 const REPLIES_PER_TICK: u64 = 40;
1597
1598 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 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 target_surb_buffer_size: 1_000,
1622 max_surbs_per_sec: 2_500,
1623 surb_decay: None,
1624 }
1625 }
1626
1627 #[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 #[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 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 #[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 #[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 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 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 #[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 fn capacity_probe_state(target: u64) -> BalancerStateValues {
1792 BalancerStateValues::new(SurbBalancerConfig {
1793 target_surb_buffer_size: target,
1794 ..Default::default()
1795 })
1796 }
1797
1798 #[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 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 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 #[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 #[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 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 #[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 #[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 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 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 #[test_log::test]
1942 fn surb_balancer_pins_estimate_and_collapses_output_under_return_path_loss() {
1943 use std::sync::atomic::Ordering;
1944
1945 const COUNTERPARTY_CAPACITY: u64 = 15_000;
1947
1948 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 for _ in 0..40 {
1955 tick(&mut balancer, &surb_estimator, &output, REPLIES_PER_TICK);
1956 }
1957
1958 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 balancer.update();
1968 }
1969
1970 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 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 #[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 #[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 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 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 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 #[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 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 state.observe_reported_level(7_000);
2155 assert_eq!(0, state.buffer_level(), "a report above the believed level is dropped");
2156
2157 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 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 #[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 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 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 #[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 #[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 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 #[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 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 #[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 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 #[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 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 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 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 #[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 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 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 #[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 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 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 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 #[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 #[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 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 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 #[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 #[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 #[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 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 #[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 #[test]
2671 fn reports_during_a_quiet_stretch_should_not_age_the_reply_stream() {
2672 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 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 #[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(); 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 #[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 #[test]
2757 fn reports_every_second_keep_the_entry_out_of_the_silence_sustain() {
2758 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 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 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 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 #[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 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 #[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 #[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 #[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 #[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 #[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}