/v1/shape HTTP caching: cache-control tiers, ETag/304, cursor collapsing, 10MB chunking
Nobody has claimed this yet.
Assessment
- Difficulty
- 5/5
- Estimated time
- Over a week
- Newbie friendliness
- 42/100
- Issue type
- Feature
- Clarity
- Mostly clear
- Activity status
- Quiet
- Tech stack
- rust
- Domain
- api, backend, performance
Research direction
Read apps/engine/src/electric.rs at lines 652 and 698, then compare upstream shapes/api/response.ex and utils.ex:59-93; account for dependency #8 before changing cache behavior. Done means the shape endpoint implements the specified cache tiers, ETag/304 handling, cursor bucketing, 10 MB offsets, cacheable long-poll responses, and the send_cache_headers off-switch.
Written by the indexing model from the issue text.
Description
Today every /v1/shape response is cache-control: no-store (apps/engine/src/electric.rs:652,698), the client's cursor is ignored, there is no ETag, and snapshot bodies are unbounded. Zero CDN/edge offload. Depends on #8 (handles/offsets must survive restarts, or cached URLs point at dead handles).
Adopt upstream sync-service's scheme (values encode real CDN tuning — copy verbatim, refs into shapes/api/response.ex):
- Cache-control tiers: snapshot
public, max-age=604800, s-maxage=3600, stale-while-revalidate=2629746; catch-uppublic, max-age=60, stale-while-revalidate=300(configurable); livepublic, max-age=5, stale-while-revalidate=5; 409 must-refetchpublic, max-age=1(no handle) /60(with handle) +must-revalidate; other errorsno-store+surrogate-control: no-store. - ETag + If-None-Match → 304: etag
"<handle>:<request offset>:<chunk end offset>"; empty live responses get a monotonic suffix so CDNs never serve them from cache (forces origin collapsing). electric-cursortime-bucketing: bucket = long-poll window, with jitter on rollover, so concurrent live pollers share a URL and CDNs collapse them to one origin request (upstreamutils.ex:59-93).- Response chunking at 10 MB: cap each response's read size and return
electric-offsetat the cut; client re-requests from there (fresh cacheable URL). Our DS offsets are byte-positioned so no storage change is needed. - Long-poll timeout → 200 +
[up-to-date]control (+electric-has-data: false) instead of today's 204 — the 200 is the cacheable/collapsible response, and it matches upstream exactly (conformance win). send_cache_headersoff-switch for deployments without a CDN.
Non-goal here: the extended API read path (durable-streams server) — separate issue, different surface; investigating whether the DS implementation supports per-stream/response cache headers.
🤖 Generated with Claude Code
- Dominant language
- Rust
- Stars
- 31
- Forks
- 7
- PR merge metrics
- No merged PRs in 30d
Getting set up
- No Dockerfile or Docker Compose file
- No pull request template
- Read the contributing guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
More from electric-sql/electric-circuits
-
Difficulty 5/5 Over a week Newbie friendliness 25/100
-
Difficulty 5/5 Over a week Newbie friendliness 35/100
-
Difficulty 5/5 Over a week Newbie friendliness 35/100
-
Difficulty 5/5 Over a week Newbie friendliness 35/100
-
Difficulty 5/5 Over a week Newbie friendliness 35/100
All issues in electric-sql/electric-circuits
Similar issues
-
agent duplicate providers tool triaged
Difficulty 2/5 1-3 hours Newbie friendliness 74/100
Maintainers usually reply within 1 day
-
Difficulty 2/5 1-3 hours Newbie friendliness 68/100
Maintainers usually reply within 1 day
-
founders_reward panics on a configured Testnet when the slow-start subsidy is not a multiple of 5Openexternal-contribution
Difficulty 2/5 1-3 hours Newbie friendliness 78/100
ZcashFoundation/zebra#11792 ·
Maintainers usually reply within 1 day
-
content:edit documentation effort:high
Difficulty 1/5 1-3 hours Newbie friendliness 67/100
cloudflare/cloudflare-docs#34428 ·
Maintainers usually reply within 1 day
-
area/cli bug
Difficulty 2/5 1-3 hours Newbie friendliness 85/100