README.md: rework against the fifth review, mostly by cutting

Fixes the seven findings and drops mechanism detail the code
and its comments hold. 5,864 words to 3,500.

Model: fable-5-1

README.md

@@ -36,23 +36,22 @@ make docker
 docker run -p 8080:8080 netwatch
 ```
 
-`make check` and `make docker` need Docker. `make dev` serves the page at the
+`make check` and `make docker` need Docker. `make run` starts `netwatch-server`
-address Vite prints and passes `/api` requests to `http://127.0.0.1:8080`.
+on port 8080 with its defaults, so the page's reports are stored in
-`make run` starts `netwatch-server` there with its defaults, so the page's
+`data/reports`. `make dev` passes the page's `/api` requests there.
-reports are stored in `data/reports`.
 
 ## The page
 
-The page shows one row per host. A row has the host's name, its URL, its latest
+The page shows one row per host: the host's name, its URL, its latest latency in
-latency in milliseconds and a graph of its last 100 checks. Below the figure,
+milliseconds and a graph of its last 100 checks. Below the figure are the
-the row shows the minimum, median, average and maximum of the host's answers in
+minimum, median, average and maximum of the host's answers in that history, or
-that history. After a failed check, it shows `timeout` or `unreachable` there
+`timeout` or `unreachable` after a failed check. A round of checks runs every 3
-instead. A round of checks runs every 3 seconds by default. The header shows the
+seconds by default. The header shows the interval, the history's span, and
-interval, how long the history spans, and whether the page is running or paused.
+whether the page is running or paused.
 
 ### Targets
 
-The page checks 26 hosts on the internet, called the WAN hosts:
+The page checks 26 hosts on the internet, the WAN hosts:
 
 - `datavi.be`, pinned to the top at start
 - the Anthropic API and the OpenAI API
@@ -63,79 +62,32 @@ The page checks 26 hosts on the internet, called the WAN hosts:
 - 6 Hetzner speed-test servers: Nuremberg, Falkenstein, Helsinki, Ashburn,
   Hillsboro and Singapore
 
-Two local targets follow under the heading "Local Network". They are left out of
+Two local targets follow under the heading "Local Network", left out of the
-the summary and the health box.
+summary and the health box. `Local CPE` is the cable modem at
+`http://192.168.100.1`. `Local Gateway` is the first of `http://192.168.1.1`,
+`http://192.168.0.1`, `http://192.168.8.1` and `http://10.0.0.1` to answer
+within 1.5 seconds of the page loading; with no answer, it has no row. Browsers
+block a page served from a public address from reaching private addresses. So
+the local targets answer only when the page is served from `localhost` or from a
+private address.
 
-- `Local CPE` is the cable modem at `http://192.168.100.1`. Its row is always
+The host list is written in `web/src/main.js`; there is no setting for it.
-  shown.
-- `Local Gateway` is found when the page loads. The page sends a request to
-  `http://192.168.1.1`, `http://192.168.0.1`, `http://192.168.8.1` and
-  `http://10.0.0.1`. The first to answer within 1.5 seconds becomes this target.
-  If none answers, there is no row for it.
-
-Browsers block a page served from a public address from reaching private
-addresses (Private Network Access). So the local targets answer only when the
-page is served from `localhost` or from a private address, and only on a network
-that has them.
-
-The host list is written in `web/src/main.js`. There is no setting for it.
 
 ### What a figure measures
 
-A check is a request to the target's URL: GET, or HEAD for the S3 regions. The
+A check is a request to the target's URL: `GET`, or `HEAD` for the S3 regions.
-figure is the time from sending the request until the response headers arrive,
+The figure is the time from sending the request until the response headers
-in milliseconds. Unlike ping, it includes the time the server takes to answer.
+arrive, in milliseconds. Unlike ping, it includes the time the server takes to
-When the browser opens a new connection, it also includes the DNS lookup, the
+answer. On a new connection it also includes the DNS lookup, the connection
-connection setup and the TLS handshake. Chrome opens a new connection for every
+setup and the TLS handshake. Any answer counts as reachable, an error page
-check of the Hetzner servers, and for more targets at longer intervals.
+included. The browser follows redirects, so a target whose home page redirects
+is checked at `/robots.txt` on the same host.
 
-Any answer counts as reachable, an error page included. The request is made in
+A check times out after 80% of the interval: 2.4 seconds at the default. A check
-the browser's `no-cors` mode, so the page cannot read the answer, only time it.
+that answers after that limit counts as a timeout too. A check that fails with a
-
+network error is recorded as unreachable. The first round after the page loads
-The browser follows redirects, and the figure then includes the request to the
+is discarded, as its figures include the connection setup. So is the first round
-new URL too. So a target whose home page redirects is checked at `/robots.txt`
+after an interval change.
-on the same host, which answers without a redirect. The S3 regions are checked
-with a HEAD request. Chrome keeps the connection to an S3 region open after a
-HEAD request, but closes it after most GET requests.
-
-The request is sent with `cache: 'no-store'`, so the browser's cache stays out
-of the measurement. It carries no `Referer` header and no query string: the
-Hetzner servers close the connection without an answer when either is present.
-
-A check times out after 80% of the interval: 2.4 seconds at the default of 3
-seconds, 24 seconds at 30 seconds. So a round's checks have all finished before
-the next round is due. A check that times out is recorded as a timeout, and so
-is one that answers after that limit. A check that fails with a network error is
-recorded as unreachable.
-
-A round can start early, after an interval change or when the recovery probe
-finds a target answering. It then gives up the last round's checks that are
-still waiting, so rounds never overlap.
-
-The first round after the page loads is discarded, as is the first round after
-an interval change. Its connections are all new, so its figures run high.
-
-The browser chooses between IPv4 and IPv6 for each target, as for any request.
-The local targets are IPv4 addresses.
-
-### Colors
-
-A latency figure and its line in the graph take one color:
-
-- green: under 50 ms
-- lime: under 100 ms
-- yellow: under 200 ms
-- orange: under 500 ms
-- red: 500 ms and over
-- gray: no answer
-
-### The graph
-
-The graph in each row plots the host's last 100 checks. At the default interval
-that is 5 minutes; the labels on its time axis say how long. The vertical axis
-runs from 0 to 1000 ms. A latency above 1000 ms is drawn at the top, and the
-figure still shows its real value. The rounds in which a check failed are shaded
-red.
 
 ### Health and summary
 
@@ -147,156 +99,93 @@ counts as failed when its last check timed out or found it unreachable.
 - `SLOW` (yellow): otherwise, more than 3 hosts took over 1000 ms
 - `HEALTHY` (green): otherwise
 
-Below the health box, a summary line covers the WAN hosts only:
+Below it, a summary line covers the WAN hosts only:
 
-- `Reachable`: how many answered in the last round, out of 26
+- `Reachable`: how many of the 26 answered their last check
 - `Now`: the minimum, median, average and maximum of their latest figures
-- the history's span, such as `5m`, with the minimum and maximum over the whole
+- the history's span, such as `5m`: the minimum and maximum over the whole
   history
-- `Checks`: the number of rounds run since the page loaded or the interval
+- `Checks`: the rounds run since the page loaded or the interval changed
-  changed
 
-When no WAN host answers, the page starts a recovery probe. Every half second it
+When no WAN host answers, the page checks 4 of them, picked at random, every
-checks 4 WAN hosts and gives up the checks it started half a second before. The
+half second. As soon as one answers, a new round starts.
-4 are picked at random when the probe starts. As soon as one answers, a new
-round starts at once.
 
-### Row order
+### Rows, colors and controls
 
-The WAN rows are sorted by their latest latency, fastest first and unreachable
+A figure and its line in the graph take the color of the legend in the footer,
-last. The rows are sorted when the second round ends, and again in rounds 11,
+from green under 50 ms to red from 500 ms up; gray is no answer. The graph's
-21, 31 and so on. The pin button at the left of a row keeps the row at the top.
+axis ends at 1000 ms; a higher latency is drawn at the top, and the figure still
-Pinned rows are sorted by name, and a line separates them from the rest.
+shows its real value.
-`datavi.be` is pinned at start.
 
-### Controls
+From time to time, the page sorts the WAN rows by their latest latency: fastest
+first, failed last. The pin button at the left of a row keeps the row at the
+top; pinned rows are sorted by name. `datavi.be` is pinned at start.
 
-- `Pause` stops the checks. The graphs keep scrolling and leave a gap for each
+`Pause` stops the checks: the graphs keep scrolling with a gap for each paused
-  paused round; no outage is drawn. The figures turn gray until `Resume`.
+round, and the figures turn gray. The `Interval` menu sets the time between
-- The `Interval` menu sets the time between rounds: 1, 2, 3, 5, 10, 15, 30 or 60
+rounds: 1, 2, 3, 5, 10, 15, 30 or 60 seconds. Changing it clears the history and
-  seconds. Changing it clears the history on the page and starts a new round at
+starts a new round at once. The `Debug log` checkbox in the footer opens a panel
-  once.
+with the page's last 1000 log lines.
-- The pin button in each WAN row pins and unpins the row.
-- Each host's URL is a link that opens in a new tab.
-- The `Debug log` checkbox in the footer opens a panel with the page's last 1000
-  log lines. Each line has a level: error, warning, notice, info or debug.
-- The header shows the local time with its time zone, and the UTC time. The
-  footer shows the color legend and links to the commit the page was built from.
-
-When the page records a failed check, it writes one line to the browser console
-with `console.error`, and the same line to the debug log. Nothing is written for
-the discarded first round, for a check a round gives up, or by the recovery
-probe. The line gives the target's name and URL, the time, what failed and how
-long the request took. The three kinds of failure are a timeout, an answer over
-the time limit, and a network error. For a network error the line quotes the
-error the browser gives the page, such as `TypeError: Failed to fetch`, which
-does not say why. When a target answers again after failed checks, one
-`console.info` line gives its latency and how many checks in a row had failed.
-
-### Browsers
-
-The page needs a browser with ES modules, the Fetch API, the Canvas API and CSS
-custom properties.
 
 ## Reporting
 
-Every 60 seconds the page gathers its undelivered samples and posts them as a
+Every 60 seconds the page posts its undelivered samples as a report to
-report to `/api/v1/reports` on the origin it was served from. When there are
+`/api/v1/reports` on the origin it was served from. The report is JSON with four
-none, it posts nothing. The report is JSON with four fields:
+fields:
 
-- `clientId`: a random id, made once per browser and kept in `localStorage`.
+- `clientId`: a random id, made once per browser and kept in `localStorage`, or
-  When the browser has no usable storage, a new id is made for the session.
+  once per session when the browser has no usable storage
 - `geo`: always `null`
-- `hosts`: one entry per host with new samples. The entry has the host's `name`,
+- `hosts`: one entry per host with new samples: its `name`, `url` and `status`,
-  `url` and `status`, and `history`, a list of samples. A sample has the check's
+  and `history`, its samples. A sample has the check's time `t` in Unix
-  time `t` in Unix milliseconds, its `latency` (`null` for a failed check) and
+  milliseconds, its `latency` (`null` for a failed check) and its `error`
-  its `error` (`"timeout"`, `"unreachable"` or `null`).
+  (`"timeout"`, `"unreachable"` or `null`).
 - `timestamp`: the time of the report
 
-Each report carries only the samples no earlier report has delivered. For each
+Each report carries only the samples no earlier report has delivered. A sample
-host, the page remembers the time of the newest sample it delivered, and moves
+waits only as long as the history holds it: the last 100 rounds of each host.
-that mark only when the server answers 2xx. Paused rounds are never sent. While
+Nothing is sent while the page is paused. A report with no answer after 30
-the page is paused, no report is sent at all. One report is in flight at a time.
+seconds is abandoned, and its samples go in the next one. So a server that
-A report with no answer after 30 seconds is abandoned, and its samples go in the
+stored them but answered late gets them twice.
-next report. So a server that stored them but answered late gets them twice.
 
-A failed delivery is quiet. The page writes one debug log line when deliveries
+A failed delivery is quiet, as on a static file host with no backend: one debug
-start failing and one when they recover. The checks go on.
+log line when deliveries start failing, one when they recover. The checks go on.
-
-A sample waits for delivery only as long as the history holds it. The history
-keeps each host's last 100 rounds: 5 minutes at the default interval of 3
-seconds. At 1 second it spans 100 seconds, at 2 seconds 200 seconds, and at 60
-seconds 100 minutes. Changing the interval clears the history. The cleared
-samples are kept apart, the last 100 per host, and those not yet delivered go in
-the next report.
-
-So at the 1-second interval, one refused or failed report loses the oldest 20
-seconds of each host's samples: the next delivered report comes 2 minutes after
-the last. At 2 seconds and longer, one failed report loses nothing. Samples are
-lost from the third failed report in a row at 2 seconds, from the fifth at 3
-seconds, and later still at longer intervals.
-
-Each paused round still adds an entry to the history, so each report due during
-a pause counts as a failed one. A pause longer than the history spans loses the
-samples recorded between the last delivered report and the pause: up to a
-minute's worth for each host.
 
 ## Deployment
 
-### Static files
+`make docker` builds the image `netwatch` from `Dockerfile`: the whole service
+in one container. nginx serves the page and passes `/api/`,
+`/.well-known/healthcheck` and `/metrics` to `netwatch-server` in the same
+container. The backend listens on `127.0.0.1:8081` only, as user `netwatch` (uid
+1000). `bin/entrypoint.sh` starts both and watches them.
 
-`make build` writes the page to `dist/`: an `index.html` and an `assets/`
+Before the backend starts, `bin/entrypoint.sh` runs two subcommands of
-directory with one CSS file and one JavaScript file. Any static file host can
+`netwatch-server`. `check-cidr` checks each `TRUSTED_PROXIES` entry (see
-serve it. Without a backend at `/api/v1/reports` on that host, the reports fail
+[Running under upaas](#running-under-upaas)). `prepare-data-dir` creates the
-quietly and nothing is stored.
+report directory and gives `/data`, with the directories, regular files and
+symbolic links in it, to user `netwatch`. It changes nothing outside `/data`.
 
-### The Docker image
+The image also:
 
-`make docker` builds the image `netwatch` from `Dockerfile`. It is the whole
+- takes the client address from `X-Forwarded-For` only on a request from a proxy
-service in one container. nginx serves the page and passes `/api/`,
+  named in `TRUSTED_PROXIES`, and passes that one address to the backend. The
-`/.well-known/healthcheck` and `/metrics` to `netwatch-server`, which runs in
+  backend is started with `TRUSTED_PROXIES=127.0.0.1/32`, so it trusts nginx
-the same container. The backend listens on `127.0.0.1:8081` only, as user
+  alone.
-`netwatch` (uid 1000). `bin/entrypoint.sh` starts both and watches them.
+- writes nginx's access log and the backend's JSON log to stdout
-
+- refuses a request body over 1 MiB with nginx's own 413 error page
-The image:
-
-- listens on port `8080`; the `PORT` variable changes it (see
-  [Settings](#settings))
-- stores the report files in `/data/reports`, on the `/data` volume. Before the
-  backend starts, `netwatch-server prepare-data-dir` creates that directory and
-  gives `/data` and the directories, regular files and symbolic links in it to
-  user `netwatch`. A file with a second name (hard link) keeps its owner, and
-  its path is logged. A host directory mounted at `/data` therefore ends up
-  owned by uid 1000. The command changes nothing outside `/data`, whatever links
-  it meets there.
-- takes the client address from `X-Forwarded-For` only on a request from a
-  reverse proxy named in `TRUSTED_PROXIES`. nginx resolves the address and
-  passes that one address to the backend. The backend is started with
-  `TRUSTED_PROXIES=127.0.0.1/32`, so it trusts nginx alone.
-- writes nginx's access log to stdout, and the backend's log as JSON to stdout
-- sends the page with `Cache-Control: no-cache`, so a browser that keeps a copy
-  asks the server whether it is current before using it again. The files under
-  `/assets/` are cached as immutable; their names change whenever their contents
-  do.
-- sends the security headers in `configs/security-headers.conf` on every
-  response, in place of the backend's own
-- refuses a request body over 1 MiB with nginx's own 413 error page; the backend
-  never sees such a request
 - requests `/.well-known/healthcheck` through nginx every 30 seconds, as its
-  `HEALTHCHECK`. The check fails unless both nginx and the backend answer. It
+  `HEALTHCHECK`. The check fails unless both nginx and the backend answer, and
-  also fails while report files cannot be written. Three failures in a row make
+  while report files cannot be written.
-  the container `unhealthy`; one pass makes it `healthy` again.
+- on `docker stop`, writes the waiting reports to disk and exits 0, or non-zero
-- on `docker stop`, writes the waiting reports to disk and exits 0. If that
+  if that write fails. If nginx or the backend exits on its own, the other is
-  final write fails, the container exits non-zero. If nginx or the backend exits
+  stopped and the container exits non-zero.
-  on its own, the other is stopped and the container exits non-zero, so the
-  platform restarts it.
 
 ### Running under upaas
 
 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`.
+- Volume: container path `/data`.
 - Environment variables: none is required. Every setting in
   [Settings](#settings) applies, with four differences in the image:
     - `BIND_ADDRESS` has no effect. The backend listens on `127.0.0.1` inside
@@ -307,14 +196,16 @@ The [upaas](https://git.eeqj.de/sneak/upaas) app for netwatch needs:
       `.` or `..` part and no extra `/`. A path through a symbolic link is
       refused unless the link is relative and stays inside `/data`.
     - `TRUSTED_PROXIES` names the proxies nginx trusts, as IP addresses or CIDRs
-      separated by commas. The backend's own setting is fixed to `127.0.0.1/32`.
+      separated by commas; the backend's own setting is fixed to `127.0.0.1/32`.
-      With `TRUSTED_PROXIES` set and empty, nginx trusts no proxy. Every client
+      `bin/entrypoint.sh` gives a lone address a `/32` or `/128` and checks each
-      behind the proxy then shares the proxy's one allowance of
+      entry with `netwatch-server check-cidr`, which refuses what the backend
-      `REPORTS_PER_MINUTE`. Any client that connects from an address in the set
+      would refuse. Set and empty, nginx trusts no proxy, and every client
-      can write its own `X-Forwarded-For`. A connection through a port Docker
+      behind a proxy then shares the proxy's one allowance of
-      publishes can arrive from the Docker network's gateway, such as
+      `REPORTS_PER_MINUTE`. A client that connects from a trusted address can
-      `172.17.0.1`. The default includes that address. Where that matters, name
+      write its own `X-Forwarded-For`. A port Docker publishes can bring
-      only the addresses that nothing but the proxy connects from.
+      connections from the Docker network's gateway, such as `172.17.0.1`, which
+      the default includes. Where that matters, name only the proxy's own
+      addresses.
 - Health: the image's `HEALTHCHECK`, described above.
 
 The container stops at start when a variable holds a value it cannot use. The
@@ -350,30 +241,24 @@ names the variable. An empty variable counts as unset, except `TRUSTED_PROXIES`.
   API, separated by commas. See [CORS](#cors).
 - `METRICS_USERNAME` and `METRICS_PASSWORD`, default empty: the basic auth
   credentials for `/metrics`. See [Metrics](#metrics).
-- `SENTRY_DSN`, default empty: the DSN of a Sentry project to report crashes to.
+- `SENTRY_DSN`, default empty: the DSN of a Sentry project. Each request whose
-  See [Sentry](#sentry).
+  handling crashes is reported there; the request still gets a 500.
 - `DEBUG`, default empty: any non-empty value turns debug logging on, `false`
   and `0` included. Every value is accepted.
 
 ### Trusted proxies
 
 Each `TRUSTED_PROXIES` entry must be a CIDR, such as `127.0.0.1/32`; a lone
-address is refused. A list replaces the default. Set and empty, the server
+address is refused. 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.
 
-A request from a peer outside this set has its forwarded headers ignored. The
+A request from a peer outside this set has its forwarded headers ignored; the
-peer's own address is logged and rate limited.
+peer's own address is logged and rate limited. From a peer inside the set, the
-
+client address is the right-most `X-Forwarded-For` entry that is not in the set.
-A request from a peer inside the set takes its client address from
+The peer's address is used when every entry is in the set, or when the search
-`X-Forwarded-For`. Each proxy appends the address it took the request from, so
+from the right meets an entry that is not an address, such as `unknown`.
-the entries on the right were written by trusted proxies and the ones further
+`X-Real-IP` is read only when `X-Forwarded-For` is missing or empty.
-left by the client. The client address is the right-most entry that is not in
-the set. An entry may carry a port, such as `198.51.100.7:5000` or
-`[2001:db8::1]:443`. It is read as the address alone. The peer's address is used
-when every entry is in the set. It is also used when the search from the right
-meets an entry that is not an address at all, such as `unknown`. `X-Real-IP` is
-read only when `X-Forwarded-For` is missing or empty.
 
 ### Routes
 
@@ -391,29 +276,14 @@ Every request body is capped at 1 MiB, and every request at 60 seconds.
 ### Report storage
 
 The server keeps the reports it takes in memory and writes them to `DATA_DIR` as
-files of JSON lines, compressed with zstd. It writes the waiting reports to a
+files of JSON lines, compressed with zstd. It writes a new file every minute,
-new file every minute, whenever 10 MiB of them are waiting, and when it stops.
+whenever 10 MiB of reports are waiting, and when it stops. With none waiting, it
-With none waiting, it writes no file.
+writes no file. The files are named `reports-<timestamp>-<number>.jsonl.zst`;
+the timestamp is UTC to the millisecond, so the names sort by time.
 
-The files are named `reports-<timestamp>-<number>.jsonl.zst`. The timestamp is
+The reports of a failed write, as on a full disk, stay in memory for the next
-UTC to the millisecond, so the names sort by time. The number starts at 1 when
+write to try again. Until a write succeeds, `POST /api/v1/reports` refuses every
-the server starts, and goes up by one for each file the server starts to write.
+report with 500 and the health check answers 503.
-So two files started in the same millisecond still get different names. A file
-is created with `O_EXCL`, so it never overwrites another.
-
-A write can fail, as when the disk is full. The reports of a failed write stay
-in memory. The next write tries them again, within a minute. One file is written
-at a time, so a file holds its reports in the order they arrived, those of a
-failed write included. A failed write uses up its number. A file it created is
-removed. If removing it fails too, the file stays and counts toward
-`DATA_DIR_MAX_BYTES` from the next start.
-
-From a 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. The
-page sends the refused samples again in its next report, as long as it still
-holds them (see [Reporting](#reporting)). Reports already answered 200 are lost
-only if the server stops before a write succeeds. The final write at stop tries
-them too, and if it fails, the process exits non-zero.
 
 ### Report limits
 
@@ -421,102 +291,48 @@ them too, and if it fails, the process exits non-zero.
 bounded in four ways. Each refusal by the backend answers with the body
 `{"status":"error"}`.
 
-- JSON only. A report must be sent with `Content-Type: application/json`, with
+- JSON only. A report must be sent with `Content-Type: application/json`; any
-  or without parameters such as `charset`, as the page sends it. Any other
+  other content type is refused with 415, and malformed JSON with 400.
-  content type is refused with 415, and nothing of it is stored. A page on
+- Body limit. A report body may be at most 1 MiB. A request that declares a
-  another origin can send a `text/plain` POST, or a form, without a CORS
+  longer body, or a report that runs past that, is refused with 413.
-  preflight. Refusing those 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. A request that declares a longer body is answered 413 before it
-  reaches the route. A body sent without a declared length is read up to 1 MiB.
-  The route answers 413 only when the report runs past that; nothing after the
-  end of the report is read. A body that stops being valid JSON sooner is
-  answered 400. In the image, nginx refuses a body over 1 MiB itself, with its
-  own HTML error page, and the backend never sees the request.
 - Rate limit. Each client address may send `REPORTS_PER_MINUTE` reports a
-  minute. [Trusted proxies](#trusted-proxies) says how that address is found.
+  minute; past that it gets 429 with `Retry-After: 60`. The page sends one
-  Past that it gets 429 with `Retry-After: 60`. The minute slides: reports from
+  report a minute from each open tab, so the default of 60 refuses nothing from
-  the minute before still count, fading out over the current one. An address
+  up to 30 tabs behind one address.
-  that sends at most half the limit in any 60 seconds is never refused. Above
-  that, it may be. 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, however
-  their reports bunch up. Every answer the route gives carries the headers
-  `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset`.
 - Size cap. The report files in `DATA_DIR` may total at most
-  `DATA_DIR_MAX_BYTES`, counting the files already there at start. Reports
+  `DATA_DIR_MAX_BYTES`, counting the files already there at start and the
-  waiting in memory count at their uncompressed size until they are written.
+  reports waiting in memory. When a report would take the total past the cap,
-  When a report would take the total past the cap, the oldest report files are
+  the oldest files are deleted to make room. A report is refused with 507 when
-  deleted to make room, and each deletion is logged with the file's name and
+  deleting the oldest files cannot make room.
-  size. A file still being written is never deleted. A report is refused with
-  507 only when the reports waiting to be written fill the cap on their own;
-  then no file is deleted. At start, report files past the cap are deleted the
-  same way, as after lowering it.
 
-So the cap decides how much of the newest reports is kept. The default of 1 GiB
+At the defaults, one address can fill the 1 GiB cap with its own reports in
-fits on any host; set it to the space you can give `DATA_DIR`. At the defaults,
+about 17 minutes, and every report stored before them is deleted to make room.
-one address may send 60 reports of up to 1 MiB a minute. A report made up to
-compress badly takes about as much room in the files as in its request body. So
-in about 17 minutes one address can fill the 1 GiB cap with its own reports, and
-every report stored before them is deleted to make room. A lower
-`REPORTS_PER_MINUTE` or a higher `DATA_DIR_MAX_BYTES` makes that take longer.
 
 ### CORS
 
-The page calls the API from the origin it is served from. By default the server
+The page needs no entry here: it calls the API from the origin it is served
-sends no CORS headers, so browsers let no other origin's pages call it.
+from. By default the server sends no CORS headers, and browsers let no other
-`CORS_ALLOWED_ORIGINS` lets pages served from the listed origins call the API,
+origin's pages call it. `CORS_ALLOWED_ORIGINS` lists other origins, such as
-for example `https://netwatch.example.com`. The page as built posts to its own
+`https://netwatch.example.com`, whose pages may then call the API with `GET` and
-origin only, so it needs no entry. Pages from a listed origin may `GET` and
+`POST`. Each entry must be a plain origin as browsers send it: `scheme://host`,
-`POST` with a `Content-Type` header.
+with an optional `:port`, no path, no trailing `/` and no `*`.
-
-Each entry must be a plain origin as browsers send it: `scheme://host`, with an
-optional `:port`, no path, no trailing `/` and no `*`. Any other entry stops the
-server from starting.
 
 ### Metrics
 
 With both `METRICS_USERNAME` and `METRICS_PASSWORD` set, the server serves
 Prometheus metrics at `GET /metrics`. A request with those as its basic auth
-credentials gets them; any other gets 401. With neither set, there are no
+credentials gets them; any other gets 401. With neither set, `/metrics`
-metrics and `/metrics` answers 404. One set without the other stops the start,
+answers 404. The metrics record each request that reaches the health check or
-and so does a user name containing `:`.
+`POST /api/v1/reports`: its duration and response size, labelled with its path,
-
+method and status. Each client address may make 60 requests to `/metrics` a
-The metrics record each request that reaches the health check or
+minute. Past that it gets 429 with `Retry-After: 60`, and its credentials are
-`POST /api/v1/reports`. For each, they record its duration and response size,
+not checked.
-labelled with its path, method and status, and they count such requests in
-progress. Requests the rate limit refuses are included. Go's runtime and process
-metrics are included too. No other request is recorded:
-
-- not a request to `/metrics` itself
-- not a CORS preflight
-- not a 404 for an unknown path, or a 405 for the wrong method
-- not a 413 answered before the route
-
-Only those two routes are recorded because the labels are the request's path and
-method. Recording every request would let clients add labels without bound.
-
-`/metrics` has its own rate limit, so that its password cannot be guessed
-quickly. Each client address may make 60 requests to it a minute, whatever its
-credentials. The address is found as for reports. Past that it gets 429 with
-`Retry-After: 60`, and its credentials are not checked. The minute slides as it
-does for reports, so a scraper polling every 2 seconds or less often is never
-refused.
-
-### Sentry
-
-With `SENTRY_DSN` set, each request whose handling crashes is reported to that
-Sentry project, under the release `netwatch-server-` followed by the server's
-version. The request still gets a 500 answer. The server does not start if
-Sentry rejects the DSN. On shutdown the server waits up to 2 seconds for Sentry
-to finish sending. Empty, the server sends nothing to Sentry.
 
 ### Logging
 
 The backend logs JSON to stdout, or plain text when stdout is a terminal. Each
-line names the source location it was written from. Each request is logged with
+request is logged with its method, URL, status, client address and duration.
-its method, URL, status, client address and duration, among other fields. Every
+Every value taken from a request is cut to 128 bytes before it is logged.
-value taken from a request is cut to 128 bytes before it is logged.
 
 ## Design
 
@@ -538,24 +354,17 @@ The repository holds the page, the backend and the image:
 The page is built with Vite and Tailwind CSS v4. All its code is in
 `web/src/main.js`:
 
-- `CONFIG` holds the timing and display constants. The interval menu sets its
+- `CONFIG`: the timing and display constants. The interval menu sets its
-  `updateInterval`; the check timeout, the history span and the time axis are
+  `updateInterval`; the check timeout and the history span follow from it.
-  computed from it.
+- `WAN_HOSTS`: the WAN targets, each with its URL and, for the S3 entries, the
-- `WAN_HOSTS` is the list of WAN targets, each with its URL. The S3 entries also
+  method `HEAD`.
-  name HEAD as their method.
+- `HostState` and `AppState`: one host's history and status, and the whole
-- `HostState` is one host's history, latest latency and status.
+  page's state.
-- `AppState` holds the WAN hosts, the local hosts, the pause state and the round
+- `measureLatency`: one check. `tick`: one round, which checks every host in
-  count, and computes the summary and the health.
+  parallel and draws each row as soon as its check ends.
-- `measureLatency` runs one check.
+- `SparklineRenderer`: the graphs. `buildUI`, `updateHostRow`, `updateSummary`
-- `tick` runs one round. It checks every host in parallel and draws each row as
+  and `updateHealthBox`: the page and its parts.
-  soon as its check ends. When the last check ends, it redraws every row, the
+- `Reporter`: builds and posts the reports. `buildReport` is a pure function of
-  summary and the health box, and sorts the rows when a sort is due. A discarded
-  round draws nothing.
-- `SparklineRenderer` draws a graph on a canvas, scaled to the device's pixel
-  ratio.
-- `buildUI` builds the page; `updateHostRow`, `updateSummary` and
-  `updateHealthBox` redraw its parts.
-- `Reporter` builds and posts the reports. `buildReport` is a pure function of
   the hosts' state.
 
 ### The backend
@@ -563,24 +372,17 @@ The page is built with Vite and Tailwind CSS v4. All its code is in
 `netwatch-server` is a Go HTTP server. The `fx` library starts and stops its
 parts in dependency order. The backend's packages are in `internal/`:
 
-- `cli` runs the command line. Given no arguments, it runs the server. It also
+- `cli`: the command line: the server when given no arguments, or the
-  runs the `check-cidr` and `prepare-data-dir` subcommands, which
+  `check-cidr` and `prepare-data-dir` subcommands that `bin/entrypoint.sh` runs.
-  `bin/entrypoint.sh` runs before the server starts. Any other arguments get a
+- `config`: reads the settings and refuses values the server cannot use.
-  usage message and exit code 2.
+- `server`: the router, the routes and the HTTP server.
-- `config` reads the settings and refuses values the server cannot use.
+- `middleware`: the request log, the security headers, CORS, the body limit, the
-- `server` builds the router and the HTTP server and registers the routes.
+  rate limit, the client address resolution and the metrics.
-- `middleware` holds the request log, the security headers, CORS, the body
+- `handlers`: the health check and the report route.
-  limit, the rate limit, the client address resolution and the metrics.
+- `reportbuf`: the in-memory buffer of reports and the files it writes them to.
-- `handlers` answers the health check and takes reports.
+  It also holds `PrepareDataDir`, which `prepare-data-dir` runs.
-- `reportbuf` is the in-memory buffer of reports and the files it writes them
+- `healthcheck`, `logger` and `globals`: the health status, the logger, and the
-  to. It also holds `PrepareDataDir`, which `prepare-data-dir` runs.
+  name and version the build stamps in.
-- `healthcheck`, `logger` and `globals` hold the health status, the logger and
-  the name and version the build stamps in.
-
-In the image, the `test` phase of `Dockerfile` tests the backend, the `builder`
-stage builds it, and `bin/entrypoint.sh` runs it as user `netwatch` on
-`127.0.0.1:8081`, behind nginx. Outside the image, `make run` builds it and runs
-it on port 8080.
 
 ## Development
 
@@ -589,100 +391,55 @@ it on port 8080.
 This repository adheres to the
 [Scripts to Rule Them All](https://github.com/github/scripts-to-rule-them-all)
 standard. The scripts in `script/` are the entrypoints for the development
-workflow, and the `Makefile` targets are thin shims that call them. The scripts
+workflow, and the `Makefile` targets are thin shims that call them.
-cover both the page and the Go backend, so `make check` fails if either one is
-broken. Every script that runs yarn on the host does so through `script/yarn`,
-except `script/bootstrap`.
 
-- `script/bootstrap`: install the dependencies. It uses the `node` on `PATH`
+- `script/bootstrap`: install the dependencies. It installs the pinned node,
-  when that node has the pinned major version and is new enough for the page's
+  yarn and Go when the ones on `PATH` do not pass its checks, and links them
-  dependencies. Otherwise it installs nvm from a hash-verified archive, and the
+  into `~/.local/bin`, which has to be on `PATH`. It installs no Go linter and
-  pinned node through it. It uses the `yarn` on `PATH` only when it is exactly
+  no Docker.
-  the pinned version. Otherwise it installs that version through corepack, or
+- `script/setup`: `script/bootstrap`, then the git pre-commit hook.
-  through npm where there is no corepack. Then it runs
+- `script/dev`: run the Vite dev server.
-  `yarn install --frozen-lockfile`. It uses the `go` on `PATH` only when it is
-  exactly the pinned version. Otherwise it installs that release from a
-  hash-verified archive. Then it runs `go mod download`. What it installs itself
-  is linked into `~/.local/bin`, which has to be on `PATH`. It installs no Go
-  linter and no Docker; `make test` and `make lint` run in Docker.
-- `script/setup`: make a fresh clone ready for development: `script/bootstrap`,
-  then the git pre-commit hook.
-- `script/dev`: run the Vite dev server, which passes `/api` to a
-  `netwatch-server` running locally.
 - `script/build`: build the page into `dist/`, then the static `netwatch-server`
-  binary into the repo root. The binary's version is `VERSION` from the
+  binary into the repo root. Its version is `VERSION` from the environment, else
-  environment. When that is unset or empty, it is
+  `git describe --tags --always --dirty`, else `dev`.
-  `git describe --tags --always --dirty`, as in `script/docker`, or `dev`
-  outside a git checkout.
 - `script/run`: `script/build`, then run `netwatch-server` with its defaults.
 - `script/clean`: remove what `script/build` writes.
-- `script/projectname`: print the project name, `netwatch`, which
+- `script/projectname`: print `netwatch`, the image tag `script/docker` uses.
-  `script/docker` uses as the image tag.
+- `script/yarn`: run yarn under the node `script/bootstrap` would use.
-- `script/yarn`: run yarn with the given arguments under the node
+- `script/test`: build the `test` phase of `Dockerfile`, writing no image: the
-  `script/bootstrap` would use.
+  Go tests with the race detector and coverage, and the page's unit tests.
-- `script/test`: build the `test` phase of `Dockerfile`, writing no image. The
+- `script/lint`: build the `lint` phase of `Dockerfile`, writing no image:
-  phase runs the backend's Go tests with the race detector and coverage, and the
+  golangci-lint over the Go packages and eslint over the JavaScript.
-  page's unit tests in its `frontend-test` stage.
+- `script/fmt`: run the formatters: prettier over the JavaScript, CSS, HTML and
-- `script/lint`: build the `lint` phase of `Dockerfile`, writing no image. The
+  Markdown, then gofmt over `cmd/` and `internal/`. They write the files in
-  phase runs golangci-lint over the Go packages, and eslint in its
+  place.
-  `frontend-lint` stage.
-- `script/fmt`: run the formatters, which write: prettier over the JavaScript,
-  CSS, HTML and Markdown, then gofmt over `cmd/` and `internal/`. It runs on the
-  host, with `~/.local/bin` put on `PATH`.
 - `script/fmt-check`: check the formatting (read-only), with the same scope as
   `script/fmt`.
 - `script/check`: `script/test`, `script/lint` and `script/fmt-check`.
 - `script/add-dependency`: add a page dependency, or move one to another
-  version. `make add-dependency PACKAGE=<name>@<version>` runs `yarn add --dev`,
+  version: `make add-dependency PACKAGE=<name>@<version>`.
-  which changes `package.json` and `yarn.lock` together, then
+- `script/tidy`: run `go mod tidy`.
-  `yarn install --frozen-lockfile`.
-- `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, then the production build. If a test fails, the
+  Node's built-in test runner, then the production build.
-  tests run again listing every test, and the script fails. Each test run has a
-  90-second timeout.
 - `script/frontend-fmt` and `script/frontend-fmt-check`: the prettier half of
   `script/fmt` and `script/fmt-check`.
 - `script/frontend-viewport-test`: check the built page's layout in a
-  containerised headless Chrome; see
+  containerised headless Chrome, not as part of `script/check`; see
-  [test/viewport/README.md](test/viewport/README.md). It is not part of
+  [test/viewport/README.md](test/viewport/README.md).
-  `script/check`, as it takes minutes.
 - `script/docker`: build the image from `Dockerfile`, tagged `netwatch`.
-- `script/cibuild`: the CI entrypoint. It runs `script/bootstrap` and
+- `script/cibuild`: `script/bootstrap`, `script/check`, then the image build.
-  `script/check`, then builds the image as `script/docker` does. The Gitea
+  The Gitea workflow `.gitea/workflows/check.yml` runs it on every push.
-  workflow `.gitea/workflows/check.yml` runs it on every push.
 - `script/precommit`: run by the git pre-commit hook; it runs `script/check`.
 - `script/install-precommit`: install the git pre-commit hook. `make hooks`
   calls it.
 
-### Build caching
-
-`script/test`, `script/lint`, `script/docker` and `script/cibuild` each pass a
-new `CACHEBUST` build argument. In `Dockerfile`, every step that lints, tests or
-compiles comes after `ARG CACHEBUST`, so it runs again on every build, even when
-nothing has changed. Docker keeps the layers above that line, the system
-packages and the Go modules, until the base image, their own lines, or `go.mod`
-and `go.sum` change. Go's build cache and golangci-lint's cache are kept between
-builds too; 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.
-
 ### Tests
 
-`make test` runs the backend's Go tests and the page's unit tests in
+`make test` runs the backend's Go tests and the page's unit tests in Docker. The
-`test/unit/`, in Docker. The unit tests import `web/src/main.js` in Node and
+unit tests import `web/src/main.js` in Node and call the functions it exports;
-call the functions it exports; no browser is involved.
+no browser is involved. `make frontend-viewport-test` checks the built page's
-
+layout in a headless Chrome; [test/viewport/README.md](test/viewport/README.md)
-`make frontend-viewport-test` builds the page and checks its layout at several
+says what it checks and what it cannot.
-window widths in a headless Chrome. The page is served with the nginx image and
-the `configs/nginx.conf` that the Docker image ships. It tests each breakpoint
-declared in `web/src/styles.css`, today the one at `max-width: 768px`, and the
-widths one pixel either side of it. It also tests four fixed widths: 320px,
-1280px and two phone landscape sizes.
-[test/viewport/README.md](test/viewport/README.md) says what it checks and what
-it cannot.
 
 ## TODO