crucible-agent-build-fastapi-endpoint/docs/service-design.md

Endpoint Monitor service design

Scope and lifecycle

This repository contains one unauthenticated FastAPI service for defining endpoint monitors and running checks on demand. State is held in a lock-protected, process-local MonitorStore; it starts empty, is lost on restart, and is not shared between workers. Production deployments of this implementation must therefore use exactly one worker. Persistence and authentication are intentionally out of scope.

Resource and routes

A monitor has a server-generated UUID, name, HTTP(S) URL, creation/update timestamps, and a current_status. Status is one of unknown, up, down, or error. unknown has never been checked; up means the final response was 200–399; down means it was 400–599; error represents a timeout, transport failure, redirect-policy violation, or SSRF rejection.

Method	Path	Meaning
POST	/v1/monitors	Create (201)
GET	/v1/monitors	List, ordered by creation time
GET	/v1/monitors/{id}	Retrieve
PATCH	/v1/monitors/{id}	Partially update name/URL
DELETE	/v1/monitors/{id}	Delete (204)
POST	/v1/monitors/{id}/check	Run an on-demand check and atomically store it
GET	/v1/monitors/{id}/status	Retrieve current status
GET	/healthz	Liveness
GET	/readyz	Readiness and storage mode

Checks do not download response bodies. Redirects are followed explicitly up to the configured bound. Every hop is parsed, DNS-resolved, policy-checked, and connected through a resolver pinned to the approved addresses. If any answer is loopback, private, link-local, multicast, unspecified, reserved, or otherwise non-global, the hop is rejected. This conservative all-addresses rule and address pinning prevent mixed-answer and DNS-rebinding bypasses. Only HTTP and HTTPS URLs without credentials are accepted.

The checker returns a status representation for expected outbound failures rather than turning remote endpoint behavior into a 5xx response. A concurrent monitor edit causes 409 and prevents a result for the old definition from replacing current state. Missing resources return 404. Validation returns 422. Errors use {"error":{"code":"...","message":"..."}} and never include outbound exception text.

Concurrency and logging

Store operations and compare-and-set status recording are guarded by one asyncio.Lock. Reads return deep copies. A monotonically increasing internal revision makes check updates atomic with respect to edits/deletes.

Application events are one-line JSON records. URLs are normalized for logs by removing user information, fragments, and all query values (?REDACTED). Outbound exception details are classified, not logged verbatim. API resources retain the configured URL because it is part of their explicit contract; operators should still avoid URL credentials and secrets.

Project structure

• app/main.py: application factory, lifespan, handlers
• app/api.py: REST contract
• app/models.py: typed request/response models
• app/store.py: concurrency-safe process-local state
• app/checker.py: SSRF-safe checker and redacted event logging
• app/settings.py: validated MONITOR_ environment configuration
• tests/: unit and API tests with no real outbound traffic
• Dockerfile, compose.yaml, pyproject.toml: packaging and workflows
• docs/verification.md: validation checklist and observed limitations