snowflake-sandbox-python 0.2.1a1__py3-none-any.whl

snowflake/sandbox/_transport_errors.py

@@ -0,0 +1,270 @@
+"""Error mapping and retry-timing helpers shared by the transport twins.
+
+Loop-agnostic pieces used by both the async ``_transport`` and the sync
+``_sync_transport``: the single terminal HTTP-status → ``SandboxError`` table, the
+error-envelope unwrapping, the ``Retry-After`` / rate-limit backoff math, the
+response classifiers that decide whether a failure is safe to retry, and the SSE
+JSON-decode error. Extracted into a dependency-free leaf so both transports import
+one copy, rather than the sync twin reaching into the async module for them.
+"""
+
+from __future__ import annotations
+
+import json
+import math
+import random
+from collections.abc import Mapping
+from email.utils import parsedate_to_datetime
+from typing import Any, Final
+
+import httpx
+
+from snowflake.sandbox._retry import (
+    DEFAULT_COLD_START_DELAYS_S,
+    compute_backoff,
+)
+from snowflake.sandbox.config import REAUTH_GS_CODES
+from snowflake.sandbox.exceptions import (
+    SandboxAuthError,
+    SandboxConflictError,
+    SandboxError,
+    SandboxExecTimeoutError,
+    SandboxFileTooLargeError,
+    SandboxNotFoundError,
+    SandboxNotImplementedError,
+    SandboxRateLimitError,
+    SandboxTransportError,
+    SandboxValidationError,
+)
+
+# 409 (and 503) are conditionally retried for a non-idempotent request only when
+# the response body says the work was rejected rather than attempted.
+_NOT_READY_REASONS: Final = {"not_ready", "not-ready", "starting", "pending"}
+
+# Every retry class shares one attempt budget so no path can retry forever. The
+# streaming paths (`stream_sse`, `download`) used to retry a 429 without any cap
+# -- measured at 153 requests in 8s -- because the Retry-After hint was honored
+# unconditionally. They now stop at the same budget `request()` uses and surface
+# `SandboxRateLimitError`.
+_RATE_LIMIT_MAX_ATTEMPTS: Final = len(DEFAULT_COLD_START_DELAYS_S)
+# Upper bound on a server-supplied Retry-After. A hostile or buggy header
+# (`Retry-After: 1e309` -> sleep(inf) wedges the process; a multi-hour value
+# hangs an interactive caller) must never park the SDK indefinitely.
+_RETRY_AFTER_MAX_S: Final = 60.0
+
+
+class SandboxSSEDecodeError(SandboxError, ValueError):
+    """An SSE frame's ``data`` was not valid JSON.
+
+    Subclasses ``SandboxError`` so ``except SandboxError`` catches it (the bare
+    ``json.JSONDecodeError`` it replaces did not), and ``ValueError`` so existing
+    callers that already guarded ``json()`` with ``except (ValueError, TypeError)``
+    keep working -- ``json.JSONDecodeError`` was itself a ``ValueError``.
+    """
+
+
+# Cap on the raw-body fallback when the response is not the known error envelope,
+# so a 5xx HTML error page or stack trace can never be dumped whole into an
+# exception message a public caller sees.
+_ERROR_DETAIL_MAX: Final = 200
+
+
+def _error_detail(text: str) -> str:
+    """The public-facing detail to interpolate into an exception message.
+
+    The server returns errors as a ``{"error": {"message": ...}}`` JSON envelope;
+    unwrap that to the human ``message`` so a caller (and any log line) sees
+    ``container not found`` rather than the whole envelope. Only when the body is
+    *not* that envelope do we fall back to the raw text, truncated to
+    ``_ERROR_DETAIL_MAX`` so an internal 5xx error page / stack trace is never
+    surfaced verbatim.
+    """
+    stripped = text.strip()
+    if stripped:
+        try:
+            parsed: Any = json.loads(stripped)
+        except (ValueError, TypeError):
+            parsed = None
+        if isinstance(parsed, Mapping):
+            err = parsed.get("error")
+            if isinstance(err, Mapping):
+                message = err.get("message")
+                if isinstance(message, str) and message:
+                    return message
+    return stripped[:_ERROR_DETAIL_MAX]
+
+
+def _status_to_error(status: int, text: str) -> SandboxError:
+    """The single terminal status -> exception table for every path.
+
+    `request()`, `download`, and `stream_sse` previously each kept their own copy
+    and disagreed on 409 (``SandboxError("conflict")`` vs ``SandboxNotReadyError``),
+    on 413 (only download mapped it, so ``except SandboxFileTooLargeError`` around
+    an upload never fired), on 429, and on the unknown-status fallback
+    (``SandboxTransportError`` vs ``SandboxError``). Which exception a caller had to
+    catch depended on which internal helper routed the request. This is that one
+    table; all three paths raise from it.
+
+    The response body is passed through ``_error_detail``, which unwraps the
+    server's ``{"error": {"message": ...}}`` envelope to the human message and
+    truncates any non-envelope body -- so pass the *full* ``resp.text`` here, not a
+    pre-truncated slice.
+
+    A terminal 409 here is a genuine conflict, never a cold-start: the retry loop
+    consumes a "not ready" 409 before the request reaches this mapping, so a 409
+    that arrives here means a real conflict (a duplicate name, say), not "still
+    starting" -- which is why it maps to ``SandboxConflictError`` rather than
+    ``SandboxNotReadyError`` (mapping it to "not ready" told a caller reading a
+    directory that the sandbox was starting, and invited an endless retry).
+
+    501 maps to ``SandboxNotImplementedError`` (a permanent "route not wired",
+    e.g. ``stage_put``/``stage_get``) rather than the generic 5xx
+    ``SandboxTransportError`` -- so a caller does not read it as a retryable
+    transient failure; it must precede the ``5xx`` catch-all below.
+    """
+    detail = _error_detail(text)
+    if status == 400:
+        return SandboxValidationError(f"invalid request: {detail}")
+    if status in (401, 403):
+        return SandboxAuthError(f"HTTP {status}: {detail}")
+    if status == 404:
+        return SandboxNotFoundError(f"not found: {detail}")
+    if status == 408:
+        return SandboxExecTimeoutError(f"exec timeout: {detail}")
+    if status == 409:
+        return SandboxConflictError(f"resource conflict: {detail}")
+    if status == 413:
+        return SandboxFileTooLargeError(f"file too large: {detail}")
+    if status == 429:
+        return SandboxRateLimitError(f"rate-limited: {detail}")
+    if status == 501:
+        return SandboxNotImplementedError(f"not implemented: {detail}")
+    if 500 <= status < 600:
+        return SandboxTransportError(f"HTTP {status}: {detail}")
+    return SandboxError(f"HTTP {status}: {detail}")
+
+
+def _says_not_ready(resp: httpx.Response) -> bool:
+    """True when the body identifies the response as "rejected, not attempted".
+
+    A ``409``/``503`` carrying one of the not-ready reasons is a definitive
+    statement that the request was refused before it ran, which makes a retry
+    safe even for a non-idempotent method. A bare ``503`` (an LB error page, an
+    empty body) proves nothing about whether the work happened.
+    """
+    try:
+        body = resp.json()
+    except Exception:
+        return False
+    if not isinstance(body, dict):
+        return False
+    code = str(body.get("code") or body.get("reason") or body.get("error") or "")
+    return code.lower().replace("_", "-") in {r.replace("_", "-") for r in _NOT_READY_REASONS}
+
+
+def _is_cold_start_409(resp: httpx.Response) -> bool:
+    return resp.status_code == 409 and _says_not_ready(resp)
+
+
+def _is_reauth_response(resp: httpx.Response) -> bool:
+    """True when a response means "re-authenticate", for EITHER error envelope.
+
+    An expired/invalid credential surfaces on this REST surface two ways, and the
+    reactive re-mint must catch both:
+    - a proper HTTP **401/403** (the OAuth ``Bearer`` path, and the v2 framework's
+      standard mapping), or
+    - the legacy Snowflake envelope a ``Snowflake Token=`` session token can draw —
+      HTTP **200** (or a 4xx) with a JSON body ``{"success": false, "code":
+      "390111", ...}`` (390111/390112/390114/390115; see ``REAUTH_GS_CODES``).
+
+    The body is inspected only when the response declares JSON, and a body with
+    ``success: true`` or a non-reauth ``code`` (i.e. every normal domain response)
+    is not a reauth signal — so this never mistakes an ordinary 2xx for expiry.
+    """
+    if resp.status_code in (401, 403):
+        return True
+    if "json" not in resp.headers.get("content-type", "").lower():
+        return False
+    try:
+        body = resp.json()
+    except Exception:  # noqa: BLE001 - unparseable/non-JSON → not a reauth envelope
+        return False
+    if not isinstance(body, dict) or body.get("success") is True:
+        return False
+    return str(body.get("code") or "") in REAUTH_GS_CODES
+
+
+def _is_clean_goaway(exc: BaseException) -> bool:
+    """True when the error is an HTTP/2 GOAWAY with NO_ERROR before any streams.
+
+    HTTP/2 servers send GOAWAY frames to gracefully close connections. When the
+    frame has error_code=0 (NO_ERROR) and last_stream_id is very high (meaning
+    no streams were processed on this connection), the server is telling us it
+    closed the connection before processing our request. This is safe to retry
+    even for non-idempotent methods.
+
+    The error message format from httpcore is:
+    <ConnectionTerminated error_code:0, last_stream_id:2147483647, additional_data:None>
+    """
+    msg = str(exc)
+    if "ConnectionTerminated" not in msg:
+        return False
+    # error_code:0 or error_code: 0 means NO_ERROR (graceful close)
+    if "error_code:0" not in msg and "error_code: 0" not in msg:
+        return False
+    # last_stream_id:2147483647 means no streams were processed (max value)
+    # This is the key indicator that our request wasn't touched
+    return "last_stream_id:2147483647" in msg or "last_stream_id: 2147483647" in msg
+
+
+def _retry_after_seconds(resp: httpx.Response) -> float | None:
+    """Seconds to wait from a ``Retry-After`` header, or ``None`` if unusable.
+
+    Sanitized against a hostile or malformed header:
+
+    - ``inf``/``nan`` are rejected (``None``) so the caller falls back to bounded
+      exponential backoff rather than ``sleep(inf)``.
+    - a finite value is clamped to ``[0, _RETRY_AFTER_MAX_S]`` -- a negative delta
+      (a stale HTTP-date) becomes ``0``, and an absurd multi-hour value is capped.
+    - both header forms are supported: delay-seconds (``"120"``) and an HTTP-date
+      (``"Wed, 21 Oct 2026 07:28:00 GMT"``, converted to a delta from now).
+    """
+    raw = resp.headers.get("Retry-After")
+    if not raw:
+        return None
+    raw = raw.strip()
+    try:
+        value = float(raw)
+    except ValueError:
+        # Not a number -- try the HTTP-date form.
+        try:
+            when = parsedate_to_datetime(raw)
+        except (TypeError, ValueError):
+            return None
+        if when is None:
+            return None
+        import datetime as _dt
+
+        now = _dt.datetime.now(_dt.UTC)
+        if when.tzinfo is None:
+            when = when.replace(tzinfo=_dt.UTC)
+        value = (when - now).total_seconds()
+    if not math.isfinite(value):
+        return None
+    return max(0.0, min(value, _RETRY_AFTER_MAX_S))
+
+
+def _rate_limit_delay(resp: httpx.Response, attempt: int, rng: random.Random) -> float | None:
+    """Delay before retry ``attempt`` of a 429, or ``None`` when the budget is spent.
+
+    Honors a sanitized ``Retry-After`` when present, otherwise falls back to the
+    cold-start backoff schedule. Jitter is applied **upward only** on a server
+    hint: the server told us the earliest safe moment, so retrying before it would
+    violate the contract and re-hammer a gateway that just asked us to back off.
+    """
+    if attempt > _RATE_LIMIT_MAX_ATTEMPTS:
+        return None
+    hint = _retry_after_seconds(resp)
+    if hint is not None:
+        return hint + rng.uniform(0.0, 0.25) * hint
+    return compute_backoff(attempt, delays=DEFAULT_COLD_START_DELAYS_S, rng=rng) or 1.0