103 lines
2.5 KiB
Markdown
103 lines
2.5 KiB
Markdown
# Orchestrator · First Signal API
|
|
|
|
Provides a fast “first meaningful signal” for a run (TTFS), with caching and ETag-based conditional requests.
|
|
|
|
## Endpoint
|
|
|
|
`GET /api/v1/jobengine/runs/{runId}/first-signal`
|
|
|
|
### Required headers
|
|
- `X-Tenant-Id`: tenant identifier (string)
|
|
|
|
### Optional headers
|
|
- `If-None-Match`: weak ETag from a previous 200 response (supports multiple values)
|
|
|
|
## Responses
|
|
|
|
### 200 OK
|
|
Returns the first signal payload and a weak ETag.
|
|
|
|
Response headers:
|
|
- `ETag`: weak ETag (for `If-None-Match`)
|
|
- `Cache-Control: private, max-age=60`
|
|
- `Cache-Status: hit|miss`
|
|
- `X-FirstSignal-Source: snapshot|cold_start` (best-effort diagnostics)
|
|
|
|
Body (`application/json`):
|
|
```json
|
|
{
|
|
"runId": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
|
|
"firstSignal": {
|
|
"type": "started",
|
|
"stage": "unknown",
|
|
"step": null,
|
|
"message": "Run started",
|
|
"at": "2025-12-15T12:00:10+00:00",
|
|
"artifact": { "kind": "run", "range": null }
|
|
},
|
|
"summaryEtag": "W/\"...\""
|
|
}
|
|
```
|
|
|
|
### 204 No Content
|
|
Run exists but no signal is available yet (e.g., run has no jobs).
|
|
|
|
### 304 Not Modified
|
|
Returned when `If-None-Match` matches the current ETag.
|
|
|
|
### 404 Not Found
|
|
Run does not exist for the resolved tenant.
|
|
|
|
### 400 Bad Request
|
|
Missing/invalid tenant header or invalid parameters.
|
|
|
|
## ETag semantics
|
|
- Weak ETags are computed from a deterministic, canonical hash of the stable signal content.
|
|
- Per-request diagnostics (e.g., cache hit/miss) are intentionally excluded from the ETag material.
|
|
|
|
## Streaming (SSE)
|
|
The run stream emits `first_signal` events when the signal changes:
|
|
|
|
`GET /api/v1/jobengine/stream/runs/{runId}`
|
|
|
|
Event type:
|
|
- `first_signal`
|
|
|
|
Payload shape:
|
|
```json
|
|
{
|
|
"runId": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
|
|
"etag": "W/\"...\"",
|
|
"signal": { "version": "1.0", "signalId": "...", "jobId": "...", "timestamp": "...", "kind": 1, "phase": 6, "scope": { "type": "run", "id": "..." }, "summary": "...", "etaSeconds": null, "lastKnownOutcome": null, "nextActions": null, "diagnostics": { "cacheHit": false, "source": "cold_start", "correlationId": "" } }
|
|
}
|
|
```
|
|
|
|
## Configuration
|
|
|
|
`appsettings.json`:
|
|
```json
|
|
{
|
|
"FirstSignal": {
|
|
"Cache": {
|
|
"Backend": "inmemory",
|
|
"TtlSeconds": 86400,
|
|
"SlidingExpiration": true,
|
|
"KeyPrefix": "orchestrator:first_signal:"
|
|
},
|
|
"ColdPath": {
|
|
"TimeoutMs": 3000
|
|
},
|
|
"SnapshotWriter": {
|
|
"Enabled": false,
|
|
"TenantId": null,
|
|
"PollIntervalSeconds": 10,
|
|
"MaxRunsPerTick": 50,
|
|
"LookbackMinutes": 60
|
|
}
|
|
},
|
|
"messaging": {
|
|
"transport": "inmemory"
|
|
}
|
|
}
|
|
```
|