From 4f59fa33429d6cabd9a9d99b20ce97ea66141b64 Mon Sep 17 00:00:00 2001 From: Nils Lehnen <30603423+iderex@users.noreply.github.com> Date: Fri, 18 Sep 2026 06:07:41 +0200 Subject: [PATCH] Give the failure module's two absences the reasons that hold, which are the request and the division of labour `src/failure/mod.rs` heads a section "What is not here, said once so a green build is not read as covering it", and two of the three statements in it rested on reasons the tree refutes. The first said no caller in this tree reaches any of it yet, and named #27, #39 and #49 as why. Four modules reach it in code no `#[cfg(test)]` covers: `src/lifecycle/mod.rs:486` builds a cancellation, `src/playback/handover.rs:865` builds 0111's refusal, `src/server/destinations.rs:260` builds a refused redirect, and `src/server/retry.rs:471` reads these variants to decide what a call does next. Those files begin their test modules at 533, 881, 272 and 499. The sentence landed on 2026-08-28 and the first of the four on 2026-08-31, in a change that had no reason to open this header, with three more by 2026-09-03; none of them came from the three issues named as the reason, because a module does not need a transport to build a refusal out of what it has already decided. What that statement is for survives with the reason that holds: no request is made anywhere in this library, so nothing here has been built out of an answer a server sent. The set of modules that reach the point is derived rather than carried, with `git grep -n 'use crate::failure' -- 'src/**/*.rs'` handed to the reader and its bound stated - it counts a test module's own import too. The second said the retry-after hint is carried as given or absent because #38 is not built. 0038's policy is in the tree: `src/server/retry.rs` holds the attempt ceiling, the interval the first wait is drawn over and the deadline an attempt needs, and its own arm draws an interval where no hint was given, from 2026-08-31. The statement keeps what it is about - this type invents no number - and gives the division of labour as the reason instead. The third statement, that `answer-not-understood` carries an offset and a reading site rather than a field name because nothing here parses a body, was re-read and still holds. It is untouched. No behaviour changes. The edit is doc comments. Closes #447 Signed-off-by: Nils Lehnen <30603423+iderex@users.noreply.github.com> --- src/failure/mod.rs | 41 +++++++++++++++++++++++++++++++++++------ 1 file changed, 35 insertions(+), 6 deletions(-) diff --git a/src/failure/mod.rs b/src/failure/mod.rs index 62bc8c7..b04a917 100644 --- a/src/failure/mod.rs +++ b/src/failure/mod.rs @@ -43,16 +43,45 @@ //! //! # What is not here, said once so a green build is not read as covering it //! -//! **No caller in this tree reaches any of it yet.** The transport is #27, the -//! query surface is #39 and the artwork fetch is #49, so what exists today is the -//! point and the suite that drives it. 0037 already says the honest proof that +//! **No request is made anywhere in this library, so nothing here has been built +//! out of an answer a server sent.** The transport is #27, the query surface is +//! #39 and the artwork fetch is #49, so every value built today is built from +//! something a module already decided. 0037 already says the honest proof that //! every failure went through this point is a check over the tree rather than a //! test, because a test proves the sites it reached. //! +//! THIS SAID NO CALLER IN THIS TREE REACHED ANY OF IT YET, AND FOUR MODULES +//! REACHED IT OUTSIDE EVERY TEST MODULE. [`crate::lifecycle`] builds a +//! cancellation, [`crate::playback::handover`] builds 0111's refusal, +//! [`crate::server::destinations`] builds a refused redirect, and +//! [`crate::server::retry`] reads these variants to decide what a call does next; +//! every one of those lines is above its own file's `#[cfg(test)]`. The sentence +//! landed on 2026-08-28 and the first of the four on 2026-08-31, in a change that +//! had no reason to open this header, with three more by 2026-09-03. The three +//! issues named above were not what they came from: a module does not need a +//! transport to build a refusal out of what it has already decided. Which modules +//! reach this point is not carried here from now on, because a list goes stale on +//! the next landing and nothing in this tree reads one: +//! +//! ```text +//! git grep -n 'use crate::failure' -- 'src/**/*.rs' +//! ``` +//! +//! That names every module importing these types, a test module's own import +//! included, so a reader who wants the library's own sites reads its line numbers +//! against each file's `#[cfg(test)]`. #447 is where it was found. +//! //! **The retry-after hint 0004 describes as given or assumed is carried as given -//! or absent.** The assumed value is a delay 0038 decides and #38 is not built, so -//! no number is invented here, and a caller sees the absence rather than a -//! duration nothing chose. +//! or absent.** No number is invented here, and a caller sees the absence rather +//! than a duration nothing chose. +//! +//! THE REASON GIVEN FOR THAT WAS THAT #38 IS NOT BUILT, AND 0038'S POLICY IS IN +//! THE TREE. [`crate::server::retry`] holds the attempt ceiling, the interval the +//! first wait is drawn over and the deadline an attempt needs, and its own arm +//! draws an interval where no hint was given, from 2026-08-31. What holds is the +//! division of labour rather than an absence: the assumed value belongs to the +//! retry policy, which is where a caller that has to wait reads it, and this type +//! carries what the server said or nothing. //! //! **`answer-not-understood` carries where reading stopped as an offset and the //! reading it stopped inside, and not which field.** 0037 asks for the field as