electric-sql / electric-sql/electric-circuits

Extended API caching: serve shape feeds via the Rust DS server's built-in CDN protocol

Open
#11 1 comment 0 reactions 0 assignees View on GitHub
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.