atproto relay implementation in zig
zlay.waow.tech
docs: add README with live instance, endpoints, design overview
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
+58
+58
README.md
+58
README.md
···
1
+
# zlay
2
+
3
+
an [AT Protocol](https://atproto.com/) relay in zig. crawls PDS hosts directly and rebroadcasts their firehose as a single aggregated stream.
4
+
5
+
**live instance**: [zlay.waow.tech](https://zlay.waow.tech/_health) — [metrics dashboard](https://zlay-metrics.waow.tech)
6
+
7
+
## what it does
8
+
9
+
a relay subscribes to every PDS on the network, verifies commit signatures, and serves the merged event stream to downstream consumers via `com.atproto.sync.subscribeRepos`. it also maintains a collection index for `com.atproto.sync.listReposByCollection`.
10
+
11
+
## design
12
+
13
+
- **direct PDS crawl** — no fan-out relay in between. the bootstrap relay (bsky.network) is called once at startup for the host list, then all data flows from each PDS.
14
+
- **optimistic validation** — on signing key cache miss, frames pass through immediately and the DID is queued for background resolution. >99.9% cache hit rate after warmup.
15
+
- **inline collection index** — RocksDB with two column families for bidirectional `(DID, collection)` lookups. no sidecar process.
16
+
- **one thread per PDS** — predictable memory, no GC. ~2,750 threads is fine; most are blocked on websocket reads.
17
+
18
+
## dependencies
19
+
20
+
| dependency | purpose |
21
+
|---|---|
22
+
| [zat](https://tangled.org/zzstoatzz.io/zat) | AT Protocol primitives (CBOR, CAR, signatures, DID resolution) |
23
+
| [websocket.zig](https://github.com/nicholasgasior/websocket.zig) | WebSocket client/server |
24
+
| [pg.zig](https://github.com/karlseguin/pg.zig) | PostgreSQL driver |
25
+
| [rocksdb-zig](https://github.com/Syndica/rocksdb-zig) | RocksDB bindings |
26
+
27
+
## endpoints
28
+
29
+
| endpoint | method |
30
+
|---|---|
31
+
| `com.atproto.sync.subscribeRepos` | WebSocket (port 3000) |
32
+
| `com.atproto.sync.listRepos` | GET |
33
+
| `com.atproto.sync.getRepoStatus` | GET |
34
+
| `com.atproto.sync.getLatestCommit` | GET |
35
+
| `com.atproto.sync.listReposByCollection` | GET |
36
+
| `com.atproto.sync.listHosts` | GET |
37
+
| `com.atproto.sync.requestCrawl` | POST |
38
+
39
+
## build
40
+
41
+
requires zig 0.15 and a C/C++ toolchain (for RocksDB).
42
+
43
+
```bash
44
+
zig build # build
45
+
zig build test # run tests
46
+
zig build -Doptimize=ReleaseSafe # release build
47
+
```
48
+
49
+
see [docs/deployment.md](docs/deployment.md) for production deployment and [docs/backfill.md](docs/backfill.md) for collection index backfill.
50
+
51
+
## numbers
52
+
53
+
| metric | value |
54
+
|---|---|
55
+
| code | ~6,000 lines |
56
+
| connected PDS hosts | ~2,750 |
57
+
| memory | ~2.9 GiB steady state |
58
+
| throughput | ~600 events/sec typical |