zlay #

an AT Protocol 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 — metrics dashboard

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 least recently used entry 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's work on lightrail.

• reader per PDS + frame processing pool — each PDS gets a lightweight reader (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).

• pluggable std.Io backend — the relay is written against zig's std.Io interface. the default backend is Io.Threaded (one OS thread per blocking call site); production runs zio (-Dbackend=zio), which schedules the same code as cooperative fibers on a single epoll-driven scheduler thread — ~90 threads instead of ~2,800 at fleet scale, for a ~40% RSS reduction.

spec compliance #

implements the relay endpoints from the AT Protocol sync spec: subscribeRepos, listRepos, getRepoStatus, listHosts, getHostStatus, and requestCrawl.

also implements getLatestCommit, listReposByCollection, and getRepo (302 redirect to PDS) for compatibility with the indigo relay reference implementation.

dependencies #

build #

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

zig build                          # build (debug)
zig build test                     # run tests
zig build -Doptimize=ReleaseSafe   # release build (production default)
zig build -Dbackend=zio            # zio std.Io backend (production runs ReleaseSafe + zio)
just docker-build                 # local container, native Linux architecture
just docker-build linux/amd64     # production-compatible container

configuration #

see docs/deployment.md for production deployment and docs/backfill.md for collection index backfill.

license #

MIT