Back off Builder sync recovery

[tannerlinsley]

Evidence

When a terminal Builder EventSource cannot recover its authoritative snapshot, the client retries every 500 ms forever. That is 120 sync requests per minute from one tab. The user and project stream limiter allows 180 requests per minute, so two open tabs can make 240 requests per minute during an outage and keep recovery requests rate limited.

The durable outbox already uses exponential retry delays for the same class of transient failures.

Change

Back off failed stream recovery snapshots from 500 ms to 30 seconds, and reset the delay after a successful authoritative snapshot. Recovery still starts immediately and keeps the existing abort behavior.

Impact

This prevents disconnected Builder tabs from creating a retry storm or prolonging a 429 lockout while keeping the first recovery attempt fast.

Validation

• pnpm test, 466 passed, 1 environment-gated docs smoke test skipped
• Focused Builder sync client test covers immediate recovery and the 500 ms, 1 second retry sequence
• pnpm build passed on current main during the audit

Risk

Low. The change is isolated to repeated snapshot failures after a terminal stream error. Successful recovery and ordinary live sync behavior are unchanged.

Summary by CodeRabbit

• Bug Fixes
  • Improved Builder project sync recovery by increasing retry delays after repeated snapshot fetch failures.
  • Retry intervals now start at 500 ms, increase progressively, and cap at 30 seconds.
  • Recovery delay resets after a successful retry.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 88792095-9410-4a82-9f33-69ec09b63dd0

📥 Commits

Reviewing files that changed from the base of the PR and between 8cf0df4 and 8fb4cb1.

📒 Files selected for processing (2)

• src/utils/builder-project-sync.client.ts
• tests/builder-project-sync-client.test.ts

Included review availability: Your plan provides up to 4 included reviews per hour; 2 remain after this review.

---

📝 Walkthrough

Walkthrough

Builder project sync recovery now uses bounded exponential backoff for failed snapshot fetches. The retry delay starts at 500 ms, doubles after failures, caps at 30 seconds, and resets after successful recovery. Tests verify retry timing and errors.

Changes

Stream recovery backoff

Layer / File(s)	Summary
Bounded recovery backoff and validation src/utils/builder-project-sync.client.ts, tests/builder-project-sync-client.test.ts	The recovery flow tracks retry delay, resets it after successful snapshot recovery, increases it after failures, and validates 500 ms and 1,000 ms retry intervals with fake timers.

Estimated code review effort: 2 (Simple) | ~10 minutes

Merge Risk: ⚪ Minimal · up to 8fb4c

The change limits repeated Builder recovery requests while preserving immediate recovery and normal synchronization behavior; no actionable merge-blocking risk remains after normal checks and review.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 3 functions across 2 files.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main change: adding backoff behavior to Builder sync recovery.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

• Fix all pre-merge checks with AI

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch agent/backoff-builder-sync-recovery

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Preview URL	Updated (UTC)
✅ Deployment successful! View logs	tanstack-com	8fb4cb1	Commit Preview URL Branch Preview URL	Aug 26 2026, 03:35 PM