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:
WolfandClaude Opus 5.5 committed 2026-09-23 12:29:16 +02:00
1 parent 1f436104f3
commit 9d666d0937
76 files changed
+15235

No files matched your search

+59
View File
@@ -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",
]
+86
View File
@@ -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
+56
View File
@@ -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)
+34
View File
@@ -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)]
+219
View File
@@ -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)
+218
View File
@@ -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
+75
View File
@@ -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
+280
View File
@@ -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 };
+543
View File
@@ -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 };