Skip to main content

guise_pacing/
lib.rs

1//! Cross-plane pacing primitives for requests and browser actions.
2//!
3//! Donor implementations used to carry local copies of jitter and exponential
4//! backoff policy. This module keeps the timing math pure so HTTP clients,
5//! browser drivers, and mobile executors can share one contract without taking
6//! each other's async or transport dependencies.
7
8#![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
31/// Maximum number of retry attempts used by the fleet's HTTP backoff policy.
32pub const BACKOFF_MAX_RETRIES: u32 = 4;
33
34/// Base delay for 429 / rate-limit backoff.
35pub const BACKOFF_429_BASE_MS: u64 = 500;
36
37/// Base delay for transient timeout backoff.
38pub const BACKOFF_TIMEOUT_BASE_MS: u64 = 200;
39
40/// Upper bound for a server-named `Retry-After` cooldown.
41///
42/// Longer waits are treated as hostile or operationally unhelpful and are
43/// capped so scanners can fail visibly instead of sleeping for minutes.
44pub const MAX_RETRY_AFTER_OBEYED: Duration = Duration::from_secs(60);
45
46/// Hard ceiling on any pacing/backoff delay produced by this crate.
47///
48/// Pathological base durations or attempt counts can saturate `u128`/`u64`
49/// arithmetic to values like `u64::MAX` nanoseconds (~584 years). That is
50/// operationally a hang, so every delay computation in this module clamps to
51/// this bound. Callers that configure a smaller maximum keep their cap.
52pub const MAX_PACING_BACKOFF: Duration = Duration::from_secs(60);
53
54/// Errors returned by pacing policy constructors.
55#[derive(Debug, Clone, PartialEq, Eq, Error)]
56pub enum PacingError {
57    /// The configured exclusive upper bound is below the lower bound.
58    #[error(
59        "invalid jitter range: min_ms={min_ms} is greater than max_exclusive_ms={max_exclusive_ms}"
60    )]
61    InvalidJitterRange {
62        /// Inclusive lower bound in milliseconds.
63        min_ms: u64,
64        /// Exclusive upper bound in milliseconds.
65        max_exclusive_ms: u64,
66    },
67}
68/// Convert `nanos` into a [`Duration`] without ever silently falling back to
69/// `u64::MAX` nanoseconds (~584 years). The result is clamped to `max` and,
70/// if `nanos` is representable, reconstructed exactly from its seconds and
71/// subsecond parts.
72fn 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/// Random delay envelope with an exclusive upper bound.
85///
86/// The exclusive upper bound preserves the historical `0..max_ms` behaviour
87/// from Karyx camouflage while making the policy reusable and deterministic
88/// under a caller-supplied RNG.
89#[derive(Debug, Clone, Copy, PartialEq, Eq)]
90pub struct Jitter {
91    min_ms: u64,
92    max_exclusive_ms: u64,
93}
94
95impl Jitter {
96    /// No jitter.
97    #[must_use]
98    pub const fn zero() -> Self {
99        Self {
100            min_ms: 0,
101            max_exclusive_ms: 0,
102        }
103    }
104
105    /// A delay sampled from `0..max_exclusive_ms`.
106    #[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    /// A delay sampled from `min_ms..max_exclusive_ms`.
115    ///
116    /// # Errors
117    ///
118    /// Returns [`PacingError::InvalidJitterRange`] when `min_ms` is greater
119    /// than the exclusive upper bound.
120    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    /// Inclusive lower bound in milliseconds.
134    #[must_use]
135    pub const fn min_ms(self) -> u64 {
136        self.min_ms
137    }
138
139    /// Exclusive upper bound in milliseconds.
140    #[must_use]
141    pub const fn max_exclusive_ms(self) -> u64 {
142        self.max_exclusive_ms
143    }
144
145    /// Sample a delay from this envelope.
146    ///
147    /// When the upper bound is equal to the lower bound, this returns the
148    /// fixed lower-bound delay.
149    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    /// Sample using the process-local RNG from this crate's `rand` version.
157    ///
158    /// This avoids leaking `rand`'s trait version through downstream APIs.
159    #[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/// Bounded normally-distributed delay envelope for human-like pacing.
167///
168/// The distribution is centered between the bounds with a standard deviation
169/// of one quarter of the range, then clamped to the configured bounds. This
170/// matches the historical Karyx authenticated-scan pacing contract while
171/// making the Box-Muller sampling reusable across Santh runtimes.
172#[derive(Debug, Clone, Copy, PartialEq, Eq)]
173pub struct BoundedNormalDelay {
174    min_ms: u64,
175    max_ms: u64,
176}
177
178impl BoundedNormalDelay {
179    /// No delay.
180    #[must_use]
181    pub const fn zero() -> Self {
182        Self {
183            min_ms: 0,
184            max_ms: 0,
185        }
186    }
187
188    /// Build from explicit inclusive lower and upper bounds.
189    ///
190    /// Bounds are normalized so hostile or misordered config cannot panic.
191    #[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    /// Inclusive lower bound in milliseconds.
200    #[must_use]
201    pub const fn min_ms(self) -> u64 {
202        self.min_ms
203    }
204
205    /// Inclusive upper bound in milliseconds.
206    #[must_use]
207    pub const fn max_ms(self) -> u64 {
208        self.max_ms
209    }
210
211    /// Sample a delay from the bounded normal distribution.
212    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        // Clamp again in the integer domain: above 2^53 the f64 rounding of
225        // the bounds can land a few ulps outside the documented inclusive
226        // envelope (a hostile `u64::MAX`-scale bound must still be honored).
227        Duration::from_millis((delay_ms as u64).clamp(self.min_ms, self.max_ms))
228    }
229
230    /// Sample using the process-local RNG from this crate's `rand` version.
231    ///
232    /// This avoids leaking `rand`'s trait version through downstream APIs.
233    #[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/// Apply randomized symmetric percent jitter to a duration.
241///
242/// `percent` is interpreted around 100%, so `20` samples a multiplier in
243/// `80..=120`. The calculation preserves sub-millisecond precision and
244/// saturates on hostile inputs instead of panicking.
245#[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/// Apply randomized symmetric percent jitter using the caller's RNG.
252///
253/// `percent` is interpreted around 100%, so `20` samples a multiplier in
254/// `80..=120`. Percent values over 100 allow delays below the base down to
255/// zero, and all arithmetic saturates instead of overflowing.
256#[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/// Retry category whose base delay differs by failure mode.
279#[derive(Debug, Clone, Copy, PartialEq, Eq)]
280pub enum BackoffKind {
281    /// Remote service returned a rate-limit response such as HTTP 429.
282    RateLimited,
283    /// Transport timed out before a response completed.
284    Timeout,
285}
286
287/// Exponential retry backoff policy.
288#[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    /// Build a policy from explicit retry count and base delays.
297    #[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    /// Policy matching the fleet's historical Gossan/Karyx retry contract.
307    #[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    /// Maximum number of attempts before a caller should give up.
317    #[must_use]
318    pub const fn max_retries(self) -> u32 {
319        self.max_retries
320    }
321    /// Base delay in milliseconds for HTTP 429 / rate-limited responses.
322    #[must_use]
323    pub const fn rate_limited_base_ms(self) -> u64 {
324        self.rate_limited_base_ms
325    }
326
327    /// Base delay in milliseconds for transient timeouts.
328    #[must_use]
329    pub const fn timeout_base_ms(self) -> u64 {
330        self.timeout_base_ms
331    }
332
333    /// Whether another retry should be attempted after `attempt`.
334    ///
335    /// Saturates: a corrupt `u32::MAX` attempt counter means "do not retry",
336    /// never an overflow panic (debug) or wrap-to-zero that re-arms the retry
337    /// loop (release).
338    #[must_use]
339    pub const fn should_retry_after(self, attempt: u32) -> bool {
340        attempt.saturating_add(1) < self.max_retries
341    }
342
343    /// Delay for `attempt`, using saturating exponential growth.
344    ///
345    /// The result is clamped to [`MAX_PACING_BACKOFF`] so a pathological base
346    /// delay or attempt count cannot turn a retry sleep into an effective hang.
347    #[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/// Calculate a capped exponential backoff delay from caller-owned policy data.
364///
365/// `attempt` is zero-based: attempt `0` returns `initial_ms`, attempt `1`
366/// returns `initial_ms * multiplier`, and so on. Non-finite or sub-unit
367/// multipliers are treated as `1.0` so bad policy data cannot create negative,
368/// NaN, or shrinking retry sleeps.
369#[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        // Clamp again in the integer domain: above 2^53 the f64 rounding of
392        // `initial_ms`/`effective_max_ms` can land a few ulps past the cap, which would
393        // make the documented `max_ms` bound leak.
394        Duration::from_millis((delay_ms as u64).min(effective_max_ms))
395    } else {
396        Duration::from_millis(effective_max_ms)
397    }
398}
399
400/// Calculate a capped power-of-two exponential backoff for duration policies.
401///
402/// `attempt` is zero-based: attempt `0` returns `base`, attempt `1` returns
403/// `base * 2`, and so on. The base is capped before multiplication and the
404/// final delay is capped again, matching scanner retry contracts that treat
405/// the maximum as both an input and output safety boundary.
406#[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/// Calculate a capped power-of-two exponential backoff from millisecond inputs.
427///
428/// This is a convenience wrapper around [`capped_pow2_backoff`] for HTTP and
429/// scanner configuration surfaces that store retry policy as milliseconds.
430#[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/// Parse a `Retry-After` header value at a caller-supplied clock reference.
440///
441/// Accepted forms are RFC delta-seconds and HTTP-date values. Empty values,
442/// negative values, fractional seconds, malformed integers, and past dates
443/// return `None`; valid waits are capped at [`MAX_RETRY_AFTER_OBEYED`].
444#[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        // RFC 9110 delta-seconds is 1*DIGIT: no sign, no fraction, no
453        // whitespace inside the token. A signed or fractional value falls
454        // through to the HTTP-date arm and fails there. Digit strings larger
455        // than u64::MAX saturate to u64::MAX so valid long cooldowns clamp
456        // to MAX_RETRY_AFTER_OBEYED instead of silently falling back to None.
457        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/// Apply deterministic ±20% jitter to a backoff duration.
468///
469/// The jitter is keyed by a caller-provided monotonic nonce so scan traces stay
470/// reproducible while avoiding synchronized retries across concurrent clients.
471#[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/// Human-like inter-request pacing policy.
489///
490/// `RequestPacer` is the single source of truth for *request* pacing (HTTP
491/// client delays, browser navigation gaps) and *behavioral* timing (pre-action
492/// think time, hover dwell, idle pauses). It samples from a bounded normal
493/// distribution and adjusts to rate-limit / challenge signals so the delay
494/// grows like a human who slows down when a site pushes back.
495#[derive(Debug, Clone, Copy, PartialEq, Eq)]
496pub struct RequestPacer {
497    base: BoundedNormalDelay,
498    challenge_multiplier: u32,
499}
500
501impl RequestPacer {
502    /// Hard ceiling on the challenge backoff multiplier.
503    pub const MAX_CHALLENGE_MULTIPLIER: u32 = 16;
504
505    /// Build a pacer from an explicit base delay distribution.
506    #[must_use]
507    pub const fn new(base: BoundedNormalDelay) -> Self {
508        Self {
509            base,
510            challenge_multiplier: 1,
511        }
512    }
513
514    /// Pacing between page loads: 800–3 000 ms, matching a human who takes in
515    /// the page before the next navigation (also `ActionDelay::after_page_load`).
516    #[must_use]
517    pub fn page_load() -> Self {
518        Self::new(BoundedNormalDelay::from_unordered_bounds(800, 3_000))
519    }
520
521    /// Pacing between sub-resource requests (favicon, prefetch, images): 100–400 ms.
522    #[must_use]
523    pub fn sub_resource() -> Self {
524        Self::new(BoundedNormalDelay::from_unordered_bounds(100, 400))
525    }
526
527    /// Pacing for API / fetch calls: 300–1 200 ms.
528    #[must_use]
529    pub fn api_call() -> Self {
530        Self::new(BoundedNormalDelay::from_unordered_bounds(300, 1_200))
531    }
532
533    /// Current challenge multiplier (1 = no penalty).
534    #[must_use]
535    pub const fn challenge_multiplier(self) -> u32 {
536        self.challenge_multiplier
537    }
538    /// Get the underlying base delay distribution.
539    #[must_use]
540    pub const fn base(self) -> BoundedNormalDelay {
541        self.base
542    }
543
544    /// Record a successful response so the pacer can decay any challenge
545    /// penalty back toward normal pacing.
546    pub fn record_success(&mut self) {
547        self.challenge_multiplier = self.challenge_multiplier.saturating_sub(1).max(1);
548    }
549
550    /// Record a rate-limit / challenge signal (429, 403, captcha challenge).
551    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    /// Convenience: update state from an HTTP status code.
557    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    /// Sample the next delay from the current distribution and multiplier.
567    ///
568    /// The multiplication saturates and the result is clamped to
569    /// [`MAX_PACING_BACKOFF`], so a hostile base envelope (for example a
570    /// `u64::MAX` millisecond upper bound from misordered config) cannot panic
571    /// the process or sleep it effectively forever.
572    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    /// Sample the next delay using the process-local RNG.
579    #[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        // Both are sampled from the same bounded normal envelope, but the
971        // challenged pacer multiplies by 2. It must be larger and stay within
972        // the doubled profile bounds (300–1 200 ms → 600–2 400 ms).
973        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        // One nanosecond past the hard ceiling must return the ceiling, not
1020        // `Duration::from_nanos(u64::MAX)` (~584 years).
1021        let ceiling = Duration::from_secs(60);
1022        let delay = duration_from_nanos_clamped(u128::MAX, ceiling);
1023        assert_eq!(delay, ceiling);
1024    }
1025
1026    /// Regression: `RequestPacer::next_delay` used a plain `Duration *
1027    /// u32` multiply. A hostile base envelope (an upper bound near
1028    /// `u64::MAX` milliseconds, reachable through
1029    /// `BoundedNormalDelay::from_unordered_bounds`) combined with a challenge
1030    /// multiplier overflowed the multiplication and panicked the process. The
1031    /// delay must saturate and clamp to `MAX_PACING_BACKOFF` instead, because
1032    /// a stealth pacer that crashes or sleeps for centuries fails the scan
1033    /// loudly in the wrong way.
1034    #[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    /// The challenge multiplier must still scale ordinary delays after the
1048    /// saturation fix: a multiplier of 2 on the API-call envelope doubles the
1049    /// upper bound from 1 200 ms to 2 400 ms, well under the ceiling.
1050    #[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    /// Regression: `BackoffPolicy::delay` returned the raw saturating power
1065    /// of two with no ceiling, so a configured base of one hour produced
1066    /// retry sleeps of hours while the crate documents `MAX_PACING_BACKOFF`
1067    /// as the hard ceiling on every delay it produces. Scanners must fail
1068    /// visibly within a minute, not sleep for a session.
1069    #[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    /// Regression: `parse_retry_after` accepted a signed delta like `"+5"`
1080    /// because it parsed the token as `i64`. RFC 9110 delta-seconds is
1081    /// `1*DIGIT` with no sign. Accepting a signed token drifts from what a
1082    /// standards-reading server (or WAF probe) sends and from what sibling
1083    /// parsers accept.
1084    #[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    /// Regression: `parse_retry_after` previously returned `None` when given a
1092    /// delta-seconds header whose digits overflowed `u64`. A valid long
1093    /// cooldown requested by a server must saturate and clamp to
1094    /// `MAX_RETRY_AFTER_OBEYED` rather than silently falling back to zero delay.
1095    #[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    /// Regression: `capped_exponential_backoff` with a `max_ms` exceeding
1106    /// `MAX_PACING_BACKOFF` (e.g. 5 minutes or `u64::MAX`) leaked the larger
1107    /// cap instead of clamping to the 60s fleet pacing ceiling.
1108    #[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    /// Proving test: `BoundedNormalDelay` with `f64::EPSILON` lower bound on Box-Muller $u_1$
1121    /// allows sampling the full range `[min_ms, max_ms]` including the extreme tails
1122    /// near `min_ms` and `max_ms`. Under the old `0.001..1.0` range, $Z$ was truncated at
1123    /// 3.717 $\sigma$, which prevented sampling the outer ~3.5% of the envelope.
1124    #[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 inspectability getters on `BackoffPolicy` and `RequestPacer`.
1154    #[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}