Files
jobboard/pipeline/web/schedules.py
T
WolfandClaude Opus 5.5 9d666d0937 Bring in pipeline, auth, deploy and docs from the boilerplate
roledesk is built on the boilerplate from here on: pipeline 2.0 (queue and
scheduler), auth (one password, sessions, passkeys), the deploy kit and its
docs, plus the coupling and packaging tests. Downstream copies, unedited.

Refreshed from boilerplate/d56949f7d0f6c0bfe5745478e09007bfad67ae87

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-23 12:29:16 +02:00

219 lines
8.9 KiB
Python

"""Schedules over HTTP: list, add, edit, delete, run now.
Five routes and no socket of its own. Changes go out on `/ws/jobs` as a
`schedules` message — the same socket the job list already holds open, because
a second one would be a second reconnect loop to get subtly wrong, for a list
that changes a few times a day.
Every refusal here is a sentence a person can act on, which is the whole
reason these are not four lines of `queue.jobs.*` behind a generic validator:
an unregistered kind 404, and it names what is registered
a payload missing keys 422, and it names the keys
a cadence it cannot read 422, and it lists all five accepted wordings
They arrive as `{"detail": "<sentence>"}`, which is FastAPI's own shape, so an
app's `api()` helper turns any of them into one toast carrying the server's
words rather than inventing its own — see `app/static/app.js` in the starter.
Validating the kind and the payload *here*, rather than letting the job fail at
06:00, is the point of the endpoint existing at all. A schedule is the one way
of starting work where nobody is watching when it runs.
"""
from __future__ import annotations
import logging
from datetime import UTC, datetime
from fastapi import APIRouter, HTTPException
from fastapi.responses import FileResponse
from pipeline import JOBS, JobQueue
from pipeline.models import Job, Schedule
from pipeline.schedule import Cadence
from pipeline.web.deps import QueueDep
from pipeline.web.jobs import STATIC
from pipeline.web.schemas import NewSchedule, ScheduleEdit, ScheduleRow
log = logging.getLogger(__name__)
router = APIRouter(tags=["schedules"])
@router.get("/_jobs/schedules.js", include_in_schema=False)
def element() -> FileResponse:
"""`<desk-schedules>`: the schedule table on screen.
<script type="module" src="/_jobs/schedules.js"></script>
<desk-schedules></desk-schedules>
Served and cached exactly as `/_jobs/jobs.js` is, and it reads the same
`--desk-jobs-*` custom properties, so an app that themed one has themed
both.
"""
return FileResponse(STATIC / "schedules.js", media_type="text/javascript",
headers={"Cache-Control": "public, max-age=3600"})
def listed(queue: JobQueue) -> list[ScheduleRow]:
"""The list as it goes out, over HTTP and over the socket alike.
One function for both, so the two cannot drift: a client that reads the
REST list once and then follows the socket must not be handed two shapes of
the same thing.
"""
return [served(row) for row in queue.jobs.schedules()]
def served(row: Schedule) -> ScheduleRow:
"""One schedule, plus the one thing the table cannot know: whether anything
is still registered to run it. Worked out here rather than stored, because
it is a fact about the code that is loaded and not about the row."""
return ScheduleRow(**row.model_dump(), unknown=row.kind not in JOBS)
def _check(kind: str, payload: dict) -> None:
"""Refuse a kind nothing runs, or a payload its handler cannot take."""
spec = JOBS.get(kind)
if spec is None:
raise HTTPException(404, f"no job is registered as {kind!r}. Registered: "
f"{', '.join(sorted(JOBS)) or 'none'}.")
missing = [k for k in spec.needs if k not in payload]
if missing:
raise HTTPException(422, f"{kind!r} cannot run without "
f"{', '.join(missing)} in its payload.")
def _cadence(text: str) -> Cadence:
"""Parse, or 422 with the accepted wordings.
`Cadence` already writes that sentence — see `pipeline/schedule.py` — so it
is passed through rather than reworded here. One description of the grammar
in the codebase, and it is next to the parser that enforces it.
"""
try:
return Cadence.parse(text)
except ValueError as bad:
raise HTTPException(422, str(bad)) from bad
def _free_name(queue: JobQueue, wanted: str) -> str:
"""A name nothing else has: `tick`, then `tick 2`, then `tick 3`.
Only for a request that gave none. A name somebody typed is refused rather
than quietly altered, because the name is the handle, and being handed a
different one is how you edit the wrong row a month later.
"""
taken = {row.name for row in queue.jobs.schedules()}
if wanted not in taken:
return wanted
n = 2
while f"{wanted} {n}" in taken:
n += 1
return f"{wanted} {n}"
@router.get("/api/schedules")
def list_schedules(queue: QueueDep) -> list[ScheduleRow]:
"""Every schedule, by name, with how its last job ended.
The same list the socket pushes, so a client that cannot hold one open — a
script, a `curl`, a second tab — sees exactly what the element sees.
"""
return listed(queue)
@router.post("/api/schedules", status_code=201)
def add_schedule(body: NewSchedule, queue: QueueDep) -> ScheduleRow:
"""Add one. 201, because unlike a job this really does now exist.
`name` is optional and defaults to the kind, made unique by counting. A
name that was given and is taken is a conflict rather than a second row:
two rows answering to one name is exactly the ambiguity the handle exists
to prevent.
`next_run` is worked out here, from now, so a schedule added at 09:00
saying `every 6h` is next at 15:00 rather than at some moment the table
invented.
"""
_check(body.kind, body.payload)
cadence = _cadence(body.cadence)
name = body.name.strip() or _free_name(queue, body.kind)
row = queue.jobs.add_schedule(
name, body.kind, str(cadence), payload=body.payload, label=body.label,
enabled=body.enabled,
next_run=cadence.next_after(datetime.now(UTC), queue.zone).isoformat(),
only_if_new=True)
if row is None:
raise HTTPException(409, f"there is already a schedule called {name!r}.")
queue.notify_schedules()
return served(row)
@router.patch("/api/schedules/{schedule_id}")
def edit_schedule(schedule_id: int, body: ScheduleEdit, queue: QueueDep) -> ScheduleRow:
"""Change part of one. Only what was sent is touched.
A new cadence moves `next_run` with it, because the alternative is a row
that says `every 15m` and does not run for six hours: the old time is an
answer to a question nobody is asking any more. Switching a row back on
does the same. It would come right on its own — a firing advances to the
next slot from now and never walks through the missed ones — but the time
on screen would be a lie until it did.
"""
row = queue.jobs.schedule(schedule_id)
if row is None:
raise HTTPException(404, f"there is no schedule {schedule_id}.")
# Unset and null are one thing here: every field is optional and every
# column is NOT NULL, so `{"cadence": null}` can only be a client leaving
# a key in rather than a request to blank the column.
fields = {k: v for k, v in body.model_dump(exclude_unset=True).items()
if v is not None}
if "kind" in fields or "payload" in fields:
_check(fields.get("kind", row.kind), fields.get("payload", row.payload))
now = datetime.now(UTC)
if "cadence" in fields:
cadence = _cadence(fields["cadence"])
fields["cadence"] = str(cadence)
fields["next_run"] = cadence.next_after(now, queue.zone).isoformat()
elif fields.get("enabled") and not row.enabled:
fields["next_run"] = _cadence(row.cadence).next_after(now, queue.zone).isoformat()
changed = queue.jobs.update_schedule(schedule_id, **fields)
queue.notify_schedules()
return served(changed or row)
@router.delete("/api/schedules/{schedule_id}")
def delete_schedule(schedule_id: int, queue: QueueDep) -> dict[str, bool]:
"""Forget one. Not an error when it has already gone — two tabs.
A declared default deleted here comes back on the next start, which is
what declaring one means. Switching it off is how to be rid of it for
good: that edit is the row's, and reconciliation never overwrites one.
"""
deleted = queue.jobs.delete_schedule(schedule_id)
if deleted:
queue.notify_schedules()
return {"deleted": deleted}
@router.post("/api/schedules/{schedule_id}/run", status_code=202)
def run_now(schedule_id: int, queue: QueueDep) -> Job:
"""Queue this schedule's job now, without moving when it is next due.
202 like `/api/jobs`, and for the same reason: what comes back is the
promise, not the outcome. A `solo` kind already under way comes back as
that job rather than as an error — the caller asked for the work to be in
progress, and it is.
"""
row = queue.jobs.schedule(schedule_id)
if row is None:
raise HTTPException(404, f"there is no schedule {schedule_id}.")
_check(row.kind, row.payload)
job = queue.run_schedule(schedule_id)
if job is None:
raise HTTPException(409, f"{row.kind!r} was not queued: the run it "
"would have belonged to was killed.")
return job