zzstoatzz.io
atproto relay implementation in zig
zlay.waow.tech
1# zlay
2
3an [AT Protocol](https://atproto.com/) relay in zig. subscribes to every PDS on the network, verifies commit signatures, and serves the merged event stream to downstream consumers.
4
5**live instance**: [zlay.waow.tech](https://zlay.waow.tech/_health) — [metrics dashboard](https://zlay-metrics.waow.tech)
6
7## design
8
9- **direct PDS crawl** — the bootstrap relay is called once at startup for the host list via `listHosts`, then all data flows directly from each PDS.
10
11- **optimistic signature validation** — on signing key cache miss, the frame passes through immediately and the DID is queued for background resolution. all subsequent commits are verified against the cached key. the cache caps at a configurable size and evicts the oldest 10% by resolve time when full.
12
13- **inline collection index** — indexes `(DID, collection)` pairs in the event processing pipeline using RocksDB. serves `listReposByCollection` from the relay process — no sidecar. the index design draws on [fig](https://tangled.org/microcosm.blue)'s work on [lightrail](https://tangled.org/microcosm.blue/lightrail).
14
15- **reader thread per PDS + frame processing pool** — each PDS gets a lightweight reader thread (cursor tracking, rate limiting, header decode). heavy work (full CBOR decode, validation, DB persist, broadcast) runs on a shared pool of frame workers (configurable, default 16).
16
17## spec compliance
18
19implements the [AT Protocol sync spec](https://atproto.com/specs/sync) — `subscribeRepos`, `listRepos`, `getRepoStatus`, `getLatestCommit`, `listReposByCollection`, `listHosts`, `getHostStatus`, and `requestCrawl`.
20
21## dependencies
22
23| dependency | purpose |
24|---|---|
25| [zat](https://tangled.org/zzstoatzz.io/zat) | AT Protocol primitives (CBOR, CAR, signatures, DID resolution) |
26| [websocket.zig](https://github.com/zzstoatzz/websocket.zig) | WebSocket client/server (fork with HTTP fallback + TCP split fixes) |
27| [pg.zig](https://github.com/karlseguin/pg.zig) | PostgreSQL driver |
28| [rocksdb-zig](https://github.com/Syndica/rocksdb-zig) | RocksDB bindings |
29
30## build
31
32requires zig 0.15 and a C/C++ toolchain (for RocksDB).
33
34```bash
35zig build # build (debug)
36zig build test # run tests
37zig build -Doptimize=ReleaseSafe # release build (production default)
38```
39
40## configuration
41
42| variable | default | description |
43|---|---|---|
44| `RELAY_PORT` | `3000` | firehose + API port |
45| `RELAY_METRICS_PORT` | `3001` | prometheus metrics port |
46| `RELAY_UPSTREAM` | `bsky.network` | bootstrap relay for initial host list |
47| `RELAY_DATA_DIR` | `data/events` | event log storage |
48| `RELAY_RETENTION_HOURS` | `72` | event retention window |
49| `COLLECTION_INDEX_DIR` | `data/collection-index` | RocksDB collection index path |
50| `DATABASE_URL` | — | PostgreSQL connection string |
51| `RELAY_ADMIN_PASSWORD` | — | bearer token for admin endpoints |
52| `RESOLVER_THREADS` | `4` | background DID resolution threads |
53| `FRAME_WORKERS` | `16` | frame processing pool worker count |
54| `FRAME_QUEUE_CAPACITY` | `4096` | max queued frames before backpressure |
55| `VALIDATOR_CACHE_SIZE` | `250000` | max cached signing keys before eviction |
56
57see [docs/deployment.md](docs/deployment.md) for production deployment and [docs/backfill.md](docs/backfill.md) for collection index backfill.
58
59## license
60
61MIT