# relay-exporter Prometheus exporter that probes a fixed set of Nostr relays (open / read / write-confirm) using `@nostrwatch/nocap`. Packaged as a Nix flake with a NixOS module (`services.relay-exporter`). User-facing docs (config env vars, metrics, live test knobs) live in README.md. Keep it in sync when behaviour, env vars, or metrics change. ## Layout - `src/index.ts`: HTTP server (`/metrics`, `/healthz`), probe loop, graceful shutdown - `src/config.ts`: env parsing (`loadConfig`), defaults, `DEFAULT_PROBE_CONCURRENCY` - `src/prober.ts`: `RelayProber`, which runs nocap open/read checks per relay - `src/writeConfirm.ts`: kind-30078 write + optional read-after-write verification - `src/metrics.ts`: `RelayMetrics` (prom-client gauges/counters) - `src/nocap*.d.ts`: hand-written type shims for nocap packages (no upstream types) - `test/`: `node:test` via tsx. `live.offchain.test.ts` hits the network and is skipped unless `LIVE_RELAY_TEST_OFFCHAIN=1` - `nostr-watch.code-workspace` pulls in `~/src/sandwichfarm/nostr-watch` for reading nocap source ## Commands Run everything inside the dev shell (`nix develop -c `) so Node/pnpm match the Nix build. - `pnpm test`: offline tests (~5s, live test skipped) - `pnpm build`: `tsc` to `dist/` - `nix build .#relay-exporter` and `nix flake check`: must both pass before committing - Smoke run: `RELAYS=wss://relay.damus.io PORT=19464 ./result/bin/relay-exporter`, then curl `/metrics` and `/healthz` ## Updating dependencies / nixpkgs Policy: on any update, move to the **latest stable runtime**: newest NixOS release branch, newest Node LTS (`pkgs.nodejs_`), and newest pnpm major. Don't just bump the one thing asked. Checklist (all of these must agree): 1. `flake.nix`: `nixpkgs.url` branch; `nodejs_` appears 3 times (build input, makeWrapper, devShell); `pnpm_` appears 3 times (build input, `fetchPnpmDeps { pnpm = ...; }`, devShell). Pin explicit versioned attrs, not bare `pkgs.pnpm` / `pkgs.nodejs`. 2. `package.json`: `packageManager` must match the flake's pnpm version. Otherwise pnpm in the dev shell silently switches to the pinned version. Bump `@types/node` to the Node major. 3. `nix flake update`, then in the dev shell `pnpm install` (delete `node_modules` first if the pnpm major changed: it errors with `ERR_PNPM_UNEXPECTED_STORE`). 4. Regenerate the `pnpmDeps` hash: set it to `sha256-AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=`, run `nix build`, copy the `got:` hash. The hash changes whenever the lockfile, pnpm major, or `fetcherVersion` changes. 5. Treat nixpkgs evaluation warnings (deprecated attrs, `fetcherVersion`) as work to do now. They become hard errors in the next release. 6. Verify: `nix build`, `nix flake check`, `pnpm test`, smoke run. Never push an update unverified. ## Gotchas - pnpm ≥11 fails installs on undecided dependency build scripts. Decisions live in `pnpm-workspace.yaml` under `allowBuilds`; all are currently `false` (the Nix build uses `--ignore-scripts` anyway). New deps with install scripts need an entry there. - nixpkgs marks old pnpm majors insecure. `nix flake check` evaluates the devShell, so a stale `pnpm_` there breaks the check even when the package builds. - Version strings differ: flake says `0.1.0`, `package.json` says `1.0.0`. - Remotes: `origin` (git.satstack.dev) is the upstream for `main`; `satstack` (gitea.satstack.dev) also exists. Confirm before pushing there. - `tsx` triggers a Node 26 `DEP0205` (`module.register()`) deprecation warning during tests. It's harmless; it goes away when tsx moves to `registerHooks`.