76 lines
2.5 KiB
Markdown
76 lines
2.5 KiB
Markdown
# 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 architecture
|
||
- `src/endpoint_monitor/` — application source
|
||
- `tests/` — API and checker tests with mocked outbound HTTP/DNS
|
||
- `VALIDATION.md` — validation commands and evidence status
|
||
|
||
## Run locally
|
||
|
||
```bash
|
||
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
|
||
|
||
```bash
|
||
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
|
||
|
||
```bash
|
||
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.
|