Skip to content

Secure, Fast, and Extensible Sandbox runtime for AI agents.

3.7 KB
Raw Blame
#
# Copyright 2026 The OpenSandbox Authors
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
#
"""Map httpx transport exceptions to :class:`Outcome`."""

from __future__ import annotations

import httpx

from opensandbox.transport._decision import Outcome
from opensandbox.transport.retry import (
    WAKE_MARKER_HEADER,
    WAKE_MARKER_VALUE,
    RetryCause,
)


def classify_transport_exception(exc: BaseException) -> Outcome:
    """
    Classify an httpx transport exception.

    - Connect/pool errors: pre-send, safe to retry on any method.
    - Read/write timeout, unexpected EOF: post-send, idempotent only.
    - Other transport errors: opaque, idempotent only.
    - Anything else: not a transport error; caller re-raises.
    """
    if isinstance(exc, (httpx.ConnectError, httpx.ConnectTimeout)):
        return Outcome(
            is_transport_error=True, is_pre_send=True, cause=RetryCause.PRE_SEND
        )
    if isinstance(exc, httpx.PoolTimeout):
        # No byte written; treat as pre-send.
        return Outcome(
            is_transport_error=True, is_pre_send=True, cause=RetryCause.PRE_SEND
        )
    if isinstance(exc, httpx.ReadTimeout):
        return Outcome(is_transport_error=True, cause=RetryCause.READ_TIMEOUT)
    if isinstance(exc, httpx.WriteTimeout):
        return Outcome(is_transport_error=True, cause=RetryCause.WRITE_TIMEOUT)
    if isinstance(exc, httpx.RemoteProtocolError):
        return Outcome(is_transport_error=True, cause=RetryCause.UNEXPECTED_EOF)
    if isinstance(exc, httpx.TransportError):
        return Outcome(
            is_transport_error=True,
            is_opaque_transport=True,
            cause=RetryCause.OPAQUE_TRANSPORT,
        )
    return Outcome(is_transport_error=False)


def outcome_for_response(response: httpx.Response) -> Outcome:
    return Outcome(
        is_transport_error=False,
        status_code=response.status_code,
        cause=RetryCause.for_status(response.status_code),
    )


def is_wake_timeout_response(response: httpx.Response) -> bool:
    """
    Whether ``response`` is the OSEP-0024 wake-timeout answer.

    Recognition is header-only on a 503: the gateway strips
    ``OpenSandbox-Wake`` from every upstream response, so a matching
    marker proves the gateway parked the request and never forwarded
    it. The JSON ``code`` in the body is documentation for humans, not
    a recognition signal — a forged body without the header follows the
    SDK's existing (bare 503) retry rules untouched.
    """
    return (
        response.status_code == 503
        and response.headers.get(WAKE_MARKER_HEADER) == WAKE_MARKER_VALUE
    )


def is_body_replayable(request: httpx.Request) -> bool:
    """
    Whether ``request`` can be re-dispatched with the same body.

    httpx materializes in-memory bodies (``bytes``/``str``/``json=``)
    into a ``ByteStream``, which can be iterated repeatedly. Streaming
    bodies — async/sync generators, file-like uploads, and multipart
    ``files=`` bodies — can only be consumed once; resending raises
    ``StreamConsumed`` or emits a truncated body.
    """
    # ``httpx.ByteStream`` is the public marker (listed in
    # ``httpx.__all__``) for a materialized, replayable in-memory body.
    return isinstance(request.stream, httpx.ByteStream)