Skip to content

feat(cache): share a task's remote cache entries between platforms with cache.remote.crossPlatform - #1004

Draft
fengmk2 wants to merge 2 commits into
mainfrom
feat/remote-cache-cross-platform
Draft

fengmk2 wants to merge 2 commits into
mainfrom
feat/remote-cache-cross-platform

Conversation

@fengmk2

@fengmk2 fengmk2 commented Nov 20, 2026

Copy link
Copy Markdown
Member

Motivation

Every remote key starts with a header that names the OS and the architecture, so an entry that Linux CI stores is never fetched on a developer's Mac. This is true even for a task whose outputs are the same on every platform, such as a code generator that runs on Node.js. Teams whose CI and developers use different platforms get few remote hits. Today the only workaround is a server that rewrites each key's header, which depends on the key's private encoding and applies to every task at once (#926).

Changes

  • Config. A task's cache.remote takes true, false, or an object. true is the same as {}. The object has one setting, crossPlatform, which defaults to false:

    tasks: {
      generate: {
        command: 'node generate.ts',
        cache: { remote: { crossPlatform: true } },
      },
    }

    Like the rest of remote caching, the field is parsed but left out of the public types.

  • Keys. With crossPlatform: true, both remote keys (key and secondary_key) start with a header that has an empty OS and architecture. No platform has an empty name, so these keys never equal a platform's keys. The cache schema version and the remote value format stay in the header. A fallback's key is decoded with the same header, so its miss reason still works.

  • Unchanged. Tasks without crossPlatform keep the same keys as before. The local cache doesn't depend on the setting. A fetched entry is still checked against the fetching machine's inputs, and the rest of the key (the program, its arguments, its working directory, its envs, and its input and output globs) must still match. Turning the setting on or off changes the task's remote keys one time.

  • Built-in tools. A built-in tool's cache settings merge into the settings of the task that runs it. The tool uses the remote cache only if both allow it, and shares its entries between platforms if either one sets crossPlatform. Vite+'s built-ins don't set remote today, so crossPlatform on a task like "lint": "vp lint" applies to the tool.

Built-in tools still put absolute paths in their arguments (#717), so their keys can still differ between machines.

Closes #926

🤖 Generated with Claude Code

…th `cache.remote.crossPlatform`

Every remote key starts with a header that names the OS and the
architecture, so an entry that Linux CI stores is never fetched on macOS,
even for a task whose outputs are the same on every platform. A task can
now set `cache: { remote: { crossPlatform: true } }`. Its remote keys then
have an empty OS and architecture, which no platform has. The default
keys and the local cache don't change.

Closes #926

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@fengmk2 fengmk2 added the remote cache Remote caching label Nov 20, 2026
@github-actions

github-actions Bot commented Nov 20, 2026 •

Copy link
Copy Markdown

fspy benchmark

linux

dynamic/launch             change  +0.92%  [ -2.83% ..  +5.17%]  overhead   +59.79%
dynamic/access             change  -0.43%  [ -5.85% ..  +4.04%]  overhead   +17.87%
dynamic/access-relative    change  +0.31%  [ -2.70% ..  +3.40%]  overhead   +68.43%
dynamic/access-contended   change  -0.94%  [ -5.00% ..  +5.35%]  overhead   +53.04%
static/launch              change  +0.43%  [ -2.28% ..  +4.18%]  overhead  +198.24%
static/access              change  +0.37%  [ -0.47% ..  +1.38%]  overhead +1465.02%
static/access-relative     change  +0.25%  [ -0.73% ..  +1.76%]  overhead +1965.39%
static/access-contended    change  +0.29%  [ -2.30% ..  +8.82%]  overhead +2084.87%

macos

dynamic/launch             change  +0.22%  [ -2.89% ..  +2.50%]  overhead  +230.77%
dynamic/access             change  +0.39%  [ -3.77% ..  +3.25%]  overhead    +6.02%
dynamic/access-relative    change  -0.21%  [ -2.30% ..  +1.66%]  overhead  +283.12%
dynamic/access-contended   change  +0.00%  [ -2.02% ..  +2.44%]  overhead    +3.40%

windows

dynamic/launch             change  -0.01%  [ -3.03% ..  +3.24%]  overhead   +27.92%
dynamic/access             change  +0.00%  [ -1.10% ..  +1.05%]  overhead    +1.49%
dynamic/access-relative    change  +0.00%  [ -0.75% ..  +1.14%]  overhead    +1.30%
dynamic/access-contended   change  -1.44%  [-18.42% ..  +1.87%]  overhead    +0.91%

…apshots

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

remote cache Remote caching

Projects

None yet

1 participant