sneak/netwatch
1
0
Fork 0
Code Issues 2 Pull Requests Actions 8 Packages Projects Releases Wiki Activity

Deploy main 5e572ce to prod (#198)
check / check (push) Waiting to run
Details

Browse Source 
main's tree, with next merged on 26 October, as one commit onto prod, on sneak's order.

Model: opus-5-5
Co-authored-by: clawbot <clawbot@noreply.example.org>
This commit was merged in pull request #198.
This commit is contained in:
clawbot
2026-10-26 13:10:55 +01:00
committed by clawbot
parent 0c36d79131
commit 863a1d549d
104 changed files with 9647 additions and 2949 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+400 -209
View File
@@ -1,261 +1,452 @@
NetWatch is an MIT-licensed JavaScript single-page application by
[@sneak](https://sneak.berlin) that provides real-time network latency
monitoring to common internet hosts, displayed with color-coded figures and
sparkline graphs, served from a static bucket or Docker container.
NetWatch is an MIT-licensed single-page web application by
[@sneak](https://sneak.berlin) that shows the latency from your browser to 26
well-known internet hosts. The page is JavaScript and does all its measuring in
the browser. A small Go backend, `netwatch-server`, stores the measurements the
page reports. The page and the backend ship together in one Docker image.
## Rationale
When a network misbehaves, it helps to see at a glance which hosts answer and
how fast. NetWatch is one page with a latency figure and a small graph for each
host, refreshed every few seconds. The page measures from the browser, so it
shows the path your own traffic takes. It can be served from any static file
host. The backend only stores what the page reports. Without it, the page works
the same and nothing is stored.
## Getting Started
```bash
# Install dependencies
yarn install
# Install the dependencies and the git pre-commit hook
make setup
# Development server
yarn dev
# Serve the page from the Vite dev server
make dev
# Production build
yarn build
# Build the page and netwatch-server, then run the server on port 8080
make run
# Preview production build
yarn preview
# Run the tests, both linters and the format check
make check
# Docker
docker build -t netwatch .
# Build the page into dist/ and netwatch-server into the repo root
make build
# Build the Docker image and run it
make docker
docker run -p 8080:8080 netwatch
```
`yarn dev` proxies `/api` to `http://127.0.0.1:8080`, so a locally running
`netwatch-server` (see `backend/`) receives the reports the page posts.
`make check` and `make docker` need Docker. `make run` starts `netwatch-server`
on port 8080 with its defaults, so the page's reports are stored in
`data/reports`. `make dev` passes the page's `/api` requests there.
## Entrypoints
## The page
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 page shows one row per host: the host's name, its URL, its latest latency in
milliseconds and a graph of its last 100 checks. Below the figure are the
minimum, median, average and maximum of the host's answers in that history, or
`timeout` or `unreachable` after a failed check. A round of checks runs every 3
seconds by default. The header shows the interval, the history's span, and
whether the page is running or paused.
- `script/bootstrap` — install all dependencies (the pinned node via nvm unless
one new enough for the frontend's dependencies is installed, yarn via
corepack, `yarn install --frozen-lockfile`, the pinned Go unless one at least
as new as `backend/go.mod` asks for is installed, and the Go modules), linking
what it installs itself into `~/.local/bin`, which has to be on `PATH`. It
installs no Go linter and not Docker: `make lint` runs the linter in Docker
- `script/setup` — make a fresh clone ready for development: bootstrap plus the
git pre-commit hook
- `script/projectname` — print the project name (used for the Docker image tag)
- `script/test` — run `script/frontend-test`, then the backend's Go tests, both
within one 30-second timeout
- `script/lint` — run `script/frontend-lint`, then golangci-lint in Docker, by
building the lint stage of `Dockerfile` without the cache
- `script/fmt` — format all files (writes): prettier, then gofmt over `backend/`
- `script/fmt-check` — check formatting (read-only): prettier, then gofmt
- `script/check` — run test, lint, and fmt-check
- `script/frontend-test` — run the production build as the frontend's test (no
unit tests yet)
- `script/frontend-lint` — run prettier in check mode
- `script/frontend-fmt` — format everything prettier understands (writes)
- `script/frontend-fmt-check` — check prettier formatting (read-only)
- `script/frontend-check` — the frontend half of `script/check`, for
`Dockerfile`, whose node build stage has neither Go nor Docker
- `script/frontend-viewport-test` — responsive-layout verification of the built
frontend in a containerised headless Chrome (see
[test/viewport/README.md](test/viewport/README.md)). Not part of
`script/check`: it needs Docker and takes minutes.
- `script/docker` — build the image from `Dockerfile` without the build cache,
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
- `script/precommit` — run by the git pre-commit hook; runs `script/check`
- `script/install-precommit` — install the git pre-commit hook
### Targets
## Responsive layout
The page checks 26 hosts on the internet, the WAN hosts:
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 — one pixel either
side of every breakpoint it declares, 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.
- `datavi.be`, pinned to the top at start
- the Anthropic API and the OpenAI API
- the AWS Console, the Google Cloud Console and Microsoft Azure
- Cloudflare, Fastly, Akamai, Google, GitHub and Backblaze B2
- 8 S3 regional endpoints: Cape Town, London, Bahrain, Tokyo, Singapore, Sydney,
Oregon and São Paulo
- 6 Hetzner speed-test servers: Nuremberg, Falkenstein, Helsinki, Ashburn,
Hillsboro and Singapore
## Rationale
Two local targets follow under the heading "Local Network", left out of the
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.
When debugging network issues, it's useful to have a persistent at-a-glance view
of latency and reachability to multiple well-known internet endpoints. NetWatch
provides this as a zero-dependency SPA that can be deployed anywhere static
files are served, with no backend required.
The host list is written in `web/src/main.js`; there is no setting for it.
## Design
### What a figure measures
The application is a single-page app built with Vite and Tailwind CSS v4. All
code lives in `src/main.js` with a class-based architecture:
A check is a request to the target's URL: `GET`, or `HEAD` for the S3 regions.
The figure is the time from sending the request until the response headers
arrive, in milliseconds. Unlike ping, it includes the time the server takes to
answer. On a new connection it also includes the DNS lookup, the connection
setup and the TLS handshake. Any answer counts as reachable, an error page
included. The browser follows redirects, so a target whose home page redirects
is checked at `/robots.txt` on the same host.
- **`CONFIG`**: Frozen configuration object (update interval, timeouts, axis
ticks, etc.)
- **`HostState`**: Per-host state management — history buffer, latency tracking,
status transitions
- **`AppState`**: Top-level state container — WAN hosts, local hosts, pause
state, aggregate stats
- **`SparklineRenderer`**: Canvas 2D sparkline drawing with fixed axes,
color-coded line segments, error regions, and DPR-aware scaling
- **UI functions**: `buildUI()` constructs the DOM, `updateHostRow()` /
`updateSummary()` / `updateHealthBox()` handle incremental updates
- **`tick()`**: Main loop — measures all hosts in parallel via `Promise.all`,
pushes samples, redraws UI. When paused, pushes blank markers (no probes, no
false outage)
- **`Reporter`**: Posts collected samples to the backend
A check times out after 80% of the interval: 2.4 seconds at the default. A check
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
is discarded, as its figures include the connection setup. So is the first round
after an interval change.
### Reporting
### Health and summary
Every `reportInterval` (default 60s) the page POSTs a JSON report to the
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.
Above the rows, a health box sums up the WAN hosts' latest results. A host
counts as failed when its last check timed out or found it unreachable.
### Monitoring targets
- `OFFLINE` (red): more than 10 hosts failed and at most 4 answered
- `DEGRADED` (orange): otherwise, more than 4 hosts failed
- `SLOW` (yellow): otherwise, more than 3 hosts took over 1000 ms
- `HEALTHY` (green): otherwise
- **22 WAN hosts**: datavi.be, Anthropic API, OpenAI API, AWS Console, GCP
Console, Azure, Cloudflare, Fastly, Akamai, GitHub, B2, 7 S3 regional
endpoints (Cape Town, London, Bahrain, Tokyo, Sydney, Oregon, São Paulo), 4
GCS locational endpoints (Iowa, Belgium, Singapore, Sydney)
- **Local CPE**: Cable modem at 192.168.100.1 (always monitored)
- **Local Gateway**: Auto-detected on startup by probing common default gateway
addresses (192.168.1.1, 192.168.0.1, 192.168.8.1, 10.0.0.1); first responder
wins. Note: modern browsers enforce Private Network Access restrictions that
block public-origin pages from reaching RFC1918 addresses, so local targets
only work when NetWatch is served from localhost or a private address.
Below it, a summary line covers the WAN hosts only:
Local hosts are tracked separately from WAN stats.
- `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`: the minimum and maximum over the whole
history
- `Checks`: the rounds run since the page loaded or the interval changed
### Latency measurement
When no WAN host answers, the page checks 4 of them, picked at random, every
half second. As soon as one answers, a new round starts.
HEAD requests with `mode: 'no-cors'` and `cache: 'no-store'`, timed with
`performance.now()`. 1-second timeout; anything over 1000ms is clamped to
unreachable. IPv4 only.
### Rows, colors and controls
### Color coding
A figure and its line in the graph take the color of the legend in the footer,
from green under 50 ms to red from 500 ms up; gray is no answer. The graph's
axis ends at 1000 ms; a higher latency is drawn at the top, and the figure still
shows its real value.
| Latency | Color |
| ----------- | ------ |
| < 50ms | Green |
| < 100ms | Lime |
| < 200ms | Yellow |
| < 500ms | Orange |
| >= 500ms | Red |
| Unreachable | Gray |
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.
### Output structure
`Pause` stops the checks: the graphs keep scrolling with a gap for each paused
round, and the figures turn gray. The `Interval` menu sets the time between
rounds: 1, 2, 3, 5, 10, 15, 30 or 60 seconds. Changing it clears the history and
starts a new round at once. The `Debug log` checkbox in the footer opens a panel
with the page's last 1000 log lines.
```
dist/
├── index.html
└── assets/
├── index-*.css
└── index-*.js
```
## Reporting
## Features
Every 60 seconds the page posts its undelivered samples as a report to
`/api/v1/reports` on the origin it was served from. The report is JSON with four
fields:
- Real-time monitoring with 2s update interval and 300s history sparklines
- Health indicator: green (HEALTHY) or red (DEGRADED) based on WAN reachability
- Summary stats: reachable count, min/max/avg latency across WAN hosts only
- Fixed chart axes: Y-axis 0–1000ms, X-axis 0–300s
- Color-coded latency figures and sparkline line segments
- Play/pause: pause stops probes but history keeps scrolling (blank gaps, no
false outage)
- Clickable service URLs
- Canvas-based sparkline rendering with devicePixelRatio scaling
- Zero runtime dependencies: all resources bundled into build artifacts
- `clientId`: a random id, made once per browser and kept in `localStorage`, or
once per session when the browser has no usable storage
- `geo`: always `null`
- `hosts`: one entry per host with new samples: its `name`, `url` and `status`,
and `history`, its samples. A sample has the check's time `t` in Unix
milliseconds, its `latency` (`null` for a failed check) and its `error`
(`"timeout"`, `"unreachable"` or `null`).
- `timestamp`: the time of the report
Each report carries only the samples no earlier report has delivered. A sample
waits as long as the history holds it: the last 100 rounds of each host. An
interval change clears the history. The cleared samples are kept, the last 100
of each host, until a report delivers them. Nothing is sent while the page is
paused. A report with no answer after 30 seconds is abandoned, and its samples
go in the next one. So a server that stored them but answered late gets them
twice.
A failed delivery is quiet, as on a static file host with no backend: one debug
log line when deliveries start failing, one when they recover. The checks go on.
## Deployment
After running `yarn build`, deploy the contents of the `dist/` directory to any
static file host (S3, GCS, Cloudflare Pages, Vercel, Netlify, GitHub Pages) or
use the Docker image behind a reverse proxy.
`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.
The Docker image, built from `Dockerfile`, is the whole service in one
container: nginx serves the built frontend and passes `/api/` and
`/.well-known/healthcheck` to the Go backend, `netwatch-server`, which listens
only inside the container, on `127.0.0.1:8081`. The image:
Before the backend starts, `bin/entrypoint.sh` runs two subcommands of
`netwatch-server`. `check-cidr` checks each `TRUSTED_PROXIES` entry (see
[Running under upaas](#running-under-upaas)). `prepare-data-dir` creates the
report directory and gives `/data`, with the directories, regular files and
symbolic links in it, to user `netwatch`. It changes nothing outside `/data`.
- 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
- Sends access logs to stdout
- Caches static assets with immutable headers
- Sends the security headers `REPO_POLICIES.md` requires on every response, as
`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
- 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
The image also:
## Running under upaas
- takes the client address from `X-Forwarded-For` only on a request from a proxy
named in `TRUSTED_PROXIES`, 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 and the backend's JSON log to stdout
- refuses a request body over 1 MiB with nginx's own 413 error page
- requests `/.well-known/healthcheck` through nginx every 30 seconds, as its
`HEALTHCHECK`. The check fails unless both nginx and the backend answer, and
while report files cannot be written.
- on `docker stop`, writes the waiting reports to disk and exits 0, or non-zero
if that write fails. If nginx or the backend exits on its own, the other is
stopped and the container exits non-zero.
What the [upaas](https://git.eeqj.de/sneak/upaas) app for netwatch needs:
### Running under upaas
- **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.
- `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
minute
- `DATA_DIR_MAX_BYTES`, default `1073741824` (1 GiB): the most room the
report files may take
- `CORS_ALLOWED_ORIGINS`, default empty: other origins whose pages may call
the API
- `DEBUG`, default `false`: debug logging
- `DATA_DIR`, default `/data/reports`: leave unset; reports kept outside
`/data` do not survive a redeploy
- `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`.
- **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.
The [upaas](https://git.eeqj.de/sneak/upaas) app for netwatch needs:
## Browser Compatibility
- Port: container port `8080`.
- 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
the container.
- `PORT` is nginx's public port, from 1 to 65535 and not `8081`, where the
backend listens inside the container.
- `DATA_DIR` must be `/data` or a path below it, written in full, with no
`.` 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`.
`bin/entrypoint.sh` gives a lone address a `/32` or `/128` and checks each
entry with `netwatch-server check-cidr`, which refuses what the backend
would refuse. Set and empty, nginx trusts no proxy, and every client
behind a proxy then shares the proxy's one allowance of
`REPORTS_PER_MINUTE`. A client that connects from a trusted address can
write its own `X-Forwarded-For`. A port Docker publishes can bring
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.
Requires a modern browser with ES modules, Fetch API, Canvas API, and CSS custom
properties.
The container stops at start when a variable holds a value it cannot use. The
reason is in its log.
## Limitations
## Settings
- **CORS**: Some hosts may block cross-origin HEAD requests. The app uses
`no-cors` mode which allows the request but provides opaque responses. Latency
is still measurable based on request timing.
- **Local gateway**: The 192.168.100.1 endpoint requires the host to be
accessible from your network.
- **Network conditions**: Measurements reflect browser-to-endpoint latency,
which includes your local network, ISP, and internet routing.
`netwatch-server` reads its settings from environment variables. It also reads a
`.env` file in the directory it starts in, and a YAML file named
`netwatch-server.yaml` in `/etc/netwatch-server/` or
`~/.config/netwatch-server/`, when one exists. A variable in the environment
wins over a file.
The server does not start when a variable holds a value it cannot use. Its error
names the variable. An empty variable counts as unset, except `TRUSTED_PROXIES`.
- `BIND_ADDRESS`, default empty: the IP address to listen on. Empty listens on
every interface. The image sets it to `127.0.0.1`.
- `PORT`, default `8080`: the port to listen on, from 1 to 65535. In the image
this is nginx's port; the backend listens on `8081`.
- `DATA_DIR`, default `./data/reports` (`/data/reports` in the image): the
directory for the report files. The server creates it if it is missing, and
stops at start if it cannot create a file in it.
- `DATA_DIR_MAX_BYTES`, default `1073741824` (1 GiB): the most bytes of report
files kept in `DATA_DIR`, oldest deleted first. A positive whole number. See
[Report limits](#report-limits).
- `REPORTS_PER_MINUTE`, default `60`: how many reports each client address may
send a minute. A positive whole number. See [Report limits](#report-limits).
- `TRUSTED_PROXIES`, default `10.0.0.0/8,172.16.0.0/12,192.168.0.0/16`: the
reverse proxies whose `X-Forwarded-For` and `X-Real-IP` headers are trusted,
as CIDRs separated by commas. See [Trusted proxies](#trusted-proxies).
- `CORS_ALLOWED_ORIGINS`, default empty: other origins whose pages may call the
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. Each request whose
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
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
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.
The peer's address is used when every entry is in the set, or when the search
from the right meets an entry that is not an address, such as `unknown`.
`X-Real-IP` is read only when `X-Forwarded-For` is missing or empty.
### Routes
- `POST /api/v1/reports` takes a report from the page. It needs no credentials;
[Report limits](#report-limits) bound it instead.
- `GET /.well-known/healthcheck` answers 200 with a JSON object: `appname`,
`version`, `now`, `uptime_seconds`, `uptime_human` and `status`, which is
`"ok"`. While report files cannot be written, it answers 503 with the same
fields and `"status":"error"`.
- `GET /metrics` serves Prometheus metrics, only when `METRICS_USERNAME` and
`METRICS_PASSWORD` are set. See [Metrics](#metrics).
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 a new file every minute,
whenever 10 MiB of reports are waiting, and when it stops. With none waiting, it
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 reports of a failed write, as on a full disk, stay in memory for the next
write to try again. Until a write succeeds, `POST /api/v1/reports` refuses every
report with 500 and the health check answers 503.
### Report limits
`POST /api/v1/reports` takes reports from anyone who can reach it, so it is
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`; any
other content type is refused with 415, and malformed JSON with 400.
- Body limit. A report body may be at most 1 MiB. A request that declares a
longer body, or a report that runs past that, is refused with 413.
- Rate limit. Each client address may send `REPORTS_PER_MINUTE` reports a
minute; past that it gets 429 with `Retry-After: 60`. 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.
- Size cap. The report files in `DATA_DIR` may total at most
`DATA_DIR_MAX_BYTES`, counting the files already there at start and the
reports waiting in memory. When a report would take the total past the cap,
the oldest files are deleted to make room. A report is refused with 507 when
deleting the oldest files cannot make room.
At the defaults, one address can fill the 1 GiB cap with its own reports in
about 17 minutes, and every report stored before them is deleted to make room.
### CORS
The page needs no entry here: it calls the API from the origin it is served
from. By default the server sends no CORS headers, and browsers let no other
origin's pages call it. `CORS_ALLOWED_ORIGINS` lists other origins, such as
`https://netwatch.example.com`, whose pages may then call the API with `GET` and
`POST`. Each entry must be a plain origin as browsers send it: `scheme://host`,
with an optional `:port`, no path, no trailing `/` and no `*`.
### 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, `/metrics`
answers 404. The metrics record each request that reaches the health check or
`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
minute. Past that it gets 429 with `Retry-After: 60`, and its credentials are
not checked.
### Logging
The backend logs JSON to stdout, or plain text when stdout is a terminal. Each
request is logged with its method, URL, status, client address and duration.
Every value taken from a request is cut to 128 bytes before it is logged.
## Design
The repository holds the page, the backend and the image:
- `web/`: the page's source. `index.html` loads `src/main.js` and
`src/styles.css`.
- `cmd/netwatch-server/` and `internal/`: the Go backend. `cmd/` holds only
`main`, which calls into `internal/cli`.
- `configs/`: nginx's configuration for the image, `nginx.conf` and
`security-headers.conf`.
- `bin/entrypoint.sh`: the image's entrypoint.
- `Dockerfile`: the lint and test phases, the two build stages and the image.
- `script/`: the development commands; `Makefile` targets call them.
- `test/unit/`: the page's unit tests. `test/viewport/`: the layout test.
### The page
The page is built with Vite and Tailwind CSS v4. All its code is in
`web/src/main.js`:
- `CONFIG`: the timing and display constants. The interval menu sets its
`updateInterval`; the check timeout and the history span follow from it.
- `WAN_HOSTS`: the WAN targets, each with its URL and, for the S3 entries, the
method `HEAD`.
- `HostState` and `AppState`: one host's history and status, and the whole
page's state.
- `measureLatency`: one check. `tick`: one round, which checks every host in
parallel and draws each row as soon as its check ends.
- `SparklineRenderer`: the graphs. `buildUI`, `updateHostRow`, `updateSummary`
and `updateHealthBox`: the page and its parts.
- `Reporter`: builds and posts the reports. `buildReport` is a pure function of
the hosts' state.
### The backend
`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`: the command line: the server when given no arguments, or the
`check-cidr` and `prepare-data-dir` subcommands that `bin/entrypoint.sh` runs.
- `config`: reads the settings and refuses values the server cannot use.
- `server`: the router, the routes and the HTTP server.
- `middleware`: the request log, the security headers, CORS, the body limit, the
rate limit, the client address resolution and the metrics.
- `handlers`: the health check and the report route.
- `reportbuf`: the in-memory buffer of reports and the files it writes them to.
It also holds `PrepareDataDir`, which `prepare-data-dir` runs.
- `healthcheck`, `logger` and `globals`: the health status, the logger, and the
name and version the build stamps in.
## Development
### Entrypoints
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.
- `script/bootstrap`: install the dependencies. It installs the pinned node,
yarn and Go when the ones on `PATH` do not pass its checks, and links them
into `~/.local/bin`, which has to be on `PATH`. It installs no Go linter and
no Docker.
- `script/setup`: `script/bootstrap`, then the git pre-commit hook.
- `script/dev`: run the Vite dev server.
- `script/build`: build the page into `dist/`, then the static `netwatch-server`
binary into the repo root. Its version is `VERSION` from the environment, else
`git describe --tags --always --dirty`, else `dev`.
- `script/run`: `script/build`, then run `netwatch-server` with its defaults.
- `script/clean`: remove what `script/build` writes.
- `script/projectname`: print `netwatch`, the image tag `script/docker` uses.
- `script/yarn`: run yarn under the node `script/bootstrap` would use.
- `script/test`: build the `test` phase of `Dockerfile`, writing no image: the
Go tests with the race detector and coverage, and the page's unit tests.
- `script/lint`: build the `lint` phase of `Dockerfile`, writing no image:
golangci-lint over the Go packages and eslint over the JavaScript.
- `script/fmt`: run the formatters: prettier over the JavaScript, CSS, HTML and
Markdown, then gofmt over `cmd/` and `internal/`. They write the files in
place.
- `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>`.
- `script/tidy`: run `go mod 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.
- `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, not as part of `script/check`; see
[test/viewport/README.md](test/viewport/README.md).
- `script/docker`: build the image from `Dockerfile`, tagged `netwatch`.
- `script/cibuild`: `script/bootstrap`, `script/check`, then the image build.
The Gitea 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.
### Tests
`make test` runs the backend's Go tests and the page's unit tests in Docker. The
unit tests import `web/src/main.js` in Node and call the functions it exports;
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)
says what it checks and what it cannot.
## TODO
- Add unit tests
- Add eslint for JS linting (currently lint target runs prettier only)
- Add configurable host list (environment variable or config file)
- Add latency history export (CSV/JSON)
- Add notification/alert when status changes to DEGRADED
The to-do list is [TODO.md](TODO.md): where the work stands, the next step, the
open work, and what has been done.
## License