Add make add-dependency and make tidy (closes #45)

No entrypoint could change yarn.lock or go.mod: script/bootstrap
installs with --frozen-lockfile, so adding a package meant running
yarn by hand. make add-dependency PACKAGE=<name>@<version> shims to
the new script/add-dependency: yarn add --dev, then yarn install
--frozen-lockfile. make tidy shims to the new script/tidy, go mod
tidy in backend/; a Go module is added by importing it, or moved by
editing its require line, then make tidy. script/bootstrap is
unchanged.

Model: opus-5-5

.prettierignore

@@ -1,6 +1,7 @@
-backend/
 dist/
 node_modules/
 tmp/
 yarn.lock
 .claude/
+# The org standard file, copied verbatim; backend/script/lint checks its sha256.
+backend/.golangci.yml

Dockerfile

@@ -1,6 +1,6 @@
 # The one image netwatch ships: nginx serves the built frontend and
-# passes /api/ and /.well-known/healthcheck to netwatch-server, the Go
+# passes /api/, /.well-known/healthcheck and /metrics to netwatch-server,
-# backend, which runs in the same container on loopback only.
+# the Go backend, which runs in the same container on loopback only.
 # bin/entrypoint.sh starts and watches both.
 
 # Lint stage — fast feedback on formatting and lint issues. The
@@ -20,7 +20,10 @@ RUN make lint
 # golang:1.25-alpine (2026-02-27)
 FROM golang:1.25-alpine@sha256:f6751d823c26342f9506c03797d2527668d095b0a15f1862cddb4d927a7a4ced AS builder
 
-RUN apk add --no-cache git make
+# gcc and musl-dev are for make test: its race detector needs cgo, which
+# Go turns on by itself once a C compiler is present. make build still
+# sets CGO_ENABLED=0, so the binary stays static.
+RUN apk add --no-cache gcc git make musl-dev
 
 WORKDIR /src
 
@@ -56,20 +59,35 @@ RUN version="${VERSION:-$(git --git-dir=/git describe --tags --always)}"; \
     esac; \
     VERSION="$version" make build
 
+# Frontend lint stage — eslint over the JavaScript, as the lint stage
+# above lints the Go. The root make lint builds this stage alone too.
+# node:22-alpine as of 2026-02-22
+FROM node@sha256:e4bf2a82ad0a4037d28035ae71529873c069b13eb0455466ae0bc13363826e34 AS frontend-lint
+WORKDIR /app
+COPY package.json yarn.lock ./
+RUN yarn install --frozen-lockfile
+COPY . .
+RUN script/frontend-lint
+
 # Frontend stage
 # node:22-alpine as of 2026-02-22
 FROM node@sha256:e4bf2a82ad0a4037d28035ae71529873c069b13eb0455466ae0bc13363826e34 AS frontend
 WORKDIR /app
+
+# Force BuildKit to run the frontend-lint stage before proceeding, as
+# the builder stage does with the lint stage: without this no-op copy an
+# eslint failure would not gate the image.
+COPY --from=frontend-lint /app/yarn.lock /dev/null
+
 COPY package.json yarn.lock ./
 RUN yarn install --frozen-lockfile
 RUN apk add --no-cache git make
 COPY . .
-# make frontend-check is the frontend half of make check (test + lint +
+# make frontend-check runs the frontend tests and format check; its test
-# fmt-check); its test step runs the unit tests, then the production
+# step runs the unit tests, then the production yarn build, so this both
-# yarn build, so this both produces dist/ and gates the image on
+# produces dist/ and gates the image on test and formatting regressions.
-# lint/fmt-check/test regressions.
+# This node stage has neither Go nor Docker; the frontend-lint, lint and
-# This node stage has neither Go nor Docker; the lint and builder stages
+# builder stages above gate the rest.
-# above gate the backend half.
 RUN make frontend-check
 
 # Runtime stage

Makefile

@@ -1,5 +1,5 @@
-.PHONY: bootstrap setup dev test lint fmt fmt-check check frontend-check \
+.PHONY: bootstrap setup dev build test lint fmt fmt-check check \
-	frontend-viewport-test docker hooks
+	add-dependency tidy frontend-check frontend-viewport-test docker hooks
 
 # Standard targets are thin shims; the implementations live in script/
 # per the scripts-to-rule-them-all pattern (see the Entrypoints section
@@ -13,7 +13,11 @@ setup:
 	@script/setup
 
 dev:
-	yarn dev
+	@script/dev
+
+# The frontend only; backend/Makefile's build target builds the Go server.
+build:
+	@script/build
 
 test:
 	@script/test
@@ -30,8 +34,16 @@ fmt-check:
 check:
 	@script/check
 
-# The frontend half of check, for Dockerfile's node build stage, which
+# make add-dependency PACKAGE=<name>@<version>. PACKAGE reaches the
-# has neither Go nor Docker. Use check everywhere else.
+# script through the environment, so the shell never reads it as code.
+add-dependency:
+	@script/add-dependency "$$PACKAGE"
+
+tidy:
+	@script/tidy
+
+# The frontend tests and format check, for Dockerfile's frontend stage,
+# which has neither Go nor Docker. Use check everywhere else.
 frontend-check:
 	@script/frontend-check
 

README.md

@@ -39,26 +39,45 @@ halves, so the root `make check` fails if either one is broken. We provide:
 - `script/bootstrap` — install all dependencies (the pinned node via nvm unless
   one new enough for the frontend's dependencies is installed, yarn via
   corepack, `yarn install --frozen-lockfile`, the pinned Go unless one at least
-  as new as `backend/go.mod` asks for is installed, and the Go modules), linking
+  as new as `backend/go.mod` asks for is installed, the Go modules, and gcc with
-  what it installs itself into `~/.local/bin`, which has to be on `PATH`. It
+  the C library headers unless gcc is installed, for the race detector in
-  installs no Go linter and not Docker: `make lint` runs the linter in Docker
+  `make test`), linking what it installs itself into `~/.local/bin`, which has
+  to be on `PATH`. It installs no Go linter and not Docker: `make lint` runs
+  both linters in Docker
 - `script/setup` — make a fresh clone ready for development: bootstrap plus the
   git pre-commit hook
+- `script/dev` — run the Vite dev server, which proxies `/api` to a locally
+  running `netwatch-server`
+- `script/build` — build the frontend for production into `dist/`;
+  `backend/script/build` builds the Go server
 - `script/projectname` — print the project name (used for the Docker image tag)
-- `script/test` — run `script/frontend-test`, then the backend's Go tests, both
+- `script/test` — run `script/frontend-test`, then `backend/script/test`, the
-  within one 30-second timeout
+  backend's Go tests with the race detector and coverage
-- `script/lint` — run `script/frontend-lint`, then golangci-lint in Docker, by
+- `script/lint` — run eslint, then golangci-lint, both in Docker, by building
-  building the lint stage of `Dockerfile` without the cache
+  the `frontend-lint` and `lint` stages of `Dockerfile` without the cache
 - `script/fmt` — format all files (writes): prettier, then gofmt over `backend/`
 - `script/fmt-check` — check formatting (read-only): prettier, then gofmt
 - `script/check` — run test, lint, and fmt-check
+- `script/add-dependency` — add a frontend package, or move one to another
+  version: `make add-dependency PACKAGE=<name>@<version>` runs `yarn add --dev`,
+  which changes `package.json` and `yarn.lock` together, then
+  `yarn install --frozen-lockfile`
+- `script/tidy` — run `go mod tidy` in `backend/`: to add a Go module, import it
+  and run `make tidy`; to move one to another version, edit its `require` line
+  in `backend/go.mod`, then run `make tidy`
 - `script/frontend-test` — run the unit tests in `test/unit/` with Node's
-  built-in test runner, then the production build
+  built-in test runner, through the `test` script in `package.json`, and if any
-- `script/frontend-lint` — run prettier in check mode
+  fails, run them again listing every test, and fail; then the production build.
-- `script/frontend-fmt` — format everything prettier understands (writes)
+  Each run has a 30-second timeout
+- `script/frontend-lint` — run eslint with the rules in `eslint.config.js`; it
+  runs inside the `frontend-lint` stage of `Dockerfile`, which `make lint`
+  builds
+- `script/frontend-fmt` — format everything prettier understands (writes), the
+  markdown in `backend/` included
 - `script/frontend-fmt-check` — check prettier formatting (read-only)
-- `script/frontend-check` — the frontend half of `script/check`, for
+- `script/frontend-check` — run `script/frontend-test` and
-  `Dockerfile`, whose node build stage has neither Go nor Docker
+  `script/frontend-fmt-check`, for the frontend stage of `Dockerfile`, which has
+  neither Go nor Docker
 - `script/frontend-viewport-test` — responsive-layout verification of the built
   frontend in a containerised headless Chrome (see
   [test/viewport/README.md](test/viewport/README.md)). Not part of
@@ -102,9 +121,12 @@ code lives in `src/main.js` with a class-based architecture:
   color-coded line segments, error regions, and DPR-aware scaling
 - **UI functions**: `buildUI()` constructs the DOM, `updateHostRow()` /
   `updateSummary()` / `updateHealthBox()` handle incremental updates
-- **`tick()`**: Main loop — measures all hosts in parallel via `Promise.all`,
+- **`tick()`**: Main loop — measures all hosts in parallel, pushing each host's
-  pushes samples, redraws UI. When paused, pushes blank markers (no probes, no
+  sample and redrawing its row as soon as its check ends, then redraws every
-  false outage)
+  row, the summary and the health box once the last check ends. The rows are
+  sorted then too, after the first round that is not discarded and every tenth
+  round after that. When paused, pushes blank markers (no probes, no false
+  outage)
 - **`Reporter`**: Posts collected samples to the backend
 
 ### Reporting
@@ -142,8 +164,8 @@ have all finished before the next round is due. When no WAN host answers, a
 recovery probe checks 4 random WAN hosts every half second, giving up the checks
 it started half a second before. As soon as one answers, a new round starts at
 once, as it does after an interval change. A round started early gives up the
-last round's checks if they are still waiting, and that round records nothing,
+last round's checks if they are still waiting, and that round records nothing
-so rounds never overlap. IPv4 only.
+more, so rounds never overlap. IPv4 only.
 
 ### Color coding
 
@@ -186,9 +208,9 @@ static file host (S3, GCS, Cloudflare Pages, Vercel, Netlify, GitHub Pages) or
 use the Docker image behind a reverse proxy.
 
 The Docker image, built from `Dockerfile`, is the whole service in one
-container: nginx serves the built frontend and passes `/api/` and
+container: nginx serves the built frontend and passes `/api/`,
-`/.well-known/healthcheck` to the Go backend, `netwatch-server`, which listens
+`/.well-known/healthcheck` and `/metrics` to the Go backend, `netwatch-server`,
-only inside the container, on `127.0.0.1:8081`. The image:
+which listens only inside the container, on `127.0.0.1:8081`. The image:
 
 - Listens on port 8080 by default (override with `PORT` env var)
 - Takes the client address from `X-Forwarded-For` only on requests from the
@@ -222,8 +244,10 @@ What the [upaas](https://git.eeqj.de/sneak/upaas) app for netwatch needs:
     - `CORS_ALLOWED_ORIGINS`, default empty: other origins whose pages may call
       the API
     - `DEBUG`, default `false`: debug logging
-    - `DATA_DIR`, default `/data/reports`: leave unset; reports kept outside
+    - `DATA_DIR`, default `/data/reports`: the directory the reports are kept
-      `/data` do not survive a redeploy
+      in: `/data` or a path below it, with no `.` or `..` part and no extra `/`.
+      The container also stops if the path goes through a symbolic link that
+      leads out of `/data` or is written as a full path
     - `TRUSTED_PROXIES`, default empty: set it to the address the reverse proxy
       in front of the container connects from, as an IP address or CIDR; several
       are separated by commas. nginx takes the client address from
@@ -234,6 +258,12 @@ What the [upaas](https://git.eeqj.de/sneak/upaas) app for netwatch needs:
       connects from one can write its own `X-Forwarded-For`, and through a port
       Docker publishes, every client may connect from the Docker network's
       gateway, such as `172.17.0.1`.
+    - `METRICS_USERNAME` and `METRICS_PASSWORD`, default empty: with both set,
+      the backend records Prometheus metrics of its requests and serves them at
+      `/metrics` on the container port, to requests with this user name and
+      password as their basic auth credentials. With neither set, there are no
+      metrics and `/metrics` is not found. One set without the other, or a user
+      name containing `:`, stops the container
 - **Health check:** the image's `HEALTHCHECK` requests
   `/.well-known/healthcheck` through nginx every 30 seconds, so it fails unless
   both nginx and the backend answer. upaas reads the container's health 60
@@ -257,8 +287,6 @@ properties.
 
 ## TODO
 
-- Add unit tests
-- Add eslint for JS linting (currently lint target runs prettier only)
 - Add configurable host list (environment variable or config file)
 - Add latency history export (CSV/JSON)
 - Add notification/alert when status changes to DEGRADED

TODO.md

@@ -23,6 +23,102 @@ latest run passes.
 
 # Completed Steps
 
+- 2026-10-04: a dependency can be added without running yarn or go by hand
+  (issue #45): `make add-dependency PACKAGE=<name>@<version>` shims to the new
+  `script/add-dependency`, which runs `yarn add --dev`, so `package.json` and
+  `yarn.lock` change together, then `yarn install --frozen-lockfile`; the same
+  command moves a package to another version. `make tidy` shims to the new
+  `script/tidy`, which runs `go mod tidy` in `backend/`: a Go module is added by
+  importing it, or moved by editing its `require` line, then `make tidy`.
+  `script/bootstrap` still installs with `--frozen-lockfile`
+- 2026-10-04: the backend serves Prometheus metrics (issue #94). With
+  `METRICS_USERNAME` and `METRICS_PASSWORD` both set, it records request
+  duration and response size through `go-http-metrics` and serves them, with
+  Go's runtime and process metrics, at `GET /metrics` behind basic auth with
+  those credentials; nginx passes `/metrics` to it as it does `/api/`. With
+  neither set there are no metrics and `/metrics` is 404; one without the other
+  stops the start with an error naming both, and so does a `METRICS_USERNAME`
+  containing `:`, with an error naming it. Only requests that reach the health
+  check or `POST /api/v1/reports` are recorded, not `/metrics` itself and not
+  every request as `GO_HTTP_SERVER_CONVENTIONS.md` shows, because the labels are
+  the request's path and method, which clients can make up without end. For
+  that, `POST /api/v1/reports` is now registered by its full path instead of
+  inside a `/api/v1` route group; it answers as before
+- 2026-10-04: `script/` and `Makefile` follow the org models (issue #28):
+  `make dev` shims to the new `script/dev`, the Vite dev server, and the new
+  `make build` to `script/build`, the frontend production build.
+  `.prettierignore` no longer leaves out `backend/`, so `make fmt` and
+  `make fmt-check` cover `backend/README.md`; it leaves out
+  `backend/.golangci.yml` by name, the org standard file whose sha256
+  `backend/script/lint` checks. `script/install-precommit` and the date on
+  `script/bootstrap`'s pins are the org model again; `script/bootstrap`,
+  `script/fmt` and `script/fmt-check` each say in a comment why they differ from
+  it
+- 2026-10-04: a frontend build on Node 26 or newer, such as `make test` on a
+  host with Node 26, no longer prints Node's warning that `module.register()` is
+  deprecated (issue #32); the build in `Dockerfile` runs on Node 22, which never
+  printed it. The call was in `@tailwindcss/node`, which `@tailwindcss/vite`
+  brings in at its own exact version; tailwind 4.3.1 calls
+  `module.registerHooks()` instead where Node has it. `yarn.lock` now has
+  `@tailwindcss/vite` and `tailwindcss` at 4.3.3, inside the ranges
+  `package.json` already allowed, and tailwind's own dependencies moved with
+  them. The built CSS changes only in how it is written out, in tailwind's
+  Firefox focus-ring rule, which no longer applies to iframes (the page has
+  none, so nothing on it looks different), and in tailwind's default sans-serif
+  font list, which the page does not use: `body` sets a monospace font
+- 2026-10-03: the frontend's unit tests cover what the page computes (issue
+  #21): `humanDuration`, the latency colours of a figure and of a sparkline
+  either side of each boundary, a target's min, max, average and median latency
+  over an empty history, an all-unreachable one and a mixed one, and each of the
+  four health states either side of its thresholds. `package.json` has a `test`
+  script, so `yarn run test` and `npm run test` run them, and
+  `script/frontend-test` runs it: quietly, and if a test fails, again with every
+  test listed, and then fails. `src/main.js` now exports `humanDuration`,
+  `HostState`, `latencyClass` and `latencyHex` for the tests; nothing it does
+  changed
+- 2026-10-03: the backend's logs are one stream (issue #27): fx logs its own
+  steps of starting and stopping through the backend's logger, so off a terminal
+  every line the backend's own logger and fx write is JSON, where fx used to
+  write plain text to stderr. A config file that is found but cannot be read now
+  stops the start with its error, logged as JSON like a bad setting, where it
+  used to end in a Go panic. A test runs the server as a child process and
+  checks both. The backend logs its name, version and architecture once at
+  start. The health check's uptime keys are now `uptime_seconds` and
+  `uptime_human`; its path, content type, `"status":"ok"` and 200 are unchanged.
+  `SENTRY_DSN`, `METRICS_USERNAME` and `METRICS_PASSWORD` are still read and
+  still unused, and left out of `backend/README.md`, until issues #94 and #95
+  wire them up
+- 2026-10-03: the frontend has a real linter (issue #47, and item 2 of issue
+  #28): `eslint` with its recommended rules, set in `eslint.config.js`, runs in
+  a new `frontend-lint` stage of `Dockerfile`, which the frontend stage waits
+  on, as the builder stage waits on the Go `lint` stage. `script/lint` builds
+  both stages without the cache and runs no linter on the host.
+  `script/frontend-lint` runs eslint where it used to repeat the prettier check
+  that `script/fmt-check` runs on the host, and `script/frontend-check`, run by
+  the frontend stage, is now the tests and the format check. `script/bootstrap`
+  wants node 22.13.0 or newer, as eslint 10 does
+- 2026-10-03: the tap-target check in `make frontend-viewport-test` expects one
+  visible pin button per WAN host row (issue #46), where it expected at least 10
+  of the 26, so pin buttons missing from only some rows now fail it. The host
+  row count the harness gathers, which the `app-rendered` check also reads, now
+  counts only the WAN host rows: the local host rows have no pin button
+- 2026-10-03: each target's row shows its result as soon as its check ends
+  (issue #91), where every row waited for the round's slowest check, up to 24
+  seconds at a 30-second interval. Every row is still redrawn, and sorting, the
+  summary, the health box and offline detection still run, once, when the
+  round's last check ends, so no row reads "paused" after a pause and resume
+  during the round. A check that ends after the user pauses or after its round
+  is given up shows nothing, and the first round is still discarded as a whole
+- 2026-10-03: root no longer acts outside `/data` when it prepares `DATA_DIR`
+  (issue #80): `bin/entrypoint.sh` runs `netwatch-server prepare-data-dir`,
+  which refuses a `DATA_DIR` that is not `/data` or a path below it written in
+  full, then creates `DATA_DIR`, gives `/data` and everything in it to
+  `netwatch` and sets the modes, all through a Go `os.Root` opened on `/data`.
+  That refuses any path leading out of `/data`, so neither a symbolic link
+  already there nor one a host process swaps in during the start can make root
+  create or change anything elsewhere, and `DATA_DIR=/etc` no longer gives
+  `/etc` to `netwatch`. The `README.md` section "Running under upaas" says which
+  values are accepted
 - 2026-10-03: `DATA_DIR_MAX_BYTES` is now how much of the report files is kept
   (issue #54): when a report would take them past it, the oldest report files
   are deleted to make room, each deletion logged, and at start files already
@@ -32,6 +128,25 @@ latest run passes.
   write stop counting, and the part of its file written is removed. A file that
   cannot be deleted still counts until the next start; one already deleted by
   hand counts as freed
+- 2026-10-03: `backend/script/lint` says what went wrong with its
+  `.golangci.yml` check (issue #34). On a hash mismatch it says to compare the
+  file with the org standard: if they differ, restore the org standard; if they
+  are the same, the org standard changed, so update `GOLANGCI_CONFIG_SHA256` in
+  that script. It used to say only to restore the file, which loops once the org
+  standard itself has moved. A missing `.golangci.yml`, and a `sha256sum` that
+  is missing or prints no hash, each get their own message instead of being
+  reported as a mismatch; every one still fails the lint
+- 2026-10-03: the Go tests run with the race detector and coverage (issue #88):
+  `backend/script/test` runs `go test -timeout 30s -race -cover ./...` and, if
+  that fails, runs it again with `-v` and fails. Go's `-timeout` bounds the
+  tests, not their compile; the root `script/test` no longer puts one 30-second
+  timeout around both halves, which a cold Go build cache could use up on
+  compiling alone. The race detector needs a C compiler: the builder stage of
+  `Dockerfile` has gcc and musl-dev, and `script/bootstrap` installs gcc, with
+  the C library headers on apt and apk, when gcc is missing; the binary is still
+  built with `CGO_ENABLED=0`. New tests cover the health check's answer, a valid
+  report's answer, a report file's exact contents, and the flush when the buffer
+  reaches 10 MiB; the handlers' `TestImport` stub is gone
 - 2026-10-03: each target check times out after 80% of the refresh interval
   (issue #78), 24 seconds at 30 seconds, where it was capped at 3 seconds. A
   round started early, after an interval change or when the recovery probe finds
@@ -201,9 +316,11 @@ latest run passes.
 - 2026-08-09: automated responsive-layout harness
   (`make frontend-viewport-test`): digest-pinned headless Chrome driven over CDP
   against the built `dist/`, viewport widths derived from the breakpoints in
-  `src/styles.css` ([#13](https://git.eeqj.de/sneak/netwatch/issues/13)). Every
+  `src/styles.css` ([#13](https://git.eeqj.de/sneak/netwatch/issues/13)). The
-  check carries a presence guard so none of them can pass against a page it is
+  tap-target and host-row checks each fail when they measured nothing; the
-  not actually measuring. Found two real layout defects, filed as
+  overflow, viewport-edge and clipped-text checks have no such guard of their
+  own and rely on the `app-rendered` check, which fails the run when the app did
+  not render. Found two real layout defects, filed as
   [#42](https://git.eeqj.de/sneak/netwatch/issues/42) and
   [#43](https://git.eeqj.de/sneak/netwatch/issues/43)
 - 2026-07-07 Adopted scripts-to-rule-them-all: `script/` entrypoints, Makefile

backend/README.md

@@ -32,14 +32,16 @@ pattern as the repo root: the targets in `backend/Makefile` are thin shims over
 `test`, `fmt` and `fmt-check`:
 
 - `script/build` — compile the static `netwatch-server` binary with its version
-  stamped in. The version is `VERSION` from the environment;
+  stamped in. The version is `VERSION` from the environment; when that is unset
-  when that is unset or empty, it falls back to `git describe` inside a git
+  or empty, it falls back to `git describe` inside a git checkout, then to `dev`
-  checkout, then to `dev`
+- `script/test` — run the Go tests with the race detector and coverage. Go's
-- `script/test` — run the Go tests under a 30-second timeout
+  `-timeout 30s` bounds the tests, not their compile. If they fail, they run
+  again with `-v` for the details, and the script fails. The race detector needs
+  a C compiler
 - `script/lint` — check `.golangci.yml` against its pinned sha256, then run
-  golangci-lint. It runs inside the golangci-lint image of the lint stage of
+  golangci-lint. It runs inside the golangci-lint image of the lint stage of the
-  the root `Dockerfile`; from a checkout, run `make lint` at the repo root,
+  root `Dockerfile`; from a checkout, run `make lint` at the repo root, which
-  which builds that stage
+  builds that stage
 - `script/fmt` — format the Go sources (writes)
 - `script/fmt-check` — check Go formatting (read-only)
 - `script/run` — build and run the server locally
@@ -58,8 +60,9 @@ flushes them to compressed files on disk for later analysis.
 
 ## Design
 
-The server is structured as an `fx`-wired Go application under `cmd/netwatch-server/`.
+The server is structured as an `fx`-wired Go application under
-Internal packages in `internal/` follow standard Go project layout:
+`cmd/netwatch-server/`. Internal packages in `internal/` follow standard Go
+project layout:
 
 - **`config`**: Loads configuration from environment variables and config files
   via Viper.
@@ -85,12 +88,15 @@ Internal packages in `internal/` follow standard Go project layout:
 | `TRUSTED_PROXIES`      | loopback + RFC1918   | Comma-separated CIDRs whose `X-Forwarded-For` / `X-Real-IP` headers are trusted for client IP resolution |
 | `REPORTS_PER_MINUTE`   | `60`                 | Reports each client address may send a minute; see [Report limits](#report-limits)                       |
 | `CORS_ALLOWED_ORIGINS` | empty                | Comma-separated origins whose pages may call the API; see [CORS](#cors)                                  |
+| `METRICS_USERNAME`     | empty                | Basic auth user name for `/metrics`; see [Metrics](#metrics)                                             |
+| `METRICS_PASSWORD`     | empty                | Basic auth password for `/metrics`; see [Metrics](#metrics)                                              |
 
-`TRUSTED_PROXIES` defaults to `127.0.0.1/32,::1/128,10.0.0.0/8,172.16.0.0/12,192.168.0.0/16`.
+`TRUSTED_PROXIES` defaults to
-The loopback entries cover a reverse proxy on the same host. A request whose
+`127.0.0.1/32,::1/128,10.0.0.0/8,172.16.0.0/12,192.168.0.0/16`. The loopback
-direct peer is outside this set has its forwarded headers ignored, and the
+entries cover a reverse proxy on the same host. A request whose direct peer is
-direct peer is logged and rate-limited instead. The container image does not use
+outside this set has its forwarded headers ignored, and the direct peer is
-this default; see [Container image](#container-image).
+logged and rate-limited instead. The container image does not use this default;
+see [Container image](#container-image).
 
 A variable set to a value the server cannot use, such as `PORT=abc`,
 `DEBUG=maybe` or a `BIND_ADDRESS` that is not an IP address, stops it from
@@ -99,15 +105,16 @@ starting, with an error naming the variable. An empty variable counts as unset.
 ### Container image
 
 The root `Dockerfile` builds one image in which nginx listens on the public port
-8080, serves the frontend, and proxies `/api/` and `/.well-known/healthcheck` to
+8080, serves the frontend, and proxies `/api/`, `/.well-known/healthcheck` and
-this server. The image's entrypoint, `bin/entrypoint.sh`, starts the server as
+`/metrics` to this server. The image's entrypoint, `bin/entrypoint.sh`, starts
-user `netwatch` (uid 1000) with `BIND_ADDRESS=127.0.0.1` and `PORT=8081`, so
+the server as user `netwatch` (uid 1000) with `BIND_ADDRESS=127.0.0.1` and
-only nginx reaches it, and with `TRUSTED_PROXIES=127.0.0.1/32`, so it takes the
+`PORT=8081`, so only nginx reaches it, and with `TRUSTED_PROXIES=127.0.0.1/32`,
-client address nginx passes on and no other. `DATA_DIR` is `/data/reports`, on
+so it takes the client address nginx passes on and no other. `DATA_DIR` is
-the `/data` volume; the entrypoint creates it and gives it and `/data` to
+`/data/reports`, on the `/data` volume; before starting the server, the
-`netwatch` before starting the server. nginx replaces the security headers
+entrypoint creates it and gives it and `/data` to `netwatch` with
-this server sets with those in the root `security-headers.conf`, so those are
+`netwatch-server prepare-data-dir`, which acts on nothing outside `/data`. nginx
-what clients of the image see.
+replaces the security headers this server sets with those in the root
+`security-headers.conf`, so those are what clients of the image see.
 
 The container's own `TRUSTED_PROXIES` goes to nginx instead: IP addresses or
 CIDRs, separated by commas, of the reverse proxies in front of the container.
@@ -125,10 +132,11 @@ Reports are written as `reports-<timestamp>-<number>.jsonl.zst` files in
 `DATA_DIR`. The timestamp is in UTC to the millisecond, so the names sort by
 time. The number starts at 1 when the server starts and goes up by one for each
 file the server starts to write, so two files written in the same millisecond
-still get different names. A failed write uses up its number, leaving a gap in
+still get different names. A failed write uses up its number and leaves a gap in
-the numbers if the file could not be created and otherwise a file under that
+the numbers: its file, if it was created, is removed. The file stays, counted
-number that may be incomplete. Each file contains one JSON object per line,
+toward `DATA_DIR_MAX_BYTES` from the next start, only if removing it fails too.
-compressed with zstd. Files are created with `O_EXCL` to prevent overwrites.
+Each file contains one JSON object per line, compressed with zstd. Files are
+created with `O_EXCL` to prevent overwrites.
 
 ### Report limits
 
@@ -157,8 +165,7 @@ credentials, so it is bounded instead. Both refusals below answer with the same
   to be written fill the cap on their own, and then no file is deleted. At
   start, report files past the cap, as after lowering it, are deleted the same
   way. So the cap is how much of the newest reports is kept: the default of 1
-  GiB is small enough for any host; set it to the space you can give
+  GiB is small enough for any host; set it to the space you can give `DATA_DIR`.
-  `DATA_DIR`.
 
 ### CORS
 
@@ -171,6 +178,26 @@ origin, `scheme://host` with an optional `:port`, as browsers send it: no path,
 not even a trailing `/`, and no `*`. Any other entry stops the server from
 starting, with an error naming `CORS_ALLOWED_ORIGINS`.
 
+### Metrics
+
+With both `METRICS_USERNAME` and `METRICS_PASSWORD` set, the server serves
+Prometheus metrics at `GET /metrics` to requests with those as their basic auth
+credentials, and answers any other with 401. For each request that reaches the
+health check or `POST /api/v1/reports`, those the rate limit refuses included,
+the metrics record its duration and response size, labelled with its path,
+method and status; they also count those requests in progress, and include Go's
+runtime and process metrics. No other request is recorded: not those to
+`/metrics` itself, and not those answered before they reach either route, such
+as a CORS preflight, or a request refused with 404 for a path no route has, 405
+for a method its route does not take, or 413 for declaring a body length over
+the 1 MiB limit. A report whose body goes over the limit without declaring its
+length reaches the route, is answered 413 there, and is recorded with that
+status. Clients can make up any number of paths and methods, and each would add
+labels to the metrics for as long as the server runs. With neither set, nothing
+is recorded and `/metrics` answers 404. One without the other stops the server
+from starting, with an error naming both; so does a `METRICS_USERNAME`
+containing `:`, which basic auth cannot carry, with an error naming it.
+
 ## TODO
 
 - Add integration test that POSTs a report and verifies the compressed output

backend/cmd/netwatch-server/main.go

@@ -4,6 +4,7 @@ package main
 import (
 	"fmt"
 	"os"
+	"os/user"
 
 	"sneak.berlin/go/netwatch/internal/config"
 	"sneak.berlin/go/netwatch/internal/globals"
@@ -15,6 +16,7 @@ import (
 	"sneak.berlin/go/netwatch/internal/server"
 
 	"go.uber.org/fx"
+	"go.uber.org/fx/fxevent"
 )
 
 //nolint:gochecknoglobals // set via ldflags at build time
@@ -37,10 +39,36 @@ func main() {
 		return
 	}
 
+	// "netwatch-server prepare-data-dir DATA_DIR" gets DATA_DIR ready
+	// for the netwatch user, or exits 1 with the error; see
+	// reportbuf.PrepareDataDir. bin/entrypoint.sh runs it as root
+	// before it starts this server as that user.
+	if len(os.Args) == 3 && os.Args[1] == "prepare-data-dir" {
+		netwatch, err := user.Lookup("netwatch")
+		if err != nil {
+			fmt.Fprintln(os.Stderr, err)
+			os.Exit(1)
+		}
+
+		err = reportbuf.PrepareDataDir("/data", os.Args[2], netwatch)
+		if err != nil {
+			fmt.Fprintf(os.Stderr, "DATA_DIR '%s': %v\n", os.Args[2], err)
+			os.Exit(1)
+		}
+
+		return
+	}
+
 	globals.Appname = Appname
 	globals.Version = Version
 
 	fx.New(
+		// fx logs each step of starting and stopping through the
+		// server's own logger, so off a terminal those lines are
+		// JSON like every other line.
+		fx.WithLogger(func(log *logger.Logger) fxevent.Logger {
+			return &fxevent.SlogLogger{Logger: log.Get()}
+		}),
 		fx.Provide(
 			config.New,
 			globals.New,
@@ -51,6 +79,11 @@ func main() {
 			reportbuf.New,
 			server.New,
 		),
-		fx.Invoke(func(*server.Server) {}),
+		fx.Invoke(
+			// First, so the name and version are logged even when
+			// a setting stops the start.
+			func(log *logger.Logger) { log.Identify() },
+			func(*server.Server) {},
+		),
 	).Run()
 }

backend/cmd/netwatch-server/main_test.go

@@ -0,0 +1,227 @@
+package main
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"net"
+	"net/http"
+	"os"
+	"os/exec"
+	"os/signal"
+	"path/filepath"
+	"strings"
+	"syscall"
+	"testing"
+	"time"
+)
+
+// The tests run main() in a child process, this test binary started
+// again with runMainEnv set, because main() can exit its process and
+// takes its settings from the environment.
+const runMainEnv = "NETWATCH_SERVER_RUN_MAIN"
+
+// childTimeout bounds each child's whole run; it is killed after it.
+const childTimeout = 10 * time.Second
+
+func TestMain(m *testing.M) {
+	if os.Getenv(runMainEnv) != "" {
+		// A SIGTERM that comes before fx catches it is dropped, not fatal.
+		signal.Notify(make(chan os.Signal, 1), syscall.SIGTERM)
+		main()
+
+		return
+	}
+
+	os.Exit(m.Run())
+}
+
+// TestOutputIsJSON: off a terminal, every line the server writes from
+// start to stop is JSON, fx's own lines included.
+func TestOutputIsJSON(t *testing.T) {
+	t.Parallel()
+
+	ctx, cancel := context.WithTimeout(t.Context(), childTimeout)
+	defer cancel()
+
+	port := freePort(ctx, t)
+	child, stdout, stderr := startServer(ctx, t, t.TempDir(), port)
+
+	waitForHealthcheck(ctx, t, port)
+
+	// The child drops a SIGTERM that comes before fx catches it (see
+	// TestMain), so send one every 100ms until the test ends. ctx
+	// bounds the wait: when it ends, the child is killed.
+	stop := make(chan struct{})
+	defer close(stop)
+
+	go func() {
+		for {
+			_ = child.Process.Signal(syscall.SIGTERM)
+
+			select {
+			case <-stop:
+				return
+			case <-time.After(100 * time.Millisecond):
+			}
+		}
+	}()
+
+	err := child.Wait()
+	if err != nil {
+		t.Fatalf("server exit = %v, want success", err)
+	}
+
+	requireJSONLines(t, stdout, stderr)
+
+	if !strings.Contains(stdout.String(), `"msg":"starting"`) {
+		t.Fatalf("no startup line in stdout:\n%s", stdout)
+	}
+}
+
+// TestMalformedConfigFileStopsTheStart: a config file the server finds
+// but cannot read stops the start, and the error is logged as JSON.
+func TestMalformedConfigFileStopsTheStart(t *testing.T) {
+	t.Parallel()
+
+	ctx, cancel := context.WithTimeout(t.Context(), childTimeout)
+	defer cancel()
+
+	home := t.TempDir()
+	dir := filepath.Join(home, ".config", "netwatch-server")
+
+	err := os.MkdirAll(dir, 0o750)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	err = os.WriteFile(filepath.Join(dir, "netwatch-server.yaml"),
+		[]byte("PORT: [8080\n"), 0o600)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	child, stdout, stderr := startServer(ctx, t, home, freePort(ctx, t))
+
+	err = child.Wait()
+	if child.ProcessState.ExitCode() != 1 {
+		t.Fatalf("server exit = %v, want exit status 1", err)
+	}
+
+	requireJSONLines(t, stdout, stderr)
+
+	if !strings.Contains(stdout.String(), "netwatch-server.yaml") {
+		t.Fatalf("no error naming the config file in stdout:\n%s", stdout)
+	}
+}
+
+// startServer runs main() in a child process listening on
+// 127.0.0.1:port, with home as its HOME and working directory and its
+// data directory in home, so it touches nothing outside home. Its
+// stdout and stderr go to the two buffers returned, which hold all of
+// it once child.Wait returns. The child is killed when ctx ends, and
+// killed and reaped when the test ends if nothing waited for it.
+func startServer(
+	ctx context.Context,
+	t *testing.T,
+	home, port string,
+) (*exec.Cmd, *bytes.Buffer, *bytes.Buffer) {
+	t.Helper()
+
+	self, err := os.Executable()
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	var stdout, stderr bytes.Buffer
+
+	child := exec.CommandContext(ctx, self) //nolint:gosec // this test binary
+	child.Dir = home
+	child.Env = append(os.Environ(),
+		runMainEnv+"=1",
+		"HOME="+home,
+		"DATA_DIR="+filepath.Join(home, "data"),
+		"BIND_ADDRESS=127.0.0.1",
+		"PORT="+port,
+	)
+	child.Stdout = &stdout
+	child.Stderr = &stderr
+
+	err = child.Start()
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	t.Cleanup(func() {
+		if child.ProcessState == nil {
+			_ = child.Process.Kill()
+			_ = child.Wait()
+		}
+	})
+
+	return child, &stdout, &stderr
+}
+
+// freePort returns a TCP port on 127.0.0.1 that was free a moment ago.
+func freePort(ctx context.Context, t *testing.T) string {
+	t.Helper()
+
+	var lc net.ListenConfig
+
+	l, err := lc.Listen(ctx, "tcp", "127.0.0.1:0")
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	_ = l.Close()
+
+	_, port, err := net.SplitHostPort(l.Addr().String())
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	return port
+}
+
+// waitForHealthcheck returns once the health check on port answers 200.
+func waitForHealthcheck(ctx context.Context, t *testing.T, port string) {
+	t.Helper()
+
+	url := "http://127.0.0.1:" + port + "/.well-known/healthcheck"
+
+	for {
+		req, err := http.NewRequestWithContext(ctx, http.MethodGet, url, nil)
+		if err != nil {
+			t.Fatal(err)
+		}
+
+		resp, err := http.DefaultClient.Do(req)
+		if err == nil {
+			_ = resp.Body.Close()
+
+			if resp.StatusCode == http.StatusOK {
+				return
+			}
+		}
+
+		select {
+		case <-ctx.Done():
+			t.Fatalf("health check never answered: %v", err)
+		case <-time.After(50 * time.Millisecond):
+		}
+	}
+}
+
+// requireJSONLines fails the test on each line of outs that is not
+// JSON.
+func requireJSONLines(t *testing.T, outs ...*bytes.Buffer) {
+	t.Helper()
+
+	for _, out := range outs {
+		for line := range strings.Lines(out.String()) {
+			if !json.Valid([]byte(line)) {
+				t.Errorf("line is not JSON: %s", line)
+			}
+		}
+	}
+}

backend/go.mod

@@ -3,20 +3,29 @@ module sneak.berlin/go/netwatch
 go 1.25.5
 
 require (
+	github.com/99designs/basicauth-go v0.0.0-20230316000542-bf6f9cbbf0f8
 	github.com/go-chi/chi/v5 v5.2.5
 	github.com/go-chi/cors v1.2.2
 	github.com/go-chi/httprate v0.16.0
 	github.com/joho/godotenv v1.5.1
-	github.com/klauspost/compress v1.18.4
+	github.com/klauspost/compress v1.19.1
+	github.com/prometheus/client_golang v1.24.1
+	github.com/slok/go-http-metrics v0.13.0
 	github.com/spf13/viper v1.21.0
 	go.uber.org/fx v1.24.0
 )
 
 require (
+	github.com/beorn7/perks v1.0.1 // indirect
+	github.com/cespare/xxhash/v2 v2.3.0 // indirect
 	github.com/fsnotify/fsnotify v1.9.0 // indirect
 	github.com/go-viper/mapstructure/v2 v2.4.0 // indirect
 	github.com/klauspost/cpuid/v2 v2.2.10 // indirect
+	github.com/munnerz/goautoneg v0.0.0-20191010083416-a7dc8b61c822 // indirect
 	github.com/pelletier/go-toml/v2 v2.2.4 // indirect
+	github.com/prometheus/client_model v0.6.2 // indirect
+	github.com/prometheus/common v0.70.1 // indirect
+	github.com/prometheus/procfs v0.21.1 // indirect
 	github.com/sagikazarmark/locafero v0.11.0 // indirect
 	github.com/sourcegraph/conc v0.3.1-0.20240121214520-5f936abd7ae8 // indirect
 	github.com/spf13/afero v1.15.0 // indirect
@@ -28,6 +37,7 @@ require (
 	go.uber.org/multierr v1.10.0 // indirect
 	go.uber.org/zap v1.26.0 // indirect
 	go.yaml.in/yaml/v3 v3.0.4 // indirect
-	golang.org/x/sys v0.30.0 // indirect
+	golang.org/x/sys v0.47.0 // indirect
-	golang.org/x/text v0.28.0 // indirect
+	golang.org/x/text v0.40.0 // indirect
+	google.golang.org/protobuf v1.36.11 // indirect
 )

backend/go.sum

@@ -1,3 +1,9 @@
+github.com/99designs/basicauth-go v0.0.0-20230316000542-bf6f9cbbf0f8 h1:nMpu1t4amK3vJWBibQ5X/Nv0aXL+b69TQf2uK5PH7Go=
+github.com/99designs/basicauth-go v0.0.0-20230316000542-bf6f9cbbf0f8/go.mod h1:3cARGAK9CfW3HoxCy1a0G4TKrdiKke8ftOMEOHyySYs=
+github.com/beorn7/perks v1.0.1 h1:VlbKKnNfV8bJzeqoa4cOKqO6bYr3WgKZxO8Z16+hsOM=
+github.com/beorn7/perks v1.0.1/go.mod h1:G2ZrVWU2WbWT9wwq4/hrbKbnv/1ERSJQ0ibhJ6rlkpw=
+github.com/cespare/xxhash/v2 v2.3.0 h1:UL815xU9SqsFlibzuggzjXhog7bL6oX9BbNZnL2UFvs=
+github.com/cespare/xxhash/v2 v2.3.0/go.mod h1:VGX0DQ3Q6kWi7AoAeZDth3/j3BFtOZR5XLFGgcrjCOs=
 github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
 github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
 github.com/frankban/quicktest v1.14.6 h1:7Xjx+VpznH+oBnejlPUj8oUpdxnVs4f8XU8WnHkI4W8=
@@ -12,26 +18,40 @@ github.com/go-chi/httprate v0.16.0 h1:8V5DH9j6pSK6UQoBsTpvMyFxycqaKEIToyPKzHJjUa
 github.com/go-chi/httprate v0.16.0/go.mod h1:A8lo+qRhk+s9LiuP5saS7XCGDXRXMcrueq0NfIuCa/I=
 github.com/go-viper/mapstructure/v2 v2.4.0 h1:EBsztssimR/CONLSZZ04E8qAkxNYq4Qp9LvH92wZUgs=
 github.com/go-viper/mapstructure/v2 v2.4.0/go.mod h1:oJDH3BJKyqBA2TXFhDsKDGDTlndYOZ6rGS0BRZIxGhM=
-github.com/google/go-cmp v0.6.0 h1:ofyhxvXcZhMsU5ulbFiLKl/XBFqE1GSq7atu8tAmTRI=
+github.com/google/go-cmp v0.7.0 h1:wk8382ETsv4JYUZwIsn6YpYiWiBsYLSJiTsyBybVuN8=
-github.com/google/go-cmp v0.6.0/go.mod h1:17dUlkBOakJ0+DkrSSNjCkIjxS6bF9zb3elmeNGIjoY=
+github.com/google/go-cmp v0.7.0/go.mod h1:pXiqmnSA92OHEEa9HXL2W4E7lf9JzCmGVUdgjX3N/iU=
 github.com/joho/godotenv v1.5.1 h1:7eLL/+HRGLY0ldzfGMeQkb7vMd0as4CfYvUVzLqw0N0=
 github.com/joho/godotenv v1.5.1/go.mod h1:f4LDr5Voq0i2e/R5DDNOoa2zzDfwtkZa6DnEwAbqwq4=
-github.com/klauspost/compress v1.18.4 h1:RPhnKRAQ4Fh8zU2FY/6ZFDwTVTxgJ/EMydqSTzE9a2c=
+github.com/klauspost/compress v1.19.1 h1:VsB4HPswih7mmZ8WleSFQ75c/Ui1M4trX5oAsJnhSlk=
-github.com/klauspost/compress v1.18.4/go.mod h1:R0h/fSBs8DE4ENlcrlib3PsXS61voFxhIs2DeRhCvJ4=
+github.com/klauspost/compress v1.19.1/go.mod h1:cwPg85FWrGar70rWktvGQj8/hthj3wpl0PGDogxkrSQ=
 github.com/klauspost/cpuid/v2 v2.2.10 h1:tBs3QSyvjDyFTq3uoc/9xFpCuOsJQFNPiAhYdw2skhE=
 github.com/klauspost/cpuid/v2 v2.2.10/go.mod h1:hqwkgyIinND0mEev00jJYCxPNVRVXFQeu1XKlok6oO0=
 github.com/kr/pretty v0.3.1 h1:flRD4NNwYAUpkphVc1HcthR4KEIFJ65n8Mw5qdRn3LE=
 github.com/kr/pretty v0.3.1/go.mod h1:hoEshYVHaxMs3cyo3Yncou5ZscifuDolrwPKZanG3xk=
 github.com/kr/text v0.2.0 h1:5Nx0Ya0ZqY2ygV366QzturHI13Jq95ApcVaJBhpS+AY=
 github.com/kr/text v0.2.0/go.mod h1:eLer722TekiGuMkidMxC/pM04lWEeraHUUmBw8l2grE=
+github.com/kylelemons/godebug v1.1.0 h1:RPNrshWIDI6G2gRW9EHilWtl7Z6Sb1BR0xunSBf0SNc=
+github.com/kylelemons/godebug v1.1.0/go.mod h1:9/0rRGxNHcop5bhtWyNeEfOS8JIWk580+fNqagV/RAw=
+github.com/munnerz/goautoneg v0.0.0-20191010083416-a7dc8b61c822 h1:C3w9PqII01/Oq1c1nUAm88MOHcQC9l5mIlSMApZMrHA=
+github.com/munnerz/goautoneg v0.0.0-20191010083416-a7dc8b61c822/go.mod h1:+n7T8mK8HuQTcFwEeznm/DIxMOiR9yIdICNftLE1DvQ=
 github.com/pelletier/go-toml/v2 v2.2.4 h1:mye9XuhQ6gvn5h28+VilKrrPoQVanw5PMw/TB0t5Ec4=
 github.com/pelletier/go-toml/v2 v2.2.4/go.mod h1:2gIqNv+qfxSVS7cM2xJQKtLSTLUE9V8t9Stt+h56mCY=
 github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
 github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
+github.com/prometheus/client_golang v1.24.1 h1:JnJkREXzWxUdCuPFpIWZiPispT9xVV59uiuyR2bPlnU=
+github.com/prometheus/client_golang v1.24.1/go.mod h1:F+oSRECHg4sse5ucfYpYDeIv/hu68Zo0uoHKetWnzcE=
+github.com/prometheus/client_model v0.6.2 h1:oBsgwpGs7iVziMvrGhE53c/GrLUsZdHnqNwqPLxwZyk=
+github.com/prometheus/client_model v0.6.2/go.mod h1:y3m2F6Gdpfy6Ut/GBsUqTWZqCUvMVzSfMLjcu6wAwpE=
+github.com/prometheus/common v0.70.1 h1:1HvjP4D5oL3t8RsPlwxA9onvvStjtIHYE5XuuwOi/PY=
+github.com/prometheus/common v0.70.1/go.mod h1:VdFUQDMZK3VLkurFUVhia6uys/0suUp86TJz5qbJRhc=
+github.com/prometheus/procfs v0.21.1 h1:GljZCt+zSTS+NZq88cyQ1LjZ+RCHp3uVuabBWA5+OJI=
+github.com/prometheus/procfs v0.21.1/go.mod h1:aB55Cww9pdSJVHk0hUf0inxWyyjPogFIjmHKYgMKmtY=
 github.com/rogpeppe/go-internal v1.9.0 h1:73kH8U+JUqXU8lRuOHeVHaa/SZPifC7BkcraZVejAe8=
 github.com/rogpeppe/go-internal v1.9.0/go.mod h1:WtVeX8xhTBvf0smdhujwtBcq4Qrzq/fJaraNFVN+nFs=
 github.com/sagikazarmark/locafero v0.11.0 h1:1iurJgmM9G3PA/I+wWYIOw/5SyBtxapeHDcg+AAIFXc=
 github.com/sagikazarmark/locafero v0.11.0/go.mod h1:nVIGvgyzw595SUSUE6tvCp3YYTeHs15MvlmU87WwIik=
+github.com/slok/go-http-metrics v0.13.0 h1:lQDyJJx9wKhmbliyUsZ2l6peGnXRHjsjoqPt5VYzcP8=
+github.com/slok/go-http-metrics v0.13.0/go.mod h1:HIr7t/HbN2sJaunvnt9wKP9xoBBVZFo1/KiHU3b0w+4=
 github.com/sourcegraph/conc v0.3.1-0.20240121214520-5f936abd7ae8 h1:+jumHNA0Wrelhe64i8F6HNlS8pkoyMv5sreGx2Ry5Rw=
 github.com/sourcegraph/conc v0.3.1-0.20240121214520-5f936abd7ae8/go.mod h1:3n1Cwaq1E1/1lhQhtRK2ts/ZwZEhjcQeJQ1RuC6Q/8U=
 github.com/spf13/afero v1.15.0 h1:b/YBCLWAJdFWJTN9cLhiXXcD7mzKn9Dm86dNnfyQw1I=
@@ -42,6 +62,8 @@ github.com/spf13/pflag v1.0.10 h1:4EBh2KAYBwaONj6b2Ye1GiHfwjqyROoF4RwYO+vPwFk=
 github.com/spf13/pflag v1.0.10/go.mod h1:McXfInJRrz4CZXVZOBLb0bTZqETkiAhM9Iw0y3An2Bg=
 github.com/spf13/viper v1.21.0 h1:x5S+0EU27Lbphp4UKm1C+1oQO+rKx36vfCoaVebLFSU=
 github.com/spf13/viper v1.21.0/go.mod h1:P0lhsswPGWD/1lZJ9ny3fYnVqxiegrlNrEmgLjbTCAY=
+github.com/stretchr/objx v0.5.2 h1:xuMeJ0Sdp5ZMRXx/aWO6RZxdr3beISkG5/G/aIRr3pY=
+github.com/stretchr/objx v0.5.2/go.mod h1:FRsXN1f5AsAjCGJKqEizvkpNtU+EGNCLh3NxZ/8L+MA=
 github.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu7U=
 github.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U=
 github.com/subosito/gotenv v1.6.0 h1:9NlTDc1FTs4qu0DDq7AEtTPNw6SVm7uBMsUCUjABIf8=
@@ -54,18 +76,22 @@ go.uber.org/dig v1.19.0 h1:BACLhebsYdpQ7IROQ1AGPjrXcP5dF80U3gKoFzbaq/4=
 go.uber.org/dig v1.19.0/go.mod h1:Us0rSJiThwCv2GteUN0Q7OKvU7n5J4dxZ9JKUXozFdE=
 go.uber.org/fx v1.24.0 h1:wE8mruvpg2kiiL1Vqd0CC+tr0/24XIB10Iwp2lLWzkg=
 go.uber.org/fx v1.24.0/go.mod h1:AmDeGyS+ZARGKM4tlH4FY2Jr63VjbEDJHtqXTGP5hbo=
-go.uber.org/goleak v1.2.0 h1:xqgm/S+aQvhWFTtR0XK3Jvg7z8kGV8P4X14IzwN3Eqk=
+go.uber.org/goleak v1.3.0 h1:2K3zAYmnTNqV73imy9J1T3WC+gmCePx2hEGkimedGto=
-go.uber.org/goleak v1.2.0/go.mod h1:XJYK+MuIchqpmGmUSAzotztawfKvYLUIgg7guXrwVUo=
+go.uber.org/goleak v1.3.0/go.mod h1:CoHD4mav9JJNrW/WLlf7HGZPjdw8EucARQHekz1X6bE=
 go.uber.org/multierr v1.10.0 h1:S0h4aNzvfcFsC3dRF1jLoaov7oRaKqRGC/pUEJ2yvPQ=
 go.uber.org/multierr v1.10.0/go.mod h1:20+QtiLqy0Nd6FdQB9TLXag12DsQkrbs3htMFfDN80Y=
 go.uber.org/zap v1.26.0 h1:sI7k6L95XOKS281NhVKOFCUNIvv9e0w4BF8N3u+tCRo=
 go.uber.org/zap v1.26.0/go.mod h1:dtElttAiwGvoJ/vj4IwHBS/gXsEu/pZ50mUIRWuG0so=
+go.yaml.in/yaml/v2 v2.4.4 h1:tuyd0P+2Ont/d6e2rl3be67goVK4R6deVxCUX5vyPaQ=
+go.yaml.in/yaml/v2 v2.4.4/go.mod h1:gMZqIpDtDqOfM0uNfy0SkpRhvUryYH0Z6wdMYcacYXQ=
 go.yaml.in/yaml/v3 v3.0.4 h1:tfq32ie2Jv2UxXFdLJdh3jXuOzWiL1fo0bu/FbuKpbc=
 go.yaml.in/yaml/v3 v3.0.4/go.mod h1:DhzuOOF2ATzADvBadXxruRBLzYTpT36CKvDb3+aBEFg=
-golang.org/x/sys v0.30.0 h1:QjkSwP/36a20jFYWkSue1YwXzLmsV5Gfq7Eiy72C1uc=
+golang.org/x/sys v0.47.0 h1:o7XGOvZQCADBQQ4Y7VNq2dRWQR7JmOUW8Kxx4ZsNgWs=
-golang.org/x/sys v0.30.0/go.mod h1:/VUhepiaJMQUp4+oa/7Zr1D23ma6VTLIYjOOTFZPUcA=
+golang.org/x/sys v0.47.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw=
-golang.org/x/text v0.28.0 h1:rhazDwis8INMIwQ4tpjLDzUhx6RlXqZNPEM0huQojng=
+golang.org/x/text v0.40.0 h1:Ub2Z6/xjgF1WrYQz2nuITOEegKFtiIy+rieRJ5lHZKs=
-golang.org/x/text v0.28.0/go.mod h1:U8nCwOR8jO/marOQ0QbDiOngZVEBB7MAiitBuMjXiNU=
+golang.org/x/text v0.40.0/go.mod h1:hpnzDAfGV753zIKo+wk3u1bVKCGPbrnF7+7LBF/UHVY=
+google.golang.org/protobuf v1.36.11 h1:fV6ZwhNocDyBLK0dj+fg8ektcVegBBuEolpbTQyBNVE=
+google.golang.org/protobuf v1.36.11/go.mod h1:HTf+CrKn2C3g5S8VImy6tdcUvCska2kB7j23XfzDpco=
 gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
 gopkg.in/check.v1 v1.0.0-20190902080502-41f04d3bba15 h1:YR8cESwS4TdDjEe65xsg0ogRM/Nc3DYOhEAlW+xobZo=
 gopkg.in/check.v1 v1.0.0-20190902080502-41f04d3bba15/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=

backend/internal/config/config.go

@@ -44,6 +44,15 @@ var (
 	errNotPort = errors.New("must be a port number, 1 to 65535")
 	errNotBool = errors.New("must be true or false")
 	errNotIP   = errors.New("must be an IP address, or empty")
+
+	errMetricsCredentials = errors.New(
+		"METRICS_USERNAME and METRICS_PASSWORD must be set together, " +
+			"or neither",
+	)
+	errMetricsUsernameColon = errors.New(
+		"METRICS_USERNAME must not contain \":\", " +
+			"which basic auth cannot carry in a user name",
+	)
 )
 
 // Params defines the dependencies for Config.
@@ -73,7 +82,8 @@ type Config struct {
 
 // New loads configuration from env, .env files, and config
 // files, returning a fully resolved Config. It fails, with an error
-// naming the setting, on a value the server cannot use.
+// naming the setting, on a value the server cannot use, and on a
+// config file it finds but cannot read.
 func New(
 	_ fx.Lifecycle,
 	params Params,
@@ -106,8 +116,8 @@ func New(
 	if err != nil {
 		var notFound viper.ConfigFileNotFoundError
 		if !errors.As(err, &notFound) {
-			log.Error("config file malformed", "error", err)
+			return nil, fmt.Errorf("config file %s: %w",
-			panic(err)
+				viper.ConfigFileUsed(), err)
 		}
 	}
 
@@ -177,6 +187,18 @@ func (s *Config) check() error {
 		}
 	}
 
+	// The server records and serves metrics only with both set, so
+	// one alone is a mistake that would otherwise go unnoticed.
+	if (s.MetricsUsername == "") != (s.MetricsPassword == "") {
+		return errMetricsCredentials
+	}
+
+	// Basic auth splits the credentials at the first ":", so with one
+	// in the user name every request to /metrics would get 401.
+	if strings.Contains(s.MetricsUsername, ":") {
+		return errMetricsUsernameColon
+	}
+
 	return checkOrigins(s.CORSAllowedOrigins)
 }
 

backend/internal/config/config_test.go

@@ -103,6 +103,32 @@ func TestDataDirMaxBytesMustBeANumber(t *testing.T) {
 	requireConfigError(t, "DATA_DIR_MAX_BYTES")
 }
 
+// TestMetricsCredentialsGoTogether: with only one of the two set, the
+// server would quietly serve no metrics, so the start fails, naming
+// both.
+func TestMetricsCredentialsGoTogether(t *testing.T) {
+	for _, set := range []string{"METRICS_USERNAME", "METRICS_PASSWORD"} {
+		t.Run(set, func(t *testing.T) {
+			t.Setenv("METRICS_USERNAME", "")
+			t.Setenv("METRICS_PASSWORD", "")
+			t.Setenv(set, "prometheus")
+
+			requireConfigError(t, "METRICS_USERNAME")
+			requireConfigError(t, "METRICS_PASSWORD")
+		})
+	}
+}
+
+// TestMetricsUsernameMustNotContainColon: basic auth splits the
+// credentials at the first ":", so such a user name would get 401 on
+// every request to /metrics.
+func TestMetricsUsernameMustNotContainColon(t *testing.T) {
+	t.Setenv("METRICS_USERNAME", "prom:etheus")
+	t.Setenv("METRICS_PASSWORD", "secret")
+
+	requireConfigError(t, "METRICS_USERNAME")
+}
+
 // TestCORSAllowedOriginsMustBeOrigins: "*" would let every origin in,
 // and an entry that is not a plain origin would match no page.
 func TestCORSAllowedOriginsMustBeOrigins(t *testing.T) {

backend/internal/handlers/handlers_test.go

@@ -1,13 +0,0 @@
-package handlers_test
-
-import (
-	"testing"
-
-	_ "sneak.berlin/go/netwatch/internal/handlers"
-)
-
-func TestImport(t *testing.T) {
-	t.Parallel()
-	// Compilation check — verifies the package parses
-	// and all imports resolve.
-}

backend/internal/handlers/healthcheck.go

@@ -6,6 +6,6 @@ import "net/http"
 // endpoint.
 func (s *Handlers) HandleHealthCheck() http.HandlerFunc {
 	return func(w http.ResponseWriter, r *http.Request) {
-		s.respondJSON(w, r, s.hc.Check(), http.StatusOK)
+		s.respondJSON(w, r, s.hc.Healthcheck(), http.StatusOK)
 	}
 }

backend/internal/handlers/healthcheck_test.go

@@ -0,0 +1,120 @@
+package handlers_test
+
+import (
+	"encoding/json"
+	"maps"
+	"net/http"
+	"net/http/httptest"
+	"slices"
+	"testing"
+	"time"
+
+	"sneak.berlin/go/netwatch/internal/globals"
+	"sneak.berlin/go/netwatch/internal/handlers"
+	"sneak.berlin/go/netwatch/internal/healthcheck"
+	"sneak.berlin/go/netwatch/internal/logger"
+
+	"go.uber.org/fx/fxtest"
+)
+
+// newStartedHandlers builds Handlers with a real health check for the
+// server named in g, and starts them, which records the time the
+// uptime counts from.
+func newStartedHandlers(t *testing.T, g *globals.Globals) *handlers.Handlers {
+	t.Helper()
+
+	lc := fxtest.NewLifecycle(t)
+
+	log, err := logger.New(lc, logger.Params{Globals: g})
+	if err != nil {
+		t.Fatalf("logger: %v", err)
+	}
+
+	hc, err := healthcheck.New(lc,
+		healthcheck.Params{Globals: g, Logger: log})
+	if err != nil {
+		t.Fatalf("health check: %v", err)
+	}
+
+	h, err := handlers.New(lc,
+		handlers.Params{Globals: g, Healthcheck: hc, Logger: log})
+	if err != nil {
+		t.Fatalf("handlers: %v", err)
+	}
+
+	lc.RequireStart()
+	t.Cleanup(lc.RequireStop)
+
+	return h
+}
+
+// TestHandleHealthCheck checks the health check's answer: 200, a JSON
+// content type, and a JSON object with exactly the fields of
+// healthcheck.HealthcheckResponse, carrying this server's name and
+// version and an uptime counted from its start.
+func TestHandleHealthCheck(t *testing.T) {
+	t.Parallel()
+
+	g := &globals.Globals{Appname: "netwatch-server", Version: "v1.2.3"}
+	h := newStartedHandlers(t, g)
+
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequestWithContext(t.Context(),
+		http.MethodGet, "/.well-known/healthcheck", http.NoBody)
+
+	h.HandleHealthCheck().ServeHTTP(rec, req)
+
+	if rec.Code != http.StatusOK {
+		t.Fatalf("status = %d, want %d", rec.Code, http.StatusOK)
+	}
+
+	contentType := rec.Header().Get("Content-Type")
+	if contentType != "application/json; charset=utf-8" {
+		t.Errorf("Content-Type = %q, want %q",
+			contentType, "application/json; charset=utf-8")
+	}
+
+	var body map[string]any
+
+	err := json.Unmarshal(rec.Body.Bytes(), &body)
+	if err != nil {
+		t.Fatalf("body not a JSON object: %v (%q)", err, rec.Body.String())
+	}
+
+	fields := []string{
+		"appname", "now", "status", "uptime_human", "uptime_seconds", "version",
+	}
+	if got := slices.Sorted(maps.Keys(body)); !slices.Equal(got, fields) {
+		t.Fatalf("fields = %v, want %v", got, fields)
+	}
+
+	for field, want := range map[string]string{
+		"appname": g.Appname, "status": "ok", "version": g.Version,
+	} {
+		if body[field] != want {
+			t.Errorf("%s = %v, want %q", field, body[field], want)
+		}
+	}
+
+	now, _ := body["now"].(string)
+
+	at, err := time.Parse(time.RFC3339Nano, now)
+	if err != nil || time.Since(at).Abs() > time.Minute {
+		t.Errorf("now = %q, want the current time in RFC 3339 (%v)", now, err)
+	}
+
+	// Started just now, so the uptime is well under a minute.
+	human, _ := body["uptime_human"].(string)
+
+	uptime, err := time.ParseDuration(human)
+	if err != nil || uptime > time.Minute {
+		t.Errorf("uptime_human = %q, want a duration under a minute (%v)",
+			human, err)
+	}
+
+	seconds, ok := body["uptime_seconds"].(float64)
+	if !ok || seconds < 0 || seconds > time.Minute.Seconds() {
+		t.Errorf("uptime_seconds = %v, want a number of seconds under a minute",
+			body["uptime_seconds"])
+	}
+}

backend/internal/handlers/report_test.go

@@ -46,6 +46,63 @@ func decodeStatus(t *testing.T, body []byte) string {
 	return resp.Status
 }
 
+// TestHandleReportAcceptsValidReports checks the answer to a valid
+// report, one with no hosts and one shaped as the frontend sends them:
+// 200 and {"status":"ok"} as JSON.
+func TestHandleReportAcceptsValidReports(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name string
+		body string
+	}{
+		{
+			name: "no hosts",
+			body: `{"clientId":"c1","geo":null,"hosts":[],` +
+				`"timestamp":"2026-10-03T12:00:00.000Z"}`,
+		},
+		{
+			name: "a host with a latency and an error sample",
+			body: `{"clientId":"c1","geo":null,"hosts":[{` +
+				`"name":"Example","url":"https://example.com/",` +
+				`"status":"error","history":[` +
+				`{"t":1790000000000,"latency":42,"error":null},` +
+				`{"t":1790000003000,"latency":null,"error":"timeout"}]}],` +
+				`"timestamp":"2026-10-03T12:00:00.000Z"}`,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			h := newTestHandlers(stubAppender{}, io.Discard)
+
+			rec := httptest.NewRecorder()
+			req := httptest.NewRequestWithContext(t.Context(),
+				http.MethodPost, "/api/v1/reports",
+				strings.NewReader(tt.body),
+			)
+
+			h.HandleReport().ServeHTTP(rec, req)
+
+			if rec.Code != http.StatusOK {
+				t.Fatalf("status = %d, want %d", rec.Code, http.StatusOK)
+			}
+
+			contentType := rec.Header().Get("Content-Type")
+			if contentType != "application/json; charset=utf-8" {
+				t.Errorf("Content-Type = %q, want %q",
+					contentType, "application/json; charset=utf-8")
+			}
+
+			if got := rec.Body.String(); got != "{\"status\":\"ok\"}\n" {
+				t.Errorf("body = %q, want %q", got, "{\"status\":\"ok\"}\n")
+			}
+		})
+	}
+}
+
 func TestHandleReportStorageFailureIsNon2xx(t *testing.T) {
 	t.Parallel()
 

backend/internal/healthcheck/healthcheck.go

@@ -30,14 +30,17 @@ type Healthcheck struct {
 	params      *Params
 }
 
-// Response is the JSON payload returned by the health check
+// HealthcheckResponse is the JSON payload returned by the health
-// endpoint.
+// check endpoint. Its name and its snake_case keys are the ones
-type Response struct {
+// GO_HTTP_SERVER_CONVENTIONS.md gives.
+//
+//nolint:revive,tagliatelle // name and keys from the conventions
+type HealthcheckResponse struct {
 	Appname       string `json:"appname"`
 	Now           string `json:"now"`
 	Status        string `json:"status"`
-	UptimeHuman   string `json:"uptimeHuman"`
+	UptimeHuman   string `json:"uptime_human"`
-	UptimeSeconds int64  `json:"uptimeSeconds"`
+	UptimeSeconds int64  `json:"uptime_seconds"`
 	Version       string `json:"version"`
 }
 
@@ -65,9 +68,9 @@ func New(
 	return s, nil
 }
 
-// Check returns the current health status of the application.
+// Healthcheck returns the current health status of the application.
-func (s *Healthcheck) Check() *Response {
+func (s *Healthcheck) Healthcheck() *HealthcheckResponse {
-	return &Response{
+	return &HealthcheckResponse{
 		Appname:       s.params.Globals.Appname,
 		Now:           time.Now().UTC().Format(time.RFC3339Nano),
 		Status:        "ok",

backend/internal/middleware/middleware.go

@@ -18,9 +18,14 @@ import (
 	"sneak.berlin/go/netwatch/internal/globals"
 	"sneak.berlin/go/netwatch/internal/logger"
 
+	basicauth "github.com/99designs/basicauth-go"
 	"github.com/go-chi/chi/v5/middleware"
 	"github.com/go-chi/cors"
 	"github.com/go-chi/httprate"
+	"github.com/prometheus/client_golang/prometheus"
+	metrics "github.com/slok/go-http-metrics/metrics/prometheus"
+	ghmm "github.com/slok/go-http-metrics/middleware"
+	"github.com/slok/go-http-metrics/middleware/std"
 	"go.uber.org/fx"
 )
 
@@ -364,3 +369,25 @@ func (s *Middleware) RateLimit(
 		),
 	)
 }
+
+// Metrics returns middleware that records each request's duration and
+// response size, and the requests in progress, in registry. They are
+// labelled by the request path.
+func (s *Middleware) Metrics(
+	registry prometheus.Registerer,
+) func(http.Handler) http.Handler {
+	mdlw := ghmm.New(ghmm.Config{
+		Recorder: metrics.NewRecorder(metrics.Config{Registry: registry}),
+	})
+
+	return std.HandlerProvider("", mdlw)
+}
+
+// MetricsAuth returns middleware that lets a request through only with
+// METRICS_USERNAME and METRICS_PASSWORD as its basic auth credentials,
+// and answers any other with 401.
+func (s *Middleware) MetricsAuth() func(http.Handler) http.Handler {
+	return basicauth.New("metrics", map[string][]string{
+		s.params.Config.MetricsUsername: {s.params.Config.MetricsPassword},
+	})
+}

backend/internal/reportbuf/datadir.go

@@ -0,0 +1,150 @@
+package reportbuf
+
+import (
+	"errors"
+	"io/fs"
+	"os"
+	"os/user"
+	"path/filepath"
+	"strconv"
+	"syscall"
+)
+
+// ErrDataDirOutsideVolume is returned by PrepareDataDir for a DATA_DIR
+// that is not the volume or a path below it, written in full.
+var ErrDataDirOutsideVolume = errors.New(
+	"must be /data or a path below it, with no '.', '..' or extra '/'")
+
+// PrepareDataDir gets dir, the server's DATA_DIR, ready for owner, the
+// user the server runs as, so that a host directory mounted at volume,
+// /data in the image, needs no preparing: it creates dir, gives volume
+// and everything in it to owner, and gives volume and dir the mode the
+// server gives a directory it creates. dir must be volume or a path
+// below it, with no '.', '..', empty part or '/' at the end.
+//
+// bin/entrypoint.sh runs this as root, which would follow a symbolic
+// link anywhere, so every step goes through an os.Root opened on
+// volume: it follows a link only when it is written as a relative
+// path that stays inside volume, and refuses any other. A process on
+// the host can swap a link onto a path in volume at any moment while
+// this runs. Even then, the os.Root checks each link as it reaches
+// it. MkdirAll creates each directory inside a parent it already has
+// open, never following a link at the name it creates, and follows a
+// link on the path only as the os.Root allows, so a relative link
+// inside volume can lead it to create directories elsewhere inside
+// volume. Lchown never changes what a link points to, and the modes
+// are set on directories already opened (see chmodDir), so the most
+// that process can do is make a step fail or wait, or act on
+// something else inside volume.
+func PrepareDataDir(volume, dir string, owner *user.User) error {
+	// rel is dir as a path from volume; IsLocal is false for one that
+	// leads out of it.
+	rel, err := filepath.Rel(volume, dir)
+	if err != nil || dir != filepath.Clean(dir) || !filepath.IsLocal(rel) {
+		return ErrDataDirOutsideVolume
+	}
+
+	uid, err := strconv.Atoi(owner.Uid)
+	if err != nil {
+		return err
+	}
+
+	gid, err := strconv.Atoi(owner.Gid)
+	if err != nil {
+		return err
+	}
+
+	root, err := os.OpenRoot(volume)
+	if err != nil {
+		return err
+	}
+
+	defer func() { _ = root.Close() }()
+
+	err = root.MkdirAll(rel, dirPerms)
+	if err != nil {
+		return err
+	}
+
+	err = lchownAll(root, ".", uid, gid)
+	if err != nil {
+		return err
+	}
+
+	err = chmodDir(root, ".")
+	if err != nil {
+		return err
+	}
+
+	return chmodDir(root, rel)
+}
+
+// lchownAll gives name, a directory inside root, and everything in it
+// to uid and gid. It reads each directory opened through root, not
+// through root.FS(), which refuses a name that is not valid UTF-8, and
+// calls Lchown on every entry, which gives a symbolic link itself to
+// them, not what it points to. It goes into an entry only when the
+// read found a directory there, so it follows no link it finds; one
+// swapped in for that directory afterwards is followed only as the
+// os.Root allows.
+func lchownAll(root *os.Root, name string, uid, gid int) error {
+	err := root.Lchown(name, uid, gid)
+	if err != nil {
+		return err
+	}
+
+	dir, err := root.Open(name)
+	if err != nil {
+		return err
+	}
+
+	entries, err := dir.ReadDir(-1)
+	_ = dir.Close()
+
+	if err != nil {
+		return err
+	}
+
+	for _, entry := range entries {
+		entryName := filepath.Join(name, entry.Name())
+		if entry.IsDir() {
+			err = lchownAll(root, entryName, uid, gid)
+		} else {
+			err = root.Lchown(entryName, uid, gid)
+		}
+
+		if err != nil {
+			return err
+		}
+	}
+
+	return nil
+}
+
+// chmodDir gives name, a directory inside root, the mode the server
+// gives a directory it creates. Root.Chmod would not hold: on Linux it
+// checks that name is not a symbolic link, then sets the mode by name,
+// following a link swapped in between. So chmodDir opens name through
+// root and sets the mode on the open directory. It refuses anything
+// but a directory: a directory has no second name (hard link), so the
+// one opened is inside root, where any other file could be a hard link
+// to one outside.
+func chmodDir(root *os.Root, name string) error {
+	dir, err := root.Open(name)
+	if err != nil {
+		return err
+	}
+
+	defer func() { _ = dir.Close() }()
+
+	info, err := dir.Stat()
+	if err != nil {
+		return err
+	}
+
+	if !info.IsDir() {
+		return &fs.PathError{Op: "chmod", Path: name, Err: syscall.ENOTDIR}
+	}
+
+	return dir.Chmod(dirPerms)
+}

backend/internal/reportbuf/datadir_test.go

@@ -0,0 +1,307 @@
+package reportbuf_test
+
+import (
+	"errors"
+	"io/fs"
+	"os"
+	"os/user"
+	"path/filepath"
+	"strconv"
+	"syscall"
+	"testing"
+
+	"sneak.berlin/go/netwatch/internal/reportbuf"
+)
+
+// reports is the last part of DATA_DIR in these tests, as in the
+// image's /data/reports.
+const reports = "reports"
+
+// currentUser is the user the test runs as, the only owner a test not
+// run as root can give files to.
+func currentUser() *user.User {
+	return &user.User{
+		Uid: strconv.Itoa(os.Getuid()),
+		Gid: strconv.Itoa(os.Getgid()),
+	}
+}
+
+// tempDirMode700 is a new directory in a t.TempDir with mode 0700, so
+// a test can tell that PrepareDataDir left its mode alone.
+func tempDirMode700(t *testing.T) string {
+	t.Helper()
+
+	dir := filepath.Join(t.TempDir(), "d")
+
+	err := os.Mkdir(dir, 0o700)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	return dir
+}
+
+func requireMode(t *testing.T, path string, want fs.FileMode) {
+	t.Helper()
+
+	info, err := os.Stat(path)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	if info.Mode() != want {
+		t.Errorf("%s: mode %v, want %v", path, info.Mode(), want)
+	}
+}
+
+func requireMissing(t *testing.T, path string) {
+	t.Helper()
+
+	_, err := os.Lstat(path)
+	if !errors.Is(err, fs.ErrNotExist) {
+		t.Errorf("%s: created, or Lstat failed: %v", path, err)
+	}
+}
+
+func requireOwner(t *testing.T, path string, uid, gid uint32) {
+	t.Helper()
+
+	info, err := os.Lstat(path)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	stat, _ := info.Sys().(*syscall.Stat_t)
+	if stat.Uid != uid || stat.Gid != gid {
+		t.Errorf("%s: owner %d:%d, want %d:%d", path, stat.Uid, stat.Gid,
+			uid, gid)
+	}
+}
+
+func TestPrepareDataDirCreatesDataDir(t *testing.T) {
+	t.Parallel()
+
+	volume := t.TempDir()
+	dir := filepath.Join(volume, "a", reports)
+
+	err := reportbuf.PrepareDataDir(volume, dir, currentUser())
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	requireMode(t, volume, fs.ModeDir|0o750)
+	requireMode(t, dir, fs.ModeDir|0o750)
+}
+
+// TestPrepareDataDirSetsModeOfExistingDataDir: a DATA_DIR already on
+// the host with another mode gets the mode too, not only a new one.
+func TestPrepareDataDirSetsModeOfExistingDataDir(t *testing.T) {
+	t.Parallel()
+
+	volume := t.TempDir()
+	dir := filepath.Join(volume, reports)
+
+	err := os.Mkdir(dir, 0o700)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	err = reportbuf.PrepareDataDir(volume, dir, currentUser())
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	requireMode(t, dir, fs.ModeDir|0o750)
+}
+
+func TestPrepareDataDirTakesTheVolumeItself(t *testing.T) {
+	t.Parallel()
+
+	volume := t.TempDir()
+
+	err := reportbuf.PrepareDataDir(volume, volume, currentUser())
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	requireMode(t, volume, fs.ModeDir|0o750)
+}
+
+// TestPrepareDataDirRefusesDataDirOutsideVolume covers a DATA_DIR that
+// is relative, outside the volume, or not written in full.
+func TestPrepareDataDirRefusesDataDirOutsideVolume(t *testing.T) {
+	t.Parallel()
+
+	volume := tempDirMode700(t)
+	for _, dir := range []string{
+		reports, volume + "/../new", volume + "/", volume + "//" + reports,
+		volume + "/./" + reports, volume + "/" + reports + "/..", volume + "x",
+		"/etc",
+	} {
+		err := reportbuf.PrepareDataDir(volume, dir, currentUser())
+		if !errors.Is(err, reportbuf.ErrDataDirOutsideVolume) {
+			t.Errorf("%q: error = %v, want ErrDataDirOutsideVolume", dir, err)
+		}
+	}
+
+	requireMissing(t, filepath.Join(filepath.Dir(volume), "new"))
+	requireMode(t, volume, fs.ModeDir|0o700)
+}
+
+// TestPrepareDataDirRefusesLinkOutOfVolume puts a symbolic link to a
+// directory outside the volume on the path to DATA_DIR, written as a
+// full path and as one that climbs out with '..', and as DATA_DIR
+// itself, where the mode would be set through it.
+func TestPrepareDataDirRefusesLinkOutOfVolume(t *testing.T) {
+	t.Parallel()
+
+	for _, tc := range []struct {
+		name      string
+		climbsOut bool
+		link, dir string
+	}{
+		{"full path", false, "x", "x/reports"},
+		{"climbs out", true, "x", "x/reports"},
+		{"DATA_DIR itself", false, reports, reports},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			t.Parallel()
+
+			outside := tempDirMode700(t)
+			volume := t.TempDir()
+
+			climbOut, err := filepath.Rel(volume, outside)
+			if err != nil {
+				t.Fatal(err)
+			}
+
+			target := outside
+			if tc.climbsOut {
+				target = climbOut
+			}
+
+			err = os.Symlink(target, filepath.Join(volume, tc.link))
+			if err != nil {
+				t.Fatal(err)
+			}
+
+			err = reportbuf.PrepareDataDir(volume,
+				filepath.Join(volume, tc.dir), currentUser())
+			if err == nil {
+				t.Error("no error")
+			}
+
+			requireMissing(t, filepath.Join(outside, reports))
+			requireMode(t, outside, fs.ModeDir|0o700)
+		})
+	}
+}
+
+// TestPrepareDataDirRefusesDanglingLink: DATA_DIR is a symbolic link
+// to a name in the volume that does not exist, which is not created.
+func TestPrepareDataDirRefusesDanglingLink(t *testing.T) {
+	t.Parallel()
+
+	volume := t.TempDir()
+
+	err := os.Symlink("missing", filepath.Join(volume, reports))
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	err = reportbuf.PrepareDataDir(volume, filepath.Join(volume, reports),
+		currentUser())
+	if err == nil {
+		t.Error("no error")
+	}
+
+	requireMissing(t, filepath.Join(volume, "missing"))
+}
+
+// TestPrepareDataDirTakesDirectoryNamedInLatin1: a host directory can
+// hold names that are not valid UTF-8, here "café" written in Latin-1.
+// A test not run as root can only check that PrepareDataDir goes into
+// such a directory and gives it, and what it holds, to the current
+// user.
+func TestPrepareDataDirTakesDirectoryNamedInLatin1(t *testing.T) {
+	t.Parallel()
+
+	volume := t.TempDir()
+	latin1 := filepath.Join(volume, "caf\xe9")
+
+	err := os.Mkdir(latin1, 0o700)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	err = os.WriteFile(filepath.Join(latin1, "f"), nil, 0o600)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	owner := currentUser()
+
+	err = reportbuf.PrepareDataDir(volume, filepath.Join(volume, reports),
+		owner)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	uid, _ := strconv.ParseUint(owner.Uid, 10, 32)
+	gid, _ := strconv.ParseUint(owner.Gid, 10, 32)
+
+	requireOwner(t, latin1, uint32(uid), uint32(gid))
+	requireOwner(t, filepath.Join(latin1, "f"), uint32(uid), uint32(gid))
+}
+
+// TestPrepareDataDirGivesVolumeToOwner gives everything in the volume
+// to a uid and gid that own nothing, which only root can do. A
+// symbolic link in the volume to a directory outside it is given to
+// them itself; what it points to is left as it was.
+func TestPrepareDataDirGivesVolumeToOwner(t *testing.T) {
+	t.Parallel()
+
+	if os.Geteuid() != 0 {
+		t.Skip("only root can give files to another uid")
+	}
+
+	outside := t.TempDir()
+	volume := t.TempDir()
+	old := filepath.Join(volume, "old")
+
+	err := os.WriteFile(filepath.Join(outside, "f"), nil, 0o600)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	err = os.Mkdir(old, 0o700)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	err = os.WriteFile(filepath.Join(old, "f"), nil, 0o600)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	err = os.Symlink(outside, filepath.Join(old, "link"))
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	err = reportbuf.PrepareDataDir(volume, filepath.Join(volume, reports),
+		&user.User{Uid: "4242", Gid: "4343"})
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	for _, path := range []string{
+		volume, filepath.Join(volume, reports), old,
+		filepath.Join(old, "f"), filepath.Join(old, "link"),
+	} {
+		requireOwner(t, path, 4242, 4343)
+	}
+
+	requireOwner(t, outside, 0, 0)
+	requireOwner(t, filepath.Join(outside, "f"), 0, 0)
+}

backend/internal/reportbuf/export_test.go

@@ -5,6 +5,10 @@ import (
 	"time"
 )
 
+// FlushSizeThreshold exposes the buffer size at which Append starts
+// writing a report file to the external tests.
+const FlushSizeThreshold = flushSizeThreshold
+
 // Flush writes the buffered reports to a file now, as the periodic
 // flush does, so tests need not wait a minute for it.
 func (b *Buffer) Flush() error {

backend/internal/reportbuf/reportbuf.go

@@ -13,6 +13,7 @@ import (
 	"log/slog"
 	"os"
 	"path/filepath"
+	"slices"
 	"strings"
 	"sync"
 	"sync/atomic"
@@ -69,9 +70,11 @@ type Buffer struct {
 	// except in tests that hold the write open or make it fail.
 	fileCreated func(f *os.File)
 	// files are the report files that may be deleted to make room,
-	// oldest first: those in dataDir at start, then each one this
+	// in name order, which is oldest first: those in dataDir at
-	// buffer writes, once it is complete. A file still being written
+	// start, and each one this buffer writes, put in at its place by
-	// is not among them. filesBytes is their total size.
+	// name once it is complete, even when an older file's write
+	// completes after a newer one's. A file still being written is
+	// not among them. filesBytes is their total size.
 	files      []reportFile
 	filesBytes int64
 	log        *slog.Logger
@@ -311,9 +314,16 @@ func (b *Buffer) writeFile(data []byte) error {
 	}
 
 	b.usedBytes += size
-	b.files = append(b.files, reportFile{name: name, size: size})
 	b.filesBytes += size
 
+	// At its place by name, not at the end: another write, of a newer
+	// file, may have completed while this one was being written.
+	i, _ := slices.BinarySearchFunc(b.files, name,
+		func(f reportFile, target string) int {
+			return strings.Compare(f.name, target)
+		})
+	b.files = slices.Insert(b.files, i, reportFile{name: name, size: size})
+
 	return nil
 }
 

backend/internal/reportbuf/reportbuf_test.go

@@ -424,15 +424,18 @@ func TestFileDeletedByHandFreesRoom(t *testing.T) {
 	}
 }
 
-// TestFileBeingWrittenIsNeverDeleted holds a write open, its file
+// TestFileBeingWrittenIsNeverDeleted holds the write of one report file
-// created but not complete, while a report needs room. The file may
+// open while a second write completes, then sends a report that needs
-// not be deleted to make it, so the report is refused. Once the write
+// room. Deleting either file would make it, and the one being written is
-// is complete, the file is deleted when room is needed.
+// the older, but only the complete one may be deleted. Once the first
+// write is complete, its file is deleted when room is needed.
 func TestFileBeingWrittenIsNeverDeleted(t *testing.T) {
 	report := map[string]string{"id": "writing"}
 
 	t.Setenv("DATA_DIR", t.TempDir())
-	t.Setenv("DATA_DIR_MAX_BYTES", strconv.Itoa(lineBytes(t, report)))
+	// Room for two reports waiting to be written, but not for two
+	// beside a report file.
+	t.Setenv("DATA_DIR_MAX_BYTES", strconv.Itoa(2*lineBytes(t, report)))
 
 	buf := startBuffer(t)
 
@@ -447,7 +450,7 @@ func TestFileBeingWrittenIsNeverDeleted(t *testing.T) {
 
 	err := buf.Append(report)
 	if err != nil {
-		t.Fatalf("report that fills the cap exactly: %v", err)
+		t.Fatalf("first report: %v", err)
 	}
 
 	flushed := make(chan error)
@@ -456,32 +459,47 @@ func TestFileBeingWrittenIsNeverDeleted(t *testing.T) {
 
 	writing := <-created
 
-	// Errorf, not Fatalf, until the write is released, so that a
+	// Only the first write is held; the second goes through, and
+	// so do the writes after it, the final one at stop included.
+	var complete string
+
+	buf.OnFileCreated(func(f *os.File) { complete = f.Name() })
+
+	// Errorf, not Fatalf, until the first write is released, so that a
 	// failure here does not leave it held.
 	err = buf.Append(report)
-	if !errors.Is(err, reportbuf.ErrFull) {
+	if err != nil {
-		t.Errorf("report while the first was being written: "+
+		t.Errorf("second report: %v", err)
-			"error = %v, want ErrFull", err)
+	}
+
+	err = buf.Flush()
+	if err != nil {
+		t.Errorf("flush of the second report: %v", err)
+	}
+
+	err = buf.Append(report)
+	if err != nil {
+		t.Errorf("report that needs room: %v", err)
 	}
 
 	if !exists(t, writing) {
 		t.Error("report file deleted while it was being written")
 	}
 
+	if exists(t, complete) {
+		t.Error("complete report file kept, though room was needed")
+	}
+
 	close(release)
 
 	err = <-flushed
 	if err != nil {
-		t.Fatalf("flush: %v", err)
+		t.Fatalf("flush of the first report: %v", err)
 	}
 
-	// Writes from here on, the final one at stop included, go
-	// through unheld.
-	buf.OnFileCreated(func(*os.File) {})
-
 	err = buf.Append(report)
 	if err != nil {
-		t.Fatalf("report after the write was complete: %v", err)
+		t.Fatalf("report after the first write was complete: %v", err)
 	}
 
 	if exists(t, writing) {
@@ -604,7 +622,11 @@ func TestTwoFlushesInOneMillisecond(t *testing.T) {
 		}
 	}
 
-	files := readReportFiles(t, dir)
+	files, err := readReportFiles(dir)
+	if err != nil {
+		t.Fatalf("read report files: %v", err)
+	}
+
 	if len(files) != flushes {
 		t.Fatalf("%d report files after %d flushes", len(files), flushes)
 	}
@@ -617,6 +639,88 @@ func TestTwoFlushesInOneMillisecond(t *testing.T) {
 	}
 }
 
+// TestReportFileHoldsTheLinesAppended flushes three reports and reads
+// their file back: it must decompress to exactly their JSON lines, in
+// the order they were appended.
+func TestReportFileHoldsTheLinesAppended(t *testing.T) {
+	dir := t.TempDir()
+	t.Setenv("DATA_DIR", dir)
+
+	buf := startBuffer(t)
+
+	for _, id := range []int{1, 2, 3} {
+		err := buf.Append(map[string]int{"id": id})
+		if err != nil {
+			t.Fatalf("append report %d: %v", id, err)
+		}
+	}
+
+	err := buf.Flush()
+	if err != nil {
+		t.Fatalf("flush: %v", err)
+	}
+
+	files, err := readReportFiles(dir)
+	if err != nil {
+		t.Fatalf("read report files: %v", err)
+	}
+
+	want := `{"id":1}` + "\n" + `{"id":2}` + "\n" + `{"id":3}` + "\n"
+	if len(files) != 1 || files[0] != want {
+		t.Fatalf("report files = %q, want one holding %q", files, want)
+	}
+}
+
+// TestFlushAtSizeThreshold appends reports until the buffer holds
+// FlushSizeThreshold bytes. The append that gets it there must write
+// them all to one report file, with no call to Flush and the periodic
+// flush a minute away, and no earlier append may write one.
+func TestFlushAtSizeThreshold(t *testing.T) {
+	dir := t.TempDir()
+	t.Setenv("DATA_DIR", dir)
+
+	buf := startBuffer(t)
+
+	// Large reports, so the threshold takes a few hundred appends.
+	pad := strings.Repeat("a", 64<<10)
+
+	var appended strings.Builder
+
+	for id := 0; appended.Len() < reportbuf.FlushSizeThreshold; id++ {
+		report := map[string]any{"id": id, "pad": pad}
+
+		err := buf.Append(report)
+		if err != nil {
+			t.Fatalf("append report %d: %v", id, err)
+		}
+
+		line, err := json.Marshal(report)
+		if err != nil {
+			t.Fatalf("marshal report %d: %v", id, err)
+		}
+
+		appended.Write(line)
+		appended.WriteByte('\n')
+	}
+
+	// Append writes the file in the background, so wait for it.
+	deadline := time.Now().Add(10 * time.Second)
+
+	for {
+		files, err := readReportFiles(dir)
+		if err == nil && len(files) == 1 && files[0] == appended.String() {
+			return
+		}
+
+		if time.Now().After(deadline) {
+			t.Fatalf("%d report files (error: %v), want one holding the "+
+				"%d bytes appended", len(files), err, appended.Len())
+		}
+
+		time.Sleep(10 * time.Millisecond)
+	}
+}
+
 // reportFilesBytes returns the total size of the report files in dir.
 func reportFilesBytes(t *testing.T, dir string) int64 {
 	t.Helper()
@@ -641,20 +745,19 @@ func reportFilesBytes(t *testing.T, dir string) int64 {
 }
 
 // readReportFiles returns the decompressed contents of each report
-// file in dir.
+// file in dir. A file still being written does not decompress, so it
-func readReportFiles(t *testing.T, dir string) []string {
+// gives an error.
-	t.Helper()
+func readReportFiles(dir string) ([]string, error) {
-
 	files := os.DirFS(dir)
 
 	names, err := fs.Glob(files, "reports-*.jsonl.zst")
 	if err != nil {
-		t.Fatalf("list report files: %v", err)
+		return nil, fmt.Errorf("list report files: %w", err)
 	}
 
 	dec, err := zstd.NewReader(nil)
 	if err != nil {
-		t.Fatalf("create zstd decoder: %v", err)
+		return nil, fmt.Errorf("create zstd decoder: %w", err)
 	}
 	defer dec.Close()
 
@@ -663,18 +766,18 @@ func readReportFiles(t *testing.T, dir string) []string {
 	for _, name := range names {
 		compressed, readErr := fs.ReadFile(files, name)
 		if readErr != nil {
-			t.Fatalf("read %s: %v", name, readErr)
+			return nil, fmt.Errorf("read %s: %w", name, readErr)
 		}
 
 		data, decErr := dec.DecodeAll(compressed, nil)
 		if decErr != nil {
-			t.Fatalf("decompress %s: %v", name, decErr)
+			return nil, fmt.Errorf("decompress %s: %w", name, decErr)
 		}
 
 		contents = append(contents, string(data))
 	}
 
-	return contents
+	return contents, nil
 }
 
 // reportFilePath returns the path in dir of a report file named as
@@ -732,3 +835,85 @@ func hasReportFile(t *testing.T, dir string) bool {
 
 	return false
 }
+
+// TestFilesDeletedOldestFirstWhenWritesOverlap holds the write of an
+// older report file open until a newer one's write completes, then
+// releases it. When room is needed, the older file is deleted first,
+// though its write was the last to complete.
+func TestFilesDeletedOldestFirstWhenWritesOverlap(t *testing.T) {
+	const maxBytes = 1000
+
+	report := map[string]string{"id": "overlap"}
+
+	t.Setenv("DATA_DIR", t.TempDir())
+	t.Setenv("DATA_DIR_MAX_BYTES", strconv.Itoa(maxBytes))
+
+	buf := startBuffer(t)
+
+	created := make(chan string)
+	release := make(chan struct{})
+
+	buf.OnFileCreated(func(f *os.File) {
+		created <- f.Name()
+
+		<-release
+	})
+
+	err := buf.Append(report)
+	if err != nil {
+		t.Fatalf("older report: %v", err)
+	}
+
+	flushed := make(chan error)
+
+	go func() { flushed <- buf.Flush() }()
+
+	older := <-created
+
+	// Only the older write is held; the newer one goes through, and
+	// so do the writes after it, the final one at stop included.
+	var newer string
+
+	buf.OnFileCreated(func(f *os.File) { newer = f.Name() })
+
+	// Errorf, not Fatalf, until the older write is released, so that a
+	// failure here does not leave it held.
+	err = buf.Append(report)
+	if err != nil {
+		t.Errorf("newer report: %v", err)
+	}
+
+	err = buf.Flush()
+	if err != nil {
+		t.Errorf("flush of the newer report: %v", err)
+	}
+
+	close(release)
+
+	err = <-flushed
+	if err != nil {
+		t.Fatalf("flush of the older report: %v", err)
+	}
+
+	info, err := os.Stat(newer)
+	if err != nil {
+		t.Fatalf("stat %s: %v", newer, err)
+	}
+
+	// A report that fits beside the newer file alone, so deleting the
+	// older one makes exactly the room it needs.
+	pad := maxBytes - int(info.Size()) - lineBytes(t, map[string]string{"id": ""})
+
+	err = buf.Append(map[string]string{"id": strings.Repeat("a", pad)})
+	if err != nil {
+		t.Fatalf("report that needs room: %v", err)
+	}
+
+	if exists(t, older) {
+		t.Fatal("older report file kept when room was needed")
+	}
+
+	if !exists(t, newer) {
+		t.Fatal("newer report file deleted before the older one")
+	}
+}

backend/internal/server/routes.go

@@ -5,6 +5,9 @@ import (
 
 	"github.com/go-chi/chi/v5"
 	"github.com/go-chi/chi/v5/middleware"
+	"github.com/prometheus/client_golang/prometheus"
+	"github.com/prometheus/client_golang/prometheus/collectors"
+	"github.com/prometheus/client_golang/prometheus/promhttp"
 )
 
 const (
@@ -29,13 +32,37 @@ func (s *Server) SetupRoutes() {
 	s.router.Use(s.mw.MaxBodyBytes(maxRequestBodyBytes))
 	s.router.Use(middleware.Timeout(requestTimeout))
 
-	s.router.Get(
+	// The metrics go in a registry of this server's own, not in
-		"/.well-known/healthcheck",
+	// Prometheus' default one, which takes them only once per process.
-		s.h.HandleHealthCheck(),
+	registry := prometheus.NewRegistry()
+	registry.MustRegister(
+		collectors.NewGoCollector(),
+		collectors.NewProcessCollector(collectors.ProcessCollectorOpts{}),
 	)
 
-	s.router.Route("/api/v1", func(r chi.Router) {
+	// Requests are measured only once chi has matched them to one of
+	// these routes, by path and method. The metrics are labelled with
+	// both, which any client can make up, so measuring every request
+	// would let clients add labels without bound. A Route here would
+	// be matched by its path prefix alone, so each path is given in
+	// full.
+	s.router.Group(func(r chi.Router) {
+		// config.New refuses one of the two credentials without the
+		// other.
+		if s.params.Config.MetricsUsername != "" {
+			r.Use(s.mw.Metrics(registry))
+		}
+
+		r.Get("/.well-known/healthcheck", s.h.HandleHealthCheck())
+
 		r.With(s.mw.RateLimit(s.params.Config.ReportsPerMinute)).
-			Post("/reports", s.h.HandleReport())
+			Post("/api/v1/reports", s.h.HandleReport())
 	})
+
+	if s.params.Config.MetricsUsername != "" {
+		s.router.With(s.mw.MetricsAuth()).
+			Get("/metrics", promhttp.HandlerFor(
+				registry, promhttp.HandlerOpts{},
+			).ServeHTTP)
+	}
 }

backend/internal/server/routes_test.go

@@ -107,6 +107,95 @@ func TestCORSAllowedOriginsReachTheRouter(t *testing.T) {
 	}
 }
 
+// TestNoMetricsWithoutCredentials: with neither metrics setting set,
+// there is no /metrics.
+func TestNoMetricsWithoutCredentials(t *testing.T) {
+	t.Setenv("METRICS_USERNAME", "")
+	t.Setenv("METRICS_PASSWORD", "")
+
+	srv := newServer(t)
+	srv.SetupRoutes()
+
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequestWithContext(t.Context(),
+		http.MethodGet, "/metrics", http.NoBody)
+	srv.ServeHTTP(rec, req)
+
+	if rec.Code != http.StatusNotFound {
+		t.Fatalf("status = %d, want %d", rec.Code, http.StatusNotFound)
+	}
+}
+
+// TestMetricsBehindBasicAuth: with both metrics settings set, /metrics
+// answers only with them as basic auth credentials, and shows a
+// request to a route but not one to a path no route has.
+func TestMetricsBehindBasicAuth(t *testing.T) {
+	t.Setenv("METRICS_USERNAME", "prometheus")
+	t.Setenv("METRICS_PASSWORD", "right")
+
+	srv := newServer(t)
+	srv.SetupRoutes()
+
+	get := func(path, username, password string) *httptest.ResponseRecorder {
+		rec := httptest.NewRecorder()
+		req := httptest.NewRequestWithContext(t.Context(),
+			http.MethodGet, path, http.NoBody)
+
+		if username != "" {
+			req.SetBasicAuth(username, password)
+		}
+
+		srv.ServeHTTP(rec, req)
+
+		return rec
+	}
+
+	get("/.well-known/healthcheck", "", "")
+	get("/api/v1/no-such-route", "", "")
+
+	for _, creds := range [][2]string{
+		{"", ""},
+		{"prometheus", "wrong"},
+		{"someone", "right"},
+	} {
+		rec := get("/metrics", creds[0], creds[1])
+		if rec.Code != http.StatusUnauthorized {
+			t.Errorf("credentials %q: status = %d, want %d",
+				creds, rec.Code, http.StatusUnauthorized)
+		}
+	}
+
+	rec := get("/metrics", "prometheus", "right")
+	if rec.Code != http.StatusOK {
+		t.Fatalf("right credentials: status = %d, want %d",
+			rec.Code, http.StatusOK)
+	}
+
+	body := rec.Body.String()
+	if !strings.Contains(body, `handler="/.well-known/healthcheck"`) {
+		t.Errorf("metrics show no health check request:\n%s", body)
+	}
+
+	if strings.Contains(body, "no-such-route") {
+		t.Errorf("metrics show a request to a path no route has:\n%s", body)
+	}
+
+	if !strings.Contains(body, "go_goroutines") {
+		t.Errorf("metrics show no Go runtime metrics:\n%s", body)
+	}
+}
+
+// TestMetricsInTwoServers: two servers in one process can both have
+// metrics on.
+func TestMetricsInTwoServers(t *testing.T) {
+	t.Setenv("METRICS_USERNAME", "prometheus")
+	t.Setenv("METRICS_PASSWORD", "right")
+
+	for range 2 {
+		newServer(t).SetupRoutes()
+	}
+}
+
 // TestHealthCheckRejectsOversizeBody sends the health check, which
 // never reads its body, a body one byte over the limit. Only the
 // router-wide body limit can reject it.

backend/script/lint

@@ -14,16 +14,34 @@ set -eu
 
 ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
 
+# The sha256 of the org standard .golangci.yml. When that file changes in
+# sneak/prompts and is copied here again, this changes with it.
 GOLANGCI_CONFIG_SHA256="a79b63a254602a5318db5d0e9a06bc71b84bf0c1d896305229d8bfed1d1b1776"
 
 main() {
     cd "$ROOT"
+    if [ ! -f .golangci.yml ]; then
+        echo "backend/.golangci.yml is missing. Copy the org standard verbatim" >&2
+        echo "from https://git.eeqj.de/sneak/prompts/raw/branch/main/.golangci.yml" >&2
+        exit 1
+    fi
     actual="$(sha256sum .golangci.yml | cut -d' ' -f1)"
+    if [ -z "$actual" ]; then
+        echo "sha256sum is missing or printed no hash, so" >&2
+        echo "backend/.golangci.yml could not be checked." >&2
+        exit 1
+    fi
     if [ "$actual" != "$GOLANGCI_CONFIG_SHA256" ]; then
-        echo ".golangci.yml has drifted from the org standard." >&2
+        echo "backend/.golangci.yml does not match GOLANGCI_CONFIG_SHA256" >&2
+        echo "in backend/script/lint." >&2
         echo "  expected $GOLANGCI_CONFIG_SHA256" >&2
         echo "  actual   $actual" >&2
-        echo "Restore it verbatim from sneak/prompts; do not edit it." >&2
+        echo "Compare it with the org standard," >&2
+        echo "https://git.eeqj.de/sneak/prompts/raw/branch/main/.golangci.yml" >&2
+        echo "- If they differ, it was edited here: restore the org standard" >&2
+        echo "  verbatim. Do not edit it." >&2
+        echo "- If they are the same, the org standard changed: set" >&2
+        echo "  GOLANGCI_CONFIG_SHA256 in backend/script/lint to the actual hash." >&2
         exit 1
     fi
     golangci-lint run ./...

backend/script/test

@@ -1,12 +1,20 @@
 #!/bin/sh
-# script/test: run the backend test suite.
+# script/test: run the backend test suite with the race detector and
+# coverage. Go's own -timeout bounds the tests and not their compile,
+# so a cold build cache cannot fail it. The race detector needs cgo,
+# and so a C compiler. If the tests fail, they run again with -v for
+# the details, and the script fails even if that run passes.
 set -eu
 
 ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
 
 main() {
     cd "$ROOT"
-    timeout 30 go test ./...
+    go test -timeout 30s -race -cover ./... || {
+        echo "--- Rerunning with -v for details ---"
+        go test -timeout 30s -race -v ./...
+        exit 1
+    }
 }
 
 main "$@"

bin/entrypoint.sh

@@ -63,26 +63,13 @@ done > /etc/nginx/trusted-proxies.conf
 
 # netwatch-server keeps its report files in DATA_DIR, on the /data
 # volume, which may be a host directory owned by root or by another
-# uid. Both are given to the netwatch user here, with the mode the
+# uid. Here, as root, netwatch-server prepare-data-dir creates DATA_DIR
-# server gives a directory it creates, so the host directory needs no
+# and gives /data and everything in it to the netwatch user, so the
-# preparing.
+# host directory needs no preparing. It stops the start, naming
-#
+# DATA_DIR, unless DATA_DIR is /data or a path below it, and it acts on
-# chown and chmod, run as root, change whatever a symbolic link on the
+# nothing outside /data, whatever symbolic links it meets there.
-# path points to, anywhere in the container, and the netwatch user can
-# put one in /data. So the start stops unless readlink -f, which
-# follows every link on a path, gives /data and DATA_DIR back as they
-# are. It also writes a path in full, so a DATA_DIR with '.', '..' or
-# an extra '/' in it is refused too.
 export DATA_DIR="${DATA_DIR:-/data/reports}"
-mkdir -p "$DATA_DIR" || exit 1
+netwatch-server prepare-data-dir "$DATA_DIR" || exit 1
-if [ "$(readlink -f /data)" != /data ] ||
-    [ "$(readlink -f "$DATA_DIR")" != "$DATA_DIR" ]; then
-    echo "entrypoint: DATA_DIR must be a full path with no '.', '..'," \
-        "extra '/' or symbolic link on it or on /data, not '$DATA_DIR'" >&2
-    exit 1
-fi
-chown -R netwatch:netwatch /data "$DATA_DIR" || exit 1
-chmod 750 /data "$DATA_DIR" || exit 1
 
 # A stop signal is only noted here; the loop below acts on it.
 stop_requested=""

eslint.config.js

@@ -0,0 +1,27 @@
+// eslint's recommended rules over every JavaScript file in the repo.
+// script/frontend-lint runs it, in the frontend-lint stage of Dockerfile.
+import js from "@eslint/js";
+import globals from "globals";
+import { defineConfig } from "eslint/config";
+
+export default defineConfig([
+    js.configs.recommended,
+    {
+        // The page, and facts.js, which the viewport test runs inside it.
+        files: ["src/**/*.js", "test/viewport/facts.js"],
+        languageOptions: {
+            globals: {
+                ...globals.browser,
+                // vite.config.js defines these when it builds the page.
+                __COMMIT_HASH__: "readonly",
+                __COMMIT_FULL__: "readonly",
+            },
+        },
+    },
+    {
+        // Run by node: the tests, the viewport harness and these configs.
+        files: ["test/**/*.js", "*.js"],
+        ignores: ["test/viewport/facts.js"],
+        languageOptions: { globals: globals.node },
+    },
+]);

nginx.conf

@@ -68,4 +68,10 @@ server {
     location = /.well-known/healthcheck {
         proxy_pass http://127.0.0.1:8081;
     }
+
+    # The backend's Prometheus metrics, behind its own basic auth. Unless
+    # METRICS_USERNAME and METRICS_PASSWORD are set, it answers 404.
+    location = /metrics {
+        proxy_pass http://127.0.0.1:8081;
+    }
 }

package.json

@@ -6,12 +6,16 @@
     "scripts": {
         "dev": "vite",
         "build": "vite build",
-        "preview": "vite preview"
+        "preview": "vite preview",
+        "test": "node --test test/unit/*.test.js"
     },
     "license": "MIT",
     "devDependencies": {
+        "@eslint/js": "^10.0.1",
         "@tailwindcss/vite": "^4.1.18",
         "autoprefixer": "^10.4.23",
+        "eslint": "^10.12.0",
+        "globals": "^17.13.0",
         "postcss": "^8.5.6",
         "prettier": "^3.8.1",
         "puppeteer-core": "25.5.0",

script/add-dependency

@@ -0,0 +1,30 @@
+#!/bin/sh
+# script/add-dependency: add a frontend package, or move one to another
+# version, with yarn add, which changes package.json and yarn.lock
+# together; then install from yarn.lock with --frozen-lockfile, as
+# script/bootstrap does, to show it installs as written. --dev because
+# no frontend package is needed when the page runs: it ships as the
+# built dist/.
+set -eu
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
+
+usage() {
+    echo "usage: make add-dependency PACKAGE=<name>@<version>" >&2
+    exit 2
+}
+
+main() {
+    # Exactly one package. A value beginning with - would reach yarn as
+    # an option; yarn would quietly drop all but the first of several
+    # packages given in one value.
+    [ "$#" -eq 1 ] || usage
+    case "$1" in
+    "" | -* | *[[:space:]]*) usage ;;
+    esac
+    cd "$ROOT"
+    yarn add --dev "$1"
+    yarn install --frozen-lockfile
+}
+
+main "$@"

script/bootstrap

@@ -17,16 +17,18 @@
 #
 # golangci-lint is not installed: make lint runs it in Docker, which
 # this script does not install either.
+#
+# Unlike the org model: Go and gcc for backend/, a newer node for eslint.
 set -eu
 
 ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
 
-# Pinned versions, 2026-07-07
+# Pinned versions, 2026-07-06
 NODE_VERSION="22.17.0"
 # The oldest node the frontend's dependencies accept: the "engines"
-# field of puppeteer-core 25.5.0, the most demanding of them, asks for
+# field of eslint 10.12.0, the most demanding of them, asks for 22.13.0
-# 22.12.0 or newer, 2026-09-29. An older installed node is not used.
+# or newer, 2026-10-03. An older installed node is not used.
-NODE_MIN_VERSION="22.12.0"
+NODE_MIN_VERSION="22.13.0"
 NVM_VERSION="0.40.3"
 # sha256 of https://github.com/nvm-sh/nvm/archive/refs/tags/v0.40.3.tar.gz
 NVM_SHA256="5f4d6aaa04a177dc93c985e31dbc411ab6b8c6e1e21d8015dbc1372625fcd1d0"
@@ -64,7 +66,8 @@ detect_pkgmgr() {
     fi
 }
 
-# pkg_install <nix-attr> <apt-pkg> <brew-formula> <apk-pkg>
+# pkg_install <nix-attr> <apt-pkgs> <brew-formula> <apk-pkgs>: the apt
+# and apk arguments may each list several packages, separated by spaces.
 pkg_install() {
     detect_pkgmgr
     case "$PKGMGR" in
@@ -74,10 +77,10 @@ pkg_install() {
                 $SUDO env DEBIAN_FRONTEND=noninteractive apt-get update
                 APT_UPDATED=1
             fi
-            $SUDO env DEBIAN_FRONTEND=noninteractive apt-get install -y "$2"
+            $SUDO env DEBIAN_FRONTEND=noninteractive apt-get install -y $2
             ;;
         brew) brew install "$3" ;;
-        apk) apk add --no-cache "$4" ;;
+        apk) apk add --no-cache $4 ;;
     esac
 }
 
@@ -253,6 +256,12 @@ main() {
 
     if missing make; then pkg_install gnumake make make make; fi
     if missing git; then pkg_install git git git git; fi
+    # The race detector in make test needs cgo, which Go turns on only
+    # when it finds its C compiler, gcc on Linux. apt and apk ship the C
+    # library headers apart from gcc.
+    if missing gcc; then
+        pkg_install gcc "gcc libc6-dev" gcc "gcc musl-dev"
+    fi
 
     ensure_node
     ensure_yarn
@@ -263,7 +272,7 @@ main() {
 
     if missing docker; then
         echo "bootstrap: docker not found; make lint, and so make check" >&2
-        echo "  and the pre-commit hook, need it to run the Go linter" >&2
+        echo "  and the pre-commit hook, need it to run the linters" >&2
     fi
     if [ -n "$path_hint" ] && [ -d "$BIN_DIR" ]; then
         echo "bootstrap: add $BIN_DIR to the front of your PATH, e.g." >&2

script/build

@@ -0,0 +1,13 @@
+#!/bin/sh
+# script/build: build the frontend for production into dist/. The Go
+# backend is built by backend/script/build.
+set -eu
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
+
+main() {
+    cd "$ROOT"
+    yarn build
+}
+
+main "$@"

script/dev

@@ -0,0 +1,13 @@
+#!/bin/sh
+# script/dev: run the frontend's Vite dev server. It proxies /api to a
+# netwatch-server running locally (see vite.config.js).
+set -eu
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
+
+main() {
+    cd "$ROOT"
+    yarn dev
+}
+
+main "$@"

script/fmt

@@ -1,6 +1,7 @@
 #!/bin/sh
 # script/fmt: format the whole repo (writes): prettier over everything
 # it understands, then gofmt over the Go backend.
+# The org model formats only markdown; this repo also has JS and Go.
 set -eu
 
 ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"

script/fmt-check

@@ -1,6 +1,7 @@
 #!/bin/sh
 # script/fmt-check: check formatting across the whole repo (read-only).
 # Same scope as script/fmt, but fails instead of writing.
+# The org model checks only markdown; this repo also has JS and Go.
 set -eu
 
 ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"

script/frontend-check

@@ -1,9 +1,10 @@
 #!/bin/sh
-# script/frontend-check: run the frontend half of the checks only (test,
+# script/frontend-check: run the frontend tests and format check only.
-# lint, fmt-check). This exists for the frontend stage of Dockerfile, a
+# This exists for the frontend stage of Dockerfile, a node image with
-# node image with neither Go nor Docker; the Dockerfile's lint and
+# neither Go nor Docker; the Dockerfile's frontend-lint stage runs the
-# backend build stages gate the backend half. Everywhere else, use
+# frontend linter, and its lint and builder stages gate the backend.
-# script/check, which covers the whole repo. Must not modify any files.
+# Everywhere else, use script/check, which covers the whole repo. Must
+# not modify any files.
 set -eu
 
 ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
@@ -11,7 +12,6 @@ ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
 main() {
     cd "$ROOT"
     "$ROOT/script/frontend-test"
-    "$ROOT/script/frontend-lint"
     "$ROOT/script/frontend-fmt-check"
 }
 

script/frontend-fmt

@@ -1,7 +1,7 @@
 #!/bin/sh
 # script/frontend-fmt: format the frontend and every other file prettier
-# understands, repo-wide (writes). backend/ is in .prettierignore; Go
+# understands, repo-wide (writes), the markdown in backend/ included.
-# sources are formatted by backend/script/fmt.
+# Prettier does not read Go; backend/script/fmt formats the Go sources.
 set -eu
 
 ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"

script/frontend-lint

@@ -1,12 +1,15 @@
 #!/bin/sh
-# script/frontend-lint: run the frontend linter (prettier in check mode).
+# script/frontend-lint: run eslint over the frontend. This runs inside
+# the frontend-lint stage of Dockerfile, the digest-pinned node image
+# with the packages from yarn.lock. From a checkout, run `make lint`,
+# which builds that stage.
 set -eu
 
 ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
 
 main() {
     cd "$ROOT"
-    yarn prettier --check .
+    yarn eslint .
 }
 
 main "$@"

script/frontend-test

@@ -1,14 +1,22 @@
 #!/bin/sh
 # script/frontend-test: run the frontend test suite: the unit tests in
-# test/unit/ with Node's built-in test runner, then the production
+# test/unit/, through the test script in package.json, then the
-# build, which fails on broken code.
+# production build, which fails on broken code. The tests print a dot
+# each; if any fails, they run again with every test listed, and the
+# script fails even if that run passes. NODE_OPTIONS chooses the
+# reporter because yarn adds its arguments after the test files, where
+# node would take a reporter option for one more file.
 set -eu
 
 ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
 
 main() {
     cd "$ROOT"
-    timeout 30 node --test test/unit/*.test.js
+    NODE_OPTIONS=--test-reporter=dot timeout 30 yarn --silent run test || {
+        echo "--- Rerunning with every test listed for details ---"
+        NODE_OPTIONS=--test-reporter=spec timeout 30 yarn --silent run test
+        exit 1
+    }
     timeout 30 yarn build
 }
 

script/install-precommit

@@ -8,8 +8,8 @@ ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
 main() {
     cd "$ROOT"
     hook=".git/hooks/pre-commit"
-    printf '#!/bin/sh\nset -e\nscript/precommit\n' > "$hook"
+    printf '#!/bin/sh\nset -e\nscript/precommit\n' > .git/hooks/pre-commit
-    chmod +x "$hook"
+    chmod +x .git/hooks/pre-commit
     echo "pre-commit hook installed: runs script/precommit"
 }
 

script/lint

@@ -1,19 +1,21 @@
 #!/bin/sh
-# script/lint: lint the whole repo: prettier over the frontend, then the
+# script/lint: lint the whole repo: eslint over the frontend, then the Go
-# Go linter over backend/.
+# linter over backend/.
 #
-# The Go linter runs only in Docker: this builds the lint stage of
+# No linter runs on the host: this builds the frontend-lint and lint
-# Dockerfile, the digest-pinned golangci-lint image, which runs the
+# stages of Dockerfile, the digest-pinned node and golangci-lint images.
-# backend's fmt-check and lint targets. --no-cache makes the linter
+# The first runs eslint; the second runs the backend's fmt-check and
-# really run every time rather than reuse an earlier result, and the
+# lint targets. --no-cache makes each linter really run every time
-# stage is built for its checks alone, so no image is kept.
+# rather than reuse an earlier result, and each stage is built for its
+# checks alone, so no image is kept.
 set -eu
 
 ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
 
 main() {
     cd "$ROOT"
-    "$ROOT/script/frontend-lint"
+    timeout 300 docker build --no-cache --target frontend-lint \
+        --output type=cacheonly .
     timeout 300 docker build --no-cache --target lint \
         --output type=cacheonly .
 }

script/test

@@ -1,14 +1,17 @@
 #!/bin/sh
 # script/test: run the test suite for the whole repo: the frontend at
-# the repo root, then the Go backend in backend/. Both halves together
+# the repo root, then the Go backend in backend/. Each half has its own
-# get 30 seconds; each also keeps its own limit for the Dockerfiles.
+# 30-second limit, and there is none around both: from a cold Go build
+# cache, compiling the backend's tests with the race detector can take
+# 30 seconds on its own, and Go's -timeout leaves the compile out.
 set -eu
 
 ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
 
 main() {
     cd "$ROOT"
-    timeout 30 sh -c 'script/frontend-test && backend/script/test'
+    script/frontend-test
+    backend/script/test
 }
 
 main "$@"

script/tidy

@@ -0,0 +1,13 @@
+#!/bin/sh
+# script/tidy: run go mod tidy in backend/, which adds the modules the
+# Go sources import, drops those they no longer do, and updates go.sum.
+set -eu
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
+
+main() {
+    cd "$ROOT/backend"
+    go mod tidy
+}
+
+main "$@"

src/main.js

@@ -151,7 +151,7 @@ function formatUTCTimestamp(date) {
 
 // --- Duration Formatting -----------------------------------------------------
 
-function humanDuration(seconds) {
+export function humanDuration(seconds) {
     const h = Math.floor(seconds / 3600);
     const m = Math.floor((seconds % 3600) / 60);
     const s = seconds % 60;
@@ -197,7 +197,7 @@ async function detectGateway() {
 
 // --- App State ---------------------------------------------------------------
 
-class HostState {
+export class HostState {
     constructor(host, pinned = false) {
         this.name = host.name;
         this.url = host.url;
@@ -263,7 +263,7 @@ class HostState {
     }
 }
 
-class AppState {
+export class AppState {
     constructor(localHosts) {
         this.wan = WAN_HOSTS.map(
             (h) => new HostState(h, h.name === "datavi.be"),
@@ -546,7 +546,7 @@ export async function measureLatency(url, signal) {
 
 // --- Color Helpers -----------------------------------------------------------
 
-function latencyHex(latency) {
+export function latencyHex(latency) {
     if (latency === null) return "#6b7280";
     if (latency < 50) return "#22c55e";
     if (latency < 100) return "#84cc16";
@@ -555,7 +555,7 @@ function latencyHex(latency) {
     return "#ef4444";
 }
 
-function latencyClass(latency, status) {
+export function latencyClass(latency, status) {
     if (status === "offline" || status === "error" || latency === null)
         return "text-gray-500";
     if (latency < 50) return "text-green-500";
@@ -1105,7 +1105,7 @@ function sortAndRebuildWAN(state) {
 
 // --- Main Loop ---------------------------------------------------------------
 
-async function tick(state, signal, onOffline) {
+export async function tick(state, signal, onOffline) {
     const ts = Date.now();
 
     if (state.paused) {
@@ -1126,12 +1126,26 @@ async function tick(state, signal, onOffline) {
 
     log.debug(`Tick #${state.tickCount + 1} started`);
 
-    const results = await Promise.all(
+    // Each host's row shows its result as soon as its check ends. The
-        state.allHosts.map((h) => measureLatency(h.url, signal)),
+    // result is discarded if by then the user has paused or the next round
+    // has given up this one's checks, and in the first tick (tickCount is
+    // still 0), which is discarded as a whole below. The row is looked up
+    // when the check ends, as a pin click may have re-sorted the rows since
+    // the round started.
+    await Promise.all(
+        state.allHosts.map(async (host) => {
+            const r = await measureLatency(host.url, signal);
+            if (state.paused || signal.aborted || state.tickCount === 0) {
+                return;
+            }
+            host.pushSample(ts, r);
+            updateHostRow(host, state.allHosts.indexOf(host));
+            log.debug(`${host.name}: ${r.error ? r.error : r.latency + "ms"}`);
+        }),
     );
 
     // User may have paused, or the next round may have given up this
-    // one's checks, while awaiting results — discard them
+    // one's checks, while awaiting results — skip the rest of the round
     if (state.paused || signal.aborted) return;
 
     state.tickCount++;
@@ -1142,12 +1156,9 @@ async function tick(state, signal, onOffline) {
         return;
     }
 
-    state.allHosts.forEach((host, i) => {
+    // Redraw every row: if the user paused and resumed during this round,
-        const r = results[i];
+    // rows whose check ended before the resume still read "paused"
-        host.pushSample(ts, r);
+    state.allHosts.forEach((host, i) => updateHostRow(host, i));
-        updateHostRow(host, i);
-        log.debug(`${host.name}: ${r.error ? r.error : r.latency + "ms"}`);
-    });
 
     // Sort after the first real check, then every 10 ticks thereafter
     if (state.tickCount === 2 || state.tickCount % 10 === 1) {
@@ -1213,7 +1224,7 @@ function stopRecoveryProbe(state) {
 
 // --- Pause / Resume ----------------------------------------------------------
 
-function greyOutUI(state) {
+export function greyOutUI(state) {
     // Grey out all host rows
     state.allHosts.forEach((host, i) => {
         const latencyEl = document.querySelector(
@@ -1385,10 +1396,10 @@ async function init() {
     setInterval(updateClocks, 1000);
 
     // Rounds never overlap: a round first gives up the last round's checks
-    // if they are still waiting, and the last round then records nothing.
+    // if they are still waiting, and the last round then records nothing
-    // At a steady interval they never are, as they time out at 80% of it;
+    // more. At a steady interval they never are, as they time out at 80% of
-    // they can be when a round starts early, after an interval change or
+    // it; they can be when a round starts early, after an interval change
-    // when the recovery probe finds a target answering.
+    // or when the recovery probe finds a target answering.
     let roundChecks = new AbortController();
     function doTick() {
         roundChecks.abort();

test/unit/main.test.js

@@ -1,19 +1,75 @@
-// Unit tests for src/main.js, run by script/frontend-test with Node's
+// Unit tests for src/main.js, run with Node's built-in test runner by the
-// built-in test runner. Importing the module does not start the page.
+// test script in package.json. Importing the module does not start the
+// page.
 
-import { test } from "node:test";
+import { beforeEach, test } from "node:test";
 import assert from "node:assert/strict";
-import { CONFIG, measureLatency } from "../../src/main.js";
+import {
+    AppState,
+    CONFIG,
+    greyOutUI,
+    HostState,
+    humanDuration,
+    latencyClass,
+    latencyHex,
+    measureLatency,
+    tick,
+} from "../../src/main.js";
 
-// measureLatency writes timeouts to the debug log, which looks for its
+// There is no page here, so the tests stand in for it. The debug log looks
-// panel in the page. There is no page here.
+// for its panel by id and finds none. Each element of a host's row that
-globalThis.document = { getElementById: () => null };
+// tick or greyOutUI draws into is a plain object, made the first time a
+// test looks it up and kept in elements under its selector until the next
+// test starts. As on a page, writing its text replaces its markup; the
+// status dot greyOutUI looks for in it is not there. Drawing a sparkline
+// does nothing; it looks for the pixel ratio on window and finds none.
+let elements;
+beforeEach(() => {
+    elements = {};
+});
+const doNothing = () => {};
+const canvasContext = {
+    clearRect: doNothing,
+    beginPath: doNothing,
+    moveTo: doNothing,
+    lineTo: doNothing,
+    stroke: doNothing,
+    fill: doNothing,
+    fillRect: doNothing,
+    fillText: doNothing,
+    arc: doNothing,
+};
+globalThis.window = {};
+globalThis.document = {
+    getElementById: () => null,
+    querySelector: (selector) =>
+        (elements[selector] ??= {
+            getContext: () => canvasContext,
+            querySelector: () => null,
+            set textContent(text) {
+                this.innerHTML = text;
+            },
+        }),
+};
+
+// What tick last wrote into the latency figure in host's row, or undefined
+// if it has written nothing there.
+function latencyFigure(state, host) {
+    const index = state.allHosts.indexOf(host);
+    return elements[`.latency-value[data-host="${index}"]`]?.innerHTML;
+}
+
+// What was last written into the status text in host's row.
+function statusText(state, host) {
+    const index = state.allHosts.indexOf(host);
+    return elements[`.status-text[data-host="${index}"]`]?.innerHTML;
+}
 
 // Mocks the clock for test t, so that a check lasting seconds takes no real
-// time, and replaces fetch with a target that answers after answerAfter
+// time, and replaces fetch with targets that each answer after
-// milliseconds of that clock, or never when answerAfter is Infinity. Both
+// answerAfter(url) milliseconds of that clock, or never when that is
-// are restored when the test ends.
+// Infinity. Both are restored when the test ends.
-function mockTarget(t, answerAfter) {
+function mockTargets(t, answerAfter) {
     t.mock.timers.enable({ apis: ["setTimeout", "Date"] });
     t.mock.method(performance, "now", () => Date.now());
     t.mock.method(
@@ -21,7 +77,9 @@ function mockTarget(t, answerAfter) {
         "fetch",
         (url, { signal }) =>
             new Promise((resolve, reject) => {
-                if (answerAfter !== Infinity) setTimeout(resolve, answerAfter);
+                if (answerAfter(url) !== Infinity) {
+                    setTimeout(resolve, answerAfter(url));
+                }
                 signal.addEventListener("abort", () => reject(signal.reason));
             }),
     );
@@ -42,7 +100,7 @@ for (const interval of [10000, 30000]) {
 
     test(`at a ${interval}ms interval, an answer after ${slowAnswer}ms is recorded with its real time`, async (t) => {
         CONFIG.updateInterval = interval;
-        mockTarget(t, slowAnswer);
+        mockTargets(t, () => slowAnswer);
         const check = measureLatency("https://target.test");
         t.mock.timers.tick(slowAnswer);
         assert.deepEqual(await settled(check), {
@@ -53,7 +111,7 @@ for (const interval of [10000, 30000]) {
 
     test(`at a ${interval}ms interval, a target that never answers is recorded as a timeout after ${timeout}ms`, async (t) => {
         CONFIG.updateInterval = interval;
-        mockTarget(t, Infinity);
+        mockTargets(t, () => Infinity);
         const check = measureLatency("https://target.test");
         t.mock.timers.tick(timeout - 1);
         assert.equal(await settled(check), "still waiting");
@@ -64,3 +122,268 @@ for (const interval of [10000, 30000]) {
         });
     });
 }
+
+test("at a 30000ms interval, a target answering after 1000ms shows in its row while another target's check is still waiting", async (t) => {
+    CONFIG.updateInterval = 30000;
+    const state = new AppState([
+        { name: "Answering", url: "https://answering.test" },
+    ]);
+    const answering = state.local[0];
+    const waiting = state.wan[0];
+    // No target but the answering one ever answers.
+    mockTargets(t, (url) => (url.startsWith(answering.url) ? 1000 : Infinity));
+    // The third tick: the first is discarded as a whole, and the second ends
+    // by sorting the rows, which rebuilds a page that is not here.
+    state.tickCount = 2;
+
+    const round = tick(state, new AbortController().signal);
+    t.mock.timers.tick(1000);
+    assert.equal(await settled(round), "still waiting");
+    assert.match(latencyFigure(state, answering), />1000</);
+    assert.equal(latencyFigure(state, waiting), undefined);
+    assert.equal(state.tickCount, 2);
+
+    // The round ends, once, when the last check times out.
+    t.mock.timers.tick(CONFIG.requestTimeout - 1000);
+    assert.notEqual(await settled(round), "still waiting");
+    assert.equal(state.tickCount, 3);
+});
+
+// In the next three tests, the answering target's check is still waiting
+// when something happens after which its result must not show.
+
+test("at a 30000ms interval, a check still waiting when its round is given up does not show in its row", async (t) => {
+    CONFIG.updateInterval = 30000;
+    const state = new AppState([
+        { name: "Answering", url: "https://answering.test" },
+    ]);
+    const answering = state.local[0];
+    mockTargets(t, (url) => (url.startsWith(answering.url) ? 1000 : Infinity));
+    state.tickCount = 2;
+
+    const roundChecks = new AbortController();
+    const round = tick(state, roundChecks.signal);
+    t.mock.timers.tick(500);
+    // As a round started early does to the last round's checks.
+    roundChecks.abort();
+    assert.notEqual(await settled(round), "still waiting");
+    assert.equal(latencyFigure(state, answering), undefined);
+});
+
+test("at a 30000ms interval, a check still waiting when the user pauses does not show in its row", async (t) => {
+    CONFIG.updateInterval = 30000;
+    const state = new AppState([
+        { name: "Answering", url: "https://answering.test" },
+    ]);
+    const answering = state.local[0];
+    mockTargets(t, (url) => (url.startsWith(answering.url) ? 1000 : Infinity));
+    state.tickCount = 2;
+
+    const round = tick(state, new AbortController().signal);
+    t.mock.timers.tick(500);
+    state.paused = true;
+    t.mock.timers.tick(500);
+    assert.equal(await settled(round), "still waiting");
+    assert.equal(latencyFigure(state, answering), undefined);
+});
+
+test("at a 30000ms interval, a check in the first round does not show in its row", async (t) => {
+    CONFIG.updateInterval = 30000;
+    const state = new AppState([
+        { name: "Answering", url: "https://answering.test" },
+    ]);
+    const answering = state.local[0];
+    mockTargets(t, (url) => (url.startsWith(answering.url) ? 1000 : Infinity));
+
+    const round = tick(state, new AbortController().signal);
+    t.mock.timers.tick(1000);
+    assert.equal(await settled(round), "still waiting");
+    assert.equal(latencyFigure(state, answering), undefined);
+});
+
+test("at a 30000ms interval, after the user pauses and resumes during a round, no row reads paused once its last check ends", async (t) => {
+    CONFIG.updateInterval = 30000;
+    const state = new AppState([
+        { name: "Answering", url: "https://answering.test" },
+    ]);
+    const answering = state.local[0];
+    mockTargets(t, (url) => (url.startsWith(answering.url) ? 1000 : Infinity));
+    state.tickCount = 2;
+
+    const round = tick(state, new AbortController().signal);
+    t.mock.timers.tick(1000);
+    assert.equal(await settled(round), "still waiting");
+    // The user pauses, which greys out every row, and resumes, which leaves
+    // the rows as they are, as togglePause does. The answering target's
+    // check has already ended, so only the redraw of every row at the end
+    // of the round can take "paused" out of its row.
+    state.paused = true;
+    greyOutUI(state);
+    state.paused = false;
+    assert.equal(statusText(state, answering), "paused");
+
+    // The round ends when the last check times out.
+    t.mock.timers.tick(CONFIG.requestTimeout - 1000);
+    assert.notEqual(await settled(round), "still waiting");
+    for (const host of state.allHosts) {
+        assert.notEqual(statusText(state, host), "paused", host.name);
+    }
+});
+
+for (const [seconds, text] of [
+    [0, "0s"],
+    [1, "1s"],
+    [59, "59s"],
+    [60, "1m"],
+    [61, "1m1s"],
+    [3599, "59m59s"],
+    [3600, "1h"],
+    [3601, "1h1s"],
+    [3660, "1h1m"],
+    [3661, "1h1m1s"],
+]) {
+    test(`humanDuration writes ${seconds} seconds as ${text}`, () => {
+        assert.equal(humanDuration(seconds), text);
+    });
+}
+
+// The colour of a target's latency figure, as a class, and of its sparkline
+// for an answer after latency ms, as the colour coding in README.md gives
+// them. The rows sit either side of each boundary.
+for (const [latency, figure, sparkline] of [
+    [0, "text-green-500", "#22c55e"],
+    [49, "text-green-500", "#22c55e"],
+    [50, "text-lime-500", "#84cc16"],
+    [99, "text-lime-500", "#84cc16"],
+    [100, "text-yellow-500", "#eab308"],
+    [199, "text-yellow-500", "#eab308"],
+    [200, "text-orange-500", "#f97316"],
+    [499, "text-orange-500", "#f97316"],
+    [500, "text-red-500", "#ef4444"],
+]) {
+    test(`an answer after ${latency}ms has a ${figure} figure and a ${sparkline} sparkline`, () => {
+        assert.equal(latencyClass(latency, "online"), figure);
+        assert.equal(latencyHex(latency), sparkline);
+    });
+}
+
+test("a check that timed out or found its target unreachable has a grey figure and sparkline", () => {
+    assert.equal(latencyClass(null, "error"), "text-gray-500");
+    assert.equal(latencyClass(null, "offline"), "text-gray-500");
+    assert.equal(latencyHex(null), "#6b7280");
+});
+
+// A target whose checks, in turn, answered after each of latencies ms, or,
+// for null, found it unreachable.
+function hostAfter(latencies) {
+    const host = new HostState({ name: "Target", url: "https://target.test" });
+    for (const latency of latencies) {
+        host.pushSample(
+            Date.now(),
+            latency === null
+                ? { latency: null, error: "unreachable" }
+                : { latency, error: null },
+        );
+    }
+    return host;
+}
+
+for (const { history, latencies, statistics } of [
+    {
+        history: "no checks",
+        latencies: [],
+        statistics: { min: null, max: null, average: null, median: null },
+    },
+    {
+        history: "only unreachable checks",
+        latencies: [null, null, null],
+        statistics: { min: null, max: null, average: null, median: null },
+    },
+    {
+        history: "three answers and an unreachable check",
+        latencies: [30, null, 10, 20],
+        statistics: { min: 10, max: 30, average: 20, median: 20 },
+    },
+    {
+        // The median of an even number of answers is the mean of the
+        // middle two. It and the average, 23.75, are rounded.
+        history: "four answers",
+        latencies: [10, 40, 20, 25],
+        statistics: { min: 10, max: 40, average: 24, median: 23 },
+    },
+    {
+        // Sorted as text rather than as numbers, these answers would put
+        // 100 in the middle. The average, 39.67, is rounded.
+        history: "answers with different numbers of digits",
+        latencies: [100, 9, 10],
+        statistics: { min: 9, max: 100, average: 40, median: 10 },
+    },
+]) {
+    test(`a target's min, max, average and median latency over ${history}`, () => {
+        const host = hostAfter(latencies);
+        assert.deepEqual(
+            {
+                min: host.minLatency(),
+                max: host.maxLatency(),
+                average: host.averageLatency(),
+                median: host.medianLatency(),
+            },
+            statistics,
+        );
+    });
+}
+
+// An app state in which, of the WAN targets, the first timedOut timed out,
+// the next unreachable were found unreachable, the next answered answered
+// after latency ms, and the rest have not been checked yet.
+function stateAfter({ timedOut, unreachable, answered, latency }) {
+    const state = new AppState([]);
+    const results = [
+        ...Array(timedOut).fill({ latency: null, error: "timeout" }),
+        ...Array(unreachable).fill({ latency: null, error: "unreachable" }),
+        ...Array(answered).fill({ latency, error: null }),
+    ];
+    results.forEach((result, i) => state.wan[i].pushSample(Date.now(), result));
+    return state;
+}
+
+// For each number the health is decided by, the rows put it one under, at
+// and one over its threshold.
+for (const { timedOut, unreachable = 0, answered, latency, health } of [
+    // Offline: more than 10 timed out and at most 4 answered.
+    { timedOut: 9, answered: 4, latency: 30, health: "degraded" },
+    { timedOut: 10, answered: 4, latency: 30, health: "degraded" },
+    { timedOut: 11, answered: 4, latency: 30, health: "offline" },
+    { timedOut: 11, answered: 3, latency: 30, health: "offline" },
+    { timedOut: 11, answered: 5, latency: 30, health: "degraded" },
+    // Otherwise degraded: more than 4 timed out.
+    { timedOut: 3, answered: 10, latency: 30, health: "healthy" },
+    { timedOut: 4, answered: 10, latency: 30, health: "healthy" },
+    { timedOut: 5, answered: 10, latency: 30, health: "degraded" },
+    // Otherwise slow: more than 3 answered after more than 1000ms.
+    { timedOut: 0, answered: 4, latency: 999, health: "healthy" },
+    { timedOut: 0, answered: 4, latency: 1000, health: "healthy" },
+    { timedOut: 0, answered: 4, latency: 1001, health: "slow" },
+    { timedOut: 0, answered: 2, latency: 1001, health: "healthy" },
+    { timedOut: 0, answered: 3, latency: 1001, health: "healthy" },
+    // A target found unreachable counts as one that timed out.
+    {
+        timedOut: 5,
+        unreachable: 6,
+        answered: 4,
+        latency: 30,
+        health: "offline",
+    },
+    {
+        timedOut: 0,
+        unreachable: 5,
+        answered: 10,
+        latency: 30,
+        health: "degraded",
+    },
+]) {
+    test(`with ${timedOut} WAN targets timed out, ${unreachable} found unreachable and ${answered} answering after ${latency}ms, the health is ${health}`, () => {
+        const state = stateAfter({ timedOut, unreachable, answered, latency });
+        assert.equal(state.healthStatus(), health);
+    });
+}

test/viewport/README.md

@@ -49,10 +49,11 @@ sizes straddling the breakpoint for the rotation case.
   excluded: it is a design choice, not breakage.
 - **tap-targets-44px** — every interactive control is at least 44x44 CSS px on
   touch viewports, _and_ each selector in the control list matched at least the
-  number of visible elements it declares. The second half is what stops the
+  number of visible elements it declares: one of each single control, and one
-  check passing vacuously: with size alone, a renamed class would take its
+  pin button per WAN host row. The second half is what stops the check passing
-  controls out of the measured set and the check would report "all 0 controls
+  vacuously: with size alone, a renamed class would take its controls out of the
-  are at least 44x44" and pass. See below.
+  measured set and the check would report "all 0 controls are at least 44x44"
+  and pass. See below.
 - **host-rows-stacked / host-rows-side-by-side** — the rows genuinely reflow.
   Computed `flex-direction` _and_ the actual geometry are checked, and in the
   narrow layout the info block and the sparkline must each occupy essentially

test/viewport/checks.js

@@ -15,7 +15,8 @@ export const MIN_TAP_TARGET_PX = 44;
 
 // The controls named in the definition of done, plus the pause button.
 // Each carries the smallest number of *visible* instances the page has to
-// contain for the tap-target oracle to be measuring anything at all.
+// contain, worked out from the facts gathered from that page, for the
+// tap-target oracle to be measuring every control it should.
 //
 // Without those floors the check is inert: `undersized` is empty both when
 // every control is large enough and when the selectors have gone stale and
@@ -24,13 +25,12 @@ export const MIN_TAP_TARGET_PX = 44;
 // for all three singleton controls vanishing at once — so the floor is per
 // selector, and one stale selector out of four fails the check.
 export const INTERACTIVE_CONTROLS = [
-    { selector: "#pause-btn", minCount: 1 },
+    { selector: "#pause-btn", minCount: () => 1 },
-    { selector: "#interval-select", minCount: 1 },
+    { selector: "#interval-select", minCount: () => 1 },
-    // One per pinnable host row. `app-rendered` already requires at least
+    // One per WAN host row, so pin buttons missing from even one row fail
-    // 10 host rows, so a count below that means the pin buttons stopped
+    // the check rather than only a drop below some fixed number.
-    // being rendered per row rather than that there were fewer hosts.
+    { selector: ".pin-btn", minCount: (facts) => facts.wanRowCount },
-    { selector: ".pin-btn", minCount: 10 },
+    { selector: "#debug-toggle", minCount: () => 1 },
-    { selector: "#debug-toggle", minCount: 1 },
 ];
 
 export const INTERACTIVE_SELECTORS = INTERACTIVE_CONTROLS.map(
@@ -105,8 +105,8 @@ export function evaluateChecks(facts, viewport, probes) {
     // never rendered. Everything below is only meaningful if this holds.
     check(
         "app-rendered",
-        facts.rowCount >= 10 && facts.numericLatencies >= 5,
+        facts.wanRowCount >= 10 && facts.numericLatencies >= 5,
-        `${facts.rowCount} host rows, ${facts.numericLatencies} showing a numeric latency`,
+        `${facts.wanRowCount} WAN host rows, ${facts.numericLatencies} showing a numeric latency`,
     );
 
     const viewportWidth = Math.min(facts.innerWidth, facts.documentClientWidth);
@@ -162,7 +162,8 @@ export function evaluateChecks(facts, viewport, probes) {
             seen.set(target.selector, (seen.get(target.selector) ?? 0) + 1);
         }
         const missing = INTERACTIVE_CONTROLS.filter(
-            (control) => (seen.get(control.selector) ?? 0) < control.minCount,
+            (control) =>
+                (seen.get(control.selector) ?? 0) < control.minCount(facts),
         );
 
         const undersized = facts.tapTargets.filter(
@@ -184,11 +185,11 @@ export function evaluateChecks(facts, viewport, probes) {
         const detail = [];
         if (missing.length > 0) {
             detail.push(
-                "oracle is not measuring the page: " +
+                "oracle is not measuring every control: " +
                     summarise(
                         missing,
                         (c) =>
-                            `${c.selector} matched ${seen.get(c.selector) ?? 0} visible element(s), expected at least ${c.minCount}`,
+                            `${c.selector} matched ${seen.get(c.selector) ?? 0} visible element(s), expected at least ${c.minCount(facts)}`,
                         4,
                     ),
             );

test/viewport/facts.js

@@ -173,7 +173,9 @@ export function collectLayoutFacts(options) {
         clipped,
         tapTargets,
         rows,
-        rowCount: document.querySelectorAll(".host-row").length,
+        // WAN host rows only: each has a pin button, and the tap-target
+        // check expects one per row. The local host rows have none.
+        wanRowCount: document.querySelectorAll("#wan-hosts .host-row").length,
         numericLatencies: Array.from(
             document.querySelectorAll(".latency-value"),
         ).filter((el) => /\d/.test(el.textContent)).length,

test/viewport/harness.js

@@ -16,6 +16,10 @@ import { collectLayoutFacts } from "./facts.js";
 import { evaluateChecks, INTERACTIVE_SELECTORS } from "./checks.js";
 import { deriveViewports } from "./viewports.js";
 
+// page.waitForFunction and page.evaluate run the functions given them in
+// the page, where these are defined.
+/* global document, requestAnimationFrame */
+
 function required(name) {
     const value = process.env[name];
     if (!value) {
@@ -62,7 +66,6 @@ function stableHash(text) {
 
 async function connectBrowser() {
     const deadline = Date.now() + BROWSER_TIMEOUT_MS;
-    let lastError;
     for (;;) {
         try {
             const response = await fetch(`${CDP_URL}/json/version`);
@@ -77,9 +80,10 @@ async function connectBrowser() {
             });
             return { browser, version: info.Browser };
         } catch (error) {
-            lastError = error;
             if (Date.now() > deadline) {
-                throw new Error(`browser never came up: ${lastError}`);
+                throw new Error(`browser never came up: ${error}`, {
+                    cause: error,
+                });
             }
             await sleep(250);
         }