rework: migrate module path, fix healthcheck URL, add architecture notes
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:
2026-03-01 09:57:32 -08:00
parent 18cfedb81c
commit 69bbc958a7
23 changed files with 94 additions and 61 deletions

View File

@@ -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