61 lines
3.5 KiB
Markdown
61 lines
3.5 KiB
Markdown
# Orchestrator Gateway Contract (draft v0.2)
|
|
|
|
Scope: expose Orchestrator read + operator control surfaces through the Web gateway (tenant-scoped, deterministic pagination, cache headers) to unblock Console control-plane views.
|
|
|
|
This is an interim contract until the gateway is aligned to the Orchestrator OpenAPI (`/openapi/jobengine.json` in the Orchestrator service).
|
|
|
|
## Security / headers
|
|
- `Authorization: Bearer <token>` (or `DPoP` where configured)
|
|
- `X-Stella-Tenant: <tenantId>` (required; see `docs/api/gateway/tenant-auth.md`)
|
|
- `X-Stella-Project: <projectId>` (optional)
|
|
- `X-Stella-Trace-Id: <traceId>` (optional; clients SHOULD send one)
|
|
- Scopes: `orch:read`, `orch:quota`, `orch:operate`, `orch:backfill` (endpoint-specific)
|
|
- Operator audit headers (required on mutating requests):
|
|
- `X-Stella-Operator-Reason: <free-text>`
|
|
- `X-Stella-Operator-Ticket: <ticket-id>` (optional but recommended)
|
|
|
|
## Endpoints
|
|
- `GET /jobengine/sources` — list registered job sources (tenant-scoped).
|
|
- Query params: `sourceType`, `enabled`, `limit`, `continuationToken`
|
|
- `GET /jobengine/sources/{sourceId}` — source detail.
|
|
- `GET /jobengine/quotas` — list quotas (scope: `orch:quota`).
|
|
- Query params: `jobType`, `paused`, `limit`, `continuationToken`
|
|
- `GET /jobengine/quotas/{quotaId}` — quota detail (scope: `orch:quota`).
|
|
- `POST /jobengine/quotas` — create quota (scope: `orch:quota`).
|
|
- `PUT /jobengine/quotas/{quotaId}` — update quota (scope: `orch:quota`).
|
|
- `DELETE /jobengine/quotas/{quotaId}` — delete quota (scope: `orch:quota`).
|
|
- `POST /jobengine/quotas/{quotaId}/pause` — pause quota (scope: `orch:quota`).
|
|
- `POST /jobengine/quotas/{quotaId}/resume` — resume quota (scope: `orch:quota`).
|
|
- `GET /jobengine/quotas/summary` — quota/backpressure metrics summary (scope: `orch:quota`).
|
|
- `GET /jobengine/jobs/summary` — job summary counts (scope: `orch:read`).
|
|
- `GET /jobengine/deadletter/stats` — deadletter stats and top error clustering (scope: `orch:operate`).
|
|
- `GET /jobengine/deadletter/summary` — grouped deadletter summary (scope: `orch:operate`).
|
|
- `POST /jobengine/deadletter/{entryId}/replay` — replay a deadletter entry (scope: `orch:backfill`).
|
|
- `POST /jobengine/deadletter/replay/batch` — replay a set of entry IDs (scope: `orch:backfill`).
|
|
- `POST /jobengine/deadletter/replay/pending` — replay pending entries by filter (scope: `orch:backfill`).
|
|
- `POST /jobengine/pack-runs/{packRunId}/cancel` — cancel a pack run (scope: `orch:operate`).
|
|
- `POST /jobengine/pack-runs/{packRunId}/retry` — retry a pack run (scope: `orch:backfill`).
|
|
|
|
## Caching & pagination
|
|
- `limit` max: `200`.
|
|
- Cursor/paging uses `continuationToken` (opaque string).
|
|
- Recommended headers: `Cache-Control: private, max-age=60, stale-if-error=300`.
|
|
- `ETag` SHOULD be stable over a sorted payload; clients MAY send `If-None-Match`.
|
|
|
|
## Determinism rules
|
|
- Ordering:
|
|
- sources: `(name asc, sourceId asc)`
|
|
- quotas: `(jobType asc, quotaId asc)`
|
|
- deadletter summary: `(category asc, errorCode asc)`
|
|
- Timestamps: ISO-8601 UTC.
|
|
|
|
## Samples
|
|
- `docs/api/gateway/samples/orchestrator-sources.json`
|
|
- `docs/api/gateway/samples/orchestrator-quotas.json`
|
|
- `docs/api/gateway/samples/orchestrator-quota-summary.json`
|
|
- `docs/api/gateway/samples/orchestrator-deadletter-stats.json`
|
|
- `docs/api/gateway/samples/orchestrator-deadletter-summary.json`
|
|
- `docs/api/gateway/samples/orchestrator-deadletter-replay.json`
|
|
- `docs/api/gateway/samples/orchestrator-packrun-cancel.json`
|
|
- `docs/api/gateway/samples/orchestrator-packrun-retry.json`
|