codexLB-up 1.25.0b10__py3-none-any.whl

app/modules/proxy/capability_routing.py

@@ -0,0 +1,253 @@
+from __future__ import annotations
+
+import re
+from collections.abc import Collection, Mapping
+from dataclasses import dataclass
+from enum import StrEnum
+
+from app.core.clients.proxy import CODEX_LB_REQUIRED_CAPABILITY_HEADER, ProxyResponseError
+from app.core.errors import openai_error
+from app.core.types import JsonValue
+from app.core.utils.json_guards import is_json_mapping
+from app.modules.api_keys.service import ApiKeyData
+from app.modules.proxy.capability_lineage import (
+    CapabilityLineageAlias,
+    normalize_capability_lineage_aliases,
+)
+from app.modules.proxy.repo_bundle import ProxyRepoFactory
+
+REQUIRED_CAPABILITY_HEADER = CODEX_LB_REQUIRED_CAPABILITY_HEADER
+CODEX_PARENT_THREAD_ID_HEADER = "x-codex-parent-thread-id"
+CODEX_WINDOW_ID_HEADER = "x-codex-window-id"
+CAPABILITY_SIGNAL_UNTRUSTED_CODE = "capability_signal_untrusted"
+UNSUPPORTED_REQUIRED_CAPABILITY_CODE = "unsupported_required_capability"
+CAPABILITY_LINEAGE_UNAVAILABLE_CODE = "capability_lineage_unavailable"
+CAPABILITY_ROUTING_UNAVAILABLE_CODE = "capability_routing_unavailable"
+CAPABILITY_ROUTING_UNAVAILABLE_MESSAGE = "Required capability routing is unavailable; retry later."
+
+_TERMINAL_WINDOW_SLOT_RE = re.compile(r":\d+$")
+
+
+class RoutingCapability(StrEnum):
+    TRUSTED_CYBER = "trusted_cyber"
+
+
+@dataclass(frozen=True, slots=True)
+class RoutingIntent:
+    required_capabilities: frozenset[RoutingCapability] = frozenset()
+
+    @classmethod
+    def empty(cls) -> RoutingIntent:
+        return cls()
+
+    @classmethod
+    def requiring(cls, capability: RoutingCapability) -> RoutingIntent:
+        return cls(required_capabilities=frozenset({capability}))
+
+    @property
+    def requires_trusted_cyber(self) -> bool:
+        return RoutingCapability.TRUSTED_CYBER in self.required_capabilities
+
+
+@dataclass(frozen=True, slots=True)
+class CapabilityRoute:
+    require_security_work_authorized: bool
+    aliases: tuple[CapabilityLineageAlias, ...]
+
+
+class CapabilityRouter:
+    def __init__(self, repo_factory: ProxyRepoFactory) -> None:
+        self._repo_factory = repo_factory
+
+    async def route(
+        self,
+        intent: RoutingIntent,
+        *,
+        api_key_id: str | None,
+        aliases: Collection[CapabilityLineageAlias],
+    ) -> CapabilityRoute:
+        normalized_aliases = normalize_capability_lineage_aliases(aliases)
+        explicitly_required = intent.requires_trusted_cyber
+        if api_key_id is None or not normalized_aliases:
+            return CapabilityRoute(
+                require_security_work_authorized=explicitly_required,
+                aliases=normalized_aliases,
+            )
+
+        try:
+            async with self._repo_factory() as repositories:
+                repository = repositories.capability_lineage
+                if repository is None:
+                    raise RuntimeError("capability lineage repository is unavailable")
+                inherited_requirement = False
+                if not explicitly_required:
+                    inherited_requirement = await repository.is_required(
+                        capability=RoutingCapability.TRUSTED_CYBER.value,
+                        api_key_scope=api_key_id,
+                        aliases=normalized_aliases,
+                    )
+                required = explicitly_required or inherited_requirement
+                if required:
+                    marker_hashes = await repository.require(
+                        capability=RoutingCapability.TRUSTED_CYBER.value,
+                        api_key_scope=api_key_id,
+                        aliases=normalized_aliases,
+                    )
+                    if not marker_hashes:
+                        raise RuntimeError("capability lineage marker was not persisted")
+        except Exception as exc:
+            raise _capability_lineage_unavailable_error() from exc
+
+        return CapabilityRoute(
+            require_security_work_authorized=required,
+            aliases=normalized_aliases,
+        )
+
+
+def capability_lineage_aliases(
+    headers: Mapping[str, str],
+    *,
+    session_id: str | None = None,
+    turn_state: str | None = None,
+    previous_response_ids: Collection[str | None] = (),
+    client_metadata: JsonValue | None = None,
+) -> tuple[CapabilityLineageAlias, ...]:
+    aliases: list[CapabilityLineageAlias] = []
+    _append_alias(aliases, "session_header", session_id)
+    _append_alias(aliases, "turn_state", turn_state)
+    for previous_response_id in previous_response_ids:
+        _append_alias(aliases, "previous_response", previous_response_id)
+
+    parent_thread_ids = (
+        *_header_values(headers, CODEX_PARENT_THREAD_ID_HEADER),
+        *_metadata_string_values(client_metadata, CODEX_PARENT_THREAD_ID_HEADER),
+    )
+    for parent_thread_id in parent_thread_ids:
+        _append_alias(aliases, "codex_task", parent_thread_id)
+
+    window_ids = (
+        *_header_values(headers, CODEX_WINDOW_ID_HEADER),
+        *_metadata_string_values(client_metadata, CODEX_WINDOW_ID_HEADER),
+    )
+    for window_id in window_ids:
+        _append_alias(aliases, "codex_window", window_id)
+        stable_task_id = _TERMINAL_WINDOW_SLOT_RE.sub("", window_id.strip())
+        _append_alias(aliases, "codex_task", stable_task_id)
+    return normalize_capability_lineage_aliases(aliases)
+
+
+def parse_routing_intent(
+    headers: Mapping[str, str],
+    *,
+    api_key: ApiKeyData | None,
+    client_metadata: JsonValue | None = None,
+    header_values: Collection[str] | None = None,
+    client_metadata_values: Collection[JsonValue] | None = None,
+) -> RoutingIntent:
+    values: tuple[JsonValue, ...] = (
+        *(tuple(header_values) if header_values is not None else _header_values(headers, REQUIRED_CAPABILITY_HEADER)),
+        *(
+            tuple(client_metadata_values)
+            if client_metadata_values is not None
+            else _metadata_values(client_metadata, REQUIRED_CAPABILITY_HEADER)
+        ),
+    )
+    if not values:
+        return RoutingIntent.empty()
+    if api_key is None:
+        raise ProxyResponseError(
+            403,
+            openai_error(
+                CAPABILITY_SIGNAL_UNTRUSTED_CODE,
+                "Required capability signal requires an authenticated proxy API key.",
+                error_type="permission_error",
+            ),
+        )
+    if len(values) != 1:
+        raise _unsupported_capability_error()
+    raw_capability = values[0]
+    if not isinstance(raw_capability, str):
+        raise _unsupported_capability_error()
+    try:
+        capability = RoutingCapability(raw_capability)
+    except ValueError as exc:
+        raise _unsupported_capability_error() from exc
+    return RoutingIntent.requiring(capability)
+
+
+def required_capability_metadata_values(client_metadata: JsonValue | None) -> tuple[JsonValue, ...]:
+    """Required-capability values carried in a request's ``client_metadata``."""
+
+    return _metadata_values(client_metadata, REQUIRED_CAPABILITY_HEADER)
+
+
+def reject_capability_signal_outside_response_create(
+    *,
+    api_key: ApiKeyData | None,
+    client_metadata: JsonValue | None,
+    client_metadata_values: Collection[JsonValue] | None = None,
+) -> None:
+    intent = parse_routing_intent(
+        {},
+        api_key=api_key,
+        client_metadata=client_metadata,
+        client_metadata_values=client_metadata_values,
+    )
+    if intent.required_capabilities:
+        raise _unsupported_capability_error()
+
+
+def strip_capability_metadata(client_metadata: JsonValue | None) -> JsonValue | None:
+    if not is_json_mapping(client_metadata):
+        return client_metadata
+    normalized_name = REQUIRED_CAPABILITY_HEADER.lower()
+    return {
+        key: value
+        for key, value in client_metadata.items()
+        if not isinstance(key, str) or key.lower() != normalized_name
+    }
+
+
+def _header_values(headers: Mapping[str, str], name: str) -> tuple[str, ...]:
+    normalized_name = name.lower()
+    return tuple(value for header_name, value in headers.items() if header_name.lower() == normalized_name)
+
+
+def _metadata_values(client_metadata: JsonValue | None, name: str) -> tuple[JsonValue, ...]:
+    if not is_json_mapping(client_metadata):
+        return ()
+    normalized_name = name.lower()
+    return tuple(
+        value for key, value in client_metadata.items() if isinstance(key, str) and key.lower() == normalized_name
+    )
+
+
+def _metadata_string_values(client_metadata: JsonValue | None, name: str) -> tuple[str, ...]:
+    return tuple(value for value in _metadata_values(client_metadata, name) if isinstance(value, str))
+
+
+def _append_alias(aliases: list[CapabilityLineageAlias], kind: str, value: str | None) -> None:
+    if value is not None:
+        aliases.append(CapabilityLineageAlias(kind=kind, value=value))
+
+
+def _unsupported_capability_error() -> ProxyResponseError:
+    return ProxyResponseError(
+        400,
+        openai_error(
+            UNSUPPORTED_REQUIRED_CAPABILITY_CODE,
+            "Required routing capability is unsupported.",
+            error_type="invalid_request_error",
+        ),
+    )
+
+
+def _capability_lineage_unavailable_error() -> ProxyResponseError:
+    return ProxyResponseError(
+        503,
+        openai_error(
+            CAPABILITY_LINEAGE_UNAVAILABLE_CODE,
+            "Required capability lineage is unavailable; retry later.",
+            error_type="server_error",
+        ),
+    )

app/modules/proxy/continuity.py

@@ -0,0 +1,112 @@
+"""Shared account-owner consistency checks for proxy continuity sources."""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Mapping
+from hashlib import sha256
+from typing import Protocol
+
+from app.core.clients.proxy import ProxyResponseError
+from app.core.errors import openai_error
+
+HTTP_BRIDGE_ACCOUNT_NEUTRAL_REPLAY_KIND = "internal_unanchored_parallel"
+HTTP_BRIDGE_ACCOUNT_NEUTRAL_REPLAY_KEY_PREFIX = "account-neutral-replay:v1:"
+# These are canonical lanes whose exact aliases may move only after the
+# existing full-resend validator has proved the request account-neutral. A
+# thread lane is hard during ordinary use, just like a session-header lane;
+# omitting it here would accidentally remove safe owner-unavailable recovery
+# merely because Codex now supplies a more precise canonical identity.
+HTTP_BRIDGE_ACCOUNT_NEUTRAL_REPLAY_REBINDABLE_KINDS = frozenset(
+    {"prompt_cache", "session_header", "thread_header", "turn_state_header"}
+)
+_HTTP_BRIDGE_SESSION_AFFINITY_HEADERS = frozenset(
+    {
+        "session_id",
+        "session-id",
+        "thread-id",
+        "x-codex-conversation-id",
+        "x-codex-session-id",
+        "x-codex-turn-state",
+    }
+)
+logger = logging.getLogger("app.modules.proxy.continuity")
+
+
+def make_http_bridge_account_neutral_replay_key(nonce: str) -> tuple[str, str]:
+    if not nonce:
+        raise ValueError("account-neutral replay nonce must not be empty")
+    return (
+        HTTP_BRIDGE_ACCOUNT_NEUTRAL_REPLAY_KIND,
+        f"{HTTP_BRIDGE_ACCOUNT_NEUTRAL_REPLAY_KEY_PREFIX}{nonce}",
+    )
+
+
+def is_http_bridge_account_neutral_replay(*, kind: str, key: str) -> bool:
+    """Recognize only server-namespaced durable replay keys."""
+
+    return (
+        kind == HTTP_BRIDGE_ACCOUNT_NEUTRAL_REPLAY_KIND
+        and key.startswith(HTTP_BRIDGE_ACCOUNT_NEUTRAL_REPLAY_KEY_PREFIX)
+        and len(key) > len(HTTP_BRIDGE_ACCOUNT_NEUTRAL_REPLAY_KEY_PREFIX)
+    )
+
+
+def without_http_bridge_session_affinity_headers(headers: Mapping[str, str]) -> dict[str, str]:
+    """Drop downstream aliases that must not reach a fresh upstream account."""
+
+    return {
+        header_name: header_value
+        for header_name, header_value in headers.items()
+        if header_name.lower() not in _HTTP_BRIDGE_SESSION_AFFINITY_HEADERS
+    }
+
+
+class _ReconnectPreferredOwner(Protocol):
+    preferred_account_id: str | None
+    file_required_preferred_account: bool
+
+
+def resolve_reconnect_preferred_account_id(
+    request_state: _ReconnectPreferredOwner,
+    session_account_id: str,
+    require_preferred_account: bool,
+    account_neutral_recovery: bool,
+) -> str | None:
+    if request_state.file_required_preferred_account:
+        return request_state.preferred_account_id or session_account_id
+    if require_preferred_account or account_neutral_recovery:
+        return request_state.preferred_account_id
+    return None
+
+
+def resolve_required_account_id(*owners: tuple[str, str | None]) -> str | None:
+    """Return one proven owner or fail closed when hard sources disagree."""
+    resolved = [(source, account_id) for source, account_id in owners if account_id is not None]
+    if not resolved:
+        return None
+    owner_account_id = resolved[0][1]
+    conflicting_sources = [source for source, account_id in resolved if account_id != owner_account_id]
+    if conflicting_sources:
+        # Hard sources identify account-scoped upstream state. Choosing either
+        # side would silently abandon the other, so conflicts are never ordered
+        # by caller precedence or softened into ordinary affinity fallback.
+        sources = ", ".join(source for source, _account_id in resolved)
+        owner_hashes = ", ".join(
+            f"{source}={sha256(account_id.encode()).hexdigest()[:12]}" for source, account_id in resolved
+        )
+        logger.warning(
+            "continuity_owner_conflict sources=%s conflicting_sources=%s owner_hashes=%s",
+            sources,
+            ", ".join(conflicting_sources),
+            owner_hashes,
+        )
+        raise ProxyResponseError(
+            502,
+            openai_error(
+                "continuity_owner_conflict",
+                f"Account-owned continuity sources conflict ({sources}); retry the logical turn.",
+                error_type="server_error",
+            ),
+        )
+    return owner_account_id

app/modules/proxy/downstream_delivery.py

@@ -0,0 +1,277 @@
+"""Trace whether the SSE terminal frame of a Responses stream reached the downstream writer.
+
+``request_logs.status`` is settled when the proxy *parses* the upstream
+terminal frame (``response.completed``/``failed``/``incomplete``/``error``),
+not when that frame is *written* to the client. Two paths drop the write
+without leaving a signal: uvicorn's ``send`` returns silently once the cycle is
+marked disconnected (peer FIN/RST racing the terminal write), and an exception
+raised by an ``api.py`` wrapper while formatting the terminal block closes the
+inner generators after settlement. Both produce a full-looking body without a
+terminal frame and a ``success`` row.
+
+:class:`DeliveryTracedStreamingResponse` wraps the ASGI ``send`` of a
+``StreamingResponse`` and reports, once per stream, one bounded ``outcome``
+(see :data:`OUTCOMES`) as a Prometheus counter and one structured log line:
+
+- ``terminal_written`` — a terminal frame was handed to the server's writer on
+  a live connection (a cancel or exception *after* that does not unwrite it);
+- ``terminal_after_disconnect`` — the terminal frame was handed over after the
+  connection was already lost, so uvicorn dropped it;
+- ``exception_before_terminal`` — the body raised before any terminal frame
+  (re-raised unchanged; no synthetic frame is emitted);
+- ``cancelled_before_terminal`` — the body ended unfinished without a terminal:
+  client disconnect (Starlette cancels the body iteration) or server-side task
+  cancellation (``exc=CancelledError`` in the log line), including a cancel
+  that lands while ``send`` is still waiting on write backpressure for the
+  terminal chunk itself — uvicorn drains *before* it writes, so that chunk never
+  reached the writer;
+- ``ended_without_terminal`` — the body iterator was exhausted and the final
+  ``more_body=False`` sent, yet no terminal frame was seen.
+
+It never alters the forwarded bytes, never emits a synthetic frame, and does
+not touch request-log settlement. ``terminal_written`` means the *complete*
+terminal block — ``event:`` line through the blank-line terminator — was handed
+to the HTTP server's writer on a live connection; the transport buffer and any
+reverse proxy in front are not observed. A terminal frame split across chunks
+is committed only by the chunk that carries its terminator, so a disconnect or
+cancellation between the ``event:`` line and the end of the block is reported
+as ``terminal_after_disconnect`` / ``cancelled_before_terminal``, never as a
+written terminal (an SSE client discards an unterminated event at EOF).
+``chunks``/``bytes`` count the non-empty body chunks whose ``send`` returned
+(the empty ``more_body=False`` message is not a chunk).
+
+The log line's ``request_id`` is the ingress request id
+(``RequestIdMiddleware`` contextvar, valid for the whole body stream because the
+middleware is pure ASGI). The streaming service stores that value in
+``request_logs.archive_request_id``; ``request_logs.request_id`` holds the
+upstream response id once ``response.created`` was seen. Join on
+``archive_request_id``.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import re
+from collections.abc import AsyncIterator, Mapping
+
+from fastapi.responses import StreamingResponse
+from starlette.types import Message, Receive, Scope, Send
+
+from app.core.http_protocol import HTTP_DISCONNECTED_STATE
+from app.core.metrics.prometheus import PROMETHEUS_AVAILABLE, stream_terminal_delivery_total
+from app.core.utils.request_id import get_request_id
+
+logger = logging.getLogger(__name__)
+
+OUTCOME_TERMINAL_WRITTEN = "terminal_written"
+OUTCOME_TERMINAL_AFTER_DISCONNECT = "terminal_after_disconnect"
+OUTCOME_EXCEPTION_BEFORE_TERMINAL = "exception_before_terminal"
+OUTCOME_CANCELLED_BEFORE_TERMINAL = "cancelled_before_terminal"
+OUTCOME_ENDED_WITHOUT_TERMINAL = "ended_without_terminal"
+OUTCOMES = frozenset(
+    {
+        OUTCOME_TERMINAL_WRITTEN,
+        OUTCOME_TERMINAL_AFTER_DISCONNECT,
+        OUTCOME_EXCEPTION_BEFORE_TERMINAL,
+        OUTCOME_CANCELLED_BEFORE_TERMINAL,
+        OUTCOME_ENDED_WITHOUT_TERMINAL,
+    }
+)
+
+# Canonical SSE framing: every wrapper in api.py emits ``format_sse_event``
+# blocks or passes the upstream ``event: <type>\ndata: ...\n\n`` line through
+# verbatim, so the terminal event type is always on an ``event:`` line and a
+# block starts with that line. The pattern is only ever *anchored* (``match``)
+# at a line start — never ``search``-ed across a body — so a large non-terminal
+# frame (``response.output_item.done`` with big tool-call arguments) costs one
+# anchored comparison at offset 0 plus one ``bytes.find`` (memmem) for further
+# line starts, not a regex walk over every byte.
+_TERMINAL_LINE_RE = re.compile(rb"event: (response\.completed|response\.failed|response\.incomplete|error)(?=\r|\n)")
+_EVENT_LINE_START = b"\nevent: "
+# Frames are normally one block per ASGI chunk, but nothing pins that, so the
+# last bytes of the previous chunk are re-scanned together with the current one
+# and a marker split across the boundary is still recognised. The longest marker
+# (``\nevent: response.incomplete\n``) is 28 bytes; keep a little more. The
+# same tail carries a block terminator split across chunks (``\r\n\r`` | ``\n``).
+_TAIL_BYTES = 64
+
+
+def _find_terminal_event(window: bytes) -> tuple[str, int] | None:
+    """Return ``(terminal event type, offset just past the type)`` for an ``event:`` line of ``window``."""
+    if window.startswith(b"event: "):
+        match = _TERMINAL_LINE_RE.match(window)
+        if match is not None:
+            return match.group(1).decode("ascii"), match.end()
+    position = window.find(_EVENT_LINE_START)
+    while position != -1:
+        match = _TERMINAL_LINE_RE.match(window, position + 1)
+        if match is not None:
+            return match.group(1).decode("ascii"), match.end()
+        position = window.find(_EVENT_LINE_START, position + 1)
+    return None
+
+
+def _find_block_end(window: bytes) -> int:
+    """Return the offset just past the first SSE blank line in ``window``, or ``-1``.
+
+    A block ends at an empty line: a line terminator immediately followed by
+    another one. LF and CRLF framing (and either mixed) are recognised through
+    ``bytes.find`` on ``\n`` — a terminal ``response.completed`` frame carries
+    one very long ``data:`` line, so this loop runs two or three iterations,
+    never a regex walk. Bare-CR framing is not emitted or relayed by the proxy
+    and is not recognised.
+    """
+    position = window.find(b"\n")
+    while position != -1:
+        following = window[position + 1 : position + 3]
+        if following.startswith(b"\n"):
+            return position + 2
+        if following == b"\r\n":
+            return position + 3
+        position = window.find(b"\n", position + 1)
+    return -1
+
+
+class DeliveryTracedStreamingResponse(StreamingResponse):
+    """``StreamingResponse`` that reports whether the SSE terminal frame reached the writer.
+
+    ``outcome`` is ``None`` until the response finishes and one of :data:`OUTCOMES`
+    afterwards; tests and callers may read it, the metric/log emission happens
+    exactly once in ``__call__``'s ``finally``.
+    """
+
+    def __init__(
+        self,
+        content: AsyncIterator[str] | AsyncIterator[bytes],
+        *,
+        surface: str,
+        media_type: str = "text/event-stream",
+        headers: Mapping[str, str] | None = None,
+    ) -> None:
+        super().__init__(content, media_type=media_type, headers=headers)
+        self.surface = surface
+        self.outcome: str | None = None
+        self._chunks = 0
+        self._bytes = 0
+        self._tail = b""
+        # ``_pending_terminal`` names the terminal whose ``event:`` line was
+        # handed over while the rest of its block is still outstanding;
+        # ``_terminal_type`` is set only once the block terminator was handed over.
+        self._pending_terminal: str | None = None
+        self._terminal_type: str | None = None
+        self._terminal_dropped = False
+        self._final_sent = False
+
+    def _observe_body(self, body: bytes) -> bool:
+        """Account a body chunk handed to the writer; return whether it completed the terminal block."""
+        if not body:
+            return False
+        self._chunks += 1
+        self._bytes += len(body)
+        if self._terminal_type is not None:
+            return False
+        window = self._tail + body if self._tail else body
+        if self._pending_terminal is None:
+            found = _find_terminal_event(window)
+            if found is None:
+                self._tail = window[-_TAIL_BYTES:]
+                return False
+            self._pending_terminal, block_start = found
+            # Only bytes after the event line may terminate its block: the
+            # blank line that *preceded* it belongs to the previous frame.
+            window = window[block_start:]
+        block_end = _find_block_end(window)
+        if block_end == -1:
+            self._tail = window[-_TAIL_BYTES:]
+            return False
+        self._terminal_type = self._pending_terminal
+        self._tail = b""
+        return True
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+        state = scope.get("state")
+
+        async def traced_send(message: Message) -> None:
+            await send(message)
+            if message["type"] != "http.response.body":
+                return
+            # Accounted only after ``send`` returned: uvicorn awaits its
+            # write-backpressure drain *before* writing, so a cancel that lands
+            # inside ``send`` means this chunk never reached the writer.
+            if self._observe_body(bytes(message.get("body", b""))):
+                # uvicorn's ``send`` returns without writing once the cycle is
+                # disconnected; the protocol stamps that state synchronously in
+                # ``connection_lost``, before any task can resume, so a stamp
+                # visible here means the chunk that completed the terminal
+                # block never reached the writer.
+                self._terminal_dropped = isinstance(state, dict) and HTTP_DISCONNECTED_STATE in state
+            if not message.get("more_body", False):
+                self._final_sent = True
+
+        exc_name: str | None = None
+        cancelled = False
+        try:
+            await super().__call__(scope, receive, traced_send)
+        except asyncio.CancelledError:
+            cancelled = True
+            raise
+        except BaseException as exc:
+            exc_name = type(exc).__name__
+            raise
+        finally:
+            self._finish(exc_name=exc_name, cancelled=cancelled)
+
+    def _classify(self, *, exc_name: str | None, cancelled: bool) -> str:
+        if self._terminal_type is not None:
+            # A cancel or exception after the complete terminal block was
+            # handed over does not unwrite it; the exception name stays visible
+            # in the log line. A block whose ``event:`` line went out but whose
+            # terminator did not (``_pending_terminal`` set, ``_terminal_type``
+            # unset) falls through to the no-terminal outcomes below.
+            return OUTCOME_TERMINAL_AFTER_DISCONNECT if self._terminal_dropped else OUTCOME_TERMINAL_WRITTEN
+        if exc_name is not None:
+            return OUTCOME_EXCEPTION_BEFORE_TERMINAL
+        if cancelled or not self._final_sent:
+            # Starlette's ASGI 2.3 path absorbs the disconnect-driven cancel
+            # inside its task group, so a client that left mid-stream returns
+            # here normally with the body unfinished (no ``more_body=False``).
+            # ``exc=CancelledError`` in the log line marks the other shape: the
+            # server task itself was cancelled (uvicorn shutdown drain).
+            return OUTCOME_CANCELLED_BEFORE_TERMINAL
+        return OUTCOME_ENDED_WITHOUT_TERMINAL
+
+    def _finish(self, *, exc_name: str | None, cancelled: bool) -> None:
+        outcome = self._classify(exc_name=exc_name, cancelled=cancelled)
+        self.outcome = outcome
+        if PROMETHEUS_AVAILABLE and stream_terminal_delivery_total is not None:
+            stream_terminal_delivery_total.labels(surface=self.surface, outcome=outcome).inc()
+        if outcome == OUTCOME_TERMINAL_WRITTEN:
+            level = logging.DEBUG
+        elif outcome == OUTCOME_CANCELLED_BEFORE_TERMINAL:
+            level = logging.INFO
+        else:
+            level = logging.WARNING
+        logger.log(
+            level,
+            "responses_stream_terminal_delivery request_id=%s surface=%s outcome=%s terminal=%s "
+            "chunks=%d bytes=%d exc=%s",
+            get_request_id(),
+            self.surface,
+            outcome,
+            self._terminal_type,
+            self._chunks,
+            self._bytes,
+            "CancelledError" if cancelled else exc_name,
+        )
+
+
+__all__ = [
+    "OUTCOMES",
+    "OUTCOME_CANCELLED_BEFORE_TERMINAL",
+    "OUTCOME_ENDED_WITHOUT_TERMINAL",
+    "OUTCOME_EXCEPTION_BEFORE_TERMINAL",
+    "OUTCOME_TERMINAL_AFTER_DISCONNECT",
+    "OUTCOME_TERMINAL_WRITTEN",
+    "DeliveryTracedStreamingResponse",
+]