Add fast-loop detection and backoff for proxy misconfiguration

[KyleAMathews]

Summary

This PR adds detection and mitigation for tight retry loops caused by proxy or CDN misconfiguration. When the client detects a pattern of rapid non-live requests, it applies exponential backoff and eventually throws an error with diagnostic information to help users troubleshoot their infrastructure.

Key Changes

• Fast-loop detection mechanism: Tracks timestamps of non-live requests within a 500ms window. When 5+ requests occur in this window, it's flagged as a potential fast loop.
• Exponential backoff with jitter: Applies increasing delays (100ms base, up to 5s max) between retry attempts when a fast loop is detected, with full jitter to prevent thundering herd.
• Error escalation: After detecting 5 consecutive fast loops, throws a FetchError with detailed diagnostic guidance pointing to common proxy/CDN issues (missing cache key parameters, stale responses, stripped headers).
• Console warnings: Logs a warning on first detection to alert users to the misconfiguration.
• State reset: Clears fast-loop tracking when the stream reaches a healthy state (up-to-date sync).
• Test coverage: Added integration test that simulates a misconfigured proxy returning 409 responses and verifies the fast-loop detection and error handling.

Implementation Details

• Only tracks non-live requests (!this.#syncState.isUpToDate) to avoid flagging normal live polling as problematic
• Prunes old timestamps outside the detection window before checking thresholds
• Clears timestamp history after applying backoff to measure fresh request patterns
• Error message includes troubleshooting guide link and common misconfiguration causes

https://claude.ai/code/session_01PRpp3wmqC4DinxcmxDANLZ

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/@electric-sql/react@3855

npm i https://pkg.pr.new/@electric-sql/client@3855

npm i https://pkg.pr.new/@electric-sql/y-electric@3855

commit: c8e84e9

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 75.75%. Comparing base (b3ae567) to head (c8e84e9).
⚠️ Report is 3 commits behind head on main.
✅ All tests successful. No failed tests found.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #3855      +/-   ##
==========================================
+ Coverage   69.43%   75.75%   +6.32%     
==========================================
  Files           6       11       +5     
  Lines         386      693     +307     
  Branches       96      172      +76     
==========================================
+ Hits          268      525     +257     
- Misses        117      167      +50     
  Partials        1        1              

Flag	Coverage Δ
packages/experimental	87.73% <ø> (ø)
packages/react-hooks	86.48% <ø> (?)
packages/start	82.83% <ø> (?)
packages/y-electric	56.05% <ø> (ø)
typescript	75.75% <ø> (+6.32%)	⬆️
unit-tests	75.75% <ø> (+6.32%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.