ilpanich / axiam-rust-sdk / 31325324461

94%

Build Type

push

github

Committed by web-flow

Commit Message

feat: contract 1.8 — §16 retry, §17 memo, §18 close(), §19 telemetry (D5) (#45)

* feat(retry,telemetry): §16 retry policy and §19 hooks; contract 1.8 re-sync

Re-vendors CONTRACT.md at 1.8 and lands the two foundation modules the rest of
D5 builds on. Wiring them into the authz surface, plus §17's decision memo and
§18's close(), follow in this branch.

§16 — the policy that was being required but never defined. §11.2 rule 5 and
§14.2 rule 6 had both been telling SDKs to retry "under the SDK's existing
bounded read-only retry policy" while no such policy existed in the contract.
This crate's improvisation was backon's ExponentialBuilder defaults with
with_max_times(2): no jitter, no Retry-After. Contract 1.8 wrote the table
down; src/retry.rs implements it.

Hand-rolled rather than reconfigured, for two reasons backon cannot express:

- Full jitter. §16.1 requires the wait to be uniform over [0, backoff].
  backon's with_jitter() adds a random value in [0, min_delay) on top of the
  backoff — a much narrower distribution. The difference is the entire point
  of the clause: partial jitter keeps every client's retries clustered around
  the same instant, causing the thundering herd retries are meant to prevent.
- Retry-After. backon has no seam for a server-supplied floor on the wait.

Both non-deterministic inputs are injected behind traits (Jitter, Sleeper), as
§16.7 demands — "a test that really waits 200 ms is a test nobody runs". The
tests pin the jitter fraction to 0.0 and 1.0 to prove the range really is
[0, backoff] and not backoff ± something, and record delays instead of taking
them, so the whole file runs in 0.12 s.

Two design points worth flagging:

- Retry-After is NOT clamped to the 5 s delay cap. My first implementation
  clamped it and my own test caught the contradiction: that cap governs the
  computed backoff, while §16.1 makes the hint a floor with no ceiling.
  Clamping it would retry sooner than the server said it would be ready,... (continued)

Coverage Stats

601 of 612 new or added lines in 6 files covered. (98.2%)

38 existing lines in 2 files now uncovered.

4996 of 5243 relevant lines covered (95.29%)

31.37 hits per line