41 lines
3.9 KiB
Markdown
41 lines
3.9 KiB
Markdown
# Orchestrator Event Envelopes with SSE/WebSocket Streaming
|
|
|
|
## Module
|
|
Orchestrator
|
|
|
|
## Status
|
|
IMPLEMENTED
|
|
|
|
## Description
|
|
Typed event envelope system with SSE and WebSocket streaming for real-time orchestrator job progress, enabling live UI updates and CLI monitoring of pack-run execution.
|
|
|
|
## Implementation Details
|
|
- **Modules**: `src/JobEngine/StellaOps.JobEngine/StellaOps.JobEngine.Core/Domain/Events/`, `src/JobEngine/StellaOps.JobEngine/StellaOps.JobEngine.Core/Hashing/`, `src/JobEngine/StellaOps.JobEngine/StellaOps.JobEngine.WebService/Streaming/`
|
|
- **Key Classes**:
|
|
- `EventEnvelope` (`src/JobEngine/StellaOps.JobEngine/StellaOps.JobEngine.Core/Domain/Events/EventEnvelope.cs`) - typed event envelope with event type, payload, timestamp, and correlation ID
|
|
- `EventEnvelope` (legacy) (`src/JobEngine/StellaOps.JobEngine/StellaOps.JobEngine.Core/EventEnvelope.cs`) - legacy event envelope model
|
|
- `TimelineEvent` (`src/JobEngine/StellaOps.JobEngine/StellaOps.JobEngine.Core/Domain/Events/TimelineEvent.cs`) - timeline event for job lifecycle tracking
|
|
- `TimelineEventEmitter` (`src/JobEngine/StellaOps.JobEngine/StellaOps.JobEngine.Core/Domain/Events/TimelineEventEmitter.cs`) - emits timeline events on domain actions
|
|
- `OrchestratorEventPublisher` (`src/JobEngine/StellaOps.JobEngine/StellaOps.JobEngine.Infrastructure/Events/OrchestratorEventPublisher.cs`) - concrete publisher routing events to stream coordinators
|
|
- `EventEnvelopeHasher` (`src/JobEngine/StellaOps.JobEngine/StellaOps.JobEngine.Core/Hashing/EventEnvelopeHasher.cs`) - hashes event envelopes for integrity verification
|
|
- `CanonicalJsonHasher` (`src/JobEngine/StellaOps.JobEngine/StellaOps.JobEngine.Core/Hashing/CanonicalJsonHasher.cs`) - canonical JSON hashing for deterministic event hashes
|
|
- `SseWriter` (`src/JobEngine/StellaOps.JobEngine/StellaOps.JobEngine.WebService/Streaming/SseWriter.cs`) - Server-Sent Events writer
|
|
- `JobStreamCoordinator` (`src/JobEngine/StellaOps.JobEngine/StellaOps.JobEngine.WebService/Streaming/JobStreamCoordinator.cs`) - job event stream coordinator
|
|
- `PackRunStreamCoordinator` (`src/JobEngine/StellaOps.JobEngine/StellaOps.JobEngine.WebService/Streaming/PackRunStreamCoordinator.cs`) - pack-run stream coordinator
|
|
- `RunStreamCoordinator` (`src/JobEngine/StellaOps.JobEngine/StellaOps.JobEngine.WebService/Streaming/RunStreamCoordinator.cs`) - run-level stream coordinator
|
|
- `StreamEndpoints` (`src/JobEngine/StellaOps.JobEngine/StellaOps.JobEngine.WebService/Endpoints/StreamEndpoints.cs`) - REST endpoints for SSE subscriptions
|
|
- `StreamOptions` (`src/JobEngine/StellaOps.JobEngine/StellaOps.JobEngine.WebService/Streaming/StreamOptions.cs`) - stream configuration
|
|
- `StreamPayloads` (`src/JobEngine/StellaOps.JobEngine/StellaOps.JobEngine.WebService/Streaming/StreamPayloads.cs`) - typed event payloads
|
|
- **Interfaces**: `IEventPublisher` (`src/JobEngine/StellaOps.JobEngine/StellaOps.JobEngine.Core/Domain/Events/IEventPublisher.cs`)
|
|
- **Source**: Feature matrix scan
|
|
|
|
## E2E Test Plan
|
|
- [ ] Create an `EventEnvelope` with type=job_completed and payload; verify it is hashed via `EventEnvelopeHasher` and the hash is deterministic
|
|
- [ ] Publish an event via `OrchestratorEventPublisher` and verify it reaches the `JobStreamCoordinator`
|
|
- [ ] Subscribe to SSE via `StreamEndpoints` and verify events arrive as formatted SSE messages (data: + newline)
|
|
- [ ] Verify canonical hashing: create two identical events and verify `CanonicalJsonHasher` produces identical hashes
|
|
- [ ] Subscribe to pack-run stream via `PackRunStreamCoordinator` and execute a pack; verify real-time progress events include step index and status
|
|
- [ ] Verify `StreamOptions`: configure heartbeat interval and verify heartbeats arrive at the configured cadence
|
|
- [ ] Publish 100 events rapidly and verify `SseWriter` delivers all of them in order
|
|
- [ ] Verify event envelope correlation: publish events with the same correlation ID and verify they can be filtered by correlation
|