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