feat: add resume support for R2 cache population

[beobungbu]

Summary

When populating a large R2 incremental cache (100K+ entries), the local worker proxy encounters intermittent 502 Bad Gateway errors. After 5 retry attempts on a single entry, the entire process crashes — requiring a full restart from entry 0. For a 180K-entry cache, this means losing 60+ minutes of upload progress.

This PR adds a lightweight resume mechanism so that populateCache can pick up from where it left off after a crash.

How it works

Progress directory: /tmp/opennext-cache-{workerName}-{buildId}/

File	Written when	Content
total.txt	Start of upload	Entry count (e.g. "180393")
failed-at.txt	Fatal error (retry exhaustion)	Index of failed entry (e.g. "117000")

Resume flow:

Run 1 (fresh):
  Create dir + total.txt
  Upload entries 0 → 116999 ✅
  Entry 117000 fails after 5 retries
  Write failed-at.txt = "117000"
  Process exits

Run 2 (resume):
  Dir exists, total.txt matches entry count, same buildId in dir name
  Read failed-at.txt = 117000
  Skip entries 0-116999, upload 117000-180392
  Success → delete progress dir

Stale detection:

• BuildId is embedded in the directory name → different build = different dir
• Entry count in total.txt must match current build → content changes detected
• Stale directories from previous builds are auto-cleaned on startup

Design decisions

• Zero overhead during normal upload — no file writes per entry, only writes on crash (1 syscall) and reads on resume (2 syscalls)
• No in-flight tracking — the crash always comes from retry exhaustion, not a sudden process kill. The failed-at index captures exactly where to resume.
• Directory naming includes buildId — avoids conflicts between projects and builds sharing /tmp
• R2 PUT is idempotent — re-uploading ~25 entries around the resume boundary is safe

Testing

Tested with a 180K-entry Next.js app (13 locales × ~14K administrative entities):

• Run 1: uploads ~65% before worker proxy crash → failed-at.txt written
• Run 2: resumes from 65%, uploads remaining 35% → success, progress dir cleaned

Related

• Fixes [BUG] R2 cache population fails with 180K+ objects — no resume after failure #1173
• Related: [BUG] V8 string limit hit during wrangler deploy with 180K SSG pages — bundle gzip under 10MB limit #1174 (V8 string limit with 180K SSG pages)

[changeset-bot]

⚠️ No Changeset found

Latest commit: 1f3baac

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[vicb]

@beobungbu how often does the upload crashes?

I'm not against adding resume support BUT it will not solve uploading on CI which is the most frequent use case for deployment.

Maybe what we can first do is to

• bump the max retries to a higher number
• investigate why we see failures on the Cloudflare infra and try to improve the situation

What do you think about that plan.

Could you please confirm the numbers you usually see: upload time for how many assets. 60+min for 100k files sounds like slow to me.

Thanks