Skip to content

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

9.5 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.
#
"""Retry policy, event, and cause enums. No httpx dependency."""

from __future__ import annotations

from collections.abc import Callable
from dataclasses import dataclass, field, replace
from datetime import timedelta
from enum import Enum
from http import HTTPStatus

# RFC 9110 §9.2.2.
_IDEMPOTENT_METHODS: frozenset[str] = frozenset(
    {"GET", "HEAD", "PUT", "DELETE", "OPTIONS"}
)

# OSEP-0024 wake-timeout marker. The gateway strips this header from every
# upstream response, so its presence on a 503 proves gateway origin: the
# request was parked and never forwarded, which is what makes any-method
# retry safe.
WAKE_MARKER_HEADER = "OpenSandbox-Wake"
WAKE_MARKER_VALUE = "expired"

# The gateway emits ``Retry-After: 1`` on wake-timeout responses. Used as
# the fallback wait when a marked response arrives without the header.
WAKE_DEFAULT_RETRY_AFTER = timedelta(seconds=1)


def is_idempotent_method(method: str) -> bool:
    return method.upper() in _IDEMPOTENT_METHODS


class JitterMode(str, Enum):
    """Backoff jitter algorithm."""

    NONE = "none"
    FULL = "full"
    DECORRELATED = "decorrelated"


class RetryCause(str, Enum):
    """Failure classification carried on :class:`RetryEvent`."""

    PRE_SEND = "pre_send"
    OPAQUE_TRANSPORT = "opaque_transport"
    READ_TIMEOUT = "read_timeout"
    WRITE_TIMEOUT = "write_timeout"
    UNEXPECTED_EOF = "unexpected_eof"
    STATUS_408 = "status_408"
    STATUS_425 = "status_425"
    STATUS_429 = "status_429"
    STATUS_500 = "status_500"
    STATUS_502 = "status_502"
    STATUS_503 = "status_503"
    STATUS_504 = "status_504"
    STATUS_OTHER = "status_other"
    WAKE_TIMEOUT = "wake_timeout"
    """Gateway wake-timeout marker on a 503 (OSEP-0024)."""

    @classmethod
    def for_status(cls, status_code: int) -> RetryCause:
        try:
            status = HTTPStatus(status_code)
        except ValueError:
            return cls.STATUS_OTHER
        return {
            HTTPStatus.REQUEST_TIMEOUT: cls.STATUS_408,
            HTTPStatus.TOO_EARLY: cls.STATUS_425,
            HTTPStatus.TOO_MANY_REQUESTS: cls.STATUS_429,
            HTTPStatus.INTERNAL_SERVER_ERROR: cls.STATUS_500,
            HTTPStatus.BAD_GATEWAY: cls.STATUS_502,
            HTTPStatus.SERVICE_UNAVAILABLE: cls.STATUS_503,
            HTTPStatus.GATEWAY_TIMEOUT: cls.STATUS_504,
        }.get(status, cls.STATUS_OTHER)


@dataclass(frozen=True)
class RetryEvent:
    """Payload passed to :attr:`RetryPolicy.on_retry` before each backoff sleep."""

    attempt: int
    """1-based index of the upcoming attempt (retry #1 is ``attempt=2``)."""

    retries_used: int
    """Retries consumed so far, i.e. ``attempt - 1``."""

    method: str
    url: str
    cause: RetryCause
    status_code: int | None
    backoff: timedelta
    request_id: str | None
    """``X-Request-ID`` header from the last response, if present."""

    exception: BaseException | None


_DEFAULT_IDEMPOTENT_STATUS: frozenset[HTTPStatus] = frozenset(
    {
        HTTPStatus.TOO_MANY_REQUESTS,   # 429
        HTTPStatus.BAD_GATEWAY,         # 502
        HTTPStatus.SERVICE_UNAVAILABLE, # 503
    }
)


@dataclass(frozen=True)
class RetryPolicy:
    """
    Retry configuration.

    Defaults retry idempotent methods only. Use :meth:`disabled` for
    fast-fail. Extend ``retryable_status_codes_non_idempotent`` to opt
    ``POST``/``PATCH`` in on specific status codes; the SDK never does
    this on the caller's behalf.
    """

    max_retries: int = 3
    """
    Retries after the initial attempt. ``0`` disables general retry;
    wake-timeout retries are governed separately by ``wake_retry_enabled``.
    """

    initial_backoff: timedelta = timedelta(milliseconds=500)
    max_backoff: timedelta = timedelta(seconds=30)
    backoff_multiplier: float = 2.0
    jitter: JitterMode = JitterMode.DECORRELATED

    retryable_status_codes_idempotent: frozenset[HTTPStatus] = _DEFAULT_IDEMPOTENT_STATUS
    """Statuses that trigger retry for ``GET/HEAD/PUT/DELETE/OPTIONS``."""

    retryable_status_codes_non_idempotent: frozenset[HTTPStatus] = field(
        default_factory=frozenset
    )
    """Statuses that trigger retry for ``POST/PATCH``. Empty by default."""

    per_attempt_timeout: timedelta | None = None
    overall_deadline: timedelta | None = None
    """Wall-clock cap across all attempts of one logical request."""

    on_retry: Callable[[RetryEvent], None] | None = None
    """Non-blocking hook fired synchronously before each backoff sleep."""

    wake_retry_enabled: bool = True
    """
    Auto-retry gateway wake-timeout responses (OSEP-0024): a ``503``
    carrying the ``OpenSandbox-Wake: expired`` marker proves the request
    was never forwarded, so the original request is resent for any method
    after waiting per ``Retry-After`` — provided the body is replayable.
    Bare ``503`` responses are never affected by this knob.
    """

    wake_overall_deadline: timedelta | None = timedelta(seconds=60)
    """
    Wall-clock cap spanning all wake cycles of one logical request:
    waits, retries, and request time. Wake retries never reset it; a
    next ``Retry-After`` that does not fit the remaining budget ends
    the wake retry with a typed ``SandboxWakeTimeoutException``.
    ``None`` removes the time bound (attempt count still applies).
    """

    wake_max_attempts: int = 5
    """
    Maximum wake-timeout responses (marked ``503``) consumed before the
    wake retry gives up and raises ``SandboxWakeTimeoutException``.
    """

    @classmethod
    def disabled(cls) -> RetryPolicy:
        """Never retry. Also suppresses fresh-connection recovery and wake retry."""
        return cls(max_retries=0, wake_retry_enabled=False)

    def wake_only(self) -> RetryPolicy:
        """
        This policy with only the wake-timeout retry left.

        Used for streaming (SSE) requests. They run commands, so they must
        not be resent after a status code or a post-send failure, but a
        marked wake timeout proves the gateway never forwarded the request.
        """
        return replace(
            self, max_retries=0, per_attempt_timeout=None, overall_deadline=None
        )

    def wraps_transport(self) -> bool:
        """
        Whether this policy requires the retry transport to be installed.

        Even ``max_retries == 0`` needs the wrapper when the caller uses
        it purely to enforce ``per_attempt_timeout`` or
        ``overall_deadline`` on a single attempt, or to keep the
        wake-timeout retry contract active.
        """
        return (
            self.max_retries > 0
            or self.wake_retry_enabled
            or self.per_attempt_timeout is not None
            or self.overall_deadline is not None
            or self.on_retry is not None
        )

    def retryable_statuses_for(self, method: str) -> frozenset[HTTPStatus]:
        if is_idempotent_method(method):
            return frozenset(self.retryable_status_codes_idempotent)
        return frozenset(self.retryable_status_codes_non_idempotent)

    def __post_init__(self) -> None:
        if self.max_retries < 0:
            raise ValueError(
                f"max_retries must be >= 0, got {self.max_retries!r}"
            )
        if self.initial_backoff.total_seconds() < 0:
            raise ValueError(
                f"initial_backoff must be >= 0, got {self.initial_backoff!r}"
            )
        if self.max_backoff.total_seconds() < 0:
            raise ValueError(
                f"max_backoff must be >= 0, got {self.max_backoff!r}"
            )
        if self.backoff_multiplier < 1.0:
            raise ValueError(
                f"backoff_multiplier must be >= 1.0, got {self.backoff_multiplier!r}"
            )
        if (
            self.per_attempt_timeout is not None
            and self.per_attempt_timeout.total_seconds() <= 0
        ):
            raise ValueError(
                f"per_attempt_timeout must be > 0 when set, got {self.per_attempt_timeout!r}"
            )
        if (
            self.overall_deadline is not None
            and self.overall_deadline.total_seconds() <= 0
        ):
            raise ValueError(
                f"overall_deadline must be > 0 when set, got {self.overall_deadline!r}"
            )
        if (
            self.wake_overall_deadline is not None
            and self.wake_overall_deadline.total_seconds() <= 0
        ):
            raise ValueError(
                "wake_overall_deadline must be > 0 when set, got "
                f"{self.wake_overall_deadline!r}"
            )
        if self.wake_max_attempts < 1:
            raise ValueError(
                f"wake_max_attempts must be >= 1, got {self.wake_max_attempts!r}"
            )
        # Normalize so callers can pass a plain ``set`` or ``tuple``.
        object.__setattr__(
            self,
            "retryable_status_codes_idempotent",
            frozenset(self.retryable_status_codes_idempotent),
        )
        object.__setattr__(
            self,
            "retryable_status_codes_non_idempotent",
            frozenset(self.retryable_status_codes_non_idempotent),
        )