Skip to content

feat(cache): use binary envelopes for package cache writes#43922

Open
zharinov wants to merge 2 commits into
renovatebot:mainfrom
zharinov:feat/package-cache-binary-storage
Open

feat(cache): use binary envelopes for package cache writes#43922
zharinov wants to merge 2 commits into
renovatebot:mainfrom
zharinov:feat/package-cache-binary-storage

Conversation

@zharinov

@zharinov zharinov commented Jun 11, 2026

Copy link
Copy Markdown
Collaborator

Changes

Package cache writes store binary envelopes instead of JSON-wrapped base64 strings.

  • PackageCacheBase owns set(). It encodes the value into an envelope and passes the bytes to the backend's writeRaw().
  • Each backend stores opaque bytes and handles TTL with its native mechanism:
    • Redis writes the bytes with EX.
    • SQLite writes the bytes to its data blob and keeps its expiry column.
    • File cache writes the bytes with cacache and stores expiry in the index metadata.
  • A non-positive TTL deletes the entry instead of writing a value that is already expired.
  • File-cache cleanup reads expiry from cacache index metadata. It no longer opens and parses every content file, and the in-memory expiry map is gone.
  • All backends share one codec, so SQLite payloads now use brotli quality 8 like the others.

Reads still fall back to the legacy JSON-wrapper decoder, so existing entries keep working. legacy.ts stays until pre-envelope entries age out.

Notes:

  • New writes overwrite legacy entries in place. Keys are unchanged.
  • The first file-cache cleanup after upgrading removes legacy entries that have no expiry metadata. Later runs rewrite them as envelopes.
  • Smaller payloads: the JSON wrapper and base64 layer are gone.

Context

Please select one of the following:

  • This closes an existing Issue, Closes: #
  • This doesn't close an Issue, but I accept the risk that this PR may be closed if maintainers disagree with its opening or implementation

AI assistance disclosure

Did you use AI tools to create any part of this pull request?

Please select one option and, if yes, briefly describe how AI was used (e.g., code, tests, docs) and which tool(s) you used.

  • No — I did not use AI for this contribution.
  • Yes — minimal assistance (e.g., IDE autocomplete, small code completions, grammar fixes).
  • Yes — substantive assistance (AI-generated non-trivial portions of code, tests, or documentation).
  • Yes — other (please describe):

Documentation (please check one with an [x])

  • I have updated the documentation, or
  • No documentation update is required

How I've tested my work (please select one)

I have verified these changes via:

  • Code inspection only, or
  • Newly added/modified unit tests, or
  • No unit tests, but ran on a real repository, or
  • Both unit tests + ran on a real repository

The public repository: N/A — local Redis smoke tests covered single-node Redis and a 3-node Redis cluster.

@zharinov zharinov force-pushed the feat/package-cache-binary-storage branch from b36416a to de2d2a5 Compare June 15, 2026 13:29
@zharinov zharinov marked this pull request as ready for review June 15, 2026 13:30
@github-actions github-actions Bot requested a review from viceice June 15, 2026 13:30
@zharinov

Copy link
Copy Markdown
Collaborator Author

This is smooth for the SQLite and Redis backends. For the cacache, it's cache purge + cold start after update.

The file backend's cleanup decides what to keep from cacache index metadata
alone, so legacy entries (which store expiry inside the payload) would all be
purged on the first sweep after upgrade, cooling the cache.

Add a best-effort `upgradeLegacyEntry` hook on the base class, overridden only
by the file backend, that rewrites a still-valid legacy entry as an envelope
with the same expiry when it is read. The working set converts itself during the
run, so it survives cleanup. Redis and SQLite govern expiry natively and inherit
the no-op default.
@zharinov

Copy link
Copy Markdown
Collaborator Author

Just updated cacache case to migrate on read. If read migrates 1/10 items, 9/10 are still purged, and second run will be a cold start for sharded scenarios. Do we regard this as acceptable?

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

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant