mostlyright-data 0.9.0__py3-none-any.whl

mostlyright/data_harness/serving_http.py

@@ -0,0 +1,1031 @@
+"""The loopback transport for the serving surface. It carries requests; it decides nothing.
+
+This module is a TRANSPORT. It parses one HTTP request into the closed vocabulary ``serving.py``
+already defines, hands it to :func:`serving_edge.serve_read`, and renders the envelope that comes
+back. Every refusal it can produce is either a refusal the library already produced or a refusal
+about the REQUEST'S OWN SHAPE — a path this surface does not answer, a method it does not answer on
+that path, a body over the byte bound, a body that is not strict JSON, a field name the request
+vocabulary does not contain. No refusal here is about data, because nothing here looks at data.
+
+Like ``viewer.py``, it binds ``127.0.0.1`` and never a public interface, it adds no dependency
+(``http.server`` is the standard library, and ``pyproject.toml`` is untouched by this surface), and
+**it never executes anything it serves**: the bytes it hands back were sealed by the build path and
+replay-verified by ``serving.open_sealed_version`` before this module saw them.
+
+The server handles one request at a time. This keeps HTTP concurrency separate from the
+per-process read cap in ``governors.CapPolicy.max_concurrent_runs``. Process topology is outside
+this module.
+
+**There is no authentication off-switch.** :func:`build_server` refuses to start without an https
+verify URL, so an unauthenticated serving surface cannot be constructed from this module at all, and
+``mr-data serve`` refuses the same way one layer up.
+
+**The verify transport is a library-only injection point.** The parameter supplies response bytes;
+:func:`key_seam.verify_api_key` computes the verdict and rejects invalid status, redirects,
+transport faults, invalid or oversized JSON, and key-id mismatches.
+``mr-data serve`` never passes this parameter and no command-line option maps to it; the CLI's only
+verify configuration is a URL that must be https. The parameter exists because this environment has
+no reachable cloud verify surface, and a serving surface nobody has driven end to end is not a
+shipped serving surface.
+
+**The request vocabulary is closed, and it is the library's.** Two paths, two methods, one optional
+query key, four body fields:
+
+==========================  =========================================================
+Wire name                   What it becomes
+==========================  =========================================================
+``GET /v1/datasets/{id}``   ``serving_edge.serve_read(..., shape="describe")``
+``POST .../{id}/rows``      ``serving_edge.serve_read(..., shape="rows")``
+``?pin=`` / body ``pin``    the ``pin`` argument, whose grammar ``serving.resolve_pin`` owns
+body ``filter``             the ``predicates`` argument of ``serving.serve_rows``
+body ``offset``/``limit``   the window arguments of ``serving.serve_rows``
+==========================  =========================================================
+
+``filter`` is the one wire name that is not spelled the way the library spells it, for the reason
+P-01 renames ``candidate_digest`` to ``version_digest`` on the way out: a JSON key a production
+caller types is a user-visible string, and "filter" is what ``docs/VOCABULARY.md``'s plain register
+calls it — ``serving.py``'s own prose calls it the filter throughout. The rename happens once, in
+:func:`_request_from_body`, and the field it maps to is the library's single filter parameter. There
+is no second field, and a request naming anything outside the four is refused rather than ignored.
+
+A point lookup is not a third path. It is the same POST with an equality condition on every column
+of the sealed grain, exactly as ``serving.serve_rows`` documents.
+"""
+
+from __future__ import annotations
+
+import ipaddress
+import time
+from collections.abc import Callable
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from http.server import BaseHTTPRequestHandler, HTTPServer
+from pathlib import Path
+from typing import Any
+from urllib.parse import parse_qsl
+
+from mostlyright.data_harness import canonical, key_seam, serving, serving_edge
+from mostlyright.data_harness.governors import CapLedger
+
+#: A request body is a FILTER, not a payload, so the bound is in the spirit of
+#: :data:`key_seam.MAX_VERIFY_RESPONSE_BYTES` rather than of the bootstrap envelope's. It is checked
+#: twice: against the declared content length before a byte is read, and again while reading.
+#:
+#: This is below the library's theoretical maximum filter size and bounds attacker-controlled
+#: memory held per request.
+MAX_REQUEST_BYTES = 64 * 1024
+
+#: The largest dataset id and the largest pin this transport will carry. Both are the LIBRARY's
+#: numbers, referenced rather than restated: ``serving`` owns the grammar of both, checks both on
+#: every read whoever the caller is, and a transport that declared its own could only differ from
+#: the thing it is a transport for. They are re-exported under these names because a bound a caller
+#: reads about in this module's own documentation should be readable from this module.
+MAX_DATASET_ID_CHARS = serving.MAX_DATASET_ID_CHARS
+MAX_PIN_CHARS = serving.MAX_PIN_CHARS
+
+#: How long one request may hold this surface before it is dropped, in seconds.
+#:
+#: **The server is single-threaded by design, so the handler in front is the only handler.** Without
+#: a deadline, one connection that opens and then says nothing — no credential, no request line, not
+#: one byte — blocks ``rfile.readline`` forever and every other caller is refused service for as
+#: long as the socket is held. The bound-before-read rule on the body does not help on its own
+#: either: a request may declare a length under :data:`MAX_REQUEST_BYTES`, pass that check, and then
+#: never finish sending it.
+#:
+#: **It is ONE deadline over the WHOLE request, and not a timeout per read.** A per-read timeout is
+#: what ``socketserver`` gives a handler that sets :attr:`_ServingHandler.timeout`, and a caller
+#: that sends one byte every ``timeout - 1`` seconds renews it forever — in the request line, in the
+#: headers and in the body alike. So this number is taken once when the connection is accepted and
+#: shrinks across every segment of the request, in :class:`_DeadlineReader`, which sits in front of
+#: every read the handler and the standard library make.
+#:
+#: The number is generous for a legitimate caller on loopback, where a request is written in one
+#: pass, and short next to the roughly 30 ms a verified read costs. It bounds the request side only:
+#: the deadline is not running while this surface verifies a build, and it is not the writer's
+#: budget either — the answer to a request that ran out of time is still written.
+REQUEST_TIMEOUT_SECONDS = 10.0
+
+#: The one optional query key, on the discovery path only. A pinned discovery has to be expressible
+#: — ``serving.describe_dataset`` takes a pin like every other read — and a single closed key is the
+#: smallest thing that expresses it. Any other query key refuses; a query string on the rows path
+#: refuses, because a rows read carries its pin in the body with the rest of the request.
+DISCOVERY_QUERY_KEYS = frozenset({"pin"})
+
+#: The closed body vocabulary of a rows read. A name outside this set refuses rather than being
+#: ignored: a caller who misspells a filter and is silently served an unfiltered window has been
+#: given the wrong answer with a 200 on it.
+ROWS_BODY_KEYS = frozenset({"pin", "filter", "offset", "limit"})
+
+#: The refusal codes this transport authors. Every one of them is about the shape of the REQUEST;
+#: none is about data. They are declared as constants for the reason ``serving_edge``'s are: a
+#: status mapping should be a closed lookup rather than string matching on prose.
+REQUEST_PATH_REFUSAL_CODE = "SERVING_REQUEST_PATH"
+REQUEST_METHOD_REFUSAL_CODE = "SERVING_REQUEST_METHOD"
+REQUEST_DATASET_REFUSAL_CODE = "SERVING_REQUEST_DATASET"
+REQUEST_QUERY_REFUSAL_CODE = "SERVING_REQUEST_QUERY"
+REQUEST_SIZE_REFUSAL_CODE = "SERVING_REQUEST_SIZE"
+REQUEST_BODY_REFUSAL_CODE = "SERVING_REQUEST_BODY"
+REQUEST_FIELD_REFUSAL_CODE = "SERVING_REQUEST_FIELD"
+REQUEST_SHAPE_REFUSAL_CODE = "SERVING_REQUEST_SHAPE"
+REQUEST_FAULT_REFUSAL_CODE = "SERVING_REQUEST_FAULT"
+REQUEST_TIMEOUT_REFUSAL_CODE = "SERVING_REQUEST_TIMEOUT"
+
+
+@dataclass(frozen=True)
+class ServingPath:
+    """One path this surface answers: its template, its method, and the read shape it becomes."""
+
+    method: str
+    template: str
+    shape: str
+
+
+#: The two paths, as data. Routing matches a template segment by segment rather than doing string
+#: surgery on ``self.path``, so a path this table does not name cannot be reached by any spelling of
+#: it, and adding a third shape means adding a row here and a shape ``serving_edge.READ_SHAPES``
+#: already admits.
+SERVING_PATHS = (
+    ServingPath(
+        method="GET", template="/v3/datasets/{dataset_id}/tables/{table_id}", shape="describe"
+    ),
+    ServingPath(
+        method="POST",
+        template="/v3/datasets/{dataset_id}/tables/{table_id}/rows",
+        shape="rows",
+    ),
+)
+
+#: How one refusal code becomes one status code. Closed, and every code not named here is a 400:
+#: the caller asked for something this surface will not do, and the envelope says which.
+#:
+#: ``SERVING_QUOTA_UNREADABLE`` and ``SERVING_READ_COST`` are not listed, so both use the default
+#: 400 status.
+STATUS_BY_REFUSAL_CODE = {
+    serving_edge.CREDENTIAL_REFUSAL_CODE: 401,
+    serving_edge.QUOTA_REFUSAL_CODE: 429,
+    "SERVING_DATASET_UNKNOWN": 404,
+    "SERVING_VERSION_UNKNOWN": 404,
+    "SERVING_PIN_DATASET": 404,
+    "SERVING_TABLE_SCOPE_MISMATCH": 404,
+    REQUEST_PATH_REFUSAL_CODE: 404,
+    REQUEST_METHOD_REFUSAL_CODE: 405,
+    REQUEST_TIMEOUT_REFUSAL_CODE: 408,
+    REQUEST_FAULT_REFUSAL_CODE: 500,
+}
+
+#: What a refusal this table does not name answers with.
+DEFAULT_REFUSAL_STATUS = 400
+
+#: Read in whole chunks so a body is bounded WHILE it is read and not only after. The chunk is small
+#: enough that a caller cannot make this surface allocate more than the bound plus one chunk.
+_READ_CHUNK_BYTES = 8 * 1024
+
+_LOOPBACK_RULE = (
+    "the serving surface binds loopback only, so a bind address must be a loopback address "
+    "(use 127.0.0.1)"
+)
+
+
+class ServingHttpError(RuntimeError):
+    """The transport is misconfigured, so no socket may be bound from it.
+
+    Raised only for an operator configuration fault — a bind address that is not loopback, or a
+    verify URL that is not a plain absolute https URL. It is never a rejected caller: a rejected
+    caller is a refusing :class:`serving.ServingResult` rendered with a status code, exactly as a
+    rejected key is a denying :class:`key_seam.KeyVerdict` rather than an exception.
+    """
+
+
+def _plain_single_line(value: Any, limit: int) -> bool:
+    """Whether ``value`` is one plain line within ``limit`` characters.
+
+    One line of delegation, on purpose. The rule is ``serving._one_plain_line``, which is
+    ``deploy._PLAIN_LINE`` (``deploy.py:63``) with a length bound: a control character in a dataset
+    id or a pin would otherwise be free to reach a refusal sentence, and from there any stream a
+    caller of this library writes to. This module used to spell the same rule out by hand, and a
+    hand-spelled copy of a security rule is a copy that can be relaxed on one side only.
+
+    It is applied to every piece of a request this transport reads out of a URL **or a body**. The
+    body is not the safer of the two: it is the one bounded by nothing but
+    :data:`MAX_REQUEST_BYTES`.
+    """
+
+    return serving._one_plain_line(value, limit)
+
+
+def _refused(dataset_id: str, pin: str, reason: str, code: str) -> serving.ServingResult:
+    """Turn one request-shape refusal into the one envelope every serving caller already renders.
+
+    Both digests are null, and that is the honest answer: a refusal taken out here never resolved a
+    pin, so there is no version to name. The bracketed code is appended in the idiom every
+    ``serving.py`` and ``serving_edge.py`` refusal already uses, so :data:`STATUS_BY_REFUSAL_CODE`
+    is a lookup rather than a guess about prose.
+    """
+
+    return serving.ServingResult(
+        ok=False,
+        refusals=(f"{reason} [{code}]",),
+        status=serving.STATUS_REFUSED,
+        dataset_id=dataset_id,
+        pin=pin,
+        pin_kind=None,
+        version_id=None,
+        version_number=None,
+        version_digest=None,
+        table_digest=None,
+        payload=None,
+    )
+
+
+def _timed_out() -> serving.ServingResult:
+    """Return the common response for a request that exceeds its deadline."""
+
+    return _refused(
+        "",
+        "",
+        "a read sends its whole request before this surface stops waiting for it",
+        REQUEST_TIMEOUT_REFUSAL_CODE,
+    )
+
+
+def _status_for(result: serving.ServingResult) -> int:
+    """Map one envelope onto one status code, through the closed table and nothing else.
+
+    The first refusal carrying a code this table names decides. Order matters and is the library's:
+    ``serving_edge`` refuses at one gate with one reason, so a credential refusal and a quota
+    refusal are each a single-reason envelope, and a multi-reason envelope can only come from inside
+    the read core, where every code is a 400 anyway.
+    """
+
+    if result.ok:
+        return 200
+    for reason in result.refusals:
+        start = reason.rfind("[")
+        if start == -1 or not reason.endswith("]"):
+            continue
+        status = STATUS_BY_REFUSAL_CODE.get(reason[start + 1 : -1])
+        if status is not None:
+            return status
+    return DEFAULT_REFUSAL_STATUS
+
+
+def _match_template(path: str) -> tuple[str, str, str] | None:
+    """Return the template ``path`` matches and the dataset id it carries, or nothing.
+
+    Matching is segment by segment against :data:`SERVING_PATHS`, and the dataset id is taken from
+    the path EXACTLY as it arrived: nothing is percent-decoded, so a path cannot smuggle a byte past
+    the plain-line check by spelling it as an escape. Every dataset id ``serving._IDENT`` admits is
+    already URL-safe, so no legitimate caller needs an escape.
+    """
+
+    arrived = path.split("/")
+    for entry in SERVING_PATHS:
+        wanted = entry.template.split("/")
+        if len(arrived) != len(wanted):
+            continue
+        dataset_id: str | None = None
+        table_id: str | None = None
+        for got, expected in zip(arrived, wanted, strict=True):
+            if expected == "{dataset_id}":
+                dataset_id = got
+            elif expected == "{table_id}":
+                table_id = got
+            elif got != expected:
+                dataset_id = None
+                break
+        if dataset_id is not None and table_id is not None:
+            return entry.template, dataset_id, table_id
+    return None
+
+
+def _v3_coordinates_from_path(path: str) -> tuple[str, str | None] | None:
+    """Return every V3 coordinate a malformed or unsupported path still names.
+
+    A request need not match a serving template to name its Dataset parent.  Every nonempty parent
+    following ``/v3/datasets/`` is retained.  A child exists only after that parent's literal
+    ``tables`` segment; an unknown segment is not silently reclassified as a table.  A suffix after
+    a child is still an unsupported path that must not discard either requested coordinate.
+    """
+
+    segments = path.split("/")
+    if len(segments) < 4 or segments[:3] != ["", "v3", "datasets"] or not segments[3]:
+        return None
+    table_id = (
+        segments[5] if len(segments) > 5 and segments[4] == "tables" and segments[5] else None
+    )
+    return segments[3], table_id
+
+
+def _request_from_body(parsed: Any) -> dict[str, Any]:
+    """Map one parsed body onto the library's arguments, or refuse the body's shape.
+
+    This is the only place a wire name becomes a library name, and the only rename it performs is
+    ``filter`` to ``predicates``. Nothing here validates a column, an operator, a value or a window:
+    those all belong to ``serving.py``, which owns their grammar and their refusal wording.
+
+    **The pin is the one exception, and it is the transport's own bound rather than a second
+    grammar.** ``serving.resolve_pin`` still decides what a pin MEANS; this checks only that the
+    thing arriving is one plain line inside :data:`MAX_PIN_CHARS`, exactly as the discovery path
+    already checks the pin it reads out of the address. Without it the only bound on this field is
+    :data:`MAX_REQUEST_BYTES`, so the body could carry a pin of some sixty-four thousand arbitrary
+    characters — 256 times this transport's own declared bound — and control characters among them.
+
+    Raises:
+        ValueError: carrying the sentence and code the caller should see.
+    """
+
+    if parsed is None:
+        parsed = {}
+    if not isinstance(parsed, dict):
+        raise ValueError("a read's body is a JSON object of named request fields")
+    unknown = sorted(set(parsed) - ROWS_BODY_KEYS)
+    if unknown:
+        named = ", ".join(unknown)
+        raise ValueError(
+            f"a read names pin, filter, offset and limit, and this one also names {named}"
+        )
+    pin = parsed.get("pin", serving.PIN_CURRENT)
+    if not _plain_single_line(pin, MAX_PIN_CHARS):
+        # The offending value is not quoted back. It is the value that failed the plain-line rule,
+        # which is the value that must not reach a rendered line.
+        raise ValueError(
+            f"a version is asked for as one plain line of at most {MAX_PIN_CHARS} characters"
+        )
+    return {
+        "pin": pin,
+        "predicates": parsed.get("filter"),
+        "offset": parsed.get("offset", 0),
+        "limit": parsed.get("limit", serving.MAX_SERVED_ROWS),
+    }
+
+
+class _ServingServer(HTTPServer):
+    """A single-threaded stdlib server holding the one index, ledger and verify URL it serves.
+
+    Deliberately :class:`http.server.HTTPServer` and not ``ThreadingHTTPServer``: see the module
+    docstring's paragraph on the in-flight cap. That choice is exactly why
+    :data:`REQUEST_TIMEOUT_SECONDS` is not optional — with one handler, a request with no deadline
+    is a surface with no deadline.
+    """
+
+    def __init__(
+        self,
+        address: tuple[str, int],
+        handler: type,
+        *,
+        index: serving.VersionIndex,
+        index_path: Path | None,
+        ledger: CapLedger,
+        verify_url: str,
+        transport: key_seam.VerifyTransport | None,
+        timeout: float,
+    ) -> None:
+        super().__init__(address, handler)
+        # The index as it was when the surface was checked and bound. It is the fallback for a
+        # library caller that supplied no path; when there is a path, every read re-reads it, so
+        # ``current`` means current rather than current-as-of-start-up.
+        self.serving_index = index
+        self.serving_index_path = index_path
+        self.serving_timeout = timeout
+        self.serving_ledger = ledger
+        self.serving_verify_url = verify_url
+        # Held and never inspected. The one thing this object does is travel to
+        # ``serving_edge.serve_read``, which hands it to ``key_seam`` (P-02).
+        self.serving_transport = transport
+
+
+class _DeadlineReader:
+    """Every byte of one request read under ONE deadline, taken once and shrinking on every pass.
+
+    **A per-recv socket timeout is not a deadline, and the difference is the whole point of this
+    class.** ``socketserver.StreamRequestHandler.setup`` calls ``settimeout`` once with
+    :attr:`_ServingHandler.timeout`, and the number it passes bounds each individual ``recv`` rather
+    than the request. A caller that sends one byte every ``timeout - 1`` seconds renews that bound
+    forever and holds this single-threaded surface for as long as it cares to keep dripping —
+    through the request line, through the headers, and through the body alike.
+
+    The deadline lives in front of ``rfile``, where every segment of the request reads: the
+    request line ``BaseHTTPRequestHandler.handle_one_request`` reads, the headers
+    ``http.client.parse_headers`` reads, and the body :meth:`_ServingHandler._body` reads. One
+    absolute instant is taken when the connection is accepted; before every underlying read the
+    time still left is computed and put on the socket, and when nothing is left the read raises
+    ``TimeoutError`` instead of waiting again.
+
+    Two mechanics make that bound real rather than nominal, and both are about never blocking inside
+    one call for longer than the deadline allows:
+
+    * :meth:`read` goes through ``BufferedReader.read1``, which returns what one underlying read
+      returned rather than looping until it has the whole amount asked for.
+    * :meth:`readline` goes through ``peek``, which does at most one underlying read, and then takes
+      the line out of the buffer. ``BufferedReader.readline`` would instead sit inside a single call
+      until a newline arrives, renewing the socket timeout on every packet.
+
+    Both raise ``TimeoutError`` and set :attr:`expired`, which is how the handler knows to answer
+    the 408 envelope when the deadline expires before handler code runs.
+
+    The shape is ``coordinator._receive_exact``'s (``coordinator.py:962-990``), which is this
+    repository's existing answer to the same problem on its own transport: one absolute instant, the
+    time still left recomputed before every underlying read, and ``TimeoutError`` when there is
+    none. It is restated over a file object rather than reused because the reads being bounded are
+    the standard library's, and ``BaseHTTPRequestHandler`` makes them through ``rfile``.
+    """
+
+    def __init__(self, source: Any, connection: Any, seconds: float) -> None:
+        self._source = source
+        self._connection = connection
+        self._seconds = seconds
+        self._deadline = time.monotonic() + seconds
+        #: Whether this request ran out of time. Read by the handler, never by a caller.
+        self.expired = False
+
+    @property
+    def seconds(self) -> float:
+        """The whole deadline, for the writer that must not inherit what a read had left."""
+
+        return self._seconds
+
+    def _arm(self) -> None:
+        """Put the time still left on the socket, or refuse to wait at all."""
+
+        left = self._deadline - time.monotonic()
+        if left <= 0:
+            self.expired = True
+            raise TimeoutError("this read did not arrive in time")
+        self._connection.settimeout(left)
+
+    def read(self, size: int = -1) -> bytes:
+        """Read up to ``size`` bytes, or until end of stream, inside the deadline."""
+
+        out = bytearray()
+        while size < 0 or len(out) < size:
+            want = _READ_CHUNK_BYTES if size < 0 else min(size - len(out), _READ_CHUNK_BYTES)
+            self._arm()
+            try:
+                chunk = self._source.read1(want)
+            except TimeoutError:
+                self.expired = True
+                raise
+            if not chunk:
+                break
+            out += chunk
+        return bytes(out)
+
+    def readline(self, limit: int = -1) -> bytes:
+        """Read one line, at most ``limit`` bytes of it, inside the deadline."""
+
+        out = bytearray()
+        while limit < 0 or len(out) < limit:
+            self._arm()
+            try:
+                available = self._source.peek(1)
+            except TimeoutError:
+                self.expired = True
+                raise
+            if not available:
+                break
+            newline = available.find(b"\n")
+            take = len(available) if newline < 0 else newline + 1
+            if limit >= 0:
+                take = min(take, limit - len(out))
+            # Out of the buffer ``peek`` just filled, so this read never touches the socket.
+            out += self._source.read(take)
+            if newline >= 0 and take == newline + 1:
+                break
+        return bytes(out)
+
+    def close(self) -> None:
+        """Close the stream this wraps: ``socketserver.StreamRequestHandler.finish`` calls it."""
+
+        self._source.close()
+
+    @property
+    def closed(self) -> bool:
+        return bool(self._source.closed)
+
+
+class _ServingHandler(BaseHTTPRequestHandler):
+    """One request, parsed into the closed vocabulary and handed to the edge.
+
+    Nothing in this class reads a run directory, opens a sealed version, or looks at a column. It
+    turns bytes into arguments and an envelope into a status code.
+    """
+
+    #: The class default, used when this handler is constructed without a server that carries one.
+    #: ``socketserver.StreamRequestHandler`` reads this attribute in ``setup`` and calls
+    #: ``settimeout`` with it; the stdlib's own default is ``None``, which is no deadline at all.
+    timeout: float = REQUEST_TIMEOUT_SECONDS
+
+    #: Whether this request has been answered. :meth:`_respond` is the only writer, and
+    #: :meth:`handle_one_request` reads it to decide whether a missed deadline still owes an
+    #: envelope. One answer per request either way: the connection is closed after one.
+    _answered: bool = False
+
+    #: The one deadline every read of this request draws down. :meth:`setup` installs it.
+    serving_deadline: _DeadlineReader
+
+    def setup(self) -> None:
+        """Put ONE deadline in front of the request before a byte of it is read.
+
+        The number is the server's, so one value configures the surface and a test can drive a short
+        one. It is applied twice over, and the second is the one that binds: ``self.timeout`` gives
+        the stdlib its per-recv socket timeout, and :class:`_DeadlineReader` then wraps ``rfile`` so
+        the request line, the headers and the body all draw down a single shrinking deadline. A drip
+        renews the first; nothing renews the second.
+        """
+
+        self.timeout = getattr(self.server, "serving_timeout", REQUEST_TIMEOUT_SECONDS)
+        super().setup()
+        # ``send_response_only`` reads this, and a deadline missed before the request line arrives
+        # means ``parse_request`` never set it. Its own default would suppress the 408's status
+        # line; a request that does parse overwrites this on the next statement it runs.
+        self.request_version = self.protocol_version
+        self.serving_deadline = _DeadlineReader(self.rfile, self.connection, float(self.timeout))
+        self.rfile = self.serving_deadline  # type: ignore[assignment]
+
+    def handle_one_request(self) -> None:
+        """Run the stdlib's request loop, and answer a deadline it swallowed.
+
+        ``BaseHTTPRequestHandler.handle_one_request`` catches ``TimeoutError`` from the request line
+        and header reads, logs it and closes the connection without answering. Closing is the half
+        that protects the surface and it already happened; this adds the half a caller sees, so a
+        request that ran out of time in any segment gets the same envelope and the same 408 as one
+        that ran out of time in its body.
+
+        A caller that abandoned its request may well have abandoned the socket too, so the write is
+        allowed to fail: an unreachable caller is not an event this surface reports. Letting the
+        ``OSError`` out would reach ``socketserver.BaseServer.handle_error``, which prints a
+        traceback to stderr — the one thing :meth:`log_message` exists to prevent.
+        """
+
+        super().handle_one_request()
+        if self.serving_deadline.expired and not self._answered:
+            result = _timed_out()
+            try:
+                self._respond(_status_for(result), result.canonical_bytes())
+            except OSError:
+                self.close_connection = True
+
+    def log_message(self, *_args: object) -> None:  # silence default stderr access logging
+        """Say nothing.
+
+        ``viewer.py:138`` silences the same log for tidiness; here it is security-load-bearing. A
+        default access log line carries the request line, and every request to this surface is
+        credential-bearing — an operator who later adds a log line must decide, deliberately, what
+        goes in it. Nothing this handler writes anywhere contains the presented key.
+        """
+
+        return
+
+    # ---- the pieces of the request ---------------------------------------------------------
+
+    @property
+    def _server(self) -> _ServingServer:
+        return self.server  # type: ignore[return-value]
+
+    def _key(self) -> tuple[str | None, str | None]:
+        """Return the presented credential, or the reason there is not exactly one.
+
+        Read from :data:`key_seam.API_KEY_HEADER` and from nowhere else — never a query string,
+        never a path segment — for the reason recorded at ``key_seam.py:76-78``: those are logged by
+        every proxy, load balancer and browser history on the route. Two headers is not one
+        credential, so it refuses rather than picking one.
+        """
+
+        presented = self.headers.get_all(key_seam.API_KEY_HEADER) or []
+        if len(presented) > 1:
+            return None, "a read presents one credential, and this one presented several"
+        if not presented or not presented[0]:
+            return None, None
+        return presented[0], None
+
+    def _body(self) -> bytes:
+        """Read the request body, bounded before the read, during it, and in time.
+
+        The byte bound and the deadline are two different bounds and neither implies the other. A
+        body that declares 200 bytes and sends 199 of them is inside every byte bound this module
+        has and would hold the surface forever. The byte bound is this method's, checked twice —
+        against the declared length before a byte is read and against what arrives while it is being
+        read. The deadline is NOT this method's: it belongs to :class:`_DeadlineReader`, which
+        ``setup`` put in front of every read this request makes, so the body draws down the same
+        shrinking deadline the request line and the headers already drew down. This method reads,
+        counts, and lets the timeout out.
+
+        Raises:
+            ValueError: carrying the sentence the caller should see.
+            TimeoutError: when the body does not arrive inside the deadline. The handler turns it
+                into the one envelope with a 408, because an unfinished request is the caller's
+                fault and is not an internal fault.
+        """
+
+        if self.headers.get("Transfer-Encoding"):
+            # A chunked body has no declared length, so there is no bound to check before reading
+            # one. This surface takes a filter, and a filter has a length.
+            raise ValueError("a read declares the length of its body")
+        declared = self.headers.get("Content-Length")
+        if declared is None:
+            return b""
+        if not declared.isascii() or not declared.isdigit():
+            raise ValueError("a read declares the length of its body as a whole number of bytes")
+        length = int(declared)
+        if length > MAX_REQUEST_BYTES:
+            # Refused BEFORE a byte is read: the point of the bound is that an oversized body never
+            # reaches this process's memory, so checking it afterwards would be checking nothing.
+            raise ValueError(
+                f"a read's body is at most {MAX_REQUEST_BYTES} bytes, and this one says it is more"
+            )
+        chunks: list[bytes] = []
+        remaining = length
+        read = 0
+        while remaining > 0:
+            # The reader in front of this call carries the deadline and raises ``TimeoutError``
+            # when it is gone. The loop is here for the byte bound, which needs to be checked on
+            # what arrives and not only on what was declared.
+            chunk = self.rfile.read(min(remaining, _READ_CHUNK_BYTES))
+            if not chunk:
+                break
+            read += len(chunk)
+            if read > MAX_REQUEST_BYTES:
+                # Bounded while reading too, so a declared length that lies is bounded by the
+                # same number the declaration was checked against.
+                raise ValueError(f"a read's body is at most {MAX_REQUEST_BYTES} bytes")
+            chunks.append(chunk)
+            remaining -= len(chunk)
+        return b"".join(chunks)
+
+    # ---- the answer --------------------------------------------------------------------------
+
+    def _answer_unmapped(self) -> serving.ServingResult:
+        """Turn this request into one envelope. Every path out of here is an envelope."""
+
+        path, _, query = self.path.partition("?")
+        matched = _match_template(path)
+        if matched is None:
+            return _refused(
+                "",
+                "",
+                "this surface answers a dataset's description and a dataset's rows, and nothing "
+                "else",
+                REQUEST_PATH_REFUSAL_CODE,
+            )
+        template, dataset_id, table_id = matched
+        if not _plain_single_line(dataset_id, MAX_DATASET_ID_CHARS) or not _plain_single_line(
+            table_id, MAX_DATASET_ID_CHARS
+        ):
+            return _refused(
+                "",
+                "",
+                "a dataset is named by one plain line of at most "
+                f"{MAX_DATASET_ID_CHARS} characters",
+                REQUEST_DATASET_REFUSAL_CODE,
+            )
+        entry = next(
+            (
+                item
+                for item in SERVING_PATHS
+                if item.template == template and item.method == self.command
+            ),
+            None,
+        )
+        if entry is None:
+            return _refused(
+                dataset_id,
+                "",
+                "this path answers a different method than the one this read used",
+                REQUEST_METHOD_REFUSAL_CODE,
+            )
+
+        if entry.shape == "describe":
+            request = self._discovery_request(query)
+        else:
+            if query:
+                return _refused(
+                    dataset_id,
+                    "",
+                    "a rows read carries its whole request in its body, never in the address",
+                    REQUEST_QUERY_REFUSAL_CODE,
+                )
+            request = self._rows_request()
+        if isinstance(request, serving.ServingResult):
+            return request
+
+        key, refusal = self._key()
+        if refusal is not None:
+            return _refused(dataset_id, str(request["pin"]), refusal, REQUEST_FIELD_REFUSAL_CODE)
+
+        # The whole request, handed over. The key check and the quota check are BOTH on the other
+        # side of this call, in the order ``serving_edge`` proves; nothing above this line reads
+        # anything, and a refused read opens no run directory.
+        return serving_edge.serve_read(
+            self._server.serving_index,
+            table_id,
+            request.pop("pin"),
+            shape=entry.shape,
+            index_path=self._server.serving_index_path,
+            ledger=self._server.serving_ledger,
+            now=datetime.now(UTC),
+            key=key,
+            verify_url=self._server.serving_verify_url,
+            transport=self._server.serving_transport,
+            parent_dataset_id=dataset_id,
+            api_version="v3",
+            **request,
+        )
+
+    def _answer(self) -> serving.ServingResult:
+        """Answer once, then attach V3 Dataset/Table coordinates to every mapped refusal."""
+
+        result = self._answer_unmapped()
+        path, _, _query = self.path.partition("?")
+        coordinates = _v3_coordinates_from_path(path)
+        if coordinates is None:
+            return result
+        dataset_id, table_id = coordinates
+        return serving_edge.v3_coordinates(result, dataset_id, table_id)
+
+    def _discovery_request(self, query: str) -> dict[str, Any] | serving.ServingResult:
+        """Read the discovery request out of the address: a pin, or Current."""
+
+        pairs = parse_qsl(query, keep_blank_values=True)
+        names = [name for name, _ in pairs]
+        if set(names) - DISCOVERY_QUERY_KEYS or len(names) != len(set(names)):
+            return _refused(
+                "",
+                "",
+                "a description is asked for with one optional pin and nothing else",
+                REQUEST_QUERY_REFUSAL_CODE,
+            )
+        pin = dict(pairs).get("pin", serving.PIN_CURRENT)
+        if not _plain_single_line(pin, MAX_PIN_CHARS):
+            return _refused(
+                "",
+                "",
+                f"a version is asked for as one plain line of at most {MAX_PIN_CHARS} characters",
+                REQUEST_QUERY_REFUSAL_CODE,
+            )
+        return {"pin": pin}
+
+    def _rows_request(self) -> dict[str, Any] | serving.ServingResult:
+        """Read the rows request out of the body: strict JSON, closed fields, nothing inferred."""
+
+        try:
+            raw = self._body()
+        except TimeoutError:
+            return _timed_out()
+        except ValueError as error:
+            return _refused("", "", str(error), REQUEST_SIZE_REFUSAL_CODE)
+        if not raw.strip():
+            parsed: Any = {}
+        else:
+            try:
+                # Strict on purpose, and the same parser ``key_seam`` verifies a verdict with:
+                # duplicate keys, byte-order marks, non-UTF-8 bytes and non-integer numbers all
+                # refuse, so a body two parsers would read differently is never acted on.
+                parsed = canonical.parse_json(raw)
+            except canonical.CanonicalJSONError:
+                return _refused(
+                    "",
+                    "",
+                    "a read's body is strict JSON, and this one could not be read as any",
+                    REQUEST_BODY_REFUSAL_CODE,
+                )
+        try:
+            return _request_from_body(parsed)
+        except ValueError as error:
+            return _refused("", "", str(error), REQUEST_FIELD_REFUSAL_CODE)
+
+    # ---- the wire ----------------------------------------------------------------------------
+
+    def _respond(self, status: int, body: bytes) -> None:
+        """Write one response: a status line, two headers, and the envelope.
+
+        The header set is closed and deterministic. ``send_response_only`` is used rather than
+        ``send_response`` so no ``Server`` and no ``Date`` header is emitted: the first would
+        publish this deployment's Python version to anyone who asks, and the second would make the
+        response bytes time-varying. No header echoes anything the caller sent, and there is no
+        cookie on this surface because there is no session on it — the credential is per request.
+        """
+
+        self._answered = True
+        # The deadline bounds the REQUEST, and this is the answer to it. Whatever few milliseconds
+        # the last read had left are not the writer's budget, so the socket goes back to the whole
+        # number before a byte of the envelope is written.
+        self.connection.settimeout(self.serving_deadline.seconds)
+        self.close_connection = True
+        self.send_response_only(status)
+        self.send_header("Content-Type", "application/json")
+        self.send_header("Content-Length", str(len(body)))
+        self.end_headers()
+        if getattr(self, "command", None) != "HEAD":
+            self.wfile.write(body)
+
+    def send_error(self, code: Any, message: Any = None, explain: Any = None) -> None:
+        """Answer the stdlib's own failure paths with the same envelope, never an HTML page.
+
+        ``BaseHTTPRequestHandler`` calls this for a malformed request line, an over-long header, an
+        unsupported HTTP version and an unimplemented method, and its default body is an HTML page
+        that quotes the caller's own bytes back at them. Both halves of that are refused here: the
+        body is the one envelope, and ``message`` and ``explain`` are dropped unread, because a
+        response is not a place to echo what arrived.
+        """
+
+        status = int(code)
+        result = _refused(
+            "",
+            "",
+            "this request was not in a shape this surface answers",
+            REQUEST_SHAPE_REFUSAL_CODE,
+        )
+        path = getattr(self, "path", "")
+        coordinates = (
+            _v3_coordinates_from_path(path.partition("?")[0]) if isinstance(path, str) else None
+        )
+        if coordinates is not None:
+            dataset_id, table_id = coordinates
+            result = serving_edge.v3_coordinates(result, dataset_id, table_id)
+        self._respond(status, result.canonical_bytes())
+
+    def _handle(self) -> None:
+        try:
+            result = self._answer()
+        except Exception:
+            # One broad boundary catch, in ``key_seam.verify_api_key``'s idiom. Nothing about the
+            # exception reaches the caller: its message, its repr and its traceback could all carry
+            # a path, a column or the credential that was in scope when it was raised.
+            result = _refused(
+                "",
+                "",
+                "this read could not be completed",
+                REQUEST_FAULT_REFUSAL_CODE,
+            )
+            path = getattr(self, "path", "")
+            coordinates = (
+                _v3_coordinates_from_path(path.partition("?")[0]) if isinstance(path, str) else None
+            )
+            if coordinates is not None:
+                dataset_id, table_id = coordinates
+                result = serving_edge.v3_coordinates(result, dataset_id, table_id)
+        self._respond(_status_for(result), result.canonical_bytes())
+
+    do_GET = _handle
+    do_POST = _handle
+    do_HEAD = _handle
+    do_PUT = _handle
+    do_DELETE = _handle
+    do_PATCH = _handle
+    do_OPTIONS = _handle
+    do_TRACE = _handle
+
+
+def _require_loopback(host: str) -> None:
+    """Refuse a bind address that is not loopback, before any socket exists.
+
+    The rule is ``cli._require_loopback_host``'s and the wording carries the same word, but the
+    check lives here as well because this is a library entry point: a guard that trusts its caller
+    to have already checked is not a guard, and ``build_server`` is reachable without a command
+    line.
+    """
+
+    try:
+        address = ipaddress.ip_address(host)
+    except ValueError as error:
+        raise ServingHttpError(f"{host!r} is not an IP address; {_LOOPBACK_RULE}") from error
+    if not address.is_loopback:
+        raise ServingHttpError(f"{host} is not a loopback address; {_LOOPBACK_RULE}")
+
+
+def build_server(
+    *,
+    index: serving.VersionIndex,
+    index_path: Path | None = None,
+    ledger: CapLedger,
+    verify_url: str,
+    host: str = "127.0.0.1",
+    port: int = 0,
+    transport: key_seam.VerifyTransport | None = None,
+    timeout: float = REQUEST_TIMEOUT_SECONDS,
+) -> HTTPServer:
+    """Bind the serving surface and hand back the bound server, without serving anything yet.
+
+    The entry point is split in two — this, and :func:`serve_forever` — for one reason: a caller
+    that asked for an ephemeral port has to be able to learn which port it got BEFORE the loop
+    starts, and a test that cannot learn the port cannot drive a real socket. ``viewer.py`` gets
+    away without the split because it prints its URL and opens a browser; this surface is called by
+    tests and by a CLI, and both need the address back. ``server.server_address[1]`` reports the
+    actually bound port, so ``port=0`` is usable.
+
+    ``verify_url`` is REQUIRED and is checked through ``key_seam``'s own https policy rather than a
+    second one, so a surface that cannot verify a key cannot be started: there is no unauthenticated
+    mode of this server and no argument that produces one.
+
+    ``index_path`` is the document ``index`` was parsed from, and giving it is what makes
+    ``current`` mean current: with a path, every read re-reads and re-parses the file, so a move of
+    Current is seen by a process that was already running. Without one, this server answers the
+    snapshot it was handed for its whole life — correct for a caller that built an index in memory,
+    and wrong for a long-lived surface over a document an operator maintains, which is why
+    ``mr-data serve`` always passes it.
+
+    ``transport`` is the P-02 seam. It is handed to :func:`serving_edge.serve_read` and is never
+    inspected, wrapped or branched on here; ``key_seam`` still computes every verdict. See the
+    module docstring.
+
+    ``timeout`` is the per-request deadline in seconds, defaulting to
+    :data:`REQUEST_TIMEOUT_SECONDS`. It is a parameter so a test can drive a short one; it is not an
+    off-switch, and ``None`` is not a value it takes.
+
+    Raises:
+        ServingHttpError: when ``host`` is not a loopback address, or when ``timeout`` is not a
+            positive number of seconds.
+        key_seam.KeySeamError: when ``verify_url`` is not a plain absolute https URL.
+    """
+
+    _require_loopback(host)
+    if not isinstance(timeout, int | float) or isinstance(timeout, bool) or timeout <= 0:
+        # A surface with no deadline is the defect this parameter exists to prevent, so the one
+        # value that reintroduces it is refused rather than passed to ``settimeout``.
+        raise ServingHttpError(
+            "the serving surface answers one request at a time, so a request deadline is a "
+            "positive number of seconds"
+        )
+    checked = key_seam._https_url(verify_url, "the verify URL")
+    return _ServingServer(
+        (host, port),
+        _ServingHandler,
+        index=index,
+        index_path=None if index_path is None else Path(index_path),
+        ledger=ledger,
+        verify_url=checked,
+        transport=transport,
+        timeout=float(timeout),
+    )
+
+
+def serve_forever(
+    *,
+    index: serving.VersionIndex,
+    index_path: Path | None = None,
+    ledger: CapLedger,
+    verify_url: str,
+    host: str = "127.0.0.1",
+    port: int = 0,
+    transport: key_seam.VerifyTransport | None = None,
+    timeout: float = REQUEST_TIMEOUT_SECONDS,
+    announce: Callable[[str], None] | None = None,
+) -> None:
+    """Bind the serving surface and serve it until interrupted.
+
+    The same keyword arguments :func:`build_server` takes, so there is one set of arguments to
+    reason about rather than two that have to be kept in step.
+
+    The served-address line is flushed immediately, in ``viewer.serve_notebook``'s shape and for its
+    reason: the port may be ephemeral, so a caller that starts this in the background has to read
+    that line to learn it, and a block-buffered pipe would withhold it for the life of the server.
+    """
+
+    server = build_server(
+        index=index,
+        index_path=index_path,
+        ledger=ledger,
+        verify_url=verify_url,
+        host=host,
+        port=port,
+        transport=transport,
+        timeout=timeout,
+    )
+    url = f"http://{host}:{server.server_address[1]}/"
+    if announce is None:
+        print(f"mr-data serve: serving {url} (Ctrl-C to stop)", flush=True)
+    else:
+        announce(url)
+    try:
+        server.serve_forever()
+    except KeyboardInterrupt:
+        pass
+    finally:
+        server.server_close()
+
+
+__all__ = [
+    "DEFAULT_REFUSAL_STATUS",
+    "DISCOVERY_QUERY_KEYS",
+    "MAX_DATASET_ID_CHARS",
+    "MAX_PIN_CHARS",
+    "MAX_REQUEST_BYTES",
+    "REQUEST_BODY_REFUSAL_CODE",
+    "REQUEST_DATASET_REFUSAL_CODE",
+    "REQUEST_FAULT_REFUSAL_CODE",
+    "REQUEST_FIELD_REFUSAL_CODE",
+    "REQUEST_METHOD_REFUSAL_CODE",
+    "REQUEST_PATH_REFUSAL_CODE",
+    "REQUEST_QUERY_REFUSAL_CODE",
+    "REQUEST_SHAPE_REFUSAL_CODE",
+    "REQUEST_SIZE_REFUSAL_CODE",
+    "REQUEST_TIMEOUT_REFUSAL_CODE",
+    "REQUEST_TIMEOUT_SECONDS",
+    "ROWS_BODY_KEYS",
+    "SERVING_PATHS",
+    "STATUS_BY_REFUSAL_CODE",
+    "ServingHttpError",
+    "ServingPath",
+    "build_server",
+    "serve_forever",
+]