2.8 KiB
Service contract and architecture
Resource
A monitor has an immutable UUID id, name, HTTP(S) url, timestamps, and current status. status is unknown until checked, up for a final HTTP 200–399 response, down for a final HTTP 400–599 response, and error when no accepted HTTP response is obtained. Check metadata comprises checked_at, non-negative latency_ms, optional http_status, and a bounded, non-sensitive error category.
API
All JSON is UTF-8. Routes are under /api/v1 except operational probes.
POST /api/v1/monitors-> 201 and monitor; duplicate names are allowed.GET /api/v1/monitors-> 200 list sorted by creation time and id.GET /api/v1/monitors/{id}-> 200 or 404.PUT /api/v1/monitors/{id}-> 200 or 404. Updating name/URL resets check state tounknown.DELETE /api/v1/monitors/{id}-> 204 or 404.POST /api/v1/monitors/{id}/check-> 200 and atomically persisted check result, or 404 if absent/deleted during the check.GET /api/v1/monitors/{id}/status-> 200 current status projection or 404.GET /healthz-> liveness 200;GET /readyz-> readiness 200 after app initialization.
FastAPI's validation errors use 422. Application errors use {"detail":"..."} and do not expose network exception text. There is intentionally no authentication.
Checker and SSRF policy
Only HTTP(S), non-credentialed URLs are accepted. Before every request and after every redirect, the host is resolved and every returned address must be globally routable. Loopback, private, link-local, multicast, reserved, unspecified, and non-global addresses are rejected. Redirects are followed manually up to the configured bound. Timeouts and response-body streaming are bounded. This validation substantially reduces SSRF risk, but DNS validation and connection are separate operations in the standard HTTP stack; production deployments should additionally enforce an egress proxy/firewall to eliminate DNS-rebinding TOCTOU risk.
Checks use a monotonic timer. Store mutation occurs under one asyncio lock. A delete that races with a check wins and the result is not resurrected.
Lifecycle and deployment
MonitorStore is process-local and starts empty on every process start. It is concurrency-safe within one event loop, not shared across workers, and has no persistence. Run exactly one worker. Readiness describes initialization, not durability or external dependency health.
Configuration is environment-driven and validated at startup. Logs are one-line JSON. Logged URLs have credentials, query, and fragment removed; only controlled error categories are logged.
Project layout
app/models.py defines the contract; store.py owns state; security.py validates targets; checker.py performs checks; main.py wires HTTP routes and lifecycle. Tests inject DNS and HTTP transports so outbound calls are deterministic.