- 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>
63 lines
3.5 KiB
Markdown
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`.
|