caelum0x b011dce423 test+config: connector test suite + service config/docs (manifest files)
Connectors: 22 real pytest modules (186 pass / 7 optional-dep skips) exercising
every connector's dependency-free surface + missing-driver degradation; SSRF
guard verified; errors_connector.py as a thin re-export (no forked taxonomy).
Services: config/{dev,staging,prod,test,limits,logging}.yaml + docs/*.md for
api/gateway/scheduler/worker, mapped to the real config structs; gateway/scheduler
Dockerfiles + scheduler .env/README. All YAML validated.

Closes 66 manifest files (gap 175->109). No source behavior changed.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-08-17 19:23:14 +03:00

74 lines
3.4 KiB
Markdown

# API contract
`lawsynth-api` is a stdlib WSGI adapter over `lawsynth_server.Application`. It
adds no routes of its own except the streaming endpoint and an explicit marker
for the not-yet-deployed worker transport; every other operation is dispatched
unchanged to the domain core (`app.py`). All routes are served under the `/v1`
prefix (unprefixed aliases exist for `/health` and `/version`).
## Versioning
Every response carries `X-Api-Version: 1`. A request may send `X-Api-Version`
with `1` or `v1`; any other value is rejected `406 unsupported_api_version`.
`GET /v1/version` returns `{"version": <package>, "protocol": "1"}`.
## Routes
| Method | Path | Purpose |
| --- | --- | --- |
| GET | `/v1/health` | database + storage readiness (`ok`/`degraded`) |
| GET | `/v1/version` | package version and protocol version |
| GET | `/v1/projects` `/v1/datasets` `/v1/worlds` `/v1/runs` | list (paginated) |
| POST | `/v1/projects` `/v1/datasets` `/v1/worlds` `/v1/runs` | create |
| GET | `/v1/{collection}/{id}` | fetch one |
| PATCH | `/v1/{collection}/{id}` | update one |
| DELETE | `/v1/{collection}/{id}` | delete one (`204`) |
| POST | `/v1/worlds/{id}/simulate` | run the RK4 simulator for a world |
| POST | `/v1/runs/{id}/cancel` | cancel a non-terminal run |
| GET | `/v1/runs/{id}/events` | events filtered to one run |
| POST | `/v1/artifacts` | upload base64 bytes; returns `sha256` metadata |
| GET | `/v1/artifacts/{sha256}` | download bytes (base64 in JSON) |
| GET | `/v1/events` | list events, or SSE stream (see below) |
`/v1/worker` and `/v1/worker/*` always return `501 worker_transport_unavailable`:
this process is not a worker gateway.
## Authentication
Every route except `/health` and `/version` requires
`Authorization: Bearer <token>`. Tokens are provisioned through
`LAWSYNTH_API_TOKENS_JSON` and map to one `organization_id` (the tenant) and a
set of scopes (`read`, `write`, `admin`). Reads require `read`; mutations require
`write`; `admin` implies both. Missing/invalid tokens return `401`; insufficient
scope returns `403`.
## Writes, idempotency, media type
Request bodies must be `application/json` objects. Every mutating request must
send an `Idempotency-Key` header; the domain replays a stored result for a
repeated key and marks the response `Idempotency-Replayed: true`. Bodies larger
than `max_request_bytes` are rejected `413`.
## Pagination
List routes accept `?limit=<n>&cursor=<opaque>`. Responses are enveloped as
`{"items": [...], "next_cursor": <opaque|null>, "total": <n>, "limit": <n>}`.
`limit` must be within `1..max_page_size`; `next_cursor` is an opaque base64
offset to pass back for the next page.
## Events (SSE)
`GET /v1/events` with `Accept: text/event-stream` returns, as framed SSE, every
retained event for the caller's tenant whose sequence is greater than the
`Last-Event-ID` request header (0 when absent), then closes the connection — the
socket is not held open. Clients resume by reconnecting with the last id they
saw. Retention is bounded and in-process (`event_stream_retention`); evicted
events are not replayable. Without the SSE `Accept` header the same path returns
a plain JSON `{"items": [...]}` list.
## Error envelope
Every error body is `{"error": {"code": <string>, "message": <string>,
"request_id": <uuid>}}` with the same `request_id` echoed in the `X-Request-ID`
header. See `docs/failures.md` for the code-to-status mapping.