Architecture
One Node process, one Postgres. Changes compile into versioned snapshots and are pushed to every SDK, which evaluates locally. Nothing on the evaluation path calls the control plane.
A change, in detail
| Step | What happens | Why |
|---|---|---|
| Write | Configuration, version bump and audit row commit in one transaction, checked against expectedVersion. | No lost edits, no change without an audit row. |
| Debounce | Changes to one environment are batched for 200ms (SNAPSHOT_DEBOUNCE_MS). | A dashboard edit is several writes; SDKs should apply one snapshot, not five. The kill switch skips this. |
| Compile | One node, holding a per-environment lock, compiles the whole environment into a snapshot with the next version. | Many nodes, one compile. |
| Fail safe | A compile that throws leaves the previous snapshot serving and counts a failure. | A bad change is silent, never wrong. |
| Announce | The snapshot is cached in Postgres, and other nodes hear through NOTIFY. | No Redis, no message bus. |
| Push | Each node sends patches to its server streams, and new values to the client connections they change. | Only what changed, only to who it changes for. |
Versions are stored, not counted in memory, so they only go up, across restarts and nodes. SDKs ignore any snapshot or patch older than what they hold, which makes duplicate and out-of-order delivery harmless.
Delivery
- Streaming is server-sent events. A heartbeat goes out every 30 seconds.
- Resume. A reconnecting SDK sends the version it has and gets only the patches since. The last
200 are kept (
PATCH_HISTORY_DEPTH); further back, it gets a full snapshot. - Polling is a first-class path, not a degraded one. The
ETagis the version, so a poll that's current is a304with no body. - Shedding. Past 10,000 server streams per node (
MAX_STREAM_CONNECTIONS), new ones get503and the SDK polls instead. Capacity degrades on a curve, not a cliff. - Missed notifications. If a node's
LISTENconnection drops silently, its snapshots re-check their version at least every 10 seconds, which bounds how stale it can get.
The client tier
A client connection holds one context. When a flag changes, the node evaluates it once per distinct fingerprint (the attributes the flag actually reads), not once per connection. 2,000 connections and 20 changed flags collapsed to 15 fingerprints and took 48ms. Connection records live in Postgres, so any node can resume a client's stream after a deploy.
Speed
Measured on Node 22, one core, against the code that ships:
| Check | Per call |
|---|---|
| Flag not found | 16ns |
| Flag off | 50ns |
| Fallthrough, no rules | 60ns |
| Individual target | 65ns |
| A rule with 2 clauses | 177ns |
| Segment match | 185ns |
| Percentage rollout (hashed) | 516ns |
For scale, one 1ms network round trip is about 2,000 times the slowest row. The first thing that hurts at scale isn't evaluation; it's compiling very large environments (10,000 flags takes about 60ms) and fan-out to many client connections. See capacity and the full benchmarks.
Correctness
- 870+ tests, including a chaos suite that kills the control plane under load and checks for zero evaluation errors and zero changed values.
- A conformance corpus pins bucketing, operators and precedence, including boundary buckets, non-ASCII keys and both polarities of negation, so a port to another language is held to the same answers.
- Every design decision is written down in decisions.md, including where the implementation departs from the plan.