axiam-sdk 1.2.2

Official Rust client SDK for AXIAM IAM
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
//! Bounded read-only retry policy — CONTRACT.md §16.
//!
//! Until contract 1.8 this policy did not exist. §11.2 rule 5 and §14.2 rule 6
//! had both been *requiring* retries "under the SDK's existing bounded
//! read-only retry policy" while no such policy was written down anywhere, so
//! each SDK invented one — this crate's was `backon`'s defaults with
//! `with_max_times(2)`, which has no jitter and ignores `Retry-After`. §16 is
//! the table those clauses had been pointing at all along; this module is that
//! table.
//!
//! # Why this is hand-rolled rather than `backon`
//!
//! §16 requires **full jitter**: the wait is uniform over `[0, backoff]`.
//! `backon`'s `with_jitter()` adds a random value in `[0, min_delay)` on top of
//! the computed backoff, which is a different (and much narrower) distribution.
//! The distinction is the whole point of the clause — partial jitter keeps
//! every client's retries clustered around the same instant, which causes the
//! thundering herd retries are supposed to avoid. `backon` also has no seam for
//! honoring `Retry-After`, which §16.1 makes a floor on the wait.
//!
//! # Testability
//!
//! §16.7 forbids proving this with real sleeps ("a test that really waits
//! 200 ms is a test nobody runs"), so both non-deterministic inputs are
//! injected: [`Jitter`] supplies the random fraction and [`Sleeper`] supplies
//! the wait. Production uses [`ThreadRngJitter`] and [`TokioSleeper`]; tests
//! pin the fraction to 0.0 and 1.0 to assert the range really is `[0, backoff]`
//! and record delays instead of taking them.

use std::future::Future;
use std::time::Duration;

use crate::error::AxiamError;
use crate::telemetry::{Telemetry, TelemetryEvent};

/// Attempt cap: 1 initial + 2 retries (§16.1).
pub const MAX_ATTEMPTS: u32 = 3;
/// First backoff step (§16.1).
pub const BASE_DELAY: Duration = Duration::from_millis(200);
/// Ceiling on any single wait (§16.1).
pub const MAX_DELAY: Duration = Duration::from_secs(5);

/// Source of the jitter fraction, in `[0.0, 1.0]`.
///
/// §16.1 notes this need not be cryptographic: the jitter is a load-spreading
/// device, not a secret.
pub(crate) trait Jitter: Send + Sync {
    /// Returns a value in `[0.0, 1.0]`.
    fn fraction(&self) -> f64;
}

/// Production jitter source.
pub(crate) struct ThreadRngJitter;

impl Jitter for ThreadRngJitter {
    fn fraction(&self) -> f64 {
        // Uniform in [0, 1) from 8 bytes of OS randomness. `getrandom` is
        // already an unconditional transitive dependency of the `rest` feature
        // (see Cargo.toml), so this adds nothing to the dependency tree.
        let mut buf = [0u8; 8];
        if getrandom::fill(&mut buf).is_err() {
            // A randomness failure must not fail an authorization check. Fall
            // back to the full backoff — correct, merely unjittered.
            return 1.0;
        }
        // 53-bit mantissa: the standard way to get a uniform f64 in [0, 1).
        (u64::from_le_bytes(buf) >> 11) as f64 / (1u64 << 53) as f64
    }
}

/// Waits. Injected so tests record instead of sleeping.
pub(crate) trait Sleeper: Send + Sync {
    fn sleep(&self, d: Duration) -> std::pin::Pin<Box<dyn Future<Output = ()> + Send + '_>>;
}

/// Production sleeper.
pub(crate) struct TokioSleeper;

impl Sleeper for TokioSleeper {
    fn sleep(&self, d: Duration) -> std::pin::Pin<Box<dyn Future<Output = ()> + Send + '_>> {
        Box::pin(tokio::time::sleep(d))
    }
}

/// The un-jittered backoff for `attempt` (1-based): `min(cap, base * 2^(n-1))`.
///
/// attempt 1 → 200 ms, attempt 2 → 400 ms — both under the 5 s cap, which only
/// binds if the attempt cap is ever raised.
pub(crate) fn backoff_for(attempt: u32) -> Duration {
    let shift = attempt.saturating_sub(1).min(32);
    BASE_DELAY
        .saturating_mul(1u32.checked_shl(shift).unwrap_or(u32::MAX))
        .min(MAX_DELAY)
}

/// The actual wait: full jitter over `[0, backoff]`, then raised to any
/// server-supplied `Retry-After` (§16.1).
///
/// `Retry-After` is a **floor, never a ceiling**: the server is telling you
/// when it will be ready, so retrying sooner is not permitted — and a
/// `Retry-After: 0` cannot shorten the backoff below what jitter chose.
pub(crate) fn delay_for(
    attempt: u32,
    retry_after: Option<Duration>,
    jitter: &dyn Jitter,
) -> Duration {
    let backoff = backoff_for(attempt);
    let fraction = jitter.fraction().clamp(0.0, 1.0);
    let jittered = backoff.mul_f64(fraction);
    match retry_after {
        Some(hint) => jittered.max(hint),
        None => jittered,
    }
}

/// Is an HTTP status worth another attempt? (§16.3: `408`, `429` and `5xx`.)
///
/// For the non-management call sites that classify a response themselves
/// before handing the error to [`RetryRunner`]: §2 folds a bodiless `400`
/// into `Network` too, and a `4xx` other than `408`/`429` is a decisive answer
/// that a retry reproduces.
pub(crate) fn status_is_retryable(status: u16) -> bool {
    status >= 500 || status == 408 || status == 429
}

/// Is this failure worth another attempt? (§16.3)
///
/// The §2 taxonomy folds 408/429/5xx/transport all into `Network`, so "retry
/// `Network` only" implements the whole table: `Auth`, `Authz`, validation and
/// `OAuthProtocolError` are decisive answers, not transport failures, and
/// retrying an unacceptable request reproduces the identical rejection.
pub(crate) fn is_retryable(err: &AxiamError) -> bool {
    matches!(err, AxiamError::Network { .. })
}

/// One failed attempt: the error the caller will eventually see, plus the
/// server's `Retry-After` hint if the response carried one.
///
/// The hint rides here rather than on [`AxiamError`] deliberately. §16 requires
/// the policy to *honor* `Retry-After`; it does not require callers to be able
/// to read it, and adding a field to the public `Network` variant would churn
/// every construction site in the crate for something no caller asked for. The
/// hint is consumed entirely inside this module and then dropped.
pub(crate) struct Attempt {
    pub(crate) err: AxiamError,
    pub(crate) retry_after: Option<Duration>,
}

impl Attempt {
    /// A failure with no server hint.
    pub(crate) fn bare(err: AxiamError) -> Self {
        Self {
            err,
            retry_after: None,
        }
    }
}

/// Parse an HTTP `Retry-After` header value.
///
/// RFC 9110 permits either delta-seconds or an HTTP-date. Only delta-seconds is
/// honored: the date form requires trusting the client's clock to be in sync
/// with the server's, and a skewed clock would turn the hint into either a
/// no-op or a multi-hour stall. An unparseable value is simply absent, which
/// falls back to the jittered backoff — always a safe answer.
///
/// The value is **not** clamped to [`MAX_DELAY`]. That cap governs the computed
/// backoff; §16.1 makes `Retry-After` a floor with no ceiling, and clamping it
/// would mean retrying *sooner* than the server said it would be ready — the
/// one thing the clause forbids. Total exposure stays bounded by the attempt
/// cap, and a server that wants to stall a client can simply not answer, so a
/// ceiling here would buy nothing.
pub(crate) fn parse_retry_after(value: &str) -> Option<Duration> {
    let secs: u64 = value.trim().parse().ok()?;
    Some(Duration::from_secs(secs))
}

/// Runs `op` under the §16 policy.
///
/// `op` MUST be side-effect-free: §16.2 restricts eligibility to operations
/// that change no server state, and this helper — like every retry helper —
/// cannot tell the difference. Routing a mutation through it would silently
/// duplicate a side effect, or replay a single-use credential into a hard
/// `invalid_grant`.
pub(crate) struct RetryRunner<'a> {
    pub(crate) enabled: bool,
    pub(crate) operation: &'static str,
    pub(crate) telemetry: &'a Telemetry,
    pub(crate) jitter: &'a dyn Jitter,
    pub(crate) sleeper: &'a dyn Sleeper,
}

/// A deadline that bounds a retry's wait (contract 1.60, P10: a §16 retry
/// inside `ciba_poll`, as `ciba_await` calls it, MUST NOT wait past the
/// request's deadline). `now` and `sleeper` are the caller's own clock, so the
/// bound is testable without sleeping and is served on the same clock as the
/// loop's other waits.
pub(crate) struct RetryBound<'a> {
    /// The instant after which no request may be sent.
    pub(crate) deadline: crate::time::Instant,
    /// The caller's clock reading.
    pub(crate) now: &'a (dyn Fn() -> crate::time::Instant + Send + Sync),
    /// Serves a wait on the caller's clock.
    pub(crate) sleeper: &'a dyn Sleeper,
}

/// Why a bounded run ended without a value.
pub(crate) struct Ended {
    /// The last attempt's failure.
    pub(crate) err: AxiamError,
    /// True when the retry's wait was capped at the deadline and served: no
    /// request follows it, and the caller reports its own deadline outcome.
    pub(crate) at_deadline: bool,
    /// The last attempt's `Retry-After`, if it carried one. A caller whose own
    /// loop polls again next (§14.2 rule 6) waits at least that long: §16.1
    /// makes the hint a floor, and an exhausted budget does not lift it.
    pub(crate) retry_after: Option<Duration>,
}

impl RetryRunner<'_> {
    pub(crate) async fn run<T, F, Fut>(&self, op: F) -> Result<T, AxiamError>
    where
        F: FnMut(u32) -> Fut,
        Fut: Future<Output = Result<T, Attempt>>,
    {
        self.run_until(None, op).await.map_err(|ended| ended.err)
    }

    /// [`Self::run`] with an optional deadline. With one, a retry's wait — the
    /// jittered backoff raised to `Retry-After` — is capped at the time left,
    /// the wait is served on the bound's own clock, and when the wait ends at
    /// the deadline no request follows ([`Ended::at_deadline`]). `None` is
    /// [`Self::run`] exactly.
    pub(crate) async fn run_until<T, F, Fut>(
        &self,
        bound: Option<&RetryBound<'_>>,
        mut op: F,
    ) -> Result<T, Ended>
    where
        F: FnMut(u32) -> Fut,
        Fut: Future<Output = Result<T, Attempt>>,
    {
        // §16.1: the disable switch yields exactly one attempt. Some callers
        // own their own retry layer and want the SDK out of the way.
        let cap = if self.enabled { MAX_ATTEMPTS } else { 1 };

        let mut attempt = 1;
        loop {
            match op(attempt).await {
                Ok(v) => return Ok(v),
                Err(Attempt { err, retry_after }) => {
                    let last = attempt >= cap;
                    if last || !is_retryable(&err) {
                        return Err(Ended {
                            err,
                            at_deadline: false,
                            retry_after,
                        });
                    }
                    let mut delay = delay_for(attempt, retry_after, self.jitter);
                    let mut at_deadline = false;
                    if let Some(bound) = bound {
                        let left = bound.deadline.saturating_duration_since((bound.now)());
                        if delay >= left {
                            delay = left;
                            at_deadline = true;
                        }
                    }
                    self.telemetry.emit(TelemetryEvent::Retry {
                        operation: self.operation,
                        attempt,
                        delay,
                        // `AxiamError`'s Display is already redacted per §2 —
                        // it never carries a token.
                        reason: err.to_string(),
                    });
                    match bound {
                        Some(bound) => {
                            if !delay.is_zero() {
                                bound.sleeper.sleep(delay).await;
                            }
                        }
                        None => self.sleeper.sleep(delay).await,
                    }
                    if at_deadline {
                        return Err(Ended {
                            err,
                            at_deadline: true,
                            retry_after,
                        });
                    }
                    attempt += 1;
                }
            }
        }
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    struct Pinned(f64);
    impl Jitter for Pinned {
        fn fraction(&self) -> f64 {
            self.0
        }
    }

    #[test]
    fn backoff_doubles_from_the_base_and_stops_at_the_cap() {
        assert_eq!(backoff_for(1), Duration::from_millis(200));
        assert_eq!(backoff_for(2), Duration::from_millis(400));
        // The cap only binds well past the 3-attempt cap, but it must bind.
        assert_eq!(backoff_for(20), MAX_DELAY);
        // And must not overflow at absurd attempt numbers.
        assert_eq!(backoff_for(u32::MAX), MAX_DELAY);
    }

    #[test]
    fn full_jitter_spans_zero_to_the_whole_backoff() {
        // This is the assertion that distinguishes full jitter from
        // `backoff ± something`: pinned to 0 the wait is 0, pinned to 1 it is
        // the entire backoff. Anything narrower is a different distribution.
        assert_eq!(delay_for(1, None, &Pinned(0.0)), Duration::ZERO);
        assert_eq!(delay_for(1, None, &Pinned(1.0)), Duration::from_millis(200));
        assert_eq!(delay_for(2, None, &Pinned(1.0)), Duration::from_millis(400));
        assert_eq!(delay_for(2, None, &Pinned(0.5)), Duration::from_millis(200));
    }

    #[test]
    fn retry_after_raises_the_wait_but_never_lowers_it() {
        // Longer than the backoff: the server wins.
        assert_eq!(
            delay_for(1, Some(Duration::from_secs(2)), &Pinned(1.0)),
            Duration::from_secs(2)
        );
        // Shorter than the backoff: the backoff stands. A `Retry-After: 0`
        // must not be able to defeat the policy.
        assert_eq!(
            delay_for(1, Some(Duration::ZERO), &Pinned(1.0)),
            Duration::from_millis(200)
        );
        // Even against a zero-jitter wait, the hint is still a floor.
        assert_eq!(
            delay_for(1, Some(Duration::from_millis(50)), &Pinned(0.0)),
            Duration::from_millis(50)
        );
    }

    #[test]
    fn a_jitter_fraction_outside_the_range_is_clamped() {
        assert_eq!(delay_for(1, None, &Pinned(9.0)), Duration::from_millis(200));
        assert_eq!(delay_for(1, None, &Pinned(-1.0)), Duration::ZERO);
    }

    #[test]
    fn only_network_failures_are_retryable() {
        // The §2 taxonomy folds 408/429/5xx/transport into `Network`, so this
        // one predicate implements the whole §16.3 table.
        assert!(is_retryable(&AxiamError::network("boom")));
        assert!(!is_retryable(&AxiamError::auth("nope")));
        assert!(!is_retryable(&AxiamError::authz("denied", None, None)));
    }

    #[test]
    fn retry_after_parses_delta_seconds_and_ignores_the_date_form() {
        assert_eq!(parse_retry_after("3"), Some(Duration::from_secs(3)));
        assert_eq!(parse_retry_after("  7 "), Some(Duration::from_secs(7)));
        assert_eq!(parse_retry_after("0"), Some(Duration::ZERO));
        // The HTTP-date form is deliberately not honored: it would require
        // trusting the client clock to agree with the server's, and a skewed
        // clock turns the hint into a no-op or a multi-hour stall.
        assert_eq!(parse_retry_after("Wed, 21 Oct 2026 07:28:00 GMT"), None);
        assert_eq!(parse_retry_after("garbage"), None);
        assert_eq!(parse_retry_after("-5"), None);
        // Not clamped to MAX_DELAY: that cap governs the computed backoff,
        // while §16.1 makes the hint a floor with no ceiling. Clamping would
        // retry sooner than the server said it would be ready.
        assert_eq!(
            parse_retry_after("86400"),
            Some(Duration::from_secs(86_400))
        );
    }

    /// Records delays instead of taking them, so the attempt-cap and
    /// delay-sequence tests run instantly (§16.7).
    #[derive(Default)]
    struct RecordingSleeper {
        delays: std::sync::Mutex<Vec<Duration>>,
    }
    impl Sleeper for RecordingSleeper {
        fn sleep(&self, d: Duration) -> std::pin::Pin<Box<dyn Future<Output = ()> + Send + '_>> {
            self.delays.lock().unwrap().push(d);
            Box::pin(std::future::ready(()))
        }
    }

    fn runner<'a>(
        enabled: bool,
        telemetry: &'a Telemetry,
        jitter: &'a dyn Jitter,
        sleeper: &'a dyn Sleeper,
    ) -> RetryRunner<'a> {
        RetryRunner {
            enabled,
            operation: "check_access",
            telemetry,
            jitter,
            sleeper,
        }
    }

    #[tokio::test]
    async fn a_permanently_failing_operation_makes_exactly_three_attempts() {
        let tel = Telemetry::default();
        let sleeper = RecordingSleeper::default();
        let calls = std::sync::atomic::AtomicU32::new(0);

        let out: Result<(), _> = runner(true, &tel, &Pinned(1.0), &sleeper)
            .run(|_| {
                calls.fetch_add(1, std::sync::atomic::Ordering::SeqCst);
                async { Err(Attempt::bare(AxiamError::network("down"))) }
            })
            .await;

        assert!(out.is_err());
        // Exactly 3 — not 2, not 4. The cap is the whole point of "bounded".
        assert_eq!(calls.load(std::sync::atomic::Ordering::SeqCst), 3);
        // …and the delay sequence with jitter pinned to its maximum.
        assert_eq!(
            *sleeper.delays.lock().unwrap(),
            vec![Duration::from_millis(200), Duration::from_millis(400)]
        );
    }

    #[tokio::test]
    async fn a_decisive_failure_makes_exactly_one_attempt() {
        // A 401 and a 403 are answers, not transport failures. Retrying either
        // reproduces the identical rejection and wastes the caller's latency.
        for decisive in ["auth", "authz"] {
            let tel = Telemetry::default();
            let sleeper = RecordingSleeper::default();
            let calls = std::sync::atomic::AtomicU32::new(0);

            let out: Result<(), _> = runner(true, &tel, &Pinned(1.0), &sleeper)
                .run(|_| {
                    calls.fetch_add(1, std::sync::atomic::Ordering::SeqCst);
                    async move {
                        Err(Attempt::bare(if decisive == "auth" {
                            AxiamError::auth("401")
                        } else {
                            AxiamError::authz("403", None, None)
                        }))
                    }
                })
                .await;

            assert!(out.is_err(), "{decisive} must surface");
            assert_eq!(
                calls.load(std::sync::atomic::Ordering::SeqCst),
                1,
                "{decisive} must not be retried"
            );
            assert!(sleeper.delays.lock().unwrap().is_empty());
        }
    }

    #[tokio::test]
    async fn the_disable_switch_yields_exactly_one_attempt_even_on_a_503() {
        // The switch exists for callers who own their own retry layer. With it
        // off, a retryable failure must still be surfaced after one attempt.
        let tel = Telemetry::default();
        let sleeper = RecordingSleeper::default();
        let calls = std::sync::atomic::AtomicU32::new(0);

        let out: Result<(), _> = runner(false, &tel, &Pinned(1.0), &sleeper)
            .run(|_| {
                calls.fetch_add(1, std::sync::atomic::Ordering::SeqCst);
                async { Err(Attempt::bare(AxiamError::network("503"))) }
            })
            .await;

        assert!(out.is_err());
        assert_eq!(calls.load(std::sync::atomic::Ordering::SeqCst), 1);
        assert!(sleeper.delays.lock().unwrap().is_empty());
    }

    #[tokio::test]
    async fn a_retry_that_then_succeeds_returns_the_value_and_emits_the_event() {
        // §16.5: a retried-then-succeeded call is otherwise invisible to the
        // caller — a slow success with no signal the server is failing.
        let events = std::sync::Arc::new(std::sync::Mutex::new(Vec::<String>::new()));
        let sink_events = events.clone();
        let tel = Telemetry::new(Some(std::sync::Arc::new(move |e: &TelemetryEvent| {
            if let TelemetryEvent::Retry { attempt, delay, .. } = e {
                sink_events
                    .lock()
                    .unwrap()
                    .push(format!("retry {attempt} {delay:?}"));
            }
        })));
        let sleeper = RecordingSleeper::default();
        let calls = std::sync::atomic::AtomicU32::new(0);

        let out = runner(true, &tel, &Pinned(1.0), &sleeper)
            .run(|_| {
                let n = calls.fetch_add(1, std::sync::atomic::Ordering::SeqCst);
                async move {
                    if n == 0 {
                        Err(Attempt::bare(AxiamError::network("transient")))
                    } else {
                        Ok(42u32)
                    }
                }
            })
            .await;

        assert_eq!(out.unwrap(), 42);
        assert_eq!(calls.load(std::sync::atomic::Ordering::SeqCst), 2);
        assert_eq!(events.lock().unwrap().len(), 1);
        assert!(events.lock().unwrap()[0].starts_with("retry 1 "));
    }

    #[tokio::test]
    async fn a_panicking_hook_does_not_fail_the_operation() {
        // §19.2 rule 2 — telemetry may not fail an authorization check.
        let tel = Telemetry::new(Some(std::sync::Arc::new(|_: &TelemetryEvent| {
            panic!("hook exploded");
        })));
        let sleeper = RecordingSleeper::default();
        let calls = std::sync::atomic::AtomicU32::new(0);

        let out = runner(true, &tel, &Pinned(0.0), &sleeper)
            .run(|_| {
                let n = calls.fetch_add(1, std::sync::atomic::Ordering::SeqCst);
                async move {
                    if n == 0 {
                        Err(Attempt::bare(AxiamError::network("transient")))
                    } else {
                        Ok(7u32)
                    }
                }
            })
            .await;

        assert_eq!(out.unwrap(), 7);
    }

    #[tokio::test]
    async fn a_server_hint_lengthens_the_recorded_wait() {
        let tel = Telemetry::default();
        let sleeper = RecordingSleeper::default();

        let out: Result<(), _> = runner(true, &tel, &Pinned(1.0), &sleeper)
            .run(|_| async {
                Err(Attempt {
                    err: AxiamError::network("429"),
                    retry_after: Some(Duration::from_secs(2)),
                })
            })
            .await;

        assert!(out.is_err());
        assert_eq!(
            *sleeper.delays.lock().unwrap(),
            vec![Duration::from_secs(2), Duration::from_secs(2)]
        );
    }

    /// A hand-wound clock: `sleep` advances it, so a bound is testable
    /// without sleeping.
    struct Wound {
        start: crate::time::Instant,
        offset: std::sync::Mutex<Duration>,
        waits: std::sync::Mutex<Vec<Duration>>,
    }
    impl Wound {
        fn new() -> Self {
            Self {
                start: crate::time::Instant::now(),
                offset: Default::default(),
                waits: Default::default(),
            }
        }
        fn now(&self) -> crate::time::Instant {
            self.start + *self.offset.lock().unwrap()
        }
    }
    impl Sleeper for Wound {
        fn sleep(&self, d: Duration) -> std::pin::Pin<Box<dyn Future<Output = ()> + Send + '_>> {
            *self.offset.lock().unwrap() += d;
            self.waits.lock().unwrap().push(d);
            Box::pin(std::future::ready(()))
        }
    }

    #[tokio::test]
    async fn a_bound_caps_the_wait_at_the_deadline_and_no_request_follows_it() {
        let tel = Telemetry::default();
        let unused = RecordingSleeper::default();
        let clock = Wound::new();
        let now = || clock.now();
        let bound = RetryBound {
            deadline: clock.start + Duration::from_secs(7),
            now: &now,
            sleeper: &clock,
        };
        let calls = std::sync::atomic::AtomicU32::new(0);

        let out: Result<(), _> = runner(true, &tel, &Pinned(1.0), &unused)
            .run_until(Some(&bound), |_| {
                calls.fetch_add(1, std::sync::atomic::Ordering::SeqCst);
                async {
                    Err(Attempt {
                        err: AxiamError::network("503"),
                        retry_after: Some(Duration::from_secs(3600)),
                    })
                }
            })
            .await;

        let ended = out.expect_err("the deadline ends the run");
        assert!(ended.at_deadline);
        assert_eq!(calls.load(std::sync::atomic::Ordering::SeqCst), 1);
        assert_eq!(*clock.waits.lock().unwrap(), vec![Duration::from_secs(7)]);
        assert!(
            unused.delays.lock().unwrap().is_empty(),
            "the wait is served on the bound's clock, not the runner's"
        );
    }

    #[tokio::test]
    async fn a_bound_leaves_a_wait_that_ends_before_the_deadline_alone() {
        let tel = Telemetry::default();
        let unused = RecordingSleeper::default();
        let clock = Wound::new();
        let now = || clock.now();
        let bound = RetryBound {
            deadline: clock.start + Duration::from_secs(7),
            now: &now,
            sleeper: &clock,
        };
        let calls = std::sync::atomic::AtomicU32::new(0);

        let out = runner(true, &tel, &Pinned(0.0), &unused)
            .run_until(Some(&bound), |_| {
                let n = calls.fetch_add(1, std::sync::atomic::Ordering::SeqCst);
                async move {
                    if n == 0 {
                        Err(Attempt {
                            err: AxiamError::network("503"),
                            retry_after: Some(Duration::from_secs(2)),
                        })
                    } else {
                        Ok(1u32)
                    }
                }
            })
            .await;

        assert_eq!(out.ok(), Some(1));
        assert_eq!(*clock.waits.lock().unwrap(), vec![Duration::from_secs(2)]);
    }

    #[tokio::test]
    async fn no_bound_is_the_plain_policy() {
        let tel = Telemetry::default();
        let sleeper = RecordingSleeper::default();
        let out: Result<(), _> = runner(true, &tel, &Pinned(1.0), &sleeper)
            .run_until(None, |_| async {
                Err(Attempt {
                    err: AxiamError::network("503"),
                    retry_after: Some(Duration::from_secs(3600)),
                })
            })
            .await;
        assert!(!out.expect_err("exhausted").at_deadline);
        assert_eq!(
            *sleeper.delays.lock().unwrap(),
            vec![Duration::from_secs(3600), Duration::from_secs(3600)],
            "an unbounded Retry-After is a floor with no ceiling (§16.1)"
        );
    }

    #[test]
    fn the_production_jitter_source_stays_in_range() {
        let j = ThreadRngJitter;
        for _ in 0..1_000 {
            let f = j.fraction();
            assert!((0.0..=1.0).contains(&f), "fraction out of range: {f}");
        }
    }
}