add release orchestrator docs and sprints gaps fills
This commit is contained in:
374
docs/modules/release-orchestrator/api/websockets.md
Normal file
374
docs/modules/release-orchestrator/api/websockets.md
Normal file
@@ -0,0 +1,374 @@
|
||||
# Real-Time APIs (WebSocket/SSE)
|
||||
|
||||
> WebSocket and Server-Sent Events endpoints for real-time updates.
|
||||
|
||||
**Status:** Planned (not yet implemented)
|
||||
**Source:** [Architecture Advisory Section 6.4](../../../product/advisories/09-Jan-2026%20-%20Stella%20Ops%20Orchestrator%20Architecture.md)
|
||||
**Related Modules:** [Workflow Execution](../workflow/execution.md), [UI Dashboard](../ui/dashboard.md)
|
||||
|
||||
## Overview
|
||||
|
||||
The Release Orchestrator provides real-time streaming endpoints for workflow runs, deployment progress, agent tasks, and dashboard metrics. These endpoints support both WebSocket connections and Server-Sent Events (SSE) for browser compatibility.
|
||||
|
||||
---
|
||||
|
||||
## Authentication
|
||||
|
||||
All WebSocket and SSE connections require authentication via JWT token:
|
||||
|
||||
**WebSocket:** Token in query parameter or first message
|
||||
```
|
||||
ws://api/v1/workflow-runs/{id}/stream?token=jwt-token
|
||||
```
|
||||
|
||||
**SSE:** Token in Authorization header
|
||||
```
|
||||
GET /api/v1/dashboard/stream
|
||||
Authorization: Bearer jwt-token
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Workflow Run Stream
|
||||
|
||||
**Endpoint:** `WS /api/v1/workflow-runs/{id}/stream`
|
||||
|
||||
Streams real-time updates for a workflow run including step progress and logs.
|
||||
|
||||
### Message Types (Server to Client)
|
||||
|
||||
**Step Started:**
|
||||
```json
|
||||
{
|
||||
"type": "step_started",
|
||||
"nodeId": "security-check",
|
||||
"stepType": "security-gate",
|
||||
"timestamp": "2026-01-10T14:23:45Z"
|
||||
}
|
||||
```
|
||||
|
||||
**Step Progress:**
|
||||
```json
|
||||
{
|
||||
"type": "step_progress",
|
||||
"nodeId": "deploy",
|
||||
"progress": 50,
|
||||
"message": "Deploying to target 3/6"
|
||||
}
|
||||
```
|
||||
|
||||
**Step Log:**
|
||||
```json
|
||||
{
|
||||
"type": "step_log",
|
||||
"nodeId": "deploy",
|
||||
"line": "Pulling image sha256:abc123...",
|
||||
"level": "info",
|
||||
"timestamp": "2026-01-10T14:23:50Z"
|
||||
}
|
||||
```
|
||||
|
||||
**Step Completed:**
|
||||
```json
|
||||
{
|
||||
"type": "step_completed",
|
||||
"nodeId": "security-check",
|
||||
"status": "succeeded",
|
||||
"outputs": {
|
||||
"criticalCount": 0,
|
||||
"highCount": 3
|
||||
},
|
||||
"duration": 5.2,
|
||||
"timestamp": "2026-01-10T14:23:50Z"
|
||||
}
|
||||
```
|
||||
|
||||
**Workflow Completed:**
|
||||
```json
|
||||
{
|
||||
"type": "workflow_completed",
|
||||
"status": "succeeded",
|
||||
"duration": 125.5,
|
||||
"outputs": {
|
||||
"deploymentId": "uuid"
|
||||
},
|
||||
"timestamp": "2026-01-10T14:25:50Z"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Deployment Job Stream
|
||||
|
||||
**Endpoint:** `WS /api/v1/deployment-jobs/{id}/stream`
|
||||
|
||||
Streams real-time updates for deployment job execution.
|
||||
|
||||
### Message Types (Server to Client)
|
||||
|
||||
**Task Started:**
|
||||
```json
|
||||
{
|
||||
"type": "task_started",
|
||||
"taskId": "uuid",
|
||||
"targetId": "uuid",
|
||||
"targetName": "prod-web-01",
|
||||
"taskType": "docker.pull",
|
||||
"timestamp": "2026-01-10T14:23:45Z"
|
||||
}
|
||||
```
|
||||
|
||||
**Task Progress:**
|
||||
```json
|
||||
{
|
||||
"type": "task_progress",
|
||||
"taskId": "uuid",
|
||||
"progress": 75,
|
||||
"message": "Pulling layer 4/5"
|
||||
}
|
||||
```
|
||||
|
||||
**Task Log:**
|
||||
```json
|
||||
{
|
||||
"type": "task_log",
|
||||
"taskId": "uuid",
|
||||
"line": "Container started successfully",
|
||||
"level": "info"
|
||||
}
|
||||
```
|
||||
|
||||
**Task Completed:**
|
||||
```json
|
||||
{
|
||||
"type": "task_completed",
|
||||
"taskId": "uuid",
|
||||
"targetId": "uuid",
|
||||
"status": "succeeded",
|
||||
"duration": 45.2,
|
||||
"result": {
|
||||
"containerId": "abc123",
|
||||
"digest": "sha256:..."
|
||||
},
|
||||
"timestamp": "2026-01-10T14:24:30Z"
|
||||
}
|
||||
```
|
||||
|
||||
**Job Completed:**
|
||||
```json
|
||||
{
|
||||
"type": "job_completed",
|
||||
"status": "succeeded",
|
||||
"targetsDeployed": 4,
|
||||
"targetsFailed": 0,
|
||||
"duration": 180.5,
|
||||
"timestamp": "2026-01-10T14:26:45Z"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Agent Task Stream
|
||||
|
||||
**Endpoint:** `WS /api/v1/agents/{id}/task-stream`
|
||||
|
||||
Bidirectional stream for agent task assignment and progress reporting.
|
||||
|
||||
### Message Types (Server to Agent)
|
||||
|
||||
**Task Assigned:**
|
||||
```json
|
||||
{
|
||||
"type": "task_assigned",
|
||||
"task": {
|
||||
"taskId": "uuid",
|
||||
"taskType": "docker.pull",
|
||||
"payload": {
|
||||
"image": "myapp",
|
||||
"digest": "sha256:abc123..."
|
||||
},
|
||||
"credentials": {
|
||||
"registry.username": "user",
|
||||
"registry.password": "token"
|
||||
},
|
||||
"timeout": 300
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Task Cancelled:**
|
||||
```json
|
||||
{
|
||||
"type": "task_cancelled",
|
||||
"taskId": "uuid",
|
||||
"reason": "Deployment cancelled by user"
|
||||
}
|
||||
```
|
||||
|
||||
### Message Types (Agent to Server)
|
||||
|
||||
**Task Progress:**
|
||||
```json
|
||||
{
|
||||
"type": "task_progress",
|
||||
"taskId": "uuid",
|
||||
"progress": 50,
|
||||
"message": "Pulling image layer 3/5"
|
||||
}
|
||||
```
|
||||
|
||||
**Task Log:**
|
||||
```json
|
||||
{
|
||||
"type": "task_log",
|
||||
"taskId": "uuid",
|
||||
"level": "info",
|
||||
"message": "Image layer downloaded: sha256:def456..."
|
||||
}
|
||||
```
|
||||
|
||||
**Task Completed:**
|
||||
```json
|
||||
{
|
||||
"type": "task_completed",
|
||||
"taskId": "uuid",
|
||||
"success": true,
|
||||
"result": {
|
||||
"imageId": "sha256:abc123..."
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Dashboard Metrics Stream
|
||||
|
||||
**Endpoint:** `WS /api/v1/dashboard/stream`
|
||||
|
||||
Streams real-time dashboard metrics and alerts.
|
||||
|
||||
### Message Types (Server to Client)
|
||||
|
||||
**Metric Update:**
|
||||
```json
|
||||
{
|
||||
"type": "metric_update",
|
||||
"metrics": {
|
||||
"pipelineStatus": [
|
||||
{ "environmentId": "uuid", "name": "Production", "health": "healthy" }
|
||||
],
|
||||
"pendingApprovals": 3,
|
||||
"activeDeployments": 1,
|
||||
"recentReleases": 12,
|
||||
"systemHealth": {
|
||||
"agentsOnline": 8,
|
||||
"agentsTotal": 10,
|
||||
"queueDepth": 5
|
||||
}
|
||||
},
|
||||
"timestamp": "2026-01-10T14:23:45Z"
|
||||
}
|
||||
```
|
||||
|
||||
**Alert:**
|
||||
```json
|
||||
{
|
||||
"type": "alert",
|
||||
"alert": {
|
||||
"id": "uuid",
|
||||
"severity": "warning",
|
||||
"title": "Deployment Failed",
|
||||
"message": "Deployment to Production failed: health check timeout",
|
||||
"resourceType": "deployment",
|
||||
"resourceId": "uuid",
|
||||
"timestamp": "2026-01-10T14:23:45Z"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Promotion Update:**
|
||||
```json
|
||||
{
|
||||
"type": "promotion_update",
|
||||
"promotion": {
|
||||
"id": "uuid",
|
||||
"releaseName": "myapp-v2.3.1",
|
||||
"targetEnvironment": "Production",
|
||||
"status": "awaiting_approval",
|
||||
"requestedBy": "John Doe"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Connection Management
|
||||
|
||||
### Reconnection
|
||||
|
||||
Clients should implement exponential backoff reconnection:
|
||||
|
||||
```javascript
|
||||
const connect = (retryCount = 0) => {
|
||||
const ws = new WebSocket(url);
|
||||
|
||||
ws.onclose = () => {
|
||||
const delay = Math.min(1000 * Math.pow(2, retryCount), 30000);
|
||||
setTimeout(() => connect(retryCount + 1), delay);
|
||||
};
|
||||
|
||||
ws.onopen = () => {
|
||||
retryCount = 0;
|
||||
};
|
||||
};
|
||||
```
|
||||
|
||||
### Heartbeat
|
||||
|
||||
WebSocket connections receive periodic heartbeat messages:
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "heartbeat",
|
||||
"timestamp": "2026-01-10T14:23:45Z"
|
||||
}
|
||||
```
|
||||
|
||||
Clients should respond with:
|
||||
```json
|
||||
{
|
||||
"type": "pong"
|
||||
}
|
||||
```
|
||||
|
||||
Connections without pong response within 30 seconds are terminated.
|
||||
|
||||
---
|
||||
|
||||
## Error Messages
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "error",
|
||||
"code": "unauthorized",
|
||||
"message": "Token expired",
|
||||
"timestamp": "2026-01-10T14:23:45Z"
|
||||
}
|
||||
```
|
||||
|
||||
| Error Code | Description |
|
||||
|------------|-------------|
|
||||
| `unauthorized` | Invalid or expired token |
|
||||
| `forbidden` | No access to resource |
|
||||
| `not_found` | Resource not found |
|
||||
| `rate_limited` | Too many connections |
|
||||
| `internal_error` | Server error |
|
||||
|
||||
---
|
||||
|
||||
## See Also
|
||||
|
||||
- [Workflows API](workflows.md)
|
||||
- [Agents API](agents.md)
|
||||
- [UI Dashboard](../ui/dashboard.md)
|
||||
- [Workflow Execution](../workflow/execution.md)
|
||||
Reference in New Issue
Block a user