57 lines
2.7 KiB
Markdown
57 lines
2.7 KiB
Markdown
# Endpoint Monitor service contract
|
|
|
|
## Resources and lifecycle
|
|
|
|
A monitor has an immutable UUID, `name`, HTTP(S) `url`, timestamps, and a current
|
|
check snapshot. New and URL-updated monitors are `unknown`. State is process-local
|
|
memory, protected by one async lock, and is lost on restart. Multiple workers do not
|
|
share state. No authentication is provided; deploy behind an authenticated gateway.
|
|
|
|
## HTTP API
|
|
|
|
| Method and path | Success | Notes |
|
|
|---|---:|---|
|
|
| `POST /monitors` | 201 | Create; duplicate names are allowed |
|
|
| `GET /monitors` | 200 | Stable creation-order list |
|
|
| `GET /monitors/{id}` | 200 | Retrieve |
|
|
| `PUT /monitors/{id}` | 200 | Full update |
|
|
| `DELETE /monitors/{id}` | 204 | Delete |
|
|
| `POST /monitors/{id}/check` | 200 | Run one bounded check and atomically publish it |
|
|
| `GET /monitors/{id}/status` | 200 | Current snapshot; no network call |
|
|
| `GET /health/live` | 200 | Process is serving HTTP |
|
|
| `GET /health/ready` | 200 | Configuration and in-memory store are available |
|
|
|
|
Missing monitor IDs return `404 {"detail":"monitor not found"}`. Validation failures
|
|
use FastAPI's 422 response. A check transport failure is a successful invocation and
|
|
returns a snapshot with `error`; an unsafe target returns `blocked`. These are not API
|
|
5xx responses because the service completed the requested check.
|
|
|
|
## Status semantics
|
|
|
|
`unknown` means never checked or URL changed. `up` means final status 200-399 after
|
|
safe redirects. `down` means final status 400-599. `error` means timeout, DNS failure,
|
|
or HTTP transport failure. `blocked` means SSRF policy rejected a host/address or
|
|
redirect. Snapshots contain completion time, latency in milliseconds, optional HTTP
|
|
status, and a bounded non-sensitive error code.
|
|
|
|
## Check security and consistency
|
|
|
|
Only HTTP(S), no URL credentials, and a non-empty hostname are accepted. Every hop is
|
|
resolved before I/O; every resolved address must be globally routable. Redirects are
|
|
followed manually and revalidated, with a configured maximum. Timeouts and redirect
|
|
counts are bounded. The store uses a revision compare-and-set so a result from an old
|
|
URL cannot overwrite a concurrent update. This DNS preflight mitigates ordinary SSRF;
|
|
deployments requiring protection from DNS rebinding should also enforce egress policy
|
|
at the network layer.
|
|
|
|
Logs are JSON and include monitor ID, outcome, latency, and a URL with credentials,
|
|
query, and fragment removed. Raw exception text and redirect locations are never
|
|
logged.
|
|
|
|
## Layout
|
|
|
|
`app/` contains settings, models, locked store, SSRF validation, checker, logging, and
|
|
FastAPI composition. `tests/` contains API/unit security tests. Packaging is in
|
|
`pyproject.toml`, `Dockerfile`, and `compose.yaml`; operational evidence is in
|
|
`VERIFICATION.md`.
|