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

63 lines
3.5 KiB
Markdown

# 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`.