1c16d50d67
All checks were successful
check / check (push) Successful in 32s
Root `make check` only ever ran the frontend, so the "main is always green" policy was satisfied vacuously: the Go backend could be entirely broken and the root gate stayed green. - The backend moves onto scripts-to-rule-them-all. Its test, lint, fmt, fmt-check, build, run and clean implementations now live in `backend/script/`, and `backend/Makefile` is thin shims. The backend is its own project (own module, README, LICENSE, linter config, Dockerfile stage), and `Dockerfile.backend` only copies `backend/` into its builder, so its scripts have to live under `backend/`. - The root `script/test`, `script/lint`, `script/fmt` and `script/fmt-check` now run the frontend step and then the matching `backend/script/*` step, so `script/check` — and therefore the pre-commit hook — gates both halves. The frontend-only steps moved into `script/frontend-*` so nothing is duplicated. - `script/bootstrap` now provisions the backend's toolchain as well, because widening the gate without widening bootstrap left the documented fresh-clone path (`make setup`) installing a pre-commit hook that rejected every commit with `golangci-lint: not found`. golangci-lint is installed at exactly `2.7.2`, the version `Dockerfile.backend` pins, so local findings match CI. Go is reused only when the installed version falls inside a window — at least `backend/go.mod`'s floor, and no newer in major.minor than the Go the pinned linter was built with — otherwise `go1.25.7` is installed. The upper bound is load-bearing: golangci-lint links `go/types` from its own build toolchain, so the pinned `2.7.2` (built with `go1.25.4`) panics with "file requires newer Go version go1.26" against a host Go 1.26, which would leave `make setup` exiting 0 and every commit rejected. Both tools come from a specific release archive whose sha256 is hardcoded here and verified before anything is unpacked — never an install script piped to a shell — and both are symlinked onto `PATH`, since nvm-style activation does not reach `make` or the git hook. - `script/bootstrap` links only into `~/.local/bin` and never into a system-wide prefix. `/usr/local/bin` is shared with other users and with a package manager — on an Intel Mac it is the Homebrew prefix — and pointing an entry there at one user's `$HOME` breaks it for everyone else. It also refuses, non-zero, to replace anything it did not create: only a symlink already pointing into its own toolchain directory is overwritten, so a pre-existing binary is reported rather than deleted. `corepack enable` is given `--install-directory` so its four shims (`yarn`, `yarnpkg`, `pnpm`, `pnpx`) land inside that same toolchain directory instead of beside the corepack binary, and only `yarn` is linked onto `PATH`. - `script/bootstrap` exits non-zero when it cannot guarantee the pinned toolchain is the one the gate will run. Reporting success while knowing a different linter or a newer Go precedes `~/.local/bin` is the same defect this commit exists to remove, so the final step re-resolves `go`, `gofmt`, `golangci-lint`, `node` and `yarn` against the caller's own `PATH` and fails with what it found and how to fix it. The three tools that carry a version constraint are re-checked with the same predicates their installs use, not for bare presence: `gofmt` is a gate tool — `backend/script/fmt-check` runs it — and its output is not guaranteed identical across Go releases, so a `gofmt` built by a different Go than the one that compiles the code counts as missing. `go` and `gofmt` are relinked on every run in which the pinned toolchain is the one in use, rather than only on the run that unpacked the archive, so a deleted link is repaired instead of falling through to whatever `gofmt` the host happens to have. The failure text separates a tool that resolves to the wrong build (something shadows `~/.local/bin`) from one that does not resolve at all (nothing is shadowing it, it was never installed), and always names a real directory rather than interpolating an unset one. - `script/frontend-check` is the frontend half of the gate, exposed as the `frontend-check` target, for the frontend Dockerfile: its build stage is a node image with no Go toolchain. The backend half is gated by `Dockerfile.backend`, and `script/cibuild` builds both images, so the two Dockerfiles together still gate the whole repo. The `backend-check` target is the mirror of it. Both targets are named after the script they shim, like every other target. - `script/cibuild` builds both images through one `build_image` helper, and the Gitea workflow's only build step is `script/cibuild`; the raw `docker build -f Dockerfile.backend .` is gone from the workflow. `script/docker` likewise builds and tags both images. - `backend/Makefile`'s `hooks` target is removed. It wrote the same `.git/hooks/pre-commit` as `script/install-precommit`, so the two clobbered each other and the developer silently ended up gating on only one half of the repo. `script/install-precommit` is now the only installer, and the hook it writes runs the repo-wide `script/check`. - `backend/Makefile`'s `docker` target is removed too: the backend image builds from the repo root with a root-level Dockerfile, so it belongs to the root `script/docker` and `script/cibuild` rather than to a backend script that would have to reach outside `backend/`. - `backend/script/lint` verifies that `.golangci.yml` still matches its pinned sha256 before running the linter. Offline hash comparison, no network. The pin is marked provisional in the file: it is the config currently on `main`, and the comment names PR #31 and the canonical hash that must replace it when #31 lands. - Every script locates the repo root with the mandated `$(cd "$(dirname "$0")/.." && pwd -P)` idiom, `cd`s there, and calls siblings as `"$ROOT/script/<name>"`; the `SCRIPT_DIR` variant is gone. READMEs at the root and in `backend/` document every script, the backend's Getting Started separates commands run from `backend/` from those run at the repo root, and `TODO.md` records the change.
215 lines
8.4 KiB
Markdown
215 lines
8.4 KiB
Markdown
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.
|
||
|
||
## Getting Started
|
||
|
||
```bash
|
||
# Install dependencies
|
||
yarn install
|
||
|
||
# Development server
|
||
yarn dev
|
||
|
||
# Production build
|
||
yarn build
|
||
|
||
# Preview production build
|
||
yarn preview
|
||
|
||
# Docker
|
||
docker build -t netwatch .
|
||
docker run -p 8080:8080 netwatch
|
||
```
|
||
|
||
## Entrypoints
|
||
|
||
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 repo holds two projects: the frontend at the repo root and the Go backend in
|
||
`backend/`, which has its own `script/` directory and its own shim Makefile. The
|
||
root scripts cover both, so `make check` at the root fails if either half is
|
||
broken. We provide:
|
||
|
||
- `script/bootstrap` — install all dependencies, assuming nothing is present:
|
||
pinned node via nvm if needed, yarn via corepack,
|
||
`yarn install --frozen-lockfile`, and the backend's toolchain — Go (an
|
||
already-installed Go is reused only when its version falls inside the window
|
||
the pinned golangci-lint can analyse; a newer Go is ignored, not preferred)
|
||
and golangci-lint at the version `Dockerfile.backend` pins. Everything not
|
||
installed by the system package manager comes from a hash-verified release
|
||
archive and is symlinked into `~/.local/bin`, so `make check` works in a plain
|
||
shell afterwards
|
||
- `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 tags)
|
||
- `script/test` — run the whole repo's tests: `script/frontend-test`, then
|
||
`backend/script/test`
|
||
- `script/lint` — lint the whole repo: `script/frontend-lint`, then
|
||
`backend/script/lint`
|
||
- `script/fmt` — format the whole repo (writes): `script/frontend-fmt`, then
|
||
`backend/script/fmt`
|
||
- `script/fmt-check` — check formatting across the whole repo (read-only)
|
||
- `script/check` — run test, lint, and fmt-check; this is the repo-wide gate
|
||
- `script/frontend-test` — the frontend's test: the production build (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`, shimmed by
|
||
`make frontend-check` and used by `Dockerfile`, whose build stage is a node
|
||
image with no Go toolchain. Its mirror `make backend-check` shims to
|
||
`backend/script/check`
|
||
- `script/docker` — build both images, tagged via `script/projectname`:
|
||
`netwatch` from `Dockerfile` and `netwatch-server` from `Dockerfile.backend`
|
||
- `script/cibuild` — CI entrypoint: builds both images; the only build step in
|
||
the Gitea workflow
|
||
- `script/precommit` — run by the git pre-commit hook; runs `script/check`, so a
|
||
commit is gated on both halves of the repo
|
||
- `script/install-precommit` — install the git pre-commit hook; this is the
|
||
repo's only pre-commit hook installer
|
||
|
||
The backend's scripts are shimmed by `backend/Makefile` and are also called by
|
||
the root scripts above:
|
||
|
||
- `backend/script/build` — compile `netwatch-server` with version and
|
||
architecture stamped in
|
||
- `backend/script/test` — run the Go tests under a 30-second timeout
|
||
- `backend/script/lint` — assert `.golangci.yml` still matches its pinned
|
||
sha256, then run golangci-lint
|
||
- `backend/script/fmt` — format the Go sources (writes)
|
||
- `backend/script/fmt-check` — check Go formatting (read-only)
|
||
- `backend/script/check` — run the backend's test, lint, and fmt-check
|
||
- `backend/script/run` — build and run the server locally
|
||
- `backend/script/clean` — remove build artifacts
|
||
|
||
## Rationale
|
||
|
||
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.
|
||
|
||
## Design
|
||
|
||
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:
|
||
|
||
- **`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)
|
||
|
||
### Monitoring targets
|
||
|
||
- **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.
|
||
|
||
Local hosts are tracked separately from WAN stats.
|
||
|
||
### Latency measurement
|
||
|
||
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.
|
||
|
||
### Color coding
|
||
|
||
| Latency | Color |
|
||
| ----------- | ------ |
|
||
| < 50ms | Green |
|
||
| < 100ms | Lime |
|
||
| < 200ms | Yellow |
|
||
| < 500ms | Orange |
|
||
| >= 500ms | Red |
|
||
| Unreachable | Gray |
|
||
|
||
### Output structure
|
||
|
||
```
|
||
dist/
|
||
├── index.html
|
||
└── assets/
|
||
├── index-*.css
|
||
└── index-*.js
|
||
```
|
||
|
||
## Features
|
||
|
||
- 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
|
||
|
||
## 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.
|
||
|
||
The Docker image:
|
||
|
||
- Listens on port 8080 by default (override with `PORT` env var)
|
||
- Trusts `X-Forwarded-For` from RFC1918 reverse proxies (10/8, 172.16/12,
|
||
192.168/16)
|
||
- Sends access logs to stdout
|
||
- Caches static assets with immutable headers
|
||
|
||
## Browser Compatibility
|
||
|
||
Requires a modern browser with ES modules, Fetch API, Canvas API, and CSS custom
|
||
properties.
|
||
|
||
## Limitations
|
||
|
||
- **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.
|
||
|
||
## 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
|
||
|
||
## License
|
||
|
||
MIT. See [LICENSE](LICENSE).
|
||
|
||
## Author
|
||
|
||
[@sneak](https://sneak.berlin)
|