"""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": ""}`, 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: """``: the schedule table on screen. 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