Files
jobboard/pipeline/web/jobs.py
T
WolfandClaude Fable 5.1 3a240e51df Pull pipeline/ from boilerplate a80ad8a: cadence picker, queue badge, label refresh
The schedule cadence is a picker, the add row is behind a button and off
here, a running-jobs chip with Kill and Stop run sits in every header, and
a declared schedule's label is refreshed at startup.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
2026-09-28 16:22:46 +02:00

224 lines
8.9 KiB
Python

"""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:
"""`<desk-jobs>`: the queue on screen, for an app with no UI for it yet.
<script type="module" src="/_jobs/jobs.js"></script>
<desk-jobs></desk-jobs>
<desk-queue href="/jobs"></desk-queue>
`<desk-queue>`, 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)