Secure, Fast, and Extensible Sandbox runtime for AI agents.
#
# 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),
)