FastAPI Endpoint Monitor
A typed FastAPI service for process-local endpoint monitors and secure, on-demand HTTP checks.
Features
- CRUD monitor resources and current-status retrieval
- bounded on-demand HTTP checks with latency measurement
- DNS and redirect-hop SSRF validation (only globally routable HTTP(S) targets)
- concurrency-safe in-memory storage
- health and readiness endpoints
- JSON logs with URL user-info, query, and fragment removed
- environment-validated settings, Docker packaging, and automated tests
State is process-local and ephemeral. Run exactly one worker. Restarts erase all monitors, and multiple replicas do not share state.
Layout
docs/service-design.md— contract, status semantics, security design, and architecturesrc/endpoint_monitor/— application sourcetests/— API and checker tests with mocked outbound HTTP/DNSVALIDATION.md— validation commands and evidence status
Run locally
python -m venv .venv
. .venv/bin/activate
pip install -e '.[dev]'
uvicorn endpoint_monitor.main:app --reload
OpenAPI is at http://127.0.0.1:8000/docs.
Examples
curl -sS http://localhost:8000/healthz
curl -sS -X POST http://localhost:8000/v1/monitors \
-H 'content-type: application/json' \
-d '{"name":"example","url":"https://example.com"}'
curl -sS -X POST http://localhost:8000/v1/monitors/MONITOR_ID/check
curl -sS http://localhost:8000/v1/monitors/MONITOR_ID/status
Create returns 201; reads/checks return 200; delete returns 204; duplicate names return 409; missing IDs return 404; invalid or SSRF-blocked check targets return 400. Transport failures are represented by a 200 check result with status: "error" so the latest attempt remains inspectable.
Configuration
Settings use the MONITOR_ prefix:
| Variable | Default | Constraint |
|---|---|---|
MONITOR_REQUEST_TIMEOUT_SECONDS |
5.0 |
0.1–30 |
MONITOR_MAX_REDIRECTS |
5 |
0–10 |
MONITOR_MAX_MONITORS |
1000 |
1–100000 |
MONITOR_LOG_LEVEL |
INFO |
DEBUG/INFO/WARNING/ERROR/CRITICAL |
Unknown variables are ignored. Invalid known values fail application startup.
Quality checks
ruff format --check .
ruff check .
mypy src
pytest -q
docker build -t endpoint-monitor .
docker run --rm -p 8000:8000 endpoint-monitor
curl -fsS http://localhost:8000/healthz
curl -fsS http://localhost:8000/readyz
Tests never make real outbound requests. See VALIDATION.md for evidence and limitations.