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,59 @@
|
||||
"""The parts of a web app that are the pipeline's, not the application's.
|
||||
|
||||
from pipeline.web import connect
|
||||
queue = connect(app, Jobs("app.db"), config, store)
|
||||
|
||||
An app of this shape has a queue, and therefore has the same endpoints and the
|
||||
same socket over it: list, kinds, enqueue, cancel, and `/ws/jobs`. None of that
|
||||
knows what the work is *for*, so it is here rather than copied into each app —
|
||||
and a socket's reconnect and fan-out behaviour is exactly the sort of thing a
|
||||
second copy gets subtly wrong.
|
||||
|
||||
app.py `connect`: all of the below wired into a FastAPI app, and
|
||||
the worker started and stopped with it, in one call
|
||||
broadcaster.py one message out to every connected socket
|
||||
jobs.py the queue over HTTP, the socket that reports on it, and
|
||||
the one route that serves the element below
|
||||
schedules.py schedules over HTTP: list, add, edit, delete, run now,
|
||||
with the readable refusals a thing that runs while nobody
|
||||
is watching has to have
|
||||
deps.py how those routes reach the queue and the bus
|
||||
schemas.py the request bodies they take
|
||||
static/jobs.js `<desk-jobs>`: the queue on screen. Two lines in a
|
||||
template and a new app has a job list with progress and a
|
||||
Kill button, before it has written any UI of its own
|
||||
static/schedules.js
|
||||
`<desk-schedules>`: the same two lines for the schedule
|
||||
table, themed from the same custom properties
|
||||
|
||||
<script type="module" src="/_jobs/jobs.js"></script>
|
||||
<desk-jobs></desk-jobs>
|
||||
|
||||
The element is the one thing here with an opinion about how something looks,
|
||||
and it is deliberate: this is the part nobody wants to write twice. It keeps
|
||||
to a shadow root and themes from custom properties, so an app overrides it
|
||||
without forking it, and it says nothing about *failures* — it raises an event
|
||||
and leaves the wording to the app, which is the same split `notices.py` makes
|
||||
on the server. newsdesk does not use it: it had a richer strip of its own
|
||||
before this existed, which is what an app is expected to grow into.
|
||||
|
||||
What an app still owns: its own factory, its own store and config
|
||||
dependencies, its own routers, its own page.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from pipeline.web.app import connect
|
||||
from pipeline.web.broadcaster import Broadcaster
|
||||
from pipeline.web.deps import BroadcasterDep, QueueDep, get_broadcaster, get_queue
|
||||
from pipeline.web.jobs import STATIC, router as jobs_router
|
||||
from pipeline.web.schedules import router as schedules_router, served
|
||||
from pipeline.web.schemas import (
|
||||
EnqueueBody, JobKind, NewSchedule, ScheduleEdit, ScheduleRow,
|
||||
)
|
||||
|
||||
__all__ = ["STATIC", "Broadcaster", "BroadcasterDep", "EnqueueBody",
|
||||
"JobKind", "NewSchedule", "QueueDep", "ScheduleEdit", "ScheduleRow",
|
||||
"connect", "get_broadcaster", "get_queue", "jobs_router",
|
||||
"schedules_router", "served",
|
||||
]
|
||||
@@ -0,0 +1,86 @@
|
||||
"""The whole web face of the queue, in one call.
|
||||
|
||||
app = FastAPI()
|
||||
queue = connect(app, Jobs("app.db"), config, store)
|
||||
|
||||
That is the HTTP routes, the `/ws/jobs` socket, the `<desk-jobs>` and
|
||||
`<desk-schedules>` elements, the schedule endpoints, the broadcaster that feeds
|
||||
the socket, and the worker starting and stopping with the app. Before this
|
||||
every app wrote the same thirty lines of glue — three callbacks, a lifespan,
|
||||
two `app.state` slots, two `include_router`s — which is the part of "a day of
|
||||
pipeline per project" that was still left.
|
||||
|
||||
Keyword arguments go to `JobQueue`: `workers=`, `bootstrap=`, `retain=`, `tz=`
|
||||
and the rest. `tz` is the one a deployed app has to pass: a server runs on UTC
|
||||
and `daily at 06:00` means 06:00 where the person reading it lives. The queue
|
||||
is returned for the app's own routes and commands to enqueue on; it is also on
|
||||
`app.state.queue`, which is where `QueueDep` finds it.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from collections.abc import AsyncIterator
|
||||
from contextlib import asynccontextmanager
|
||||
from typing import Any
|
||||
|
||||
from fastapi import FastAPI
|
||||
|
||||
from pipeline import JobQueue, Jobs, JobsSnapshot, Notice, Schedule
|
||||
from pipeline.web.broadcaster import Broadcaster
|
||||
from pipeline.web.jobs import router
|
||||
from pipeline.web.schedules import router as schedules_router, served
|
||||
|
||||
|
||||
def connect(app: FastAPI, jobs: Jobs, config: Any, store: Any,
|
||||
**queue_options: Any) -> JobQueue:
|
||||
"""Give `app` a queue: routes, socket, element, and a worker in its lifespan.
|
||||
|
||||
The lifespan is wrapped rather than replaced, so an app's own lifespan —
|
||||
passed to `FastAPI(lifespan=...)` before or after this — still runs, inside
|
||||
the queue's: the worker is up before the app's startup code and still up
|
||||
through its shutdown code, so either may enqueue.
|
||||
"""
|
||||
bus = Broadcaster()
|
||||
|
||||
async def publish(snapshot: JobsSnapshot) -> None:
|
||||
"""State: the whole queue, replaced wholesale by the next one."""
|
||||
await bus.broadcast({"type": "jobs", **snapshot.model_dump()})
|
||||
|
||||
async def announce(notice: Notice) -> None:
|
||||
"""An event: one failure, out to every open tab. The row it was
|
||||
written to, so a tab can tell news from a repeat — see `NoticeEntry`."""
|
||||
await bus.broadcast({"type": "notice", **notice.model_dump()})
|
||||
|
||||
async def scheduled(rows: list[Schedule]) -> None:
|
||||
"""State, on its own clock: the schedule list, whenever one changes.
|
||||
|
||||
Separate from `jobs` rather than folded into it because the two change
|
||||
at completely different rates — a running job pushes four times a
|
||||
second and a schedule a few times a day — and because a client that
|
||||
only draws the table should not have to ignore everything else.
|
||||
"""
|
||||
await bus.broadcast({"type": "schedules",
|
||||
"schedules": [served(row).model_dump() for row in rows]})
|
||||
|
||||
queue = JobQueue(jobs, config, store, listener=publish, on_notice=announce,
|
||||
on_schedules=scheduled, **queue_options)
|
||||
app.state.queue = queue
|
||||
app.state.bus = bus
|
||||
app.include_router(router)
|
||||
app.include_router(schedules_router)
|
||||
|
||||
inner = app.router.lifespan_context
|
||||
|
||||
@asynccontextmanager
|
||||
async def lifespan(this: FastAPI) -> AsyncIterator[Any]:
|
||||
# The worker needs a running event loop, which exists here and not
|
||||
# where `connect` was called.
|
||||
await queue.start()
|
||||
try:
|
||||
async with inner(this) as state:
|
||||
yield state
|
||||
finally:
|
||||
await queue.stop()
|
||||
|
||||
app.router.lifespan_context = lifespan
|
||||
return queue
|
||||
@@ -0,0 +1,56 @@
|
||||
"""One message out to every connected socket.
|
||||
|
||||
Deliberately knows nothing about jobs. It holds sockets, sends dicts, and drops
|
||||
the ones that have gone away — which is the whole of what a fan-out is, and is
|
||||
the reason the next thing that wants to push (a tag landing, a transcript
|
||||
finishing, another reader in another tab) can use this rather than grow a
|
||||
second copy of it.
|
||||
|
||||
A dead socket is discovered by writing to it, not by asking: a browser tab that
|
||||
was closed, slept or navigated away leaves a connection that looks open until
|
||||
the send fails. So every failure is a removal, and `broadcast` never raises —
|
||||
one stale subscriber must not cost the others their update.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import logging
|
||||
import asyncio
|
||||
from typing import Any
|
||||
|
||||
from fastapi import WebSocket
|
||||
|
||||
log = logging.getLogger(__name__)
|
||||
|
||||
|
||||
class Broadcaster:
|
||||
def __init__(self) -> None:
|
||||
self._subscribers: set[WebSocket] = set()
|
||||
|
||||
@property
|
||||
def count(self) -> int:
|
||||
return len(self._subscribers)
|
||||
|
||||
async def subscribe(self, ws: WebSocket, hello: dict[str, Any] | None = None) -> None:
|
||||
"""Register an accepted socket, and send it the current state.
|
||||
|
||||
The immediate send matters: a client that connects mid-job would
|
||||
otherwise see nothing at all until the next change, which for a long
|
||||
job is a blank progress bar next to work that is visibly happening.
|
||||
"""
|
||||
self._subscribers.add(ws)
|
||||
if hello is not None:
|
||||
await self._send(ws, hello)
|
||||
|
||||
def unsubscribe(self, ws: WebSocket) -> None:
|
||||
self._subscribers.discard(ws)
|
||||
|
||||
async def broadcast(self, message: dict[str, Any]) -> None:
|
||||
await asyncio.gather(*(self._send(ws, message)
|
||||
for ws in tuple(self._subscribers)))
|
||||
|
||||
async def _send(self, ws: WebSocket, message: dict[str, Any]) -> None:
|
||||
try:
|
||||
await asyncio.wait_for(ws.send_json(message), timeout=1.0)
|
||||
except Exception:
|
||||
self._subscribers.discard(ws)
|
||||
@@ -0,0 +1,34 @@
|
||||
"""How a route reaches the queue and the socket bus.
|
||||
|
||||
Both are built once by the app's factory and parked on `app.state`. Routes ask
|
||||
for them as dependencies rather than closing over them, so a router module is
|
||||
importable on its own and a test can replace either through
|
||||
`app.dependency_overrides`.
|
||||
|
||||
Only the two things that are the *pipeline's*. An app's own store and config
|
||||
are its own business and stay in its own `deps` — the queue and the bus are
|
||||
here because `pipeline.web.jobs` is here, and it needs them whichever app it is
|
||||
mounted in.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from typing import Annotated
|
||||
|
||||
from fastapi import Depends
|
||||
from starlette.requests import HTTPConnection
|
||||
|
||||
from pipeline import JobQueue
|
||||
from pipeline.web.broadcaster import Broadcaster
|
||||
|
||||
|
||||
def get_queue(request: HTTPConnection) -> JobQueue:
|
||||
return request.app.state.queue
|
||||
|
||||
|
||||
def get_broadcaster(request: HTTPConnection) -> Broadcaster:
|
||||
return request.app.state.bus
|
||||
|
||||
|
||||
QueueDep = Annotated[JobQueue, Depends(get_queue)]
|
||||
BroadcasterDep = Annotated[Broadcaster, Depends(get_broadcaster)]
|
||||
@@ -0,0 +1,219 @@
|
||||
"""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>
|
||||
|
||||
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)
|
||||
@@ -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
|
||||
@@ -0,0 +1,75 @@
|
||||
"""What the queue's endpoints accept and promise back.
|
||||
|
||||
Job-shaped, so they live with the router that serves them rather than in an
|
||||
app's schema module. The `Job`, `JobsSnapshot` and `Schedule` they sit
|
||||
alongside are in `pipeline/models.py`; these are only ever request bodies, or a
|
||||
stored shape with one derived field added for the client.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from typing import Any
|
||||
|
||||
from pydantic import BaseModel
|
||||
|
||||
from pipeline.models import Schedule
|
||||
|
||||
|
||||
class EnqueueBody(BaseModel):
|
||||
"""Start a job. `payload` is spread over the handler's keyword arguments,
|
||||
so what a kind accepts is the signature of its function and nothing else
|
||||
has to restate it."""
|
||||
|
||||
kind: str
|
||||
payload: dict[str, Any] = {}
|
||||
|
||||
|
||||
class JobKind(BaseModel):
|
||||
"""One entry from the job registry, for a UI that wants to offer them."""
|
||||
|
||||
kind: str
|
||||
label: str
|
||||
solo: bool
|
||||
|
||||
|
||||
class NewSchedule(BaseModel):
|
||||
"""Add a schedule. `name` is optional because the kind is usually answer
|
||||
enough — one `tick` schedule wants no name of its own, and the second is
|
||||
named by counting rather than by making somebody think of one."""
|
||||
|
||||
kind: str
|
||||
cadence: str
|
||||
name: str = ""
|
||||
label: str = ""
|
||||
payload: dict[str, Any] = {}
|
||||
enabled: bool = True
|
||||
|
||||
|
||||
class ScheduleEdit(BaseModel):
|
||||
"""Change part of a schedule. Every field optional, and read with
|
||||
`exclude_unset`, so sending `{"enabled": false}` switches one off without
|
||||
also resubmitting a cadence somebody edited in another tab a second ago.
|
||||
|
||||
`name` is not here: it is the handle a declared default is matched on, and
|
||||
renaming a row would hand its edits to a fresh one inserted under the old
|
||||
name on the next start.
|
||||
"""
|
||||
|
||||
kind: str | None = None
|
||||
label: str | None = None
|
||||
cadence: str | None = None
|
||||
payload: dict[str, Any] | None = None
|
||||
enabled: bool | None = None
|
||||
|
||||
|
||||
class ScheduleRow(Schedule):
|
||||
"""A schedule as it is served: the row, plus whether anything still runs it.
|
||||
|
||||
`unknown` is not stored, because it is a fact about the code that is loaded
|
||||
rather than about the row — a handler removed in a deploy makes it true
|
||||
without the table changing, and reinstalling the plugin makes it false
|
||||
again. The element greys such a row and says `unknown kind`; the queue
|
||||
never fires one.
|
||||
"""
|
||||
|
||||
unknown: bool = False
|
||||
@@ -0,0 +1,280 @@
|
||||
/* The queue, on screen, for an app that has not written a UI yet.
|
||||
*
|
||||
* <script type="module" src="/_jobs/jobs.js"></script>
|
||||
* <desk-jobs></desk-jobs>
|
||||
*
|
||||
* That is the whole of it. The element finds `/ws/jobs` itself, shows what is
|
||||
* running with a progress bar and a Kill button each, says how many are
|
||||
* waiting, and reconnects when the server restarts under you.
|
||||
*
|
||||
* One file, and the styles are in it rather than beside it, because the
|
||||
* shadow root scopes them anyway and a second file is a second route, a
|
||||
* second cache header and a second thing to forget to copy. Themed from
|
||||
* outside through the custom properties at the top of `CSS` — set them on
|
||||
* `desk-jobs` or on `:root` and nothing here has to be forked.
|
||||
*
|
||||
* What it deliberately does not do is talk about failures. It raises a
|
||||
* `desk-jobs:notice` event and leaves the wording to the app, because a
|
||||
* useful sentence names things only the app knows — its backends, its feeds,
|
||||
* its config keys. `pipeline/notices.py` is the same split on the server.
|
||||
*
|
||||
* Attributes, all optional:
|
||||
* base="/api" prefix for the HTTP calls, if the router is mounted deeper
|
||||
* socket="..." the socket's URL, if it is not `/ws/jobs` on this origin
|
||||
* probe="/api/status"
|
||||
* an authenticated endpoint to try when the socket closes. A
|
||||
* refused handshake and a dead server look identical from
|
||||
* here — the server rejects an unauthenticated upgrade before
|
||||
* completing it, so the browser reports the same abnormal
|
||||
* close for "your session expired" as for "the server is
|
||||
* gone". One cheap request tells them apart. Without this the
|
||||
* element assumes the server went away, which is the more
|
||||
* common reason and the less confusing thing to be wrong about.
|
||||
* idle="hide" with nothing running or queued, take up no space. The
|
||||
* default, since a chip that is always there is furniture.
|
||||
*/
|
||||
|
||||
const CSS = `
|
||||
:host {
|
||||
--desk-jobs-bg: #16181d;
|
||||
--desk-jobs-fg: #e7e9ee;
|
||||
--desk-jobs-dim: #9aa1ad;
|
||||
--desk-jobs-accent: #4c8dff;
|
||||
--desk-jobs-error: #ff6b6b;
|
||||
--desk-jobs-radius: 10px;
|
||||
--desk-jobs-font: system-ui, -apple-system, "Segoe UI", sans-serif;
|
||||
--desk-jobs-gap: 8px;
|
||||
|
||||
display: block;
|
||||
font-family: var(--desk-jobs-font);
|
||||
font-size: 13px;
|
||||
color: var(--desk-jobs-fg);
|
||||
}
|
||||
:host([hidden]) { display: none; }
|
||||
|
||||
.strip {
|
||||
display: flex;
|
||||
flex-direction: column;
|
||||
gap: var(--desk-jobs-gap);
|
||||
background: var(--desk-jobs-bg);
|
||||
border-radius: var(--desk-jobs-radius);
|
||||
padding: 10px 12px;
|
||||
}
|
||||
.job { display: grid; grid-template-columns: 1fr auto; gap: 2px 10px; align-items: center; }
|
||||
.what { font-weight: 600; }
|
||||
.said { color: var(--desk-jobs-dim); grid-column: 1; }
|
||||
.count { color: var(--desk-jobs-dim); font-variant-numeric: tabular-nums; }
|
||||
|
||||
/* A bar only when there is a fraction to draw. A handler that reports no
|
||||
* total is working on one thing, and an empty trough reads as stalled. */
|
||||
.bar {
|
||||
grid-column: 1 / -1;
|
||||
height: 3px;
|
||||
border-radius: 2px;
|
||||
background: color-mix(in srgb, var(--desk-jobs-fg) 15%, transparent);
|
||||
overflow: hidden;
|
||||
}
|
||||
.bar > i { display: block; height: 100%; background: var(--desk-jobs-accent); transition: width .2s; }
|
||||
|
||||
button {
|
||||
font: inherit;
|
||||
color: var(--desk-jobs-dim);
|
||||
background: none;
|
||||
border: 1px solid currentColor;
|
||||
border-radius: 6px;
|
||||
padding: 1px 8px;
|
||||
cursor: pointer;
|
||||
}
|
||||
button:hover { color: var(--desk-jobs-error); }
|
||||
button[disabled] { opacity: .4; cursor: default; }
|
||||
|
||||
.offline { color: var(--desk-jobs-error); }
|
||||
`;
|
||||
|
||||
/** Backing off rather than hammering. The usual reason a socket closed is the
|
||||
* server restarting under --reload, which comes back inside a second; the
|
||||
* ceiling is for when it is not coming back at all. */
|
||||
const FIRST_WAIT = 500;
|
||||
const LONGEST_WAIT = 30000;
|
||||
|
||||
/** How long down is long enough to say so. A reload blinks the socket every
|
||||
* time a file is saved, and a warning that flashes on every save is one you
|
||||
* stop reading — which would cost us the case that matters, where the server
|
||||
* really is gone and the strip is quietly showing state from a minute ago. */
|
||||
const QUIET_ABOUT_IT_FOR = 4000;
|
||||
|
||||
class DeskJobs extends HTMLElement {
|
||||
#root;
|
||||
#socket = null;
|
||||
#wait = FIRST_WAIT;
|
||||
#timer = null;
|
||||
#state = { running: [], queued: [], recent: [] };
|
||||
#offline = false;
|
||||
#killing = new Set();
|
||||
|
||||
constructor() {
|
||||
super();
|
||||
this.#root = this.attachShadow({ mode: "open" });
|
||||
const style = document.createElement("style");
|
||||
style.textContent = CSS;
|
||||
this.#root.append(style, document.createElement("div"));
|
||||
}
|
||||
|
||||
connectedCallback() { this.#connect(); this.#render(); }
|
||||
|
||||
disconnectedCallback() {
|
||||
clearTimeout(this.#timer);
|
||||
this.#socket?.close();
|
||||
this.#socket = null;
|
||||
}
|
||||
|
||||
get #base() { return this.getAttribute("base") ?? ""; }
|
||||
|
||||
get #socketUrl() {
|
||||
const given = this.getAttribute("socket");
|
||||
if (given) return given;
|
||||
const scheme = location.protocol === "https:" ? "wss" : "ws";
|
||||
return `${scheme}://${location.host}${this.#base}/ws/jobs`;
|
||||
}
|
||||
|
||||
#connect() {
|
||||
let socket;
|
||||
try {
|
||||
socket = new WebSocket(this.#socketUrl);
|
||||
} catch {
|
||||
this.#reconnect(); // a malformed URL, or no network
|
||||
return;
|
||||
}
|
||||
this.#socket = socket;
|
||||
|
||||
socket.onopen = () => {
|
||||
this.#wait = FIRST_WAIT;
|
||||
this.#offline = false;
|
||||
this.#render();
|
||||
};
|
||||
socket.onmessage = (event) => {
|
||||
let message;
|
||||
try { message = JSON.parse(event.data); } catch { return; }
|
||||
if (message.type === "jobs") {
|
||||
const { type, ...state } = message;
|
||||
this.#state = state;
|
||||
this.#render();
|
||||
} else if (message.type === "notice") {
|
||||
// The app's to word. Composed, so a listener on `document` hears it
|
||||
// through the shadow boundary.
|
||||
this.dispatchEvent(new CustomEvent("desk-jobs:notice", {
|
||||
detail: message, bubbles: true, composed: true,
|
||||
}));
|
||||
}
|
||||
};
|
||||
socket.onerror = () => socket.close();
|
||||
socket.onclose = async () => {
|
||||
if (this.#socket !== socket) return; // a later connection owns us now
|
||||
this.#socket = null;
|
||||
await this.#whyClosed();
|
||||
this.#reconnect();
|
||||
};
|
||||
}
|
||||
|
||||
/** Ask before assuming. See the `probe` attribute. */
|
||||
async #whyClosed() {
|
||||
const probe = this.getAttribute("probe");
|
||||
if (!probe) return;
|
||||
try {
|
||||
const answer = await fetch(this.#base + probe, { credentials: "same-origin" });
|
||||
if (answer.status === 401 || answer.status === 403) {
|
||||
this.dispatchEvent(new CustomEvent("desk-jobs:signed-out", {
|
||||
bubbles: true, composed: true,
|
||||
}));
|
||||
}
|
||||
} catch { /* offline; the strip says so below */ }
|
||||
}
|
||||
|
||||
#reconnect() {
|
||||
if (this.#wait >= QUIET_ABOUT_IT_FOR) {
|
||||
this.#offline = true;
|
||||
this.#render();
|
||||
}
|
||||
clearTimeout(this.#timer);
|
||||
this.#timer = setTimeout(() => this.#connect(), this.#wait);
|
||||
this.#wait = Math.min(this.#wait * 2, LONGEST_WAIT);
|
||||
}
|
||||
|
||||
async #kill(id) {
|
||||
this.#killing.add(id);
|
||||
this.#render();
|
||||
try {
|
||||
await fetch(`${this.#base}/api/jobs/${id}/cancel`,
|
||||
{ method: "POST", credentials: "same-origin" });
|
||||
} finally {
|
||||
// The socket reports the actual ending — a running job stops at its next
|
||||
// checkpoint, so the button going quiet is the whole of what happens here.
|
||||
this.#killing.delete(id);
|
||||
}
|
||||
}
|
||||
|
||||
#render() {
|
||||
const { running = [], queued = [] } = this.#state;
|
||||
const strip = this.#root.lastElementChild;
|
||||
this.hidden = this.getAttribute("idle") !== "show"
|
||||
&& !running.length && !queued.length && !this.#offline;
|
||||
|
||||
strip.className = "strip";
|
||||
strip.replaceChildren();
|
||||
|
||||
if (this.#offline) {
|
||||
const said = document.createElement("div");
|
||||
said.className = "offline";
|
||||
said.textContent = "Not connected — what you see here may be out of date.";
|
||||
strip.append(said);
|
||||
}
|
||||
|
||||
for (const job of running) {
|
||||
strip.append(this.#row(job));
|
||||
}
|
||||
if (queued.length) {
|
||||
const waiting = document.createElement("div");
|
||||
waiting.className = "count";
|
||||
waiting.textContent = `${queued.length} waiting`;
|
||||
strip.append(waiting);
|
||||
}
|
||||
}
|
||||
|
||||
#row(job) {
|
||||
const row = document.createElement("div");
|
||||
row.className = "job";
|
||||
|
||||
const what = document.createElement("span");
|
||||
what.className = "what";
|
||||
what.textContent = job.label || job.kind;
|
||||
row.append(what);
|
||||
|
||||
const kill = document.createElement("button");
|
||||
kill.textContent = "Kill";
|
||||
kill.disabled = this.#killing.has(job.id) || job.cancel_requested;
|
||||
kill.addEventListener("click", () => this.#kill(job.id));
|
||||
row.append(kill);
|
||||
|
||||
if (job.message) {
|
||||
const said = document.createElement("span");
|
||||
said.className = "said";
|
||||
said.textContent = job.message;
|
||||
row.append(said);
|
||||
}
|
||||
if (job.total > 0) {
|
||||
const bar = document.createElement("div");
|
||||
bar.className = "bar";
|
||||
const fill = document.createElement("i");
|
||||
fill.style.width = `${Math.min(100, (job.done / job.total) * 100)}%`;
|
||||
bar.append(fill);
|
||||
row.append(bar);
|
||||
}
|
||||
return row;
|
||||
}
|
||||
}
|
||||
|
||||
if (!customElements.get("desk-jobs")) {
|
||||
customElements.define("desk-jobs", DeskJobs);
|
||||
}
|
||||
|
||||
export { DeskJobs };
|
||||
@@ -0,0 +1,543 @@
|
||||
/* The schedule table, on screen, for an app that has not written a UI yet.
|
||||
*
|
||||
* <script type="module" src="/_jobs/schedules.js"></script>
|
||||
* <desk-schedules></desk-schedules>
|
||||
*
|
||||
* A row per schedule — name, kind, cadence, on or off, next run, last run and
|
||||
* how that job ended — plus Run now, Delete, and a row at the bottom for
|
||||
* adding one. The kinds come from `/api/jobs/kinds`, so a new `@job` is a new
|
||||
* option here without this file being touched.
|
||||
*
|
||||
* It reads `/ws/jobs` for `schedules` messages, so a row edited in another tab
|
||||
* redraws in this one, and a firing moves the times without anybody polling.
|
||||
* The socket's opening message is the *job* list, though, so the table is
|
||||
* fetched once on connect: the push says what changed, not what there is. The
|
||||
* job list is read as it goes past as well, for the last column — a schedule
|
||||
* is pushed when it fires, which is before its job has ended, so the state it
|
||||
* ended in can only come from there.
|
||||
*
|
||||
* The same one-file, shadow-root, custom-property shape as `<desk-jobs>`, and
|
||||
* deliberately the same `--desk-jobs-*` names: an app that themed one element
|
||||
* has themed both, and two schemes for two halves of one page is the thing
|
||||
* nobody wants to maintain.
|
||||
*
|
||||
* Failures are not worded here. A refused change raises `desk-schedules:error`
|
||||
* carrying the server's own `detail` — which the endpoints promise is one
|
||||
* readable sentence — and the app toasts it. Notices arriving on the socket
|
||||
* are re-raised as `desk-jobs:notice`, the same event `<desk-jobs>` raises, so
|
||||
* an app that listens for one is listening for both.
|
||||
*
|
||||
* Attributes, all optional:
|
||||
* base="/api" prefix for the HTTP calls, if the router is mounted deeper
|
||||
* socket="..." the socket's URL, if it is not `/ws/jobs` on this origin
|
||||
*/
|
||||
|
||||
const CSS = `
|
||||
:host {
|
||||
--desk-jobs-bg: #16181d;
|
||||
--desk-jobs-fg: #e7e9ee;
|
||||
--desk-jobs-dim: #9aa1ad;
|
||||
--desk-jobs-accent: #4c8dff;
|
||||
--desk-jobs-error: #ff6b6b;
|
||||
--desk-jobs-radius: 10px;
|
||||
--desk-jobs-font: system-ui, -apple-system, "Segoe UI", sans-serif;
|
||||
--desk-jobs-gap: 8px;
|
||||
|
||||
display: block;
|
||||
font-family: var(--desk-jobs-font);
|
||||
font-size: 13px;
|
||||
color: var(--desk-jobs-fg);
|
||||
}
|
||||
:host([hidden]) { display: none; }
|
||||
|
||||
.panel {
|
||||
background: var(--desk-jobs-bg);
|
||||
border-radius: var(--desk-jobs-radius);
|
||||
padding: 10px 12px;
|
||||
}
|
||||
|
||||
table { width: 100%; border-collapse: collapse; }
|
||||
th, td {
|
||||
text-align: left;
|
||||
padding: 6px 8px 6px 0;
|
||||
vertical-align: baseline;
|
||||
border-bottom: 1px solid color-mix(in srgb, var(--desk-jobs-fg) 12%, transparent);
|
||||
}
|
||||
th { color: var(--desk-jobs-dim); font-weight: 600; white-space: nowrap; }
|
||||
tr:last-child > td { border-bottom: 0; }
|
||||
td.actions { text-align: right; white-space: nowrap; }
|
||||
|
||||
.name { font-weight: 600; }
|
||||
.kind, .when { color: var(--desk-jobs-dim); font-variant-numeric: tabular-nums; }
|
||||
.off { opacity: .55; }
|
||||
.bad { color: var(--desk-jobs-error); }
|
||||
|
||||
/* The cadence is edited in place: a box that looks like text until you are in
|
||||
* it, because a table of eight input fields reads as a form to fill in rather
|
||||
* than as a list of what is running. */
|
||||
input.cadence, input.text {
|
||||
font: inherit;
|
||||
color: inherit;
|
||||
background: none;
|
||||
border: 1px solid transparent;
|
||||
border-radius: 6px;
|
||||
padding: 1px 4px;
|
||||
min-width: 9em;
|
||||
}
|
||||
input.cadence:hover { border-color: color-mix(in srgb, var(--desk-jobs-fg) 20%, transparent); }
|
||||
input:focus { outline: none; border-color: var(--desk-jobs-accent); }
|
||||
input::placeholder { color: var(--desk-jobs-dim); }
|
||||
|
||||
select {
|
||||
font: inherit;
|
||||
color: inherit;
|
||||
background: var(--desk-jobs-bg);
|
||||
border: 1px solid color-mix(in srgb, var(--desk-jobs-fg) 20%, transparent);
|
||||
border-radius: 6px;
|
||||
padding: 1px 4px;
|
||||
}
|
||||
|
||||
button {
|
||||
font: inherit;
|
||||
color: var(--desk-jobs-dim);
|
||||
background: none;
|
||||
border: 1px solid currentColor;
|
||||
border-radius: 6px;
|
||||
padding: 1px 8px;
|
||||
margin-left: 6px;
|
||||
cursor: pointer;
|
||||
}
|
||||
button:hover { color: var(--desk-jobs-accent); }
|
||||
button.remove:hover { color: var(--desk-jobs-error); }
|
||||
button[disabled] { opacity: .4; cursor: default; }
|
||||
|
||||
.state { font-size: 11px; padding: 0 5px; border-radius: 999px;
|
||||
border: 1px solid currentColor; margin-left: 6px; }
|
||||
.state.failed, .state.cancelled { color: var(--desk-jobs-error); }
|
||||
.state.running, .state.queued { color: var(--desk-jobs-accent); }
|
||||
|
||||
.empty, .offline { color: var(--desk-jobs-dim); padding: 6px 0; }
|
||||
.offline { color: var(--desk-jobs-error); }
|
||||
`;
|
||||
|
||||
/** The same backoff as `<desk-jobs>`: the usual reason a socket closed is the
|
||||
* server restarting under --reload, which comes back inside a second. */
|
||||
const FIRST_WAIT = 500;
|
||||
const LONGEST_WAIT = 30000;
|
||||
|
||||
/** The grammar, in the one place a person is asked to use it. Two of the five
|
||||
* as the placeholder, because a box wide enough for all five is a box wide
|
||||
* enough to unbalance the row it is in — and all five on hover, which is also
|
||||
* what the server's refusal says if they get it wrong anyway. */
|
||||
const FORMS = "every 15m · every 6h · every 2d · daily at 06:00 · weekly mon 07:00";
|
||||
const HINT = "every 15m · daily at 06:00";
|
||||
|
||||
/** A stamp as a person reads it. Today is a time, anything else is a date and
|
||||
* a time, and "never" is said rather than left blank — an empty cell reads as
|
||||
* a bug, and "never" is a fact. */
|
||||
function when(stamp) {
|
||||
if (!stamp) return "never";
|
||||
const at = new Date(stamp);
|
||||
if (isNaN(at)) return stamp;
|
||||
const today = at.toDateString() === new Date().toDateString();
|
||||
const clock = at.toLocaleTimeString([], { hour: "2-digit", minute: "2-digit" });
|
||||
return today ? clock : `${at.toLocaleDateString()} ${clock}`;
|
||||
}
|
||||
|
||||
class DeskSchedules extends HTMLElement {
|
||||
#root;
|
||||
#socket = null;
|
||||
#wait = FIRST_WAIT;
|
||||
#timer = null;
|
||||
#rows = [];
|
||||
#kinds = [];
|
||||
#offline = false;
|
||||
#busy = new Set();
|
||||
#loaded = false;
|
||||
|
||||
constructor() {
|
||||
super();
|
||||
this.#root = this.attachShadow({ mode: "open" });
|
||||
const style = document.createElement("style");
|
||||
style.textContent = CSS;
|
||||
this.#root.append(style, document.createElement("div"));
|
||||
}
|
||||
|
||||
connectedCallback() {
|
||||
this.#render();
|
||||
this.#load();
|
||||
this.#connect();
|
||||
}
|
||||
|
||||
disconnectedCallback() {
|
||||
clearTimeout(this.#timer);
|
||||
this.#socket?.close();
|
||||
this.#socket = null;
|
||||
}
|
||||
|
||||
get #base() { return this.getAttribute("base") ?? ""; }
|
||||
|
||||
get #socketUrl() {
|
||||
const given = this.getAttribute("socket");
|
||||
if (given) return given;
|
||||
const scheme = location.protocol === "https:" ? "wss" : "ws";
|
||||
return `${scheme}://${location.host}${this.#base}/ws/jobs`;
|
||||
}
|
||||
|
||||
/* -- the server ------------------------------------------------------- */
|
||||
|
||||
/** Every call goes through here, so one place raises the event and one
|
||||
* place knows that a refusal carries `{"detail": "<sentence>"}`. */
|
||||
async #ask(path, options) {
|
||||
const o = Object.assign({ credentials: "same-origin" }, options);
|
||||
if (o.body !== undefined && typeof o.body !== "string") {
|
||||
o.headers = Object.assign({ "Content-Type": "application/json" }, o.headers);
|
||||
o.body = JSON.stringify(o.body);
|
||||
}
|
||||
let answer;
|
||||
try {
|
||||
answer = await fetch(this.#base + path, o);
|
||||
} catch (e) {
|
||||
this.#failed("Could not reach the server.");
|
||||
throw e;
|
||||
}
|
||||
const text = await answer.text();
|
||||
let body = null;
|
||||
if (text) { try { body = JSON.parse(text); } catch (e) { body = null; } }
|
||||
if (!answer.ok) {
|
||||
this.#failed((body && body.detail)
|
||||
|| `The server answered ${answer.status} and said nothing about why.`);
|
||||
throw new Error(String((body && body.detail) || answer.status));
|
||||
}
|
||||
return body;
|
||||
}
|
||||
|
||||
#failed(detail) {
|
||||
// Composed, so a listener on `document` hears it through the shadow
|
||||
// boundary. The wording is the server's; this element has no opinion.
|
||||
this.dispatchEvent(new CustomEvent("desk-schedules:error", {
|
||||
detail: { detail: String(detail) }, bubbles: true, composed: true,
|
||||
}));
|
||||
}
|
||||
|
||||
async #load() {
|
||||
try {
|
||||
const [rows, kinds] = await Promise.all([
|
||||
this.#ask("/api/schedules"),
|
||||
this.#ask("/api/jobs/kinds"),
|
||||
]);
|
||||
this.#rows = rows || [];
|
||||
this.#kinds = kinds || [];
|
||||
} catch (e) {
|
||||
/* already raised */
|
||||
} finally {
|
||||
this.#loaded = true;
|
||||
this.#render();
|
||||
}
|
||||
}
|
||||
|
||||
#connect() {
|
||||
let socket;
|
||||
try {
|
||||
socket = new WebSocket(this.#socketUrl);
|
||||
} catch {
|
||||
this.#reconnect();
|
||||
return;
|
||||
}
|
||||
this.#socket = socket;
|
||||
|
||||
socket.onopen = () => {
|
||||
this.#wait = FIRST_WAIT;
|
||||
if (this.#offline) {
|
||||
// Down and back: what changed while we were away came as nothing, so
|
||||
// the list is read again rather than waited for.
|
||||
this.#offline = false;
|
||||
this.#load();
|
||||
}
|
||||
this.#render();
|
||||
};
|
||||
socket.onmessage = (event) => {
|
||||
let message;
|
||||
try { message = JSON.parse(event.data); } catch { return; }
|
||||
if (message.type === "schedules") {
|
||||
this.#rows = message.schedules || [];
|
||||
this.#render();
|
||||
} else if (message.type === "jobs") {
|
||||
this.#catchUp(message);
|
||||
} else if (message.type === "notice") {
|
||||
this.dispatchEvent(new CustomEvent("desk-jobs:notice", {
|
||||
detail: message, bubbles: true, composed: true,
|
||||
}));
|
||||
}
|
||||
};
|
||||
socket.onerror = () => socket.close();
|
||||
socket.onclose = () => {
|
||||
if (this.#socket !== socket) return; // a later connection owns us
|
||||
this.#socket = null;
|
||||
this.#reconnect();
|
||||
};
|
||||
}
|
||||
|
||||
/* The last column says how the last job ended, and the `schedules` message
|
||||
* is pushed when a schedule *fires* — at which point that job has not ended
|
||||
* and the cell reads `running`. Nothing pushes a schedule again when the
|
||||
* job finishes, so without this the table goes on reporting a job as
|
||||
* running long after it is done, which is the one thing this column is for.
|
||||
*
|
||||
* The job list arrives on this same socket four times a second while
|
||||
* anything is going, and it carries the state of every job worth knowing
|
||||
* about, so the answer is already here: take it off the snapshot rather
|
||||
* than ask the server a second time. A job old enough to have left `recent`
|
||||
* keeps whatever it was last seen as; its schedule has fired since, or it
|
||||
* has been on screen for an hour. */
|
||||
#catchUp(snapshot) {
|
||||
const states = new Map();
|
||||
for (const list of ["running", "queued", "recent"]) {
|
||||
for (const job of snapshot[list] || []) states.set(job.id, job.state);
|
||||
}
|
||||
let moved = false;
|
||||
for (const row of this.#rows) {
|
||||
const state = states.get(row.last_job_id);
|
||||
if (state && state !== row.last_state) {
|
||||
row.last_state = state;
|
||||
moved = true;
|
||||
}
|
||||
}
|
||||
if (moved) this.#render();
|
||||
}
|
||||
|
||||
#reconnect() {
|
||||
if (this.#wait >= 4000) {
|
||||
this.#offline = true;
|
||||
this.#render();
|
||||
}
|
||||
clearTimeout(this.#timer);
|
||||
this.#timer = setTimeout(() => this.#connect(), this.#wait);
|
||||
this.#wait = Math.min(this.#wait * 2, LONGEST_WAIT);
|
||||
}
|
||||
|
||||
/* One wrapper for every change: the row is greyed while the request is in
|
||||
* the air, and the new list arrives on the socket rather than being patched
|
||||
* in here — so what is on screen is always what the server holds. */
|
||||
async #change(id, run) {
|
||||
this.#busy.add(id);
|
||||
this.#render();
|
||||
try {
|
||||
await run();
|
||||
} catch (e) {
|
||||
/* already raised */
|
||||
} finally {
|
||||
this.#busy.delete(id);
|
||||
this.#render();
|
||||
}
|
||||
}
|
||||
|
||||
/* -- drawing ---------------------------------------------------------- */
|
||||
|
||||
#render() {
|
||||
const panel = this.#root.lastElementChild;
|
||||
panel.className = "panel";
|
||||
panel.replaceChildren();
|
||||
|
||||
if (this.#offline) {
|
||||
const said = document.createElement("div");
|
||||
said.className = "offline";
|
||||
said.textContent = "Not connected — what you see here may be out of date.";
|
||||
panel.append(said);
|
||||
}
|
||||
|
||||
const table = document.createElement("table");
|
||||
table.append(this.#head());
|
||||
const body = document.createElement("tbody");
|
||||
for (const row of this.#rows) body.append(this.#row(row));
|
||||
body.append(this.#adder());
|
||||
table.append(body);
|
||||
panel.append(table);
|
||||
|
||||
if (this.#loaded && !this.#rows.length) {
|
||||
const empty = document.createElement("div");
|
||||
empty.className = "empty";
|
||||
empty.textContent = "Nothing is scheduled. Add one below.";
|
||||
panel.insertBefore(empty, table);
|
||||
}
|
||||
}
|
||||
|
||||
#head() {
|
||||
const head = document.createElement("thead");
|
||||
const row = document.createElement("tr");
|
||||
for (const label of ["Name", "Kind", "Cadence", "On", "Next", "Last", ""]) {
|
||||
const cell = document.createElement("th");
|
||||
cell.textContent = label;
|
||||
row.append(cell);
|
||||
}
|
||||
head.append(row);
|
||||
return head;
|
||||
}
|
||||
|
||||
#row(schedule) {
|
||||
const row = document.createElement("tr");
|
||||
const busy = this.#busy.has(schedule.id);
|
||||
if (!schedule.enabled) row.classList.add("off");
|
||||
|
||||
row.append(this.#cell("name", schedule.name));
|
||||
|
||||
const kind = this.#cell("kind", schedule.kind);
|
||||
if (schedule.unknown) {
|
||||
// Never fires, and says so rather than sitting there with a next run it
|
||||
// is not going to keep. Deleting it is the only thing left to do.
|
||||
const bad = document.createElement("span");
|
||||
bad.className = "state bad";
|
||||
bad.textContent = "unknown kind";
|
||||
kind.append(bad);
|
||||
}
|
||||
row.append(kind);
|
||||
|
||||
const cadence = document.createElement("td");
|
||||
const box = document.createElement("input");
|
||||
box.className = "cadence";
|
||||
box.value = schedule.cadence;
|
||||
box.title = FORMS;
|
||||
box.disabled = busy;
|
||||
const save = () => {
|
||||
const wanted = box.value.trim();
|
||||
if (!wanted || wanted === schedule.cadence) {
|
||||
box.value = schedule.cadence;
|
||||
return;
|
||||
}
|
||||
this.#change(schedule.id, () => this.#ask(`/api/schedules/${schedule.id}`,
|
||||
{ method: "PATCH", body: { cadence: wanted } }));
|
||||
};
|
||||
box.addEventListener("change", save);
|
||||
box.addEventListener("keydown", (e) => { if (e.key === "Enter") box.blur(); });
|
||||
cadence.append(box);
|
||||
row.append(cadence);
|
||||
|
||||
const onOff = document.createElement("td");
|
||||
const toggle = document.createElement("input");
|
||||
toggle.type = "checkbox";
|
||||
toggle.checked = !!schedule.enabled;
|
||||
toggle.disabled = busy;
|
||||
toggle.title = schedule.enabled ? "switch this schedule off" : "switch it on";
|
||||
toggle.addEventListener("change", () => this.#change(schedule.id,
|
||||
() => this.#ask(`/api/schedules/${schedule.id}`,
|
||||
{ method: "PATCH", body: { enabled: toggle.checked } })));
|
||||
onOff.append(toggle);
|
||||
row.append(onOff);
|
||||
|
||||
row.append(this.#cell("when", schedule.enabled ? when(schedule.next_run) : "—"));
|
||||
|
||||
const last = this.#cell("when", when(schedule.last_run));
|
||||
if (schedule.last_state) {
|
||||
const state = document.createElement("span");
|
||||
state.className = `state ${schedule.last_state}`;
|
||||
state.textContent = schedule.last_state;
|
||||
last.append(state);
|
||||
}
|
||||
row.append(last);
|
||||
|
||||
const actions = document.createElement("td");
|
||||
actions.className = "actions";
|
||||
const now = document.createElement("button");
|
||||
now.textContent = "Run now";
|
||||
now.disabled = busy || schedule.unknown;
|
||||
now.addEventListener("click", () => this.#change(schedule.id,
|
||||
() => this.#ask(`/api/schedules/${schedule.id}/run`, { method: "POST" })));
|
||||
const remove = document.createElement("button");
|
||||
remove.className = "remove";
|
||||
remove.textContent = "Delete";
|
||||
remove.disabled = busy;
|
||||
remove.addEventListener("click", () => this.#change(schedule.id,
|
||||
() => this.#ask(`/api/schedules/${schedule.id}`, { method: "DELETE" })));
|
||||
actions.append(now, remove);
|
||||
row.append(actions);
|
||||
|
||||
return row;
|
||||
}
|
||||
|
||||
#cell(className, text) {
|
||||
const cell = document.createElement("td");
|
||||
cell.className = className;
|
||||
const span = document.createElement("span");
|
||||
span.textContent = text;
|
||||
cell.append(span);
|
||||
return cell;
|
||||
}
|
||||
|
||||
/** The add row. In the table rather than in a form above it, because what
|
||||
* is being added is another one of these and the columns already say what
|
||||
* each box is for. */
|
||||
#adder() {
|
||||
const row = document.createElement("tr");
|
||||
const busy = this.#busy.has(0);
|
||||
|
||||
const name = document.createElement("input");
|
||||
name.className = "text";
|
||||
name.placeholder = "optional";
|
||||
name.disabled = busy;
|
||||
row.append(this.#wrap(name));
|
||||
|
||||
const kind = document.createElement("select");
|
||||
kind.disabled = busy || !this.#kinds.length;
|
||||
for (const k of this.#kinds) {
|
||||
const option = document.createElement("option");
|
||||
option.value = k.kind;
|
||||
option.textContent = k.label || k.kind;
|
||||
kind.append(option);
|
||||
}
|
||||
if (!this.#kinds.length) {
|
||||
const none = document.createElement("option");
|
||||
none.textContent = this.#loaded ? "nothing registered" : "loading…";
|
||||
kind.append(none);
|
||||
}
|
||||
row.append(this.#wrap(kind));
|
||||
|
||||
const cadence = document.createElement("input");
|
||||
cadence.className = "text";
|
||||
cadence.placeholder = HINT;
|
||||
cadence.title = FORMS;
|
||||
cadence.disabled = busy;
|
||||
row.append(this.#wrap(cadence));
|
||||
|
||||
row.append(document.createElement("td"), document.createElement("td"),
|
||||
document.createElement("td"));
|
||||
|
||||
const actions = document.createElement("td");
|
||||
actions.className = "actions";
|
||||
const add = document.createElement("button");
|
||||
add.textContent = "Add";
|
||||
add.disabled = busy;
|
||||
const submit = () => {
|
||||
if (!kind.value) return;
|
||||
this.#change(0, async () => {
|
||||
await this.#ask("/api/schedules", {
|
||||
method: "POST",
|
||||
body: { name: name.value.trim(), kind: kind.value,
|
||||
cadence: cadence.value.trim() },
|
||||
});
|
||||
// Cleared only on success, so a refused cadence is still there to be
|
||||
// corrected rather than retyped from memory.
|
||||
name.value = "";
|
||||
cadence.value = "";
|
||||
});
|
||||
};
|
||||
add.addEventListener("click", submit);
|
||||
for (const box of [name, cadence]) {
|
||||
box.addEventListener("keydown", (e) => { if (e.key === "Enter") submit(); });
|
||||
}
|
||||
actions.append(add);
|
||||
row.append(actions);
|
||||
return row;
|
||||
}
|
||||
|
||||
#wrap(control) {
|
||||
const cell = document.createElement("td");
|
||||
cell.append(control);
|
||||
return cell;
|
||||
}
|
||||
}
|
||||
|
||||
if (!customElements.get("desk-schedules")) {
|
||||
customElements.define("desk-schedules", DeskSchedules);
|
||||
}
|
||||
|
||||
export { DeskSchedules };
|
||||
Reference in new issue
Block a user