taskops-cli 0.2.0__py3-none-any.whl

taskops/transports/http/live.py

@@ -0,0 +1,160 @@
+"""The live feed: a WEBSOCKET for the browser, server-sent events as the fallback.
+
+One route, two envelopes, one source. `usecases.follow` produces the events and the only difference
+is the framing — so there is no second feed to keep in step.
+
+**Why both.** The websocket is what a browser gets: its PING is the protocol's own liveness probe
+(unlike an SSE comment, it gets an answer), and it is the channel that can carry a client→server
+message the day the board needs one. SSE stays because it needs no handshake at all, which makes
+`curl -N /api/live` a working debugging tool and gives a proxy that mangles upgrades a fallback.
+
+**Why neither uses asyncio.** The engine is synchronous by an enforced invariant, so both are served
+by the threaded `ThreadingHTTPServer`: one connection is one thread parked in a generator, and the
+sqlite underneath never learns that a websocket exists. The RFC 6455 framing this needs is small
+enough to write (`_wsframes`) and buys zero runtime dependencies — which matters in a package that
+installs into every agent's environment on every machine.
+
+The tailing itself is `usecases.feed`, because it needs the event bus and a cursor, and a transport
+may not reach for either — including the filter that keeps one project's narration off another
+project's board. This module only strips that routing field back off on the way out (`_public`).
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Generator
+from pathlib import Path
+from typing import Any
+
+from ...usecases import follow, is_wire
+from . import websocket
+from ._wire import Reply, Request
+
+__all__ = ["stream"]
+
+NARRATION = "narration"
+"""The second thing this feed carries. An event is a stored fact and this is not — it is the prose
+of a report arriving as a model writes it, published to `engine.WIRE`, never to the log. Same route and same socket on purpose: a browser holds one connection, and a second stream would
+be a second subscription and a second lifetime to leak for what is one panel on one screen. The
+envelope keeps them apart — a client that never heard of narration drops the frame."""
+
+KEEPALIVE_TICKS = 4
+"""Quiet ticks before a comment frame goes out — 4 × 0.5s = 2 seconds.
+
+Proxies and browsers close an idle response, so something has to be sent. It is also how a write
+eventually fails on a socket whose client went away — but only *eventually*, which is why it is not
+the mechanism this relies on (see `MAX_TICKS`)."""
+
+MAX_TICKS = 600
+"""Ticks before the stream ends itself — 600 × 0.5s = 5 minutes. THE resource bound.
+
+Measured, not assumed. The obvious design is a response that lives forever and ends when a write to
+a departed client fails; that write does not reliably fail. Against a closed loopback socket on
+macOS, writes kept succeeding for over seven seconds, so a closed tab held a bus subscription and an
+open sqlite connection for an unbounded time — a real leak, found by the test below.
+
+Ending the response on a schedule inverts the problem instead of fighting it: `EventSource`
+reconnects on its own, by specification, and the UI refetches on every open — so a recycled stream
+is invisible to the watcher, and resource use is bounded by DESIGN rather than by how promptly an
+operating system reports a dead peer.
+"""
+
+
+def stream(root: Path, request: Request) -> Reply:
+    """The live feed. A WEBSOCKET when the client asks to upgrade, SSE otherwise — one route
+    serving both, for the reasons in this module's header.
+
+    `X-Accel-Buffering: no` is not decoration on the SSE path: nginx buffers a proxied response by
+    default, and with it the whole feed arrives in one lump whenever the buffer happens to fill.
+    """
+    key = request.headers.get("sec-websocket-key", "")
+    if websocket.is_upgrade(request.headers):
+        return Reply(status=101, stream=lambda: _ws_frames(root),
+                     headers=websocket.handshake_headers(key))
+    return Reply(status=200, stream=lambda: _frames(root),
+                 headers={"Content-Type": "text/event-stream; charset=utf-8",
+                          "Cache-Control": "no-cache, no-transform",
+                          "Connection": "keep-alive",
+                          "X-Accel-Buffering": "no"})
+
+
+def _ws_frames(root: Path) -> Generator[bytes, None, None]:
+    """The same feed, in websocket frames.
+
+    JSON with a `type` rather than SSE's `event:` line, because a websocket has no per-message event
+    name — so the envelope carries it, and the browser switches on one field.
+
+    A quiet tick sends a PING, not a comment: the protocol's own liveness probe, and unlike the SSE
+    keepalive it gets an answer, so the browser can tell a live-but-idle board from a dead socket.
+    Both still end at `MAX_TICKS` — a parked generator cannot notice a departed client.
+    """
+    yield websocket.text_frame(json.dumps({"type": "hello"}))
+    ticks = 0
+    for event in follow(root):
+        if is_wire(event):
+            yield websocket.text_frame(json.dumps({"type": NARRATION, "message": _public(event)},
+                                                  default=str))
+            continue
+        if event is not None:
+            yield websocket.text_frame(json.dumps({"type": "change", "event": event},
+                                                  default=str))
+            continue
+        ticks += 1
+        if ticks >= MAX_TICKS:
+            yield websocket.close_frame()
+            return
+        if ticks % KEEPALIVE_TICKS == 0:
+            yield websocket.ping_frame()
+
+
+def _frames(root: Path) -> Generator[bytes, None, None]:
+    """Turn the feed into SSE frames. Always from NOW, and no `id:`.
+
+    No resume cursor, deliberately. The `seq` a cursor would need is machine-local by design and is
+    not part of the `Event` contract, so a frame has nothing honest to put in `id:` — and the
+    recovery a board wants is not a replay anyway. The UI refetches the board and the fleet whenever
+    the stream opens, which closes any gap in one request; events are only the signal to refetch.
+    Replaying into a projection derived from the database is slower and less correct than reading it.
+    """
+    # Immediately, before the first tick. Two jobs: the UI's `onOpen` fires on it and refetches, and
+    # a connection that was already dead on arrival raises here instead of parking for two seconds.
+    yield b"event: hello\ndata: {}\n\n"
+    quiet = 0
+    ticks = 0
+    for event in follow(root):
+        if is_wire(event):
+            quiet = 0
+            yield _frame(_public(event), NARRATION)
+            continue
+        if event is not None:
+            quiet = 0
+            yield _frame(event)
+            continue
+        ticks += 1
+        quiet += 1
+        if ticks >= MAX_TICKS:
+            # Return, never raise. The generator's `finally` releases the store and the
+            # subscription, the server closes the response, and the browser reconnects on its own.
+            return
+        if quiet >= KEEPALIVE_TICKS:
+            quiet = 0
+            yield b": keepalive\n\n"
+
+
+def _public(message: Any) -> dict[str, Any]:
+    """A wire message with its `root` STRIPPED — what a browser is allowed to see.
+
+    The field routes the message inside the server (`usecases.follow`); on the wire it is only an
+    absolute path on the server's filesystem, and on a multi-project server the name of a board
+    this caller may hold no token for. A COPY, never a mutation: the broadcast handed the same
+    dict to every subscriber and a message without a root is dropped, so popping the key in place
+    would silence the board next door. Typed loosely — `is_wire` already ran at the call site.
+    """
+    return {key: value for key, value in message.items() if key != "root"}
+
+
+def _frame(event: object, name: str = "change") -> bytes:
+    """One SSE frame. The event NAME is what tells the two feeds apart — the websocket has no
+    such line, which is why its envelope carries a `type` instead."""
+    payload = json.dumps(event, default=str)
+    return f"event: {name}\ndata: {payload}\n\n".encode("utf-8")

taskops/transports/http/policy.py

@@ -0,0 +1,110 @@
+"""Who may do what over HTTP. Three settings, and each one has a deployment behind it.
+
+The UI binds to loopback by default, so on a laptop none of this is load-bearing. It all is
+the moment somebody puts it behind nginx to show a team the board — which is the intended use,
+so the controls exist before the first person needs them rather than after.
+"""
+
+from __future__ import annotations
+
+from collections import deque
+from dataclasses import dataclass, field
+
+from ..._clock import now
+from ._wire import Reply, Request, error_reply
+
+__all__ = ["Policy"]
+
+_WRITE_METHODS = frozenset({"POST", "PUT", "PATCH", "DELETE"})
+
+_ASSETS = (".js", ".css", ".map", ".svg", ".png", ".ico", ".woff2")
+"""Extensions the bundle is made of. A closed list, not "anything not under /api/": the SPA
+falls back to `index.html` for unknown paths, so a wildcard would hand the app shell — and any
+future page — to anyone who guessed a path."""
+
+
+def _is_asset(request: Request) -> bool:
+    """A GET for a file of the built UI. Never an API path, whatever it is named."""
+    return (request.method == "GET" and not request.path.startswith("/api/")
+            and request.path.endswith(_ASSETS))
+
+
+@dataclass
+class Policy:
+    token: str = ""
+    """Require `Authorization: Bearer <token>`. Empty means open, which is correct on
+    loopback and wrong the moment `--host 0.0.0.0` appears."""
+
+    readonly: bool = False
+    """Refuse every write. For a board on a screen in a room: a shared display should not be
+    able to close somebody's task, and a viewer should not be able to post as an agent."""
+
+    rate_limit: int = 0
+    """Requests per minute per process, 0 for none. Not per client: this is one small server
+    and the thing it protects against is a page with a broken retry loop, not an attacker —
+    who would be stopped by the token, not by a counter."""
+
+    _hits: deque[float] = field(default_factory=deque[float], repr=False)
+
+    def check(self, request: Request) -> Reply | None:
+        """None means allowed. Ordered cheapest-first, and auth before everything.
+
+        Auth first so a wrong token cannot consume the rate budget, which would otherwise let
+        an unauthenticated caller lock out an authenticated one.
+        """
+        if refusal := self._auth(request):
+            return refusal
+        if self.readonly and request.method in _WRITE_METHODS:
+            return error_reply(403, "this board is read-only — start it without "
+                                    "--readonly to comment or change a status", "readonly")
+        return self._rate()
+
+    def _auth(self, request: Request) -> Reply | None:
+        """The header, or `?token=` — and the query form is not laziness.
+
+        `EventSource` has no API for request headers, at all. So an SSE stream behind a token can
+        ONLY be authenticated by the URL, and refusing the query form would mean the live feed is
+        the one endpoint a token locks out. It is accepted everywhere rather than only on
+        `/api/live`, because a rule that holds for one path is a rule somebody will move.
+
+        The cost is a token in the browser's address bar and history. That is acceptable for a
+        loopback tool whose token is minted per run; it would not be for a public service, and a
+        deployment that needs more should terminate auth at the proxy.
+
+        THE BUNDLE IS EXEMPT, and that is what makes a token usable at all in a browser. A page
+        opened as `/axion/?token=…` asks for `/axion/app.js` with NO query string — browsers do
+        not propagate a parameter to subresources — so guarding the bundle 401s the page's own
+        script and leaves a blank screen behind a URL that looked right. Measured in production
+        before it was believed. What the exemption gives away is a JavaScript file identical in
+        every install: no task, no title, no event. Everything that IS this project — the API and
+        the live feed — stays behind the token.
+        """
+        if not self.token or _is_asset(request):
+            return None
+        expected = f"Bearer {self.token}"
+        if request.headers.get("authorization") == expected:
+            return None
+        if request.param("token") == self.token:
+            return None
+        return error_reply(401, "a bearer token is required — open the URL `taskops ui` "
+                                "printed, which carries it", "unauthorized")
+
+    def _rate(self) -> Reply | None:
+        """A sliding window over a deque. No dependency, no background sweep.
+
+        Old timestamps are dropped on the way in, so the deque cannot grow past the limit and
+        nothing has to clean up after an idle hour.
+        """
+        if not self.rate_limit:
+            return None
+        # `_clock.now` and not `time.time`: an invariant test enforces the single clock, and the
+        # reason applies here too — a rate-limit test that had to sleep for a minute is a test
+        # that gets deleted.
+        at = now()
+        while self._hits and at - self._hits[0] > 60.0:
+            self._hits.popleft()
+        if len(self._hits) >= self.rate_limit:
+            return error_reply(429, f"more than {self.rate_limit} requests a minute — "
+                                    f"slow down", "rate_limited")
+        self._hits.append(at)
+        return None

taskops/transports/http/projects.py

@@ -0,0 +1,116 @@
+"""Many boards on one port: `/<project>/api/...` and `/<project>/` for each project's UI.
+
+The whole design is one sentence: a project is the router that already exists, MOUNTED. This
+module splits the first path segment off, finds the project it names, and hands the request to
+`router.build` with the prefix trimmed — so every endpoint, the SSE feed and the websocket work
+under a prefix without a single one of them learning that prefixes exist.
+
+**Isolation is structural, not checked per endpoint.** A mounted router is bound to one root, so
+a request that arrived under `/axion/` has no way to name another project's store: the only path
+a route ever sees has already had its prefix removed. The name is validated against a strict
+pattern BEFORE the filesystem is touched, so `..` and `/` are refused as syntax rather than
+caught later by a resolve.
+
+**A miss is a bare 404.** Naming the projects that do exist would hand an unauthenticated caller
+the list of every board on the server, which is exactly the enumeration a per-project token is
+there to prevent. The reply says nothing, including whether the name was wrong or the secret was.
+
+**Narration is isolated too, and not by this file.** `WireMessage` (a narration delta) rides a
+process-global broadcast, so for a while a browser watching one board could see the prose of a
+report being written on another — the one leak this design had. It was closed on the contract:
+a wire message carries the `root` that emitted it, and `usecases.feed.follow` yields only the
+ones matching its own root (a message without a root is dropped). This module still knows
+nothing about frames, which is exactly why the filter is not here — it never sees one.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import replace
+from pathlib import Path
+from urllib.parse import urlencode
+
+from ..._errors import TaskopsError
+from ...usecases import locate
+from ._wire import Reply, Request, Route, error_reply
+from .policy import Policy
+from .router import build
+
+__all__ = ["mount", "NAME", "TOKEN_FILE"]
+
+NAME = re.compile(r"^[a-z0-9-]{1,40}$")
+"""What may name a project. Deliberately narrower than "a valid directory name": lowercase,
+digits and dashes only, so a project name is also a URL segment nobody has to escape — and
+`..`, `/`, an empty string and a leading dot are all refused by the pattern itself."""
+
+TOKEN_FILE = "token"
+"""The project's secret, `0600`, minted by `taskops serve init`. A project without one is not
+served AT ALL, rather than served open: this transport is meant to face the internet, and the
+failure mode of the alternative is a board that is public because a file was missing."""
+
+
+def mount(root: Path, *, readonly: bool = False, rate_limit: int = 0) -> Route:
+    """The root dispatcher for a directory of projects.
+
+    Routers are CACHED per project. Building one opens a store, so constructing it per request
+    would open and close sqlite on every poll of every board.
+    """
+    home = Path(root).expanduser().resolve()
+    cache: dict[str, tuple[Policy, Route]] = {}
+
+    def dispatch(request: Request) -> Reply:
+        name, rest = _split(request.path)
+        found = _project(home, name)
+        if found is None:
+            return error_reply(404, "no such project", "no_such_project")
+        if name not in cache:
+            policy = Policy(token=_token(found), readonly=readonly, rate_limit=rate_limit)
+            cache[name] = (policy, build(found, policy, base=f"/{name}/"))
+        policy, route = cache[name]
+        if not rest:
+            # The redirect is gated too. It is a reply about a project, so handing it to an
+            # unauthenticated caller would make `/name` a working existence oracle for every
+            # board on the server — the one thing the bare 404 above exists to deny.
+            return policy.check(request) or _redirect(f"/{name}/", request)
+        return route(replace(request, path=rest))
+
+    return dispatch
+
+
+def _split(path: str) -> tuple[str, str]:
+    """`/axion/api/board` -> `axion`, `/api/board`. An empty rest means the prefix had no
+    trailing slash, which is a redirect rather than a route — the UI's relative URLs would
+    otherwise resolve one level too high."""
+    name, slash, rest = path.lstrip("/").partition("/")
+    return name, f"/{rest}" if slash else ""
+
+
+def _project(home: Path, name: str) -> Path | None:
+    """The project directory, or None. The pattern is checked BEFORE any path is built.
+
+    `locate` walking UP is the subtlety: a plain directory under the root would resolve to some
+    ancestor project, so the answer only counts when it is the directory we asked about.
+    """
+    if not NAME.match(name):
+        return None
+    candidate = home / name
+    try:
+        found = locate(candidate)
+    except (TaskopsError, OSError):
+        return None
+    return candidate if found == candidate and _token(candidate) else None
+
+
+def _token(project: Path) -> str:
+    try:
+        return (project / TOKEN_FILE).read_text(encoding="utf-8").strip()
+    except OSError:
+        return ""
+
+
+def _redirect(location: str, request: Request) -> Reply:
+    """308 and not 302: the method must survive, or a POST to `/axion` would silently become a
+    GET. The query is carried across by hand — a redirect that dropped it would strip the
+    `?token=` out of the very link `serve init` printed, and the board would 401 on arrival."""
+    query = urlencode(request.query)
+    return Reply(status=308, headers={"Location": f"{location}?{query}" if query else location})

taskops/transports/http/reports.py

@@ -0,0 +1,75 @@
+"""The three report endpoints: the index, one report's markdown, and narrating one.
+
+Their own module rather than three more functions in `api.py`, because they are the only
+endpoints that touch a FILE — a report is written to disk and committed, unlike every other
+projection here, which is regenerated on demand. Grouping them keeps that difference visible.
+
+`POST /api/report/digest` is the one endpoint in taskops that costs money and takes MINUTES:
+it shells out to `claude`. It is a POST for exactly that reason — a write is refused under
+`--readonly` by the policy, by method, so a board on a screen in a room cannot spend an API key
+by being looked at.
+
+It does not WAIT for it, though. It starts the narration and answers immediately; the prose
+arrives on `/api/live` as it is written. Holding the response open for a multi-minute model
+call was the whole bug: the browser showed a mute spinner, the file said `_pendiente_`
+throughout, and a connection that dropped took the only feedback there was with it.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from ...usecases import narration, parse_date, read_report, report_index
+from ._wire import Reply, Request, json_reply
+from .api import guarded
+
+__all__ = ["get_report", "get_reports", "post_digest"]
+
+
+def get_reports(root: Path, request: Request) -> Reply:
+    """Every report on disk, newest first. Rows only — no bodies.
+
+    Thirty days of dossiers is a megabyte of markdown, and the list on the left of the screen
+    shows a label and two badges. The body arrives when a row is clicked.
+    """
+    return guarded(lambda: json_reply(report_index(root)))
+
+
+def get_report(root: Path, request: Request) -> Reply:
+    """A day's written dossier, and whether the day outran it.
+
+    `?date=` is optional and defaults to today, like the CLI — the endpoint answers for a day
+    that was never written up as readily as for one that was, so a UI can show the report and
+    the "not written yet" state through one call instead of probing for a 404.
+    """
+    return guarded(lambda: json_reply(read_report(root, request.param("date"))))
+
+
+def post_digest(root: Path, request: Request) -> Reply:
+    """START narrating the report. Answers `{"status": "narrating", "label"}` at once.
+
+    Not the finished file, deliberately. The narration is minutes of a model writing, and the
+    only honest thing a request can return in that time is "it began" — the prose itself
+    arrives on `/api/live`, frame by frame, on the socket the board already holds. The UI shows
+    it appearing and refetches the file when the terminal frame lands.
+
+    The day is parsed HERE, before the thread starts, so a label nobody can read is still a 400
+    with the parser's own sentence in it rather than a `narration.failed` frame two seconds
+    later on a stream the caller may not even be watching.
+
+    `force` is the Regenerate button; without it an existing narration is refused, since a
+    person may have edited that prose. A second request while one is running is refused too
+    (409) — two models rewriting one file is corruption, not contention.
+    """
+    payload = request.payload()
+    label = str(payload.get("date") or payload.get("label") or "")
+    force = bool(payload.get("force"))
+
+    def run() -> Reply:
+        # A day, named explicitly: the button lives on a day's row, and a window selector is
+        # something the UI has no way to express yet.
+        day = parse_date(label)
+        return json_reply({"status": "narrating",
+                           "label": narration.start(root, day, force=force)})
+
+    return guarded(run)

taskops/transports/http/router.py

@@ -0,0 +1,90 @@
+"""Path and method -> a route. A TABLE, built once with the root and the policy bound in.
+
+Same shape as the MCP dispatch and for the same reason: the table is the surface, so adding an
+endpoint is a row here rather than a branch in a handler, and nothing can be reachable without
+appearing in a list somebody can read.
+"""
+
+from __future__ import annotations
+
+from functools import partial
+from pathlib import Path
+
+from . import agentapi, api, exchange, live, reports, static
+from ._wire import Reply, Request, Route, error_reply
+from .policy import Policy
+
+__all__ = ["build"]
+
+
+def _table(root: Path, policy: Policy) -> dict[tuple[str, str], Route]:
+    """THE surface, as data. Its own function so `build` stays a dispatcher and the table can
+    grow a row without the closure around it growing with it."""
+    return {
+        ("GET", "/api/config"): partial(_config, root, policy),
+        ("GET", "/api/board"): partial(api.get_board, root),
+        ("GET", "/api/fleet"): partial(api.get_fleet, root),
+        ("GET", "/api/standup"): partial(api.get_standup, root),
+        ("GET", "/api/task"): partial(api.get_task, root),
+        ("GET", "/api/search"): partial(api.get_search, root),
+        ("GET", "/api/activity"): partial(api.get_activity, root),
+        ("GET", "/api/report"): partial(reports.get_report, root),
+        ("GET", "/api/reports"): partial(reports.get_reports, root),
+        ("POST", "/api/report/digest"): partial(reports.post_digest, root),
+        ("POST", "/api/comment"): partial(api.post_comment, root),
+        ("POST", "/api/status"): partial(api.post_status, root),
+        ("GET", "/api/live"): partial(live.stream, root),
+        ("POST", "/api/sync"): partial(exchange.post_sync, root),
+        ("GET", "/api/sync"): partial(exchange.get_sync, root),
+        ("GET", "/api/report/file"): partial(exchange.get_report_file, root),
+        ("PUT", "/api/report/file"): partial(exchange.put_report_file, root),
+        ("POST", "/api/next"): partial(agentapi.post_next, root),
+        ("POST", "/api/update"): partial(agentapi.post_update, root),
+    }
+
+
+def build(root: Path, policy: Policy, base: str = "/") -> Route:
+    """The one function the server calls per request. Everything else is bound here.
+
+    `base` is the URL prefix this table was mounted under — `/` for `taskops ui`, `/<project>/`
+    for one board inside `taskops serve`. It never reaches a route: paths arrive already
+    trimmed, and the only thing that needs it is the `<base>` tag in `index.html`.
+    """
+    routes = _table(root, policy)
+
+    def dispatch(request: Request) -> Reply:
+        if refusal := policy.check(request):
+            return refusal
+        route = routes.get((request.method, request.path))
+        if route is not None:
+            return route(request)
+        if request.method == "GET" and not request.path.startswith("/api/"):
+            # Everything that is not the API is the single-page app, INCLUDING unknown paths:
+            # the UI routes in the browser, so a reload on /task/tk-1 must serve index.html
+            # rather than 404 — which is the classic broken-refresh bug in an SPA.
+            return static.serve(request.path, base)
+        return _no_route(request, routes)
+
+    return dispatch
+
+
+def _config(root: Path, policy: Policy, request: Request) -> Reply:
+    """`readonly` reaches the UI through the request rather than through module state, so the
+    endpoint stays a pure function of what it was given."""
+    marked = Request(method=request.method, path=request.path,
+                     query={**request.query, "_readonly": "1" if policy.readonly else "0"},
+                     headers=request.headers, body=request.body)
+    return api.config(root, marked)
+
+
+def _no_route(request: Request, routes: dict[tuple[str, str], Route]) -> Reply:
+    """405 when the path exists under another method, 404 otherwise.
+
+    The two send a caller to completely different places, and "not found" for a GET on a POST
+    route has cost everyone an afternoon at some point.
+    """
+    allowed = sorted({method for method, path in routes if path == request.path})
+    if allowed:
+        return error_reply(405, f"{request.path} accepts {', '.join(allowed)}",
+                           "method_not_allowed")
+    return error_reply(404, f"no route {request.path}", "no_such_route")

taskops/transports/http/server.py

@@ -0,0 +1,50 @@
+"""Constructing the server. The handler itself is `_handler`.
+
+`ThreadingHTTPServer` and not asyncio: the engine is synchronous by an enforced invariant, and a
+thread per connection is what lets a live websocket or SSE stream park in a generator without the
+sqlite underneath ever learning about it. A handful of threads for a handful of tabs is the right
+size — this is a local tool, not a service.
+"""
+
+from __future__ import annotations
+
+from http.server import ThreadingHTTPServer
+from pathlib import Path
+
+from ._handler import Handler
+from ._wire import Route
+from .policy import Policy
+from .router import build
+
+__all__ = ["build_server", "serve_route", "bound_port"]
+
+
+def build_server(host: str, port: int, root: Path, policy: Policy) -> ThreadingHTTPServer:
+    """A server over ONE project — what `taskops ui` opens."""
+    return serve_route(host, port, build(root, policy))
+
+
+def serve_route(host: str, port: int, route: Route) -> ThreadingHTTPServer:
+    """A server ready to `serve_forever`. Returned rather than run, so a test can bind port 0.
+
+    The route table is bound into a per-server handler SUBCLASS, because stdlib's server takes a
+    class and instantiates it per request — there is nowhere else to put the root and the policy
+    without making them module state, which two servers in one process (every test file here) would
+    then share.
+
+    Taking a `Route` rather than a root is what lets `taskops serve` reuse every line of this:
+    the multi-project dispatcher is just another `Request -> Reply`, so the socket half of the
+    transport did not have to learn that projects exist.
+    """
+
+    class Bound(Handler):
+        dispatch = staticmethod(route)
+
+    server = ThreadingHTTPServer((host, port), Bound)
+    server.daemon_threads = True
+    return server
+
+
+def bound_port(server: ThreadingHTTPServer) -> int:
+    """The port actually bound. With `--port 0` the OS chooses, and this is how it gets said."""
+    return int(server.socket.getsockname()[1])