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

Bring repo up to REPO_POLICIES.md standards

Browse Source 
- Add prettier (4-space indents) and reformat all files
- Add Makefile with test/lint/fmt/fmt-check/check/docker targets
- Add MIT LICENSE file
- Add REPO_POLICIES.md
- Fix Dockerfile: listen on 8080 with PORT env var via envsubst
- Restructure README.md with all required sections
- Set up pre-commit hook (make check)
- Update .prettierignore, .gitignore, .dockerignore
This commit is contained in:
Jeffrey Paul
2026-02-22 15:59:10 +01:00
parent ca403e68d1
commit 818accc454
14 changed files with 671 additions and 420 deletions
Download Patch File Download Diff File Expand all files Collapse all files

132
README.md
View File

@@ -1,39 +1,6 @@
# NetWatch
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.
Real-time network latency monitor SPA designed to be served from a static bucket or Docker container.
## Features
- **Real-time monitoring**: Updates every 2s with 300s history sparklines
- **9 WAN hosts**: Google Cloud, AWS, GitHub, Cloudflare, Azure, DigitalOcean, Fastly, Akamai, datavi.be
- **Local network group**: Local gateway (192.168.100.1) tracked separately
- **Health indicator**: Overall status box — green (HEALTHY) or red (DEGRADED) based on WAN reachability
- **Summary stats**: Reachable count, min/max/avg latency across WAN hosts only
- **Visual latency display**: Large color-coded figures with canvas sparkline graphs
- **Color coding**:
- Green: <50ms (excellent)
- Lime: <100ms (good)
- Yellow: <200ms (moderate)
- Orange: <500ms (poor)
- Red: >500ms (bad)
- Gray: offline/unreachable
- **Fixed chart axes**: Y-axis 0–1000ms, X-axis 0–300s
- **Play/pause**: Pause stops probes but history keeps scrolling (blank gaps, no false outage)
- **Clickable URLs**: Service URLs open in new tabs
- **>1000ms clamped**: Anything over 1s is treated as unreachable
- **Zero runtime dependencies**: All resources bundled into build artifacts
- **IPv4 only**: Designed for IPv4 connectivity testing
## Technical Details
- Latency measured via HEAD requests with cache-busting
- Uses `mode: 'no-cors'` to allow cross-origin requests where CORS headers aren't present
- 1-second timeout for unresponsive hosts (>1000ms clamped to unreachable)
- Canvas-based sparkline rendering with fixed axes
- Tailwind CSS v4 for styling
- Local gateway excluded from WAN summary statistics
## Build
## Getting Started
```bash
# Install dependencies
@@ -47,34 +14,48 @@ yarn build
# Preview production build
yarn preview
```
## Docker
```bash
# Docker
docker build -t netwatch .
docker run -p 8080:80 netwatch
docker run -p 8080:8080 netwatch
```
The nginx config:
- Trusts `X-Forwarded-For` from RFC1918 reverse proxies (10/8, 172.16/12, 192.168/16)
- Access log goes to stdout
- Static assets cached with immutable headers
## Rationale
## Deployment
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.
After running `yarn build`, deploy the contents of the `dist/` directory to any static file host:
## Design
- AWS S3
- Google Cloud Storage
- Cloudflare Pages
- Vercel
- Netlify
- GitHub Pages
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:
Or use the Docker image behind a reverse proxy.
- **`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)
## Output Structure
### Monitoring targets
- **9 WAN hosts**: Google Cloud Console, AWS Console, GitHub, Cloudflare, Azure, DigitalOcean, Fastly, Akamai, datavi.be
- **1 Local host**: Local Gateway (192.168.100.1), 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/
@@ -84,15 +65,32 @@ dist/
└── index-*.js
```
All assets are bundled and minified. No external dependencies at runtime.
## 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 modern browser with:
- ES modules support
- Fetch API
- Canvas API
- CSS custom properties
Requires a modern browser with ES modules, Fetch API, Canvas API, and CSS custom properties.
## Limitations
@@ -100,6 +98,18 @@ Requires modern browser with:
- **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
MIT. See [LICENSE](LICENSE).
## Author
[@sneak](https://sneak.berlin)