Aniworld/FRONTEND_INTEGRATION.md

Frontend Integration Changes

Overview

This document details the changes made to integrate the existing frontend JavaScript with the new FastAPI backend and native WebSocket implementation.

Key Changes

1. WebSocket Migration (Socket.IO → Native WebSocket)

Files Created:

• src/server/web/static/js/websocket_client.js - Native WebSocket wrapper with Socket.IO-compatible interface

Files Modified:

• src/server/web/templates/index.html - Replace Socket.IO CDN with websocket_client.js
• src/server/web/templates/queue.html - Replace Socket.IO CDN with websocket_client.js

Migration Details:

• Created WebSocketClient class that provides Socket.IO-style .on() and .emit() methods
• Automatic reconnection with exponential backoff
• Room-based subscriptions (join/leave rooms for topic filtering)
• Message queueing during disconnection
• Native WebSocket URL: ws://host:port/ws/connect (or wss:// for HTTPS)

2. WebSocket Message Format Changes

Old Format (Socket.IO custom events):

socket.on('download_progress', (data) => { ... });
// data was sent directly

New Format (Structured messages):

{
    "type": "download_progress",
    "timestamp": "2025-10-17T12:34:56.789Z",
    "data": {
        // Message payload
    }
}

Event Mapping:

Old Socket.IO Event	New WebSocket Type	Room	Notes
scan_progress	scan_progress	scan_progress	Scan updates
scan_completed	scan_complete	scan_progress	Scan finished
scan_error	scan_failed	scan_progress	Scan error
download_progress	download_progress	download_progress	Real-time download updates
download_completed	download_complete	downloads	Single download finished
download_error	download_failed	downloads	Download failed
download_queue_update	queue_status	downloads	Queue state changes
queue_started	queue_started	downloads	Queue processing started
queue_stopped	queue_stopped	downloads	Queue processing stopped
queue_paused	queue_paused	downloads	Queue paused
queue_resumed	queue_resumed	downloads	Queue resumed

3. API Endpoint Changes

Authentication Endpoints:

• ✅ /api/auth/status - Check auth status (GET)
• ✅ /api/auth/login - Login (POST)
• ✅ /api/auth/logout - Logout (POST)
• ✅ /api/auth/setup - Initial setup (POST)

Anime Endpoints:

• ✅ /api/v1/anime - List anime with missing episodes (GET)
• ✅ /api/v1/anime/rescan - Trigger rescan (POST)
• ✅ /api/v1/anime/search - Search for anime (POST)
• ✅ /api/v1/anime/{anime_id} - Get anime details (GET)

Download Queue Endpoints:

• ✅ /api/queue/status - Get queue status (GET)
• ✅ /api/queue/add - Add to queue (POST)
• ✅ /api/queue/{item_id} - Remove single item (DELETE)
• ✅ /api/queue/ - Remove multiple items (DELETE)
• ✅ /api/queue/start - Start queue (POST)
• ✅ /api/queue/stop - Stop queue (POST)
• ✅ /api/queue/pause - Pause queue (POST)
• ✅ /api/queue/resume - Resume queue (POST)
• ✅ /api/queue/reorder - Reorder queue (POST)
• ✅ /api/queue/completed - Clear completed (DELETE)
• ✅ /api/queue/retry - Retry failed (POST)

WebSocket Endpoint:

• ✅ /ws/connect - WebSocket connection (WebSocket)
• ✅ /ws/status - WebSocket status (GET)

4. Required JavaScript Updates

app.js Changes Needed:

1. WebSocket Initialization - Add room subscriptions:

initSocket() {
    this.socket = io();

    // Subscribe to relevant rooms after connection
    this.socket.on('connected', () => {
        this.socket.join('scan_progress');
        this.socket.join('download_progress');
        this.socket.join('downloads');
        this.isConnected = true;
        // ... rest of connect handler
    });

    // ... rest of event handlers
}

2. Event Handler Updates - Map new message types:

• scan_completed → scan_complete
• scan_error → scan_failed
• Legacy events that are no longer sent need to be handled differently or removed

3. API Call Updates - Already correct:

• /api/v1/anime for anime list ✅
• /api/auth/* for authentication ✅

queue.js Changes Needed:

1. WebSocket Initialization - Add room subscriptions:

initSocket() {
    this.socket = io();

    this.socket.on('connected', () => {
        this.socket.join('downloads');
        this.socket.join('download_progress');
        // ... rest of connect handler
    });

    // ... rest of event handlers
}

2. API Calls - Already mostly correct:

• /api/queue/status ✅
• /api/queue/* operations ✅

3. Event Handlers - Map to new types:

• queue_updated → queue_status
• download_progress_update → download_progress

5. Authentication Flow

Current Implementation:

• JWT tokens stored in localStorage (via auth service)
• Tokens included in Authorization header for API requests
• WebSocket connections can optionally authenticate (user_id in session)

JavaScript Implementation Needed: Add helper for authenticated requests:

async makeAuthenticatedRequest(url, options = {}) {
    const token = localStorage.getItem('auth_token');

    if (!token) {
        window.location.href = '/login';
        return null;
    }

    const headers = {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${token}`,
        ...options.headers
    };

    const response = await fetch(url, { ...options, headers });

    if (response.status === 401) {
        // Token expired or invalid
        localStorage.removeItem('auth_token');
        window.location.href = '/login';
        return null;
    }

    return response;
}

6. Backend Router Registration

Fixed in fastapi_app.py:

• ✅ Added anime_router import
• ✅ Registered app.include_router(anime_router)

All routers now properly registered:

• health_router
• page_router
• auth_router
• anime_router ⭐ (newly added)
• download_router
• websocket_router

Implementation Status

✅ Completed

1. Created native WebSocket client wrapper
2. Updated HTML templates to use new WebSocket client
3. Registered anime router in FastAPI app
4. Documented API endpoint mappings
5. Documented WebSocket message format changes

🔄 In Progress

1. Update app.js WebSocket initialization and room subscriptions
2. Update app.js event handlers for new message types
3. Update queue.js WebSocket initialization and room subscriptions
4. Update queue.js event handlers for new message types

⏳ Pending

1. Add authentication token handling to all API requests
2. Test complete workflow (auth → scan → download)
3. Update other JavaScript modules if they use WebSocket/API
4. Integration tests for frontend-backend communication
5. Update infrastructure.md documentation

Testing Plan

1. Authentication Flow:

   • Test setup page → creates master password
   • Test login page → authenticates with master password
   • Test logout → clears session
   • Test protected pages redirect to login

2. Anime Management:

   • Test loading anime list
   • Test rescan functionality with progress updates
   • Test search functionality

3. Download Queue:

   • Test adding items to queue
   • Test queue operations (start, stop, pause, resume)
   • Test progress updates via WebSocket
   • Test retry and clear operations

4. WebSocket Communication:

   • Test connection/reconnection
   • Test room subscriptions
   • Test message routing to correct handlers
   • Test disconnect handling

Known Issues & Limitations

1. Legacy Events: Some Socket.IO events in app.js don't have backend equivalents:

   • scheduled_rescan_* events
   • auto_download_* events
   • download_episode_update event
   • download_series_completed event

   Solution: Either remove these handlers or implement corresponding backend events

2. Configuration Endpoints: Many config-related API calls in app.js don't have backend implementations:

   • Scheduler configuration
   • Logging configuration
   • Advanced configuration
   • Config backups

   Solution: Implement these endpoints or remove the UI features

3. Process Status Monitoring: checkProcessLocks() method may not work with new backend

   Solution: Implement equivalent status endpoint or remove feature

Migration Guide for Developers

Adding New WebSocket Events

1. Define message type in src/server/models/websocket.py:

class WebSocketMessageType(str, Enum):
    MY_NEW_EVENT = "my_new_event"

2. Broadcast from service:

await ws_service.broadcast_to_room(
    {"type": "my_new_event", "data": {...}},
    "my_room"
)

3. Subscribe and handle in JavaScript:

this.socket.join("my_room");
this.socket.on("my_new_event", (data) => {
    // Handle event
});

Adding New API Endpoints

1. Define Pydantic models in src/server/models/
2. Create endpoint in appropriate router file in src/server/api/
3. Add endpoint to this documentation
4. Update JavaScript to call new endpoint

References

• FastAPI Application: src/server/fastapi_app.py
• WebSocket Service: src/server/services/websocket_service.py
• WebSocket Models: src/server/models/websocket.py
• Download Service: src/server/services/download_service.py
• Anime Service: src/server/services/anime_service.py
• Progress Service: src/server/services/progress_service.py
• Infrastructure Doc: infrastructure.md