Files
relay-exporter/CLAUDE.md
T
plebandClaude Opus 5.5 741144d300 Bump to nixos-26.05, Node 26 LTS, and pnpm 11
- nixpkgs: nixos-25.11 -> nixos-26.05
- Node: nodejs_22 -> nodejs_26; @types/node ^25 -> ^26
- pnpm: pin pnpm_11 in build and devShell (pnpm_10 is marked insecure
  in 26.05); packageManager pnpm@10.28.0 -> pnpm@11.27.0
- Migrate to top-level fetchPnpmDeps/pnpmConfigHook and
  fetcherVersion 4 (v1 is removed in 26.11); regenerate deps hash
- Add pnpm-workspace.yaml declining dependency build scripts, which
  pnpm 11 requires to be decided explicitly
- Add CLAUDE.md with layout, commands, and update checklist

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-16 10:10:42 -08:00

3.5 KiB

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 <cmd>) 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_<N>), 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_<N> appears 3 times (build input, makeWrapper, devShell); pnpm_<N> 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_<old> 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.