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>
224 lines
8.9 KiB
Python
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)
|