🐛 fix(http): answer a failed request body as a client error

[gaborbernat]

A request body that failed answered 502 with "upstream transfer failed". Nothing upstream serves a request body: the bytes were coming from the client and peryx is the server. The stall bound #2182 added made it reachable with the client still connected, so a client that paused for thirty seconds was told something upstream of peryx had gone wrong. 502 also tells an intermediary that a backend gave a bad answer, which invites a retry against a different backend for a condition no backend change reaches. 🔍

The distinction lives in one place. BodyFailure sits in peryx-driver::body beside the Stalled error the edge produces, and both ecosystems ask it the same question instead of each reading an opaque body error. A handler cannot recover the distinction on its own: the stall arrives boxed and wrapped by whatever read the body, so the classification walks the source chain rather than inspecting the outermost error. Putting it anywhere else would have meant two answers to one question, which is the per-handler patchwork #2176 exists to avoid. It landed in peryx-driver rather than peryx-http because the registry takes peryx-http only as a dev-dependency, while both ecosystems already depend on the driver at runtime.

The two statuses are chosen for what they tell the client to do next. A stall answers 408, which says the server gave up waiting for a message that never arrived, and leaves the client free to repeat the request; a registry upload also gets the offset its session stands at, so it resumes there instead of starting over. Everything else answers 400, since a body the server could not read fails the same way when repeated unchanged. Merging the two under 400 fails in the more damaging direction. It tells a client that stalled that its request came out malformed, so the useful move, sending it again, looks pointless.

I updated the four registry tests that asserted the old status, and their intent survives unchanged. The two stall cases asserted that a cut chunk must not read as accepted, which 408 satisfies as well as 502 did, and the message that now accompanies them says which end went quiet. The monolithic case took its name from the gateway status it happened to produce rather than from any gateway being involved, so it now names a client error.

On what changes for clients that retry the old 502: peryx's own upstream client sees no change, because should_retry_status already retries both is_server_error() and REQUEST_TIMEOUT, so it retries a 408 exactly where it retried a 502. RFC 9110 gives 408 the same permission, since the request never completed and may be repeated. What an external pusher such as docker or containerd does with either status is not something this repository can answer, so a client that treated 502 as fatal and 408 as retryable, or the reverse, would see a change this change cannot verify.

Closes #2184

[codspeed-hq]

Merging this PR will not alter performance

✅ 29 untouched benchmarks
⏩ 133 skipped benchmarks¹

---

_{Comparing fix/client-body-failure-status-2184 (4628b0b) with main (0df149b)}

Footnotes

1. 133 benchmarks were skipped, so the baseline results were used instead. If they were deleted from the codebase, click here and archive them to remove them from the performance reports. ↩

[read-the-docs-community]

Documentation build overview

📚 peryx | 🛠️ Build #34390002 | 📁 Comparing 4628b0b against latest (e64cc83)

  🔍 Preview build  

No files changed.