[wan9chi]

Motivation

Vite+'s Cloudflare remote cache now keeps each key's newest entries instead of only the last one stored (voidzero-dev/vite-plus-remote-cache-cloudflare#47). Runs built on an older default-branch commit, such as PR runs without a merged result, stacked PRs, and machines that haven't pulled, can then hit an entry stored earlier. An exact fetch now returns a list of entries, which vp run has to decode and choose from. Which entry a lookup restores, which ones a store retires, and how expiry affects both are new behaviour, so the e2e cases check the whole path against the Worker.

Changes

• Client. vt_remote_cache decodes { kind: "exact", entries: [{ value, blob_id }] }, newest first. An empty list, or the single entry earlier servers sent, is a malformed response, which vp run treats as a failed read.

• Lookup. A remote lookup checks the entries newest first and restores the first one that passes validation. If none does, the miss is the newest entry's: its fingerprint mismatch, or its read failure if it doesn't decode or its blob doesn't match its value.

• E2E backend. The pinned Worker is that pull request's head. The tap's request lines list an exact fetch's entries by blob number, newest first:

  [remote-cache] POST /fetch 200 exact [2, 1]
  

  That's the only change to existing snapshots.

• E2E cases. New remote_cache_entries cases, each against its own backend:

  Case	What it shows
  older_entries	Entries come newest first, and a lookup restores the first that matches, here the oldest.
  newest_entry_explains_miss	When no entry matches, the miss reason compares with the newest one.
  entries_per_key	A store past the namespace's limit retires the key's oldest entry.
  entries_per_key_isolation	Stores to one key don't retire another key's entries, even when its fetch fell back to that key.
  expired_entries	Expired entries aren't fetched. A key whose entries have all expired is a miss without a fallback.
  expired_entry_takes_no_slot	An expired newer entry doesn't count against the limit, so the older live entry is kept.

  To set them up:

  • remote-cache-server start --entries-per-key N registers the namespace with that limit.
  • remote-cache-server expire-entry NUMBER makes the entry with that blob expire now. As before the Worker's scheduled cleanup, nothing removes it.

Stacked on #811.

🤖 Generated with Claude Code

---

Note

Medium Risk
Changes core remote cache hit/miss selection and tightens fetch response decoding; behavior is heavily covered by new unit and e2e tests but wrong selection could cause unexpected cache misses or restores.

Overview
Remote cache fetches can return multiple entries per key (newest first) instead of a single value/blob pair. The client and session layer are updated end-to-end for that protocol.

vt_remote_cache decodes exact matches as { entries: [...] }, rejects empty lists and legacy single-entry shapes as malformed, and exports a public Entry type.

Remote lookup in vt walks entries newest-first in resolve, restores the first that decodes, has a matching blob, and passes fingerprint validation, and when none match the miss is attributed to the newest entry (mismatch or read failure).

E2E tooling pins a newer Cloudflare Worker, adds remote-cache-server start --entries-per-key N and expire-entry, and logs fetches as exact [2, 1]. New remote_cache_entries snapshot cases cover multi-entry restore, per-key limits, isolation, and expiry; existing remote-cache snapshots only gain the bracketed entry list in request lines.

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

[github-actions]

fspy benchmark

linux

dynamic/launch             change  +0.16%  [ -2.64% ..  +2.66%]  overhead   +54.61%
dynamic/access             change  +0.44%  [ -3.30% ..  +3.92%]  overhead   +20.72%
dynamic/access-relative    change  +0.28%  [ -2.63% ..  +3.11%]  overhead   +70.27%
dynamic/access-contended   change  +2.04%  [ -3.93% ..  +6.33%]  overhead   +10.29%
static/launch              change  +1.07%  [ -2.28% ..  +3.92%]  overhead  +202.85%
static/access              change  -0.17%  [ -1.22% ..  +0.90%]  overhead +1451.86%
static/access-relative     change  -0.30%  [ -1.28% ..  +0.70%]  overhead +1992.30%
static/access-contended    change  +0.09%  [ -1.04% ..  +1.41%]  overhead +2054.24%

macos

dynamic/launch             change  -0.14%  [ -5.14% ..  +5.01%]  overhead  +260.59%
dynamic/access             change  +0.68%  [ -6.34% .. +13.58%]  overhead    +3.43%
dynamic/access-relative    change  -1.34%  [ -7.99% ..  +5.42%]  overhead  +223.42%
dynamic/access-contended   change  +0.87%  [ -7.63% .. +20.63%]  overhead    +6.81%

windows

dynamic/launch             change  -0.06%  [ -1.17% ..  +1.73%]  overhead   +26.69%
dynamic/access             change  +0.00%  [ -1.44% ..  +1.27%]  overhead    +1.29%
dynamic/access-relative    change  +0.17%  [-18.20% .. +13.53%]  overhead    +1.71%
dynamic/access-contended   change  +0.17%  [ -1.55% ..  +1.93%]  overhead    +1.77%