# gotchas

hard-won knowledge from debugging zlay. check here before guessing.

## zig 0.15

- `&.{...}` in loops creates stack-local arrays that alias across iterations — all references point to same memory. heap-allocate instead.
- operator precedence: `(byte & 0xf0) == 0` not `byte & 0xf0 == 0`
- `ArrayList` is unmanaged — pass allocator to each method
- `f.readAll()` not `f.reader().readAll()` — `File.reader()` takes a buffer arg in zig 0.15

## pg.zig

- `pool.rowUnsafe()` for single-row queries — `.get(T, col)` returns `T`
- `pool.query()` + `result.nextUnsafe()` for multi-row
- `QueryRow.deinit()` returns `!void` — use `defer row.deinit() catch {}`
- DB-dependent tests skip via `requireDatabaseUrl()` → `error.SkipZigTest`

## rocksdb-zig

- iterator `Data` has `.free = rocksdb_free` but points to internal buffers — do NOT call `.deinit()` on iterator entries (SIGABRT). only deinit `Data` from `db.get()`
- `DB.open` passes `dir.ptr` raw to C API — path must be null-terminated (use `realpathAlloc` or zero-init buffer)
- `ColumnFamilyOptions` is a stub — use `extern fn rocksdb_set_options_cf` to set options post-open

## websocket.zig fork

fork of karlseguin/websocket.zig with patches:
- `httpFallback`: `_handleHandshake` catches parse errors, routes to `H.httpFallback` if present — this is how all HTTP API endpoints are served on the WS port
- lenient handshake parser: non-WS headers skip instead of error

## metrics

- mallinfo() overflows at 2 GiB (c_int fields) — smaps metrics are the reliable RSS source
- `relay_build_info{git_sha,optimize}` confirms what binary is running

## deploy

- containers are minimal debian — no curl, wget, or shell utilities. use busybox pod or `kubectl port-forward`
- two separate kubeconfigs: Go relay (`kubeconfig.yaml`) vs zlay (`zlay-kubeconfig.yaml`)
- `$ZLAY_KUBECONFIG` is only set inside `just` — raw shell needs the absolute path
- after `helm upgrade`, must `kubectl set image` back to SHA tag (helm uses `latest` from values)
- never change probe paths and image in separate operations (see [incident-2026-03-04.md](incident-2026-03-04.md))