# zlay

an [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.

**live instance**: [zlay.waow.tech](https://zlay.waow.tech/_health) — [metrics dashboard](https://zlay-metrics.waow.tech)

## design

- **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.

- **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.

- **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).

- **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).

## spec compliance

implements the [AT Protocol sync spec](https://atproto.com/specs/sync) — `subscribeRepos`, `listRepos`, `getRepoStatus`, `getLatestCommit`, `listReposByCollection`, `listHosts`, `getHostStatus`, and `requestCrawl`.

## dependencies

| dependency | purpose |
|---|---|
| [zat](https://tangled.org/zzstoatzz.io/zat) | AT Protocol primitives (CBOR, CAR, signatures, DID resolution) |
| [websocket.zig](https://github.com/zzstoatzz/websocket.zig) | WebSocket client/server (fork with HTTP fallback + TCP split fixes) |
| [pg.zig](https://github.com/karlseguin/pg.zig) | PostgreSQL driver |
| [rocksdb-zig](https://github.com/Syndica/rocksdb-zig) | RocksDB bindings |

## build

requires zig 0.15 and a C/C++ toolchain (for RocksDB).

```bash
zig build                          # build (debug)
zig build test                     # run tests
zig build -Doptimize=ReleaseSafe   # release build (production default)
```

## configuration

| variable | default | description |
|---|---|---|
| `RELAY_PORT` | `3000` | firehose + API port |
| `RELAY_METRICS_PORT` | `3001` | prometheus metrics port |
| `RELAY_UPSTREAM` | `bsky.network` | bootstrap relay for initial host list |
| `RELAY_DATA_DIR` | `data/events` | event log storage |
| `RELAY_RETENTION_HOURS` | `72` | event retention window |
| `COLLECTION_INDEX_DIR` | `data/collection-index` | RocksDB collection index path |
| `DATABASE_URL` | — | PostgreSQL connection string |
| `RELAY_ADMIN_PASSWORD` | — | bearer token for admin endpoints |
| `RESOLVER_THREADS` | `4` | background DID resolution threads |
| `FRAME_WORKERS` | `16` | frame processing pool worker count |
| `FRAME_QUEUE_CAPACITY` | `4096` | max queued frames before backpressure |
| `VALIDATOR_CACHE_SIZE` | `250000` | max cached signing keys before eviction |

see [docs/deployment.md](docs/deployment.md) for production deployment and [docs/backfill.md](docs/backfill.md) for collection index backfill.

## license

MIT