Files
WolfandClaude Opus 5.5 9d666d0937 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>
2026-09-23 12:29:16 +02:00

87 lines
3.6 KiB
Python

"""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