Skip to content

AI-powered video editor that turns raw footage and a creative brief into a polished ad using an ensemble of AI agents (Google Gemini + FFmpeg)

Python
7.5 KB
Raw Blame
"""WebSocket route for live pipeline progress streaming (US-003).

The single endpoint here — ``/ws/jobs/{job_id}`` — lets the UI subscribe
to a running pipeline job and receive progress updates as they happen.
It is a read-only channel: the client never sends anything back, and the
server closes the connection cleanly as soon as the job reaches a
terminal state.

Protocol
--------

On connect:

1. The server looks the job id up in the :class:`JobRegistry`. If no
   such job exists, the connection is closed immediately with
   WebSocket close code ``4004``.
2. The server accepts the handshake and atomically subscribes to the
   job via :meth:`src.web.jobs.Job.subscribe`. ``subscribe`` returns a
   fresh :class:`asyncio.Queue`, a point-in-time copy of every
   structured progress entry captured so far, and a flag indicating
   whether the job had already reached a terminal state.
3. The server replays every snapshot entry to the client as
   ``{"type": "progress", "line": ..., "timestamp": ...}``.
4. If the job was already terminal, the server enqueues the matching
   terminal status + result (or failure) and the stream-end sentinel
   via :meth:`src.web.jobs.Job.enqueue_terminal`, drains them from the
   queue, and closes the connection.
5. Otherwise the server loops reading from the queue and forwarding
   every event dict as JSON. When the sentinel
   :data:`~src.web.jobs._STREAM_END` arrives (published by the worker
   after it has already emitted the terminal status + result events),
   the loop exits and the connection is closed cleanly.

Threading
---------

The subscriber queues live on the main asyncio event loop. The
pipeline runs in a worker thread via :func:`asyncio.to_thread`, so
writes from the stdout-capture callback are marshalled back through
:meth:`asyncio.AbstractEventLoop.call_soon_threadsafe` by
:meth:`src.web.jobs.Job.publish`. This file never reads or writes
across threads — it only touches the queue on the loop that owns it.
"""

from __future__ import annotations

import logging
from typing import Any

from fastapi import APIRouter, WebSocket, WebSocketDisconnect

from src.web.jobs import _STREAM_END, JobRegistry

logger = logging.getLogger(__name__)

router = APIRouter()


#: WebSocket close code used when the client requests an unknown job id.
#: Codes in the ``4000–4999`` range are application-defined per RFC 6455.
UNKNOWN_JOB_CLOSE_CODE = 4004

#: WebSocket close code used when the handler itself crashes. Matches the
#: RFC 6455 "internal server error" code so browser devtools surface it
#: clearly.
INTERNAL_ERROR_CLOSE_CODE = 1011


def _get_registry(websocket: WebSocket) -> JobRegistry | None:
    """Fetch the :class:`JobRegistry` from app state, if it exists.

    Mirrors the logic in :func:`src.web.routes.jobs.get_registry` but
    for the WebSocket side of FastAPI — we cannot raise
    ``HTTPException`` from a WS handler, so the caller decides how to
    respond (close the socket).
    """
    return getattr(websocket.app.state, "job_registry", None)


def _progress_message(entry: dict[str, str]) -> dict[str, Any]:
    """Normalize a stored progress entry into the wire format.

    Each entry stored on :attr:`src.web.jobs.Job._progress_entries` is
    already in the ``{"line", "timestamp"}`` shape; this helper just
    tacks on the discriminator ``type`` field so the client sees a
    uniform message schema whether the entry came from replay or the
    live queue.
    """
    return {
        "type": "progress",
        "line": entry.get("line", ""),
        "timestamp": entry.get("timestamp", ""),
    }


@router.websocket("/ws/jobs/{job_id}")
async def stream_job(websocket: WebSocket, job_id: str) -> None:
    """Stream replay + live progress for a single pipeline job.

    See the module docstring for the full protocol. The handler is
    intentionally defensive: any unexpected exception closes the socket
    cleanly so a buggy pipeline run can never leak file descriptors or
    leave zombie connections hanging in uvicorn's state.
    """
    registry = _get_registry(websocket)
    if registry is None:
        # Server still starting up or already shutting down. Accept the
        # handshake first so the application-defined close code (4004)
        # survives the trip back to the browser — uvicorn's websockets
        # transport maps any pre-accept ``websocket.close`` to an HTTP
        # 403 response and drops the code, which would hide the
        # "unknown job" signal from real clients.
        await websocket.accept()
        await websocket.close(code=UNKNOWN_JOB_CLOSE_CODE)
        return

    job = registry.get(job_id)
    if job is None:
        # Same rationale as above: accept the handshake so the 4004
        # close code actually reaches the client instead of being
        # collapsed into a generic 403 by the uvicorn websockets layer.
        await websocket.accept()
        await websocket.close(code=UNKNOWN_JOB_CLOSE_CODE)
        return

    await websocket.accept()

    # ``subscribe`` atomically snapshots the replay buffer AND registers
    # the new queue under the job's lock, so ``_record_progress`` cannot
    # slip a new entry between those two steps. Any event that lands
    # after ``subscribe`` returns is guaranteed to flow through the
    # queue; any event visible in the replay is guaranteed NOT to have
    # been put on the queue (because the job's publish fan-out snapshots
    # the subscriber list while holding the same lock).
    queue, replay, terminal_at_subscribe = job.subscribe()

    try:
        # Replay every progress entry captured so far with its original
        # timestamp. The client sees these as a burst of ``progress``
        # messages before the live feed begins.
        for entry in replay:
            await websocket.send_json(_progress_message(entry))

        # If the job had already terminated before our subscribe,
        # ``finalize`` had already run, which means the live queue will
        # never receive any future events. Synthesize the terminal
        # messages from the job's stored state so the client sees the
        # same wire format it would for a live job. ``enqueue_terminal``
        # also pushes the stream-end sentinel so the drain loop below
        # exits cleanly.
        if terminal_at_subscribe:
            job.enqueue_terminal(queue)

        # Drain events until the worker (or ``enqueue_terminal``) pushes
        # the stream-end sentinel. Everything else on the queue is a
        # dict matching one of the wire formats and can be forwarded
        # straight through.
        while True:
            event = await queue.get()
            if event is _STREAM_END:
                break
            await websocket.send_json(event)

    except WebSocketDisconnect:
        # Client hung up — nothing to do beyond the ``finally`` block's
        # subscriber unregister. Do not try to send a close frame.
        return
    except Exception:  # noqa: BLE001 - log and close, never crash uvicorn
        logger.exception("WebSocket stream for job %s crashed", job_id)
        try:
            await websocket.close(code=INTERNAL_ERROR_CLOSE_CODE)
        except Exception:  # pragma: no cover - best effort
            pass
        return
    finally:
        job.remove_subscriber(queue)

    # Clean close after the live loop (or replay of a terminal job)
    # finished normally. The try/except around ``close`` handles the
    # (rare) case where the client already shut down in parallel.
    try:
        await websocket.close()
    except Exception:  # pragma: no cover - best effort
        pass