zat.dev / zat
atproto utils for zig zat.dev
atproto sdk zig
Star
Fork 2
Watch
zat docs roadmap.md
3.5 kB
Markdown
at star-lite

roadmap #

zat started as a small set of string primitives for AT Protocol — the types everyone reimplements (Tid, Did, Handle, Nsid, Rkey, AtUri). the scope grew based on real usage, and this page tracks where that leaves the library: what it covers today, what's likely next, and what stays out.

where it is #

v0.3.11 — zig 0.16, std.Io throughout.

the library covers both sides of the repo lifecycle:

  • verify: identity resolution, CAR/MST parsing, and commit verification (verifyCommitCar for full repos, verifyCommitDiff for firehose diffs) — with hardening for malformed MSTs, incomplete CARs, and unsafe network targets (SSRF guards on resolution)
  • produce: signCommit builds and signs canonical repo commits, the mirror of verifyCommitCar — PDS-shaped consumers no longer hand-roll commit CBOR
  • connect: XRPC client with checked results and retry policy, jetstream and raw firehose clients with subscribe(handler) reconnection, and a framework-neutral OAuth 2.1 + DPoP client toolkit

it passes the atproto interop test suite and is benchmarked against the Go, Rust, Python, and Elixir ecosystems in atproto-bench. downstream consumers (zds, zlay, and the projects in the README's "used by" section) continue to drive the hardening work.

what's next #

near-term:

  • keep validating the v0.3.x surface in production consumers
  • promote repeated downstream patterns into the library once they prove stable
  • candidates surfaced by the publish-docs showcase, which still hand-rolls plumbing on top of XrpcClient: typed com.atproto.repo write helpers (createRecord / putRecord / applyWrites) and a Tid.now(io) constructor (today only fromTimestamp exists). session/login stays app-specific — see "maybe later".

what's missing will show up when people build things. until then, no speculative features.

maybe later #

these stay out of scope unless real demand emerges:

  • lexicon codegen — probably a separate project
  • higher-level clients/frameworks — too opinionated
  • token refresh/session management — app-specific
  • feed generator scaffolding — each feed is unique

non-goals #

zat is not trying to be:

  • a "one true SDK" that does everything
  • an opinionated app framework
  • a replacement for understanding the protocol

how it got here #

each era was pulled in by something downstream needed, not planned up front:

  • v0.1.x — primitives to streams: string parsing and validation, DID/handle resolution, XRPC + JSON helpers, JWT service auth, then the jetstream and raw firehose clients with the DAG-CBOR/CAR codecs under them
  • v0.2.x — verification and auth: MST, ECDSA signing, did:key; end-to-end repo verification from handle to MST root match (v0.2.0); CID hash verification and size limits in the CAR parser; the OAuth 2.1 DPoP client (v0.2.14)
  • v0.3.x — std.Io and both sides of the repo: the 0.16 std.Io migration and subscribe(handler) streaming (v0.3.0), checked XRPC results and SSRF-safe resolution (v0.3.1), the OAuth toolkit (v0.3.7), Atmos-informed MST performance (v0.3.5), MST/CAR hardening (v0.3.9), and the produce-side signCommit (v0.3.10)

the changelog has the full record. this pattern — start minimal, expand based on real pain — continues.