fix(cache): re-add cacache.verify() to garbage collect orphaned content from put() overwrites

[bbodenmiller]

Changes

Re-add cacache.verify() to the destroy() method to garbage collect content blobs orphaned by cacache.put() overwrites.

When cacache.put() is called with an existing key but different data (e.g., a version lookup result changes because a new release was published), cacache writes a new content blob and updates the index entry to point to it, but does not remove the previous content blob. Over many scheduled runs with many dependencies, these orphaned blobs accumulate indefinitely in content-v2/.

rm.content (added in #29860 when verify() was removed) only removes content when an entry
expires. It does not handle orphans created by overwrites of still-live keys.

On a self-hosted instance running scheduled scans of ~100 repos over several months, the cache grew to multiple GB of orphaned content while the actual referenced data was only ~16 MB. Running cacache.verify() reclaimed ~5 GB by removing ~565k unreferenced content blobs. After GC, Renovate's cache behavior was unchanged (verified: identical package cache hits, HTTP request counts, and lookup results before and after).

Performance

The concern in #29795 was that verify() is slow. However:

• On a healthy cache (after initial cleanup), verify() completes in under 1 second (~260ms for ~500 entries in testing)
• The slow times previously reported were caused by the orphan accumulation itself — scanning hundreds of thousands of orphaned blobs is slow, but that only happens once
• Without verify(), the cache grows until it causes CI cache upload failures (exceeding S3 size limits), pod evictions from ephemeral storage exhaustion, and minutes-long cache restore times — all worse than a sub-second GC pass

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

Related:

• fix(cache): Trigger cacache to remove expired contents #28275 — originally added cacache.verify() to fix cacache cleanup doesn't return diskspace #28169
• Cleaning file-based package cache is slow, research if/when we need verify step #29795 / refactor(cache): use rm.content to remove expired content #29860 — removed verify() for performance, replaced with rm.content per expired entry (does not cover put() orphans)
• feat(cache): Optimize package cache file backend #42543 — open PR with alternative GC approach (tracks digests during sweep, but does not handle pre-existing orphans)

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):

Investigation and drafting assisted by Claude. Root cause analysis, testing on real self-hosted instance, and code change were done collaboratively.

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

Tested cacache.verify() on a real self-hosted GitLab instance across three job types (local scan, 50-repo dry run, 100+ repo dry run). For each: ran cold (no cache), warm (with cache), GC, then warm again. Cache metrics (package cache gets/sets, HTTP requests) were identical between warm and warm-after-GC runs, confirming GC does not affect cache functionality.

[zharinov]

I approve but needs prettier fix

[RahulGautamSingh]

Nice

[bbodenmiller]

I approve but needs prettier fix

@zharinov thanks, fixed