Add POST support for subset snapshots to avoid URL length limits

[KyleAMathews]

Summary

Adds HTTP POST support for subset snapshots, allowing clients to send subset parameters (WHERE clauses, ordering, pagination) in the request body instead of URL query parameters. This prevents HTTP 414 Request-URI Too Long errors that occur with complex queries or large IN lists (common in join-loaded queries with hundreds of IDs).

Root Cause

When using fetchSnapshot with large parameter lists (e.g., WHERE id = ANY($1) with hundreds of IDs), the encoded query parameters can exceed browser and CDN URL length limits (~2KB for many CDNs, ~8KB for most browsers), causing 414 errors. There's no way to work around this with GET requests.

Approach

Backend (Elixir):

• Added POST route for /v1/shape alongside existing GET
• New parse_body/2 plug parses JSON request bodies with proper error handling (400 for invalid JSON with details, 413 for oversized bodies)
• merge_body_params/2 merges subset params from body with query params, body taking precedence
• Supports both nested ({"subset": {...}}) and flat subset parameter formats

Frontend (TypeScript):

• Added subsetMethod option on ShapeStream for default method selection
• Added method option on SubsetParams for per-request override
• Defaults to GET for backwards compatibility
• Extracted #buildSubsetBody helper to construct POST body with column mapper encoding

Key Invariants

1. Body params override query params when both present (allows query string defaults with body overrides)
2. Column mapper encoding applies to both GET and POST paths
3. Server error messages are preserved and surfaced to client via FetchError.fromResponse()
4. CDN infinite loop fix preserved: lastSeenCursor cleared after first suppression

Non-goals

• Changing default to POST (breaking change, deferred to Electric 2.0)
• Supporting POST for regular shape streaming (only affects fetchSnapshot/requestSnapshot)

Trade-offs

GET as default vs POST as default:
Chose GET as default for backwards compatibility. Documentation recommends POST for large queries. Will deprecate GET in Electric 2.0.

Flat vs nested body format:
Server accepts both {"where": "..."} and {"subset": {"where": "..."}} to match flexibility of query string format.

Verification

# TypeScript client tests
cd packages/typescript-client && pnpm test

# Type checking
pnpm tsc --noEmit

Files Changed

• packages/sync-service/lib/electric/plug/router.ex - Added POST route, updated CORS
• packages/sync-service/lib/electric/plug/serve_shape_plug.ex - Added parse_body, merge_body_params, error logging
• packages/typescript-client/src/client.ts - Added POST support in fetchSnapshot, #buildSubsetBody helper, fixed error handling
• packages/typescript-client/src/types.ts - Added method to SubsetParams
• website/docs/api/http.md - POST endpoint documentation
• website/docs/api/clients/typescript.md - Client usage documentation
• website/docs/guides/troubleshooting.md - 414 error troubleshooting guide
• website/electric-api.yaml - OpenAPI spec for POST endpoint

---

🤖 Generated with Claude Code

https://claude.ai/code/session_016ij4YWznxum2ytc8a8aQPK

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

• 🔍 Trigger a full review

---

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

[pkg-pr-new]

Open in StackBlitz

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

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

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

commit: 97fd2cb

[netlify]

✅ Deploy Preview for electric-next ready!

Name	Link
🔨 Latest commit	c373fc4
🔍 Latest deploy log	https://app.netlify.com/projects/electric-next/deploys/6978ee1fcde4780008e41e1d
😎 Deploy Preview	https://deploy-preview-3777--electric-next.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[codecov]

Codecov Report

❌ Patch coverage is 31.25000% with 22 lines in your changes missing coverage. Please review.
✅ Project coverage is 86.56%. Comparing base (571ed07) to head (97fd2cb).
⚠️ Report is 3 commits behind head on main.
✅ All tests successful. No failed tests found.

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

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #3777      +/-   ##
==========================================
+ Coverage   84.15%   86.56%   +2.40%     
==========================================
  Files          44       23      -21     
  Lines        2834     2039     -795     
  Branches      535      543       +8     
==========================================
- Hits         2385     1765     -620     
+ Misses        447      272     -175     
  Partials        2        2              

Flag	Coverage Δ
elixir	?
elixir-client	?
packages/experimental	87.73% <ø> (ø)
packages/react-hooks	86.48% <ø> (ø)
packages/start	82.83% <ø> (ø)
packages/typescript-client	92.12% <31.25%> (-1.36%)	⬇️
packages/y-electric	56.05% <ø> (ø)
typescript	86.56% <31.25%> (-0.81%)	⬇️
unit-tests	86.56% <31.25%> (+2.40%)	⬆️

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.

[robacourt]

Nice. LGTM 👍

[github-actions]

This PR has been released! 🚀

The following packages include changes from this PR:

• @core/sync-service@1.4.0
• @electric-sql/client@1.5.0

Thanks for contributing to Electric!