codexLB-up 1.25.0b10__py3-none-any.whl

app/core/handlers/exceptions.py

@@ -0,0 +1,478 @@
+from __future__ import annotations
+
+import logging
+import time
+from typing import Any
+
+from fastapi import FastAPI, Request
+from fastapi.exception_handlers import (
+    http_exception_handler,
+    request_validation_exception_handler,
+)
+from fastapi.exceptions import RequestValidationError
+from fastapi.responses import JSONResponse, Response
+from starlette._utils import get_route_path
+from starlette.exceptions import HTTPException as StarletteHTTPException
+from starlette.types import ASGIApp, Receive, Scope, Send
+
+from app.core.errors import SCIM_CONTENT_TYPE, dashboard_error, openai_error, scim_error
+from app.core.exceptions import (
+    AppError,
+    DashboardAuthError,
+    DashboardBadRequestError,
+    DashboardConflictError,
+    DashboardNotFoundError,
+    DashboardPermissionError,
+    DashboardRateLimitError,
+    DashboardServiceUnavailableError,
+    DashboardUpstreamError,
+    DashboardValidationError,
+    ProxyAuthError,
+    ProxyModelNotAllowed,
+    ProxyRateLimitError,
+    ProxyReasoningEffortNotAllowed,
+    ProxyRequiredCapabilityTransportError,
+    ProxyUpstreamError,
+    ScimError,
+)
+from app.core.middleware.multipart_content_encoding import (
+    UnsupportedMultipartContentEncoding,
+    multipart_error_response,
+)
+from app.core.middleware.request_body_limit import (
+    REQUEST_BODY_TOO_LARGE_MESSAGE,
+    request_body_limit_was_exceeded,
+    request_ingress_error_response,
+)
+from app.core.multipart import MultipartPayloadTooLarge
+from app.core.runtime_logging import log_error_response
+from app.modules.proxy.images_observability import (
+    IMAGE_ROUTE_MODEL_STATE,
+    IMAGE_ROUTE_STARTED_AT_STATE,
+    IMAGE_ROUTE_STREAM_STATE,
+    ImageRoute,
+    record_images_route_observability,
+)
+
+logger = logging.getLogger(__name__)
+
+_OPENAI_EXCEPTION_TYPES: tuple[type[AppError], ...] = (
+    ProxyAuthError,
+    ProxyModelNotAllowed,
+    ProxyReasoningEffortNotAllowed,
+    ProxyRateLimitError,
+    ProxyRequiredCapabilityTransportError,
+    ProxyUpstreamError,
+)
+
+_DASHBOARD_EXCEPTION_TYPES: tuple[type[AppError], ...] = (
+    DashboardAuthError,
+    DashboardPermissionError,
+    DashboardNotFoundError,
+    DashboardConflictError,
+    DashboardBadRequestError,
+    DashboardValidationError,
+    DashboardRateLimitError,
+    DashboardServiceUnavailableError,
+    DashboardUpstreamError,
+)
+
+
+def _error_format(request: Request) -> str | None:
+    fmt = getattr(request.state, "error_format", None)
+    if fmt is not None:
+        return fmt
+    # Fallback for unmatched routes (e.g. SPA fallback 404s)
+    path = request.url.path
+    if path.startswith("/api/"):
+        return "dashboard"
+    if path in {"/v1", "/backend-api"} or path.startswith(("/v1/", "/backend-api/")):
+        return "openai"
+    # Unmatched ``/scim/...`` paths never reach the router's marker dependency,
+    # so the 404 an identity provider probing for an unimplemented resource
+    # gets has to be decided here. Without it the answer is FastAPI's
+    # ``{"detail": ...}``, which no SCIM client parses.
+    if path == "/scim" or path.startswith("/scim/"):
+        return "scim"
+    return None
+
+
+def _scim_response(status_code: int, detail: str, *, scim_type: str | None = None) -> JSONResponse:
+    return JSONResponse(
+        status_code=status_code,
+        content=scim_error(status_code, detail, scim_type=scim_type),
+        media_type=SCIM_CONTENT_TYPE,
+    )
+
+
+# Codex-native aliases under /backend-api/codex map to the same route labels
+# as their /v1 counterparts so observability stays consistent across surfaces.
+_IMAGE_ROUTE_PATHS: dict[str, ImageRoute] = {
+    "/v1/images/generations": "generations",
+    "/backend-api/codex/images/generations": "generations",
+    "/v1/images/edits": "edits",
+    "/backend-api/codex/images/edits": "edits",
+}
+_CODEX_JSON_IMAGE_EDIT_PATH = "/backend-api/codex/images/edits"
+
+
+def _image_route_from_path(path: str) -> ImageRoute | None:
+    return _IMAGE_ROUTE_PATHS.get(path)
+
+
+def _is_json_request(request: Request) -> bool:
+    content_type = request.headers.get("content-type", "")
+    return content_type.split(";", 1)[0].strip().lower() == "application/json"
+
+
+async def _image_request_model_and_stream(request: Request, route: ImageRoute) -> tuple[str | None, bool]:
+    model: str | None = None
+    stream = False
+
+    # Generations is always JSON; only the codex edits alias accepts a JSON
+    # payload. The /v1 edits surface must never consume its body here, even
+    # when a client supplies the wrong Content-Type before authorization.
+    is_codex_json_edit = get_route_path(request.scope) == _CODEX_JSON_IMAGE_EDIT_PATH and _is_json_request(request)
+    if route == "generations" or is_codex_json_edit:
+        try:
+            payload: Any = await request.json()
+        except Exception:
+            payload = None
+        if isinstance(payload, dict):
+            model_value = payload.get("model")
+            if isinstance(model_value, str) and model_value:
+                model = model_value
+            stream = payload.get("stream") is True
+        return model, stream
+
+    if route == "edits":
+        # Multipart edit bodies are parsed only inside the authorized handler.
+        # Pre-handler errors use bounded unknown/false labels rather than
+        # consuming and spooling an unauthenticated upload for observability.
+        parsed_model = getattr(request.state, IMAGE_ROUTE_MODEL_STATE, None)
+        if isinstance(parsed_model, str) and parsed_model:
+            model = parsed_model
+        parsed_stream = getattr(request.state, IMAGE_ROUTE_STREAM_STATE, None)
+        if isinstance(parsed_stream, bool):
+            stream = parsed_stream
+        return model, stream
+
+    return model, stream
+
+
+async def _record_image_route_exception_observability(
+    request: Request,
+    *,
+    status: int,
+    outcome: str,
+) -> None:
+    path = get_route_path(request.scope)
+    route = _image_route_from_path(path)
+    if route is None:
+        return
+
+    model, stream = await _image_request_model_and_stream(request, route)
+    started_at = getattr(request.state, IMAGE_ROUTE_STARTED_AT_STATE, None)
+    if not isinstance(started_at, float):
+        started_at = time.perf_counter()
+
+    record_images_route_observability(
+        route=route,
+        model=model,
+        stream=stream,
+        status=status,
+        outcome=outcome,
+        started_at=started_at,
+    )
+
+
+class ImageRouteStartedAtMiddleware:
+    """Stamp the ingress start time for image routes into ``scope["state"]``.
+
+    Pure ASGI (no ``BaseHTTPMiddleware``): the previous ``@app.middleware("http")``
+    form ran the whole HTTP app in a child task and relayed every response
+    chunk through an anyio memory stream. ``Request.state`` is backed by
+    ``scope["state"]``, so the handler and the exception observability paths
+    keep reading the value through ``request.state`` unchanged.
+    """
+
+    def __init__(self, app: ASGIApp) -> None:
+        self.app = app
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+        if scope["type"] == "http" and _image_route_from_path(get_route_path(scope)) is not None:
+            scope.setdefault("state", {})[IMAGE_ROUTE_STARTED_AT_STATE] = time.perf_counter()
+        await self.app(scope, receive, send)
+
+
+def add_exception_handlers(app: FastAPI) -> None:
+    app.add_middleware(ImageRouteStartedAtMiddleware)
+
+    @app.exception_handler(MultipartPayloadTooLarge)
+    async def multipart_payload_too_large_handler(
+        request: Request,
+        exc: MultipartPayloadTooLarge,
+    ) -> JSONResponse:
+        await _record_image_route_exception_observability(
+            request,
+            status=413,
+            outcome="invalid_request",
+        )
+        return multipart_error_response(
+            request,
+            status_code=413,
+            code="payload_too_large",
+            message=exc.message,
+            param=exc.param,
+        )
+
+    @app.exception_handler(UnsupportedMultipartContentEncoding)
+    async def unsupported_multipart_content_encoding_handler(
+        request: Request,
+        exc: UnsupportedMultipartContentEncoding,
+    ) -> JSONResponse:
+        del exc
+        await _record_image_route_exception_observability(
+            request,
+            status=400,
+            outcome="invalid_request",
+        )
+        return multipart_error_response(
+            request,
+            status_code=400,
+            code="invalid_request",
+            message="Compressed multipart uploads are not supported",
+        )
+
+    # --- Domain exceptions: OpenAI envelope ---
+
+    for exc_cls in _OPENAI_EXCEPTION_TYPES:
+
+        @app.exception_handler(exc_cls)
+        async def _openai_domain_handler(request: Request, exc: AppError) -> JSONResponse:
+            error_type = getattr(exc, "error_type", "server_error")
+            log_error_response(
+                logger,
+                request,
+                exc.status_code,
+                exc.code,
+                exc.message,
+                category="openai_error_response",
+            )
+            if isinstance(exc, ProxyAuthError):
+                await _record_image_route_exception_observability(
+                    request,
+                    status=exc.status_code,
+                    outcome="auth_error",
+                )
+            elif isinstance(exc, ProxyRequiredCapabilityTransportError):
+                await _record_image_route_exception_observability(
+                    request,
+                    status=exc.status_code,
+                    outcome="invalid_request",
+                )
+            error = openai_error(exc.code, exc.message, error_type=error_type)
+            if exc.param is not None:
+                error["error"]["param"] = exc.param
+            return JSONResponse(status_code=exc.status_code, content=error)
+
+    # --- Domain exceptions: Dashboard envelope ---
+
+    for exc_cls in _DASHBOARD_EXCEPTION_TYPES:
+
+        @app.exception_handler(exc_cls)
+        async def _dashboard_domain_handler(request: Request, exc: AppError) -> JSONResponse:
+            headers: dict[str, str] | None = None
+            if isinstance(exc, DashboardRateLimitError):
+                headers = {"Retry-After": str(exc.retry_after)}
+            log_error_response(
+                logger,
+                request,
+                exc.status_code,
+                exc.code,
+                exc.message,
+                category="dashboard_error_response",
+            )
+            return JSONResponse(
+                status_code=exc.status_code,
+                content=dashboard_error(exc.code, exc.message, param=exc.param, details=exc.details),
+                headers=headers,
+            )
+
+    # --- Domain exceptions: SCIM envelope ---
+
+    @app.exception_handler(ScimError)
+    async def _scim_domain_handler(request: Request, exc: ScimError) -> JSONResponse:
+        log_error_response(
+            logger,
+            request,
+            exc.status_code,
+            exc.scim_type or f"http_{exc.status_code}",
+            exc.message,
+            category="scim_error_response",
+        )
+        response = _scim_response(exc.status_code, exc.message, scim_type=exc.scim_type)
+        for name, value in (exc.headers or {}).items():
+            response.headers[name] = value
+        return response
+
+    # --- Framework exceptions: format based on router marker ---
+
+    @app.exception_handler(RequestValidationError)
+    async def validation_error_handler(
+        request: Request,
+        exc: RequestValidationError,
+    ) -> Response:
+        first_message: str | None = None
+        if exc.errors():
+            first = exc.errors()[0]
+            message = first.get("msg")
+            if isinstance(message, str):
+                first_message = message
+        fmt = _error_format(request)
+        if fmt == "dashboard":
+            log_error_response(
+                logger,
+                request,
+                422,
+                "validation_error",
+                first_message or "Invalid request payload",
+                category="dashboard_error_response",
+            )
+            return JSONResponse(
+                status_code=422,
+                content=dashboard_error("validation_error", "Invalid request payload"),
+            )
+        if fmt == "openai":
+            error = openai_error("invalid_request_error", "Invalid request payload", error_type="invalid_request_error")
+            if exc.errors():
+                first = exc.errors()[0]
+                loc = first.get("loc", [])
+                if isinstance(loc, (list, tuple)):
+                    param = ".".join(str(part) for part in loc if part != "body")
+                    if param:
+                        error["error"]["param"] = param
+            log_error_response(
+                logger,
+                request,
+                400,
+                "invalid_request_error",
+                first_message or "Invalid request payload",
+                category="openai_error_response",
+            )
+            await _record_image_route_exception_observability(
+                request,
+                status=400,
+                outcome="invalid_request",
+            )
+            return JSONResponse(status_code=400, content=error)
+        if fmt == "scim":
+            log_error_response(
+                logger,
+                request,
+                400,
+                "invalidSyntax",
+                first_message or "Invalid request",
+                category="scim_error_response",
+            )
+            return _scim_response(400, "The request could not be understood.", scim_type="invalidSyntax")
+        return await request_validation_exception_handler(request, exc)
+
+    @app.exception_handler(StarletteHTTPException)
+    async def http_error_handler(
+        request: Request,
+        exc: StarletteHTTPException,
+    ) -> Response:
+        if request_body_limit_was_exceeded(request):
+            return request_ingress_error_response(
+                request,
+                status_code=413,
+                code="payload_too_large",
+                message=REQUEST_BODY_TOO_LARGE_MESSAGE,
+            )
+        fmt = _error_format(request)
+        detail = exc.detail if isinstance(exc.detail, str) else "Request failed"
+        if fmt == "dashboard":
+            log_error_response(
+                logger,
+                request,
+                exc.status_code,
+                f"http_{exc.status_code}",
+                detail,
+                category="dashboard_error_response",
+            )
+            return JSONResponse(
+                status_code=exc.status_code,
+                content=dashboard_error(f"http_{exc.status_code}", detail),
+            )
+        if fmt == "openai":
+            if exc.status_code == 400 and _image_route_from_path(get_route_path(request.scope)) == "edits":
+                await _record_image_route_exception_observability(
+                    request,
+                    status=400,
+                    outcome="invalid_request",
+                )
+            error_type = "invalid_request_error"
+            code = "invalid_request_error"
+            if exc.status_code == 401:
+                error_type = "authentication_error"
+                code = "invalid_api_key"
+            elif exc.status_code == 403:
+                error_type = "permission_error"
+                code = "insufficient_permissions"
+            elif exc.status_code == 404:
+                error_type = "invalid_request_error"
+                code = "not_found"
+            elif exc.status_code == 429:
+                error_type = "rate_limit_error"
+                code = "rate_limit_exceeded"
+            elif exc.status_code >= 500:
+                error_type = "server_error"
+                code = "server_error"
+            log_error_response(
+                logger,
+                request,
+                exc.status_code,
+                code,
+                detail,
+                category="openai_error_response",
+            )
+            return JSONResponse(status_code=exc.status_code, content=openai_error(code, detail, error_type=error_type))
+        if fmt == "scim":
+            log_error_response(
+                logger,
+                request,
+                exc.status_code,
+                f"http_{exc.status_code}",
+                detail,
+                category="scim_error_response",
+            )
+            response = _scim_response(exc.status_code, detail)
+            allow = (exc.headers or {}).get("Allow")
+            if allow is not None:
+                response.headers["Allow"] = allow
+            return response
+        return await http_exception_handler(request, exc)
+
+    # --- Catch-all for unhandled exceptions ---
+
+    @app.exception_handler(Exception)
+    async def unhandled_error_handler(request: Request, exc: Exception) -> JSONResponse:
+        fmt = _error_format(request)
+        category = "unhandled_error_response"
+        code = "server_error"
+        message = str(exc) or "Unexpected error"
+        log_error_response(logger, request, 500, code, message, category=category, exc_info=True)
+        if fmt == "dashboard":
+            return JSONResponse(
+                status_code=500,
+                content=dashboard_error("internal_error", "Unexpected error"),
+            )
+        if fmt == "openai":
+            return JSONResponse(
+                status_code=500,
+                content=openai_error("server_error", "Internal server error", error_type="server_error"),
+            )
+        if fmt == "scim":
+            return _scim_response(500, "The request could not be completed.")
+        return JSONResponse(status_code=500, content={"detail": "Internal Server Error"})

app/core/http_protocol.py

@@ -0,0 +1,176 @@
+"""Uvicorn HTTP protocol selection tolerant of opportunistic upgrade offers.
+
+JetBrains/Ktor clients attach cleartext HTTP/2 upgrade headers
+(``Connection: Upgrade, HTTP2-Settings`` + ``Upgrade: h2c`` +
+``HTTP2-Settings``) to ordinary HTTP/1.1 Responses API POSTs. RFC 9110
+section 7.8 lets a server ignore such an offer and answer over HTTP/1.1 —
+upstream OpenAI endpoints do exactly that — but uvicorn's stock protocol
+implementations either wedge on the offer (httptools) or leak the declined
+offer's hop-by-hop headers into the ASGI scope (h11). See
+https://github.com/Soju06/codex-lb/issues/1757 and the module docstring of
+``app.core.http_protocol_httptools`` for the full failure analysis.
+
+This module exposes :func:`load_http_protocol_class`, which returns the
+tolerant httptools subclass when httptools is importable (matching uvicorn's
+``auto`` preference) and an h11 subclass with the same header hygiene
+otherwise.
+
+Both subclasses also release the keep-alive timer on every connection loss.
+Stock uvicorn cancels it only on a clean close (``exc is None``), so after an
+RST/``ECONNRESET`` the armed ``TimerHandle`` keeps the protocol graph alive for
+``--timeout-keep-alive`` seconds — a per-request leak behind reverse proxies
+that purge idle connections with RST. See
+``tests/integration/test_http_keepalive_timer.py``.
+
+Their third job is observational: when a connection is lost while a response
+is still in flight, :func:`stamp_disconnect_into_scope` records the loss in
+that request's ASGI ``scope["state"]`` (key :data:`HTTP_DISCONNECTED_STATE`) —
+on a pipelined connection, in every request that is still open (the httptools
+subclass tracks the active cycle separately from uvicorn's ``self.cycle``).
+Uvicorn's ``send`` silently drops every message once the cycle is marked
+disconnected, and the ASGI ``receive()`` channel cannot tell a mid-stream loss
+from the ``http.disconnect`` it reports after every normal completion, so the
+stamp is the only deterministic way for a streaming response to learn that a
+late write — typically the SSE terminal frame — never reached the transport.
+See ``app.modules.proxy.downstream_delivery`` and
+``tests/integration/test_http_disconnect_stamp.py``.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Any
+
+from uvicorn.protocols.http.h11_impl import H11Protocol
+
+# ``scope["state"]`` key stamped by ``stamp_disconnect_into_scope``. The value
+# is ``"eof"`` for a clean peer close or the exception type name reported to
+# ``connection_lost`` (e.g. ``"ConnectionResetError"``).
+HTTP_DISCONNECTED_STATE = "codex_lb.http_disconnected"
+
+# Hop-by-hop headers that only exist to carry the declined protocol switch.
+# ``HTTP2-Settings`` is defined exclusively for the h2c upgrade (RFC 9113
+# section 3.1) and MUST NOT be forwarded once the offer is declined.
+UPGRADE_HOP_BY_HOP_HEADERS = frozenset({b"upgrade", b"http2-settings"})
+
+
+def stamp_disconnect_into_scope(cycle: Any, exc: BaseException | None) -> None:
+    """Record a mid-response connection loss in the in-flight request's ``scope["state"]``.
+
+    Uvicorn creates ``scope["state"]`` per request (``app_state.copy()``) and
+    pure-ASGI middlewares hand the same dict down, so the streaming response
+    that is still iterating can read the stamp. Nothing is written once the
+    response is complete: keep-alive idle closes leave the key absent. The
+    stamp only mutates the existing per-request dict — it adds no reference to
+    the protocol and no transport side effect, so it cannot re-introduce the
+    keep-alive-timer retention this module also guards against.
+    """
+    if cycle is None or cycle.response_complete:
+        return
+    state = cycle.scope.setdefault("state", {})
+    state.setdefault(HTTP_DISCONNECTED_STATE, "eof" if exc is None else type(exc).__name__)
+
+
+def combined_upgrade_offer(headers: list[tuple[bytes, bytes]]) -> bytes | None:
+    """Return the accepted ``Upgrade`` token, honoring repeated/list-valued fields.
+
+    Unlike uvicorn's ``_get_upgrade`` — which keeps only the tokens of the
+    *last* ``Connection`` field (so ``Connection: Upgrade`` followed by
+    ``Connection: keep-alive`` hides the offer) and the last ``Upgrade``
+    field's raw value (so ``Upgrade: websocket, h2c`` matches nothing) —
+    repeated fields are combined per RFC 9110 section 5.3 and the ``Upgrade``
+    protocol list is tokenized per section 7.8. ``websocket`` is returned
+    whenever it is among the offered protocols (the server may pick any
+    offered protocol it supports); otherwise the client's first preference is
+    returned. Header names must already be lowercased (both uvicorn
+    implementations store them that way).
+    """
+    connection_tokens: list[bytes] = []
+    upgrade_tokens: list[bytes] = []
+    for name, value in headers:
+        if name == b"connection":
+            connection_tokens.extend(token.lower().strip() for token in value.split(b","))
+        elif name == b"upgrade":
+            upgrade_tokens.extend(token for token in (token.lower().strip() for token in value.split(b",")) if token)
+    if b"upgrade" not in connection_tokens or not upgrade_tokens:
+        return None
+    if b"websocket" in upgrade_tokens:
+        return b"websocket"
+    return upgrade_tokens[0]
+
+
+def offers_ignorable_upgrade(headers: list[tuple[bytes, bytes]]) -> bool:
+    """True when the request offers a non-WebSocket protocol switch (e.g. h2c)."""
+    upgrade = combined_upgrade_offer(headers)
+    return upgrade is not None and upgrade != b"websocket"
+
+
+def without_upgrade_headers(headers: list[tuple[bytes, bytes]]) -> list[tuple[bytes, bytes]]:
+    """Drop the declined offer's hop-by-hop headers and ``Connection`` tokens."""
+    sanitized: list[tuple[bytes, bytes]] = []
+    for name, value in headers:
+        if name in UPGRADE_HOP_BY_HOP_HEADERS:
+            continue
+        if name == b"connection":
+            tokens = [token.strip() for token in value.split(b",")]
+            kept = [token for token in tokens if token and token.lower() not in UPGRADE_HOP_BY_HOP_HEADERS]
+            if not kept:
+                continue
+            value = b", ".join(kept)
+        sanitized.append((name, value))
+    return sanitized
+
+
+class UpgradeTolerantH11Protocol(H11Protocol):
+    """h11 protocol that hides declined non-WebSocket upgrade offers from the app.
+
+    The stock h11 implementation already serves such requests as plain
+    HTTP/1.1 with the full body, but it exposes the declined offer's
+    hop-by-hop headers in the ASGI scope and logs a spurious
+    "Unsupported upgrade request." warning. ``_should_upgrade`` is the seam:
+    it runs right after ``self.headers`` (the same list object referenced by
+    ``scope["headers"]``) is populated, so sanitizing in place here is enough.
+    """
+
+    def connection_lost(self, exc: Exception | None) -> None:
+        # Same defect as httptools_impl: stock h11_impl cancels the keep-alive
+        # timer only when exc is None, so an RST-closed idle connection stays
+        # pinned by the armed TimerHandle for timeout_keep_alive seconds.
+        # super() first: the base sends h11.ConnectionClosed before the exc
+        # check; the cancel touches only ``timeout_keep_alive_task``.
+        super().connection_lost(exc)
+        self._unset_keepalive_if_required()
+        # super() marked the in-flight cycle disconnected and keeps self.cycle
+        # referenced, so the stamp lands on the request that lost its peer.
+        # Unlike httptools, h11 never replaces ``self.cycle`` while a response
+        # is in flight: a pipelined follow-up stays unparsed inside the h11
+        # connection (``PAUSED``) until ``start_next_cycle``, so the newest
+        # cycle *is* the active one.
+        stamp_disconnect_into_scope(self.cycle, exc)
+
+    def _should_upgrade(self) -> bool:
+        # Reimplements the stock decision on top of combined Connection fields
+        # (RFC 9110 section 5.3): the stock ``_get_upgrade`` keeps only the
+        # last field's tokens, so ``Connection: Upgrade`` followed by
+        # ``Connection: keep-alive`` would hide the offer entirely.
+        upgrade = combined_upgrade_offer(self.headers)
+        if upgrade is None:
+            return False
+        if upgrade == b"websocket":
+            if self._should_upgrade_to_ws():
+                return True
+            self._unsupported_upgrade_warning()
+            return False
+        self.headers[:] = without_upgrade_headers(self.headers)
+        return False
+
+
+def load_http_protocol_class() -> type[asyncio.Protocol]:
+    """Return the HTTP protocol implementation for ``uvicorn.Config(http=...)``."""
+    try:
+        from app.core.http_protocol_httptools import UpgradeTolerantHttpToolsProtocol
+    except ImportError:
+        # httptools is an optional (transitive) dependency; uvicorn's "auto"
+        # selection would fall back to h11 as well.
+        return UpgradeTolerantH11Protocol
+    return UpgradeTolerantHttpToolsProtocol