rework: migrate module path, fix healthcheck URL, add architecture notes
All checks were successful
check / check (push) Successful in 1m57s
All checks were successful
check / check (push) Successful in 1m57s
- Migrate Go module path from git.eeqj.de/sneak/webhooker to sneak.berlin/go/webhooker (go.mod, pkg/config/go.mod, all imports) - Drop .json extension from healthcheck endpoint: /.well-known/healthcheck (routes.go, Dockerfile HEALTHCHECK, README) - Add Rate Limiting section to README Design: global rate limiting must not apply to webhook endpoints; per-webhook configurable limits instead - Add Database Architecture section to README Design: separate SQLite files for main app config vs per-processor data (input logs, processor logs, output queues) Addresses review feedback from sneak on PR #6.
This commit is contained in:
35
README.md
35
README.md
@@ -66,6 +66,39 @@ application lifecycle. It uses `log/slog` for structured logging, GORM
|
||||
for database access, and SQLite (via `modernc.org/sqlite`, pure Go, no
|
||||
CGO) for storage. HTTP routing uses chi.
|
||||
|
||||
### Rate Limiting
|
||||
|
||||
Global rate limiting middleware (e.g. per-IP throttling applied at the
|
||||
router level) must **not** apply to webhook receiver endpoints
|
||||
(`/webhook/{uuid}`). Webhook endpoints receive automated traffic from
|
||||
external services at unpredictable rates, and blanket rate limits would
|
||||
cause legitimate webhook deliveries to be dropped.
|
||||
|
||||
Instead, each webhook endpoint has its own individually configurable rate
|
||||
limit, applied within the webhook handler itself. By default, no rate
|
||||
limit is applied — webhook endpoints accept traffic as fast as it arrives.
|
||||
Rate limits can be configured on a per-webhook basis in the application
|
||||
when needed (e.g. to protect against a misbehaving sender).
|
||||
|
||||
### Database Architecture
|
||||
|
||||
webhooker uses separate SQLite database files rather than a single
|
||||
monolithic database:
|
||||
|
||||
- **Main application database** — Stores application configuration and
|
||||
all standard webapp data: users, sessions, API keys, and global
|
||||
settings.
|
||||
- **Per-processor databases** — Each processor (working name — a better
|
||||
term is needed) gets its own dedicated SQLite database file containing:
|
||||
input logs, processor logs, and all output queues for that specific
|
||||
processor.
|
||||
|
||||
This separation provides several benefits: processor databases can be
|
||||
independently backed up, rotated, or archived; a high-volume processor
|
||||
won't cause lock contention or bloat affecting the main application; and
|
||||
individual processor data can be cleanly deleted when a processor is
|
||||
removed.
|
||||
|
||||
### Package Layout
|
||||
|
||||
All application code lives under `internal/` to prevent external imports.
|
||||
@@ -98,7 +131,7 @@ The main entry point is `cmd/webhooker/main.go`.
|
||||
### API Endpoints
|
||||
|
||||
- `GET /` — Web UI index page
|
||||
- `GET /.well-known/healthcheck.json` — Health check with uptime, version
|
||||
- `GET /.well-known/healthcheck` — Health check with uptime, version
|
||||
- `GET /s/*` — Static file serving (CSS, JS)
|
||||
- `GET /metrics` — Prometheus metrics (requires basic auth)
|
||||
- `POST /webhook/{uuid}` — Webhook receiver endpoint
|
||||
|
||||
Reference in New Issue
Block a user