# Endpoint Monitor Service

A typed FastAPI API that keeps endpoint monitors in concurrency-safe, process-local memory and performs SSRF-aware checks on demand. The service has no authentication and should not be exposed directly to untrusted users.

## Quick start

Requires Python 3.12.

```sh
python -m venv .venv
. .venv/bin/activate
python -m pip install -e '.[dev]'
./scripts/validate.sh
uvicorn monitor_service.api:app --reload
```

Create and check a monitor:

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

OpenAPI is at `/docs`. Liveness and readiness are at `/healthz` and `/readyz`.

## Configuration

All settings use the `MONITOR_` prefix: `APP_NAME`, `LOG_LEVEL`, `CONNECT_TIMEOUT_SECONDS` (default 3), `READ_TIMEOUT_SECONDS` (5), `POOL_TIMEOUT_SECONDS` (3), `MAX_REDIRECTS` (5), and `USER_AGENT`. Invalid or out-of-range values fail startup. Use one worker: memory is not durable or shared among processes.

## Security behavior

Every initial and redirected HTTP(S) target is resolved before a request. A hop is denied if any answer is non-global, URL credentials are denied, redirect count is bounded, and timeouts are finite. Logs and check responses remove URL query and fragment data. See `docs/service-contract.md` for status/error semantics and the documented DNS resolver/connect TOCTOU limitation.

## Container

```sh
docker build -t endpoint-monitor .
docker run --rm -p 8000:8000 endpoint-monitor
# or: docker compose up --build
curl -f http://localhost:8000/healthz
```

The image is two-stage, runs as a non-root user, contains a healthcheck, and deliberately starts one Uvicorn worker.

## Layout and verification

- `docs/service-contract.md`: API and architecture contract
- `src/monitor_service/`: application, checker, state, models, settings, logging
- `tests/`: API, concurrency, checker, SSRF redirect/DNS, failure, and redaction tests
- `scripts/validate.sh`: the authoritative Ruff format/lint, mypy, and pytest contract
- `Dockerfile` and `compose.yaml`: container workflows

Run `./scripts/validate.sh`. Container verification additionally uses the build/run/curl commands above. `VALIDATION.md` records what was and was not executed by generation; it must not be read as a substitute for fresh CI output.