"""The work queue over HTTP, and the socket that reports on it. Four operations and one socket. Anything the UI can start, it starts by enqueueing a job here; anything it needs to know about running work, it learns from `/ws/jobs`. There is no polling endpoint on purpose — a queue that pushes is both less code and less latency than one that is asked every second. """ from __future__ import annotations import logging import asyncio from pathlib import Path from fastapi import APIRouter, HTTPException, WebSocket, WebSocketDisconnect from fastapi.responses import FileResponse from pipeline import FINAL, JOBS, TASKS from pipeline.models import Job, JobsSnapshot, NoticeEntry, Run from pipeline.web.deps import BroadcasterDep, QueueDep from pipeline.web.schemas import EnqueueBody, JobKind log = logging.getLogger(__name__) router = APIRouter(tags=["jobs"]) #: The element that renders all this, shipped with the package. Served from a #: route rather than mounted as a static directory because a router cannot #: mount one — only an app can — and needing the app to mount something is #: exactly the line of setup this is meant to remove. One file, so one route. STATIC = Path(__file__).resolve().parent / "static" @router.get("/_jobs/jobs.js", include_in_schema=False) def element() -> FileResponse: """``: the queue on screen, for an app with no UI for it yet. ``, the top bar's chip, is defined by the same file, so it needs no route of its own. Cached for an hour rather than forever. It changes when the package is copied into a project and then hardly ever, and an app that wants it fingerprinted can serve the file itself from `STATIC`. """ return FileResponse(STATIC / "jobs.js", media_type="text/javascript", headers={"Cache-Control": "public, max-age=3600"}) @router.get("/api/jobs") def list_jobs(queue: QueueDep) -> JobsSnapshot: """What is running and what recently finished. The same shape the socket pushes, so a client that cannot hold a socket open — a script, a `curl`, another tab — sees exactly what the UI sees. """ return queue.snapshot() @router.get("/api/jobs/kinds") def kinds() -> list[JobKind]: """What can be started. Populated by `@job` and by the app's `TASKS`, so a new handler or a new task appears here without being registered twice. Tasks and jobs in one list because they are one thing to press: a task is what a person means by "tag everything", and that it becomes eight jobs is the pipeline's business rather than the button's. Which is also why a job some task queues is not listed. `tag_batch` without a list of uids is a button that does nothing, and the final job without the batches it reports on is a button that reports nothing. If a task queues it, the task is the thing to offer — worked out from `TASKS` rather than declared, so a new batch kind cannot be forgotten here. Nor is a job that needs a payload, such as `mark_reclassify` without a `source`: a press sends none, so its button could only ever fail. """ made_for_you = {build().kind for build in TASKS.values()} | {FINAL} listed = [ JobKind(kind=spec.kind, label=spec.label, solo=spec.solo) for spec in JOBS.values() if spec.kind not in made_for_you and not spec.needs ] listed += [JobKind(kind=name, label=build().called, solo=True) for name, build in TASKS.items()] return sorted(listed, key=lambda k: k.kind) @router.post("/api/jobs", status_code=202) def enqueue(body: EnqueueBody, queue: QueueDep) -> Job | Run: """Start work: one job, or one task. A kind that names a task starts it rather than being refused — one task, on its own, which is a cascade of one and comes back as that run. Refusing with "use /api/cascades" was the other reading and is worse: every caller would have to know which names had become tasks, when what they asked for is exactly what this does. A name that is both a job and a task is the job. A task of a single batch is that batch, so the two are the same work, and one row says it more plainly than two. 202 rather than 201, because the useful thing has not happened yet — this only promises that it will. A `solo` job that is already underway comes back as itself rather than as an error: the caller asked for that work to be in progress, and it is. """ if body.kind not in JOBS and body.kind in TASKS: task_id = queue.start_task(TASKS[body.kind]()) run = queue.jobs.run(task_id) if run is None: raise HTTPException(409, f"{body.kind!r} would not start") return run spec = JOBS.get(body.kind) missing = [k for k in (spec.needs if spec else ()) if k not in body.payload] if missing: raise HTTPException(422, f"{body.kind!r} needs {', '.join(missing)} " "in its payload") try: job = queue.enqueue(body.kind, body.payload) except KeyError as exc: raise HTTPException(404, str(exc)) from exc if job is None: raise HTTPException(409, "the run it belongs to was killed") return job @router.post("/api/jobs/{job_id}/cancel") def cancel(job_id: int, queue: QueueDep) -> Job: """Stop a job. A queued one stops immediately. A running one stops at its next checkpoint, so this returns while it is still `running` with `cancel_requested` set — the socket reports the actual end. A job that has already finished is returned unchanged rather than treated as an error; the button was simply pressed a moment too late. """ job = queue.cancel(job_id) if job is None: raise HTTPException(404, "no such job") return job @router.post("/api/tasks/{task_id}/cancel") def cancel_task(task_id: int, queue: QueueDep) -> dict[str, int]: """Stop one task: every batch of it. Not the cascade it belongs to, and not the task's final job: that still runs, reports the cancels and calls back, so the cascade knows how this ended — "skip this", rather than "stop". Stopping is the cascade's own button, below. """ return {"ended": queue.cancel_run(task_id)} @router.post("/api/cascades/{cascade_id}/cancel") def cancel_cascade(cascade_id: int, queue: QueueDep) -> dict[str, int]: """Stop a whole cascade: every task of it, and every job of those. The same operation as above — a task and a cascade are one thing to the pipeline — and two endpoints because they are two buttons and mean different things to whoever presses one. An id nobody has heard of, or one already over, ends nothing and says so rather than being an error — the same reading as pressing Kill a moment too late. """ return {"ended": queue.cancel_run(cascade_id)} @router.get("/api/notices") def list_notices(queue: QueueDep) -> list[NoticeEntry]: """Everything the queue has said that nobody has cleared, newest first. What a line on screen was always missing: somewhere to be found again. A notice fades in seconds and is raised, as often as not, while no tab is open to show it. This is the same sentence with its fix and its raw error, how many times it has been said, and when it last was. """ return queue.jobs.notices() @router.delete("/api/notices/{notice_id}") def clear_notice(notice_id: int, queue: QueueDep) -> dict[str, bool]: """Done with this one. Not an error when it has already gone: two tabs, or the fortnight running out between the list and the press.""" return {"cleared": queue.jobs.clear_notice(notice_id)} @router.delete("/api/notices") def clear_notices(queue: QueueDep) -> dict[str, int]: return {"cleared": queue.jobs.clear_notices()} @router.websocket("/ws/jobs") async def jobs_socket(ws: WebSocket, queue: QueueDep, bus: BroadcasterDep) -> None: """Push queue state on connect and on every change. Two message types go out here: `jobs`, the whole queue state, replaced by each new one; and `notice`, a single failure as the log now holds it, its count included. See `pipeline/notices.py` for what a client does with that. The receive loop exists only to notice the client leaving — nothing the browser sends is read. Starting and cancelling go over HTTP, where they get status codes and error bodies; making the socket bidirectional would mean inventing a second request protocol inside it for no gain. """ await ws.accept() snapshot = await asyncio.to_thread(queue.snapshot) await bus.subscribe(ws, {"type": "jobs", **snapshot.model_dump()}) try: while True: await ws.receive_text() except WebSocketDisconnect: pass except Exception: log.debug("jobs socket closed unexpectedly", exc_info=True) finally: bus.unsubscribe(ws)