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