Task 4.4: Update WebSocket API Endpoints to use key identifier
- Updated src/server/api/websocket.py docstrings to document key as primary series identifier - Updated src/server/models/websocket.py with detailed docstrings explaining key and folder fields in message payloads - Updated src/server/services/websocket_service.py broadcast method docstrings to document key field usage - Added WebSocket message example with key in infrastructure.md - All 83 WebSocket tests pass - Task 4.4 marked as complete in instructions.md
This commit is contained in:
@@ -2,6 +2,14 @@
|
||||
|
||||
This module provides WebSocket endpoints for clients to connect and receive
|
||||
real-time updates about downloads, queue status, and system events.
|
||||
|
||||
Series Identifier Convention:
|
||||
- `key`: Primary identifier for series (provider-assigned, URL-safe)
|
||||
e.g., "attack-on-titan"
|
||||
- `folder`: Display metadata only (e.g., "Attack on Titan (2013)")
|
||||
|
||||
All series-related WebSocket events include `key` as the primary identifier
|
||||
in their data payload. The `folder` field is optional for display purposes.
|
||||
"""
|
||||
from __future__ import annotations
|
||||
|
||||
@@ -58,19 +66,25 @@ async def websocket_endpoint(
|
||||
}
|
||||
```
|
||||
|
||||
Server message format:
|
||||
Server message format (series-related events include 'key' identifier):
|
||||
```json
|
||||
{
|
||||
"type": "download_progress",
|
||||
"timestamp": "2025-10-17T10:30:00.000Z",
|
||||
"data": {
|
||||
"download_id": "abc123",
|
||||
"key": "attack-on-titan",
|
||||
"folder": "Attack on Titan (2013)",
|
||||
"percent": 45.2,
|
||||
"speed_mbps": 2.5,
|
||||
"eta_seconds": 180
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Note:
|
||||
- `key` is the primary series identifier (provider-assigned, URL-safe)
|
||||
- `folder` is optional display metadata
|
||||
"""
|
||||
connection_id = str(uuid.uuid4())
|
||||
user_id: Optional[str] = None
|
||||
|
||||
@@ -3,6 +3,15 @@
|
||||
This module defines message models for WebSocket communication between
|
||||
the server and clients. Models ensure type safety and provide validation
|
||||
for real-time updates.
|
||||
|
||||
Series Identifier Convention:
|
||||
- `key`: Primary identifier for series (provider-assigned, URL-safe)
|
||||
e.g., "attack-on-titan"
|
||||
- `folder`: Display metadata only (e.g., "Attack on Titan (2013)")
|
||||
|
||||
All series-related WebSocket events should include `key` as the primary
|
||||
identifier in their data payload. The `folder` field is optional and
|
||||
used for display purposes only.
|
||||
"""
|
||||
from __future__ import annotations
|
||||
|
||||
@@ -65,7 +74,16 @@ class WebSocketMessage(BaseModel):
|
||||
|
||||
|
||||
class DownloadProgressMessage(BaseModel):
|
||||
"""Download progress update message."""
|
||||
"""Download progress update message.
|
||||
|
||||
Data payload should include:
|
||||
- download_id: Unique download identifier
|
||||
- key: Series identifier (primary, e.g., 'attack-on-titan')
|
||||
- folder: Series folder name (optional, display only)
|
||||
- percent: Download progress percentage
|
||||
- speed_mbps: Download speed
|
||||
- eta_seconds: Estimated time remaining
|
||||
"""
|
||||
|
||||
type: WebSocketMessageType = Field(
|
||||
default=WebSocketMessageType.DOWNLOAD_PROGRESS,
|
||||
@@ -77,12 +95,22 @@ class DownloadProgressMessage(BaseModel):
|
||||
)
|
||||
data: Dict[str, Any] = Field(
|
||||
...,
|
||||
description="Progress data including download_id, percent, speed, eta",
|
||||
description=(
|
||||
"Progress data including download_id, key (series identifier), "
|
||||
"folder (display), percent, speed_mbps, eta_seconds"
|
||||
),
|
||||
)
|
||||
|
||||
|
||||
class DownloadCompleteMessage(BaseModel):
|
||||
"""Download completion message."""
|
||||
"""Download completion message.
|
||||
|
||||
Data payload should include:
|
||||
- download_id: Unique download identifier
|
||||
- key: Series identifier (primary, e.g., 'attack-on-titan')
|
||||
- folder: Series folder name (optional, display only)
|
||||
- file_path: Path to downloaded file
|
||||
"""
|
||||
|
||||
type: WebSocketMessageType = Field(
|
||||
default=WebSocketMessageType.DOWNLOAD_COMPLETE,
|
||||
@@ -93,12 +121,23 @@ class DownloadCompleteMessage(BaseModel):
|
||||
description="ISO 8601 timestamp",
|
||||
)
|
||||
data: Dict[str, Any] = Field(
|
||||
..., description="Completion data including download_id, file_path"
|
||||
...,
|
||||
description=(
|
||||
"Completion data including download_id, key (series identifier), "
|
||||
"folder (display), file_path"
|
||||
),
|
||||
)
|
||||
|
||||
|
||||
class DownloadFailedMessage(BaseModel):
|
||||
"""Download failure message."""
|
||||
"""Download failure message.
|
||||
|
||||
Data payload should include:
|
||||
- download_id: Unique download identifier
|
||||
- key: Series identifier (primary, e.g., 'attack-on-titan')
|
||||
- folder: Series folder name (optional, display only)
|
||||
- error_message: Description of the failure
|
||||
"""
|
||||
|
||||
type: WebSocketMessageType = Field(
|
||||
default=WebSocketMessageType.DOWNLOAD_FAILED,
|
||||
@@ -109,7 +148,11 @@ class DownloadFailedMessage(BaseModel):
|
||||
description="ISO 8601 timestamp",
|
||||
)
|
||||
data: Dict[str, Any] = Field(
|
||||
..., description="Error data including download_id, error_message"
|
||||
...,
|
||||
description=(
|
||||
"Error data including download_id, key (series identifier), "
|
||||
"folder (display), error_message"
|
||||
),
|
||||
)
|
||||
|
||||
|
||||
|
||||
@@ -3,6 +3,15 @@
|
||||
This module provides a comprehensive WebSocket manager for handling
|
||||
real-time updates, connection management, room-based messaging, and
|
||||
broadcast functionality for the Aniworld web application.
|
||||
|
||||
Series Identifier Convention:
|
||||
- `key`: Primary identifier for series (provider-assigned, URL-safe)
|
||||
e.g., "attack-on-titan"
|
||||
- `folder`: Display metadata only (e.g., "Attack on Titan (2013)")
|
||||
|
||||
All broadcast methods that handle series-related data should include `key`
|
||||
as the primary identifier in the message payload. The `folder` field is
|
||||
optional and used for display purposes only.
|
||||
"""
|
||||
from __future__ import annotations
|
||||
|
||||
@@ -363,6 +372,16 @@ class WebSocketService:
|
||||
Args:
|
||||
download_id: The download item identifier
|
||||
progress_data: Progress information (percent, speed, etc.)
|
||||
Should include 'key' (series identifier) and
|
||||
optionally 'folder' (display name)
|
||||
|
||||
Note:
|
||||
The progress_data should include:
|
||||
- key: Series identifier (primary, e.g., 'attack-on-titan')
|
||||
- folder: Series folder name (optional, display only)
|
||||
- percent: Download progress percentage
|
||||
- speed_mbps: Download speed
|
||||
- eta_seconds: Estimated time remaining
|
||||
"""
|
||||
message = {
|
||||
"type": "download_progress",
|
||||
@@ -382,6 +401,14 @@ class WebSocketService:
|
||||
Args:
|
||||
download_id: The download item identifier
|
||||
result_data: Download result information
|
||||
Should include 'key' (series identifier) and
|
||||
optionally 'folder' (display name)
|
||||
|
||||
Note:
|
||||
The result_data should include:
|
||||
- key: Series identifier (primary, e.g., 'attack-on-titan')
|
||||
- folder: Series folder name (optional, display only)
|
||||
- file_path: Path to the downloaded file
|
||||
"""
|
||||
message = {
|
||||
"type": "download_complete",
|
||||
@@ -401,6 +428,14 @@ class WebSocketService:
|
||||
Args:
|
||||
download_id: The download item identifier
|
||||
error_data: Error information
|
||||
Should include 'key' (series identifier) and
|
||||
optionally 'folder' (display name)
|
||||
|
||||
Note:
|
||||
The error_data should include:
|
||||
- key: Series identifier (primary, e.g., 'attack-on-titan')
|
||||
- folder: Series folder name (optional, display only)
|
||||
- error_message: Description of the failure
|
||||
"""
|
||||
message = {
|
||||
"type": "download_failed",
|
||||
@@ -412,7 +447,9 @@ class WebSocketService:
|
||||
}
|
||||
await self._manager.broadcast_to_room(message, "downloads")
|
||||
|
||||
async def broadcast_queue_status(self, status_data: Dict[str, Any]) -> None:
|
||||
async def broadcast_queue_status(
|
||||
self, status_data: Dict[str, Any]
|
||||
) -> None:
|
||||
"""Broadcast queue status update to all clients.
|
||||
|
||||
Args:
|
||||
|
||||
Reference in New Issue
Block a user