electric-sql / electric-sql/electric-circuits
Extended API caching: serve shape feeds via the Rust DS server's built-in CDN protocol
- Dominant language
- Rust
- Stars
- 30
- Forks
- 6
- PR merge metrics
- No merged PRs in 30d
Description
Companion to #10 (different surface: the extended API's read path is the durable-streams server, not the engine). Investigation of `../electric-ds-rust-1m` (packages/durable-streams-rust) found it **already ships the cache protocol we need**, while the npm `@durable-streams/server` we deploy today has none of it:
- Historical offset-addressed reads: immutable ranges served `public, max-age=60, stale-while-revalidate=300` + range-derived ETag (`"{stream}:{start}:{end}"`), with If-None-Match → 304 (`handlers.rs:1970-2019`).
- CDN request collapsing built in: `stream-cursor` header + `cursor` param, 20s time buckets with 1–180-interval jitter (`store.rs:1237-1262`).
- Tail/`now` reads correctly `no-store` + no ETag; `stream-next-offset` / `stream-up-to-date` on everything.
**Scope:**
1. Make the Rust DS server the client-facing feed path for production deployments (docker overlay + docs); keep the npm server for tests/demos. *(Pending the broader "which DS is the production target" decision — issue text to be updated if that lands differently.)*
2. Client: send `cursor` on long-polls and honor 304s (`packages/client` stream reader currently uses only `offset` + `live=long-poll`).
3. `ShapeHandle.streamUrl` should be the CDN-fronted URL (config knob on the API server), not the origin DS address.
4. Optional upstream patch to ds-rust: per-stream cache policy at create time (e.g. `stream-cache-max-age`) so initial-snapshot chunks can get Electric's week-long tier instead of the hardcoded 60s. Requires new `StreamConfig`/`Meta` fields, parsing in `handle_create`, echo in read builders, and relaxing the `&'static str` header-name type in `api.rs` (`handlers.rs:120,431-465`, `store.rs:38-48`).
**Non-goals:** engine `/v1/shape` caching (#10); auth on feed URLs (auth issue, TBD).
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Contributor guide
Research direction
First resolve the pending production-DS decision, then read packages/durable-streams-rust handlers.rs:1970-2019 and store.rs:1237-1262, followed by packages/client's stream reader and ShapeHandle.streamUrl. Check the docker overlay and deployment docs. Done means the chosen production feed path supports the requested cursor/304 behavior and CDN URL configuration; the optional ds-rust policy work is separate.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- docker, rust
- Domain
- backend-api-design, cloud, distributed-systems, documentation
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Needs clarification
- Newbie friendliness
- 35/100