70 lines
2.6 KiB
Markdown
70 lines
2.6 KiB
Markdown
# Orchestrator Event Envelope (draft)
|
|
|
|
Status: draft for ORCH-SVC-38-101 (pending ORCH-SVC-37-101 approval)
|
|
|
|
## Goals
|
|
- Single, provenance-rich envelope for policy/export/job lifecycle events.
|
|
- Idempotent across retries and transports (Notifier bus, webhooks, SSE/WS streams).
|
|
- Tenant/project isolation and offline-friendly replays.
|
|
|
|
## Envelope
|
|
```jsonc
|
|
{
|
|
"schemaVersion": "orch.event.v1",
|
|
"eventId": "urn:orch:event:...", // UUIDv7 or ULID
|
|
"eventType": "job.failed|job.completed|pack_run.log|pack_run.artifact|policy.updated|export.completed",
|
|
"occurredAt": "2025-11-19T12:34:56Z",
|
|
"idempotencyKey": "orch-{eventType}-{jobId}-{attempt}",
|
|
"correlationId": "corr-...", // propagated from producer
|
|
"tenantId": "...",
|
|
"projectId": "...", // optional but preferred
|
|
"actor": {
|
|
"subject": "service/worker-sdk-go", // who emitted the event
|
|
"scopes": ["orch:quota", "orch:backfill"]
|
|
},
|
|
"job": {
|
|
"id": "job_018f...",
|
|
"type": "pack-run|ingest|export|policy-simulate",
|
|
"runId": "run_018f...", // for pack runs / sims
|
|
"attempt": 3,
|
|
"leaseId": "lease_018f...",
|
|
"taskRunnerId": "tr_018f...",
|
|
"status": "completed|failed|running|canceled",
|
|
"reason": "user_cancelled|retry_backoff|quota_paused",
|
|
"payloadDigest": "sha256:...",
|
|
"artifacts": [
|
|
{"uri": "s3://...", "digest": "sha256:...", "mime": "application/json"}
|
|
]
|
|
},
|
|
"metrics": {
|
|
"durationSeconds": 12.345,
|
|
"logStreamLagSeconds": 0.8,
|
|
"backoffSeconds": 30
|
|
},
|
|
"notifier": {
|
|
"channel": "orch.jobs",
|
|
"delivery": "dsse",
|
|
"replay": {"ordinal": 5, "total": 12}
|
|
}
|
|
}
|
|
```
|
|
|
|
## Idempotency rules
|
|
- `eventId` globally unique; `idempotencyKey` dedupe per channel.
|
|
- Emit once per state transition; retries reuse the same `eventId`/`idempotencyKey`.
|
|
|
|
## Provenance
|
|
- Always include `tenantId` and `projectId` (if available).
|
|
- Carry `correlationId` from upstream producers and `taskRunnerId` from leasing bridge.
|
|
- Include `actor.scopes` when events are triggered via elevated tokens (`orch:quota`, `orch:backfill`).
|
|
|
|
## Transport bindings
|
|
- **Notifier bus**: DSSE-wrapped envelope; subject `orch.event` and `eventType`.
|
|
- **Webhooks**: HMAC with `X-Orchestrator-Signature` (sha256), replay-safe via `idempotencyKey`.
|
|
- **SSE/WS**: stream per `tenantId` filtered by `projectId`; client dedupe via `eventId`.
|
|
|
|
## Backlog & follow-ups
|
|
- Align field names with ORCH-SVC-37-101 once finalized.
|
|
- Add examples for policy/export events and pack-run log/manifest payloads.
|
|
- Document retry/backoff semantics in Notify/Console subscribers.
|