codexLB-up 1.25.0b10__py3-none-any.whl

app/core/errors.py

@@ -0,0 +1,365 @@
+from __future__ import annotations
+
+import re
+import time
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import Literal, NotRequired, TypedDict
+
+from app.core.types import JsonValue
+
+
+@dataclass(frozen=True, slots=True)
+class OpenAIErrorParam:
+    """Preserve whether an upstream error supplied a ``param`` field."""
+
+    present: bool
+    raw: JsonValue | None = None
+
+    @classmethod
+    def absent(cls) -> "OpenAIErrorParam":
+        return cls(False, None)
+
+    @classmethod
+    def from_mapping(cls, error: Mapping[str, JsonValue]) -> "OpenAIErrorParam":
+        if "param" not in error:
+            return cls.absent()
+        return cls(True, error["param"])
+
+    @property
+    def normalized(self) -> str | None:
+        return self.raw.strip() if isinstance(self.raw, str) else None
+
+    @property
+    def malformed(self) -> bool:
+        return self.present and (self.normalized is None or not self.normalized)
+
+
+def coerce_error_param(param: OpenAIErrorParam | JsonValue) -> OpenAIErrorParam:
+    """Convert legacy raw values to presence-aware error parameter state."""
+
+    if isinstance(param, OpenAIErrorParam):
+        return param
+    if param is None:
+        return OpenAIErrorParam.absent()
+    return OpenAIErrorParam(True, param)
+
+
+def normalize_public_error_param(param: OpenAIErrorParam | JsonValue) -> str | None:
+    """Return only a trimmed, non-empty string safe for a public response."""
+
+    normalized = coerce_error_param(param).normalized
+    return normalized if normalized else None
+
+
+class OpenAIErrorDetail(TypedDict, total=False):
+    message: str
+    type: str
+    code: str
+    param: JsonValue
+    plan_type: str
+    resets_at: int | float
+    resets_in_seconds: int | float
+
+
+class OpenAIErrorEnvelope(TypedDict):
+    error: OpenAIErrorDetail
+
+
+class DashboardErrorDetail(TypedDict):
+    code: str
+    message: str
+    param: NotRequired[str]
+    details: NotRequired[dict[str, JsonValue]]
+
+
+class DashboardErrorEnvelope(TypedDict):
+    error: DashboardErrorDetail
+
+
+class ResponseFailedResponse(TypedDict):
+    object: str
+    status: str
+    error: OpenAIErrorDetail
+    id: NotRequired[str]
+    created_at: NotRequired[int]
+    incomplete_details: NotRequired[dict[str, str] | None]
+
+
+class ResponseFailedEvent(TypedDict):
+    type: Literal["response.failed"]
+    response: ResponseFailedResponse
+    _codex_lb_synthetic_transport_failure: NotRequired[bool]
+
+
+PREVIOUS_RESPONSE_STREAM_INCOMPLETE_MESSAGE = "Upstream websocket closed before response.completed"
+# Local bridge recovery (fresh replay, context-overflow rollover, previous
+# response rebind) tears down our own upstream session. It is not an upstream
+# close and must not be reported as one.
+HTTP_BRIDGE_LOCAL_RESET_MESSAGE = "HTTP responses session bridge reset this session locally before response.completed"
+# ``stream_incomplete`` raised against a continuation anchor is ambiguous: the
+# turn may already exist upstream. Neither of these messages proves the account
+# misbehaved, so neither may drive an account-health penalty.
+STREAM_INCOMPLETE_ANCHOR_NEUTRAL_MESSAGES = frozenset(
+    {
+        PREVIOUS_RESPONSE_STREAM_INCOMPLETE_MESSAGE,
+        HTTP_BRIDGE_LOCAL_RESET_MESSAGE,
+    }
+)
+# Pre-response-start bridge silence. Distinct from ``stream_idle_timeout``,
+# whose budget (``stream_idle_timeout_seconds``) only governs gaps *after*
+# ``response.created``. When the bridge saw no unmatched upstream liveness,
+# nothing was created upstream and a retry forks no context. If liveness was
+# observed but not matched to a response, callers must treat retry as
+# at-least-once.
+HTTP_BRIDGE_EVENTLESS_TIMEOUT_CODE = "bridge_eventless_timeout"
+PREVIOUS_RESPONSE_NOT_FOUND_CODE = "previous_response_not_found"
+PREVIOUS_RESPONSE_NOT_FOUND_MESSAGE = "Previous response was not found; retry without previous_response_id."
+PREVIOUS_RESPONSE_MALFORMED_PARAM_REASON = "previous_response_not_found_malformed_param"
+SYNTHETIC_TRANSPORT_FAILURE_MARKER = "_codex_lb_synthetic_transport_failure"
+SYNTHETIC_TRANSPORT_FAILURE_CODES = frozenset(
+    {"stream_incomplete", "stream_idle_timeout", "upstream_request_timeout", "upstream_unavailable"}
+)
+# Every sentence upstream uses to say the account's subscription window is
+# spent, written in the form ``is_upstream_usage_limit_message`` normalizes to:
+# lowercase alphanumeric words joined by single spaces. The passive
+# "The usage limit has been reached" is what the HTTP bridge, the Codex
+# WebSocket and the SDK error body actually carry; the second-person forms come
+# from the native client rendering and from the promo text appended to a
+# decline. A table built from one voice is a table that never fires.
+_USAGE_LIMIT_MESSAGE_MARKERS = (
+    "usage limit has been reached",
+    "usage limit reached",
+    "hit your usage limit",
+    "reached your usage limit",
+    "exceeded your usage limit",
+)
+_MESSAGE_WORD_SEPARATOR_RE = re.compile(r"[^a-z0-9]+")
+
+
+def openai_error(
+    code: str,
+    message: str,
+    error_type: str = "server_error",
+    *,
+    resets_at: int | float | None = None,
+) -> OpenAIErrorEnvelope:
+    detail: OpenAIErrorDetail = {"message": message, "type": error_type, "code": code}
+    if resets_at is not None:
+        detail["resets_at"] = int(resets_at)
+    return {"error": detail}
+
+
+def dashboard_error(
+    code: str,
+    message: str,
+    *,
+    param: str | None = None,
+    details: Mapping[str, JsonValue] | None = None,
+) -> DashboardErrorEnvelope:
+    detail: DashboardErrorDetail = {"code": code, "message": message}
+    if param is not None:
+        detail["param"] = param
+    if details:
+        detail["details"] = dict(details)
+    return {"error": detail}
+
+
+#: RFC 7644 §3.12. Every body from ``/scim/v2`` carries this media type, and
+#: every refusal carries the error schema below; an identity provider reads
+#: both and neither the dashboard nor the OpenAI envelope means anything to it.
+SCIM_CONTENT_TYPE = "application/scim+json"
+SCIM_ERROR_SCHEMA = "urn:ietf:params:scim:api:messages:2.0:Error"
+
+
+class ScimErrorEnvelope(TypedDict):
+    schemas: list[str]
+    status: str
+    detail: str
+    scimType: NotRequired[str]
+
+
+def scim_error(status_code: int, detail: str, *, scim_type: str | None = None) -> ScimErrorEnvelope:
+    """RFC 7644's error body. ``status`` is a string there, not a number."""
+
+    envelope: ScimErrorEnvelope = {
+        "schemas": [SCIM_ERROR_SCHEMA],
+        "status": str(status_code),
+        "detail": detail,
+    }
+    if scim_type is not None:
+        envelope["scimType"] = scim_type
+    return envelope
+
+
+def previous_response_stream_incomplete_error() -> OpenAIErrorEnvelope:
+    return openai_error(
+        "stream_incomplete",
+        PREVIOUS_RESPONSE_STREAM_INCOMPLETE_MESSAGE,
+        error_type="server_error",
+    )
+
+
+def is_upstream_usage_limit_message(message: str | None) -> bool:
+    """True when the message asserts the account's usage limit is spent.
+
+    Upstream delivers this rejection as an HTTP body and as a serialized
+    ``response.failed`` frame that carries no status and often no error code, so
+    neither the status nor the code table can be the gate and every path that
+    needs the answer has to read it from the same place. The words are matched
+    after folding each run of non-alphanumeric characters to a single space,
+    because the same sentence arrives with a straight apostrophe, a curly one,
+    a hyphen joining "usage" and "limit", or wrapped across a line break.
+    """
+    if message is None:
+        return False
+    normalized = _MESSAGE_WORD_SEPARATOR_RE.sub(" ", message.lower()).strip()
+    return any(marker in normalized for marker in _USAGE_LIMIT_MESSAGE_MARKERS)
+
+
+def is_previous_response_not_found_message(message: str | None) -> bool:
+    if message is None:
+        return False
+    normalized = " ".join(message.lower().split())
+    return "previous response" in normalized and "not found" in normalized
+
+
+def _is_invalid_previous_response_id_message(message: str | None) -> bool:
+    if message is None:
+        return False
+    normalized = " ".join(message.casefold().replace("`", "").split()).removesuffix(".").rstrip()
+    return normalized == "invalid previous_response_id"
+
+
+def previous_response_id_from_not_found_message(message: str | None) -> str | None:
+    if message is None:
+        return None
+    normalized = " ".join(message.split())
+    match = re.search(
+        r"""previous\s+response\s+with\s+id\s+['"](?P<response_id>[^'"]+)['"]\s+not\s+found""",
+        normalized,
+        re.IGNORECASE,
+    )
+    if match is None:
+        return None
+    response_id = match.group("response_id").strip()
+    return response_id or None
+
+
+def sanitize_public_error_detail(error: Mapping[str, JsonValue]) -> dict[str, JsonValue]:
+    """Copy an error detail while omitting malformed ``param`` values."""
+
+    normalized = dict(error)
+    if "param" not in normalized:
+        return normalized
+    public_param = normalize_public_error_param(OpenAIErrorParam.from_mapping(error))
+    if public_param is None:
+        normalized.pop("param", None)
+    else:
+        normalized["param"] = public_param
+    return normalized
+
+
+def is_previous_response_not_found_error(
+    *,
+    code: str | None,
+    param: OpenAIErrorParam | JsonValue,
+    message: str | None,
+) -> bool:
+    param_state = coerce_error_param(param)
+    if param_state.malformed:
+        return False
+    if code == PREVIOUS_RESPONSE_NOT_FOUND_CODE:
+        return True
+    if code != "invalid_request_error":
+        return False
+    if not param_state.present:
+        return _is_invalid_previous_response_id_message(message)
+    if param_state.normalized != "previous_response_id":
+        return False
+    return is_previous_response_not_found_message(message) or _is_invalid_previous_response_id_message(message)
+
+
+def is_previous_response_not_found_public_shape(
+    *,
+    code: str | None,
+    param: OpenAIErrorParam | JsonValue,
+    message: str | None,
+) -> bool:
+    """Match stale-anchor errors for masking without authorizing replay."""
+
+    if code == PREVIOUS_RESPONSE_NOT_FOUND_CODE:
+        return True
+    param_state = coerce_error_param(param)
+    if (
+        code == "invalid_request_error"
+        and param_state.present
+        and not param_state.malformed
+        and param_state.normalized != "previous_response_id"
+    ):
+        return False
+    if code == "invalid_request_error" and (
+        _is_invalid_previous_response_id_message(message)
+        or previous_response_id_from_not_found_message(message) is not None
+    ):
+        return True
+    return is_previous_response_not_found_error(code=code, param=param, message=message)
+
+
+def response_failed_event(
+    code: str,
+    message: str,
+    error_type: str = "server_error",
+    response_id: str | None = None,
+    created_at: int | None = None,
+    error_param: OpenAIErrorParam | JsonValue = None,
+    resets_at: int | float | None = None,
+    incomplete_details: dict[str, str] | None = None,
+) -> ResponseFailedEvent:
+    error = openai_error(code, message, error_type, resets_at=resets_at)["error"]
+    public_param = normalize_public_error_param(error_param)
+    if public_param is not None:
+        error["param"] = public_param
+    if created_at is None:
+        created_at = int(time.time())
+    response: ResponseFailedResponse = {
+        "object": "response",
+        "status": "failed",
+        "error": error,
+    }
+    response["incomplete_details"] = incomplete_details
+    if response_id:
+        response["id"] = response_id
+    if created_at is not None:
+        response["created_at"] = created_at
+    return {"type": "response.failed", "response": response}
+
+
+def synthetic_transport_failure_event(event: ResponseFailedEvent) -> ResponseFailedEvent:
+    """Mark an LB-generated transport terminal for boundary-only handling."""
+    event[SYNTHETIC_TRANSPORT_FAILURE_MARKER] = True
+    return event
+
+
+def synthetic_stream_failure_event(
+    code: str,
+    message: str,
+    error_type: str = "server_error",
+    response_id: str | None = None,
+    created_at: int | None = None,
+    error_param: OpenAIErrorParam | JsonValue = None,
+    resets_at: int | float | None = None,
+    incomplete_details: dict[str, str] | None = None,
+) -> ResponseFailedEvent:
+    """Build a failed event and mark transport codes manufactured by codex-lb."""
+    event = response_failed_event(
+        code,
+        message,
+        error_type,
+        response_id,
+        created_at,
+        error_param,
+        resets_at,
+        incomplete_details,
+    )
+    return synthetic_transport_failure_event(event) if code in SYNTHETIC_TRANSPORT_FAILURE_CODES else event

app/core/exceptions.py

@@ -0,0 +1,155 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+
+from app.core.types import JsonValue
+
+
+class AppError(Exception):
+    """Base exception for all domain errors."""
+
+    status_code: int = 500
+    code: str = "internal_error"
+    message: str = "Unexpected error"
+
+    def __init__(
+        self,
+        message: str | None = None,
+        *,
+        code: str | None = None,
+        param: str | None = None,
+        details: Mapping[str, JsonValue] | None = None,
+    ) -> None:
+        self.message = message or self.__class__.message
+        self.param = param
+        #: Structured hints for the client (dashboard envelope only), e.g. the
+        #: step-up methods a principal may use.
+        self.details = details
+        if code is not None:
+            self.code = code
+        super().__init__(self.message)
+
+
+# --- OpenAI-envelope errors (proxy routes) ---
+
+
+class ProxyAuthError(AppError):
+    status_code = 401
+    code = "invalid_api_key"
+    error_type = "authentication_error"
+
+
+class ProxyModelNotAllowed(AppError):
+    status_code = 403
+    code = "model_not_allowed"
+    error_type = "permission_error"
+
+
+class ProxyReasoningEffortNotAllowed(AppError):
+    status_code = 403
+    code = "reasoning_effort_not_allowed"
+    error_type = "permission_error"
+
+
+class ProxyRateLimitError(AppError):
+    status_code = 429
+    code = "rate_limit_exceeded"
+    error_type = "rate_limit_error"
+
+
+class ProxyUpstreamError(AppError):
+    status_code = 503
+    code = "upstream_error"
+    error_type = "server_error"
+
+
+class ProxyRequiredCapabilityTransportError(AppError):
+    status_code = 400
+    code = "required_capability_transport_unsupported"
+    error_type = "invalid_request_error"
+    message = "Required capability routing is only supported over the Responses WebSocket transport."
+
+
+# --- Dashboard-envelope errors ---
+
+
+class DashboardAuthError(AppError):
+    status_code = 401
+    code = "authentication_required"
+
+
+class DashboardPermissionError(AppError):
+    status_code = 403
+    code = "permission_denied"
+
+
+class DashboardNotFoundError(AppError):
+    status_code = 404
+    code = "not_found"
+
+
+class DashboardConflictError(AppError):
+    status_code = 409
+    code = "conflict"
+
+
+class DashboardSettingsConflictError(DashboardConflictError):
+    code = "settings_conflict"
+    message = "Settings were modified by another writer; reload and retry"
+
+
+class DashboardBadRequestError(AppError):
+    status_code = 400
+    code = "bad_request"
+
+
+class DashboardValidationError(AppError):
+    status_code = 422
+    code = "validation_error"
+
+
+class DashboardRateLimitError(AppError):
+    status_code = 429
+    code = "rate_limited"
+
+    def __init__(self, message: str, *, retry_after: int, code: str | None = None) -> None:
+        self.retry_after = retry_after
+        super().__init__(message, code=code)
+
+
+class ScimError(AppError):
+    """A refusal from ``/scim/v2``, answered in RFC 7644's error envelope.
+
+    The status is per-instance because one exception type covers the whole
+    surface; ``scim_type`` carries an RFC 7644 §3.12 keyword only where the
+    specification defines one for the case (``400`` and the duplicate-resource
+    ``409``), and nothing product-specific is ever added to the body. The
+    dashboard envelope is deliberately not reused: an identity provider parses
+    this shape and no other.
+    """
+
+    status_code = 400
+    code = "scim_error"
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: int = 400,
+        scim_type: str | None = None,
+        headers: Mapping[str, str] | None = None,
+    ) -> None:
+        self.status_code = status_code
+        self.scim_type = scim_type
+        self.headers = dict(headers) if headers else None
+        super().__init__(message)
+
+
+class DashboardUpstreamError(AppError):
+    status_code = 502
+    code = "upstream_error"
+
+
+class DashboardServiceUnavailableError(AppError):
+    status_code = 503
+    code = "service_unavailable"

app/core/handlers/__init__.py

@@ -0,0 +1,3 @@
+from app.core.handlers.exceptions import add_exception_handlers
+
+__all__ = ["add_exception_handlers"]