WebSocket Service (Live Updates)

The WebSocket Service provides real-time communication between the evaluation platform backend and connected clients. It enables the system to push live updates regarding evaluation progress, log streaming, and system status changes without requiring client-side polling.

This service manages persistent connections and broadcasts messages to specific client groups or individual sessions based on evaluation activity.

Architecture and Connection Management

The WebSocket Service utilizes a centralized manager to track active connections and handle the lifecycle of client sessions. It maintains a registry of connected clients to ensure messages reach the intended recipients during evaluation runs.

Connection Lifecycle

The service follows a standard lifecycle for every client connection:

1. The client initiates a connection request to the /ws endpoint.
2. The server accepts the connection and registers the client in the ConnectionManager.
3. The service listens for incoming messages or waits to push server-side events.
4. Upon disconnect, the service removes the client from the registry to prevent memory leaks.

Message Broadcasting and Event Handling

The service categorizes updates into specific event types. When an evaluation task changes state, the EventBroadcaster identifies the relevant clients and pushes the updated data payload.

Event Types and Payloads

The service handles various message types defined in the system schemas. These include:

Implementation Details

The core logic resides in ConnectionManager, which utilizes a dictionary-based registry to map user IDs to their respective WebSocket objects.

Key Classes and Functions

• ConnectionManager.connect(websocket, client_id): Validates and stores a new connection.
• ConnectionManager.disconnect(websocket, client_id): Cleans up the registry.
• ConnectionManager.broadcast(message): Sends a message to all connected clients.
• handle_socket_event(data): Processes incoming messages from the client to trigger server actions.

# Example of the connection handling logic
# Path: src/websocket/manager.py

class ConnectionManager:
    def __init__(self):
        self.active_connections: list[WebSocket] = []

    async def connect(self, websocket: WebSocket):
        await websocket.accept()
        self.active_connections.append(websocket)

    def disconnect(self, websocket: WebSocket):
        self.active_connections.remove(websocket)

Sources: src/websocket/manager.py:22-40, src/websocket/server.py:50-65

Conclusion

The WebSocket Service ensures that the evaluation platform remains responsive and transparent by providing instantaneous feedback to users. By decoupling event generation from message delivery through the ConnectionManager, the system maintains high throughput during intensive evaluation workloads.