[wan9chi]

Motivation

An exact fetch now returns up to entries_per_key entries, 8 by default and at most 16, and the Worker caps each value at 4 MiB. Uncompressed, values are large: in a replay of five public repositories' CI, the median was 111 KB, the p90 1.66 MB and the largest 3.10 MB. Eight of those make every fetch heavy, and large repositories exceed the cap. RFC 0003 of Vite+'s Cloudflare remote cache asks vp run to compress values with zstd. They're opaque bytes to the server, so this changes only the client.

Changes

• Upload. A value is zstd(wincode(CacheEntryValue)), at zstd's default level, the same as output archives. On 42 real values from local task caches (18.9 MB), level 3 compressed to 2.59 MB in milliseconds. Level 9 was about 22% smaller but about 5 times slower, and a value is compressed as its task finishes.
• Fetch. A value decompresses through a reader that stops past 32 MiB, whatever size its frame declares. A value that isn't zstd, is too large, or doesn't decode is still a miss with remote cache value is corrupt.
• Size limit. A value larger than 32 MiB before compression isn't uploaded (cache entry is larger than 32 MiB), since no client would read it back.
• Key header. Both keys now carry a remote value format version. Clients that encode values differently never share entries, and so never push out each other's within a key's limit. The local cache's schema version, and so its directory, stays the same.

None of the snapshots change.

Stacked on #955.

🤖 Generated with Claude Code

---

Note

Medium Risk
Changes remote cache wire format and key matching; old uncompressed entries become misses for new clients, with safeguards for bombs and oversized uploads.

Overview
Remote cache values are now zstd over the existing wincode payload on upload, and decompressed with a 32 MiB cap on fetch so oversized or malformed frames are treated as corrupt misses instead of exhausting memory.

Uploads reject uncompressed values above that limit; new UploadError variants cover compression failure and too large. Reads route decode failures through DecodeValueError (decompress, too large, or wincode decode).

Cache keys gain a remote_value_format field in the header (version 1) so clients using different value encodings do not share or evict each other's entries in the same remote namespace.

Tests cover round-trip encoding, non-zstd/truncated payloads, size limits, and mismatched format versions in fallback keys.

^{Reviewed by Cursor Bugbot for commit 8bd6a40. Bugbot is set up for automated code reviews on this repo. Configure here.}

[github-actions]

fspy benchmark

linux

dynamic/launch             change  +0.17%  [ -3.07% ..  +3.29%]  overhead   +53.44%
dynamic/access             change  +0.00%  [ -3.81% ..  +3.44%]  overhead   +20.50%
dynamic/access-relative    change  +0.00%  [ -2.42% ..  +3.08%]  overhead   +76.31%
dynamic/access-contended   change  +0.58%  [ -5.23% ..  +4.13%]  overhead   +43.72%
static/launch              change  +0.27%  [ -2.36% ..  +2.87%]  overhead  +195.95%
static/access              change  -0.07%  [ -1.20% ..  +0.91%]  overhead +1474.95%
static/access-relative     change  -0.23%  [ -1.39% ..  +0.90%]  overhead +1936.15%
static/access-contended    change  -0.12%  [ -1.22% ..  +0.69%]  overhead +2208.00%

macos

dynamic/launch             change  +0.53%  [ -4.49% ..  +6.43%]  overhead  +255.28%
dynamic/access             change  +0.00%  [ -7.92% .. +13.28%]  overhead    +2.06%
dynamic/access-relative    change  +0.31%  [ -5.43% ..  +5.56%]  overhead  +251.42%
dynamic/access-contended   change  +2.79%  [-10.83% .. +11.95%]  overhead    +4.59%

windows

dynamic/launch             change  +1.14%  [ -6.70% .. +11.23%]  overhead   +23.48%
dynamic/access             change  -0.18%  [-13.06% ..  +4.88%]  overhead    +2.42%
dynamic/access-relative    change  +0.53%  [ -4.42% ..  +8.17%]  overhead    +2.63%
dynamic/access-contended   change  -1.22%  [ -6.10% ..  +4.84%]  overhead    +1.97%