[KyleAMathews]

Fix unbounded URL growth on 409 retries when proxy strips the handle header, which caused 414 URI Too Long errors and cascading 5xx failures.

Root Cause

When the server returns a 409 "must-refetch" response, the client needs a new shape handle. If the response includes the electric-handle header, the client uses it directly. If not (e.g., a proxy/CDN strips the header), the old code appended -next to the current handle as a cache buster. This violated two invariants:

1. Handles are identities, not cache busters — concatenating -next conflated identity with URL uniqueness
2. Retry URLs must be unique — handle-next was the same on every retry, only busting the cache once. And it grew unboundedly: handle-next-next-next-next...

Two patterns were observed in production (ELECTRIC-4GV, 8,764 events in 9 hours):

• Pattern A: expired_handle=undefined-next-next-next... — handle was never initialized
• Pattern B: handle=87840909-...-next-next-next... — valid handle that spiraled

Approach

Removed the -next suffix hack entirely. When a 409 lacks a handle header:

1. Reset without fabricating a handle — #reset(undefined) via markMustRefetch, preserving the state machine's contract (per SPEC.md I10)
2. Use a random cache-buster query param — the same CACHE_BUSTER_QUERY_PARAM mechanism already used by StaleRetryState for stale CDN responses

// Before: conflated handle with cache busting, grew unboundedly
const newShapeHandle =
  e.headers[SHAPE_HANDLE_HEADER] || `${this.#syncState.handle!}-next`

// After: proper separation of concerns
if (!newShapeHandle) {
  this.#refetchCacheBuster = `${Date.now()}-${Math.random()...}`
}
this.#reset(newShapeHandle || undefined)

The cache buster is consumed once in #constructUrl and cleared, ensuring each retry gets a unique URL without polluting the handle.

Key Invariants

• Every retry URL must be unique — enforced by random cache-buster param (tested)
• Handles are never fabricated — no -next, no undefined stringification
• State machine contract preserved — markMustRefetch(handle?) produces InitialState per SPEC.md I10
• Both code paths covered — #requestShape (line 890) and fetchSnapshot (line 1886)

Non-goals

• Not changing the happy path (409 with handle header works as before)
• Not adding retry limits — the existing fast-loop detector handles that

Verification

cd packages/typescript-client
pnpm exec vitest run --config vitest.unit.config.ts
# 295 tests pass (10 files)

Tests assert the real invariants:

• All retry URLs are unique (no duplicates)
• No URL contains -next or undefined in any parameter
• Cache buster or expired_handle param present on every retry

Files Changed

File	Change
packages/typescript-client/src/client.ts	Replace -next hack with #refetchCacheBuster at both 409 paths + consumption in #constructUrl
packages/typescript-client/test/expired-shapes-cache.test.ts	Rewrite regression tests to assert URL uniqueness invariant
AGENTS.md	Add note to read SPEC.md before working on typescript-client
.changeset/fix-handle-next-accumulation.md	Changeset for patch release

---

🤖 Generated with Claude Code

[pkg-pr-new]

Open in StackBlitz

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

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

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

commit: 7e7d88c

[codecov]

Codecov Report

❌ Patch coverage is 80.00000% with 3 lines in your changes missing coverage. Please review.
✅ Project coverage is 88.78%. Comparing base (deb2a61) to head (992502d).
⚠️ Report is 1 commits behind head on main.
✅ All tests successful. No failed tests found.

Files with missing lines	Patch %	Lines
packages/typescript-client/src/client.ts	80.00%	3 Missing ⚠️

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #3961   +/-   ##
=======================================
  Coverage   88.77%   88.78%           
=======================================
  Files          25       25           
  Lines        2415     2425   +10     
  Branches      604      612    +8     
=======================================
+ Hits         2144     2153    +9     
- Misses        269      270    +1     
  Partials        2        2           

Flag	Coverage Δ
packages/experimental	87.73% <ø> (ø)
packages/react-hooks	86.48% <ø> (ø)
packages/start	82.83% <ø> (ø)
packages/typescript-client	93.99% <80.00%> (-0.03%)	⬇️
packages/y-electric	56.05% <ø> (ø)
typescript	88.78% <80.00%> (+<0.01%)	⬆️
unit-tests	88.78% <80.00%> (+<0.01%)	⬆️

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.

[github-actions]

This PR has been released! 🚀

The following packages include changes from this PR:

• @electric-sql/client@1.5.11

Thanks for contributing to Electric!