Refresh HTTP cache policies in place by charliermarsh · Pull Request #22052 · astral-sh/uv

charliermarsh · 2026-09-28T19:32:23Z

We now update the HTTP cache policy in place on a 304 response, avoiding a rewrite of the cached payload. The format change bumps the six cache buckets containing HTTP responses.

Warm-cache benchmarks on Linux/ext4, with 96 entries and 16 concurrent requests per batch (c9dab42be → 1562e401b, using SeaHash):

Warm-cache workload	Main	PR	Paired change
304 refresh, 256 KiB	80.39 ms	9.84 ms	87.4% faster
304 refresh, 1 MiB	323.20 ms	17.59 ms	94.6% faster
Fresh reads, 4 KiB	0.711 ms	0.712 ms	Approximately unchanged
Fresh reads, 256 KiB	2.140 ms	2.112 ms	2.9% faster
Fresh reads, 1 MiB	7.529 ms	7.698 ms	No clear difference

astral-sh-bot · 2026-09-28T21:55:14Z

uv test inventory changes

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

Added tests: 9
Removed tests: 1
Changed suites: 2

uv-client: +3 / -0

Added:

uv-client::cached_client::tests::cache_trailer_corruption_is_rejected
uv-client::cached_client::tests::interrupted_policy_writes_never_accept_a_mixed_policy
uv-client::cached_client::tests::policy_can_grow_and_shrink_in_place

Removed: none

uv-client::it: +6 / -1

Added:

uv-client::it::cached_client::delayed_revalidation_cannot_modify_replaced_payload
uv-client::it::cached_client::overlapping_policy_updates_are_refetched
uv-client::it::cached_client::reject_invalid_cache_lengths
uv-client::it::cached_client::revalidation_of_readonly_entry
uv-client::it::cached_client::revalidation_updates_only_policy
uv-client::it::cached_client::torn_policy_is_refetched

Removed:

uv-client::it::cached_client::reject_overflowing_cache_policy_length

konstin · 2026-09-29T07:25:54Z

+                    let path = cache_entry.path().to_path_buf();
+                    let span = Span::current();
+                    let payload = tokio::task::spawn_blocking(move || {
+                        span.in_scope(|| {


We can give this its own scope so it shows up separately in traces

konstin · 2026-09-29T07:30:20Z

-/// Reading the format is done via an `AlignedVec` so that `rkyv` can correctly
-/// read the archived representation of the data blob. The cache policy is
-/// split into its own `AlignedVec` allocation.
+/// Each file contains the payload, a random 16-byte generation ID, the archived


What the ID for?

My read of below is that we use it to prevent an accidental clobber of another cache write, i.e. due to concurrency. But calling it a "generation" is arguably confusing since that implies an incrementing value, not a random ID like it currently is 🙂

Specifically here: https://github.com/astral-sh/uv/pull/22052/changes#diff-a327e08abfc6c0f1a83a8c92ad294c17f1b410f5133b1e81ccbdc76008c1f8b0R1057

codspeed · 2026-09-30T02:16:27Z

Merging this PR will improve performance by ×3.8

⚡ 1 improved benchmark
✅ 71 untouched benchmarks
⏩ 28 skipped benchmarks¹

Performance Changes

	Mode	Benchmark	`BASE`	`HEAD`	Efficiency
⚡	WallTime	`revalidate_shared`	328.9 ms	85.9 ms	×3.8

Tip

Curious why performance improved? Comment @codspeedbot explain why performance improved on this PR, or directly use the CodSpeed MCP with your agent.

_{Comparing charlie/refresh-cache-policy-in-place (ccaca30) with main (831a46a)}

28 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. ↩

We revert the cache-format stack so `main` retains the 0.12 cache formats and bucket versions. These changes are deferred to 0.13. This reverts the following PRs together, including the six cache bucket bumps and the serialization and Windows lock-name changes that depend on them: - #22052: Refresh HTTP cache policies in place - #22059: Store source distribution revision IDs inline - #22060: Remove the legacy hash digest cache representation - #22061: Derive serialization for cached artifact records - #22062: Use bounded wheel cache lock names on Windows - #22078: Pack HTTP cache policy flags and optional integers - #22079: Align cached HTTP policies within the payload buffer

Reapplies #22052 for 0.13. We now update the HTTP cache policy in place on a 304 response, avoiding a rewrite of the cached payload. The format change bumps the six cache buckets containing HTTP responses. Original benchmarks from #22052 on Linux/ext4, with 96 entries and 16 concurrent requests per batch (`c9dab42be` → `1562e401b`, using SeaHash): | Warm-cache workload | Main | PR | Paired change | |---|---:|---:|---:| | 304 refresh, 256 KiB | 80.39 ms | 9.84 ms | 87.4% faster | | 304 refresh, 1 MiB | 323.20 ms | 17.59 ms | 94.6% faster | | Fresh reads, 4 KiB | 0.711 ms | 0.712 ms | Approximately unchanged | | Fresh reads, 256 KiB | 2.140 ms | 2.112 ms | 2.9% faster | | Fresh reads, 1 MiB | 7.529 ms | 7.698 ms | No clear difference |

Reapplies astral-sh#22052 for 0.13. We now update the HTTP cache policy in place on a 304 response, avoiding a rewrite of the cached payload. The format change bumps the six cache buckets containing HTTP responses. Original benchmarks from astral-sh#22052 on Linux/ext4, with 96 entries and 16 concurrent requests per batch (`c9dab42be` → `1562e401b`, using SeaHash): | Warm-cache workload | Main | PR | Paired change | |---|---:|---:|---:| | 304 refresh, 256 KiB | 80.39 ms | 9.84 ms | 87.4% faster | | 304 refresh, 1 MiB | 323.20 ms | 17.59 ms | 94.6% faster | | Fresh reads, 4 KiB | 0.711 ms | 0.712 ms | Approximately unchanged | | Fresh reads, 256 KiB | 2.140 ms | 2.112 ms | 2.9% faster | | Fresh reads, 1 MiB | 7.529 ms | 7.698 ms | No clear difference |

charliermarsh temporarily deployed to automations September 28, 2026 19:33 — with GitHub Actions Inactive

charliermarsh added 2 commits September 28, 2026 15:57

Refresh HTTP cache policies in place

9f06ee6

Handle read-only HTTP cache entries and verify refresh recovery

60895fe

charliermarsh force-pushed the charlie/refresh-cache-policy-in-place branch from 9bfd20d to 60895fe Compare September 28, 2026 19:57

charliermarsh temporarily deployed to automations September 28, 2026 19:59 — with GitHub Actions Inactive

charliermarsh added the performance label Sep 28, 2026

Use SeaHash for HTTP cache policy checksums

1562e40

charliermarsh temporarily deployed to automations September 28, 2026 20:35 — with GitHub Actions Inactive

charliermarsh requested a review from woodruffw September 28, 2026 20:38

This was referenced Sep 28, 2026

Store source distribution revision IDs inline #22059

Merged

Remove the legacy hash digest cache representation #22060

Merged

woodruffw reviewed Sep 28, 2026

View reviewed changes

Comment thread crates/uv-cache/src/lib.rs Resolved

Comment thread crates/uv-client/src/cached_client.rs Resolved

Comment thread crates/uv-client/src/cached_client.rs Resolved

charliermarsh mentioned this pull request Sep 28, 2026

Derive serialization for cached artifact records #22061

Merged

Use a typed footer for HTTP cache policies

380df35

charliermarsh mentioned this pull request Sep 28, 2026

Use bounded wheel cache lock names on Windows #22062

Merged

charliermarsh temporarily deployed to automations September 28, 2026 21:05 — with GitHub Actions Inactive

Use CRC32 for HTTP cache policy checksums

59c7762

charliermarsh temporarily deployed to automations September 28, 2026 21:23 — with GitHub Actions Inactive

charliermarsh requested a review from woodruffw September 28, 2026 21:27

charliermarsh added the internal A refactor or improvement that is not user-facing label Sep 28, 2026

woodruffw approved these changes Sep 28, 2026

View reviewed changes

charliermarsh added this pull request to stack #22065 September 28, 2026 23:15

charliermarsh mentioned this pull request Sep 28, 2026

Refresh HTTP cache policies without bumping cache buckets #22066

Closed

konstin approved these changes Sep 29, 2026

View reviewed changes

Clarify HTTP cache entry identifiers

ccaca30

charliermarsh temporarily deployed to automations September 30, 2026 01:44 — with GitHub Actions Inactive

charliermarsh merged commit f060188 into main Sep 30, 2026
89 of 90 checks passed

charliermarsh deleted the charlie/refresh-cache-policy-in-place branch September 30, 2026 02:07

charliermarsh mentioned this pull request Oct 1, 2026

Defer cache format changes to 0.13 #22128

Merged

charliermarsh mentioned this pull request Oct 1, 2026

Refresh HTTP cache policies in place #22130

Merged

Navigation Menu

Repository navigation

Refresh HTTP cache policies in place - #22052

Refresh HTTP cache policies in place#22052
charliermarsh merged 6 commits into
mainfrom
charlie/refresh-cache-policy-in-place

charliermarsh commented Sep 28, 2026 •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

Uh oh!

astral-sh-bot Bot commented Sep 28, 2026

Uh oh!

konstin Sep 29, 2026

Uh oh!

konstin Sep 29, 2026

Uh oh!

woodruffw Sep 29, 2026

Uh oh!

Uh oh!

codspeed Bot commented Sep 30, 2026

Uh oh!

This branch was previously deployed

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

charliermarsh commented Sep 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

astral-sh-bot Bot commented Sep 28, 2026

uv test inventory changes

Uh oh!

konstin Sep 29, 2026

Choose a reason for hiding this comment

Uh oh!

konstin Sep 29, 2026

Choose a reason for hiding this comment

Uh oh!

woodruffw Sep 29, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

codspeed Bot commented Sep 30, 2026

Merging this PR will improve performance by ×3.8

Performance Changes

Footnotes

Uh oh!

This branch was previously deployed

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

charliermarsh commented Sep 28, 2026 •

edited

Loading