1#![forbid(unsafe_code)]
9#![warn(missing_docs)]
10#![cfg_attr(
11 not(test),
12 deny(
13 clippy::unwrap_used,
14 clippy::expect_used,
15 clippy::todo,
16 clippy::unimplemented,
17 clippy::panic
18 )
19)]
20#![allow(
21 clippy::module_name_repetitions,
22 clippy::must_use_candidate,
23 clippy::missing_errors_doc
24)]
25
26use std::time::{Duration, SystemTime};
27
28use rand::Rng;
29use thiserror::Error;
30
31pub const BACKOFF_MAX_RETRIES: u32 = 4;
33
34pub const BACKOFF_429_BASE_MS: u64 = 500;
36
37pub const BACKOFF_TIMEOUT_BASE_MS: u64 = 200;
39
40pub const MAX_RETRY_AFTER_OBEYED: Duration = Duration::from_secs(60);
45
46pub const MAX_PACING_BACKOFF: Duration = Duration::from_secs(60);
53
54#[derive(Debug, Clone, PartialEq, Eq, Error)]
56pub enum PacingError {
57 #[error(
59 "invalid jitter range: min_ms={min_ms} is greater than max_exclusive_ms={max_exclusive_ms}"
60 )]
61 InvalidJitterRange {
62 min_ms: u64,
64 max_exclusive_ms: u64,
66 },
67}
68fn duration_from_nanos_clamped(nanos: u128, max: Duration) -> Duration {
73 let max_nanos = max.as_nanos();
74 if nanos >= max_nanos {
75 return max;
76 }
77 let secs = (nanos / 1_000_000_000) as u64;
78 let subsec_nanos = (nanos % 1_000_000_000) as u64;
79 Duration::from_secs(secs)
80 .checked_add(Duration::from_nanos(subsec_nanos))
81 .unwrap_or(max)
82}
83
84#[derive(Debug, Clone, Copy, PartialEq, Eq)]
90pub struct Jitter {
91 min_ms: u64,
92 max_exclusive_ms: u64,
93}
94
95impl Jitter {
96 #[must_use]
98 pub const fn zero() -> Self {
99 Self {
100 min_ms: 0,
101 max_exclusive_ms: 0,
102 }
103 }
104
105 #[must_use]
107 pub const fn up_to(max_exclusive_ms: u64) -> Self {
108 Self {
109 min_ms: 0,
110 max_exclusive_ms,
111 }
112 }
113
114 pub fn range(min_ms: u64, max_exclusive_ms: u64) -> Result<Self, PacingError> {
121 if min_ms > max_exclusive_ms {
122 return Err(PacingError::InvalidJitterRange {
123 min_ms,
124 max_exclusive_ms,
125 });
126 }
127 Ok(Self {
128 min_ms,
129 max_exclusive_ms,
130 })
131 }
132
133 #[must_use]
135 pub const fn min_ms(self) -> u64 {
136 self.min_ms
137 }
138
139 #[must_use]
141 pub const fn max_exclusive_ms(self) -> u64 {
142 self.max_exclusive_ms
143 }
144
145 pub fn sample<R: Rng + ?Sized>(self, rng: &mut R) -> Duration {
150 if self.max_exclusive_ms <= self.min_ms {
151 return Duration::from_millis(self.min_ms);
152 }
153 Duration::from_millis(rng.gen_range(self.min_ms..self.max_exclusive_ms))
154 }
155
156 #[must_use]
160 pub fn sample_thread(self) -> Duration {
161 let mut rng = rand::thread_rng();
162 self.sample(&mut rng)
163 }
164}
165
166#[derive(Debug, Clone, Copy, PartialEq, Eq)]
173pub struct BoundedNormalDelay {
174 min_ms: u64,
175 max_ms: u64,
176}
177
178impl BoundedNormalDelay {
179 #[must_use]
181 pub const fn zero() -> Self {
182 Self {
183 min_ms: 0,
184 max_ms: 0,
185 }
186 }
187
188 #[must_use]
192 pub fn from_unordered_bounds(first_ms: u64, second_ms: u64) -> Self {
193 Self {
194 min_ms: first_ms.min(second_ms),
195 max_ms: first_ms.max(second_ms),
196 }
197 }
198
199 #[must_use]
201 pub const fn min_ms(self) -> u64 {
202 self.min_ms
203 }
204
205 #[must_use]
207 pub const fn max_ms(self) -> u64 {
208 self.max_ms
209 }
210
211 pub fn sample<R: Rng + ?Sized>(self, rng: &mut R) -> Duration {
213 if self.max_ms <= self.min_ms {
214 return Duration::from_millis(self.min_ms);
215 }
216
217 let mean = (self.min_ms as f64 + self.max_ms as f64) / 2.0;
218 let stddev = (self.max_ms - self.min_ms) as f64 / 4.0;
219 let u1: f64 = rng.gen_range(f64::EPSILON..1.0);
220 let u2: f64 = rng.gen_range(0.0..std::f64::consts::TAU);
221 let z = (-2.0 * u1.ln()).sqrt() * u2.cos();
222 let delay_ms = (mean + z * stddev).clamp(self.min_ms as f64, self.max_ms as f64);
223
224 Duration::from_millis((delay_ms as u64).clamp(self.min_ms, self.max_ms))
228 }
229
230 #[must_use]
234 pub fn sample_thread(self) -> Duration {
235 let mut rng = rand::thread_rng();
236 self.sample(&mut rng)
237 }
238}
239
240#[must_use]
246pub fn percent_jitter(base: Duration, percent: u64) -> Duration {
247 let mut rng = rand::thread_rng();
248 percent_jitter_with_rng(base, percent, &mut rng)
249}
250
251#[must_use]
257pub fn percent_jitter_with_rng<R: Rng + ?Sized>(
258 base: Duration,
259 percent: u64,
260 rng: &mut R,
261) -> Duration {
262 if base.is_zero() {
263 return Duration::ZERO;
264 }
265
266 let lower = 100_u64.saturating_sub(percent);
267 let upper = 100_u64.saturating_add(percent);
268 let factor = if lower == upper {
269 lower
270 } else {
271 rng.gen_range(lower..=upper)
272 };
273
274 let jittered_nanos = base.as_nanos().saturating_mul(u128::from(factor)) / 100;
275 duration_from_nanos_clamped(jittered_nanos, MAX_PACING_BACKOFF)
276}
277
278#[derive(Debug, Clone, Copy, PartialEq, Eq)]
280pub enum BackoffKind {
281 RateLimited,
283 Timeout,
285}
286
287#[derive(Debug, Clone, Copy, PartialEq, Eq)]
289pub struct BackoffPolicy {
290 max_retries: u32,
291 rate_limited_base_ms: u64,
292 timeout_base_ms: u64,
293}
294
295impl BackoffPolicy {
296 #[must_use]
298 pub const fn new(max_retries: u32, rate_limited_base_ms: u64, timeout_base_ms: u64) -> Self {
299 Self {
300 max_retries,
301 rate_limited_base_ms,
302 timeout_base_ms,
303 }
304 }
305
306 #[must_use]
308 pub const fn gossan_compatible() -> Self {
309 Self::new(
310 BACKOFF_MAX_RETRIES,
311 BACKOFF_429_BASE_MS,
312 BACKOFF_TIMEOUT_BASE_MS,
313 )
314 }
315
316 #[must_use]
318 pub const fn max_retries(self) -> u32 {
319 self.max_retries
320 }
321 #[must_use]
323 pub const fn rate_limited_base_ms(self) -> u64 {
324 self.rate_limited_base_ms
325 }
326
327 #[must_use]
329 pub const fn timeout_base_ms(self) -> u64 {
330 self.timeout_base_ms
331 }
332
333 #[must_use]
339 pub const fn should_retry_after(self, attempt: u32) -> bool {
340 attempt.saturating_add(1) < self.max_retries
341 }
342
343 #[must_use]
348 pub fn delay(self, kind: BackoffKind, attempt: u32) -> Duration {
349 let base_ms = match kind {
350 BackoffKind::RateLimited => self.rate_limited_base_ms,
351 BackoffKind::Timeout => self.timeout_base_ms,
352 };
353 Duration::from_millis(saturating_pow2_ms(base_ms, attempt)).min(MAX_PACING_BACKOFF)
354 }
355}
356
357impl Default for BackoffPolicy {
358 fn default() -> Self {
359 Self::gossan_compatible()
360 }
361}
362
363#[must_use]
370pub fn capped_exponential_backoff(
371 initial_ms: u64,
372 multiplier: f64,
373 attempt: u32,
374 max_ms: u64,
375) -> Duration {
376 if initial_ms == 0 || max_ms == 0 {
377 return Duration::ZERO;
378 }
379
380 let effective_max_ms = max_ms.min(MAX_PACING_BACKOFF.as_millis() as u64);
381 let bounded_multiplier = if multiplier.is_finite() && multiplier >= 1.0 {
382 multiplier
383 } else {
384 1.0
385 };
386 let exponent = i32::try_from(attempt).unwrap_or(i32::MAX);
387 let delay_ms =
388 (initial_ms as f64 * bounded_multiplier.powi(exponent)).min(effective_max_ms as f64);
389
390 if delay_ms.is_finite() {
391 Duration::from_millis((delay_ms as u64).min(effective_max_ms))
395 } else {
396 Duration::from_millis(effective_max_ms)
397 }
398}
399
400#[must_use]
407pub fn capped_pow2_backoff(base: Duration, attempt: u32, max: Duration) -> Duration {
408 if base.is_zero() || max.is_zero() {
409 return Duration::ZERO;
410 }
411
412 let effective_max = max.min(MAX_PACING_BACKOFF);
413 let capped_base_nanos = base.as_nanos().min(effective_max.as_nanos());
414 let multiplier = if attempt >= u128::BITS {
415 u128::MAX
416 } else {
417 1_u128 << attempt
418 };
419 let capped_nanos = capped_base_nanos
420 .saturating_mul(multiplier)
421 .min(effective_max.as_nanos());
422
423 duration_from_nanos_clamped(capped_nanos, effective_max)
424}
425
426#[must_use]
431pub fn capped_pow2_backoff_ms(base_ms: u64, attempt: u32, max_ms: u64) -> Duration {
432 capped_pow2_backoff(
433 Duration::from_millis(base_ms),
434 attempt,
435 Duration::from_millis(max_ms),
436 )
437}
438
439#[must_use]
445pub fn parse_retry_after(value: &str, now: SystemTime) -> Option<Duration> {
446 let trimmed = value.trim();
447 if trimmed.is_empty() {
448 return None;
449 }
450
451 if trimmed.bytes().all(|byte| byte.is_ascii_digit()) {
452 let seconds: u64 = trimmed.parse().unwrap_or(u64::MAX);
458 let delay = Duration::from_secs(seconds);
459 return Some(delay.min(MAX_RETRY_AFTER_OBEYED));
460 }
461
462 let target = httpdate::parse_http_date(trimmed).ok()?;
463 let delay = target.duration_since(now).ok()?;
464 Some(delay.min(MAX_RETRY_AFTER_OBEYED))
465}
466
467#[must_use]
472pub fn jittered_backoff(base: Duration, nonce: u32) -> Duration {
473 if base.is_zero() {
474 return Duration::ZERO;
475 }
476
477 let mut x = nonce ^ 0x9E37_79B9;
478 x ^= x.wrapping_shl(13);
479 x ^= x.wrapping_shr(17);
480 x ^= x.wrapping_shl(5);
481
482 let multiplier_per_mille = 800 + u64::from(x % 401);
483 let base_nanos = base.as_nanos();
484 let jittered_nanos = base_nanos.saturating_mul(u128::from(multiplier_per_mille)) / 1000;
485 duration_from_nanos_clamped(jittered_nanos, MAX_PACING_BACKOFF)
486}
487
488#[derive(Debug, Clone, Copy, PartialEq, Eq)]
496pub struct RequestPacer {
497 base: BoundedNormalDelay,
498 challenge_multiplier: u32,
499}
500
501impl RequestPacer {
502 pub const MAX_CHALLENGE_MULTIPLIER: u32 = 16;
504
505 #[must_use]
507 pub const fn new(base: BoundedNormalDelay) -> Self {
508 Self {
509 base,
510 challenge_multiplier: 1,
511 }
512 }
513
514 #[must_use]
517 pub fn page_load() -> Self {
518 Self::new(BoundedNormalDelay::from_unordered_bounds(800, 3_000))
519 }
520
521 #[must_use]
523 pub fn sub_resource() -> Self {
524 Self::new(BoundedNormalDelay::from_unordered_bounds(100, 400))
525 }
526
527 #[must_use]
529 pub fn api_call() -> Self {
530 Self::new(BoundedNormalDelay::from_unordered_bounds(300, 1_200))
531 }
532
533 #[must_use]
535 pub const fn challenge_multiplier(self) -> u32 {
536 self.challenge_multiplier
537 }
538 #[must_use]
540 pub const fn base(self) -> BoundedNormalDelay {
541 self.base
542 }
543
544 pub fn record_success(&mut self) {
547 self.challenge_multiplier = self.challenge_multiplier.saturating_sub(1).max(1);
548 }
549
550 pub fn record_rate_limit(&mut self) {
552 self.challenge_multiplier =
553 (self.challenge_multiplier.saturating_mul(2)).min(Self::MAX_CHALLENGE_MULTIPLIER);
554 }
555
556 pub fn record_http_status(&mut self, status: u16) {
558 match status {
559 429 => self.record_rate_limit(),
560 403 => self.record_rate_limit(),
561 _ if (200..300).contains(&status) => self.record_success(),
562 _ => {}
563 }
564 }
565
566 pub fn next_delay<R: Rng + ?Sized>(&self, rng: &mut R) -> Duration {
573 let base = self.base.sample(rng);
574 base.saturating_mul(self.challenge_multiplier)
575 .min(MAX_PACING_BACKOFF)
576 }
577
578 #[must_use]
580 pub fn next_delay_thread(self) -> Duration {
581 let mut rng = rand::thread_rng();
582 self.next_delay(&mut rng)
583 }
584}
585
586impl Default for RequestPacer {
587 fn default() -> Self {
588 Self::page_load()
589 }
590}
591
592fn saturating_pow2_ms(base_ms: u64, attempt: u32) -> u64 {
593 let multiplier = if attempt >= u64::BITS {
594 u64::MAX
595 } else {
596 1_u64 << attempt
597 };
598 base_ms.saturating_mul(multiplier)
599}
600
601#[cfg(test)]
602mod tests {
603 use super::*;
604 use rand::{rngs::StdRng, SeedableRng};
605
606 #[test]
607 fn jitter_up_to_preserves_exclusive_upper_bound() {
608 let mut rng = StdRng::seed_from_u64(7);
609 let jitter = Jitter::up_to(10);
610 for _ in 0..100 {
611 let delay = jitter.sample(&mut rng);
612 assert!(delay < Duration::from_millis(10));
613 }
614 }
615
616 #[test]
617 fn jitter_equal_bounds_is_fixed_delay() {
618 let mut rng = StdRng::seed_from_u64(1);
619 let jitter = Jitter::range(25, 25).unwrap();
620 assert_eq!(jitter.sample(&mut rng), Duration::from_millis(25));
621 }
622
623 #[test]
624 fn percent_jitter_preserves_symmetric_bounds() {
625 let mut rng = StdRng::seed_from_u64(21);
626 let base = Duration::from_millis(500);
627 let lo = Duration::from_millis(400);
628 let hi = Duration::from_millis(600);
629 let mut distinct = std::collections::HashSet::new();
630
631 for _ in 0..10_000 {
632 let delay = percent_jitter_with_rng(base, 20, &mut rng);
633 assert!(delay >= lo && delay <= hi, "{delay:?}");
634 distinct.insert(delay);
635 }
636
637 assert_eq!(
638 distinct.len(),
639 41,
640 "20% millisecond jitter over a 500ms base should preserve the historical 80..=120 factor domain"
641 );
642 }
643
644 #[test]
645 fn percent_jitter_zero_percent_is_fixed_delay() {
646 let mut rng = StdRng::seed_from_u64(23);
647 assert_eq!(
648 percent_jitter_with_rng(Duration::from_millis(750), 0, &mut rng),
649 Duration::from_millis(750)
650 );
651 }
652
653 #[test]
654 fn percent_jitter_zero_base_is_zero() {
655 let mut rng = StdRng::seed_from_u64(25);
656 assert_eq!(
657 percent_jitter_with_rng(Duration::ZERO, 20, &mut rng),
658 Duration::ZERO
659 );
660 }
661
662 #[test]
663 fn percent_jitter_large_percent_does_not_underflow() {
664 let mut rng = StdRng::seed_from_u64(27);
665 for _ in 0..1000 {
666 let delay = percent_jitter_with_rng(Duration::from_millis(10), 250, &mut rng);
667 assert!(delay <= Duration::from_millis(35), "{delay:?}");
668 }
669 }
670
671 #[test]
672 fn bounded_normal_delay_preserves_bounds_and_distribution_shape() {
673 let mut rng = StdRng::seed_from_u64(31);
674 let policy = BoundedNormalDelay::from_unordered_bounds(400, 600);
675 let mut delays = Vec::with_capacity(10_000);
676
677 for _ in 0..10_000 {
678 let delay = policy.sample(&mut rng);
679 assert!(
680 delay >= Duration::from_millis(400) && delay <= Duration::from_millis(600),
681 "{delay:?}"
682 );
683 delays.push(delay.as_millis() as f64);
684 }
685
686 let actual_mean = delays.iter().sum::<f64>() / delays.len() as f64;
687 let variance = delays
688 .iter()
689 .map(|delay| (delay - actual_mean).powi(2))
690 .sum::<f64>()
691 / delays.len() as f64;
692 let actual_stddev = variance.sqrt();
693
694 assert!(
695 (actual_mean - 500.0).abs() < 8.0,
696 "mean {actual_mean} should stay centered"
697 );
698 assert!(
699 actual_stddev > 35.0 && actual_stddev < 60.0,
700 "stddev {actual_stddev} should preserve bounded normal shape"
701 );
702 }
703
704 #[test]
705 fn bounded_normal_delay_normalizes_misordered_bounds() {
706 let mut rng = StdRng::seed_from_u64(33);
707 let policy = BoundedNormalDelay::from_unordered_bounds(1_000, 100);
708
709 assert_eq!(policy.min_ms(), 100);
710 assert_eq!(policy.max_ms(), 1_000);
711 for _ in 0..100 {
712 let delay = policy.sample(&mut rng);
713 assert!(
714 delay >= Duration::from_millis(100) && delay <= Duration::from_millis(1_000),
715 "{delay:?}"
716 );
717 }
718 }
719
720 #[test]
721 fn bounded_normal_delay_equal_bounds_is_fixed_delay() {
722 let mut rng = StdRng::seed_from_u64(35);
723 let policy = BoundedNormalDelay::from_unordered_bounds(250, 250);
724 assert_eq!(policy.sample(&mut rng), Duration::from_millis(250));
725 }
726
727 #[test]
728 fn invalid_jitter_range_is_rejected() {
729 assert!(matches!(
730 Jitter::range(50, 10),
731 Err(PacingError::InvalidJitterRange {
732 min_ms: 50,
733 max_exclusive_ms: 10
734 })
735 ));
736 }
737
738 #[test]
739 fn gossan_backoff_schedule_is_pinned() {
740 let policy = BackoffPolicy::gossan_compatible();
741 assert_eq!(
742 policy.delay(BackoffKind::RateLimited, 0),
743 Duration::from_millis(500)
744 );
745 assert_eq!(
746 policy.delay(BackoffKind::RateLimited, 3),
747 Duration::from_millis(4_000)
748 );
749 assert_eq!(
750 policy.delay(BackoffKind::Timeout, 2),
751 Duration::from_millis(800)
752 );
753 assert!(policy.should_retry_after(2));
754 assert!(!policy.should_retry_after(3));
755 }
756
757 #[test]
758 fn capped_exponential_backoff_is_zero_based_and_capped() {
759 assert_eq!(
760 capped_exponential_backoff(100, 2.0, 0, 2_000),
761 Duration::from_millis(100)
762 );
763 assert_eq!(
764 capped_exponential_backoff(100, 2.0, 3, 2_000),
765 Duration::from_millis(800)
766 );
767 assert_eq!(
768 capped_exponential_backoff(100, 2.0, 10, 2_000),
769 Duration::from_millis(2_000)
770 );
771 }
772
773 #[test]
774 fn capped_exponential_backoff_rejects_hostile_policy_values() {
775 assert_eq!(
776 capped_exponential_backoff(100, f64::NAN, 4, 2_000),
777 Duration::from_millis(100)
778 );
779 assert_eq!(
780 capped_exponential_backoff(100, 0.5, 4, 2_000),
781 Duration::from_millis(100)
782 );
783 assert_eq!(
784 capped_exponential_backoff(100, f64::INFINITY, 4, 2_000),
785 Duration::from_millis(100)
786 );
787 assert_eq!(capped_exponential_backoff(0, 2.0, 4, 2_000), Duration::ZERO);
788 }
789
790 #[test]
791 fn capped_pow2_backoff_is_zero_based_and_capped() {
792 assert_eq!(
793 capped_pow2_backoff(Duration::from_millis(100), 0, Duration::from_secs(60)),
794 Duration::from_millis(100)
795 );
796 assert_eq!(
797 capped_pow2_backoff(Duration::from_millis(100), 3, Duration::from_secs(60)),
798 Duration::from_millis(800)
799 );
800 assert_eq!(
801 capped_pow2_backoff(Duration::from_millis(100), 20, Duration::from_secs(60)),
802 Duration::from_secs(60)
803 );
804 }
805
806 #[test]
807 fn capped_pow2_backoff_handles_zero_and_huge_inputs() {
808 assert_eq!(
809 capped_pow2_backoff(Duration::ZERO, 8, Duration::from_secs(60)),
810 Duration::ZERO
811 );
812 assert_eq!(
813 capped_pow2_backoff(Duration::from_secs(1), 8, Duration::ZERO),
814 Duration::ZERO
815 );
816 assert_eq!(
817 capped_pow2_backoff(Duration::MAX, u32::MAX, Duration::from_secs(60)),
818 Duration::from_secs(60)
819 );
820 }
821
822 #[test]
823 fn capped_pow2_backoff_ms_matches_duration_policy() {
824 assert_eq!(
825 capped_pow2_backoff_ms(250, 4, 60_000),
826 capped_pow2_backoff(Duration::from_millis(250), 4, Duration::from_secs(60))
827 );
828 }
829
830 #[test]
831 fn retry_after_delta_seconds_are_trimmed_and_capped() {
832 let now = SystemTime::UNIX_EPOCH + Duration::from_secs(1_700_000_000);
833
834 assert_eq!(
835 parse_retry_after("\t30\t", now),
836 Some(Duration::from_secs(30))
837 );
838 assert_eq!(parse_retry_after("3600", now), Some(MAX_RETRY_AFTER_OBEYED));
839 assert_eq!(parse_retry_after("0", now), Some(Duration::ZERO));
840 }
841
842 #[test]
843 fn retry_after_rejects_malformed_delta_seconds() {
844 let now = SystemTime::UNIX_EPOCH + Duration::from_secs(1_700_000_000);
845
846 assert_eq!(parse_retry_after("", now), None);
847 assert_eq!(parse_retry_after(" ", now), None);
848 assert_eq!(parse_retry_after("-1", now), None);
849 assert_eq!(parse_retry_after("12.5", now), None);
850 assert_eq!(parse_retry_after("1 2", now), None);
851 }
852
853 #[test]
854 fn retry_after_http_date_uses_caller_clock_and_cap() {
855 let now = SystemTime::UNIX_EPOCH + Duration::from_secs(1_700_000_000);
856 let future = httpdate::fmt_http_date(now + Duration::from_secs(30));
857 let past = httpdate::fmt_http_date(now - Duration::from_secs(30));
858 let far = httpdate::fmt_http_date(now + Duration::from_secs(3600));
859
860 let wait = parse_retry_after(&future, now).expect("future date should parse");
861 assert!(wait >= Duration::from_secs(29) && wait <= Duration::from_secs(30));
862 assert_eq!(parse_retry_after(&past, now), None);
863 assert_eq!(parse_retry_after(&far, now), Some(MAX_RETRY_AFTER_OBEYED));
864 }
865
866 #[test]
867 fn retry_after_rejects_non_gmt_http_date() {
868 let now = SystemTime::UNIX_EPOCH + Duration::from_secs(1_700_000_000);
869
870 assert_eq!(
871 parse_retry_after("Wed, 21 Oct 2015 07:28:00 +0530", now),
872 None
873 );
874 }
875
876 #[test]
877 fn deterministic_jitter_is_bounded_and_varied() {
878 let base = Duration::from_millis(1000);
879 let lo = Duration::from_millis(800);
880 let hi = Duration::from_millis(1200);
881 let mut distinct = std::collections::HashSet::new();
882
883 for nonce in 0..10_000_u32 {
884 let delay = jittered_backoff(base, nonce);
885 assert!(delay >= lo && delay <= hi, "nonce {nonce}: {delay:?}");
886 if nonce < 128 {
887 distinct.insert(delay);
888 }
889 }
890
891 assert!(
892 distinct.len() >= 40,
893 "jitter produced only {} distinct delays",
894 distinct.len()
895 );
896 }
897
898 #[test]
899 fn deterministic_jitter_zero_base_is_zero() {
900 for nonce in 0..1000_u32 {
901 assert_eq!(jittered_backoff(Duration::ZERO, nonce), Duration::ZERO);
902 }
903 }
904
905 #[test]
906 fn request_pacer_delays_stay_within_profile_bounds() {
907 let mut rng = StdRng::seed_from_u64(41);
908 let pacer = RequestPacer::page_load();
909 for _ in 0..100 {
910 let delay = pacer.next_delay(&mut rng);
911 assert!(
912 delay >= Duration::from_millis(800) && delay <= Duration::from_millis(3_000),
913 "{delay:?}"
914 );
915 }
916 }
917
918 #[test]
919 fn request_pacer_default_is_not_a_fixed_sleep() {
920 let mut rng = StdRng::seed_from_u64(43);
921 let pacer = RequestPacer::default();
922 let mut distinct = std::collections::HashSet::new();
923 for _ in 0..100 {
924 distinct.insert(pacer.next_delay(&mut rng));
925 }
926 assert!(
927 distinct.len() > 50,
928 "default pacer produced only {} distinct delays, looks fixed",
929 distinct.len()
930 );
931 }
932
933 #[test]
934 fn request_pacer_doubles_then_decays_on_status_feedback() {
935 let mut pacer = RequestPacer::api_call();
936 pacer.record_http_status(429);
937 assert_eq!(pacer.challenge_multiplier(), 2);
938 pacer.record_http_status(429);
939 assert_eq!(pacer.challenge_multiplier(), 4);
940 pacer.record_http_status(200);
941 assert_eq!(pacer.challenge_multiplier(), 3);
942 pacer.record_http_status(200);
943 assert_eq!(pacer.challenge_multiplier(), 2);
944 pacer.record_http_status(200);
945 assert_eq!(pacer.challenge_multiplier(), 1);
946 pacer.record_http_status(200);
947 assert_eq!(pacer.challenge_multiplier(), 1);
948 }
949
950 #[test]
951 fn request_pacer_challenge_multiplier_is_capped() {
952 let mut pacer = RequestPacer::sub_resource();
953 for _ in 0..10 {
954 pacer.record_rate_limit();
955 }
956 assert_eq!(
957 pacer.challenge_multiplier(),
958 RequestPacer::MAX_CHALLENGE_MULTIPLIER
959 );
960 }
961
962 #[test]
963 fn request_pacer_challenge_multiplies_delay() {
964 let mut rng = StdRng::seed_from_u64(47);
965 let base = RequestPacer::api_call();
966 let mut challenged = base;
967 challenged.record_rate_limit();
968 let base_delay = base.next_delay(&mut rng);
969 let challenged_delay = challenged.next_delay(&mut rng);
970 assert!(
974 challenged_delay > base_delay,
975 "challenged delay should exceed base delay"
976 );
977 assert!(
978 challenged_delay >= Duration::from_millis(600)
979 && challenged_delay <= Duration::from_millis(2_400),
980 "{challenged_delay:?} outside doubled API-call bounds"
981 );
982 }
983
984 #[test]
985 fn percent_jitter_overflow_clamps_to_max_pacing_backoff() {
986 let mut rng = StdRng::seed_from_u64(7);
987 let delay = percent_jitter_with_rng(Duration::MAX, 20, &mut rng);
988 assert!(
989 delay <= MAX_PACING_BACKOFF,
990 "overflow percent jitter {delay:?} exceeded ceiling"
991 );
992 }
993
994 #[test]
995 fn capped_pow2_backoff_overflow_clamps_to_configured_max() {
996 let max = Duration::from_secs(60);
997 let delay = capped_pow2_backoff(Duration::MAX, u32::MAX, max);
998 assert!(
999 delay <= max,
1000 "overflow capped_pow2 {delay:?} exceeded configured max {max:?}"
1001 );
1002 assert!(
1003 delay <= MAX_PACING_BACKOFF,
1004 "overflow capped_pow2 {delay:?} exceeded hard ceiling"
1005 );
1006 }
1007
1008 #[test]
1009 fn jittered_backoff_overflow_clamps_to_max_pacing_backoff() {
1010 let delay = jittered_backoff(Duration::MAX, 42);
1011 assert!(
1012 delay <= MAX_PACING_BACKOFF,
1013 "overflow jittered_backoff {delay:?} exceeded ceiling"
1014 );
1015 }
1016
1017 #[test]
1018 fn duration_from_nanos_clamped_never_falls_back_to_u64_max() {
1019 let ceiling = Duration::from_secs(60);
1022 let delay = duration_from_nanos_clamped(u128::MAX, ceiling);
1023 assert_eq!(delay, ceiling);
1024 }
1025
1026 #[test]
1035 fn request_pacer_hostile_base_saturates_instead_of_panicking() {
1036 let mut rng = StdRng::seed_from_u64(53);
1037 let mut pacer = RequestPacer::new(BoundedNormalDelay::from_unordered_bounds(
1038 u64::MAX,
1039 u64::MAX,
1040 ));
1041 pacer.record_rate_limit();
1042 pacer.record_rate_limit();
1043 let delay = pacer.next_delay(&mut rng);
1044 assert_eq!(delay, MAX_PACING_BACKOFF);
1045 }
1046
1047 #[test]
1051 fn request_pacer_ordinary_multiplication_is_preserved() {
1052 let mut rng = StdRng::seed_from_u64(59);
1053 let mut pacer = RequestPacer::api_call();
1054 pacer.record_rate_limit();
1055 for _ in 0..256 {
1056 let delay = pacer.next_delay(&mut rng);
1057 assert!(
1058 delay >= Duration::from_millis(600) && delay <= Duration::from_millis(2_400),
1059 "{delay:?} outside doubled API-call bounds"
1060 );
1061 }
1062 }
1063
1064 #[test]
1070 fn backoff_policy_delay_clamps_to_max_pacing_backoff() {
1071 let policy = BackoffPolicy::new(8, 3_600_000, 3_600_000);
1072 assert_eq!(
1073 policy.delay(BackoffKind::RateLimited, 0),
1074 MAX_PACING_BACKOFF
1075 );
1076 assert_eq!(policy.delay(BackoffKind::Timeout, 20), MAX_PACING_BACKOFF);
1077 }
1078
1079 #[test]
1085 fn retry_after_rejects_signed_delta_seconds() {
1086 let now = SystemTime::UNIX_EPOCH + Duration::from_secs(1_700_000_000);
1087 assert_eq!(parse_retry_after("+5", now), None);
1088 assert_eq!(parse_retry_after("5 ", now), Some(Duration::from_secs(5)));
1089 }
1090
1091 #[test]
1096 fn retry_after_overflowing_digit_string_clamps_to_max_retry_after() {
1097 let now = SystemTime::UNIX_EPOCH + Duration::from_secs(1_700_000_000);
1098 let huge_digits = "9".repeat(50);
1099 assert_eq!(
1100 parse_retry_after(&huge_digits, now),
1101 Some(MAX_RETRY_AFTER_OBEYED)
1102 );
1103 }
1104
1105 #[test]
1109 fn capped_exponential_backoff_clamps_to_max_pacing_backoff() {
1110 assert_eq!(
1111 capped_exponential_backoff(1000, 2.0, 10, 300_000),
1112 MAX_PACING_BACKOFF
1113 );
1114 assert_eq!(
1115 capped_exponential_backoff(1000, 2.0, 10, u64::MAX),
1116 MAX_PACING_BACKOFF
1117 );
1118 }
1119
1120 #[test]
1125 fn bounded_normal_delay_can_sample_full_envelope() {
1126 let mut rng = StdRng::seed_from_u64(12345);
1127 let pacer = BoundedNormalDelay::from_unordered_bounds(100, 1_000);
1128 let mut saw_low = false;
1129 let mut saw_high = false;
1130
1131 for _ in 0..100_000 {
1132 let delay = pacer.sample(&mut rng);
1133 if delay <= Duration::from_millis(115) {
1134 saw_low = true;
1135 }
1136 if delay >= Duration::from_millis(985) {
1137 saw_high = true;
1138 }
1139 if saw_low && saw_high {
1140 break;
1141 }
1142 }
1143 assert!(
1144 saw_low,
1145 "BoundedNormalDelay should reach the low tail <= 115ms"
1146 );
1147 assert!(
1148 saw_high,
1149 "BoundedNormalDelay should reach the high tail >= 985ms"
1150 );
1151 }
1152
1153 #[test]
1155 fn policy_and_pacer_getters_match_constructed_state() {
1156 let policy = BackoffPolicy::new(5, 400, 150);
1157 assert_eq!(policy.max_retries(), 5);
1158 assert_eq!(policy.rate_limited_base_ms(), 400);
1159 assert_eq!(policy.timeout_base_ms(), 150);
1160
1161 let pacer = RequestPacer::api_call();
1162 assert_eq!(pacer.base().min_ms(), 300);
1163 assert_eq!(pacer.base().max_ms(), 1_200);
1164 }
1165}