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>
This commit is contained in:
1 parent
1f436104f3
commit
9d666d0937
76 files changed
+15235
No files matched your search
@@ -0,0 +1,218 @@
|
||||
"""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
|
||||
Reference in new issue
Block a user