Add CI workflow and backend repo standard files
Some checks failed
check / check (push) Failing after 26s
Some checks failed
check / check (push) Failing after 26s
Add .gitea/workflows/check.yml that builds both the root and backend Docker images on push. Add LICENSE and README.md to the backend subproject to match repo standards.
This commit is contained in:
70
backend/README.md
Normal file
70
backend/README.md
Normal file
@@ -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-<timestamp>.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)
|
||||
Reference in New Issue
Block a user