atproto relay implementation in zig
zlay.waow.tech
docs: add postgres, websocket fork, and ops knowledge to CLAUDE.md
stash operational context from zat project memory into the zlay repo
where it belongs — pg.zig API patterns, websocket.zig fork details,
metrics gotchas (mallinfo overflow, File.reader API), and deploy
operational tips (minimal containers, helm SHA tag dance).
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
+29
+29
CLAUDE.md
+29
CLAUDE.md
···
61
61
- probes: `/_healthz` (liveness), `/_readyz` (readiness, DB check)
62
62
- `relay_build_info{git_sha,optimize}` metric confirms what's running
63
63
64
+
## postgres
65
+
66
+
schema: `account`, `account_repo` (rev/cid), `log_file_refs`, `host`, `domain_ban`, `backfill_progress`.
67
+
68
+
pg.zig patterns:
69
+
- `pool.rowUnsafe()` for single-row queries — `.get(T, col)` returns `T`
70
+
- `pool.query()` + `result.nextUnsafe()` for multi-row
71
+
- `QueryRow.deinit()` returns `!void` — use `defer row.deinit() catch {}`
72
+
- DB-dependent tests skip via `requireDatabaseUrl()` → `error.SkipZigTest`
73
+
74
+
## websocket.zig fork
75
+
76
+
fork of karlseguin/websocket.zig with patches:
77
+
- `httpFallback`: `_handleHandshake` catches parse errors, routes to `H.httpFallback`
78
+
if present — this is how all HTTP API endpoints are served on the WS port
79
+
- lenient handshake parser: non-WS headers skip instead of error
80
+
- all HTTP + WS on port 3000, metrics-only on 3001
81
+
82
+
## operational notes
83
+
84
+
- containers are minimal debian — no curl, wget, or shell utilities.
85
+
use busybox pod or `kubectl port-forward` to check metrics
86
+
- two separate kubeconfigs: Go relay (`kubeconfig.yaml`) vs zlay (`zlay-kubeconfig.yaml`)
87
+
- `$ZLAY_KUBECONFIG` is only set inside `just` — raw shell needs the absolute path
88
+
- after `helm upgrade`, must `kubectl set image` back to SHA tag (helm uses `latest` from values)
89
+
- `f.readAll()` not `f.reader().readAll()` — `File.reader()` takes a buffer arg in zig 0.15
90
+
- mallinfo() overflows at 2 GiB (c_int fields) — smaps metrics are the reliable RSS source
91
+
- rocksdb-zig `ColumnFamilyOptions` is a stub — use `extern fn rocksdb_set_options_cf` post-open
92
+
64
93
## zig gotchas relevant here
65
94
66
95
- `&.{...}` in loops creates stack-local arrays that alias — heap-allocate instead