A typed FastAPI service for process-local monitor CRUD and secure, on-demand HTTP checks. The full contract and status semantics are in docs/service-contract.md.

Run locally

python -m venv .venv
. .venv/bin/activate
pip install -e '.[dev]'
uvicorn app.main:app --reload

Create and check a monitor:

curl -sS -X POST http://localhost:8000/monitors \
  -H 'content-type: application/json' \
  -d '{"name":"example","url":"https://example.com/health?token=secret"}'
curl -sS -X POST http://localhost:8000/monitors/MONITOR_UUID/check
curl -sS http://localhost:8000/monitors/MONITOR_UUID/status
curl -sS http://localhost:8000/health/ready

OpenAPI is at /docs. There is intentionally no authentication.

Configuration

All settings are validated at startup and use the MONITOR_ prefix:

Variable	Default	Constraint
`MONITOR_APP_NAME`	endpoint-monitor	string
`MONITOR_LOG_LEVEL`	INFO	logging level
`MONITOR_CONNECT_TIMEOUT_SECONDS`	2	>0, <=30
`MONITOR_CHECK_TIMEOUT_SECONDS`	5	>0, <=60
`MONITOR_MAX_REDIRECTS`	3	0..10

Quality checks

ruff format --check .
ruff check .
mypy app
pytest

Outbound HTTP is mocked in tests. Security cases cover private DNS answers, redirects to loopback, bounded errors, compare-and-set status publication, and query redaction.

Container

docker build -t endpoint-monitor .
docker run --rm -p 8000:8000 endpoint-monitor
# or: docker compose up --build

The image runs as a non-root user and deliberately uses one worker. A restart loses all monitors. Running multiple workers/replicas creates independent datasets and inconsistent reads; use a shared durable store before scaling. DNS preflight is not a replacement for network-level egress controls against rebinding.

Project layout

app/: API, settings, locked store, checker, SSRF policy, JSON logging
tests/: API, checker, store, configuration, and security tests
docs/service-contract.md: routes, semantics, lifecycle, and threat boundaries
VERIFICATION.md: exact validation commands and execution status