diff --git a/.gitea/workflows/check.yml b/.gitea/workflows/check.yml new file mode 100644 index 0000000..e545bef --- /dev/null +++ b/.gitea/workflows/check.yml @@ -0,0 +1,10 @@ +name: check +on: [push] +jobs: + check: + runs-on: ubuntu-latest + steps: + # actions/checkout v4.2.2, 2026-02-22 + - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 + - run: docker build . + - run: docker build backend/ diff --git a/backend/LICENSE b/backend/LICENSE new file mode 100644 index 0000000..5b83a52 --- /dev/null +++ b/backend/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2026 @sneak (https://sneak.berlin) + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/backend/README.md b/backend/README.md new file mode 100644 index 0000000..a7de988 --- /dev/null +++ b/backend/README.md @@ -0,0 +1,70 @@ +netwatch-server is an MIT-licensed Go HTTP backend by +[@sneak](https://sneak.berlin) that receives telemetry reports from the NetWatch +SPA and persists them as zstd-compressed JSONL files on disk. + +## Getting Started + +```bash +# Build and run locally +make run + +# Run tests, lint, and format check +make check + +# Docker +docker build -t netwatch-server . +docker run -p 8080:8080 netwatch-server +``` + +## Rationale + +The NetWatch frontend collects latency measurements from the browser but has no +way to persist or aggregate them. This backend provides a minimal +`POST /api/v1/reports` endpoint that buffers incoming reports in memory and +flushes them to compressed files on disk for later analysis. + +## Design + +The server is structured as an `fx`-wired Go application under `cmd/netwatch-server/`. +Internal packages in `internal/` follow standard Go project layout: + +- **`config`**: Loads configuration from environment variables and config files + via Viper. +- **`handlers`**: HTTP request handlers for the API (health check, report + ingestion). +- **`reportbuf`**: In-memory buffer that accumulates JSONL report lines and + flushes to zstd-compressed files when the buffer reaches 10 MiB or every 60 + seconds. +- **`server`**: Chi-based HTTP server with middleware wiring and route + registration. +- **`healthcheck`**, **`middleware`**, **`logger`**, **`globals`**: Supporting + infrastructure. + +### Configuration + +| Variable | Default | Description | +| ---------- | ------------------ | --------------------------------- | +| `PORT` | `8080` | HTTP listen port | +| `DATA_DIR` | `./data/reports` | Directory for compressed reports | +| `DEBUG` | `false` | Enable debug logging | + +### Report storage + +Reports are written as `reports-.jsonl.zst` files in `DATA_DIR`. +Each file contains one JSON object per line, compressed with zstd. Files are +created with `O_EXCL` to prevent overwrites. + +## TODO + +- Add integration test that POSTs a report and verifies the compressed output +- Add report decompression/query endpoint +- Add metrics (Prometheus) for buffer size, flush count, report count +- Add retention policy to prune old report files + +## License + +MIT. See [LICENSE](LICENSE). + +## Author + +[@sneak](https://sneak.berlin)