# Feature: SSE Streaming

## Description
Server-Sent Events (SSE) endpoint for real-time streaming of flight processing results to clients. Manages SSE connections, handles keepalive, and supports client reconnection with event replay.

## Component APIs Implemented
- `create_sse_stream(flight_id: str) -> SSEStream`

## REST Endpoints
| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/flights/{flightId}/stream` | Open SSE connection |

## SSE Events
| Event Type | Description |
|------------|-------------|
| `frame_processed` | New frame GPS calculated |
| `frame_refined` | Previous frame GPS refined |
| `search_expanded` | Search grid expanded |
| `user_input_needed` | User input required |
| `processing_blocked` | Processing halted |
| `flight_completed` | Flight processing finished |

## External Tools and Services
- **FastAPI**: Web framework with SSE support
- **sse-starlette**: SSE event streaming library
- **asyncio**: Async event handling

## Internal Methods
| Method | Purpose |
|--------|---------|
| `_validate_flight_exists(flight_id)` | Verify flight exists before connecting |
| `_create_sse_response(flight_id)` | Create SSE StreamingResponse |
| `_event_generator(flight_id, client_id)` | Async generator yielding events |
| `_handle_client_disconnect(client_id)` | Cleanup on client disconnect |
| `_send_keepalive()` | Send ping every 30 seconds |
| `_replay_missed_events(last_event_id)` | Replay events since last_event_id |
| `_format_sse_event(event_type, data)` | Format event for SSE protocol |

## Unit Tests
1. **Connection establishment**
   - Valid flight_id → SSE connection opens
   - Non-existent flight_id → returns 404
   - Invalid flight_id format → returns 400

2. **Event formatting**
   - frame_processed event → correct JSON structure
   - All event types → valid SSE format with id, event, data

3. **Keepalive**
   - No events for 30s → ping sent
   - Connection stays alive during idle periods

4. **Client disconnect handling**
   - Client closes connection → resources cleaned up
   - No memory leaks on disconnect

## Integration Tests
1. **Full event flow**
   - Connect to stream → Upload images → Receive all frame_processed events
   - Verify event count matches frames processed

2. **Event ordering**
   - Process 100 frames → events received in order
   - Event IDs are sequential

3. **Reconnection with replay**
   - Connect → Process 50 frames → Disconnect → Reconnect with last_event_id
   - Receive missed events since last_event_id

4. **user_input_needed flow**
   - Process until blocked → Receive user_input_needed event
   - Submit user fix → Receive processing_resumed confirmation

5. **Multiple concurrent clients**
   - 10 clients connect to same flight
   - All receive same events
   - No cross-contamination between flights

6. **Long-running stream**
   - Stream 2000 frames over extended period
   - Connection remains stable
   - All events delivered

7. **Flight completion**
   - Process all frames → Receive flight_completed event
   - Stream closes gracefully

