server.go starts listenAndServe in an anonymous function (closes #162)

The server's OnStart hook started the HTTP listener with
`go s.listenAndServe()`; the Go style guide asks for a function called
with `go` to be wrapped in an anonymous function, so it is now
`go func() { s.listenAndServe() }()`. No other go statement in the Go
code called a function directly. Nothing the server does changed.

Model: opus-5-5

.dockerignore

@@ -72,10 +72,13 @@
 **/*.sublime-*
 
 # This repository's own entries, after the shared content above: the
-# frontend build, the viewport test's output, what `make build` and
-# `make run` in backend/ leave behind, and log files at the root.
+# frontend build, the viewport test's output, the binary `make build`
+# writes and the reports `make run` stores, and Go test binaries,
+# coverage output and log files at the root.
 /dist
 /tmp
-/backend/netwatch-server
-/backend/data
+/netwatch-server
+/data
+/*.test
+/*.out
 /*.log

.editorconfig

@@ -11,7 +11,8 @@ insert_final_newline = true
 [Makefile]
 indent_style = tab
 
-# This repository's own entries, after the shared content above.
-
 [*.go]
 indent_style = tab
+
+# This repository's own sections, such as one for another language it
+# uses, go below this comment, and a re-vendor keeps them.

.gitea/workflows/check.yml

@@ -1,9 +1,20 @@
 name: check
 on: [push]
+# Free the shared runner: a new push cancels only the same branch's older run.
+concurrency:
+    group: ${{ github.workflow }}-${{ github.ref }}
+    cancel-in-progress: true
 jobs:
     check:
         runs-on: ubuntu-latest
+        # Free the shared runner from a hung build.
+        timeout-minutes: 20
         steps:
             # actions/checkout v4.2.2, 2026-02-22
             - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683
+              # script/cibuild needs no token, so none is left in .git/config.
+              with:
+                  persist-credentials: false
+                  # All history and tags, so git describe finds the version tag.
+                  fetch-depth: 0
             - run: script/cibuild

.gitignore

@@ -27,7 +27,7 @@ node_modules/
 # Environment files. `*.env` covers bare `.env` and the `prod.env`
 # convention. Only the templates `example.env` and `sample.env` are
 # re-included below. A repository that commits any other template adds
-# its own negation after these lines, for example `!.env.example`.
+# its own negation at the end of this file, for example `!.env.example`.
 *.[eE][nN][vV]
 .[eE][nN][vV].*
 .[eE][nN][vV][rR][cC]
@@ -46,12 +46,17 @@ node_modules/
 [iI][dD]_[eE][dD]25519
 [iI][dD]_[eE][dD]25519_[sS][kK]
 
-# This repository's own entries, after the shared content above.
+# This repository's own entries, such as its build outputs, go below
+# this comment, and a re-vendor keeps them. Anchor a binary built at the
+# root: `/myapp`, never `myapp`, which also ignores `cmd/myapp/`.
 
 # Build output
 dist/
 tmp/
-/backend/netwatch-server
+/netwatch-server
+
+# The reports make run stores, in netwatch-server's default DATA_DIR
+/data/
 
 # Go test binaries and coverage output
 *.test

.golangci.yml

@@ -25,6 +25,8 @@ linters:
     # silenced by disabling that name, not by enabling the successor.
     - wsl              # Deprecated, replaced by wsl_v5
     - gomodguard       # Deprecated, replaced by gomodguard_v2
+    # Misses findings at random in v2.14.0; back once a pinned release fixes it
+    - canonicalheader
   settings:
     lll:
       line-length: 88

Dockerfile

@@ -5,98 +5,125 @@
 #
 # The lint and test phases are the gates: `make lint` (script/lint)
 # builds the lint stage alone and `make test` (script/test) the test
-# stage alone, and the builder stage depends on both, so the image
-# cannot be built unless they pass. Each covers the frontend as well,
-# through a copy from a node stage. Inside them each tool is invoked
-# directly, never through make or script/, whose lint and test are
-# themselves docker builds.
+# stage alone, and the two build stages, frontend-build and builder,
+# depend on both, so the image cannot be built unless they pass. Each
+# phase covers the frontend as well, through a copy from a node stage.
+# Inside them each tool is invoked directly, never through make or
+# script/, whose lint and test are themselves docker builds.
+#
+# In every stage ARG CACHEBUST comes right after the steps that install
+# system packages and download Go's modules, or right after FROM in a
+# stage with neither, and every step that lints, tests or compiles
+# comes after it, as does yarn install in the node stages. script/
+# passes a new value on every build, which reruns every RUN step after
+# it. Docker keeps the layers above it until the base image, their own
+# lines or go.mod and go.sum change. The steps that compile mount Go's
+# build cache, and golangci-lint run also mounts golangci-lint's; both
+# survive from build to build.
 
 # Frontend lint stage: eslint with the rules in eslint.config.js. The
 # lint phase below runs it.
 # node:22-alpine as of 2026-02-22
 FROM node@sha256:e4bf2a82ad0a4037d28035ae71529873c069b13eb0455466ae0bc13363826e34 AS frontend-lint
+ARG CACHEBUST
 WORKDIR /app
 COPY package.json yarn.lock ./
 RUN yarn install --frozen-lockfile
 COPY . .
 RUN yarn eslint .
 
-# Lint phase: golangci-lint over the backend with backend/.golangci.yml,
+# Lint phase: golangci-lint over the Go packages with .golangci.yml,
 # and eslint through the copy from frontend-lint at the end. The
 # golangci/golangci-lint image ships Go and the linter.
 # golangci/golangci-lint:v2.14.0, 2026-09-24
 FROM golangci/golangci-lint@sha256:ad862ba6b3798cbe0fd9fd7408d498fd74fbd2623a92406b2fd3898faf0bf98f AS lint
 WORKDIR /src
-COPY backend/go.mod backend/go.sum ./
+COPY go.mod go.sum ./
 RUN go mod download
-COPY backend/ .
-RUN golangci-lint run --config .golangci.yml ./...
+ARG CACHEBUST
+COPY . .
+RUN --mount=type=cache,target=/root/.cache/go-build \
+    --mount=type=cache,target=/root/.cache/golangci-lint \
+    golangci-lint run --config .golangci.yml ./...
 # Nothing is wanted from frontend-lint; the copy is what makes this
 # phase run it.
 COPY --from=frontend-lint /app/yarn.lock /dev/null
 
-# Frontend stage: the unit tests in test/unit/, then the production
-# build into dist/, which the runtime stage serves. The test phase below
-# runs it. The tests print a dot each; if any fails, they run again with
-# every test listed, and the step 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.
+# Frontend test stage: the unit tests in test/unit/. The test phase
+# below runs it, and the frontend-build stage starts from it. The tests
+# print a dot each; if any fails, they run again with every test listed,
+# and the step 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.
 # node:22-alpine as of 2026-02-22
-FROM node@sha256:e4bf2a82ad0a4037d28035ae71529873c069b13eb0455466ae0bc13363826e34 AS frontend
+FROM node@sha256:e4bf2a82ad0a4037d28035ae71529873c069b13eb0455466ae0bc13363826e34 AS frontend-test
+ARG CACHEBUST
 WORKDIR /app
 COPY package.json yarn.lock ./
 RUN yarn install --frozen-lockfile
-# vite.config.js reads the commit for the page's footer with git.
-RUN apk add --no-cache git
 COPY . .
 RUN NODE_OPTIONS=--test-reporter=dot timeout 90 yarn --silent run test || \
     { echo "--- Rerunning with every test listed for details ---"; \
       NODE_OPTIONS=--test-reporter=spec timeout 90 yarn --silent run test; \
       exit 1; }
-RUN yarn build
 
 # Test phase: the backend's tests with the race detector and coverage,
-# and the frontend's through the copy from the frontend stage at the
-# end. -race needs cgo and so a C compiler, which the Debian Go image
+# and the frontend's through the copy from the frontend-test stage at
+# the end. -race needs cgo and so a C compiler, which the Debian Go image
 # ships and the alpine one does not. -timeout 90s is a backstop above
 # the 60-second cap on the suite. The rerun with -v only shows details:
 # the step fails however it ends, because the first run already failed.
-# Go's module and build caches are in memory (tmpfs) for the go test
-# step alone, so the image make test tags does not carry them and the
-# build spends no time writing them into it. They start empty on every
-# build, so no stored test result can stand in for a run.
+# -count=1 because the mounted cache also holds test results, which go
+# test would otherwise replay.
 # golang:1.25.7-trixie, 2026-10-07
 FROM golang@sha256:2b174ffcf56c7ad0c47d30d2630693265639ddf2a5141149c2da34db921791b4 AS test
 WORKDIR /src
-COPY backend/ .
-RUN --mount=type=tmpfs,target=/go/pkg/mod \
-    --mount=type=tmpfs,target=/root/.cache/go-build \
-    go test -timeout 90s -race -cover ./... || \
+COPY go.mod go.sum ./
+RUN go mod download
+ARG CACHEBUST
+COPY . .
+RUN --mount=type=cache,target=/root/.cache/go-build \
+    go test -count=1 -timeout 90s -race -cover ./... || \
     { echo "--- Rerunning with -v for details ---"; \
-      go test -timeout 90s -race -v ./...; exit 1; }
-# Nothing is wanted from the frontend stage; the copy is what makes
+      go test -count=1 -timeout 90s -race -v ./...; exit 1; }
+# Nothing is wanted from the frontend-test stage; the copy is what makes
 # this phase run its tests.
-COPY --from=frontend /app/yarn.lock /dev/null
+COPY --from=frontend-test /app/yarn.lock /dev/null
 
-# Backend build stage. Nothing is wanted from the two phases; the copies
+# Frontend build stage: the production build into dist/, which the
+# runtime stage serves, on the yarn packages and source of the
+# frontend-test stage. Nothing is wanted from the two phases; the copies
 # are what make BuildKit build them first, so this stage cannot run
 # unless lint and test passed.
-# golang:1.25-alpine (2026-02-27)
-FROM golang@sha256:f6751d823c26342f9506c03797d2527668d095b0a15f1862cddb4d927a7a4ced AS builder
+FROM frontend-test AS frontend-build
 COPY --from=lint /src/go.sum /dev/null
 COPY --from=test /src/go.sum /dev/null
+# vite.config.js reads the commit for the page's footer with git. git is
+# installed again on every image build, although it comes above
+# ARG CACHEBUST, because this stage starts from frontend-test, whose
+# steps run again on every build.
 RUN apk add --no-cache git
+ARG CACHEBUST
+RUN yarn build
+
+# Backend build stage. Nothing is wanted from the two phases; the copies
+# are what make BuildKit build them first, so nothing after them can
+# run unless lint and test passed.
+# golang:1.25-alpine (2026-02-27)
+FROM golang@sha256:f6751d823c26342f9506c03797d2527668d095b0a15f1862cddb4d927a7a4ced AS builder
+RUN apk add --no-cache git
+WORKDIR /src
+COPY go.mod go.sum ./
+RUN go mod download
+ARG CACHEBUST
+COPY --from=lint /src/go.sum /dev/null
+COPY --from=test /src/go.sum /dev/null
 # A tar-stream context keeps the sender's file owners, which git refuses.
 RUN git config --system --add safe.directory /src
-WORKDIR /src
-COPY backend/go.mod backend/go.sum backend/
-RUN cd backend && go mod download
 COPY . .
 
-# backend/script/build is the one definition of the build command:
-# CGO_ENABLED=0 go build -trimpath -ldflags "-s -w -X main.Version=..."
-# It reads VERSION from the environment.
+# The same go build as in script/build, which builds the binary on the
+# host.
 #
 # The version is the VERSION build argument when one is given, otherwise
 # `git describe --tags --always` on the .git in the build context: the
@@ -105,19 +132,23 @@ COPY . .
 # still empty, dev or unknown fails the build: git is missing or could
 # not read the checkout.
 ARG VERSION
-RUN version="${VERSION:-$(git describe --tags --always)}"; \
+RUN --mount=type=cache,target=/root/.cache/go-build \
+    version="${VERSION:-$(git describe --tags --always)}"; \
     if [ -e .git ]; then \
         case "$version" in ""|dev|unknown) \
             echo "version is '$version' although .git is present" >&2; \
             exit 1 ;; \
         esac; \
     fi; \
-    VERSION="$version" backend/script/build
+    CGO_ENABLED=0 go build -trimpath \
+        -ldflags "-s -w -X main.Version=$version" \
+        -o netwatch-server ./cmd/netwatch-server/
 
 # Runtime stage, and the last one: a plain `docker build .` builds it
 # and the stages it copies from, the two phases included.
 # nginx:stable-alpine as of 2026-02-22
 FROM nginx@sha256:15e96e59aa3b0aada3a121296e3bce117721f42d88f5f64217ef4b18f458c6ab
+ARG CACHEBUST
 
 # netwatch-server runs as this user, which owns the report directory.
 # nginx keeps the image's own arrangement: its main process runs as
@@ -128,10 +159,10 @@ RUN addgroup -g 1000 -S netwatch && \
 # At start-up the nginx image renders every template here into
 # conf.d; bin/entrypoint.sh says how.
 RUN rm /etc/nginx/conf.d/default.conf
-COPY nginx.conf /etc/nginx/templates/netwatch.conf.template
-COPY security-headers.conf /etc/nginx/security-headers.conf
-COPY --from=frontend /app/dist /usr/share/nginx/html
-COPY --from=builder /src/backend/netwatch-server /usr/local/bin/netwatch-server
+COPY configs/nginx.conf /etc/nginx/templates/netwatch.conf.template
+COPY configs/security-headers.conf /etc/nginx/security-headers.conf
+COPY --from=frontend-build /app/dist /usr/share/nginx/html
+COPY --from=builder /src/netwatch-server /usr/local/bin/netwatch-server
 COPY bin/entrypoint.sh /usr/local/bin/entrypoint.sh
 
 # bin/entrypoint.sh creates DATA_DIR at start and gives it and /data to

Makefile

@@ -1,10 +1,10 @@
-.PHONY: bootstrap setup dev build test lint fmt fmt-check check \
+.PHONY: bootstrap setup dev build run clean test lint fmt fmt-check check \
 	add-dependency tidy 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
 # of README.md). test, lint, fmt, fmt-check and check cover the whole
-# repo: the frontend here and the Go backend in backend/.
+# repo: the frontend in web/ and the Go backend in cmd/ and internal/.
 
 bootstrap:
 	@script/bootstrap
@@ -15,10 +15,17 @@ setup:
 dev:
 	@script/dev
 
-# The frontend only; backend/Makefile's build target builds the Go server.
+# The frontend into dist/ and the netwatch-server binary.
 build:
 	@script/build
 
+# Builds, then runs netwatch-server on port 8080.
+run:
+	@script/run
+
+clean:
+	@script/clean
+
 test:
 	@script/test
 

README.md

@@ -13,10 +13,13 @@ make setup
 # Run the page on the Vite dev server
 make dev
 
+# Build netwatch-server and run it on port 8080
+make run
+
 # Run the tests, both linters and the format check
 make check
 
-# Build the page into dist/
+# Build the page into dist/ and netwatch-server into the repo root
 make build
 
 # Build the image and run it
@@ -25,9 +28,8 @@ docker run -p 8080:8080 netwatch
 ```
 
 `make check` and `make docker` need Docker. `make dev` passes `/api` to
-`http://127.0.0.1:8080`, where `make run` in `backend/` starts `netwatch-server`
-with its defaults, so the reports the page posts are stored in
-`backend/data/reports`.
+`http://127.0.0.1:8080`, where `make run` starts `netwatch-server` with its
+defaults, so the reports the page posts are stored in `data/reports`.
 
 ## Entrypoints
 
@@ -35,69 +37,95 @@ This repository adheres to the
 [Scripts to Rule Them All](https://github.com/github/scripts-to-rule-them-all)
 standard: normalized scripts in `script/` are the entrypoints for the
 development workflow, and the Makefile targets are thin shims that call them.
-The Go backend in `backend/` has its own `script/` directory and shim Makefile
-(see [backend/README.md](backend/README.md)). The root scripts cover both
-halves, so the root `make check` fails if either one is broken. We provide:
+The scripts cover both the frontend and the Go backend, so `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`, Go `GO_VERSION` unless the `go` on
-  `PATH` is exactly that version, the Go modules, and gcc with the C library
-  headers unless gcc is installed, for the race detector in `make test` in
-  `backend/`), linking what it installs itself into `~/.local/bin`, which has to
-  be on `PATH`. It installs no Go linter and not Docker: `make test` and
-  `make lint` run in Docker
+  the `node` on `PATH` has the pinned major version and is new enough for the
+  frontend's dependencies, yarn `YARN_VERSION` via corepack, or npm where there
+  is no corepack, unless the `yarn` on `PATH` is exactly that version,
+  `yarn install --frozen-lockfile`, Go `GO_VERSION` unless the `go` on `PATH` is
+  exactly that version, and the Go modules), linking what it installs itself
+  into `~/.local/bin`, which has to be on `PATH`. It installs no Go linter and
+  not Docker: `make test` and `make lint` run 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/build` — build the frontend for production into `dist/`, then the
+  static `netwatch-server` binary into the repo root with its version stamped
+  in: `VERSION` from the environment, or when that is unset or empty,
+  `git describe --tags --always --dirty` inside a git checkout, as
+  `script/docker` does, then `dev`
+- `script/run` — build with `script/build`, then run `netwatch-server` with its
+  defaults (see [Settings](#settings))
+- `script/clean` — remove what `script/build` writes
 - `script/projectname` — print the project name (used for the Docker image tag)
-- `script/test` — build the `test` phase of `Dockerfile` without the cache: the
-  frontend's unit tests and production build in its `frontend` stage, and the
-  backend's Go tests with the race detector and coverage
-- `script/lint` — build the `lint` phase of `Dockerfile` without the cache:
-  eslint in its `frontend-lint` stage, and golangci-lint over `backend/`
+- `script/yarn` — run yarn with the given arguments under the node
+  `script/bootstrap` would use: with `~/.local/bin` first on `PATH`, the first
+  `node` on that `PATH` when it has the pinned major version and is new enough
+  for the frontend's dependencies, and otherwise the pinned node in nvm. Every
+  script that runs yarn on the host runs it through this one, except
+  `script/bootstrap`, which picks its own node and yarn
+- `script/test` — build the `test` phase of `Dockerfile`, writing no image: the
+  frontend's unit tests in its `frontend-test` stage, and the backend's Go tests
+  with the race detector and coverage. The frontend's production build is left
+  to the image build, in the `frontend-build` stage
+- `script/lint` — build the `lint` phase of `Dockerfile`, writing no image:
+  eslint in its `frontend-lint` stage, and golangci-lint over the Go packages
 - `script/fmt` — format all files (writes): prettier over the JavaScript, CSS,
-  HTML and Markdown, then gofmt over `backend/`. It runs on the host, as
-  `script/fmt-check` does, with `~/.local/bin` put on `PATH`
+  HTML and Markdown, then gofmt over `cmd/` and `internal/`. It runs on the
+  host, as `script/fmt-check` does, with `~/.local/bin` put on `PATH`
 - `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/tidy` — run `go mod tidy`: to add a Go module, import it and run
+  `make tidy`; to move one to another version, edit its `require` line in
+  `go.mod`, then run `make tidy`
 - `script/frontend-test` — run the unit tests in `test/unit/` on the host with
   Node's built-in test runner, through the `test` script in `package.json`, and
   if any fails, run them again listing every test, and fail; then the production
-  build. Each test run has a 90-second timeout. `make test` runs the same in
-  Docker
+  build. Each test run has a 90-second timeout. `make test` runs the same tests
+  in Docker, without the production build
 - `script/frontend-fmt` — format the JavaScript, CSS, HTML and Markdown with
-  prettier (writes), the markdown in `backend/` included
+  prettier (writes)
 - `script/frontend-fmt-check` — check prettier formatting (read-only)
 - `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
+  [test/viewport/README.md](test/viewport/README.md)). Before the browser
+  starts, it checks that the page, and a path that falls back to it, are served
+  with `Cache-Control: no-cache` and `Content-Security-Policy`. Not part of
   `script/check`: it takes minutes.
-- `script/docker` — build the image from `Dockerfile` without the build cache,
-  tagged `netwatch` via `script/projectname`
+- `script/docker` — build the image from `Dockerfile`, tagged `netwatch` via
+  `script/projectname`
 - `script/cibuild` — CI entrypoint: runs `script/bootstrap` and `script/check`,
-  then builds the image as `script/docker` does, without the build cache
+  then builds the image as `script/docker` does
 - `script/precommit` — run by the git pre-commit hook; runs `script/check`
 - `script/install-precommit` — install the git pre-commit hook
 
+`script/test`, `script/lint`, `script/docker` and `script/cibuild` each pass a
+new `CACHEBUST` value, so every step in `Dockerfile` that lints, tests or
+compiles runs again even when nothing has changed. Docker keeps the system
+packages and the Go modules from earlier builds until the base image, the step
+that installs them, or `go.mod` and `go.sum` change. The `frontend-build` stage
+is the exception: it installs git again on every image build, because it starts
+from the `frontend-test` stage, whose steps run again on every build. Go's build
+cache and golangci-lint's are kept as well, and each reuses a result only when
+everything it was made from is unchanged. Both `go test` runs carry `-count=1`,
+so no test result is reused. The yarn packages are installed again on every
+build.
+
 ## Responsive layout
 
 The narrow-viewport layout lives in the `max-width: 768px` media block in
-`src/styles.css`. It is verified automatically by `make frontend-viewport-test`,
-which drives a digest-pinned headless Chrome against the built `dist/` and
-asserts on computed layout at widths derived from that CSS — on every breakpoint
-it declares and one pixel either side of it, plus a 320px floor, a desktop
-baseline and two landscape sizes. See
+`web/src/styles.css`. It is verified automatically by
+`make frontend-viewport-test`, which drives a digest-pinned headless Chrome
+against the built `dist/` and asserts on computed layout at widths derived from
+that CSS — on every breakpoint it declares and one pixel either side of it, plus
+a 320px floor, a desktop baseline and two landscape sizes. See
 [test/viewport/README.md](test/viewport/README.md) for what it covers and what
 it genuinely cannot.
 
@@ -112,8 +140,11 @@ the same and nothing is stored.
 
 ## Design
 
+The page's source is in `web/`, the Go backend's in `cmd/` and `internal/`, and
+nginx's configuration in `configs/`.
+
 The page is built with Vite and Tailwind CSS v4. Its code is all in
-`src/main.js`, with a class-based architecture:
+`web/src/main.js`, with a class-based architecture:
 
 - **`CONFIG`**: Configuration object (update interval, timeouts, axis ticks,
   etc.). The interval menu sets `updateInterval`, the one value the page writes
@@ -142,31 +173,227 @@ same-origin path `/api/v1/reports`: a random per-browser `clientId` kept in
 `localStorage`, `geo` sent as null, and each host's unreported, non-paused
 samples (timestamp, latency, error). A per-host high-water mark makes every
 report a delta, so only new samples are sent; the mark advances only on a
-delivered report, and while paused nothing is sent. Delivery failure is quiet —
-one debug-log line per outage, retried at the next interval, never blocking
-probing. The report-building step is a pure function of host state.
+delivered report, and while paused nothing is sent. Changing the interval clears
+each host's history on the page; the samples in it not yet reported still go in
+the next report. Delivery failure is quiet — one debug-log line per outage,
+never blocking probing. The report-building step is a pure function of host
+state.
+
+A sample in the history that no report has delivered is sent only as long as the
+history holds it, so after a refused or failed report the next report carries
+the samples the history still has. Samples an interval change cleared from the
+history are kept apart, the last 100 per host, until they are delivered. The
+history keeps each host's last 100 rounds: 100 seconds at the 1-second interval,
+200 seconds at 2 seconds, 5 minutes at the default of 3 seconds and 100 minutes
+at 60 seconds. At 1 second, one refused or failed report loses the oldest 20
+seconds of each host's samples, as the next delivered report comes 2 minutes
+after the last. At 2 seconds and longer one loses nothing; samples are lost from
+the third refused report in a row at 2 seconds, from the fifth at 3 seconds, and
+later still at the longer intervals.
+
+No report is sent while the page is paused, but each paused round still adds an
+entry to the history, so each report due during a pause counts as a refused one.
+A pause longer than the history spans loses the samples in the history recorded
+between the last delivered report and the pause: up to a minute's worth for each
+host if the report before the pause was delivered.
 
 ### Backend
 
-`netwatch-server`, in `backend/`, is a small Go HTTP server that stores the
-reports the page posts. It keeps them in memory and writes them to `DATA_DIR` as
-zstd-compressed files of JSON lines: every minute, whenever 10 MiB are waiting,
-and when it stops. Its routes:
+`netwatch-server` is a small Go HTTP server that stores the reports the page
+posts. It keeps them in memory and writes them to `DATA_DIR` as zstd-compressed
+files of JSON lines: every minute, whenever 10 MiB are waiting, and when it
+stops. Its routes:
 
 - `POST /api/v1/reports` — takes a report, without credentials; each client
   address may send a limited number a minute, and the report files are capped in
   size, the oldest deleted first
 - `GET /.well-known/healthcheck` — answers 200 with `"status":"ok"`, the
-  server's version and its uptime
+  server's version and its uptime; while reports cannot be stored, as the last
+  write of a report file failed, it answers 503 with `"status":"error"` and the
+  same fields (see [Report storage](#report-storage))
 - `GET /metrics` — Prometheus metrics behind basic auth, only when
   `METRICS_USERNAME` and `METRICS_PASSWORD` are set; each client address may
   make a limited number of requests to it a minute
 
+It is an `fx`-wired Go application: `cmd/netwatch-server/` starts it, and its
+packages are in `internal/`:
+
+- **`cli`**: Runs `netwatch-server` from its command line: the `check-cidr` and
+  `prepare-data-dir` subcommands, which `bin/entrypoint.sh` runs before it
+  starts the server, and, given no arguments, the server, with the `fx` wiring.
+  It refuses any other arguments with a usage message and exit code 2.
+- **`config`**: Loads configuration from environment variables and config files
+  via Viper.
+- **`handlers`**: HTTP request handlers for the API (health check, report
+  ingestion).
+- **`reportbuf`**: The in-memory buffer of reports and the files it writes them
+  to.
+- **`server`**: Chi-based HTTP server with middleware wiring and route
+  registration.
+- **`healthcheck`**, **`middleware`**, **`logger`**, **`globals`**: Supporting
+  infrastructure.
+
 In the image, the `test` phase of `Dockerfile` tests it, the `builder` stage
-builds it with `backend/script/build`, and `bin/entrypoint.sh` runs it as user
-`netwatch` on `127.0.0.1:8081`, behind nginx. Outside the image, `make run` in
-`backend/` builds it and runs it on port 8080. Its settings, report storage and
-limits are in [backend/README.md](backend/README.md).
+builds it, and `bin/entrypoint.sh` runs it as user `netwatch` on
+`127.0.0.1:8081`, behind nginx (see [Deployment](#deployment)). Outside the
+image, `make run` builds it and runs it on port 8080.
+
+#### Settings
+
+| Variable               | Default              | Description                                                                                              |
+| ---------------------- | -------------------- | -------------------------------------------------------------------------------------------------------- |
+| `BIND_ADDRESS`         | empty                | IP address to listen on; empty listens on every interface                                                |
+| `PORT`                 | `8080`               | HTTP listen port                                                                                         |
+| `DATA_DIR`             | `./data/reports`     | Directory for compressed reports                                                                         |
+| `DATA_DIR_MAX_BYTES`   | `1073741824` (1 GiB) | Most bytes of report files kept in `DATA_DIR`, oldest deleted first; see [Report limits](#report-limits) |
+| `DEBUG`                | empty                | Debug logging; any non-empty value, `false` and `0` included, turns it on                                |
+| `TRUSTED_PROXIES`      | RFC 1918 ranges      | 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)                                              |
+| `SENTRY_DSN`           | empty                | DSN of the Sentry project to send errors to; see [Sentry](#sentry)                                       |
+
+`TRUSTED_PROXIES` defaults to `10.0.0.0/8,172.16.0.0/12,192.168.0.0/16`. A list
+replaces the default; set and empty, the server trusts no proxy. Loopback is not
+in the default, so a reverse proxy on the same host has to be named, as in
+`TRUSTED_PROXIES=127.0.0.1/32`. A request whose direct peer is outside this set
+has its forwarded headers ignored, and the direct peer is logged and
+rate-limited instead. From a direct peer inside the set, the client address is
+the right-most `X-Forwarded-For` entry that is not in the set: each proxy
+appends the address it took the request from, so the entries further left were
+written by the client and are not used. An entry written as an address with a
+port, such as `198.51.100.7:5000` or `[2001:db8::1]:443`, is read as that
+address. If the search from the right finds only addresses in the set, or meets
+an entry that is not an address at all, such as `unknown`, the direct peer is
+used. `X-Real-IP` is read only when `X-Forwarded-For` is missing or empty. The
+container image does not use this default; see [Deployment](#deployment).
+
+A variable set to a value the server cannot use, such as `PORT=abc` or a
+`BIND_ADDRESS` that is not an IP address, stops it from starting, with an error
+naming the variable. An empty variable counts as unset, except
+`TRUSTED_PROXIES`. No value of `DEBUG` stops the start.
+
+#### Report storage
+
+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 and leaves a gap in
+the numbers: its file, if it was created, is removed. The file stays, counted
+toward `DATA_DIR_MAX_BYTES` from the next start, only if removing it fails too.
+Files are created with `O_EXCL` to prevent overwrites.
+
+The reports of a failed write stay in memory, and the next flush, within a
+minute, tries again to write them. The server writes one file at a time, so a
+file holds its reports in the order they arrived, those of a failed write
+included. From the failed write until a write succeeds, `POST /api/v1/reports`
+refuses every report with 500 and keeps nothing of it, and the health check
+answers 503 with `"status":"error"`. The page sends the refused samples again in
+its next report, as long as it still holds them: at the 1-second interval one
+refused report already loses some of those in the history (see
+[Reporting](#reporting)). Reports already answered 200 are lost only if the
+server stops before a write succeeds; the final flush at stop tries them too,
+and if it fails, the process exits non-zero.
+
+#### Report limits
+
+`POST /api/v1/reports` takes reports from anyone who can reach it, without
+credentials, so it is bounded instead. Each refusal below answers with the same
+`{"status":"error"}` body as any other error, except nginx's refusal of a body
+over the limit in the image.
+
+- **JSON only.** A report must be sent with `Content-Type: application/json`,
+  parameters such as `charset` allowed, as the page sends it; any other is
+  refused with 415, and nothing of it is stored. A page on another origin can
+  send a `text/plain` POST, or a form, without a CORS preflight; refusing them
+  keeps any site from making its visitors' browsers store reports (see
+  [CORS](#cors)).
+- **Body limit.** A report body may be at most 1 MiB, the backend's limit for
+  any request. Run on its own, the backend answers 413 before the route to a
+  request that declares a longer body. Without a declared length, the route
+  answers 413 only when the report it reads runs past 1 MiB; nothing after the
+  end of the report is read, so a longer body whose report ends sooner is
+  stored, and one that stops being valid JSON sooner is answered 400. In the
+  image, nginx refuses a body over 1 MiB first, with or without a declared
+  length, as its `client_max_body_size`, which `configs/nginx.conf` does not
+  set, is 1 MiB by default. nginx answers 413 with its own HTML error page, and
+  the backend never sees the request.
+- **Rate limit.** Each client address, resolved through `TRUSTED_PROXIES`, may
+  send `REPORTS_PER_MINUTE` reports a minute; past that it gets 429 with
+  `Retry-After: 60`. The minute slides: reports from the minute before still
+  count, fading out over the current one, so an address is sure never to be
+  refused only while it sends at most half of `REPORTS_PER_MINUTE` in any 60
+  seconds. The page sends one report a minute from each open tab, so the default
+  of 60 refuses nothing from up to 30 tabs behind one address, such as a
+  household or an office sharing it, however their reports bunch up. Report
+  responses also carry `X-RateLimit-Limit`, `X-RateLimit-Remaining` and
+  `X-RateLimit-Reset` headers.
+- **Size cap.** The report files in `DATA_DIR` may total at most
+  `DATA_DIR_MAX_BYTES`, counting the files already there at start. Reports
+  waiting in memory count at their uncompressed size until they are written,
+  those of a failed write included; the part of its file written is removed.
+  When a report would take the total past the cap, the oldest report files are
+  deleted to make room, and each deletion is logged with the file's name and
+  size; a file still being written is never deleted. A report is refused with
+  507, and nothing of it is stored, only when the reports waiting 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 `DATA_DIR`.
+
+At the defaults, one address may send 60 reports of up to 1 MiB a minute, and a
+report made up to compress badly takes about as much room in the report files as
+its request body, so in about 17 minutes one address can fill the 1 GiB cap with
+its own reports, every report stored before them deleted to make room. Lowering
+`REPORTS_PER_MINUTE` or raising `DATA_DIR_MAX_BYTES` makes that take longer.
+
+#### CORS
+
+The page calls the API from the origin it is served from, so by default the
+server sends no CORS headers, and browsers let no other origin's pages call it.
+To serve the page from elsewhere, list that origin in `CORS_ALLOWED_ORIGINS`
+(for example `https://netwatch.example.com`); pages from a listed origin may
+`GET` and `POST` with a `Content-Type` header. Each entry must be a plain
+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 or
+405 for a method its route does not take. Run on its own, the backend also
+answers 413 before the route to a request declaring a body length over the 1 MiB
+limit, which is not recorded. A body over the limit sent without a declared
+length reaches the route and is recorded with the status the route answers,
+which is 413 only when the report it reads runs past the limit: nothing after
+the end of the report is read. In the image neither reaches the backend: nginx
+answers both with 413 itself (see [Report limits](#report-limits)), and nothing
+of them is recorded. 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.
+
+`/metrics` is rate limited, so that its password cannot be guessed quickly: each
+client address, resolved through `TRUSTED_PROXIES`, may make 60 requests to it a
+minute, whatever their credentials. Past that it gets 429 with
+`Retry-After: 60`, and its credentials are not checked. The minute slides as it
+does for reports (see [Report limits](#report-limits)), so a scraper polling
+every 2 seconds or less often is never refused. This allowance is apart from the
+one for reports.
+
+#### Sentry
+
+With `SENTRY_DSN` set, each panic in a handler is reported to that Sentry
+project under the release `netwatch-server-` followed by the server's version.
+On shutdown the server waits up to 2 seconds for Sentry to finish sending.
 
 ### Monitoring targets
 
@@ -268,20 +495,29 @@ behind a reverse proxy.
 
 The Docker image, built from `Dockerfile` by `make docker`, is the whole service
 in one container: nginx serves the built frontend and passes `/api/`,
-`/.well-known/healthcheck` and `/metrics` to the Go backend, `netwatch-server`,
-which listens only inside the container, on `127.0.0.1:8081`. The image:
+`/.well-known/healthcheck` and `/metrics` to the Go backend, `netwatch-server`.
+`bin/entrypoint.sh` starts it listening only inside the container, on
+`127.0.0.1:8081`, with `TRUSTED_PROXIES=127.0.0.1/32`, so it takes the client
+address nginx passes on and no other. 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
-  reverse proxies named in `TRUSTED_PROXIES`, and by default from none
+  reverse proxies named in `TRUSTED_PROXIES`, by default from any address in
+  `10.0.0.0/8`, `172.16.0.0/12` or `192.168.0.0/16`. `bin/entrypoint.sh` checks
+  each entry with `netwatch-server check-cidr`, which parses it as the backend
+  parses its own `TRUSTED_PROXIES`
 - Sends access logs to stdout
-- Caches static assets with immutable headers
+- Sends the page with `Cache-Control: no-cache`, so a browser that keeps a copy
+  checks with the server that it is current before using it again; only the
+  files under `/assets/`, whose names change whenever their contents do, are
+  cached as immutable
 - Sends the security headers `REPO_POLICIES.md` requires on every response, as
-  `security-headers.conf` sets them, in place of the backend's own
+  `configs/security-headers.conf` sets them, in place of the backend's own
 - Stores reports in `DATA_DIR`, `/data/reports` by default, on the `/data`
   volume. Before the backend starts, the image creates `DATA_DIR` and gives it
-  and `/data` to user `netwatch` (uid 1000), which the backend runs as, so a
-  host directory bind-mounted at `/data` ends up owned by uid 1000
+  and `/data` to user `netwatch` (uid 1000), which the backend runs as, with
+  `netwatch-server prepare-data-dir`, which acts on nothing outside `/data`, so
+  a host directory bind-mounted at `/data` ends up owned by uid 1000
 - Writes buffered reports to disk on `docker stop`, and exits non-zero if nginx
   or the backend exits on its own, so the platform restarts it
 
@@ -291,9 +527,9 @@ What the [upaas](https://git.eeqj.de/sneak/upaas) app for netwatch needs:
 
 - **Port:** container port `8080`.
 - **Volume:** container path `/data`; the reports are kept in `/data/reports`.
-- **Environment variables:** none is required. An empty one counts as unset, and
-  one set to a value netwatch cannot use stops the container at start, with the
-  reason in its log.
+- **Environment variables:** none is required. An empty one counts as unset,
+  except `TRUSTED_PROXIES`, and one set to a value netwatch cannot use stops the
+  container at start, with the reason in its log.
     - `PORT`, default `8080`: the container port, from 1 to 65535. `8081` cannot
       be used: the backend listens on it inside the container
     - `REPORTS_PER_MINUTE`, default `60`: reports each client address may send a
@@ -302,21 +538,23 @@ What the [upaas](https://git.eeqj.de/sneak/upaas) app for netwatch needs:
       report files may take; the oldest are deleted to stay under it
     - `CORS_ALLOWED_ORIGINS`, default empty: other origins whose pages may call
       the API
-    - `DEBUG`, default `false`: debug logging
+    - `DEBUG`, default empty: debug logging; any non-empty value, `false` and
+      `0` included, turns it on
     - `DATA_DIR`, default `/data/reports`: the directory the reports are kept
       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
-      `X-Forwarded-For` only on a request from one of them, and the rate limit
-      counts that address. Unset, `X-Forwarded-For` is ignored and every client
-      behind the proxy shares the proxy's one allowance of `REPORTS_PER_MINUTE`.
-      Name only addresses nothing but the proxy connects from: any client that
-      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`.
+    - `TRUSTED_PROXIES`, default `10.0.0.0/8,172.16.0.0/12,192.168.0.0/16`: the
+      addresses the reverse proxy in front of the container connects from, as IP
+      addresses or CIDRs separated by commas. nginx takes the client address
+      from `X-Forwarded-For` only on a request from one of them, and the rate
+      limit counts that address. A list replaces the default. Set and empty,
+      `X-Forwarded-For` is ignored and every client behind the proxy shares the
+      proxy's one allowance of `REPORTS_PER_MINUTE`. Any client that connects
+      from one of these addresses 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`, which the default includes; where
+      that matters, name only the addresses nothing but the proxy connects from.
     - `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
@@ -329,9 +567,16 @@ What the [upaas](https://git.eeqj.de/sneak/upaas) app for netwatch needs:
       stops the container. Empty, the backend sends nothing to Sentry
 - **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
-  seconds after a deploy and fails the deploy unless it is `healthy`. The
-  container also stops when either process exits.
+  both nginx and the backend answer. It also fails while reports cannot be
+  stored, as when the volume is full or `DATA_DIR` cannot be written: the health
+  check answers 503 from a failed write of a report file until a write succeeds,
+  and the backend tries the write again every minute. Three failed checks in a
+  row make the container `unhealthy`, and one that passes makes it `healthy`
+  again. upaas reads the container's health once, 60 seconds after a deploy, and
+  fails the deploy unless it is `healthy`. A container that turns `unhealthy`
+  after that is neither restarted nor reported by upaas, whose `unless-stopped`
+  restart policy ignores health; only `docker ps` and `docker inspect` show it.
+  The container also stops when either process exits.
 
 ## Browser Compatibility
 

REPO_POLICIES.md

@@ -1,6 +1,6 @@
 ---
 title: Repository Policies
-last_modified: 2026-10-04
+last_modified: 2026-10-18
 ---
 
 This document covers repository structure, tooling, and workflow standards. Code
@@ -54,34 +54,39 @@ style conventions are in separate documents:
   `cibuild`. `script/bootstrap` installs all dependencies idempotently and
   assumes nothing is present: base tools come from nix, apt, brew, or apk
   (detected in that order; apt runs noninteractive). For node it uses the
-  installed node if present; otherwise it installs a PINNED node version via
-  nvm, first installing nvm itself if missing — from a hash-verified GitHub
-  release archive (never `curl | sh`), with bash installed as an explicit
-  prerequisite since nvm requires bash. yarn is then pinned via
-  `corepack prepare yarn@<version> --activate`. Never install "latest" or "lts";
-  always exact versions. `script/cibuild` runs the CI build: it changes to the
-  repo root, runs `script/bootstrap`, runs `script/check`, and builds the image
-  with the version; the Gitea workflow calls it. **`script/cibuild` runs
+  installed node only when its major version is the pinned one; otherwise (node
+  missing, or another major, such as the node 24 the CI runner image ships) it
+  installs the PINNED node version via nvm and installs yarn and the packages
+  under it. nvm itself is installed first if missing, from a hash-verified
+  GitHub release archive (never `curl | sh`), with bash installed as an explicit
+  prerequisite since nvm requires bash. Only the major version is compared
+  because the `Dockerfile` stages start from a node image whose exact version is
+  not the pin, and nvm cannot install a prebuilt node on alpine. yarn is pinned
+  via `corepack prepare yarn@<version> --activate`. Never install "latest" or
+  "lts"; always exact versions. `script/cibuild` runs the CI build: it changes
+  to the repo root, runs `script/bootstrap`, runs `script/check`, and builds the
+  image with the version; the Gitea workflow calls it. **`script/cibuild` runs
   `script/bootstrap` first**, because the workflow checks out the repo and runs
   nothing else, while `script/fmt-check` runs the formatter on the host: on a
   pristine checkout with nothing installed the run dies there, after the
-  containerised gates have passed. **The bootstrap alone is not enough**:
-  `script/bootstrap` installs node and yarn under nvm and leaves neither on the
-  `PATH` of the shell that called it, so a bare `yarn` still exits 127. The host
-  entrypoints that need yarn — `script/fmt` and `script/fmt-check` — therefore
-  source nvm for the pinned node version before invoking it, exactly as
-  `script/bootstrap`'s own install step does. A runner carrying nothing but
-  docker and git then gets through `script/check`. Four further scripts are our
-  own extensions to the standard: `script/check` runs `script/test`,
-  `script/lint` and `script/fmt-check`; `script/precommit` is what the git
-  pre-commit hook runs, and it calls `script/check`; `script/install-precommit`
-  installs the git pre-commit hook (the `make hooks` target shims to it); and
-  `script/projectname` (literally that filename) simply outputs the project's
-  name. Scripts that need the name call `script/projectname` — e.g.
-  `script/docker` assembles its image tag from it — so those scripts stay
-  byte-identical across all repos. Repo-type-specific pre-commit extras (e.g.
-  `go mod tidy` verification in Go repos) belong in `script/precommit`, not in
-  the hook itself. Model scripts are at
+  containerised gates have passed. **The bootstrap alone is not enough**: when
+  `script/bootstrap` installs node and yarn under nvm it leaves neither on the
+  `PATH` of the shell that called it, so a bare `yarn` either exits 127 or runs
+  under another node. The host entrypoints that need yarn — `script/fmt` and
+  `script/fmt-check` — therefore use the same test as `script/bootstrap`: when
+  the node on `PATH` has the pinned major version they run the `yarn` on `PATH`,
+  and otherwise they load nvm through `$HOME/.nvm/nvm.sh` and run yarn under the
+  pinned node. A runner carrying nothing but docker and git then gets through
+  `script/check`. Four further scripts are our own extensions to the standard:
+  `script/check` runs `script/test`, `script/lint` and `script/fmt-check`;
+  `script/precommit` is what the git pre-commit hook runs, and it calls
+  `script/check`; `script/install-precommit` installs the git pre-commit hook
+  (the `make hooks` target shims to it); and `script/projectname` (literally
+  that filename) simply outputs the project's name. Scripts that need the name
+  call `script/projectname` — e.g. `script/docker` assembles its image tag from
+  it — so those scripts stay byte-identical across all repos. Repo-type-specific
+  pre-commit extras (e.g. `go mod tidy` verification in Go repos) belong in
+  `script/precommit`, not in the hook itself. Model scripts are at
   `https://git.eeqj.de/sneak/prompts/raw/branch/main/script/<name>`. The README
   must document the provided scripts in an **Entrypoints** section (see the
   README requirements below).
@@ -118,8 +123,10 @@ style conventions are in separate documents:
   and nothing else:
 
     ```sh
-    docker build --no-cache --target lint -t "$(script/projectname)-lint" .
-    docker build --no-cache --target test -t "$(script/projectname)-test" .
+    docker build --build-arg CACHEBUST="$(date +%s)-$$" \
+        --target lint --output type=cacheonly .
+    docker build --build-arg CACHEBUST="$(date +%s)-$$" \
+        --target test --output type=cacheonly .
     ```
 
     **A stage that is not the last one in the file is built only when the final
@@ -129,10 +136,15 @@ style conventions are in separate documents:
     plain `docker build .` builds the last stage alone and exits 0 having linted
     and tested nothing.
 
-    **Every `docker build` in `script/` is tagged**, here and in
-    `script/cibuild` and `script/docker`. An untagged build leaves a dangling
-    image behind on every invocation, on every developer host and every CI
-    runner; a tagged one replaces the previous image.
+    **The gate builds write no image.** With `--output type=cacheonly` the phase
+    runs and a failing step fails the build, but the result is not exported.
+    Nothing uses those images, and writing one out is slow: a Go test phase's
+    image holds the toolchain. A build given neither `--output` nor `-t` writes
+    an untagged image and leaves it dangling, on every developer host and every
+    CI runner. `script/cibuild` and `script/docker` build the image that ships
+    and tag it, so each build replaces the previous image; each assigns the tag
+    on its own line before the build, so `set -e` stops it where
+    `script/projectname` fails.
 
     Inside a phase the tool is invoked directly — `golangci-lint`, `go test`,
     `eslint`, `prettier` — never through `make lint` or `script/test`, which are
@@ -147,22 +159,42 @@ style conventions are in separate documents:
     one's findings, and a host-global lock in `$TMPDIR` makes concurrent runs
     exit non-zero with `parallel golangci-lint is running` — a status a caller
     cannot tell from real findings. Both have produced wrong verdicts in this
-    org, in both directions. A container has its own cache, its own `TMPDIR` and
-    a digest-pinned binary, so neither is reachable.
+    org, in both directions. A container has its own `TMPDIR`, so the lock is
+    out of reach. The lint phase does keep golangci-lint's cache between check
+    builds (below), but it lints every checkout at `/src`, and a finding is
+    taken from that cache only for the same files, settings and golangci-lint
+    version.
 
-- **Any build that runs checks is built with `--no-cache`.** Docker invalidates
-  a `COPY` layer only when the copied content changes, so on an unchanged tree
-  the check `RUN` is served from cache, nothing executes, and the build still
-  exits 0. Every `docker build` in `script/` therefore passes `--no-cache`:
-  `script/lint`, `script/test`, `script/cibuild` and `script/docker` are the
-  four, and there is no fifth — `script/check` runs the two gate phases and
-  `script/fmt-check`, and builds no image of its own. A bare `docker build .` is
-  not evidence that anything ran: a sub-second build reporting success is a
-  cache hit, not a result. Never invalidate by pruning — `docker builder prune`
-  and friends destroy a build cache shared with every other build on the host.
-  When a check is added or changed, prove it works by planting a defect it must
-  catch and watching the run fail on it, then revert the defect. A green run
-  alone shows neither that the check ran nor that it covers what it should.
+- **Any build that runs checks is given a new `CACHEBUST` value.** Docker
+  invalidates a `COPY` layer only when the copied content changes, so on an
+  unchanged tree the check `RUN` is served from cache, nothing executes, and the
+  build still exits 0. Every `docker build` in `script/` therefore passes
+  `--build-arg CACHEBUST="$(date +%s)-$$"`, the time and the script's process
+  id, so no two builds share a value, not even the three in one
+  `script/cibuild`. `script/lint`, `script/test`, `script/cibuild` and
+  `script/docker` are the four, and there is no fifth — `script/check` runs the
+  two gate phases and `script/fmt-check`, and builds no image of its own. In
+  every stage of the `Dockerfile`, `ARG CACHEBUST` comes right after the steps
+  that install system packages and download Go's modules, or right after `FROM`
+  in a stage with neither, and every step that lints, tests or compiles comes
+  after it. A step that installs anything else as well, such as a
+  `script/bootstrap` that also installs node packages, comes after it too. A new
+  value reruns every `RUN` step after that line; `COPY` steps are compared by
+  content and need nothing. Docker keeps the layers above the line until the
+  base image, their own lines or the files they copy change. A stage without the
+  `ARG` line is served from cache on an unchanged tree, so a repository
+  re-vendors the scripts and adds the `ARG` lines in one commit. The scripts do
+  not pass `--no-cache`: it reruns every step too, but it also builds the layers
+  above the line again and empties every cache mount, so Go's build cache and
+  golangci-lint's, which the canonical Go `Dockerfile` below mounts so that they
+  survive between check builds, would start empty every time. A bare
+  `docker build .` is not evidence that anything ran: a sub-second build
+  reporting success is a cache hit, not a result. Never invalidate by pruning —
+  `docker builder prune` and friends destroy a build cache shared with every
+  other build on the host. When a check is added or changed, prove it works by
+  planting a defect it must catch and watching the run fail on it, then revert
+  the defect. A green run alone shows neither that the check ran nor that it
+  covers what it should.
 
 - **The gate phases are separate stages, and the build stage depends on both.**
   The lint phase is based on the `golangci/golangci-lint` image (pinned by
@@ -171,40 +203,56 @@ style conventions are in separate documents:
   `Dockerfile`:
 
     ```dockerfile
+    # In every stage ARG CACHEBUST comes right after the steps that install
+    # system packages and download Go's modules, or right after FROM in a
+    # stage with neither, and every step that lints, tests or compiles
+    # comes after it. script/ passes a new value on every build, which
+    # reruns every RUN step after it. Docker keeps the layers above it
+    # until the base image, their own lines or go.mod and go.sum change.
+    # The steps that compile mount Go's build cache, and golangci-lint run
+    # also mounts golangci-lint's; both survive from build to build.
+
     # Lint phase
     # golangci/golangci-lint:v2.x.x, YYYY-MM-DD
     FROM golangci/golangci-lint@sha256:... AS lint
     WORKDIR /src
     COPY go.mod go.sum ./
     RUN go mod download
+    ARG CACHEBUST
     COPY . .
-    RUN golangci-lint run --config .golangci.yml ./...
+    RUN --mount=type=cache,target=/root/.cache/go-build \
+        --mount=type=cache,target=/root/.cache/golangci-lint \
+        golangci-lint run --config .golangci.yml ./...
 
     # Test phase. -race needs cgo and so a C compiler, which the Debian Go
-    # image ships and the alpine one does not.
+    # image ships and the alpine one does not. -count=1 because the mounted
+    # cache also holds test results, which go test would otherwise replay.
     # golang:1.x, YYYY-MM-DD
     FROM golang@sha256:... AS test
     WORKDIR /src
     COPY go.mod go.sum ./
     RUN go mod download
+    ARG CACHEBUST
     COPY . .
-    RUN go test -timeout 90s -race -cover ./... || \
+    RUN --mount=type=cache,target=/root/.cache/go-build \
+        go test -count=1 -timeout 90s -race -cover ./... || \
         { echo "--- Rerunning with -v for details ---"; \
-          go test -timeout 90s -race -v ./...; exit 1; }
+          go test -count=1 -timeout 90s -race -v ./...; exit 1; }
 
     # Build stage. Nothing is wanted from either phase above; the copies
-    # are what make BuildKit build them first, so this stage cannot run
-    # unless lint and test passed.
+    # are what make BuildKit build them first, so nothing after them can
+    # run unless lint and test passed.
     # golang:1.x-alpine, YYYY-MM-DD
     FROM golang@sha256:... AS builder
-    COPY --from=lint /src/go.sum /dev/null
-    COPY --from=test /src/go.sum /dev/null
     RUN apk add --no-cache git
-    # A tar-stream context keeps the sender's file owners, which git refuses.
-    RUN git config --system --add safe.directory /src
     WORKDIR /src
     COPY go.mod go.sum ./
     RUN go mod download
+    ARG CACHEBUST
+    COPY --from=lint /src/go.sum /dev/null
+    COPY --from=test /src/go.sum /dev/null
+    # A tar-stream context keeps the sender's file owners, which git refuses.
+    RUN git config --system --add safe.directory /src
     COPY . .
 
     # The VERSION build arg when one is given, otherwise
@@ -212,7 +260,8 @@ style conventions are in separate documents:
     # .git present, a version that is still empty, dev or unknown fails the
     # build: git is missing or could not read the checkout.
     ARG VERSION
-    RUN VERSION="${VERSION:-$(git describe --tags --always)}"; \
+    RUN --mount=type=cache,target=/root/.cache/go-build \
+        VERSION="${VERSION:-$(git describe --tags --always)}"; \
         if [ -e .git ]; then \
             case "$VERSION" in ""|dev|unknown) \
                 echo "version is '$VERSION' although .git is present" >&2; \
@@ -225,6 +274,7 @@ style conventions are in separate documents:
 
     # Runtime stage, and the last one
     FROM alpine@sha256:...
+    ARG CACHEBUST
     COPY --from=builder /app /usr/local/bin/app
     ENTRYPOINT ["app"]
     ```
@@ -239,6 +289,26 @@ style conventions are in separate documents:
     - Keep the runtime stage last, and if you add a stage after it, give it the
       same two copies. A plain `docker build .` builds the last stage's chain
       and nothing else.
+    - Check builds keep these, and none of them can hand back a stale result:
+        - The layers above `ARG CACHEBUST`: the system packages and Go's
+          modules. Docker installs the packages again when the base image or the
+          install line changes, and downloads the modules again when `go.mod` or
+          `go.sum` changes. Go checks every module against `go.sum` as it
+          downloads it, and no later build can change a kept layer. The modules
+          are kept in a layer rather than a cache mount because a cache mount is
+          shared by every build on the host, and Go builds from whatever files
+          it holds without checking them again (only `go mod verify` does), so a
+          file changed there would go unnoticed.
+        - Go's build cache (`/root/.cache/go-build`, where Go keeps it for
+          root), mounted on the steps that compile: `golangci-lint run`, both
+          `go test` runs and `go build`. Go reuses a compiled package only when
+          all its inputs are unchanged. The cache also holds test results, which
+          is why both `go test` runs carry `-count=1`.
+        - golangci-lint's cache (`/root/.cache/golangci-lint`, where the pinned
+          image keeps it), mounted on `golangci-lint run`. golangci-lint reuses
+          a package's findings only when the package's files and those of every
+          package it imports, `go.mod`, the linters and their settings in
+          `.golangci.yml`, and the golangci-lint version are all unchanged.
     - If the project uses `//go:embed` directives that reference build artifacts
       (e.g. a web frontend compiled in a separate stage), the lint phase must
       create placeholder files so the embed directives resolve. Example:
@@ -247,12 +317,20 @@ style conventions are in separate documents:
       in the lint phase. The `golangci/golangci-lint` image is Debian-based and
       has no `apk`, so install with `apt-get` under the Debian package name
       (`libvips-dev`, where alpine says `vips-dev`), and delete the package
-      lists in the same `RUN`, so the layer does not keep them:
+      lists in the same `RUN`, so the layer does not keep them. The test phase,
+      on the Debian Go image, installs the libraries its tests need the same
+      way. Either install goes right after `FROM`, above `ARG CACHEBUST`, so
+      Docker keeps it until the base image or the install line changes:
 
         ```dockerfile
+        FROM golangci/golangci-lint@sha256:... AS lint
         RUN apt-get update \
             && apt-get install -y --no-install-recommends libvips-dev \
             && rm -rf /var/lib/apt/lists/*
+        WORKDIR /src
+        COPY go.mod go.sum ./
+        RUN go mod download
+        ARG CACHEBUST
         ```
 
     - `.dockerignore` lets `.git` into the build context. It keeps out every git
@@ -278,20 +356,39 @@ style conventions are in separate documents:
       `.git` and the version still comes out empty, `dev` or `unknown`. A plain
       `docker build .` with no build arguments must succeed; a Dockerfile that
       refuses an empty build argument drops that refusal and keeps the argument.
+      A checkout whose `.git` is a file (a linked worktree, or a repository
+      checked out as a submodule) is the exception: that file points to a git
+      directory outside the build context, so the build cannot read the version
+      and a plain `docker build .` fails; pass the version with
+      `--build-arg VERSION=...`, as `script/docker` and `script/cibuild` already
+      do.
 
 - Every repo should have a Gitea Actions workflow (`.gitea/workflows/`) that
-  runs `script/cibuild` on push, and checks out the repo as its only other step.
-  That script bootstraps, runs the gate phases, and then builds the image, so a
-  successful run means every check passed; a bare `docker build .` does not
+  runs `script/cibuild` on push, and checks out the repo as its only other step,
+  with `persist-credentials: false`: `script/cibuild` needs no token, and
+  without it the checkout leaves the job's token in `.git/config` for every
+  later step. The checkout step also sets `fetch-depth: 0`, which fetches the
+  tags `git describe` needs: by default it clones shallow with no tags, and a
+  tagged repository's CI build would stamp a bare short commit id. The
+  workflow's `concurrency` block groups runs by workflow and branch
+  (`${{ github.workflow }}-${{ github.ref }}`) with `cancel-in-progress: true`,
+  so a new push cancels the older run on the same branch, queued or running, and
+  no other: runs for replaced commits do not hold up the shared runner.
+  `script/cibuild` bootstraps, runs the gate phases, and then builds the image,
+  so a successful run means every check passed; a bare `docker build .` does not
   carry the same guarantee, because its gate phases may come from the cache. The
-  image build is uncached and so runs the gate phases a second time. That is the
-  price of the rule above, and it is worth paying: the image that ships is built
-  from a run of its own gates rather than from a cache entry. A separate
-  workflow limited to `main` by a `branches` list under `on: push` cannot be
-  checked by review: to try a change to it, add the feature branch to that list
-  and push, then remove the branch from the list again before merging. Keep any
-  job in it that publishes behind `if: github.ref_name == 'main'`, so the run
-  from the feature branch publishes nothing.
+  image build gets a `CACHEBUST` value of its own and so runs the gate phases a
+  second time. That is the price of the rule above, and it is worth paying: the
+  image that ships is built from a run of its own gates rather than from a cache
+  entry. The `check` job sets `timeout-minutes: 20`, so a hung build frees the
+  shared runner after 20 minutes. That allows for the three Docker builds
+  described above (the test phase, the lint phase, then the image), each held to
+  the 5-minute Docker build limit below, plus the bootstrap. A separate workflow
+  limited to `main` by a `branches` list under `on: push` cannot be checked by
+  review: to try a change to it, add the feature branch to that list and push,
+  then remove the branch from the list again before merging. Keep any job in it
+  that publishes behind `if: github.ref_name == 'main'`, so the run from the
+  feature branch publishes nothing.
 
 - Use platform-standard formatters: `black` for Python, `prettier` for
   JS/CSS/Markdown/HTML, `go fmt` for Go. Always use default configuration with
@@ -351,12 +448,11 @@ style conventions are in separate documents:
     That cache is Go's own, separate from Docker's layer cache. Go stores a
     passing result in its cache directory (`GOCACHE`), and when the same tests
     run again on unchanged code it prints that result, marked `(cached)`,
-    without running them. That matters on a developer's machine, where this
-    target runs and the directory lasts from one run to the next. The `test`
-    phase of the `Dockerfile` needs no `-count=1`: its base image holds no
-    result for this repo's tests and nothing before its `go test` step runs a
-    test, so there is nothing to replay. `--no-cache` (above) is what makes that
-    step run on an unchanged tree.
+    without running them. The directory lasts from one run to the next on a
+    developer's machine, where this target runs, and in the `test` phase of the
+    `Dockerfile`, which mounts it to keep compiled packages between check
+    builds, so the phase's `go test` runs carry `-count=1` too. A new
+    `CACHEBUST` value (above) is what makes that step run on an unchanged tree.
 
     Python example:
 
@@ -384,9 +480,12 @@ style conventions are in separate documents:
 
 - `.gitignore` should be comprehensive from the start: OS files (`.DS_Store`),
   editor files (`.swp`, `*~`), in-repo agent scratch directories (`.claude/`),
-  language build artifacts, and `node_modules/`. Fetch the standard `.gitignore`
-  from `https://git.eeqj.de/sneak/prompts/raw/branch/main/.gitignore` when
-  setting up a new repo. These patterns are written to `.gitignore`'s own
+  `node_modules/`, and the repo's own build outputs. Fetch the standard
+  `.gitignore` from
+  `https://git.eeqj.de/sneak/prompts/raw/branch/main/.gitignore` when setting up
+  a new repo. A repo's `.gitignore` is the standard file followed by the repo's
+  own entries, such as its binaries; a re-vendor replaces the standard part and
+  keeps those entries. These patterns are written to `.gitignore`'s own
   semantics, in which an unanchored pattern already matches at every depth; they
   are not a `.dockerignore` and must not be transplanted into one unmodified.
 
@@ -434,13 +533,15 @@ style conventions are in separate documents:
   byte-identically across repos:
 
     ```sh
-    # Own line: a failing command substitution inside an argument does not
-    # trip `set -e`, so the inline form degrades to an empty constant.
+    # The version and the tag each get their own line: a failing command
+    # substitution inside an argument does not trip `set -e`, so the inline
+    # form degrades to an empty constant.
     version="$(git describe --tags --always --dirty 2>/dev/null || true)"
     [ -n "$version" ] || version="unknown"
-    docker build --no-cache \
+    tag="$(script/projectname)"
+    docker build --build-arg CACHEBUST="$(date +%s)-$$" \
         --build-arg VERSION="$version" \
-        -t "$(script/projectname)" .
+        -t "$tag" .
     ```
 
     `--always` makes an untagged repo yield an abbreviated commit hash rather
@@ -452,8 +553,8 @@ style conventions are in separate documents:
     there because `ARG` is stage-scoped; passing `VERSION` to a repo whose
     Dockerfile declares no such `ARG` is ignored and costs nothing, which is why
     the scripts stay byte-identical. One consequence for CI: the standard
-    checkout action clones shallow and fetches no tags, so a repo that embeds a
-    tag-derived version must set `fetch-depth: 0` on its checkout step.
+    checkout action clones shallow and fetches no tags, so the canonical
+    `.gitea/workflows/check.yml` sets `fetch-depth: 0` on its checkout step.
 
 - **Verify `.dockerignore` by enumerating the image, not by reading the
   patterns.** Plant files at the root _and_ at least two directories deep, build
@@ -520,6 +621,11 @@ style conventions are in separate documents:
       function defined and never invoked has the same exit status and the same
       empty output as one that worked.
 
+    Node is the exception to the whole-token comparison: the canonical
+    `script/bootstrap` compares only its major version, because the node 22
+    alpine image the `Dockerfile` stages start from is not the exact pin, and
+    nvm cannot install a prebuilt node on alpine.
+
     Keep it POSIX sh: no arrays, no `[[`, no `grep -P`.
 
     A Go tool a repo needs on the host is installed with `go install` pinned to
@@ -636,7 +742,11 @@ style conventions are in separate documents:
       Never edit existing migrations after release.
 
 - All repos should have an `.editorconfig` enforcing the project's indentation
-  settings.
+  settings: the standard file from
+  `https://git.eeqj.de/sneak/prompts/raw/branch/main/.editorconfig`, which sets
+  tabs for `Makefile` and Go files, followed by the repo's own sections, such as
+  one for another language it uses. A re-vendor replaces the standard part and
+  keeps those sections.
 
 - Avoid putting files in the repo root unless necessary. Root should contain
   only project-level config files (`README.md`, `AGENTS.md`, `Makefile`,

TODO.md

@@ -9,19 +9,345 @@
 
 # Status
 
-pre-1.0. No git tags. `main` is the stable branch and `next` the development
-branch, which every PR targets. The frontend and the Go backend ship as one
-Docker image, and the Gitea workflow `.gitea/workflows/check.yml` runs
-`script/cibuild` on every push. Working toward 1.0.0.
+pre-1.0. Release candidates are tagged on `next`, the first being `v1.0.0-rc1`;
+`git tag --merged origin/next` lists them. `main` is the stable branch and
+`next` the development branch, which every PR targets. The frontend and the Go
+backend ship as one Docker image, and the Gitea workflow
+`.gitea/workflows/check.yml` runs `script/cibuild` on every push, and cancels
+the older run on the same branch. Working toward 1.0.0.
 
 # Next Step
 
-Decide whether the repo moves to the layout `REPO_POLICIES.md` gives, with
-`backend/` no longer repeating files from the root
-([#30](https://git.eeqj.de/sneak/netwatch/issues/30)).
+Run `make frontend-viewport-test` in CI as its own step; it is not part of
+`make check`, as it needs Docker and takes minutes.
 
 # Completed Steps
 
+- 2026-10-19: the server's `OnStart` hook in `internal/server/server.go` starts
+  `listenAndServe` with `go func() { s.listenAndServe() }()`, as the Go style
+  guide asks ([#162](https://git.eeqj.de/sneak/netwatch/issues/162)); it was
+  `go s.listenAndServe()`. No other `go` statement in the Go code called a
+  function directly. Nothing the server does changed
+- 2026-10-19: `.gitignore`, `.editorconfig` and `.golangci.yml` are the
+  sneak/prompts copies at `0653579`
+  ([#174](https://git.eeqj.de/sneak/netwatch/issues/174)). `.gitignore` is the
+  standard file followed by this repository's own entries; `.editorconfig` is
+  the standard file alone, which now carries the `[*.go]` section.
+  `.golangci.yml` disables `canonicalheader`, as the canonical copy does,
+  because golangci-lint v2.14.0 misses its findings at random
+- 2026-10-19: `package.json` has no `version` field and is marked
+  `"private": true` ([#158](https://git.eeqj.de/sneak/netwatch/issues/158)). It
+  said `1.0.0`, a release that has not been made, and nothing read it; the git
+  tag is the one version, which the image and `make build` take from
+  `git describe --tags`. The package is never published
+- 2026-10-19: Status names `v1.0.0-rc1`, the first release candidate, and says
+  release candidates are tagged on `next`, where it said there were no git tags
+  ([#157](https://git.eeqj.de/sneak/netwatch/issues/157)). The rest of Status
+  matches the tree
+- 2026-10-19: `netwatch-server` starts the server only when given no arguments
+  ([#179](https://git.eeqj.de/sneak/netwatch/issues/179)). `check-cidr CIDR` and
+  `prepare-data-dir DATA_DIR` behave as before; any other arguments, such as a
+  subcommand with no value or two, or a misspelt one, print a one-line usage
+  message naming both forms to stderr and exit 2. They used to start the server.
+  Unit tests call `cli.Main` with no arguments and check that it starts the
+  server, and with each subcommand given no value and two values and with a
+  misspelt subcommand, and check the exit code, the message and that the server
+  does not start
+- 2026-10-19: `main()` in `cmd/netwatch-server/main.go` is one call into a new
+  package, `internal/cli`, as the Go style guide asks
+  ([#160](https://git.eeqj.de/sneak/netwatch/issues/160)). `internal/cli` runs
+  the `check-cidr` and `prepare-data-dir` subcommands, with the same arguments,
+  messages and exit codes, and otherwise the server, with the `fx` wiring.
+  `Appname` and `Version` stay in `main`, where the build sets `Version`, and
+  `main` gives `cli.Main` stderr and the function that runs the server, which
+  the tests replace with a buffer and a function that fails them. Unit tests
+  call `cli.Main` with `check-cidr` and a CIDR the server takes and one it
+  refuses, and check the exit code and what it writes to stderr, and with
+  `prepare-data-dir` and a path outside `/data`, and check that it exits 1 with
+  the error from looking up the `netwatch` user, which the test image does not
+  have. Others give the functions behind the subcommands input they take and
+  input they refuse, and check the exit code and what they write to stderr
+- 2026-10-19: when `VERSION` is unset or empty, `script/build` stamps the
+  version from `git describe --tags --always --dirty`, as `script/docker` does
+  ([#156](https://git.eeqj.de/sneak/netwatch/issues/156)). Without `--tags` it
+  skipped lightweight tags, so `make run` could report a commit where the image
+  built from the same tree reported the tag. Checked once with a lightweight tag
+  on a scratch clone: `make build` stamped it
+- 2026-10-19: `.dockerignore` keeps Go test binaries and coverage output at the
+  root out of the build context, with `/*.test` and `/*.out` in the repository's
+  own section ([#155](https://git.eeqj.de/sneak/netwatch/issues/155)). Such
+  files went into the build context of every `docker build` in `script/` and
+  were copied into the lint, test and build stages. Checked with a probe image
+  that copies the whole context: `x.test` and `x.out` planted at the root no
+  longer land in it, and nothing else changed. The entries match only at the
+  root, so the same files in a subdirectory still reach the image
+- 2026-10-19: `.gitea/workflows/check.yml` is the sneak/prompts copy at
+  `0653579` ([#153](https://git.eeqj.de/sneak/netwatch/issues/153)). Its
+  checkout step sets `fetch-depth: 0`, so CI clones all history and tags, and
+  `git describe` in `script/cibuild` gives the image built from a tagged commit
+  the tag as its version; it gave the short commit. The checkout step also sets
+  `persist-credentials: false`, so the job's token is not left in `.git/config`.
+  A new push cancels the older run on the same branch, and a run stops after 20
+  minutes
+- 2026-10-19: `script/bootstrap` keeps the `yarn` on `PATH` only when
+  `yarn --version` is exactly `YARN_VERSION`, and otherwise installs that
+  version as it did when no yarn was installed
+  ([#154](https://git.eeqj.de/sneak/netwatch/issues/154)); any yarn used to be
+  kept. It uses the `node` on `PATH` only when that node has the major version
+  of `NODE_VERSION`, as `REPO_POLICIES.md` asks, and is at least
+  `NODE_MIN_VERSION`; a node 24 was kept before. After installing node or yarn
+  it looks the tool up through `PATH` again and stops if that one fails the same
+  check, as it does for Go, and it prints the node and yarn versions it uses.
+  Every script that runs yarn on the host, except `script/bootstrap`, which
+  picks its own node and yarn, runs it through the new `script/yarn`. That
+  script puts `~/.local/bin` first on `PATH`, uses the first `node` on that
+  `PATH` when it passes the same test, and otherwise runs yarn under the pinned
+  node in nvm; `make build` ran yarn under whatever node was first on `PATH`
+- 2026-10-19: `bin/entrypoint.sh` has each of its steps in a function, and a
+  `main` at the end calls them in order, as the shell section of the code style
+  guide asks ([#163](https://git.eeqj.de/sneak/netwatch/issues/163)). It is
+  still POSIX sh with no `set -e`, and does what it did, with the same messages
+  and exit codes. Checked by running the image with each script: a normal start,
+  bad `PORT`, `TRUSTED_PROXIES` and `DATA_DIR` values, `docker stop`, INT, and
+  nginx exiting on its own
+- 2026-10-19: while report files cannot be written, the health check answers 503
+  with `"status":"error"` and the same fields, so the image's `HEALTHCHECK`
+  reports the container `unhealthy`
+  ([#142](https://git.eeqj.de/sneak/netwatch/issues/142)). It answered 200
+  `"status":"ok"` whatever happened, so the platform saw a healthy container
+  while every report was refused with 500. It answers 200 at start, before any
+  write has failed, and again from the first write that succeeds. A unit test
+  removes `DATA_DIR` to make a write fail and checks the 503, then puts it back
+  and checks the 200 after the next write
+- 2026-10-19: report file writes no longer overlap
+  ([#150](https://git.eeqj.de/sneak/netwatch/issues/150)), so the reports of
+  failed writes are written in the order they arrived. Two writes that failed at
+  the same time put their reports back in the wrong order when the older failed
+  first. One write runs at a time, and each takes the waiting reports only when
+  it starts, after a failed write has put its own back. The write `Append`
+  starts when 10 MiB are waiting waits for any write under way, and `Append`
+  starts no other while it waits. Files written since the start are deleted to
+  make room in the order they were written, after those found at start. A unit
+  test holds a write open, starts a second at 10 MiB, fails both and checks the
+  order in the next file. Others check that `Append` starts no second write at
+  10 MiB while one waits, that it starts one again the next time 10 MiB are
+  waiting, and that the first file written since the start is the first deleted
+- 2026-10-19: `DEBUG` unset or empty leaves debug logging off, and any other
+  value, `false` and `0` included, turns it on, as the code style guide says
+  ([#159](https://git.eeqj.de/sneak/netwatch/issues/159)). No value of it stops
+  the start any more; before, only `1`, `t`, `T`, `TRUE`, `true`, `True`, `0`,
+  `f`, `F`, `FALSE`, `false` and `False` were accepted. `README.md` no longer
+  gives `false` as its default
+- 2026-10-19: check builds keep Go's modules and compiled packages between runs
+  ([#118](https://git.eeqj.de/sneak/netwatch/issues/118)), on sneak's rulings in
+  [prompts#113](https://git.eeqj.de/sneak/prompts/issues/113) and
+  [prompts#130](https://git.eeqj.de/sneak/prompts/issues/130).
+  `REPO_POLICIES.md`, `script/test`, `script/lint`, `script/docker` and
+  `script/cibuild` are the sneak/prompts copies at `0653579`: the scripts pass a
+  new `CACHEBUST` value where they passed `--no-cache`, and the lint and test
+  builds write no image. In each stage of `Dockerfile`, `ARG CACHEBUST` comes
+  after the system packages and the Go module download, and before every step
+  that lints, tests or compiles and the node stages' `yarn install`. Go's build
+  cache and golangci-lint's are cache mounts, and both `go test` runs carry
+  `-count=1`. The test phase's Go caches used to be in memory, empty on every
+  build
+- 2026-10-19: the three unit tests of a check whose result is discarded (its
+  round given up, the user paused, or the first round) also check that the
+  host's history is still empty, its status still `pending`, and nothing was
+  written to the console
+  ([#151](https://git.eeqj.de/sneak/netwatch/issues/151)). They checked only the
+  row, so a change that recorded the result and skipped only the row would have
+  kept them passing
+- 2026-10-18: when the backend runs on its own, a `DATA_DIR` that cannot be
+  created or read, or where no file can be created, stops the start with an
+  error naming `DATA_DIR` and its value, as the other settings' errors do
+  ([#148](https://git.eeqj.de/sneak/netwatch/issues/148)); the first two named
+  only the path, and the third was found only at the first write of a report
+  file. At start the server creates a file in `DATA_DIR` and removes it. Unit
+  tests start the buffer with `DATA_DIR` below a regular file and with
+  `DATA_DIR` set to `/proc`, and check the error. The report file number is an
+  `atomic.Int64`, as the Go style guide asks for int types
+  ([#161](https://git.eeqj.de/sneak/netwatch/issues/161)); file names are
+  unchanged
+- 2026-10-18: the image's nginx sends the page with `Cache-Control: no-cache`
+  ([#141](https://git.eeqj.de/sneak/netwatch/issues/141)), so a browser that
+  keeps a copy checks with the server that it is current before using it again.
+  The page went out with no `Cache-Control`, so a browser could keep it after a
+  deploy and ask for files under `/assets/` that the new build no longer has,
+  and show an empty page. A path that `location /` answers with the page through
+  its `try_files` fallback gets the same header. `location /` now includes the
+  security headers again, as `/assets/` does, since its own `add_header` drops
+  the server's. `/assets/` keeps its immutable caching.
+  `make frontend-viewport-test` fails unless `/` and a path that falls back to
+  the page carry `Cache-Control: no-cache` and `Content-Security-Policy`, which
+  comes from the same file as the other security headers
+- 2026-10-18: `README.md` says what the page loses while reports are refused or
+  the page is paused ([#145](https://git.eeqj.de/sneak/netwatch/issues/145)),
+  how fast one address can replace the stored reports
+  ([#146](https://git.eeqj.de/sneak/netwatch/issues/146)), and that in the image
+  nginx answers a body over 1 MiB itself
+  ([#147](https://git.eeqj.de/sneak/netwatch/issues/147)). A sample in the
+  history that no report has delivered is sent only as long as the history holds
+  it: at the 1-second interval one refused or failed report loses the oldest 20
+  seconds of each host's samples, and a pause longer than the history loses
+  every sample between the last delivered report and the pause. Samples an
+  interval change cleared are kept apart, the last 100 per host, until they are
+  delivered. At the defaults, one address sending 1 MiB reports made up to
+  compress badly can fill the 1 GiB cap in about 17 minutes. nginx's
+  `client_max_body_size` is also 1 MiB by default, so in the image it answers a
+  larger body with 413 and its own HTML page, and the backend never sees or
+  records it; the backend's own 413 sentences now say they apply to it run on
+  its own. The reporter, the body limit and nginx are unchanged
+- 2026-10-18: a browser that cannot format the header's clocks still probes
+  ([#149](https://git.eeqj.de/sneak/netwatch/issues/149)). The clocks name the
+  local time zone through `Intl.DateTimeFormat`'s `shortGeneric` option, which
+  Chrome before 95, Firefox before 91 and Safari before 15.4 reject with an
+  error; it came before the first round started, so such a browser never checked
+  a target. The clocks now start last, after the rounds, and an error formatting
+  them leaves both blank. The footer's color legend reads `>=500ms` for red,
+  where it read `>500ms`, so 500 ms, which is red, is in one of its colors
+  ([#152](https://git.eeqj.de/sneak/netwatch/issues/152)). Unit tests check the
+  clocks with a working `Intl.DateTimeFormat` and with one that rejects
+  `shortGeneric`, and draw the page and check the legend against every entry of
+  `CONFIG.latencyColors`
+- 2026-10-18: `netwatch-server prepare-data-dir` no longer changes the owner of
+  a file outside `/data` through a hard link in the volume
+  ([#143](https://git.eeqj.de/sneak/netwatch/issues/143)). A file with a second
+  name (hard link) keeps its owner, and the start logs its path. Owners are now
+  set on the opened directory, file or link, never by name, so a hard link
+  swapped in after the check is caught too; a symbolic link is opened without
+  following it and given to the netwatch user itself, so the server can still
+  follow one in a sticky directory that anyone can write to. Devices, named
+  pipes and sockets keep their owner. Setting the owner on an open file that is
+  not a directory is built only for Linux: `prepare-data-dir` runs only in the
+  Linux image, and macOS, where the backend is also built for development, has
+  neither `O_PATH` nor `AT_EMPTY_PATH`. On any other system the package still
+  builds, and `prepare-data-dir` fails at the first file that is not a
+  directory. The test that runs as root hard-links a file, a symbolic link and a
+  named pipe from outside the volume into it and finds their owners unchanged
+- 2026-10-18: from a trusted proxy, the backend takes the client address from
+  the right-most `X-Forwarded-For` entry that is not in `TRUSTED_PROXIES`
+  ([#144](https://git.eeqj.de/sneak/netwatch/issues/144)). It took the left-most
+  entry, which the client writes itself behind a proxy that appends to the
+  header, so a client could choose the address the rate limit counts and the
+  request log records. An entry written as an address with a port is read as
+  that address. With only trusted addresses in the header, or an entry that is
+  not an address at all (such as `unknown`) met on the way, the direct peer is
+  used. `X-Real-IP` is read only without `X-Forwarded-For`, and every
+  `X-Forwarded-For` header line is read, not only the first. The image's nginx,
+  and the `TRUSTED_PROXIES=127.0.0.1/32` it starts the backend with, are
+  unchanged; the comment in `configs/nginx.conf` that said the backend takes the
+  first entry now says it takes the one address nginx passes on. Unit tests
+  resolve the address from chains ending in an untrusted address, in trusted
+  ones, of only trusted ones, with ports, with an entry that is not an address,
+  and split over two header lines
+- 2026-10-18: after an interval change, the summary's Reachable slot reads
+  `--/--` in white, as at page load, until the second round since the change
+  ends ([#140](https://git.eeqj.de/sneak/netwatch/issues/140)). It used to read
+  0/26 in red from the change on, as no WAN host had a check recorded, for up to
+  two intervals with the network fine. The summary update now writes `--/--`
+  while every WAN host still waits for its first check. A unit test resets the
+  hosts as the interval menu does and checks the slot; another checks that it
+  reads 0/26 in red once every WAN host's check has failed
+- 2026-10-14: stopping the server waits for a report file write already under
+  way, the periodic flush's or the one `Append` starts when 10 MiB are waiting,
+  before the final flush
+  ([#122](https://git.eeqj.de/sneak/netwatch/issues/122)). It used to return at
+  once, and the process exiting cut the write off, losing its reports. A write
+  under way that fails puts its reports back in memory, so the final flush
+  writes them; the stop fails, and the process exits non-zero, only if that
+  flush fails too. Two tests hold the periodic write and the one at 10 MiB open
+  and find the stop waiting until each is released; a third makes the held write
+  fail and finds its report written by the final flush. They run in a
+  `testing/synctest` bubble, so the periodic flush comes without waiting a
+  minute
+- 2026-10-14: `make test` no longer runs the frontend's production build, which
+  the tests do not need ([#118](https://git.eeqj.de/sneak/netwatch/issues/118)).
+  `yarn build` moved out of the stage that runs the frontend's unit tests, now
+  named `frontend-test`, into a new `frontend-build` stage, which starts from it
+  and, like the `builder` stage, waits on the lint and test phases, so the image
+  still cannot be built unless they pass. The runtime stage copies `dist/` from
+  it, and the `git` that `vite.config.js` reads the commit with is installed
+  there. No build cache was added
+- 2026-10-14: opening the debug log no longer raises the measured latencies
+  ([#131](https://git.eeqj.de/sneak/netwatch/issues/131)). With the panel open,
+  each line written drew the panel again with every line before it, up to 1000,
+  and a check that ends while the page draws is timed only when the drawing is
+  done. Each line is now added at the end of the open panel, its first line is
+  dropped once it holds more than 1000, and it scrolls to its newest line once a
+  frame rather than once a line; the whole panel is drawn only when it is
+  opened. A unit test writes more lines than the panel keeps and checks that the
+  lines already shown are left as they are
+- 2026-10-14: unset, the backend's own `TRUSTED_PROXIES` trusts `10.0.0.0/8`,
+  `172.16.0.0/12` and `192.168.0.0/16`, and no longer loopback; a list replaces
+  that; set and empty, it trusts no proxy, where it used to get the default, as
+  viper reads an empty environment variable as unset
+  ([#129](https://git.eeqj.de/sneak/netwatch/issues/129)). A value it cannot
+  parse still stops the start, and the image still starts the backend with
+  `TRUSTED_PROXIES=127.0.0.1/32`. Tests load the config with it unset, empty and
+  set to a list
+- 2026-10-14: while report files cannot be written, `POST /api/v1/reports`
+  answers 500, and storing recovers once writing works again, with no restart
+  ([#123](https://git.eeqj.de/sneak/netwatch/issues/123)). A failed write puts
+  its reports back in the report buffer, still counted against
+  `DATA_DIR_MAX_BYTES`, where they used to be lost; the next flush, within a
+  minute, tries them again. Until a write succeeds, every report is refused and
+  nothing of it is kept, so the buffer does not grow while writes fail. A test
+  posts reports through the report handler before, during and after a failure;
+  others check that a report appended while a write runs is kept, behind that
+  write's own, when the write fails, and that the cap still holds exactly once a
+  failed write's reports are written
+- 2026-10-14: a request whose handler panics is logged with status 500 and
+  counted with `code` 500 in the metrics
+  ([#125](https://git.eeqj.de/sneak/netwatch/issues/125)), not 200. `Recoverer`
+  is still the first middleware; `Write500OnPanic`, after the request log and
+  after the metrics, writes the 500 as the panic passes and lets it go on to
+  Sentry and `Recoverer`, which now writes a 500 only when no status was written
+- 2026-10-14: with `TRUSTED_PROXIES` unset, the container's nginx trusts the
+  three private ranges of RFC 1918, `10.0.0.0/8`, `172.16.0.0/12` and
+  `192.168.0.0/16` ([#119](https://git.eeqj.de/sneak/netwatch/issues/119)), as
+  sneak ruled on 2026-09-22 for every app; it trusted no proxy before. A list
+  replaces them, and set and empty it trusts none. The backend inside the
+  container still trusts only `127.0.0.1/32`
+- 2026-10-14: `POST /api/v1/reports` takes only a report sent with
+  `Content-Type: application/json`, parameters such as `charset` allowed, and
+  refuses any other with 415 and the usual error body, storing nothing
+  ([#126](https://git.eeqj.de/sneak/netwatch/issues/126)). A page on another
+  origin can send a `text/plain` POST without a CORS preflight, so any site
+  could make its visitors' browsers store reports; a JSON POST waits for the
+  preflight, which only an origin in `CORS_ALLOWED_ORIGINS` passes. The page
+  already sent `application/json`. A test posts a report as `text/plain`, as
+  `application/x-www-form-urlencoded`, as `multipart/form-data`, with no
+  `Content-Type`, and as `application/json` with and without a charset, and
+  checks which are stored
+- 2026-10-14: changing the interval no longer drops the samples not yet reported
+  to the backend ([#124](https://git.eeqj.de/sneak/netwatch/issues/124)). The
+  interval menu resets each host with the new `HostState.reset`, which moves the
+  history's entries to `clearedHistory`, keeping the last 100 of all it has
+  cleared, and `buildReport` reads both, so the next report has the samples
+  recorded before the change that no report has delivered. Until its next check,
+  such a host is sent with the status of its last check, not `pending`. The
+  page's history still starts over, and the per-host marks still leave out of a
+  report the samples a delivered one had. Unit tests reset a host as the
+  interval menu does and find its unreported samples in the next report, and
+  only the last 100 after more were cleared; `web/src/main.js` now exports
+  `Reporter` for them
+- 2026-10-14: the repo has the layout `REPO_POLICIES.md` gives
+  ([#30](https://git.eeqj.de/sneak/netwatch/issues/30)). The Go module is at the
+  root (`go.mod`, `go.sum`, `.golangci.yml`, `cmd/netwatch-server/`,
+  `internal/`), so its path `sneak.berlin/go/netwatch` names the repository.
+  `go.mod` ignores `node_modules/`, where npm packages can ship `.go` files that
+  `make tidy` would otherwise read as this module's packages. The page's source
+  is in `web/` (`index.html`, `src/`), which `vite.config.js` makes Vite's root;
+  the build still goes to `dist/`. `nginx.conf` and `security-headers.conf` are
+  in `configs/`. `backend/` is gone: its `LICENSE` and `.dockerignore` are
+  deleted, its `.gitignore` entries are in the root one, its `README.md` is
+  folded into the root `README.md`, and its scripts into the root `script/`:
+  `script/build` builds the server binary after the frontend, `script/run` and
+  `script/clean` came from `backend/script/`, and `make test`, `make lint`,
+  `make fmt` and `make fmt-check` do what its `test`, `lint`, `fmt` and
+  `fmt-check` did. `script/bootstrap` no longer installs gcc, which only the
+  host Go tests needed. The image and the page are unchanged
 - 2026-10-07: the files shared from `sneak/prompts` are its copies at commit
   `dd4027b` ([#113](https://git.eeqj.de/sneak/netwatch/issues/113)), with this
   repository's own entries after the shared content in `.gitignore`,
@@ -416,8 +742,6 @@ Decide whether the repo moves to the layout `REPO_POLICIES.md` gives, with
 
 # Future Steps
 
-- Run `make frontend-viewport-test` in CI as its own step; it is not part of
-  `make check`, as it needs Docker and takes minutes
 - A backend test that posts a report to `POST /api/v1/reports` and checks the
   compressed file it is written to
 - A backend route that decompresses the stored reports and answers queries on

backend/.dockerignore

@@ -1,2 +0,0 @@
-node_modules
-.DS_Store

backend/.gitignore

@@ -1,6 +0,0 @@
-/netwatch-server
-*.log
-*.out
-*.test
-.env
-data/

backend/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2026 @sneak (https://sneak.berlin)
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.

backend/Makefile

@@ -1,30 +0,0 @@
-# Thin shims; the implementations live in backend/script/ (see the
-# Entrypoints section of README.md). There is no check, hooks or docker
-# target here: the root Makefile's check covers this directory, its
-# hooks target installs the repo's only pre-commit hook, and its docker
-# target builds the one image, which contains this backend.
-
-.PHONY: all build test lint fmt fmt-check run clean
-
-all: build
-
-build:
-	@script/build
-
-test:
-	@script/test
-
-lint:
-	@script/lint
-
-fmt:
-	@script/fmt
-
-fmt-check:
-	@script/fmt-check
-
-run:
-	@script/run
-
-clean:
-	@script/clean

backend/README.md

@@ -1,232 +0,0 @@
-netwatch-server is an MIT-licensed Go HTTP backend by
-[@sneak](https://sneak.berlin) that receives telemetry reports from the NetWatch
-SPA and persists them as zstd-compressed JSONL files on disk.
-
-## Getting Started
-
-From this directory:
-
-```bash
-# Build and run locally
-make run
-```
-
-From the repo root, whose `Dockerfile` builds the one image that ships this
-backend behind nginx (see [Container image](#container-image)):
-
-```bash
-# Run tests, lint, and format check over the frontend and this backend
-make check
-
-# Build the image: nginx, the frontend and this backend
-make docker
-docker run -p 8080:8080 netwatch
-```
-
-## Entrypoints
-
-This directory follows the same
-[Scripts to Rule Them All](https://github.com/github/scripts-to-rule-them-all)
-pattern as the repo root: the targets in `backend/Makefile` are thin shims over
-`backend/script/`. The root `Dockerfile` runs `build`, and the root scripts call
-`fmt` and `fmt-check`:
-
-- `script/build` — compile the static `netwatch-server` binary with its version
-  stamped in. The version is `VERSION` from the environment; when that is unset
-  or empty, it falls back to `git describe` inside a git checkout, then to `dev`
-- `script/test` — run the Go tests on the host with the race detector and
-  coverage; the root `make test` runs them in the `test` phase of the root
-  `Dockerfile`. Go's `-timeout 90s` bounds the tests, not their compile, and
-  `-count=1` keeps Go from reporting a stored pass. If they fail, they run again
-  with `-v` for the details, and the script fails. The race detector needs a C
-  compiler
-- `script/lint` — run the root `script/lint`, which builds the `lint` phase of
-  the root `Dockerfile`: golangci-lint over this directory, and eslint over the
-  frontend. golangci-lint never runs on the host
-- `script/fmt` — format the Go sources (writes)
-- `script/fmt-check` — check Go formatting (read-only)
-- `script/run` — build and run the server locally
-- `script/clean` — remove build artifacts
-
-There is no `check`, `hooks` or `docker` target here: the root `make check`
-covers this directory, the root `make hooks` installs the repo's only pre-commit
-hook, and the root `make docker` builds the image that contains this backend.
-
-## Rationale
-
-The NetWatch frontend collects latency measurements from the browser but has no
-way to persist or aggregate them. This backend provides a minimal
-`POST /api/v1/reports` endpoint that buffers incoming reports in memory and
-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/`. Internal packages in `internal/` follow standard Go
-project layout:
-
-- **`config`**: Loads configuration from environment variables and config files
-  via Viper.
-- **`handlers`**: HTTP request handlers for the API (health check, report
-  ingestion).
-- **`reportbuf`**: In-memory buffer that accumulates JSONL report lines and
-  flushes to zstd-compressed files when the buffer reaches 10 MiB or every 60
-  seconds.
-- **`server`**: Chi-based HTTP server with middleware wiring and route
-  registration.
-- **`healthcheck`**, **`middleware`**, **`logger`**, **`globals`**: Supporting
-  infrastructure.
-
-### Configuration
-
-| Variable               | Default              | Description                                                                                              |
-| ---------------------- | -------------------- | -------------------------------------------------------------------------------------------------------- |
-| `BIND_ADDRESS`         | empty                | IP address to listen on; empty listens on every interface                                                |
-| `PORT`                 | `8080`               | HTTP listen port                                                                                         |
-| `DATA_DIR`             | `./data/reports`     | Directory for compressed reports                                                                         |
-| `DATA_DIR_MAX_BYTES`   | `1073741824` (1 GiB) | Most bytes of report files kept in `DATA_DIR`, oldest deleted first; see [Report limits](#report-limits) |
-| `DEBUG`                | `false`              | Enable debug logging                                                                                     |
-| `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)                                              |
-| `SENTRY_DSN`           | empty                | DSN of the Sentry project to send errors to; see [Sentry](#sentry)                                       |
-
-`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`. The loopback
-entries cover a reverse proxy on the same host. A request whose direct peer is
-outside this set has its forwarded headers ignored, and the direct peer is
-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
-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/`, `/.well-known/healthcheck` and
-`/metrics` to this server. The image's entrypoint, `bin/entrypoint.sh`, starts
-the server as user `netwatch` (uid 1000) with `BIND_ADDRESS=127.0.0.1` and
-`PORT=8081`, so only nginx reaches it, and with `TRUSTED_PROXIES=127.0.0.1/32`,
-so it takes the client address nginx passes on and no other. `DATA_DIR` is
-`/data/reports`, on the `/data` volume; before starting the server, the
-entrypoint creates it and gives it and `/data` to `netwatch` with
-`netwatch-server prepare-data-dir`, which acts on nothing outside `/data`. nginx
-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.
-nginx takes the client address from `X-Forwarded-For` only on a request from one
-of them. Unset or empty, nginx trusts no proxy, and the client address is the
-one each request comes from, so every client behind a proxy shares one rate
-limit. An entry that is not an IP address or CIDR, such as a hostname or
-`1.2.3`, stops the container at start with an error naming `TRUSTED_PROXIES`:
-the entrypoint checks each entry with `netwatch-server check-cidr`, which parses
-it as this server parses its own `TRUSTED_PROXIES`.
-
-### Report storage
-
-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 and leaves a gap in
-the numbers: its file, if it was created, is removed. The file stays, counted
-toward `DATA_DIR_MAX_BYTES` from the next start, only if removing it fails too.
-Each file contains one JSON object per line, compressed with zstd. Files are
-created with `O_EXCL` to prevent overwrites.
-
-### Report limits
-
-`POST /api/v1/reports` takes reports from anyone who can reach it, without
-credentials, so it is bounded instead. Both refusals below answer with the same
-`{"status":"error"}` body as any other error.
-
-- **Rate limit.** Each client address, resolved through `TRUSTED_PROXIES`, may
-  send `REPORTS_PER_MINUTE` reports a minute; past that it gets 429 with
-  `Retry-After: 60`. The minute slides: reports from the minute before still
-  count, fading out over the current one, so an address is sure never to be
-  refused only while it sends at most half of `REPORTS_PER_MINUTE` in any 60
-  seconds. The page sends one report a minute from each open tab, so the default
-  of 60 refuses nothing from up to 30 tabs behind one address, such as a
-  household or an office sharing it, however their reports bunch up. Report
-  responses also carry `X-RateLimit-Limit`, `X-RateLimit-Remaining` and
-  `X-RateLimit-Reset` headers.
-- **Size cap.** The report files in `DATA_DIR` may total at most
-  `DATA_DIR_MAX_BYTES`, counting the files already there at start. Reports
-  waiting in memory count at their uncompressed size until they are written;
-  those lost to a failed write stop counting, and the part of its file written
-  is removed. When a report would take the total past the cap, the oldest report
-  files are deleted to make room, and each deletion is logged with the file's
-  name and size; a file still being written is never deleted. A report is
-  refused with 507, and nothing of it is stored, only when the reports waiting
-  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 `DATA_DIR`.
-
-### CORS
-
-The page calls the API from the origin it is served from, so by default the
-server sends no CORS headers, and browsers let no other origin's pages call it.
-To serve the page from elsewhere, list that origin in `CORS_ALLOWED_ORIGINS`
-(for example `https://netwatch.example.com`); pages from a listed origin may
-`GET` and `POST` with a `Content-Type` header. Each entry must be a plain
-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.
-
-`/metrics` is rate limited, so that its password cannot be guessed quickly: each
-client address, resolved through `TRUSTED_PROXIES`, may make 60 requests to it a
-minute, whatever their credentials. Past that it gets 429 with
-`Retry-After: 60`, and its credentials are not checked. The minute slides as it
-does for reports (see [Report limits](#report-limits)), so a scraper polling
-every 2 seconds or less often is never refused. This allowance is apart from the
-one for reports.
-
-### Sentry
-
-With `SENTRY_DSN` set, the server sends its errors to that Sentry project: each
-panic in a handler is reported there, under the release `netwatch-server-`
-followed by the server's version, and the request still gets 500 from the
-server's panic recovery. On shutdown the server waits up to 2 seconds for Sentry
-to finish sending. A DSN Sentry refuses stops the server from starting, with an
-error naming `SENTRY_DSN`. With it empty, Sentry is not set up, and nothing is
-sent to it.
-
-## TODO
-
-The to-do list, this backend's open work included, is [TODO.md](../TODO.md) at
-the repo root.
-
-## License
-
-MIT. See [LICENSE](LICENSE).
-
-## Author
-
-[@sneak](https://sneak.berlin)

backend/cmd/netwatch-server/main.go

@@ -1,89 +0,0 @@
-// Package main is the entry point for netwatch-server.
-package main
-
-import (
-	"fmt"
-	"os"
-	"os/user"
-
-	"sneak.berlin/go/netwatch/internal/config"
-	"sneak.berlin/go/netwatch/internal/globals"
-	"sneak.berlin/go/netwatch/internal/handlers"
-	"sneak.berlin/go/netwatch/internal/healthcheck"
-	"sneak.berlin/go/netwatch/internal/logger"
-	"sneak.berlin/go/netwatch/internal/middleware"
-	"sneak.berlin/go/netwatch/internal/reportbuf"
-	"sneak.berlin/go/netwatch/internal/server"
-
-	"go.uber.org/fx"
-	"go.uber.org/fx/fxevent"
-)
-
-//nolint:gochecknoglobals // set via ldflags at build time
-var (
-	Appname = "netwatch-server"
-	Version string
-)
-
-func main() {
-	// "netwatch-server check-cidr CIDR" exits 1, with the error, if
-	// this server would refuse CIDR in its TRUSTED_PROXIES.
-	// bin/entrypoint.sh runs it on each entry it gives nginx.
-	if len(os.Args) == 3 && os.Args[1] == "check-cidr" {
-		_, err := middleware.ParseTrustedProxies(os.Args[2:])
-		if err != nil {
-			fmt.Fprintln(os.Stderr, err)
-			os.Exit(1)
-		}
-
-		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,
-			handlers.New,
-			healthcheck.New,
-			logger.New,
-			middleware.New,
-			reportbuf.New,
-			server.New,
-		),
-		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/internal/handlers/healthcheck.go

@@ -1,11 +0,0 @@
-package handlers
-
-import "net/http"
-
-// HandleHealthCheck returns a handler for the health check
-// endpoint.
-func (s *Handlers) HandleHealthCheck() http.HandlerFunc {
-	return func(w http.ResponseWriter, r *http.Request) {
-		s.respondJSON(w, r, s.hc.Healthcheck(), http.StatusOK)
-	}
-}

backend/internal/reportbuf/reportbuf_test.go

@@ -1,919 +0,0 @@
-package reportbuf_test
-
-import (
-	"encoding/json"
-	"errors"
-	"fmt"
-	"io/fs"
-	"os"
-	"path/filepath"
-	"slices"
-	"strconv"
-	"strings"
-	"sync"
-	"sync/atomic"
-	"testing"
-	"time"
-
-	"sneak.berlin/go/netwatch/internal/config"
-	"sneak.berlin/go/netwatch/internal/globals"
-	"sneak.berlin/go/netwatch/internal/logger"
-	"sneak.berlin/go/netwatch/internal/reportbuf"
-
-	"github.com/klauspost/compress/zstd"
-	"go.uber.org/fx"
-	"go.uber.org/fx/fxtest"
-)
-
-// TestFlushOnShutdown proves the flush-on-shutdown path: a
-// report appended after start but before the periodic flush
-// window must reach disk when the fx lifecycle stops. This is
-// the exact case that silent data loss on restart used to
-// destroy.
-func TestFlushOnShutdown(t *testing.T) {
-	dir := t.TempDir()
-	t.Setenv("DATA_DIR", dir)
-
-	var buf *reportbuf.Buffer
-
-	app := fxtest.New(t,
-		fx.Provide(
-			globals.New,
-			logger.New,
-			config.New,
-			reportbuf.New,
-		),
-		fx.Populate(&buf),
-	)
-
-	app.RequireStart()
-
-	err := buf.Append(map[string]string{"probe": "shutdown"})
-	if err != nil {
-		t.Fatalf("append report: %v", err)
-	}
-
-	// RequireStop runs the reportbuf OnStop hook, which is the
-	// only code path that flushes buffered reports on shutdown.
-	app.RequireStop()
-
-	if !hasReportFile(t, dir) {
-		t.Fatal("no report file on disk after shutdown; " +
-			"the buffered report was lost")
-	}
-}
-
-// TestFailedFinalFlushFailsStop proves a final flush that cannot
-// write its file makes the stop fail, which makes the process
-// exit non-zero instead of dropping the buffered reports silently.
-func TestFailedFinalFlushFailsStop(t *testing.T) {
-	dir := t.TempDir()
-	t.Setenv("DATA_DIR", dir)
-
-	var buf *reportbuf.Buffer
-
-	app := fxtest.New(t,
-		fx.Provide(
-			globals.New,
-			logger.New,
-			config.New,
-			reportbuf.New,
-		),
-		fx.Populate(&buf),
-	)
-
-	app.RequireStart()
-
-	err := buf.Append(map[string]string{"probe": "shutdown"})
-	if err != nil {
-		t.Fatalf("append report: %v", err)
-	}
-
-	// Removing the data directory leaves the final flush nowhere to
-	// write. A read-only directory would not do: tests run as root
-	// in the backend image, and root ignores the read-only bit.
-	err = os.RemoveAll(dir)
-	if err != nil {
-		t.Fatalf("remove data dir: %v", err)
-	}
-
-	err = app.Stop(t.Context())
-	if !errors.Is(err, fs.ErrNotExist) {
-		t.Fatalf("stop error = %v, want the final flush's error", err)
-	}
-}
-
-// startBuffer starts a Buffer through fx, as main does, with the
-// DATA_DIR and DATA_DIR_MAX_BYTES the calling test has set.
-func startBuffer(t *testing.T) *reportbuf.Buffer {
-	t.Helper()
-
-	var buf *reportbuf.Buffer
-
-	app := fxtest.New(t,
-		fx.Provide(
-			globals.New,
-			logger.New,
-			config.New,
-			reportbuf.New,
-		),
-		fx.Populate(&buf),
-	)
-
-	app.RequireStart()
-	t.Cleanup(app.RequireStop)
-
-	return buf
-}
-
-// lineBytes is what one report takes in the buffer: its JSON and a
-// newline.
-func lineBytes(t *testing.T, report any) int {
-	t.Helper()
-
-	line, err := json.Marshal(report)
-	if err != nil {
-		t.Fatalf("marshal report: %v", err)
-	}
-
-	return len(line) + 1
-}
-
-// TestAppendPastCapIsRefused fills the cap with a report not yet
-// written. The next report is refused, and the report file already in
-// DATA_DIR is kept: it is smaller than a report, so deleting it could
-// not make room.
-func TestAppendPastCapIsRefused(t *testing.T) {
-	report := map[string]string{"id": "cap"}
-	dir := t.TempDir()
-	earlier := reportFilePath(dir, 1)
-
-	writeBytes(t, earlier, 1)
-
-	t.Setenv("DATA_DIR", dir)
-	t.Setenv("DATA_DIR_MAX_BYTES", strconv.Itoa(1+lineBytes(t, report)))
-
-	buf := startBuffer(t)
-
-	err := buf.Append(report)
-	if err != nil {
-		t.Fatalf("report that fills the cap exactly: %v", err)
-	}
-
-	err = buf.Append(report)
-	if !errors.Is(err, reportbuf.ErrFull) {
-		t.Fatalf("report past the cap: error = %v, want ErrFull", err)
-	}
-
-	if !exists(t, earlier) {
-		t.Fatal("report file deleted, though that could not make room")
-	}
-}
-
-// TestOldestReportFileDeletedFirst starts on a data directory holding
-// report files from an earlier run, and a file that is not a report,
-// which neither counts nor is ever deleted. Nothing is deleted while
-// there is room; then only the oldest report file is.
-func TestOldestReportFileDeletedFirst(t *testing.T) {
-	const fileBytes = 100
-
-	report := map[string]string{"id": "oldest"}
-	dir := t.TempDir()
-	oldest := reportFilePath(dir, 1)
-	kept := []string{
-		reportFilePath(dir, 2),
-		reportFilePath(dir, 3),
-		filepath.Join(dir, "notes.txt"),
-	}
-
-	writeBytes(t, oldest, fileBytes)
-
-	for _, path := range kept {
-		writeBytes(t, path, fileBytes)
-	}
-
-	t.Setenv("DATA_DIR", dir)
-	// Room for the three report files and one report.
-	t.Setenv("DATA_DIR_MAX_BYTES",
-		strconv.Itoa(3*fileBytes+lineBytes(t, report)))
-
-	buf := startBuffer(t)
-
-	err := buf.Append(report)
-	if err != nil {
-		t.Fatalf("report that fills the cap exactly: %v", err)
-	}
-
-	if !exists(t, oldest) {
-		t.Fatal("oldest report file deleted while there was room")
-	}
-
-	err = buf.Append(report)
-	if err != nil {
-		t.Fatalf("report past the cap: %v", err)
-	}
-
-	if exists(t, oldest) {
-		t.Fatal("oldest report file kept when room was needed")
-	}
-
-	for _, path := range kept {
-		if !exists(t, path) {
-			t.Fatalf("%s deleted; only the oldest report file should be", path)
-		}
-	}
-}
-
-// TestStartDeletesFilesPastCap starts on report files past the cap,
-// as after the cap is lowered: the oldest are deleted until the rest
-// fit.
-func TestStartDeletesFilesPastCap(t *testing.T) {
-	const fileBytes = 100
-
-	dir := t.TempDir()
-	oldest := reportFilePath(dir, 1)
-	kept := []string{reportFilePath(dir, 2), reportFilePath(dir, 3)}
-
-	writeBytes(t, oldest, fileBytes)
-
-	for _, path := range kept {
-		writeBytes(t, path, fileBytes)
-	}
-
-	t.Setenv("DATA_DIR", dir)
-	t.Setenv("DATA_DIR_MAX_BYTES", strconv.Itoa(len(kept)*fileBytes))
-
-	startBuffer(t)
-
-	if exists(t, oldest) {
-		t.Fatal("oldest report file kept, though the files were past the cap")
-	}
-
-	for _, path := range kept {
-		if !exists(t, path) {
-			t.Fatalf("%s deleted, though the rest fit without it", path)
-		}
-	}
-}
-
-// TestWrittenReportsCountAtFileSize checks that once reports are
-// written, they count as their compressed file, not their
-// uncompressed size, which frees room under the cap.
-func TestWrittenReportsCountAtFileSize(t *testing.T) {
-	// Repetitive, so its file is far smaller than its JSON.
-	report := map[string]string{"id": strings.Repeat("a", 1000)}
-	size := lineBytes(t, report)
-	dir := t.TempDir()
-
-	t.Setenv("DATA_DIR", dir)
-	// Room for the report twice over only if the first one counts
-	// at its file's size by the time the second arrives.
-	t.Setenv("DATA_DIR_MAX_BYTES", strconv.Itoa(2*size-1))
-
-	buf := startBuffer(t)
-
-	err := buf.Append(report)
-	if err != nil {
-		t.Fatalf("first report: %v", err)
-	}
-
-	err = buf.Flush()
-	if err != nil {
-		t.Fatalf("flush: %v", err)
-	}
-
-	err = buf.Append(report)
-	if err != nil {
-		t.Fatalf("second report, after the first was written: %v", err)
-	}
-
-	if !hasReportFile(t, dir) {
-		t.Fatal("first report's file deleted, though the second fit beside it")
-	}
-}
-
-// TestWrittenFilesDeletedToMakeRoom writes one report file after
-// another under a small cap. Every report must be taken; files are
-// deleted only when the report would not fit beside them, and the
-// files kept leave room for it.
-func TestWrittenFilesDeletedToMakeRoom(t *testing.T) {
-	const (
-		maxBytes = 200
-		// One file each, which take far more than maxBytes together.
-		reports = 50
-	)
-
-	report := map[string]string{"id": "written"}
-	size := int64(lineBytes(t, report))
-	dir := t.TempDir()
-
-	t.Setenv("DATA_DIR", dir)
-	t.Setenv("DATA_DIR_MAX_BYTES", strconv.Itoa(maxBytes))
-
-	buf := startBuffer(t)
-
-	for range reports {
-		before := reportFilesBytes(t, dir)
-
-		err := buf.Append(report)
-		if err != nil {
-			t.Fatalf("with %d bytes of report files: %v", before, err)
-		}
-
-		after := reportFilesBytes(t, dir)
-
-		if before+size <= maxBytes && after != before {
-			t.Fatalf("files deleted, though the report fit beside "+
-				"their %d bytes", before)
-		}
-
-		if after+size > maxBytes {
-			t.Fatalf("%d bytes of report files kept, leaving no room "+
-				"for the report", after)
-		}
-
-		err = buf.Flush()
-		if err != nil {
-			t.Fatalf("flush: %v", err)
-		}
-	}
-}
-
-// TestFailedDeletionStillCounts makes deleting the oldest report file
-// fail. It is still there, so it still takes room, and the next oldest
-// is deleted in its place.
-func TestFailedDeletionStillCounts(t *testing.T) {
-	const fileBytes = 100
-
-	report := map[string]string{"id": "stuck"}
-	dir := t.TempDir()
-	stuck := reportFilePath(dir, 1)
-	next := reportFilePath(dir, 2)
-	newest := reportFilePath(dir, 3)
-
-	for _, path := range []string{stuck, next, newest} {
-		writeBytes(t, path, fileBytes)
-	}
-
-	t.Setenv("DATA_DIR", dir)
-	t.Setenv("DATA_DIR_MAX_BYTES", strconv.Itoa(3*fileBytes))
-
-	buf := startBuffer(t)
-
-	// A directory that is not empty cannot be deleted, even by root,
-	// which the tests run as in the backend image.
-	err := os.Remove(stuck)
-	if err != nil {
-		t.Fatalf("remove %s: %v", stuck, err)
-	}
-
-	err = os.Mkdir(stuck, 0o750)
-	if err != nil {
-		t.Fatalf("make directory %s: %v", stuck, err)
-	}
-
-	writeBytes(t, filepath.Join(stuck, "file"), 1)
-
-	err = buf.Append(report)
-	if err != nil {
-		t.Fatalf("report past the cap: %v", err)
-	}
-
-	if exists(t, next) {
-		t.Fatal("next oldest report file kept: the failed deletion " +
-			"counted as making room")
-	}
-
-	if !exists(t, newest) {
-		t.Fatal("newest report file deleted, though deleting one made room")
-	}
-}
-
-// TestFileDeletedByHandFreesRoom deletes the oldest report file by
-// hand after start. When room is needed, its room counts as freed, so
-// no other file is deleted.
-func TestFileDeletedByHandFreesRoom(t *testing.T) {
-	const fileBytes = 100
-
-	report := map[string]string{"id": "by-hand"}
-	dir := t.TempDir()
-	gone := reportFilePath(dir, 1)
-	kept := reportFilePath(dir, 2)
-
-	writeBytes(t, gone, fileBytes)
-	writeBytes(t, kept, fileBytes)
-
-	t.Setenv("DATA_DIR", dir)
-	t.Setenv("DATA_DIR_MAX_BYTES", strconv.Itoa(2*fileBytes))
-
-	buf := startBuffer(t)
-
-	err := os.Remove(gone)
-	if err != nil {
-		t.Fatalf("remove %s: %v", gone, err)
-	}
-
-	err = buf.Append(report)
-	if err != nil {
-		t.Fatalf("report past the cap: %v", err)
-	}
-
-	if !exists(t, kept) {
-		t.Fatal("report file deleted, though the one deleted by hand " +
-			"had made room")
-	}
-}
-
-// TestFileBeingWrittenIsNeverDeleted holds the write of one report file
-// open while a second write completes, then sends a report that needs
-// room. Deleting either file would make it, and the one being written is
-// 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())
-	// 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)
-
-	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("first report: %v", err)
-	}
-
-	flushed := make(chan error)
-
-	go func() { flushed <- buf.Flush() }()
-
-	writing := <-created
-
-	// 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 err != nil {
-		t.Errorf("second report: %v", 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 of the first report: %v", err)
-	}
-
-	err = buf.Append(report)
-	if err != nil {
-		t.Fatalf("report after the first write was complete: %v", err)
-	}
-
-	if exists(t, writing) {
-		t.Fatal("complete report file kept when room was needed")
-	}
-}
-
-// TestFailedWriteStopsCounting makes a write fail once its file is
-// created. Its reports are lost, so they stop counting, and the part of
-// the file written is removed, so it takes no room.
-func TestFailedWriteStopsCounting(t *testing.T) {
-	report := map[string]string{"id": "failed"}
-
-	t.Setenv("DATA_DIR", t.TempDir())
-	t.Setenv("DATA_DIR_MAX_BYTES", strconv.Itoa(lineBytes(t, report)))
-
-	buf := startBuffer(t)
-
-	var failed string
-
-	// Closing the file under the write makes the write fail.
-	buf.OnFileCreated(func(f *os.File) {
-		failed = f.Name()
-
-		_ = f.Close()
-	})
-
-	err := buf.Append(report)
-	if err != nil {
-		t.Fatalf("report that fills the cap exactly: %v", err)
-	}
-
-	err = buf.Flush()
-	if err == nil {
-		t.Fatal("flush succeeded, though its file was closed under it")
-	}
-
-	if exists(t, failed) {
-		t.Fatal("file of the failed write kept")
-	}
-
-	// Writes from here on, the final one at stop included, succeed.
-	buf.OnFileCreated(func(*os.File) {})
-
-	err = buf.Append(report)
-	if err != nil {
-		t.Fatalf("report after the failed write: %v", err)
-	}
-}
-
-// TestConcurrentAppendsStopAtCap appends from many goroutines at once
-// with room for exactly roomFor reports: exactly that many must be
-// taken, which holds only if Append checks and counts each report
-// under one lock.
-func TestConcurrentAppendsStopAtCap(t *testing.T) {
-	const (
-		roomFor = 5
-		senders = 50
-	)
-
-	// Large, so each Append takes long enough for the senders to
-	// overlap while the cap is reached.
-	report := map[string]string{"id": strings.Repeat("a", 1_000_000)}
-
-	t.Setenv("DATA_DIR", t.TempDir())
-	t.Setenv("DATA_DIR_MAX_BYTES",
-		strconv.Itoa(roomFor*lineBytes(t, report)))
-
-	buf := startBuffer(t)
-
-	var (
-		taken atomic.Int64
-		wg    sync.WaitGroup
-	)
-
-	start := make(chan struct{})
-
-	for range senders {
-		wg.Go(func() {
-			<-start
-
-			err := buf.Append(report)
-			if err == nil {
-				taken.Add(1)
-			} else if !errors.Is(err, reportbuf.ErrFull) {
-				t.Errorf("append: %v", err)
-			}
-		})
-	}
-
-	close(start)
-	wg.Wait()
-
-	if got := taken.Load(); got != roomFor {
-		t.Fatalf("%d reports taken, want %d", got, roomFor)
-	}
-}
-
-// TestTwoFlushesInOneMillisecond flushes twice within one millisecond,
-// as a flush for size and the final flush at shutdown can: each flush
-// must write a file of its own, and the files must hold every report.
-func TestTwoFlushesInOneMillisecond(t *testing.T) {
-	const flushes = 2
-
-	dir := t.TempDir()
-	t.Setenv("DATA_DIR", dir)
-
-	buf := startBuffer(t)
-	buf.StopClock(time.Date(2026, 1, 1, 0, 0, 0, 0, time.UTC))
-
-	for id := 1; id <= flushes; id++ {
-		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 %d: %v", id, err)
-		}
-	}
-
-	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)
-	}
-
-	for id := 1; id <= flushes; id++ {
-		want := fmt.Sprintf(`{"id":%d}`+"\n", id)
-		if !slices.Contains(files, want) {
-			t.Fatalf("no report file holds report %d alone", id)
-		}
-	}
-}
-
-// 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()
-
-	paths, err := filepath.Glob(filepath.Join(dir, "reports-*.jsonl.zst"))
-	if err != nil {
-		t.Fatalf("list report files: %v", err)
-	}
-
-	var total int64
-
-	for _, path := range paths {
-		info, statErr := os.Stat(path)
-		if statErr != nil {
-			t.Fatalf("stat %s: %v", path, statErr)
-		}
-
-		total += info.Size()
-	}
-
-	return total
-}
-
-// readReportFiles returns the decompressed contents of each report
-// file in dir. A file still being written does not decompress, so it
-// gives an error.
-func readReportFiles(dir string) ([]string, error) {
-	files := os.DirFS(dir)
-
-	names, err := fs.Glob(files, "reports-*.jsonl.zst")
-	if err != nil {
-		return nil, fmt.Errorf("list report files: %w", err)
-	}
-
-	dec, err := zstd.NewReader(nil)
-	if err != nil {
-		return nil, fmt.Errorf("create zstd decoder: %w", err)
-	}
-	defer dec.Close()
-
-	contents := make([]string, 0, len(names))
-
-	for _, name := range names {
-		compressed, readErr := fs.ReadFile(files, name)
-		if readErr != nil {
-			return nil, fmt.Errorf("read %s: %w", name, readErr)
-		}
-
-		data, decErr := dec.DecodeAll(compressed, nil)
-		if decErr != nil {
-			return nil, fmt.Errorf("decompress %s: %w", name, decErr)
-		}
-
-		contents = append(contents, string(data))
-	}
-
-	return contents, nil
-}
-
-// reportFilePath returns the path in dir of a report file named as
-// written on the given day of January 2026, so that a lower day sorts
-// as older.
-func reportFilePath(dir string, day int) string {
-	return filepath.Join(dir,
-		fmt.Sprintf("reports-2026-01-%02dT00-00-00.000Z-1.jsonl.zst", day))
-}
-
-func writeBytes(t *testing.T, path string, n int) {
-	t.Helper()
-
-	err := os.WriteFile(path, make([]byte, n), 0o600)
-	if err != nil {
-		t.Fatalf("write %s: %v", path, err)
-	}
-}
-
-func exists(t *testing.T, path string) bool {
-	t.Helper()
-
-	_, err := os.Stat(path)
-	if errors.Is(err, fs.ErrNotExist) {
-		return false
-	}
-
-	if err != nil {
-		t.Fatalf("stat %s: %v", path, err)
-	}
-
-	return true
-}
-
-func hasReportFile(t *testing.T, dir string) bool {
-	t.Helper()
-
-	entries, err := os.ReadDir(dir)
-	if err != nil {
-		t.Fatalf("read data dir: %v", err)
-	}
-
-	for _, e := range entries {
-		if strings.HasSuffix(e.Name(), ".jsonl.zst") {
-			info, statErr := e.Info()
-			if statErr != nil {
-				t.Fatalf("stat %s: %v", e.Name(), statErr)
-			}
-
-			if info.Size() > 0 {
-				return true
-			}
-		}
-	}
-
-	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/script/build

@@ -1,21 +0,0 @@
-#!/bin/sh
-# script/build: compile the static netwatch-server binary into the
-# backend project root, with its version stamped in.
-set -eu
-
-ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
-
-main() {
-    cd "$ROOT"
-
-    # VERSION comes from the environment (the root Dockerfile passes its
-    # ARG VERSION in). Unset or empty, it is git describe, or "dev" where
-    # there is no git or no repository history.
-    version="${VERSION:-$(git describe --always --dirty 2>/dev/null || echo dev)}"
-
-    CGO_ENABLED=0 go build -trimpath \
-        -ldflags "-s -w -X main.Version=$version" \
-        -o netwatch-server ./cmd/netwatch-server/
-}
-
-main "$@"

backend/script/clean

@@ -1,12 +0,0 @@
-#!/bin/sh
-# script/clean: remove build artifacts.
-set -eu
-
-ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
-
-main() {
-    cd "$ROOT"
-    rm -f netwatch-server
-}
-
-main "$@"

backend/script/fmt

@@ -1,12 +0,0 @@
-#!/bin/sh
-# script/fmt: format the Go sources (writes).
-set -eu
-
-ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
-
-main() {
-    cd "$ROOT"
-    go fmt ./...
-}
-
-main "$@"

backend/script/fmt-check

@@ -1,18 +0,0 @@
-#!/bin/sh
-# script/fmt-check: check Go formatting (read-only). Same scope as
-# script/fmt, but fails instead of writing.
-set -eu
-
-ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
-
-main() {
-    cd "$ROOT"
-    unformatted="$(gofmt -l .)"
-    if [ -n "$unformatted" ]; then
-        echo "Files not formatted:" >&2
-        echo "$unformatted" >&2
-        exit 1
-    fi
-}
-
-main "$@"

backend/script/lint

@@ -1,13 +0,0 @@
-#!/bin/sh
-# script/lint: lint the whole repo as the root make lint does, by
-# building the lint phase of the root Dockerfile. golangci-lint never
-# runs on the host (REPO_POLICIES.md).
-set -eu
-
-ROOT="$(cd "$(dirname "$0")/../.." && pwd -P)"
-
-main() {
-    exec "$ROOT/script/lint"
-}
-
-main "$@"

backend/script/test

@@ -1,23 +0,0 @@
-#!/bin/sh
-# script/test: run the backend test suite on the host with the race
-# detector and coverage. The root make test runs the same in the test
-# phase of the root Dockerfile. Go's own -timeout bounds the tests and
-# not their compile, so a cold build cache cannot fail it. -count=1
-# keeps Go's test result cache out of both runs, so neither can report
-# a stored pass. 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"
-    go test -count=1 -timeout 90s -race -cover ./... || {
-        echo "--- Rerunning with -v for details ---"
-        go test -count=1 -timeout 90s -race -v ./...
-        exit 1
-    }
-}
-
-main "$@"

bin/entrypoint.sh

@@ -13,6 +13,7 @@ set -u
 # address and start anyway, and reports a bad port without naming
 # PORT, so a value that is not a usable port stops the container here,
 # before either process starts.
+check_port() {
     export PORT="${PORT:-8080}"
     case "$PORT" in
         *[!0-9]*)
@@ -28,15 +29,19 @@ if [ "${#PORT}" -gt 5 ] || [ "$PORT" -lt 1 ] || [ "$PORT" -gt 65535 ]; then
         exit 1
     fi
     if [ "$PORT" -eq 8081 ]; then
-    echo "entrypoint: PORT cannot be 8081, netwatch-server listens there" >&2
+        echo "entrypoint: PORT cannot be 8081, netwatch-server" \
+            "listens there" >&2
         exit 1
     fi
+}
 
 # TRUSTED_PROXIES names the reverse proxies in front of the container,
 # as IP addresses or CIDRs separated by commas. nginx takes the client
-# address from X-Forwarded-For only on a request from one of them, so
-# unset or empty, it trusts no one. nginx.conf includes the file written
-# here, one set_real_ip_from line per entry.
+# address from X-Forwarded-For only on a request from one of them.
+# Unset, they are the three private ranges of RFC 1918; set and empty,
+# nginx trusts no one, which is why the default below follows - and not
+# :-. configs/nginx.conf includes the file written here, one
+# set_real_ip_from line per entry.
 #
 # nginx looks up an entry it cannot read as an address as a hostname,
 # and trusts what it finds (1.2.3 is found as 1.2.0.3). So each entry
@@ -45,7 +50,8 @@ fi
 # TRUSTED_PROXIES. Its error, naming the CIDR, is dropped for the one
 # below, naming the entry as written. set -f keeps a * in an entry from
 # becoming a list of file names.
-TRUSTED_PROXIES="${TRUSTED_PROXIES:-}"
+write_trusted_proxies() {
+    TRUSTED_PROXIES="${TRUSTED_PROXIES-10.0.0.0/8,172.16.0.0/12,192.168.0.0/16}"
     set -f
     for proxy in $(printf '%s' "$TRUSTED_PROXIES" | tr ',' ' '); do
         case "$proxy" in
@@ -60,42 +66,48 @@ for proxy in $(printf '%s' "$TRUSTED_PROXIES" | tr ',' ' '); do
         fi
         echo "set_real_ip_from $cidr;"
     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. Here, as root, netwatch-server prepare-data-dir creates DATA_DIR
-# and gives /data and everything in it to the netwatch user, so the
-# 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
-# nothing outside /data, whatever symbolic links it meets there.
+# and gives /data and the directories, regular files and symbolic links
+# in it to the netwatch user, so the host directory needs no preparing.
+# A file with a second name (hard link) keeps its owner, as that name
+# could be outside /data, and its path is logged. It stops the start,
+# naming DATA_DIR, unless DATA_DIR is /data or a path below it, and it
+# acts on nothing outside /data, whatever symbolic or hard links it
+# meets there.
+prepare_data_dir() {
     export DATA_DIR="${DATA_DIR:-/data/reports}"
     netwatch-server prepare-data-dir "$DATA_DIR" || exit 1
-
-# A stop signal is only noted here; the loop below acts on it.
-stop_requested=""
-trap 'stop_requested=yes' TERM INT
+}
 
 # netwatch-server runs as the netwatch user and listens on loopback
-# only, on a port other than the public one; nginx.conf proxies to this
-# address. Its only client is nginx, so it takes the client address
-# nginx passes on from 127.0.0.1 alone, whatever TRUSTED_PROXIES the
-# container has. The netwatch user has no login shell, hence -s
+# only, on a port other than the public one; configs/nginx.conf proxies
+# to this address. Its only client is nginx, so it takes the client
+# address nginx passes on from 127.0.0.1 alone, whatever TRUSTED_PROXIES
+# the container has. The netwatch user has no login shell, hence -s
 # /bin/sh. busybox su replaces itself with the command instead of
 # staying on as its parent, so $! is the server's own PID.
+start_backend() {
     BIND_ADDRESS=127.0.0.1 PORT=8081 TRUSTED_PROXIES=127.0.0.1/32 \
         su -s /bin/sh netwatch -c 'exec netwatch-server' &
     backend=$!
+}
 
 # nginx starts through the nginx image's own entrypoint, which applies
 # the image's start-up configuration and then replaces itself with
-# nginx. Part of that start-up configuration renders nginx.conf into
-# conf.d with nginx listening on PORT. NGINX_ENVSUBST_FILTER limits
+# nginx. Part of that start-up configuration renders configs/nginx.conf
+# into conf.d with nginx listening on PORT. NGINX_ENVSUBST_FILTER limits
 # that rendering to PORT: a variable nginx itself uses, such as $uri,
 # would otherwise be replaced by an environment variable of the same
 # name.
+start_nginx() {
     NGINX_ENVSUBST_FILTER='^PORT$' \
         /docker-entrypoint.sh nginx -g 'daemon off;' &
     nginx=$!
+}
 
 running() {
     kill -0 "$1" 2>/dev/null
@@ -104,26 +116,47 @@ running() {
 # POSIX sh cannot wait for whichever of two children exits first, so
 # look once a second. The shell collects a child that has exited while
 # it runs sleep, and running() is false for that child from then on.
+wait_for_stop_or_exit() {
     while [ -z "$stop_requested" ] && running "$backend" && running "$nginx"; do
         sleep 1
     done
+}
 
 # Stop both, then wait until neither is left.
+stop_both() {
     kill -TERM "$backend" "$nginx" 2>/dev/null
     while running "$backend" || running "$nginx"; do
         sleep 1
     done
+}
 
+# Success is a requested stop that both processes exited cleanly from.
+exit_with_status() {
     wait "$backend"
     backend_status=$?
     wait "$nginx"
     nginx_status=$?
     echo "entrypoint: netwatch-server exited $backend_status," \
         "nginx exited $nginx_status"
-
-# Success is a requested stop that both processes exited cleanly from.
     if [ -n "$stop_requested" ] && [ "$backend_status" -eq 0 ] &&
         [ "$nginx_status" -eq 0 ]; then
         exit 0
     fi
     exit 1
+}
+
+main() {
+    check_port
+    write_trusted_proxies
+    prepare_data_dir
+    # A stop signal is only noted here; wait_for_stop_or_exit acts on it.
+    stop_requested=""
+    trap 'stop_requested=yes' TERM INT
+    start_backend
+    start_nginx
+    wait_for_stop_or_exit
+    stop_both
+    exit_with_status
+}
+
+main "$@"

cmd/netwatch-server/main.go

@@ -0,0 +1,19 @@
+// Package main is the entry point for netwatch-server; package cli
+// does the work.
+package main
+
+import (
+	"os"
+
+	"sneak.berlin/go/netwatch/internal/cli"
+)
+
+//nolint:gochecknoglobals // set via ldflags at build time
+var (
+	Appname = "netwatch-server"
+	Version string
+)
+
+func main() {
+	os.Exit(cli.Main(os.Stderr, Appname, Version, os.Args[1:], cli.RunServer))
+}

configs/nginx.conf

@@ -18,9 +18,10 @@ server {
 
     # The client address comes from X-Forwarded-For only on a request
     # from the reverse proxies in TRUSTED_PROXIES: bin/entrypoint.sh
-    # writes one set_real_ip_from line for each into this file, and
-    # leaves it empty when TRUSTED_PROXIES is unset, so that by default
-    # the client address is the one each request comes from.
+    # writes one set_real_ip_from line for each into this file. Unset,
+    # TRUSTED_PROXIES is the three private ranges of RFC 1918; set and
+    # empty, the file is empty and the client address is the one each
+    # request comes from.
     include /etc/nginx/trusted-proxies.conf;
     real_ip_header X-Forwarded-For;
     real_ip_recursive on;
@@ -29,8 +30,13 @@ server {
     access_log /dev/stdout combined;
     error_log  /dev/stderr warn;
 
+    # With no-cache, a browser never uses a copy of the page that names
+    # assets a newer build no longer has without first checking with the
+    # server that it is current.
     location / {
         try_files $uri $uri/ /index.html;
+        add_header Cache-Control no-cache;
+        include /etc/nginx/security-headers.conf;
     }
 
     # Cache static assets aggressively
@@ -45,7 +51,9 @@ server {
     # 127.0.0.1:8081. These headers go with every request passed to it.
     # X-Forwarded-For carries only the client address, as resolved by
     # the real IP settings above, and not the chain the request came
-    # with: the backend takes the first entry, which a client can write.
+    # with. bin/entrypoint.sh starts the backend with
+    # TRUSTED_PROXIES=127.0.0.1/32, the address nginx connects from, so
+    # the backend takes that one entry as the client address.
     proxy_set_header Host $host;
     proxy_set_header X-Real-IP $remote_addr;
     proxy_set_header X-Forwarded-For $remote_addr;
@@ -53,7 +61,7 @@ server {
 
     # netwatch-server sets the same security headers on its own
     # responses. Its copies are dropped so that each header goes out
-    # once, as security-headers.conf sets it.
+    # once, as configs/security-headers.conf sets it.
     proxy_hide_header Strict-Transport-Security;
     proxy_hide_header Content-Security-Policy;
     proxy_hide_header X-Frame-Options;

configs/security-headers.conf

@@ -1,5 +1,5 @@
 # The security headers REPO_POLICIES.md requires on every response.
-# nginx.conf includes this file, which Dockerfile copies to
+# configs/nginx.conf includes this file, which Dockerfile copies to
 # /etc/nginx/security-headers.conf. always sends each header on error
 # responses too.
 
@@ -8,11 +8,11 @@ add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" alway
 # Scripts and styles load only from the page's own origin. Inline ones
 # are blocked, style attributes in markup included, so style elements
 # through classes or element.style. data: images are for the favicon
-# in index.html. connect-src is * because the browser checks each probe in
-# src/main.js against it, and also every redirect the probe follows,
-# and several of those hosts redirect to others; a list of hosts here
-# would block those probes. It also covers the reports the page sends
-# to its own origin.
+# in web/index.html. connect-src is * because the browser checks each
+# probe in web/src/main.js against it, and also every redirect the probe
+# follows, and several of those hosts redirect to others; a list of
+# hosts here would block those probes. It also covers the reports the
+# page sends to its own origin.
 add_header Content-Security-Policy "default-src 'self'; connect-src *; img-src 'self' data:; object-src 'none'; base-uri 'none'; form-action 'none'; frame-ancestors 'none'" always;
 
 add_header X-Frame-Options DENY always;

eslint.config.js

@@ -8,7 +8,7 @@ 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"],
+        files: ["web/src/**/*.js", "test/viewport/facts.js"],
         languageOptions: {
             globals: {
                 ...globals.browser,

go.mod

@@ -2,6 +2,9 @@ module sneak.berlin/go/netwatch
 
 go 1.25.5
 
+// npm packages can ship .go files, which ./... and all would include.
+ignore ./node_modules
+
 require (
 	github.com/99designs/basicauth-go v0.0.0-20230316000542-bf6f9cbbf0f8
 	github.com/getsentry/sentry-go v0.49.0
@@ -14,6 +17,7 @@ require (
 	github.com/slok/go-http-metrics v0.13.0
 	github.com/spf13/viper v1.21.0
 	go.uber.org/fx v1.24.0
+	golang.org/x/sys v0.47.0
 )
 
 require (
@@ -38,7 +42,6 @@ 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.47.0 // indirect
 	golang.org/x/text v0.40.0 // indirect
 	google.golang.org/protobuf v1.36.11 // indirect
 )

internal/cli/cli.go

@@ -0,0 +1,143 @@
+// Package cli runs netwatch-server from its command line: the
+// check-cidr and prepare-data-dir subcommands, which bin/entrypoint.sh
+// runs before it starts the server, and, given no arguments, the
+// server, with the fx wiring.
+package cli
+
+import (
+	"fmt"
+	"io"
+	"os/user"
+
+	"sneak.berlin/go/netwatch/internal/config"
+	"sneak.berlin/go/netwatch/internal/globals"
+	"sneak.berlin/go/netwatch/internal/handlers"
+	"sneak.berlin/go/netwatch/internal/healthcheck"
+	"sneak.berlin/go/netwatch/internal/logger"
+	"sneak.berlin/go/netwatch/internal/middleware"
+	"sneak.berlin/go/netwatch/internal/reportbuf"
+	"sneak.berlin/go/netwatch/internal/server"
+
+	"go.uber.org/fx"
+	"go.uber.org/fx/fxevent"
+)
+
+// usageExitCode is what Main returns for a command line it does not
+// understand, the usual exit code for a usage error.
+const usageExitCode = 2
+
+// Main runs netwatch-server with args, its command line after the
+// program's name, and returns the exit code. With no args, Main runs
+// the server by calling serve with appname and version, the name and
+// version the server logs and reports. With "check-cidr CIDR" or
+// "prepare-data-dir DATA_DIR" it runs that subcommand, which writes its
+// errors to stderr. Any other args get a one-line usage message on
+// stderr and exit code 2. main passes os.Stderr and RunServer; the
+// tests pass a buffer and a function of their own, so that no test
+// starts the server. When serve is RunServer and the server fails to
+// start, to listen or to stop, fx's Run exits the process with status 1
+// and Main never returns.
+func Main(
+	stderr io.Writer,
+	appname, version string,
+	args []string,
+	serve func(appname, version string),
+) int {
+	// "netwatch-server check-cidr CIDR" exits 1, with the error, if
+	// this server would refuse CIDR in its TRUSTED_PROXIES.
+	// bin/entrypoint.sh runs it on each entry it gives nginx.
+	if len(args) == 2 && args[0] == "check-cidr" {
+		return checkCIDR(stderr, args[1])
+	}
+
+	// "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(args) == 2 && args[0] == "prepare-data-dir" {
+		return prepareDataDir(stderr, "/data", args[1], "netwatch")
+	}
+
+	// Any other command line is refused, so that a mistyped one does
+	// not start the server.
+	if len(args) > 0 {
+		_, _ = fmt.Fprintln(stderr,
+			"usage: netwatch-server [check-cidr CIDR | prepare-data-dir DATA_DIR]")
+
+		return usageExitCode
+	}
+
+	serve(appname, version)
+
+	return 0
+}
+
+// checkCIDR returns 0 if the server would take cidr in its
+// TRUSTED_PROXIES, and otherwise writes the error to stderr and
+// returns 1.
+func checkCIDR(stderr io.Writer, cidr string) int {
+	_, err := middleware.ParseTrustedProxies([]string{cidr})
+	if err != nil {
+		_, _ = fmt.Fprintln(stderr, err)
+
+		return 1
+	}
+
+	return 0
+}
+
+// prepareDataDir gets dataDir ready for the user named username with
+// reportbuf.PrepareDataDir, volume being where the data volume is
+// mounted, and returns 0. Otherwise it writes the error to stderr and
+// returns 1.
+func prepareDataDir(stderr io.Writer, volume, dataDir, username string) int {
+	owner, err := user.Lookup(username)
+	if err != nil {
+		_, _ = fmt.Fprintln(stderr, err)
+
+		return 1
+	}
+
+	err = reportbuf.PrepareDataDir(volume, dataDir, owner)
+	if err != nil {
+		_, _ = fmt.Fprintf(stderr, "DATA_DIR '%s': %v\n", dataDir, err)
+
+		return 1
+	}
+
+	return 0
+}
+
+// RunServer runs the server until it is told to stop, with appname and
+// version as the name and version it logs and reports. If the server
+// fails to start, to listen or to stop, fx's Run exits the process
+// with status 1 itself.
+func RunServer(appname, version string) {
+	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,
+			handlers.New,
+			healthcheck.New,
+			logger.New,
+			middleware.New,
+			reportbuf.New,
+			server.New,
+		),
+		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()
+}

internal/cli/cli_test.go

@@ -0,0 +1,219 @@
+package cli_test
+
+import (
+	"bytes"
+	"os"
+	"os/user"
+	"path/filepath"
+	"strconv"
+	"strings"
+	"testing"
+
+	"sneak.berlin/go/netwatch/internal/cli"
+	"sneak.berlin/go/netwatch/internal/reportbuf"
+)
+
+// TestMainRunsCheckCIDR: Main given check-cidr returns 0, writing
+// nothing, for a CIDR the server takes in its TRUSTED_PROXIES, and 1,
+// with an error naming TRUSTED_PROXIES and the CIDR, for one it
+// refuses, and does not start the server.
+func TestMainRunsCheckCIDR(t *testing.T) {
+	t.Parallel()
+
+	var stderr bytes.Buffer
+
+	code := cli.Main(&stderr, "netwatch", "test",
+		[]string{"check-cidr", "10.0.0.0/8"}, failIfServerStarts(t))
+	if code != 0 || stderr.Len() != 0 {
+		t.Errorf("check-cidr 10.0.0.0/8: exit %d, stderr %q; want exit 0 and no output",
+			code, stderr.String())
+	}
+
+	stderr.Reset()
+
+	code = cli.Main(&stderr, "netwatch", "test",
+		[]string{"check-cidr", "1.2.3/32"}, failIfServerStarts(t))
+
+	want := `TRUSTED_PROXIES "1.2.3/32": `
+	if code != 1 || !strings.HasPrefix(stderr.String(), want) {
+		t.Errorf("check-cidr 1.2.3/32: exit %d, stderr %q; want exit 1 and %q...",
+			code, stderr.String(), want)
+	}
+}
+
+// TestMainRunsPrepareDataDir: Main given prepare-data-dir runs the
+// prepare-data-dir subcommand for the netwatch user, and does not start
+// the server. The test image has no netwatch user, so that subcommand
+// exits 1 with the error from looking the user up;
+// TestPrepareDataDirRefusesPathOutsideVolume checks the path.
+func TestMainRunsPrepareDataDir(t *testing.T) {
+	t.Parallel()
+
+	var stderr bytes.Buffer
+
+	code := cli.Main(&stderr, "netwatch", "test",
+		[]string{"prepare-data-dir", "/etc"}, failIfServerStarts(t))
+
+	want := user.UnknownUserError("netwatch").Error() + "\n"
+	if code != 1 || stderr.String() != want {
+		t.Errorf("prepare-data-dir /etc: exit %d, stderr %q; want exit 1 and %q",
+			code, stderr.String(), want)
+	}
+}
+
+// TestMainRunsServerWithNoArguments: Main given no arguments starts the
+// server with the name and version it was given, writes nothing and
+// returns 0.
+func TestMainRunsServerWithNoArguments(t *testing.T) {
+	t.Parallel()
+
+	var (
+		stderr                 bytes.Buffer
+		gotAppname, gotVersion string
+	)
+
+	code := cli.Main(&stderr, "netwatch", "test", []string{},
+		func(appname, version string) {
+			gotAppname, gotVersion = appname, version
+		})
+	if code != 0 || stderr.Len() != 0 {
+		t.Errorf("exit %d, stderr %q; want exit 0 and no output",
+			code, stderr.String())
+	}
+
+	if gotAppname != "netwatch" || gotVersion != "test" {
+		t.Errorf("server started with %q %q; want %q %q",
+			gotAppname, gotVersion, "netwatch", "test")
+	}
+}
+
+// TestMainRefusesOtherCommandLines: Main given a subcommand with too
+// few or too many values, or a misspelt subcommand, writes the usage
+// message to stderr, returns 2 and does not start the server.
+func TestMainRefusesOtherCommandLines(t *testing.T) {
+	t.Parallel()
+
+	want := "usage: netwatch-server " +
+		"[check-cidr CIDR | prepare-data-dir DATA_DIR]\n"
+
+	for _, commandLine := range []string{
+		"netwatch-server check-cidr",
+		"netwatch-server check-cidr 192.0.2.0/24 198.51.100.0/24",
+		"netwatch-server prepare-data-dir",
+		"netwatch-server prepare-data-dir /data/reports /data/other",
+		"netwatch-server check-cdir 192.0.2.0/24",
+	} {
+		var stderr bytes.Buffer
+
+		// Main takes the command line after the program's name.
+		args := strings.Fields(commandLine)[1:]
+
+		code := cli.Main(&stderr, "netwatch", "test", args, failIfServerStarts(t))
+		if code != 2 || stderr.String() != want {
+			t.Errorf("%q: exit %d, stderr %q; want exit 2 and %q",
+				commandLine, code, stderr.String(), want)
+		}
+	}
+}
+
+// TestCheckCIDRTakesCIDR: check-cidr exits 0, writing nothing, for a
+// CIDR the server takes in its TRUSTED_PROXIES.
+func TestCheckCIDRTakesCIDR(t *testing.T) {
+	t.Parallel()
+
+	for _, cidr := range []string{"10.0.0.0/8", "192.0.2.1/32", "2001:db8::/32"} {
+		var stderr bytes.Buffer
+
+		code := cli.CheckCIDR(&stderr, cidr)
+		if code != 0 || stderr.Len() != 0 {
+			t.Errorf("%q: exit %d, stderr %q; want exit 0 and no output",
+				cidr, code, stderr.String())
+		}
+	}
+}
+
+// TestCheckCIDRRefusesOtherInput: check-cidr exits 1, with an error
+// naming TRUSTED_PROXIES and the input, for anything the server would
+// refuse in its TRUSTED_PROXIES, such as 1.2.3/32, which nginx would
+// look up as a hostname.
+func TestCheckCIDRRefusesOtherInput(t *testing.T) {
+	t.Parallel()
+
+	for _, cidr := range []string{
+		"1.2.3/32", "example.com/32", "10.0.0.0/33", "10.0.0.1", "",
+	} {
+		var stderr bytes.Buffer
+
+		code := cli.CheckCIDR(&stderr, cidr)
+
+		want := "TRUSTED_PROXIES " + strconv.Quote(cidr) + ": "
+		if code != 1 || !strings.HasPrefix(stderr.String(), want) {
+			t.Errorf("%q: exit %d, stderr %q; want exit 1 and %q...",
+				cidr, code, stderr.String(), want)
+		}
+	}
+}
+
+// TestPrepareDataDirTakesPathInVolume: prepare-data-dir exits 0,
+// writing nothing, for a DATA_DIR below the volume, and creates it.
+func TestPrepareDataDirTakesPathInVolume(t *testing.T) {
+	t.Parallel()
+
+	volume := t.TempDir()
+	dataDir := filepath.Join(volume, "reports")
+
+	var stderr bytes.Buffer
+
+	code := cli.PrepareDataDir(&stderr, volume, dataDir, currentUsername(t))
+	if code != 0 || stderr.Len() != 0 {
+		t.Errorf("exit %d, stderr %q; want exit 0 and no output",
+			code, stderr.String())
+	}
+
+	info, err := os.Stat(dataDir)
+	if err != nil || !info.IsDir() {
+		t.Errorf("DATA_DIR not created: %v", err)
+	}
+}
+
+// TestPrepareDataDirRefusesPathOutsideVolume: prepare-data-dir exits
+// 1, with an error naming DATA_DIR and its value, for a DATA_DIR
+// outside the volume.
+func TestPrepareDataDirRefusesPathOutsideVolume(t *testing.T) {
+	t.Parallel()
+
+	volume := t.TempDir()
+
+	var stderr bytes.Buffer
+
+	code := cli.PrepareDataDir(&stderr, volume, "/etc", currentUsername(t))
+
+	want := "DATA_DIR '/etc': " + reportbuf.ErrDataDirOutsideVolume.Error() + "\n"
+	if code != 1 || stderr.String() != want {
+		t.Errorf("exit %d, stderr %q; want exit 1 and %q",
+			code, stderr.String(), want)
+	}
+}
+
+// currentUsername is the name of the user the test runs as, the only
+// owner a test not run as root can give files to.
+func currentUsername(t *testing.T) string {
+	t.Helper()
+
+	current, err := user.Current()
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	return current.Username
+}
+
+// failIfServerStarts is what the tests give Main in place of
+// cli.RunServer: it fails the test instead of starting the server.
+func failIfServerStarts(t *testing.T) func(appname, version string) {
+	t.Helper()
+
+	return func(string, string) {
+		t.Error("Main started the server")
+	}
+}

internal/cli/export_test.go

@@ -0,0 +1,16 @@
+package cli
+
+import "io"
+
+// CheckCIDR exposes the check-cidr subcommand to the external tests,
+// which read what it writes to stderr.
+func CheckCIDR(stderr io.Writer, cidr string) int {
+	return checkCIDR(stderr, cidr)
+}
+
+// PrepareDataDir exposes the prepare-data-dir subcommand to the
+// external tests, which give it a volume and a user of their own in
+// place of /data and netwatch.
+func PrepareDataDir(stderr io.Writer, volume, dataDir, username string) int {
+	return prepareDataDir(stderr, volume, dataDir, username)
+}

internal/config/config.go

@@ -9,6 +9,7 @@ import (
 	"math"
 	"net/netip"
 	"net/url"
+	"os"
 	"strconv"
 	"strings"
 
@@ -21,16 +22,14 @@ import (
 )
 
 // defaultTrustedProxies lists the networks whose forwarded
-// headers are honoured by default: IPv4 and IPv6 loopback,
-// for a reverse proxy on the same host, and the RFC1918
-// ranges. The container image does not use it:
+// headers are honoured when TRUSTED_PROXIES is unset: the
+// RFC 1918 ranges. The container image does not use it:
 // bin/entrypoint.sh gives the server 127.0.0.1/32, since
 // nginx is its only client there.
-const defaultTrustedProxies = "127.0.0.1/32,::1/128," +
-	"10.0.0.0/8,172.16.0.0/12,192.168.0.0/16"
+const defaultTrustedProxies = "10.0.0.0/8,172.16.0.0/12,192.168.0.0/16"
 
-// Default limits on stored reports; backend/README.md gives the
-// reasons for these values.
+// Default limits on stored reports; README.md gives the reasons for
+// these values.
 const (
 	defaultReportsPerMinute = 60
 	defaultDataDirMaxBytes  = 1 << 30 // 1 GiB
@@ -42,7 +41,6 @@ var (
 		"must be an origin, scheme://host with an optional port",
 	)
 	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(
@@ -102,7 +100,7 @@ func New(
 	viper.SetDefault("CORS_ALLOWED_ORIGINS", "")
 	viper.SetDefault("DATA_DIR", "./data/reports")
 	viper.SetDefault("DATA_DIR_MAX_BYTES", defaultDataDirMaxBytes)
-	viper.SetDefault("DEBUG", "false")
+	viper.SetDefault("DEBUG", "")
 	// An empty BIND_ADDRESS listens on every interface.
 	viper.SetDefault("BIND_ADDRESS", "")
 	viper.SetDefault("PORT", "8080")
@@ -121,18 +119,24 @@ func New(
 		}
 	}
 
-	// Read with strconv: viper's GetInt and GetBool would read a value
-	// they cannot parse as 0 or false instead of failing.
+	// Read with strconv: viper's GetInt would read a value it cannot
+	// parse as 0 instead of failing.
 	port, err := strconv.Atoi(viper.GetString("PORT"))
 	if err != nil || port < 1 || port > math.MaxUint16 {
 		return nil, fmt.Errorf("PORT %q: %w",
 			viper.GetString("PORT"), errNotPort)
 	}
 
-	debug, err := strconv.ParseBool(viper.GetString("DEBUG"))
-	if err != nil {
-		return nil, fmt.Errorf("DEBUG %q: %w",
-			viper.GetString("DEBUG"), errNotBool)
+	// Any non-empty value turns debug logging on, "false" and "0"
+	// included, as the code style guide says.
+	debug := viper.GetString("DEBUG") != ""
+
+	// An empty TRUSTED_PROXIES trusts no proxy, but viper reads an
+	// empty environment variable as unset and would give the default,
+	// so the environment is read first.
+	trustedProxies, set := os.LookupEnv("TRUSTED_PROXIES")
+	if !set {
+		trustedProxies = viper.GetString("TRUSTED_PROXIES")
 	}
 
 	s := &Config{
@@ -146,7 +150,7 @@ func New(
 		Port:               port,
 		ReportsPerMinute:   viper.GetInt("REPORTS_PER_MINUTE"),
 		SentryDSN:          viper.GetString("SENTRY_DSN"),
-		TrustedProxies:     splitList(viper.GetString("TRUSTED_PROXIES")),
+		TrustedProxies:     splitList(trustedProxies),
 		log:                log,
 		params:             &params,
 	}
@@ -165,8 +169,8 @@ func New(
 }
 
 // check fails with an error naming the first setting here whose value
-// the server cannot use. New checks PORT and DEBUG as it reads them,
-// and the middleware checks TRUSTED_PROXIES as it parses it.
+// the server cannot use. New checks PORT as it reads it, and the
+// middleware checks TRUSTED_PROXIES as it parses it.
 func (s *Config) check() error {
 	// viper reads a value that is not a number as 0, so this also
 	// catches a mistyped setting.

internal/config/config_test.go

@@ -1,6 +1,8 @@
 package config_test
 
 import (
+	"os"
+	"slices"
 	"strings"
 	"testing"
 
@@ -11,8 +13,8 @@ import (
 	"go.uber.org/fx"
 )
 
-// requireConfigError builds the config as main does and fails the
-// test unless that fails with an error naming setting. It uses
+// requireConfigError builds the config as cli.RunServer does and fails
+// the test unless that fails with an error naming setting. It uses
 // fx.New, because fxtest.New fails the test itself on an error.
 func requireConfigError(t *testing.T, setting string) {
 	t.Helper()
@@ -29,6 +31,62 @@ func requireConfigError(t *testing.T, setting string) {
 	}
 }
 
+// requireTrustedProxies builds the config as cli.RunServer does and
+// fails the test unless its TrustedProxies are want.
+func requireTrustedProxies(t *testing.T, want []string) {
+	t.Helper()
+
+	var cfg *config.Config
+
+	app := fx.New(
+		fx.NopLogger,
+		fx.Provide(globals.New, logger.New, config.New),
+		fx.Populate(&cfg),
+	)
+
+	err := app.Err()
+	if err != nil {
+		t.Fatalf("config error = %v", err)
+	}
+
+	if !slices.Equal(cfg.TrustedProxies, want) {
+		t.Fatalf("TrustedProxies = %q, want %q", cfg.TrustedProxies, want)
+	}
+}
+
+// TestTrustedProxiesUnsetTrustsRFC1918: unset, the server trusts the
+// RFC 1918 ranges and nothing else, loopback included.
+func TestTrustedProxiesUnsetTrustsRFC1918(t *testing.T) {
+	// t.Setenv first, so the variable is put back as it was after the
+	// test.
+	t.Setenv("TRUSTED_PROXIES", "")
+
+	err := os.Unsetenv("TRUSTED_PROXIES")
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	requireTrustedProxies(t,
+		[]string{"10.0.0.0/8", "172.16.0.0/12", "192.168.0.0/16"})
+}
+
+// TestTrustedProxiesEmptyTrustsNothing: set and empty, the server
+// trusts no proxy. viper alone would read the empty variable as unset
+// and give the default.
+func TestTrustedProxiesEmptyTrustsNothing(t *testing.T) {
+	t.Setenv("TRUSTED_PROXIES", "")
+
+	requireTrustedProxies(t, []string{})
+}
+
+// TestTrustedProxiesListReplacesDefault: a list is used as given, with
+// none of the default ranges added.
+func TestTrustedProxiesListReplacesDefault(t *testing.T) {
+	t.Setenv("TRUSTED_PROXIES", "172.17.0.1/32, 2001:db8::/32")
+
+	requireTrustedProxies(t, []string{"172.17.0.1/32", "2001:db8::/32"})
+}
+
 // TestSettingsLoadAsGiven: valid values pass the checks and are used
 // as given. bin/entrypoint.sh starts the server with these
 // BIND_ADDRESS and PORT values.
@@ -69,12 +127,52 @@ func TestPortMustBeAPortNumber(t *testing.T) {
 	}
 }
 
-// TestDebugMustBeTrueOrFalse: viper reads any other value, such as
-// "yes", as false.
-func TestDebugMustBeTrueOrFalse(t *testing.T) {
-	t.Setenv("DEBUG", "yes")
+// TestDebugIsOnForAnyNonEmptyValue: unset or empty, debug logging is
+// off; any other value turns it on, "false" and "0" included, and none
+// stops the start.
+func TestDebugIsOnForAnyNonEmptyValue(t *testing.T) {
+	for _, tc := range []struct {
+		name  string
+		value string
+		unset bool
+		want  bool
+	}{
+		{name: "unset", unset: true, want: false},
+		{name: "empty", value: "", want: false},
+		{name: "false", value: "false", want: true},
+		{name: "0", value: "0", want: true},
+		{name: "yes", value: "yes", want: true},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			// t.Setenv first, so the variable is put back as it was
+			// after the test.
+			t.Setenv("DEBUG", tc.value)
 
-	requireConfigError(t, "DEBUG")
+			if tc.unset {
+				err := os.Unsetenv("DEBUG")
+				if err != nil {
+					t.Fatal(err)
+				}
+			}
+
+			var cfg *config.Config
+
+			app := fx.New(
+				fx.NopLogger,
+				fx.Provide(globals.New, logger.New, config.New),
+				fx.Populate(&cfg),
+			)
+
+			err := app.Err()
+			if err != nil {
+				t.Fatalf("config error = %v", err)
+			}
+
+			if cfg.Debug != tc.want {
+				t.Fatalf("Debug = %t, want %t", cfg.Debug, tc.want)
+			}
+		})
+	}
 }
 
 // TestBindAddressMustBeAnIPAddress: a host name would be looked up

internal/globals/globals.go

@@ -4,7 +4,7 @@ package globals
 
 import "go.uber.org/fx"
 
-//nolint:gochecknoglobals // set from main before fx starts
+//nolint:gochecknoglobals // set by cli.RunServer before fx starts
 var (
 	// Appname is the application name.
 	Appname string

internal/handlers/handlers.go

@@ -5,7 +5,9 @@ package handlers
 import (
 	"context"
 	"encoding/json"
+	"errors"
 	"log/slog"
+	"mime"
 	"net/http"
 
 	"sneak.berlin/go/netwatch/internal/globals"
@@ -18,6 +20,10 @@ import (
 
 const jsonContentType = "application/json; charset=utf-8"
 
+// errNotJSON is what decodeJSON returns for a request whose
+// Content-Type is not application/json.
+var errNotJSON = errors.New("content type is not application/json")
+
 // reportAppender is the subset of the report buffer the handlers
 // depend on. Defining it here keeps the storage failure path
 // exercisable with a stub in tests.
@@ -80,14 +86,25 @@ func (s *Handlers) respondJSON(
 	}
 }
 
-// decodeJSON decodes the request body into v. The body is
-// expected to already be bounded by the body-size middleware, so
-// a caller can distinguish an over-limit body from malformed
-// JSON by testing the returned error for *http.MaxBytesError.
+// decodeJSON decodes the request body into v. It returns errNotJSON,
+// reading nothing, unless the request's Content-Type is
+// application/json, with or without parameters such as charset. The
+// body is expected to already be bounded by the body-size middleware,
+// so a caller can distinguish an over-limit body from malformed JSON
+// by testing the returned error for *http.MaxBytesError.
 func (s *Handlers) decodeJSON(
 	_ http.ResponseWriter,
 	r *http.Request,
 	v any,
 ) error {
+	// A page on another origin can POST text/plain or a form without
+	// a CORS preflight, so its visitors' browsers would send it
+	// whatever the CORS settings. A JSON POST waits for the
+	// preflight, so only JSON is taken.
+	mediaType, _, err := mime.ParseMediaType(r.Header.Get("Content-Type"))
+	if err != nil || mediaType != "application/json" {
+		return errNotJSON
+	}
+
 	return json.NewDecoder(r.Body).Decode(v)
 }

internal/handlers/healthcheck.go

@@ -0,0 +1,19 @@
+package handlers
+
+import "net/http"
+
+// HandleHealthCheck returns a handler for the health check
+// endpoint. It answers 200 while the status is "ok" and 503 otherwise,
+// so that the image's HEALTHCHECK fails.
+func (s *Handlers) HandleHealthCheck() http.HandlerFunc {
+	return func(w http.ResponseWriter, r *http.Request) {
+		resp := s.hc.Healthcheck()
+
+		code := http.StatusOK
+		if resp.Status != "ok" {
+			code = http.StatusServiceUnavailable
+		}
+
+		s.respondJSON(w, r, resp, code)
+	}
+}

internal/handlers/healthcheck_test.go

@@ -9,17 +9,19 @@ import (
 	"testing"
 	"time"
 
+	"sneak.berlin/go/netwatch/internal/config"
 	"sneak.berlin/go/netwatch/internal/globals"
 	"sneak.berlin/go/netwatch/internal/handlers"
 	"sneak.berlin/go/netwatch/internal/healthcheck"
 	"sneak.berlin/go/netwatch/internal/logger"
+	"sneak.berlin/go/netwatch/internal/reportbuf"
 
 	"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.
+// server named in g, and a report buffer in a temporary directory, and
+// starts them, which records the time the uptime counts from.
 func newStartedHandlers(t *testing.T, g *globals.Globals) *handlers.Handlers {
 	t.Helper()
 
@@ -30,14 +32,23 @@ func newStartedHandlers(t *testing.T, g *globals.Globals) *handlers.Handlers {
 		t.Fatalf("logger: %v", err)
 	}
 
+	buf, err := reportbuf.New(lc, reportbuf.Params{
+		Config: &config.Config{DataDir: t.TempDir(), DataDirMaxBytes: 1 << 20},
+		Logger: log,
+	})
+	if err != nil {
+		t.Fatalf("report buffer: %v", err)
+	}
+
 	hc, err := healthcheck.New(lc,
-		healthcheck.Params{Globals: g, Logger: log})
+		healthcheck.Params{Buffer: buf, 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})
+	h, err := handlers.New(lc, handlers.Params{
+		Buffer: buf, Globals: g, Healthcheck: hc, Logger: log,
+	})
 	if err != nil {
 		t.Fatalf("handlers: %v", err)
 	}
@@ -48,10 +59,12 @@ func newStartedHandlers(t *testing.T, g *globals.Globals) *handlers.Handlers {
 	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.
+// TestHandleHealthCheck checks the health check's answer at start, when
+// no write of a report file has failed: 200, a JSON content type, and a
+// JSON object with exactly the fields of healthcheck.HealthcheckResponse,
+// carrying "status":"ok", this server's name and version and an uptime
+// counted from its start. The answer while writes fail is checked in
+// internal/reportbuf, whose tests can make a write fail.
 func TestHandleHealthCheck(t *testing.T) {
 	t.Parallel()
 

internal/handlers/report.go

@@ -30,7 +30,7 @@ type report struct {
 }
 
 // HandleReport returns a handler that accepts telemetry
-// reports from NetWatch clients.
+// reports from NetWatch clients, sent as application/json.
 func (s *Handlers) HandleReport() http.HandlerFunc {
 	type response struct {
 		Status string `json:"status"`
@@ -66,9 +66,15 @@ func (s *Handlers) HandleReport() http.HandlerFunc {
 }
 
 // decodeErrorStatus logs a report decode failure and returns the
-// status to send: 413 when the body exceeded the size limit,
-// otherwise 400 for malformed JSON.
+// status to send: 415 when the report was not sent as JSON, 413 when
+// the body exceeded the size limit, otherwise 400 for malformed JSON.
 func (s *Handlers) decodeErrorStatus(err error) int {
+	if errors.Is(err, errNotJSON) {
+		s.log.Warn("report refused: Content-Type is not application/json")
+
+		return http.StatusUnsupportedMediaType
+	}
+
 	var tooLarge *http.MaxBytesError
 	if errors.As(err, &tooLarge) {
 		s.log.Warn("report body too large", "limit_bytes", tooLarge.Limit)
@@ -87,7 +93,7 @@ func (s *Handlers) decodeErrorStatus(err error) int {
 
 // appendErrorStatus logs a failure to store a report and returns
 // the status to send: 507 when the reports waiting to be written fill
-// the size cap, otherwise 500.
+// the size cap, otherwise 500, as when report files cannot be written.
 func (s *Handlers) appendErrorStatus(err error) int {
 	if errors.Is(err, reportbuf.ErrFull) {
 		s.log.Warn("report refused: " +

internal/handlers/report_test.go

@@ -27,6 +27,17 @@ type stubAppender struct {
 
 func (s stubAppender) Append(any) error { return s.err }
 
+// recordingAppender keeps every report the handler stores.
+type recordingAppender struct {
+	reports []any
+}
+
+func (a *recordingAppender) Append(v any) error {
+	a.reports = append(a.reports, v)
+
+	return nil
+}
+
 func newTestHandlers(buf stubAppender, out io.Writer) *handlers.Handlers {
 	return handlers.NewForTest(buf, slog.New(slog.NewJSONHandler(out, nil)))
 }
@@ -83,6 +94,7 @@ func TestHandleReportAcceptsValidReports(t *testing.T) {
 				http.MethodPost, "/api/v1/reports",
 				strings.NewReader(tt.body),
 			)
+			req.Header.Set("Content-Type", "application/json")
 
 			h.HandleReport().ServeHTTP(rec, req)
 
@@ -103,6 +115,89 @@ func TestHandleReportAcceptsValidReports(t *testing.T) {
 	}
 }
 
+// TestHandleReportStoresOnlyJSON checks that a report is stored only
+// when sent as application/json, as the page sends it. One sent as
+// text/plain or as a form, which a page on another origin can send
+// without a CORS preflight, is refused with 415.
+func TestHandleReportStoresOnlyJSON(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name        string
+		contentType string
+		wantStatus  int
+		wantStored  int
+	}{
+		{
+			name:        "text/plain",
+			contentType: "text/plain;charset=UTF-8",
+			wantStatus:  http.StatusUnsupportedMediaType,
+			wantStored:  0,
+		},
+		{
+			name:        "a urlencoded form",
+			contentType: "application/x-www-form-urlencoded",
+			wantStatus:  http.StatusUnsupportedMediaType,
+			wantStored:  0,
+		},
+		{
+			name:        "a multipart form",
+			contentType: "multipart/form-data; boundary=x",
+			wantStatus:  http.StatusUnsupportedMediaType,
+			wantStored:  0,
+		},
+		{
+			name:        "no Content-Type",
+			contentType: "",
+			wantStatus:  http.StatusUnsupportedMediaType,
+			wantStored:  0,
+		},
+		{
+			name:        "application/json",
+			contentType: "application/json",
+			wantStatus:  http.StatusOK,
+			wantStored:  1,
+		},
+		{
+			name:        "application/json with a charset",
+			contentType: "application/json;charset=UTF-8",
+			wantStatus:  http.StatusOK,
+			wantStored:  1,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			var stored recordingAppender
+
+			h := handlers.NewForTest(&stored, slog.New(slog.DiscardHandler))
+
+			rec := httptest.NewRecorder()
+			req := httptest.NewRequestWithContext(t.Context(),
+				http.MethodPost, "/api/v1/reports",
+				strings.NewReader(`{"clientId":"c1","hosts":[]}`),
+			)
+
+			if tt.contentType != "" {
+				req.Header.Set("Content-Type", tt.contentType)
+			}
+
+			h.HandleReport().ServeHTTP(rec, req)
+
+			if rec.Code != tt.wantStatus {
+				t.Errorf("status = %d, want %d", rec.Code, tt.wantStatus)
+			}
+
+			if len(stored.reports) != tt.wantStored {
+				t.Errorf("reports stored = %d, want %d",
+					len(stored.reports), tt.wantStored)
+			}
+		})
+	}
+}
+
 func TestHandleReportStorageFailureIsNon2xx(t *testing.T) {
 	t.Parallel()
 
@@ -113,6 +208,7 @@ func TestHandleReportStorageFailureIsNon2xx(t *testing.T) {
 		http.MethodPost, "/api/v1/reports",
 		strings.NewReader(`{"clientId":"c1","hosts":[]}`),
 	)
+	req.Header.Set("Content-Type", "application/json")
 
 	h.HandleReport().ServeHTTP(rec, req)
 
@@ -138,6 +234,7 @@ func TestHandleReportFullIs507(t *testing.T) {
 		http.MethodPost, "/api/v1/reports",
 		strings.NewReader(`{"clientId":"c1","hosts":[]}`),
 	)
+	req.Header.Set("Content-Type", "application/json")
 
 	h.HandleReport().ServeHTTP(rec, req)
 
@@ -161,6 +258,7 @@ func TestHandleReportMalformedJSONIs400(t *testing.T) {
 		http.MethodPost, "/api/v1/reports",
 		strings.NewReader(`{not json`),
 	)
+	req.Header.Set("Content-Type", "application/json")
 
 	h.HandleReport().ServeHTTP(rec, req)
 
@@ -185,6 +283,8 @@ func TestHandleReportOversizeIs413(t *testing.T) {
 		http.MethodPost, "/api/v1/reports",
 		strings.NewReader(`{"clientId":"`+strings.Repeat("x", 200)+`"}`),
 	)
+	req.Header.Set("Content-Type", "application/json")
+
 	// No declared length, so only the middleware's read cap can
 	// stop this body.
 	req.ContentLength = -1
@@ -213,6 +313,7 @@ func TestHandleReportDoesNotLogRawGeo(t *testing.T) {
 			`{"clientId":"c1","geo":{"raw":"`+sentinel+`"},"hosts":[]}`,
 		),
 	)
+	req.Header.Set("Content-Type", "application/json")
 
 	h.HandleReport().ServeHTTP(rec, req)
 
@@ -245,6 +346,7 @@ func TestHandleReportLogsClientIDCutToBound(t *testing.T) {
 			`{"clientId":"`+long+`","timestamp":"`+long+`","hosts":[]}`,
 		),
 	)
+	req.Header.Set("Content-Type", "application/json")
 
 	h.HandleReport().ServeHTTP(rec, req)
 
@@ -284,6 +386,7 @@ func TestHandleReportDecodeErrorLogIsBounded(t *testing.T) {
 		http.MethodPost, "/api/v1/reports",
 		strings.NewReader(`{"hosts":[{"history":[{"t":`+huge+`}]}]}`),
 	)
+	req.Header.Set("Content-Type", "application/json")
 
 	h.HandleReport().ServeHTTP(rec, req)
 

internal/healthcheck/healthcheck.go

@@ -10,6 +10,7 @@ import (
 	"sneak.berlin/go/netwatch/internal/config"
 	"sneak.berlin/go/netwatch/internal/globals"
 	"sneak.berlin/go/netwatch/internal/logger"
+	"sneak.berlin/go/netwatch/internal/reportbuf"
 
 	"go.uber.org/fx"
 )
@@ -18,6 +19,7 @@ import (
 type Params struct {
 	fx.In
 
+	Buffer  *reportbuf.Buffer
 	Config  *config.Config
 	Globals *globals.Globals
 	Logger  *logger.Logger
@@ -68,12 +70,18 @@ func New(
 	return s, nil
 }
 
-// Healthcheck returns the current health status of the application.
+// Healthcheck returns the current health status of the application:
+// "ok", or "error" while report files cannot be written.
 func (s *Healthcheck) Healthcheck() *HealthcheckResponse {
+	status := "ok"
+	if s.params.Buffer.LastWriteFailed() {
+		status = "error"
+	}
+
 	return &HealthcheckResponse{
 		Appname:       s.params.Globals.Appname,
 		Now:           time.Now().UTC().Format(time.RFC3339Nano),
-		Status:        "ok",
+		Status:        status,
 		UptimeHuman:   s.uptime().String(),
 		UptimeSeconds: int64(s.uptime().Seconds()),
 		Version:       s.params.Globals.Version,

internal/middleware/middleware.go

@@ -11,6 +11,7 @@ import (
 	"net/http"
 	"net/netip"
 	"runtime/debug"
+	"slices"
 	"strings"
 	"time"
 
@@ -133,6 +134,17 @@ func ipFromHostPort(hostPort string) string {
 // X-Real-IP are honoured only when the direct peer is a
 // trusted proxy; otherwise the direct peer is returned so a
 // spoofed header cannot forge the logged address.
+//
+// Each proxy appends to X-Forwarded-For the address it took the
+// request from, so the entries on the right are written by the
+// trusted proxies and those further left by the client. The
+// client's address is therefore the right-most entry that is not
+// a trusted proxy. An entry written as an address with a port is
+// read as that address, both for the trust check and as the
+// result. When every entry is a trusted proxy, or the walk from
+// the right meets an entry that is not an address at all (such as
+// "unknown"), the peer is used. X-Real-IP is read only when there
+// is no X-Forwarded-For entry at all.
 func clientIP(
 	remoteAddr string,
 	header http.Header,
@@ -144,10 +156,9 @@ func clientIP(
 		return peer
 	}
 
-	if xff := firstForwardedFor(header.Get("X-Forwarded-For")); xff != "" {
-		return xff
-	}
+	forwarded := forwardedFor(header)
 
+	if len(forwarded) == 0 {
 		if xr := strings.TrimSpace(header.Get("X-Real-IP")); validIP(xr) {
 			return xr
 		}
@@ -155,17 +166,39 @@ func clientIP(
 		return peer
 	}
 
-// firstForwardedFor returns the left-most valid address in an
-// X-Forwarded-For list (the original client), or "" if none.
-func firstForwardedFor(value string) string {
-	for part := range strings.SplitSeq(value, ",") {
-		candidate := strings.TrimSpace(part)
-		if validIP(candidate) {
-			return candidate
+	for _, entry := range slices.Backward(forwarded) {
+		if !validIP(entry) {
+			return peer
+		}
+
+		if !addrInAny(entry, trusted) {
+			return entry
 		}
 	}
 
-	return ""
+	return peer
+}
+
+// forwardedFor returns the entries of X-Forwarded-For in order,
+// leaving out blank ones. A proxy may add its entry as a header
+// line of its own rather than append it to the line the client
+// sent, so every line is read, not only the first. Some proxies
+// write an entry as an address with a port, such as
+// 198.51.100.7:5000 or [2001:db8::1]:443; the port is removed so
+// that the entry is read as its address.
+func forwardedFor(header http.Header) []string {
+	value := strings.Join(header.Values("X-Forwarded-For"), ",")
+
+	var entries []string
+
+	for part := range strings.SplitSeq(value, ",") {
+		entry := strings.TrimSpace(part)
+		if entry != "" {
+			entries = append(entries, ipFromHostPort(entry))
+		}
+	}
+
+	return entries
 }
 
 func validIP(s string) bool {
@@ -297,12 +330,16 @@ func (s *Middleware) MaxBodyBytes(
 
 // Recoverer returns middleware that recovers from a panic in a
 // downstream handler, logs the panic and stack trace through
-// slog, and responds 500 with no body. http.ErrAbortHandler is
-// re-panicked so the server can abort the response as intended.
+// slog, and responds 500 with no body, unless a status was already
+// written, as Write500OnPanic writes one for a handler's panic.
+// http.ErrAbortHandler is re-panicked so the server can abort the
+// response as intended.
 func (s *Middleware) Recoverer() func(http.Handler) http.Handler {
 	return func(next http.Handler) http.Handler {
 		return http.HandlerFunc(
 			func(w http.ResponseWriter, r *http.Request) {
+				ww := middleware.NewWrapResponseWriter(w, r.ProtoMajor)
+
 				defer func() {
 					rec := recover()
 					if rec == nil {
@@ -320,10 +357,43 @@ func (s *Middleware) Recoverer() func(http.Handler) http.Handler {
 						"stack", string(debug.Stack()),
 					)
 
-					w.WriteHeader(http.StatusInternalServerError)
+					if ww.Status() == 0 {
+						ww.WriteHeader(http.StatusInternalServerError)
+					}
 				}()
 
-				next.ServeHTTP(w, r)
+				next.ServeHTTP(ww, r)
+			},
+		)
+	}
+}
+
+// Write500OnPanic returns middleware that writes 500 when a downstream
+// handler panics before writing a status, and lets the panic go on to
+// Sentry and Recoverer. Recoverer, which comes first, would write its
+// 500 only after the request log and the metrics had recorded the
+// status they saw; placed after each of them, this makes them record
+// the 500.
+func (s *Middleware) Write500OnPanic() func(http.Handler) http.Handler {
+	return func(next http.Handler) http.Handler {
+		return http.HandlerFunc(
+			func(w http.ResponseWriter, r *http.Request) {
+				ww := middleware.NewWrapResponseWriter(w, r.ProtoMajor)
+
+				defer func() {
+					rec := recover()
+					if rec == nil {
+						return
+					}
+
+					if ww.Status() == 0 {
+						ww.WriteHeader(http.StatusInternalServerError)
+					}
+
+					panic(rec)
+				}()
+
+				next.ServeHTTP(ww, r)
 			},
 		)
 	}

internal/middleware/middleware_test.go

@@ -4,6 +4,7 @@ import (
 	"bytes"
 	"encoding/json"
 	"errors"
+	"log"
 	"log/slog"
 	"net/http"
 	"net/http/httptest"
@@ -16,16 +17,24 @@ import (
 	"sneak.berlin/go/netwatch/internal/logger"
 	"sneak.berlin/go/netwatch/internal/middleware"
 
+	"github.com/go-chi/chi/v5"
 	chimiddleware "github.com/go-chi/chi/v5/middleware"
+	"github.com/prometheus/client_golang/prometheus"
 )
 
 const (
 	// loopbackPeer is a remote address inside the trusted-proxy allowlist.
 	loopbackPeer = "127.0.0.1:5000"
+	// loopbackIP is the address of loopbackPeer, which ClientIP returns
+	// when it uses the peer.
+	loopbackIP = "127.0.0.1"
 	// forwardedIP is the client address presented via X-Forwarded-For.
 	forwardedIP = "203.0.113.7"
 	// realIP is the client address presented via X-Real-IP.
 	realIP = "203.0.113.9"
+	// appendedIP is the X-Forwarded-For entry a trusted proxy appended
+	// after the entries the client wrote.
+	appendedIP = "198.51.100.7"
 )
 
 func mustPrefixes(t *testing.T, cidrs ...string) []netip.Prefix {
@@ -82,10 +91,35 @@ func clientIPCases() []clientIPCase {
 			want:       forwardedIP,
 		},
 		{
-			name:       "trusted proxy uses left-most of chain",
-			remoteAddr: "10.1.2.3:5000",
-			xff:        forwardedIP + ", 10.1.2.3",
-			want:       forwardedIP,
+			name:       "trusted proxy uses right-most of chain",
+			remoteAddr: loopbackPeer,
+			xff:        "203.0.113.9, " + appendedIP,
+			want:       appendedIP,
+		},
+		{
+			name:       "trusted proxy entries are skipped from the right",
+			remoteAddr: loopbackPeer,
+			xff:        "203.0.113.9, 10.0.0.5",
+			want:       "203.0.113.9",
+		},
+		{
+			name:       "chain of only trusted proxies uses peer",
+			remoteAddr: loopbackPeer,
+			xff:        "10.0.0.5, 10.1.2.3",
+			want:       loopbackIP,
+		},
+		{
+			name:       "entry that is not an address uses peer",
+			remoteAddr: loopbackPeer,
+			xff:        "203.0.113.9, unknown",
+			want:       loopbackIP,
+		},
+		{
+			name:       "x-real-ip ignored when forwarded-for has entries",
+			remoteAddr: loopbackPeer,
+			xff:        "10.0.0.5",
+			xRealIP:    realIP,
+			want:       loopbackIP,
 		},
 		{
 			name:       "trusted proxy falls back to x-real-ip",
@@ -114,7 +148,7 @@ func clientIPCases() []clientIPCase {
 			name:       "trusted proxy with garbage header uses peer",
 			remoteAddr: loopbackPeer,
 			xff:        "not-an-ip",
-			want:       "127.0.0.1",
+			want:       loopbackIP,
 		},
 	}
 }
@@ -145,6 +179,47 @@ func TestClientIP(t *testing.T) {
 	}
 }
 
+// TestClientIPReadsEveryForwardedForLine checks that an entry a proxy
+// adds as an X-Forwarded-For line of its own is read, and the line the
+// client sent before it is not taken.
+func TestClientIPReadsEveryForwardedForLine(t *testing.T) {
+	t.Parallel()
+
+	header := http.Header{}
+	header.Add("X-Forwarded-For", "203.0.113.9")
+	header.Add("X-Forwarded-For", appendedIP)
+
+	got := middleware.ClientIP(loopbackPeer, header,
+		mustPrefixes(t, "127.0.0.1/32"))
+	if got != appendedIP {
+		t.Errorf("ClientIP() = %q, want %q", got, appendedIP)
+	}
+}
+
+// TestClientIPReadsAddressWithPort checks that an X-Forwarded-For entry
+// written as an address with a port is read as that address, both for
+// the trust check and as the result.
+func TestClientIPReadsAddressWithPort(t *testing.T) {
+	t.Parallel()
+
+	trusted := mustPrefixes(t, "127.0.0.1/32", "10.0.0.0/8")
+
+	for xff, want := range map[string]string{
+		"203.0.113.9, " + appendedIP + ":5000": appendedIP,
+		"203.0.113.9, [2001:db8::1]:443":       "2001:db8::1",
+		"203.0.113.9, 10.0.0.5:5000":           "203.0.113.9",
+	} {
+		header := http.Header{}
+		header.Set("X-Forwarded-For", xff)
+
+		got := middleware.ClientIP(loopbackPeer, header, trusted)
+		if got != want {
+			t.Errorf("X-Forwarded-For %q: ClientIP() = %q, want %q",
+				xff, got, want)
+		}
+	}
+}
+
 func TestSecurityHeaders(t *testing.T) {
 	t.Parallel()
 
@@ -323,6 +398,172 @@ func TestRecovererRepanicsOnAbortHandler(t *testing.T) {
 	}
 }
 
+// TestHandlerPanicIsLoggedAndCountedAs500 sends a request to a handler
+// that panics through the middleware SetupRoutes puts around a route
+// with metrics, in its order, leaving out those that write no status
+// for a panic and Sentry, which TestSentry covers. The request log line
+// and the metrics must give the 500 the client gets, and the panic must
+// still reach Recoverer, which logs it.
+func TestHandlerPanicIsLoggedAndCountedAs500(t *testing.T) {
+	t.Parallel()
+
+	var logbuf bytes.Buffer
+
+	mw := middleware.NewWithLogger(
+		slog.New(slog.NewJSONHandler(&logbuf, nil)),
+	)
+	registry := prometheus.NewRegistry()
+
+	handler := chi.Chain(
+		mw.Recoverer(),
+		chimiddleware.RequestID,
+		mw.Logging(),
+		mw.Write500OnPanic(),
+		mw.Metrics(registry),
+		mw.Write500OnPanic(),
+	).HandlerFunc(func(http.ResponseWriter, *http.Request) {
+		panic("boom")
+	})
+
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequestWithContext(t.Context(), http.MethodGet, "/", http.NoBody)
+	handler.ServeHTTP(rec, req)
+
+	if rec.Code != http.StatusInternalServerError {
+		t.Fatalf("status = %d, want %d",
+			rec.Code, http.StatusInternalServerError)
+	}
+
+	request := findLogLine(t, logbuf.Bytes(), "request")
+	if request.Status != http.StatusInternalServerError {
+		t.Errorf("request log status = %d, want %d",
+			request.Status, http.StatusInternalServerError)
+	}
+
+	recovered := findLogLine(t, logbuf.Bytes(), "panic recovered")
+	if recovered.Panic != "boom" {
+		t.Errorf("panic recovered line has panic %q, want %q",
+			recovered.Panic, "boom")
+	}
+
+	for _, name := range []string{
+		"http_request_duration_seconds", "http_response_size_bytes",
+	} {
+		codes := metricCodes(t, registry, name)
+		if len(codes) != 1 || codes[0] != "500" {
+			t.Errorf("%s code labels = %v, want [500]", name, codes)
+		}
+	}
+}
+
+// loggedLine holds the fields the tests read from a JSON log line.
+type loggedLine struct {
+	Msg    string `json:"msg"`
+	Status int    `json:"status"`
+	Panic  string `json:"panic"`
+}
+
+// findLogLine returns the first of the JSON log lines in logged whose
+// message is msg.
+func findLogLine(t *testing.T, logged []byte, msg string) loggedLine {
+	t.Helper()
+
+	dec := json.NewDecoder(bytes.NewReader(logged))
+
+	for {
+		var line loggedLine
+
+		err := dec.Decode(&line)
+		if err != nil {
+			t.Fatalf("no %q line in the log: %v (%q)", msg, err, logged)
+		}
+
+		if line.Msg == msg {
+			return line
+		}
+	}
+}
+
+// metricCodes returns the code label of each series of the metric
+// family name in registry.
+func metricCodes(
+	t *testing.T,
+	registry *prometheus.Registry,
+	name string,
+) []string {
+	t.Helper()
+
+	families, err := registry.Gather()
+	if err != nil {
+		t.Fatalf("gather metrics: %v", err)
+	}
+
+	var codes []string
+
+	for _, family := range families {
+		if family.GetName() != name {
+			continue
+		}
+
+		for _, metric := range family.GetMetric() {
+			for _, label := range metric.GetLabel() {
+				if label.GetName() == "code" {
+					codes = append(codes, label.GetValue())
+				}
+			}
+		}
+	}
+
+	return codes
+}
+
+// TestRecovererWritesNoSecondStatus checks, on a real server, that
+// Recoverer does not write its 500 again after Write500OnPanic has
+// written one, which the server would log as a superfluous
+// WriteHeader call.
+func TestRecovererWritesNoSecondStatus(t *testing.T) {
+	t.Parallel()
+
+	var serverLog bytes.Buffer
+
+	mw := middleware.NewWithLogger(slog.New(slog.DiscardHandler))
+
+	server := httptest.NewUnstartedServer(chi.Chain(
+		mw.Recoverer(),
+		mw.Write500OnPanic(),
+	).HandlerFunc(func(http.ResponseWriter, *http.Request) {
+		panic("boom")
+	}))
+	server.Config.ErrorLog = log.New(&serverLog, "", 0)
+	server.Start()
+
+	req, err := http.NewRequestWithContext(t.Context(),
+		http.MethodGet, server.URL, http.NoBody)
+	if err != nil {
+		t.Fatalf("new request: %v", err)
+	}
+
+	resp, err := server.Client().Do(req)
+	if err != nil {
+		t.Fatalf("request: %v", err)
+	}
+
+	_ = resp.Body.Close()
+
+	// Close waits for the handler to return, so whatever the server
+	// logs for this request is in serverLog after it.
+	server.Close()
+
+	if resp.StatusCode != http.StatusInternalServerError {
+		t.Errorf("status = %d, want %d",
+			resp.StatusCode, http.StatusInternalServerError)
+	}
+
+	if serverLog.Len() != 0 {
+		t.Errorf("server logged %q", serverLog.String())
+	}
+}
+
 // TestLoggingCutsRequestStringsToBound sends an over-long URL and
 // over-long header values, and checks the request log writes each
 // one cut to logger.MaxLoggedFieldBytes.

internal/reportbuf/datadir.go

@@ -18,9 +18,15 @@ var ErrDataDirOutsideVolume = errors.New(
 // 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.
+// and the directories, regular files and symbolic links in it to
+// owner, and gives volume and dir the mode the server gives a directory
+// it creates. It leaves a file with a second name (hard link) as it
+// is, as that name could be outside volume, and logs its path; it
+// leaves a device, named pipe or socket as it is too (see chownFile).
+// dir must be volume or a path below it, with no '.', '..', empty part
+// or '/' at the end. On any system but Linux, the system of the image, it
+// fails at the first file in volume that is not a directory (see
+// chownFile).
 //
 // bin/entrypoint.sh runs this as root, which would follow a symbolic
 // link anywhere, so every step goes through an os.Root opened on
@@ -32,10 +38,9 @@ var ErrDataDirOutsideVolume = errors.New(
 // 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.
+// volume. The owners and modes are set on files already opened (see
+// chownAll and 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.
@@ -66,7 +71,7 @@ func PrepareDataDir(volume, dir string, owner *user.User) error {
 		return err
 	}
 
-	err = lchownAll(root, ".", uid, gid)
+	err = chownAll(root, ".", uid, gid)
 	if err != nil {
 		return err
 	}
@@ -79,28 +84,23 @@ func PrepareDataDir(volume, dir string, owner *user.User) error {
 	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()
-
+// chownAll gives name, a directory inside root, and the directories,
+// regular files and symbolic links in it to uid and gid, but not the
+// files chownFile leaves. It opens each through root and gives the
+// open file to them, as chmodDir sets a mode on the open directory.
+// Root.Lchown would not hold: it acts on whatever is at the name by
+// then, and a hard link swapped in there shares its owner with a file
+// that could be outside root. A symbolic link is given to them itself,
+// never what it points to, because in a directory that anyone can
+// write to and that has the sticky bit set, as /tmp has, the kernel
+// follows a link only for the link's owner or when the link and the
+// directory have the same owner. chownAll goes into an entry only when
+// the read found a directory there, so it follows no link it finds;
+// one swapped in afterwards for a directory is followed only as the
+// os.Root allows, and one swapped in for any other file is not
+// followed at all (see chownFile).
+func chownAll(root *os.Root, name string, uid, gid int) error {
+	entries, err := chownDir(root, name, uid, gid)
 	if err != nil {
 		return err
 	}
@@ -108,9 +108,9 @@ func lchownAll(root *os.Root, name string, uid, gid int) error {
 	for _, entry := range entries {
 		entryName := filepath.Join(name, entry.Name())
 		if entry.IsDir() {
-			err = lchownAll(root, entryName, uid, gid)
+			err = chownAll(root, entryName, uid, gid)
 		} else {
-			err = root.Lchown(entryName, uid, gid)
+			err = chownFile(root, entryName, uid, gid)
 		}
 
 		if err != nil {
@@ -121,6 +121,36 @@ func lchownAll(root *os.Root, name string, uid, gid int) error {
 	return nil
 }
 
+// chownDir gives name, a directory inside root, to uid and gid, and
+// returns what it holds. Like chmodDir, it opens name through root and
+// refuses anything but a directory, which has no second name (hard
+// link). It reads the open directory, not root.FS(), which refuses a
+// name that is not valid UTF-8.
+func chownDir(root *os.Root, name string, uid, gid int) ([]fs.DirEntry, error) {
+	dir, err := root.Open(name)
+	if err != nil {
+		return nil, err
+	}
+
+	defer func() { _ = dir.Close() }()
+
+	info, err := dir.Stat()
+	if err != nil {
+		return nil, err
+	}
+
+	if !info.IsDir() {
+		return nil, &fs.PathError{Op: "chown", Path: name, Err: syscall.ENOTDIR}
+	}
+
+	err = dir.Chown(uid, gid)
+	if err != nil {
+		return nil, err
+	}
+
+	return dir.ReadDir(-1)
+}
+
 // 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,

internal/reportbuf/datadir_linux.go

@@ -0,0 +1,65 @@
+//go:build linux
+
+package reportbuf
+
+import (
+	"io/fs"
+	"log/slog"
+	"os"
+	"syscall"
+
+	"golang.org/x/sys/unix"
+)
+
+// chownFile gives name, a file inside root that is not a directory, to
+// uid and gid if it is a regular file or symbolic link with one name.
+// It leaves, and logs, a file of any kind with a second name (hard
+// link): all the names of a file share its owner, and the other could
+// be outside root. It leaves any other file with one name, such as a
+// device, named pipe or socket: the server needs to own none of them.
+// It opens name through root with O_PATH, which reads nothing from the
+// file, so opening a device or named pipe neither waits nor acts on
+// it; os.Root adds O_NOFOLLOW, and the two together open a symbolic
+// link itself, never what it points to. It reads the kind of file and
+// its number of names from the open file and gives that file to them,
+// so a hard link swapped in at name is caught too.
+//
+// This file is built only on Linux: prepare-data-dir runs only in the
+// Linux image, and macOS, where the backend is also built for
+// development, has neither O_PATH nor AT_EMPTY_PATH. On any other
+// system chownFile returns an error (see datadir_other.go).
+func chownFile(root *os.Root, name string, uid, gid int) error {
+	file, err := root.OpenFile(name, unix.O_PATH, 0)
+	if err != nil {
+		return err
+	}
+
+	defer func() { _ = file.Close() }()
+
+	info, err := file.Stat()
+	if err != nil {
+		return err
+	}
+
+	stat, ok := info.Sys().(*syscall.Stat_t)
+	if !ok || stat.Nlink > 1 {
+		slog.Warn("owner not changed: file has a second name (hard link)",
+			"path", file.Name())
+
+		return nil
+	}
+
+	if !info.Mode().IsRegular() && info.Mode().Type() != fs.ModeSymlink {
+		return nil
+	}
+
+	// File.Chown would fail: fchown refuses a file opened with O_PATH.
+	// Fchownat with an empty name and AT_EMPTY_PATH acts on the open
+	// file instead.
+	err = unix.Fchownat(int(file.Fd()), "", uid, gid, unix.AT_EMPTY_PATH)
+	if err != nil {
+		return &fs.PathError{Op: "chown", Path: file.Name(), Err: err}
+	}
+
+	return nil
+}

internal/reportbuf/datadir_other.go

@@ -0,0 +1,21 @@
+//go:build !linux
+
+package reportbuf
+
+import (
+	"errors"
+	"io/fs"
+	"os"
+)
+
+// chownFile returns an error on every system but Linux. Opening a file
+// that is not a directory without reading it or following it, and
+// giving it to a user on the open file, never by name, is built only
+// for Linux (see datadir_linux.go): prepare-data-dir runs only in the
+// Linux image, and macOS, where the backend is also built for
+// development, has neither O_PATH nor AT_EMPTY_PATH. This file lets
+// the package build elsewhere, such as on macOS, where a developer
+// runs make build and make run.
+func chownFile(_ *os.Root, name string, _, _ int) error {
+	return &fs.PathError{Op: "chown", Path: name, Err: errors.ErrUnsupported}
+}

internal/reportbuf/datadir_test.go

@@ -254,10 +254,13 @@ func TestPrepareDataDirTakesDirectoryNamedInLatin1(t *testing.T) {
 	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.
+// TestPrepareDataDirGivesVolumeToOwner gives the directories, regular
+// files and symbolic links 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. A hard link to a file outside the volume, one to a
+// symbolic link outside it and one to a named pipe outside it are left
+// as they were, and so is a named pipe in the volume.
 func TestPrepareDataDirGivesVolumeToOwner(t *testing.T) {
 	t.Parallel()
 
@@ -274,6 +277,16 @@ func TestPrepareDataDirGivesVolumeToOwner(t *testing.T) {
 		t.Fatal(err)
 	}
 
+	err = os.Symlink("f", filepath.Join(outside, "link"))
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	err = syscall.Mkfifo(filepath.Join(outside, "fifo"), 0o600)
+	if err != nil {
+		t.Fatal(err)
+	}
+
 	err = os.Mkdir(old, 0o700)
 	if err != nil {
 		t.Fatal(err)
@@ -289,6 +302,21 @@ func TestPrepareDataDirGivesVolumeToOwner(t *testing.T) {
 		t.Fatal(err)
 	}
 
+	err = syscall.Mkfifo(filepath.Join(old, "fifo"), 0o600)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	// os.Link does not follow a symbolic link: it gives the link itself
+	// a second name.
+	for _, name := range []string{"f", "link", "fifo"} {
+		err = os.Link(filepath.Join(outside, name),
+			filepath.Join(old, "hardlink-to-"+name))
+		if err != nil {
+			t.Fatal(err)
+		}
+	}
+
 	err = reportbuf.PrepareDataDir(volume, filepath.Join(volume, reports),
 		&user.User{Uid: "4242", Gid: "4343"})
 	if err != nil {
@@ -296,12 +324,16 @@ func TestPrepareDataDirGivesVolumeToOwner(t *testing.T) {
 	}
 
 	for _, path := range []string{
-		volume, filepath.Join(volume, reports), old,
-		filepath.Join(old, "f"), filepath.Join(old, "link"),
+		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)
+	for _, path := range []string{
+		outside, filepath.Join(outside, "f"), filepath.Join(outside, "link"),
+		filepath.Join(outside, "fifo"), filepath.Join(old, "fifo"),
+	} {
+		requireOwner(t, path, 0, 0)
+	}
 }

internal/reportbuf/reportbuf.go

@@ -1,6 +1,9 @@
 // Package reportbuf accumulates telemetry reports in memory
 // and periodically flushes them to zstd-compressed JSONL files,
-// deleting the oldest files to keep them under a size cap.
+// deleting the oldest files to keep them under a size cap. Before the
+// server starts, PrepareDataDir gets the directory those files are
+// kept in, DATA_DIR, ready for the user the server runs as: it creates
+// it and gives it and the volume it is on to that user.
 package reportbuf
 
 import (
@@ -13,7 +16,6 @@ import (
 	"log/slog"
 	"os"
 	"path/filepath"
-	"slices"
 	"strings"
 	"sync"
 	"sync/atomic"
@@ -70,11 +72,9 @@ 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,
-	// in name order, which is oldest first: those in dataDir at
-	// start, and each one this buffer writes, put in at its place by
-	// 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.
+	// oldest first: those in dataDir at start, in name order, then
+	// each one this buffer writes, once it is complete. A file still
+	// being written is not among them. filesBytes is their total size.
 	files      []reportFile
 	filesBytes int64
 	log        *slog.Logger
@@ -85,12 +85,30 @@ type Buffer struct {
 	now func() time.Time
 	// seq numbers the report files, so that two named in the same
 	// millisecond still get different names.
-	seq      atomic.Uint64
+	seq      atomic.Int64
 	stopOnce sync.Once
+	// thresholdWriteWaiting is set while a write Append started at
+	// flushSizeThreshold waits for writeMu; Append starts no other
+	// while it is set.
+	thresholdWriteWaiting atomic.Bool
 	// usedBytes is what Append checks against maxBytes: the size
 	// of the report files in dataDir, plus the reports waiting to
 	// be written to one at their uncompressed size.
 	usedBytes int64
+	// writeErr is the error of the last write of a report file to
+	// finish, nil if it succeeded or none has. While it is set, Append
+	// refuses reports, and the reports of that write wait in buf for
+	// the next flush.
+	writeErr error
+	// writeMu is held across each write of a report file, so writes
+	// never overlap: a failed write puts its reports back in buf before
+	// the next write takes them, which keeps them in the order they
+	// were appended.
+	writeMu sync.Mutex
+	// writers are the goroutines that write report files: flushLoop,
+	// and each one Append starts at flushSizeThreshold. OnStop waits
+	// for them before the final flush.
+	writers sync.WaitGroup
 }
 
 // New creates a Buffer and registers lifecycle hooks to
@@ -115,16 +133,33 @@ func New(
 
 	lc.Append(fx.Hook{
 		OnStart: func(_ context.Context) error {
+			// The errors name DATA_DIR, as config.New's do for the
+			// settings it checks.
 			err := os.MkdirAll(b.dataDir, dirPerms)
 			if err != nil {
-				return fmt.Errorf("create data dir: %w", err)
+				return fmt.Errorf("DATA_DIR %q: %w", b.dataDir, err)
+			}
+
+			// Creating and removing a file stops the start when no
+			// file can be created in DATA_DIR, instead of the first
+			// write of a report file failing after reports were
+			// answered 200. A full disk is not caught: the empty
+			// file is still created.
+			f, err := os.CreateTemp(b.dataDir, "")
+			if err != nil {
+				return fmt.Errorf("DATA_DIR %q: %w", b.dataDir, err)
+			}
+
+			err = errors.Join(f.Close(), os.Remove(f.Name()))
+			if err != nil {
+				return fmt.Errorf("DATA_DIR %q: %w", b.dataDir, err)
 			}
 
 			// Report files left by earlier runs count too, and are
 			// the first to be deleted to make room.
 			files, err := reportFiles(b.dataDir)
 			if err != nil {
-				return err
+				return fmt.Errorf("DATA_DIR %q: %w", b.dataDir, err)
 			}
 
 			b.mu.Lock()
@@ -142,7 +177,7 @@ func New(
 
 			b.mu.Unlock()
 
-			go b.flushLoop()
+			b.writers.Go(b.flushLoop)
 
 			return nil
 		},
@@ -153,7 +188,14 @@ func New(
 			var err error
 
 			b.stopOnce.Do(func() {
+				// Closing done ends flushLoop after any flush it is
+				// running. Wait for it and for the writes Append
+				// started, which the process exiting would cut off;
+				// one that fails puts its reports back in buf, for the
+				// final flush to write.
 				close(b.done)
+				b.writers.Wait()
+
 				err = b.flushLocked()
 			})
 
@@ -167,11 +209,13 @@ func New(
 }
 
 // Append marshals v as a single JSON line and appends it to
-// the buffer. If the line would take usedBytes past maxBytes, the
-// oldest report files are deleted to make room; it stores nothing
-// and returns ErrFull if that cannot make room. If the buffer
-// reaches the size threshold, it is drained and written to disk
-// asynchronously.
+// the buffer. It stores nothing and returns an error if the last
+// write of a report file failed, until a write succeeds again. If the
+// line would take usedBytes past maxBytes, the oldest report files are
+// deleted to make room; it stores nothing and returns ErrFull if that
+// cannot make room. If the buffer reaches the size threshold, it starts
+// a write of the reports in the background (see flushAtThreshold),
+// unless one it started is still waiting.
 func (b *Buffer) Append(v any) error {
 	line, err := json.Marshal(v)
 	if err != nil {
@@ -182,6 +226,13 @@ func (b *Buffer) Append(v any) error {
 
 	b.mu.Lock()
 
+	if b.writeErr != nil {
+		err = fmt.Errorf("report files cannot be written: %w", b.writeErr)
+		b.mu.Unlock()
+
+		return err
+	}
+
 	b.deleteOldestFiles(lineBytes)
 
 	if b.usedBytes+lineBytes > b.maxBytes {
@@ -194,18 +245,9 @@ func (b *Buffer) Append(v any) error {
 	b.buf.Write(line)
 	b.buf.WriteByte('\n')
 
-	if b.buf.Len() >= flushSizeThreshold {
-		data := b.drainBuf()
-		b.mu.Unlock()
-
-		go func() {
-			writeErr := b.writeFile(data)
-			if writeErr != nil {
-				b.log.Error("flush reports failed", "error", writeErr)
-			}
-		}()
-
-		return nil
+	if b.buf.Len() >= flushSizeThreshold &&
+		b.thresholdWriteWaiting.CompareAndSwap(false, true) {
+		b.writers.Go(b.flushAtThreshold)
 	}
 
 	b.mu.Unlock()
@@ -213,6 +255,16 @@ func (b *Buffer) Append(v any) error {
 	return nil
 }
 
+// LastWriteFailed reports whether the last write of a report file to
+// finish failed: false at start until a write fails, and false again
+// once a write succeeds. While it is true, Append refuses reports.
+func (b *Buffer) LastWriteFailed() bool {
+	b.mu.Lock()
+	defer b.mu.Unlock()
+
+	return b.writeErr != nil
+}
+
 // deleteOldestFiles deletes report files, oldest first, until n more
 // bytes fit under maxBytes. It deletes none when the reports waiting
 // to be written leave no room for n even with every file gone, since
@@ -263,21 +315,28 @@ func (b *Buffer) flushLoop() {
 	}
 }
 
-// flushLocked acquires the lock, drains the buffer, and
-// writes the data to a compressed file.
+// flushLocked waits for any write of a report file under way, then
+// writes the reports waiting in the buffer to a new one.
 func (b *Buffer) flushLocked() error {
-	b.mu.Lock()
+	b.writeMu.Lock()
+	defer b.writeMu.Unlock()
 
-	if b.buf.Len() == 0 {
-		b.mu.Unlock()
-
-		return nil
+	return b.writeFile()
 }
 
-	data := b.drainBuf()
-	b.mu.Unlock()
+// flushAtThreshold is the write Append starts when the buffer reaches
+// flushSizeThreshold. Once any write under way is done, it lets Append
+// start another and writes the reports waiting in the buffer.
+func (b *Buffer) flushAtThreshold() {
+	b.writeMu.Lock()
+	defer b.writeMu.Unlock()
 
-	return b.writeFile(data)
+	b.thresholdWriteWaiting.Store(false)
+
+	err := b.writeFile()
+	if err != nil {
+		b.log.Error("flush reports failed", "error", err)
+	}
 }
 
 // drainBuf copies the buffer contents and resets it.
@@ -290,9 +349,22 @@ func (b *Buffer) drainBuf() []byte {
 	return data
 }
 
-// writeFile writes data, reports drained from the buffer, to a new
-// timestamped zstd-compressed JSONL file in the data directory.
-func (b *Buffer) writeFile(data []byte) error {
+// writeFile takes the reports waiting in the buffer, if any, and writes
+// them to a new timestamped zstd-compressed JSONL file in the data
+// directory. If the write fails, it puts the reports back in the
+// buffer. The caller must hold b.writeMu.
+func (b *Buffer) writeFile() error {
+	b.mu.Lock()
+
+	if b.buf.Len() == 0 {
+		b.mu.Unlock()
+
+		return nil
+	}
+
+	data := b.drainBuf()
+	b.mu.Unlock()
+
 	// The timestamp comes first, so the names sort by time; the number
 	// after it tells apart files named in the same millisecond.
 	ts := b.now().UTC().Format("2006-01-02T15-04-05.000Z")
@@ -300,29 +372,30 @@ func (b *Buffer) writeFile(data []byte) error {
 
 	size, err := b.createFile(filepath.Join(b.dataDir, name), data)
 
-	// The reports no longer wait to be written, so they stop counting
-	// at their uncompressed size. If the write failed they are lost;
-	// otherwise they count as the file, which from here on may be
-	// deleted to make room.
 	b.mu.Lock()
 	defer b.mu.Unlock()
 
-	b.usedBytes -= int64(len(data))
+	b.writeErr = err
 
 	if err != nil {
+		// The reports go back in front of any appended since, for the
+		// next flush to write, and still count at their uncompressed
+		// size.
+		appended := bytes.Clone(b.buf.Bytes())
+		b.buf.Reset()
+		b.buf.Write(data)
+		b.buf.Write(appended)
+
 		return err
 	}
 
+	// The reports no longer wait to be written, so they stop counting
+	// at their uncompressed size and count as the file, which from here
+	// on may be deleted to make room.
+	b.usedBytes -= int64(len(data))
 	b.usedBytes += 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})
+	b.files = append(b.files, reportFile{name: name, size: size})
 
 	return nil
 }

internal/server/routes.go

@@ -34,13 +34,16 @@ func (s *Server) SetupRoutes() {
 	s.router.Use(s.mw.Recoverer())
 	s.router.Use(middleware.RequestID)
 	s.router.Use(s.mw.Logging())
+	// s.mw.Recoverer would write a panic's 500 only after the panic has
+	// passed the request log, so it is written here, where the log sees it.
+	s.router.Use(s.mw.Write500OnPanic())
 	s.router.Use(s.mw.SecurityHeaders())
 	s.router.Use(s.mw.CORS(s.params.Config.CORSAllowedOrigins))
 	s.router.Use(s.mw.MaxBodyBytes(maxRequestBodyBytes))
 	s.router.Use(middleware.Timeout(requestTimeout))
 
-	// Sentry reports a panic, then panics again, so that s.mw.Recoverer
-	// still answers 500.
+	// Sentry reports a panic, then panics again, so that it still
+	// reaches s.mw.Recoverer.
 	if s.params.Config.SentryDSN != "" {
 		s.router.Use(sentryhttp.New(sentryhttp.Options{Repanic: true}).Handle)
 	}
@@ -64,6 +67,8 @@ func (s *Server) SetupRoutes() {
 		// other.
 		if s.params.Config.MetricsUsername != "" {
 			r.Use(s.mw.Metrics(registry))
+			// Likewise inside the metrics.
+			r.Use(s.mw.Write500OnPanic())
 		}
 
 		r.Get("/.well-known/healthcheck", s.h.HandleHealthCheck())

internal/server/routes_test.go

@@ -22,9 +22,9 @@ import (
 	"go.uber.org/fx/fxtest"
 )
 
-// newServer builds a Server from the same constructors as main,
-// configured from the environment. It is never started, so nothing
-// listens.
+// newServer builds a Server from the same constructors as
+// cli.RunServer, configured from the environment. It is never started,
+// so nothing listens.
 func newServer(t *testing.T) *server.Server {
 	t.Helper()
 
@@ -66,6 +66,7 @@ func TestReportsAreRateLimited(t *testing.T) {
 			http.MethodPost, "/api/v1/reports",
 			strings.NewReader(`{"clientId":"c1","hosts":[]}`),
 		)
+		req.Header.Set("Content-Type", "application/json")
 		srv.ServeHTTP(rec, req)
 
 		return rec.Code

internal/server/server.go

@@ -79,7 +79,7 @@ func New(
 			s.SetupRoutes()
 			s.httpServer = s.newHTTPServer()
 
-			go s.listenAndServe()
+			go func() { s.listenAndServe() }()
 
 			return nil
 		},

package.json

@@ -1,6 +1,6 @@
 {
     "name": "netwatch",
-    "version": "1.0.0",
+    "private": true,
     "description": "Real-time network latency monitor SPA",
     "type": "module",
     "scripts": {

script/add-dependency

@@ -23,8 +23,8 @@ main() {
     "" | -* | *[[:space:]]*) usage ;;
     esac
     cd "$ROOT"
-    yarn add --dev "$1"
-    yarn install --frozen-lockfile
+    "$ROOT/script/yarn" add --dev "$1"
+    "$ROOT/script/yarn" install --frozen-lockfile
 }
 
 main "$@"

script/bootstrap

@@ -3,11 +3,14 @@
 # this repo. Idempotent: every install is guarded by a check so already
 # installed tools are skipped. Base tooling comes from nix, apt, brew,
 # or apk (detected in that order); assumes nothing is present. Node is
-# used directly if it is at least NODE_MIN_VERSION; otherwise it is
-# installed at a pinned version via nvm (installing nvm itself first,
-# from a hash-verified release archive, never curl | sh). Go, with its
-# gofmt, is used directly only if it is exactly GO_VERSION; otherwise
-# that release is installed from its hash-verified archive.
+# used directly only if it has the major version of NODE_VERSION and is
+# at least NODE_MIN_VERSION; otherwise NODE_VERSION is installed via nvm
+# (installing nvm itself first, from a hash-verified release archive,
+# never curl | sh). Yarn is used directly only if it is exactly
+# YARN_VERSION; otherwise that version is prepared through corepack,
+# or installed with npm where there is no corepack.
+# Go, with its gofmt, is used directly only if it is exactly GO_VERSION;
+# otherwise that release is installed from its hash-verified archive.
 #
 # What this script installs outside the system package manager lives
 # under $HOME and is linked into ~/.local/bin, where make and the git
@@ -17,7 +20,7 @@
 # golangci-lint is not installed: make lint runs it in Docker, as make
 # test runs the tests, and this script does not install Docker either.
 #
-# Unlike the org model: Go and gcc for backend/, a newer node for eslint.
+# Unlike the org model: Go for the backend, a newer node for eslint.
 set -eu
 
 ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
@@ -142,32 +145,63 @@ ensure_nvm() {
     rm -rf "$tmp"
 }
 
-# node_ok: the node on PATH is at least NODE_MIN_VERSION. node itself
-# compares the two: major, then minor, then patch.
+# node_ok: the node on PATH has the major version of NODE_VERSION and is
+# at least NODE_MIN_VERSION. Only the major is compared with the pin,
+# as REPO_POLICIES.md asks. node itself compares the versions: major,
+# then minor, then patch. A node that fails does not pass.
+# script/bootstrap and script/yarn carry this function unchanged.
 node_ok() {
-    if missing node; then return 1; fi
+    if ! command -v node >/dev/null 2>&1; then return 1; fi
     node -e '
         const have = process.versions.node.split(".").map(Number);
         const want = process.argv[1].split(".").map(Number);
+        const pinned = process.argv[2].split(".").map(Number);
+        if (have[0] !== pinned[0]) process.exit(1);
         for (let i = 0; i < 3; i++) {
             if (have[i] !== want[i]) process.exit(have[i] > want[i] ? 0 : 1);
         }
-    ' "$NODE_MIN_VERSION"
+    ' "$NODE_MIN_VERSION" "$NODE_VERSION"
 }
 
 # ensure_node: unless node_ok, install NODE_VERSION and link its node.
+# Afterwards node is looked up through PATH again and must pass node_ok.
 ensure_node() {
-    if node_ok; then return 0; fi
+    if node_ok; then
+        echo "bootstrap: using node $(node --version)"
+        return 0
+    fi
     ensure_nvm
     nvm_sh "nvm install $NODE_VERSION"
     link_bin "$HOME/.nvm/versions/node/v$NODE_VERSION/bin/node" node
+    hash -r
+    if ! node_ok; then
+        echo "bootstrap: after installing node $NODE_VERSION through nvm," >&2
+        echo "  the node on PATH, $(command -v node), is not it" >&2
+        exit 1
+    fi
+    echo "bootstrap: installed node $(node --version)"
 }
 
-# ensure_yarn: corepack writes its shims (pnpm and yarnpkg as well as
-# yarn) into $TOOLCHAIN rather than next to itself, and the npm fallback
-# installs there too; only yarn is linked.
+# yarn_ok: yarn --version on PATH prints exactly YARN_VERSION, compared
+# over the whole version. A yarn that fails or prints anything else does
+# not pass.
+yarn_ok() {
+    if missing yarn; then return 1; fi
+    version="$(yarn --version 2>/dev/null)" || return 1
+    [ "$version" = "$YARN_VERSION" ]
+}
+
+# ensure_yarn: unless yarn_ok, prepare YARN_VERSION and link its yarn.
+# corepack writes its shims (pnpm and yarnpkg as well as yarn) into
+# $TOOLCHAIN rather than next to itself, and the npm fallback installs
+# there too; only yarn is linked. Afterwards yarn is looked up through
+# PATH again and must pass yarn_ok, so another yarn that hides the link
+# stops bootstrap.
 ensure_yarn() {
-    if ! missing yarn; then return 0; fi
+    if yarn_ok; then
+        echo "bootstrap: using yarn $(yarn --version)"
+        return 0
+    fi
     shims="$TOOLCHAIN/corepack-shims"
     mkdir -p "$shims"
     if ! missing corepack; then
@@ -182,6 +216,13 @@ ensure_yarn() {
         shims="$TOOLCHAIN/npm-global/bin"
     fi
     link_bin "$shims/yarn" yarn
+    hash -r
+    if ! yarn_ok; then
+        echo "bootstrap: after installing yarn $YARN_VERSION in $shims," >&2
+        echo "  the yarn on PATH, $(command -v yarn), does not report it" >&2
+        exit 1
+    fi
+    echo "bootstrap: installed yarn $(yarn --version)"
 }
 
 # go_ok: the go on PATH has its gofmt beside it (a Go release ships the
@@ -272,19 +313,13 @@ 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 backend/'s 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
     yarn install --frozen-lockfile
 
     ensure_go
-    (cd "$ROOT/backend" && go mod download)
+    go mod download
 
     if missing docker; then
         echo "bootstrap: docker not found; make test and make lint, and so" >&2

script/build

@@ -1,13 +1,23 @@
 #!/bin/sh
-# script/build: build the frontend for production into dist/. The Go
-# backend is built by backend/script/build.
+# script/build: build the frontend for production into dist/, then the
+# static netwatch-server binary into the repo root, with its version
+# stamped in.
 set -eu
 
 ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
 
 main() {
     cd "$ROOT"
-    yarn build
+    "$ROOT/script/yarn" build
+
+    # VERSION comes from the environment. Unset or empty, it is
+    # `git describe --tags --always --dirty`, as in script/docker, or
+    # "dev" where there is no git or no repository history.
+    version="${VERSION:-$(git describe --tags --always --dirty 2>/dev/null || echo dev)}"
+
+    CGO_ENABLED=0 go build -trimpath \
+        -ldflags "-s -w -X main.Version=$version" \
+        -o netwatch-server ./cmd/netwatch-server/
 }
 
 main "$@"

script/cibuild

@@ -2,9 +2,12 @@
 # script/cibuild: run the CI build. It bootstraps first: a CI runner
 # checks out and runs this and nothing else, and script/fmt-check runs
 # the formatter on the host, which a pristine checkout cannot do.
-# --no-cache for the same reason as script/docker: the gate phases the
-# final stage depends on are RUN steps, and a cached one is a check that
-# did not run.
+# A new CACHEBUST value reruns every RUN step after the ARG CACHEBUST
+# line, since a cached gate phase is a check that did not run; unlike
+# --no-cache, it keeps the layers above that line and the cache mounts.
+# This relies on every stage of the Dockerfile declaring ARG CACHEBUST
+# before every step that lints, tests or compiles; a stage without that
+# line is served from cache on an unchanged tree, with no warning.
 set -eu
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)"
@@ -14,15 +17,17 @@ main() {
     cd "$ROOT"
     "$SCRIPT_DIR/bootstrap"
     "$SCRIPT_DIR/check"
-    # Own line: a failing command substitution inside an argument does
-    # not trip `set -e`, so the inline form degrades silently to an
-    # empty constant. The VERSION build argument takes precedence over
-    # the version a build stage derives from the .git in the context.
+    # The version and the tag each get their own line: a failing
+    # command substitution inside an argument does not trip `set -e`,
+    # so the inline form degrades silently to an empty constant. The
+    # VERSION build argument takes precedence over the version a build
+    # stage derives from the .git in the context.
     version="$(git describe --tags --always --dirty 2>/dev/null || true)"
     [ -n "$version" ] || version="unknown"
-    docker build --no-cache \
+    tag="$("$SCRIPT_DIR/projectname")"
+    docker build --build-arg CACHEBUST="$(date +%s)-$$" \
         --build-arg VERSION="$version" \
-        -t "$("$SCRIPT_DIR/projectname")" .
+        -t "$tag" .
 }
 
 main "$@"

script/clean

@@ -0,0 +1,13 @@
+#!/bin/sh
+# script/clean: remove what script/build writes: dist/ and the
+# netwatch-server binary.
+set -eu
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
+
+main() {
+    cd "$ROOT"
+    rm -rf dist netwatch-server
+}
+
+main "$@"

script/dev

@@ -7,7 +7,7 @@ ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
 
 main() {
     cd "$ROOT"
-    yarn dev
+    "$ROOT/script/yarn" dev
 }
 
 main "$@"

script/docker

@@ -1,8 +1,12 @@
 #!/bin/sh
 # script/docker: build the Docker image tagged with the project name.
 # Identical in all repos; the tag comes from script/projectname.
-# --no-cache because the gate phases the final stage depends on are RUN
-# steps, and a cached one is a check that did not run.
+# A new CACHEBUST value reruns every RUN step after the ARG CACHEBUST
+# line, since a cached gate phase is a check that did not run; unlike
+# --no-cache, it keeps the layers above that line and the cache mounts.
+# This relies on every stage of the Dockerfile declaring ARG CACHEBUST
+# before every step that lints, tests or compiles; a stage without that
+# line is served from cache on an unchanged tree, with no warning.
 set -eu
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)"
@@ -10,15 +14,17 @@ ROOT="$(cd "$SCRIPT_DIR/.." && pwd -P)"
 
 main() {
     cd "$ROOT"
-    # Own line: a failing command substitution inside an argument does
-    # not trip `set -e`, so the inline form degrades silently to an
-    # empty constant. The VERSION build argument takes precedence over
-    # the version a build stage derives from the .git in the context.
+    # The version and the tag each get their own line: a failing
+    # command substitution inside an argument does not trip `set -e`,
+    # so the inline form degrades silently to an empty constant. The
+    # VERSION build argument takes precedence over the version a build
+    # stage derives from the .git in the context.
     version="$(git describe --tags --always --dirty 2>/dev/null || true)"
     [ -n "$version" ] || version="unknown"
-    docker build --no-cache \
+    tag="$("$SCRIPT_DIR/projectname")"
+    docker build --build-arg CACHEBUST="$(date +%s)-$$" \
         --build-arg VERSION="$version" \
-        -t "$("$SCRIPT_DIR/projectname")" .
+        -t "$tag" .
 }
 
 main "$@"

script/fmt

@@ -1,7 +1,9 @@
 #!/bin/sh
 # script/fmt: format the whole repo (writes): prettier over the
-# JavaScript, CSS, HTML and Markdown, then gofmt over the Go backend.
-# The org model formats only markdown; this repo also has JS and Go.
+# JavaScript, CSS, HTML and Markdown, then gofmt over the Go sources in
+# cmd/ and internal/; not over the whole root, as node_modules/ holds
+# .go files of its own. The org model formats only markdown; this repo
+# also has JS and Go.
 set -eu
 
 ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
@@ -12,7 +14,7 @@ main() {
     # ~/.local/bin, which the shell that called it may not have on PATH.
     PATH="$HOME/.local/bin:$PATH"
     "$ROOT/script/frontend-fmt"
-    "$ROOT/backend/script/fmt"
+    gofmt -l -w cmd internal
 }
 
 main "$@"

script/fmt-check

@@ -12,7 +12,12 @@ main() {
     # ~/.local/bin, which the shell that called it may not have on PATH.
     PATH="$HOME/.local/bin:$PATH"
     "$ROOT/script/frontend-fmt-check"
-    "$ROOT/backend/script/fmt-check"
+    unformatted="$(gofmt -l cmd internal)"
+    if [ -n "$unformatted" ]; then
+        echo "Go files not formatted:" >&2
+        echo "$unformatted" >&2
+        exit 1
+    fi
 }
 
 main "$@"

script/frontend-fmt

@@ -1,16 +1,16 @@
 #!/bin/sh
 # script/frontend-fmt: format the JavaScript, CSS, HTML and Markdown,
-# repo-wide (writes), the markdown in backend/ included. Those are the
-# languages REPO_POLICIES.md gives prettier; the YAML is left alone, as
-# backend/.golangci.yml must stay the org standard byte for byte.
-# Prettier does not read Go; backend/script/fmt formats the Go sources.
+# repo-wide (writes). Those are the languages REPO_POLICIES.md gives
+# prettier; the YAML is left alone, as .golangci.yml must stay the org
+# standard byte for byte. Prettier does not read Go; script/fmt runs
+# gofmt over the Go sources.
 set -eu
 
 ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
 
 main() {
     cd "$ROOT"
-    yarn prettier --write '**/*.{js,css,html,md}'
+    "$ROOT/script/yarn" prettier --write '**/*.{js,css,html,md}'
 }
 
 main "$@"

script/frontend-fmt-check

@@ -7,7 +7,7 @@ ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
 
 main() {
     cd "$ROOT"
-    yarn prettier --check '**/*.{js,css,html,md}'
+    "$ROOT/script/yarn" prettier --check '**/*.{js,css,html,md}'
 }
 
 main "$@"

script/frontend-test

@@ -2,9 +2,10 @@
 # script/frontend-test: run the frontend test suite on the host: the
 # unit tests in test/unit/, through the test script in package.json,
 # then the production build, which fails on broken code. make test runs
-# the same in the frontend stage of Dockerfile. 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
+# the same tests in the frontend-test stage of Dockerfile, and the image
+# build runs the production build in its frontend-build stage. 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
@@ -13,12 +14,14 @@ ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
 
 main() {
     cd "$ROOT"
-    NODE_OPTIONS=--test-reporter=dot timeout 90 yarn --silent run test || {
+    NODE_OPTIONS=--test-reporter=dot \
+        timeout 90 "$ROOT/script/yarn" --silent run test || {
         echo "--- Rerunning with every test listed for details ---"
-        NODE_OPTIONS=--test-reporter=spec timeout 90 yarn --silent run test
+        NODE_OPTIONS=--test-reporter=spec \
+            timeout 90 "$ROOT/script/yarn" --silent run test
         exit 1
     }
-    timeout 30 yarn build
+    timeout 30 "$ROOT/script/yarn" build
 }
 
 main "$@"

script/frontend-viewport-test

@@ -2,11 +2,13 @@
 # script/frontend-viewport-test: verify the responsive layout of the built
 # frontend in a real browser engine.
 #
-# Builds dist/, serves it with the same nginx image and the same nginx.conf
-# the shipping container uses, points a containerised headless Chrome at it
-# over CDP, and asserts on computed layout at every viewport width derived
-# from the app's own CSS. See test/viewport/README.md for what this covers
-# and what it cannot.
+# Builds dist/, serves it with the same nginx image and the same
+# configs/nginx.conf the shipping container uses, points a containerised
+# headless Chrome at it over CDP, and asserts on computed layout at every
+# viewport width derived from the app's own CSS. See
+# test/viewport/README.md for what this covers and what it cannot.
+# Before the browser starts, it checks that the page is served with
+# Cache-Control: no-cache and Content-Security-Policy.
 #
 # Deliberately not part of script/check: it needs Docker and takes far
 # longer than the 20s budget make test has to stay inside.
@@ -61,20 +63,46 @@ main() {
     # host.
     docker network create --internal "$NETWORK" > /dev/null
 
-    # nginx.conf is a template: the image renders it over its own
+    # configs/nginx.conf is a template: the image renders it over its own
     # default.conf, with the same port and limit bin/entrypoint.sh uses.
     # The empty file it includes trusts no proxy, as bin/entrypoint.sh
-    # writes it when TRUSTED_PROXIES is unset. nginx.conf also includes
+    # writes it when TRUSTED_PROXIES is set and empty. It also includes
     # the security headers, so the page runs under the shipped policy.
     docker run -d --rm --name "$SERVER" \
         --network "$NETWORK" --network-alias netwatch \
         -e PORT=8080 -e NGINX_ENVSUBST_FILTER='^PORT$' \
         -v "$ROOT/dist:/usr/share/nginx/html:ro" \
-        -v "$ROOT/nginx.conf:/etc/nginx/templates/default.conf.template:ro" \
+        -v "$ROOT/configs/nginx.conf:/etc/nginx/templates/default.conf.template:ro" \
         -v /dev/null:/etc/nginx/trusted-proxies.conf:ro \
-        -v "$ROOT/security-headers.conf:/etc/nginx/security-headers.conf:ro" \
+        -v "$ROOT/configs/security-headers.conf:/etc/nginx/security-headers.conf:ro" \
         "$SERVER_IMAGE" > /dev/null
 
+    # The page, and /no-such-page, which location / answers with the
+    # page through its try_files fallback, must go out with
+    # Cache-Control: no-cache. That add_header in its location drops the
+    # server's own unless the location includes the security headers
+    # again; only Content-Security-Policy is checked, as it comes from
+    # the same file as the rest. curl tries up to ten more times, a
+    # second apart, while nginx starts. It runs without -S, which would
+    # print an error for every failed attempt, even when a later one
+    # succeeds.
+    for path in / /no-such-page; do
+        if ! headers="$(docker exec "$SERVER" curl -s -o /dev/null -D - \
+            --retry 10 --retry-connrefused --retry-delay 1 \
+            "http://127.0.0.1:8080$path")"; then
+            echo "frontend-viewport-test: nginx did not answer $path" >&2
+            exit 1
+        fi
+        headers="$(printf '%s\n' "$headers" | tr -d '\r')"
+        if ! printf '%s\n' "$headers" | grep -qix 'Cache-Control: no-cache' ||
+            ! printf '%s\n' "$headers" | grep -qi '^Content-Security-Policy:'; then
+            echo "frontend-viewport-test: $path needs" \
+                "Cache-Control: no-cache and Content-Security-Policy; got:" >&2
+            printf '%s\n' "$headers" >&2
+            exit 1
+        fi
+    done
+
     # The image's own entrypoint already exposes CDP on 9222 and passes
     # --no-sandbox, so only extra flags belong here; re-specifying the
     # debugging port collides with it and leaves the endpoint bound to

script/lint

@@ -5,9 +5,14 @@
 # make its answer untrustworthy.
 #
 # The phase is not the last stage in the file, so it is built only when
-# --target names it. --no-cache because a cached lint layer is a lint
-# that did not run. The tag makes each build replace the previous image
-# instead of leaving a dangling one behind.
+# --target names it. A new CACHEBUST value reruns every RUN step after
+# the ARG CACHEBUST line, since a cached lint layer is a lint that did
+# not run; unlike --no-cache, it keeps the layers above that line and
+# the cache mounts. This relies on every stage of the Dockerfile
+# declaring ARG CACHEBUST before every step that lints, tests or
+# compiles; a stage without that line is served from cache on an
+# unchanged tree, with no warning.
+# --output type=cacheonly writes no image, since nothing uses one.
 set -eu
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)"
@@ -15,9 +20,9 @@ ROOT="$(cd "$SCRIPT_DIR/.." && pwd -P)"
 
 main() {
     cd "$ROOT"
-    docker build --no-cache \
+    docker build --build-arg CACHEBUST="$(date +%s)-$$" \
         --target lint \
-        -t "$("$SCRIPT_DIR/projectname")-lint" .
+        --output type=cacheonly .
 }
 
 main "$@"

script/run

@@ -1,5 +1,6 @@
 #!/bin/sh
-# script/run: build and run netwatch-server locally.
+# script/run: build with script/build, then run netwatch-server locally
+# with its defaults: port 8080, reports stored in data/reports.
 set -eu
 
 ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"

script/test

@@ -2,8 +2,13 @@
 # script/test: run the test suite. Testing is a phase of the Dockerfile
 # and this builds that phase alone, on the same terms as script/lint:
 # --target because a phase that is not the last stage is built only when
-# named, --no-cache because a cached test layer is a test that did not
-# run, and a tag so each build replaces the previous image.
+# named, and a new CACHEBUST value because a cached test layer is a test
+# that did not run; unlike --no-cache, it keeps the layers above the ARG
+# CACHEBUST line and the cache mounts. This relies on every stage of the
+# Dockerfile declaring ARG CACHEBUST before every step that lints, tests
+# or compiles; a stage without that line is served from cache on an
+# unchanged tree, with no warning. --output type=cacheonly writes no
+# image, since nothing uses one.
 set -eu
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)"
@@ -11,9 +16,9 @@ ROOT="$(cd "$SCRIPT_DIR/.." && pwd -P)"
 
 main() {
     cd "$ROOT"
-    docker build --no-cache \
+    docker build --build-arg CACHEBUST="$(date +%s)-$$" \
         --target test \
-        -t "$("$SCRIPT_DIR/projectname")-test" .
+        --output type=cacheonly .
 }
 
 main "$@"

script/tidy

@@ -1,12 +1,12 @@
 #!/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.
+# script/tidy: run go mod tidy, 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"
+    cd "$ROOT"
     go mod tidy
 }
 

script/yarn

@@ -0,0 +1,55 @@
+#!/bin/sh
+# script/yarn: run yarn with the given arguments under the node
+# script/bootstrap would use. Every script that runs yarn on the host
+# runs it through this one, except script/bootstrap, which picks its
+# own node and yarn.
+set -eu
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
+
+# Must match the pins in script/bootstrap.
+NODE_VERSION="22.17.0"
+NODE_MIN_VERSION="22.13.0"
+
+# node_ok: the node on PATH has the major version of NODE_VERSION and is
+# at least NODE_MIN_VERSION. Only the major is compared with the pin,
+# as REPO_POLICIES.md asks. node itself compares the versions: major,
+# then minor, then patch. A node that fails does not pass.
+# script/bootstrap and script/yarn carry this function unchanged.
+node_ok() {
+    if ! command -v node >/dev/null 2>&1; then return 1; fi
+    node -e '
+        const have = process.versions.node.split(".").map(Number);
+        const want = process.argv[1].split(".").map(Number);
+        const pinned = process.argv[2].split(".").map(Number);
+        if (have[0] !== pinned[0]) process.exit(1);
+        for (let i = 0; i < 3; i++) {
+            if (have[i] !== want[i]) process.exit(have[i] > want[i] ? 0 : 1);
+        }
+    ' "$NODE_MIN_VERSION" "$NODE_VERSION"
+}
+
+# Run the yarn script/bootstrap installed: the yarn on PATH when the
+# node on PATH passes node_ok, and otherwise yarn under the pinned node
+# in nvm. nvm is a bash script, hence the subshell.
+run_yarn() {
+    if node_ok && command -v yarn >/dev/null 2>&1; then
+        exec yarn "$@"
+    fi
+    if node_ok || [ ! -s "$HOME/.nvm/nvm.sh" ]; then
+        echo "script/yarn: no yarn; run script/bootstrap first" >&2
+        exit 1
+    fi
+    exec bash -c '. "$HOME/.nvm/nvm.sh" && nvm use "$1" >/dev/null &&
+        shift && exec yarn "$@"' bash "$NODE_VERSION" "$@"
+}
+
+main() {
+    cd "$ROOT"
+    # script/bootstrap links the node and yarn it installs into
+    # ~/.local/bin, which the shell that called it may not have on PATH.
+    PATH="$HOME/.local/bin:$PATH"
+    run_yarn "$@"
+}
+
+main "$@"

test/unit/main.test.js

@@ -1,4 +1,4 @@
-// Unit tests for src/main.js, run with Node's built-in test runner by the
+// Unit tests for web/src/main.js, run with Node's built-in test runner by the
 // test script in package.json. Importing the module does not start the
 // page.
 
@@ -6,6 +6,7 @@ import { beforeEach, test } from "node:test";
 import assert from "node:assert/strict";
 import {
     AppState,
+    buildUI,
     CONFIG,
     greyOutUI,
     hostRowHTML,
@@ -13,19 +14,26 @@ import {
     humanDuration,
     latencyClass,
     latencyHex,
+    log,
     measureLatency,
+    Reporter,
     tick,
-} from "../../src/main.js";
+    updateClocks,
+    updateSummary,
+} from "../../web/src/main.js";
 
 // There is no page here, so the tests stand in for it. The debug log looks
-// for its panel by id and finds none. Each element of a host's row that
-// 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. In
-// each test, console.error and console.info print nothing and keep what
-// they are given.
+// for its panel by id and finds none, an element the page creates is a
+// plain object, and no frame the page asks for ever comes. Each element of
+// a host's row that 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. The commit the page's footer names, which
+// vite.config.js fills in when it builds the page, is blank. In each test,
+// console.error and console.info print nothing and keep what they are
+// given.
 const doNothing = () => {};
 let elements;
 beforeEach((t) => {
@@ -45,8 +53,13 @@ const canvasContext = {
     arc: doNothing,
 };
 globalThis.window = {};
+globalThis.requestAnimationFrame = doNothing;
+globalThis.cancelAnimationFrame = doNothing;
+globalThis.__COMMIT_HASH__ = "";
+globalThis.__COMMIT_FULL__ = "";
 globalThis.document = {
     getElementById: () => null,
+    createElement: () => ({}),
     querySelector: (selector) =>
         (elements[selector] ??= {
             getContext: () => canvasContext,
@@ -70,6 +83,11 @@ function statusText(state, host) {
     return elements[`.status-text[data-host="${index}"]`]?.innerHTML;
 }
 
+// What this test wrote to the browser console with console[method].
+function consoleLines(method) {
+    return console[method].mock.calls.map((call) => call.arguments[0]);
+}
+
 // Mocks the clock for test t, so that a check lasting seconds takes no real
 // time, and replaces fetch with targets that each answer after
 // answerAfter(url) milliseconds of that clock, or never when that is
@@ -189,9 +207,10 @@ test("at a 30000ms interval, a target answering after 1000ms shows in its row wh
 });
 
 // In the next three tests, the answering target's check is still waiting
-// when something happens after which its result must not show.
+// when something happens after which its result must not be recorded or
+// show in its row, and the check must write nothing to the console.
 
-test("at a 30000ms interval, a check still waiting when its round is given up does not show in its row", async (t) => {
+test("at a 30000ms interval, a check still waiting when its round is given up is not recorded and does not show in its row", async (t) => {
     CONFIG.updateInterval = 30000;
     const state = new AppState([
         { name: "Answering", url: "https://answering.test" },
@@ -207,9 +226,13 @@ test("at a 30000ms interval, a check still waiting when its round is given up do
     roundChecks.abort();
     assert.notEqual(await settled(round), "still waiting");
     assert.equal(latencyFigure(state, answering), undefined);
+    assert.deepEqual(answering.history, []);
+    assert.equal(answering.status, "pending");
+    assert.deepEqual(consoleLines("error"), []);
+    assert.deepEqual(consoleLines("info"), []);
 });
 
-test("at a 30000ms interval, a check still waiting when the user pauses does not show in its row", async (t) => {
+test("at a 30000ms interval, a check still waiting when the user pauses is not recorded and does not show in its row", async (t) => {
     CONFIG.updateInterval = 30000;
     const state = new AppState([
         { name: "Answering", url: "https://answering.test" },
@@ -224,9 +247,13 @@ test("at a 30000ms interval, a check still waiting when the user pauses does not
     t.mock.timers.tick(500);
     assert.equal(await settled(round), "still waiting");
     assert.equal(latencyFigure(state, answering), undefined);
+    assert.deepEqual(answering.history, []);
+    assert.equal(answering.status, "pending");
+    assert.deepEqual(consoleLines("error"), []);
+    assert.deepEqual(consoleLines("info"), []);
 });
 
-test("at a 30000ms interval, a check in the first round does not show in its row", async (t) => {
+test("at a 30000ms interval, a check in the first round is not recorded and does not show in its row", async (t) => {
     CONFIG.updateInterval = 30000;
     const state = new AppState([
         { name: "Answering", url: "https://answering.test" },
@@ -238,6 +265,10 @@ test("at a 30000ms interval, a check in the first round does not show in its row
     t.mock.timers.tick(1000);
     assert.equal(await settled(round), "still waiting");
     assert.equal(latencyFigure(state, answering), undefined);
+    assert.deepEqual(answering.history, []);
+    assert.equal(answering.status, "pending");
+    assert.deepEqual(consoleLines("error"), []);
+    assert.deepEqual(consoleLines("info"), []);
 });
 
 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) => {
@@ -287,11 +318,6 @@ function stateWithOneTarget() {
     return { state, target: state.local[0] };
 }
 
-// What this test wrote to the browser console with console[method].
-function consoleLines(method) {
-    return console[method].mock.calls.map((call) => call.arguments[0]);
-}
-
 test("a check that fails with a network error writes one console line with the target, the time, the error and how long the request took", async (t) => {
     const { state, target } = stateWithOneTarget();
     mockTargets(t, () => 23, target.url);
@@ -378,6 +404,131 @@ test("a check that fails in the first round, which is discarded, writes nothing
     assert.deepEqual(consoleLines("info"), []);
 });
 
+// The reports Reporter sent in this test, each as the hosts it sent.
+function reportedHosts() {
+    return fetch.mock.calls.map(
+        (call) => JSON.parse(call.arguments[1].body).hosts,
+    );
+}
+
+// In the next two tests every report is delivered, and only Target has
+// checks to report. target.reset() does to Target what the interval menu
+// does to each target.
+
+// The interval changes after the first report. The second report is sent
+// before Target's first check since then, and the third after it. A fourth
+// would hold no check the first three did not, so it is not sent.
+test("checks recorded before an interval change and not yet reported go in the next report, with the status of the last check, and no check is reported twice", async (t) => {
+    const state = new AppState([
+        { name: "Target", url: "https://target.test" },
+    ]);
+    const target = state.local[0];
+    const reporter = new Reporter(state, "client", CONFIG.reportInterval);
+    t.mock.method(globalThis, "fetch", async () => ({ ok: true }));
+
+    target.pushSample(1000, { latency: 10, error: null });
+    await reporter.flush();
+    target.pushSample(2000, { latency: 20, error: null });
+    target.pushSample(3000, { latency: null, error: "timeout" });
+    target.reset();
+    await reporter.flush();
+    target.pushSample(4000, { latency: 40, error: null });
+    await reporter.flush();
+    await reporter.flush();
+
+    const name = "Target";
+    const url = "https://target.test";
+    assert.deepEqual(reportedHosts(), [
+        [
+            {
+                name,
+                url,
+                status: "online",
+                history: [{ t: 1000, latency: 10, error: null }],
+            },
+        ],
+        [
+            {
+                name,
+                url,
+                status: "error",
+                history: [
+                    { t: 2000, latency: 20, error: null },
+                    { t: 3000, latency: null, error: "timeout" },
+                ],
+            },
+        ],
+        [
+            {
+                name,
+                url,
+                status: "online",
+                history: [{ t: 4000, latency: 40, error: null }],
+            },
+        ],
+    ]);
+    // The page's history starts over.
+    assert.deepEqual(target.history, [
+        { timestamp: 4000, latency: 40, error: null },
+    ]);
+});
+
+// The interval changes twice, after 60 checks each time, before the first
+// report. Of the 120 checks the interval menu cleared, the report has the
+// last 100 (CONFIG.maxHistoryPoints).
+test("of the checks interval changes cleared before they were reported, the next report has the last 100", async (t) => {
+    const state = new AppState([
+        { name: "Target", url: "https://target.test" },
+    ]);
+    const target = state.local[0];
+    const reporter = new Reporter(state, "client", CONFIG.reportInterval);
+    t.mock.method(globalThis, "fetch", async () => ({ ok: true }));
+
+    for (let n = 1; n <= 120; n++) {
+        target.pushSample(n * 1000, { latency: 10, error: null });
+        if (n % 60 === 0) target.reset();
+    }
+    await reporter.flush();
+
+    const sent = reportedHosts()[0][0].history;
+    assert.equal(sent.length, 100);
+    assert.equal(sent[0].t, 21000);
+    assert.equal(sent.at(-1).t, 120000);
+});
+
+// panel stands in for the open debug log panel, and for the element in it
+// that holds its lines, whichever the page looks up by id; the lines are
+// kept in order in lines. Drawing the whole panel, as opening it does,
+// replaces every line with a new one.
+test("with the debug log open, writing more lines than it keeps adds each to the panel and leaves the lines already shown as they are", (t) => {
+    const lines = [];
+    const panel = {
+        classList: { contains: () => false },
+        children: lines,
+        get firstElementChild() {
+            return lines[0];
+        },
+        append: (line) => lines.push(line),
+        removeChild: (line) => lines.splice(lines.indexOf(line), 1),
+        replaceChildren: (...newLines) =>
+            lines.splice(0, lines.length, ...newLines),
+    };
+    t.mock.method(globalThis.document, "getElementById", () => panel);
+    const kept = CONFIG.maxLogEntries;
+
+    for (let i = 1; i <= kept; i++) log.info(`line ${i}`);
+    const shown = [...lines];
+    for (let i = kept + 1; i <= kept + 5; i++) log.info(`line ${i}`);
+
+    assert.deepEqual(
+        lines.map((line) => line.textContent.match(/line \d+$/)?.[0]),
+        Array.from({ length: kept }, (_, i) => `line ${i + 6}`),
+    );
+    // The first five lines shown were dropped, and the rest are the same
+    // lines, not drawn again.
+    shown.slice(5).forEach((line, i) => assert.equal(lines[i], line));
+});
+
 // The page shows &lt; &gt; &quot; &amp; and &#39; in a row's markup as
 // < > " & and '.
 test(`a target whose name and URL hold < > " & and ' shows those characters in its row`, () => {
@@ -447,6 +598,32 @@ test("a check that timed out or found its target unreachable has a grey figure a
     assert.equal(latencyHex(null), "#6b7280");
 });
 
+// buildUI draws the page into #app, here a plain object. Each entry in the
+// footer's color legend is a colored dot and the latencies it stands for,
+// with < and > written as &lt; and &gt;. A latency takes the color of the
+// first entry in CONFIG.latencyColors whose limit it is below, so the
+// legend has, for each of those entries in order, a dot of its color (a
+// bg- class where CONFIG.latencyColors has a text- one) and the latencies
+// below its limit, or, for the last, which has no limit, the latencies
+// from the limit before it up. A gray dot for offline comes after them.
+test("the footer's color legend has each entry in CONFIG.latencyColors, with its color and limit, then offline", (t) => {
+    const app = {};
+    t.mock.method(globalThis.document, "getElementById", () => app);
+    buildUI(new AppState([]));
+
+    const legend = [
+        ...app.innerHTML.matchAll(/(bg-\w+-500) [^"]*"><\/span>(\S+)/g),
+    ].map(([, dot, latencies]) => [dot, latencies]);
+    const colors = CONFIG.latencyColors;
+    const expected = colors.map((color, i) => [
+        color.className.replace("text-", "bg-"),
+        color.below === Infinity
+            ? `&gt;=${colors[i - 1].below}ms`
+            : `&lt;${color.below}ms`,
+    ]);
+    assert.deepEqual(legend, [...expected, ["bg-gray-500", "offline"]]);
+});
+
 // A target whose checks, in turn, answered after each of latencies ms, or,
 // for null, found it unreachable.
 function hostAfter(latencies) {
@@ -523,6 +700,102 @@ test("the summary's min, max, median and average latency over the WAN targets' l
     });
 });
 
+// In the next two tests each element of the summary that updateSummary
+// writes into is a plain object, made the first time it is looked up and
+// kept in elements under "#" and its id.
+
+// The interval menu resets each target and counts the rounds from 0 again,
+// then updates the summary, before any check since the change is recorded.
+test("after an interval change, the summary's Reachable slot reads --/-- in white, as at page load", (t) => {
+    t.mock.method(
+        globalThis.document,
+        "getElementById",
+        (id) => (elements[`#${id}`] ??= {}),
+    );
+    const state = new AppState([]);
+    for (const host of state.wan) {
+        host.pushSample(Date.now(), { latency: 30, error: null });
+    }
+    state.tickCount = 5;
+
+    for (const host of state.allHosts) host.reset();
+    state.tickCount = 0;
+    updateSummary(state);
+
+    assert.equal(elements["#summary-reachable"].textContent, "--/--");
+    assert.equal(elements["#summary-reachable"].className, "text-white");
+});
+
+test("once every WAN target's check has failed, the summary's Reachable slot reads 0 of them, in red", (t) => {
+    t.mock.method(
+        globalThis.document,
+        "getElementById",
+        (id) => (elements[`#${id}`] ??= {}),
+    );
+    const state = new AppState([]);
+    for (const host of state.wan) {
+        host.pushSample(Date.now(), { latency: null, error: "timeout" });
+    }
+
+    updateSummary(state);
+
+    assert.equal(
+        elements["#summary-reachable"].textContent,
+        `0/${state.wan.length}`,
+    );
+    assert.equal(elements["#summary-reachable"].className, "text-red-400");
+});
+
+// In the next two tests each of the header's clocks is a plain object, made
+// the first time updateClocks looks it up and kept in elements under "#" and
+// its id.
+
+// The mocked clock reads 1970-01-01T00:00:00.000Z.
+test("the header's clocks show the local time with its time zone's name, and the UTC time", (t) => {
+    t.mock.method(
+        globalThis.document,
+        "getElementById",
+        (id) => (elements[`#${id}`] ??= {}),
+    );
+    t.mock.timers.enable({ apis: ["Date"] });
+
+    updateClocks();
+
+    assert.match(
+        elements["#clock-local"].textContent,
+        /^Local: \d{4}-\d\d-\d\d \d\d:\d\d:\d\d \S/,
+    );
+    assert.equal(
+        elements["#clock-utc"].textContent,
+        "UTC: 1970-01-01 00:00:00 UTC",
+    );
+});
+
+// Here Intl.DateTimeFormat is as in Chrome before 95, Firefox before 91 or
+// Safari before 15.4: it throws a RangeError when asked for the time zone's
+// "shortGeneric" name.
+test("in a browser that cannot name the time zone, updating the clocks throws nothing and leaves them blank", (t) => {
+    t.mock.method(
+        globalThis.document,
+        "getElementById",
+        (id) => (elements[`#${id}`] ??= {}),
+    );
+    const DateTimeFormat = Intl.DateTimeFormat;
+    t.mock.method(Intl, "DateTimeFormat", function (locales, options) {
+        if (options?.timeZoneName === "shortGeneric") {
+            throw new RangeError(
+                "Value shortGeneric out of range for Intl.DateTimeFormat options property timeZoneName",
+            );
+        }
+        return new DateTimeFormat(locales, options);
+    });
+
+    updateClocks();
+
+    assert.equal(elements["#clock-local"].textContent, "");
+    assert.equal(elements["#clock-utc"].textContent, "");
+});
+
 // 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.

test/viewport/README.md

@@ -7,11 +7,11 @@ make frontend-viewport-test
 ```
 
 It builds `dist/`, serves it from the same digest-pinned `nginx` image and the
-same `nginx.conf` the shipping container uses, drives a digest-pinned headless
-Chrome against it over CDP, and asserts on computed layout at every viewport
-width derived from the app's own CSS. Screenshots land in `tmp/viewport/`
-alongside a `results.json`; they are artifacts for a human to look at when
-something fails, not the evidence. The assertions are the evidence.
+same `configs/nginx.conf` the shipping container uses, drives a digest-pinned
+headless Chrome against it over CDP, and asserts on computed layout at every
+viewport width derived from the app's own CSS. Screenshots land in
+`tmp/viewport/` alongside a `results.json`; they are artifacts for a human to
+look at when something fails, not the evidence. The assertions are the evidence.
 
 The target is deliberately outside `make check`: it takes minutes, and
 `make test` has to stay under 60 seconds.
@@ -19,10 +19,10 @@ The target is deliberately outside `make check`: it takes minutes, and
 ## How the widths are chosen
 
 Not from a list of phone models. `viewports.js` parses the `@media` conditions
-out of `src/styles.css` and scans `src/main.js` and `index.html` for Tailwind
-responsive prefixes, then tests every breakpoint it finds at one pixel below it,
-exactly on it, and one pixel above it. A generic 375px "phone" test sails
-straight past an off-by-one at a media query boundary; `max-width: 768px`
+out of `web/src/styles.css` and scans `web/src/main.js` and `web/index.html` for
+Tailwind responsive prefixes, then tests every breakpoint it finds at one pixel
+below it, exactly on it, and one pixel above it. A generic 375px "phone" test
+sails straight past an off-by-one at a media query boundary; `max-width: 768px`
 matches _at_ 768, and the sweep pins down which side of that line each layout is
 on.
 
@@ -108,7 +108,7 @@ function of viewport width and CSS, and is covered above.
 
 Complementary layers, not two stacks. The unit tests in `test/unit/`, which
 `make test` runs with Node's built-in test runner, exercise the functions
-`src/main.js` exports in-process with no browser. This harness exercises
+`web/src/main.js` exports in-process with no browser. This harness exercises
 rendered layout in a real engine and is the only thing here that can see a media
 query. Neither replaces the other; assertions about computed styles and element
 geometry belong here, assertions about functions belong in `test/unit/`.

test/viewport/harness.js

@@ -51,7 +51,8 @@ const PROBE_DELAYS_MS = [2, 45, 123, 456, 780];
 // offline row rendering is exercised too.
 const UNREACHABLE_MODULUS = 7;
 // The gateway candidate that "answers", so gateway detection succeeds and
-// the Local Gateway row renders. Matches GATEWAY_CANDIDATES in src/main.js.
+// the Local Gateway row renders. Matches GATEWAY_CANDIDATES in
+// web/src/main.js.
 const RESPONSIVE_GATEWAY = "http://192.168.1.1";
 
 const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

test/viewport/viewports.js

@@ -161,26 +161,27 @@ const ANCHOR_VIEWPORTS = [
 export function deriveViewports(root) {
     const conditions = [
         ...mediaConditionsFromCss(
-            readFileSync(join(root, "src/styles.css"), "utf8"),
-            "src/styles.css",
+            readFileSync(join(root, "web/src/styles.css"), "utf8"),
+            "web/src/styles.css",
         ),
         ...mediaConditionsFromMarkup([
             {
-                path: "src/main.js",
-                text: readFileSync(join(root, "src/main.js"), "utf8"),
+                path: "web/src/main.js",
+                text: readFileSync(join(root, "web/src/main.js"), "utf8"),
             },
             {
-                path: "index.html",
-                text: readFileSync(join(root, "index.html"), "utf8"),
+                path: "web/index.html",
+                text: readFileSync(join(root, "web/index.html"), "utf8"),
             },
         ]),
     ];
 
     if (conditions.length === 0) {
         throw new Error(
-            "no responsive breakpoints found in src/styles.css, src/main.js or " +
-                "index.html — either the responsive layout was deleted or this " +
-                "derivation has stopped matching the sources",
+            "no responsive breakpoints found in web/src/styles.css, " +
+                "web/src/main.js or web/index.html — either the responsive " +
+                "layout was deleted or this derivation has stopped matching " +
+                "the sources",
         );
     }
 

vite.config.js

@@ -6,6 +6,10 @@ const commitHash = execSync("git rev-parse --short HEAD").toString().trim();
 const commitFull = execSync("git rev-parse HEAD").toString().trim();
 
 export default defineConfig({
+    // The page's source is in web/; the build still goes to dist/ at the
+    // repo root, which Dockerfile and the viewport test serve. Vite
+    // empties only an outDir inside root unless told to.
+    root: "web",
     plugins: [tailwindcss()],
     server: {
         // Proxy /api to a locally running netwatch-server so `yarn dev`
@@ -19,6 +23,8 @@ export default defineConfig({
         __COMMIT_FULL__: JSON.stringify(commitFull),
     },
     build: {
+        outDir: "../dist",
+        emptyOutDir: true,
         target: "esnext",
         minify: "esbuild",
         cssMinify: true,

web/index.html

@@ -9,7 +9,7 @@
             type="image/svg+xml"
             href="data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 100 100'><text y='.9em' font-size='90'>📡</text></svg>"
         />
-        <!-- Linked here, not imported by src/main.js, so the unit tests can
+        <!-- Linked here, not imported by web/src/main.js, so the unit tests can
              import that module in Node, which cannot import CSS. -->
         <link rel="stylesheet" href="/src/styles.css" />
     </head>

web/src/main.js

@@ -144,13 +144,15 @@ const WAN_HOSTS = [
 
 const debugLog = [];
 
-const log = (() => {
+export const log = (() => {
     function append(level, message) {
-        debugLog.push({ timestamp: new Date(), level, message });
+        const entry = { timestamp: new Date(), level, message };
+        debugLog.push(entry);
         if (debugLog.length > CONFIG.maxLogEntries)
             debugLog.splice(0, debugLog.length - CONFIG.maxLogEntries);
         const panel = document.getElementById("debug-panel");
-        if (panel && !panel.classList.contains("hidden")) renderDebugLog();
+        if (panel && !panel.classList.contains("hidden"))
+            appendDebugLogLine(entry);
     }
     return {
         error: (msg) => append("error", msg),
@@ -257,6 +259,14 @@ function latencyStats(latencies) {
     };
 }
 
+// The status a check's error gives its host: "error" for a timeout,
+// "offline" for any other error, and "online" for none.
+function statusFromError(error) {
+    if (error === "timeout") return "error";
+    if (error) return "offline";
+    return "online";
+}
+
 export class HostState {
     constructor(host, pinned = false) {
         this.name = host.name;
@@ -265,6 +275,10 @@ export class HostState {
         // error }, or a round skipped while paused, { timestamp,
         // latency: null, paused: true }.
         this.history = [];
+        // The last 100 (CONFIG.maxHistoryPoints) entries the interval menu
+        // has cleared from the history, which the reporter may not have
+        // sent yet.
+        this.clearedHistory = [];
         this.lastLatency = null;
         this.status = "pending"; // 'online' | 'offline' | 'error' | 'pending'
         this.pinned = pinned;
@@ -280,9 +294,7 @@ export class HostState {
         });
         this._trim();
         this.lastLatency = result.latency;
-        if (result.error === "timeout") this.status = "error";
-        else if (result.error) this.status = "offline";
-        else this.status = "online";
+        this.status = statusFromError(result.error);
         this.consecutiveFailures = result.error
             ? this.consecutiveFailures + 1
             : 0;
@@ -293,6 +305,18 @@ export class HostState {
         this._trim();
     }
 
+    // What the interval menu does to each host: the history starts over and
+    // the host waits for its next check. The history's entries move to
+    // clearedHistory, so the reporter still sends those it has not.
+    reset() {
+        this.clearedHistory = [...this.clearedHistory, ...this.history].slice(
+            -CONFIG.maxHistoryPoints,
+        );
+        this.history = [];
+        this.lastLatency = null;
+        this.status = "pending";
+    }
+
     // The min, max, median and average latency of the checks in the history
     // that got an answer.
     historyStats() {
@@ -429,9 +453,12 @@ function getClientId() {
 
 // Build the delta report body the backend decodes, plus the new per-host
 // high-water marks. Pure function of the passed state: `hosts` is an array
-// of { name, url, status, history }, `since` maps a host url to the Unix-ms
-// timestamp of the last sample already reported for it, and `now` is a Date.
-// Only non-paused samples newer than the mark are included. Returns null
+// of { name, url, status, clearedHistory, history }, `since` maps a host url
+// to the Unix-ms timestamp of the last sample already reported for it, and
+// `now` is a Date. Only non-paused samples newer than the mark are included,
+// from clearedHistory as well as history. A host whose status is pending,
+// as the interval menu leaves it until its next check, is sent with the
+// status of its last check, which is the last sample sent. Returns null
 // when no host has an unreported sample.
 export function buildReport(hosts, clientId, now, since) {
     const reportHosts = [];
@@ -440,7 +467,7 @@ export function buildReport(hosts, clientId, now, since) {
         const mark = since.get(host.url) ?? 0;
         const samples = [];
         let high = mark;
-        for (const p of host.history) {
+        for (const p of [...host.clearedHistory, ...host.history]) {
             if (p.paused) continue;
             if (p.timestamp <= mark) continue;
             samples.push({
@@ -454,7 +481,10 @@ export function buildReport(hosts, clientId, now, since) {
         reportHosts.push({
             name: host.name,
             url: host.url,
-            status: host.status,
+            status:
+                host.status === "pending"
+                    ? statusFromError(samples.at(-1).error)
+                    : host.status,
             history: samples,
         });
         marks.set(host.url, high);
@@ -481,7 +511,7 @@ export function buildReport(hosts, clientId, now, since) {
 // Only one report is ever in flight, and it is abandoned after half the
 // interval, so a slow POST can neither overlap the next report (which would
 // carry the same samples) nor stall reporting for good.
-class Reporter {
+export class Reporter {
     constructor(state, clientId, intervalMs) {
         this.state = state;
         this.clientId = clientId;
@@ -799,7 +829,7 @@ function wanRowsHTML(wanHosts) {
     return rows.join("");
 }
 
-function buildUI(state) {
+export function buildUI(state) {
     const app = document.getElementById("app");
     app.innerHTML = `
     <div class="mx-auto px-[5%] py-8">
@@ -881,7 +911,7 @@ function buildUI(state) {
           <span class="inline-block w-3 h-3 rounded-full bg-lime-500 mr-1 ml-3 align-middle"></span>&lt;100ms
           <span class="inline-block w-3 h-3 rounded-full bg-yellow-500 mr-1 ml-3 align-middle"></span>&lt;200ms
           <span class="inline-block w-3 h-3 rounded-full bg-orange-500 mr-1 ml-3 align-middle"></span>&lt;500ms
-          <span class="inline-block w-3 h-3 rounded-full bg-red-500 mr-1 ml-3 align-middle"></span>&gt;500ms
+          <span class="inline-block w-3 h-3 rounded-full bg-red-500 mr-1 ml-3 align-middle"></span>&gt;=500ms
           <span class="inline-block w-3 h-3 rounded-full bg-gray-500 mr-1 ml-3 align-middle"></span>offline
         </p>
         <p class="mt-2"><a href="https://git.eeqj.de/sneak/netwatch/commit/${__COMMIT_FULL__}" target="_blank" rel="noopener" class="text-gray-600 hover:text-gray-400">${__COMMIT_HASH__}</a></p>
@@ -965,7 +995,7 @@ function updateHostRow(host, index) {
     SparklineRenderer.draw(canvas, host.history);
 }
 
-function updateSummary(state) {
+export function updateSummary(state) {
     const stats = state.wanStats();
     const hstats = state.wanHistoryStats();
 
@@ -984,6 +1014,12 @@ function updateSummary(state) {
     const hmaxUnitEl = document.getElementById("summary-hmax-unit");
     if (!reachableEl) return;
 
+    // Before any WAN host's check is recorded, as after an interval change,
+    // no host has answered or failed, so the slot reads as at page load.
+    if (state.wan.every((h) => h.status === "pending")) {
+        reachableEl.textContent = "--/--";
+        reachableEl.className = "text-white";
+    } else {
         reachableEl.textContent = `${stats.reachable}/${stats.total}`;
         reachableEl.className =
             stats.reachable === stats.total
@@ -991,6 +1027,7 @@ function updateSummary(state) {
                 : stats.reachable === 0
                   ? "text-red-400"
                   : "text-yellow-400";
+    }
 
     if (stats.min !== null) {
         minEl.textContent = `${stats.min}`;
@@ -1077,11 +1114,37 @@ function updateHealthBox(state) {
     else if (health === "healthy") log.notice(`Health: ${labels[health]}`);
 }
 
+// Writes the local time, with its time zone's name, and the UTC time into
+// the header's clocks. The clocks only decorate the page: in a browser
+// whose Intl.DateTimeFormat rejects the "shortGeneric" time zone name
+// (Chrome before 95, Firefox before 91, Safari before 15.4) they are left
+// blank.
+export function updateClocks() {
+    let local = "";
+    let utc = "";
+    try {
+        const now = new Date();
+        const zone = new Intl.DateTimeFormat("en-US", {
+            timeZoneName: "shortGeneric",
+        })
+            .formatToParts(now)
+            .find((p) => p.type === "timeZoneName").value;
+        const pad = (n) => String(n).padStart(2, "0");
+        local = `Local: ${now.toLocaleString("sv-SE", { hour12: false })} ${zone}`;
+        utc =
+            `UTC: ${now.getUTCFullYear()}-${pad(now.getUTCMonth() + 1)}-${pad(now.getUTCDate())} ` +
+            `${pad(now.getUTCHours())}:${pad(now.getUTCMinutes())}:${pad(now.getUTCSeconds())} UTC`;
+    } catch {
+        // Both clocks are left blank.
+    }
+    document.getElementById("clock-local").textContent = local;
+    document.getElementById("clock-utc").textContent = utc;
+}
+
 // --- Debug Log Renderer ------------------------------------------------------
 
-function renderDebugLog() {
-    const el = document.getElementById("debug-log");
-    if (!el) return;
+// One line of the debug log panel, its message set as text.
+function debugLogLine(entry) {
     const levelColors = {
         error: "text-red-400",
         warning: "text-orange-400",
@@ -1089,19 +1152,43 @@ function renderDebugLog() {
         info: "text-gray-300",
         debug: "text-gray-500",
     };
-    el.replaceChildren(
-        ...debugLog.map((entry) => {
     const ts = formatUTCTimestamp(entry.timestamp);
     const lvl = entry.level.toUpperCase().padEnd(7);
     const line = document.createElement("div");
     line.className = levelColors[entry.level] || "text-gray-400";
     line.textContent = `${ts} ${lvl} ${entry.message}`;
     return line;
-        }),
-    );
+}
+
+// Draws every line of the debug log into the panel, when it is opened.
+function renderDebugLog() {
+    const el = document.getElementById("debug-log");
+    if (!el) return;
+    el.replaceChildren(...debugLog.map((entry) => debugLogLine(entry)));
     el.scrollTop = el.scrollHeight;
 }
 
+// The request that scrolls the open panel to its newest line in the next
+// frame. One waits at most, also in a hidden tab, where frames do not run.
+let debugLogScrollFrame = 0;
+
+// Adds entry to the open panel as its last line, and drops the first line
+// once the panel holds more than maxLogEntries. A check that ends while the
+// page is busy is timed only when the page is done, so the lines already
+// shown are left as they are, and the panel is scrolled once a frame
+// rather than once a line: scrolling it lays out all of its lines again.
+function appendDebugLogLine(entry) {
+    const el = document.getElementById("debug-log");
+    if (!el) return;
+    el.append(debugLogLine(entry));
+    if (el.children.length > CONFIG.maxLogEntries)
+        el.removeChild(el.firstElementChild);
+    cancelAnimationFrame(debugLogScrollFrame);
+    debugLogScrollFrame = requestAnimationFrame(() => {
+        el.scrollTop = el.scrollHeight;
+    });
+}
+
 // --- Sorting -----------------------------------------------------------------
 
 // Sort WAN hosts: pinned hosts first (alphabetically), then unpinned hosts
@@ -1449,24 +1536,6 @@ async function init() {
         sortAndRebuildWAN(state);
     });
 
-    function updateClocks() {
-        const now = new Date();
-        const pad = (n) => String(n).padStart(2, "0");
-        const utc =
-            `${now.getUTCFullYear()}-${pad(now.getUTCMonth() + 1)}-${pad(now.getUTCDate())} ` +
-            `${pad(now.getUTCHours())}:${pad(now.getUTCMinutes())}:${pad(now.getUTCSeconds())} UTC`;
-        const local =
-            now.toLocaleString("sv-SE", { hour12: false }) +
-            " " +
-            new Intl.DateTimeFormat("en-US", { timeZoneName: "shortGeneric" })
-                .formatToParts(now)
-                .find((p) => p.type === "timeZoneName").value;
-        document.getElementById("clock-local").textContent = "Local: " + local;
-        document.getElementById("clock-utc").textContent = "UTC: " + utc;
-    }
-    updateClocks();
-    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
     // more. At a steady interval they never are, as they time out at 80% of
@@ -1502,9 +1571,7 @@ async function init() {
 
             // Clear all host history and reset state
             for (const host of state.allHosts) {
-                host.history = [];
-                host.lastLatency = null;
-                host.status = "pending";
+                host.reset();
             }
             state.tickCount = 0;
 
@@ -1548,6 +1615,11 @@ async function init() {
 
     window.addEventListener("resize", () => handleResize(state));
     setTimeout(() => handleResize(state), CONFIG.resizeDelay);
+
+    // The clocks start last, after the rounds: they only decorate the page,
+    // so nothing in them may stop the monitor from probing.
+    updateClocks();
+    setInterval(updateClocks, 1000);
 }
 
 // Bootstrap only when loaded as the page: a real DOM containing the #app