Decode fresh HTTP cache entries in the read task

[charliermarsh]

Summary

We currently read an HTTP cache entry in one blocking task, check whether it is fresh, then dispatch another task to decode its payload. We now read the file, check its policy against the request, and decode a fresh payload in the same cache-read worker.

For online revalidation, stale payloads remain encoded until a 304 response permits reuse. We retain request overrides, request matching, corruption recovery, and the existing offline/allowed-stale path.

Benchmarks

Resolving pinned Jupyter 1.1.1 and its 95 dependencies with fresh cached catalogs and wheel metadata takes 5–8% less time across two batches, around 4 ms off the independent median command time. Every measured command makes zero HTTP requests. These are warm-cache resolution results.

Batch	Median baseline → PR	Paired time reduction [95% interval]
1	45.2 → 41.2 ms	+4.9% [+3.1, +9.1]
2	46.0 → 41.7 ms	+8.0% [+6.6, +11.0]

The offline control moves by +8.2% in the first batch and +0.1% in the second, with both intervals spanning zero. The primary improvement repeats, but this is a small effect with noisy controls. Peak RSS stays around 46.7 MiB.

Raw samples, exact inputs, and benchmark harness.

Benchmark method and offline control

Compared fb1439e3f with implementation commit 93620834b. The current-main merge is validated separately; these measurements have not been rerun on the merge commit. Measured on Linux/AMD EPYC-Milan with 32 available CPUs, CPython 3.12.13, and the same Ohm 1.98.1-1 compiler, default features, and optimized profiling configuration (no LTO). Each independent batch has 12 alternating baseline/candidate pairs for the primary workload and six for the control, after an excluded warmup pair. The second batch reverses the starting variant. Timings cover the complete command, including startup; preparation, cache priming, environment creation, and output validation are excluded. OS pages are warm.

The workload uses uv pip compile with pinned constraints against a local mirror of captured PyPI catalogs. The mirror retains historical versions and serves 14.7 MB of JSON, selecting the pinned platform wheel for each package. Each variant is primed separately outside timing with 96 catalog and 96 METADATA requests; cached policies remain fresh throughout measurement. Resolved versions and normalized output match for all 96 packages.

The offline control uses separately primed caches and exercises the existing single-task cache-read path. It also makes zero HTTP requests.

Offline control	Median baseline → PR	Paired time reduction [95% interval]
Batch 1	44.2 → 40.4 ms	+8.2% [-5.7, +11.4]
Batch 2	44.4 → 44.4 ms	+0.1% [-14.7, +8.3]

Positive percentages mean less time. We compute 100 × (1 − median(candidate / baseline)) across matched pairs, with 95% intervals from 10,000 paired bootstrap resamples. This need not equal the ratio of the independently computed medians in the tables.

[astral-sh-bot]

uv test inventory changes

This PR changes the tests when compared with the main base revision.

• Added tests: 3
• Removed tests: 0
• Changed suites: 1

uv-client::it: +3 / -0

Added:

• uv-client::it::cached_client::cache_heals_corrupted_payload
• uv-client::it::cached_client::fresh_cache_rejects_a_different_request
• uv-client::it::cached_client::fresh_cache_respects_overrides_and_revalidation

Removed: none