scalebrowser 0.2.0__py3-none-any.whl

scalebrowser/errors.py

@@ -0,0 +1,97 @@
+"""Typed SDK errors and the daemon's stable numeric error codes.
+
+The daemon returns error bodies shaped ``{ "code": <4001-4010>, "message": "…" }``
+with the HTTP status from ``core::Error::http_status()`` (docs/features/api.md, SPEC §5).
+"""
+
+from __future__ import annotations
+
+from typing import Any, Final, Optional
+
+
+class ErrorCode:
+    """Stable numeric API error codes (SPEC §5, ``crates/core/src/error.rs``)."""
+
+    NOT_FOUND: Final = 4001
+    PROXY_GEO: Final = 4002
+    CAPACITY: Final = 4003
+    ENGINE_MISSING: Final = 4004
+    PREFLIGHT: Final = 4005
+    ALREADY_RUNNING: Final = 4006
+    # Retired: the removed Methode-D (VM) tier produced this. Kept reserved (never
+    # reused) to match the server's append-only code contract; never returned now.
+    VM_PROVISION_FAILED: Final = 4007
+    # The subscription's abo-wide concurrent-browser allowance is used up (DEC-012).
+    # Distinct from CAPACITY (4003 = this machine is full, wait): the caller's move
+    # is to stop a running browser anywhere or upgrade the plan.
+    CONCURRENCY_LIMIT: Final = 4008
+    UNAUTHORIZED: Final = 4010
+
+
+_CODE_LABELS: Final[dict[int, str]] = {
+    4001: "Not found",
+    4002: "Proxy or geo check failed",
+    4003: "Capacity exceeded",
+    4004: "Engine missing",
+    4005: "Launch preflight failed",
+    4006: "Profile already running",
+    4008: "Concurrent-browser limit reached (subscription-wide)",
+    4010: "Unauthorized",
+}
+
+
+def code_label(code: Optional[int]) -> Optional[str]:
+    """Human-readable label for a coded business error, if known."""
+    return _CODE_LABELS.get(code) if code is not None else None
+
+
+class ScalebrowserError(Exception):
+    """Base class for every error raised by this SDK."""
+
+
+class ApiError(ScalebrowserError):
+    """A transport/contract error from the daemon REST API.
+
+    Carries the HTTP ``status`` and the daemon's numeric ``code`` so callers can
+    branch on auth failures or specific business errors (4001-4010).
+    """
+
+    def __init__(
+        self,
+        status: int,
+        code: Optional[int] = None,
+        message: Optional[str] = None,
+        body: Optional[dict[str, Any]] = None,
+    ) -> None:
+        self.status = status
+        self.code = code
+        self.body = body
+        label = code_label(code)
+        super().__init__(message or label or f"Request failed (HTTP {status})")
+
+    @property
+    def is_auth_error(self) -> bool:
+        """True for auth failures that should trigger re-authentication."""
+        return self.status == 401 or self.code == ErrorCode.UNAUTHORIZED
+
+    @property
+    def code_label(self) -> Optional[str]:
+        """Short label for the error code, if any."""
+        return code_label(self.code)
+
+
+class NetworkError(ScalebrowserError):
+    """A network-level failure — the daemon was unreachable (no HTTP response)."""
+
+    def __init__(self, message: str, cause: Optional[BaseException] = None) -> None:
+        super().__init__(message)
+        self.cause = cause
+
+
+class CdpError(ScalebrowserError):
+    """An error returned by the browser over the direct-CDP channel."""
+
+    def __init__(self, code: Optional[int], message: str, data: Any = None) -> None:
+        self.code = code
+        self.data = data
+        super().__init__(f"CDP error {code}: {message}" if code is not None else f"CDP error: {message}")

scalebrowser/events.py

@@ -0,0 +1,52 @@
+"""Live lifecycle event stream (``GET /v1/events``, AC-API-003).
+
+We read the ``text/event-stream`` over the authenticated transport and frame it
+into the typed :data:`~scalebrowser.models.Event` union, mirroring the behaviour
+of ``web-ui/src/api/events.ts``.
+"""
+
+from __future__ import annotations
+
+from typing import AsyncIterator, Optional
+
+from pydantic import ValidationError
+
+from ._http import AsyncTransport
+from .models import EVENT_ADAPTER, Event
+
+EVENTS_PATH = "/v1/events"
+
+
+def parse_sse_frame(frame: str) -> Optional[Event]:
+    """Extract and validate the ``data:`` payload of a single SSE frame."""
+    data_lines: list[str] = []
+    for line in frame.splitlines():
+        if line.startswith("data:"):
+            data_lines.append(line[5:].lstrip(" "))
+    if not data_lines:
+        return None
+    payload = "\n".join(data_lines)
+    if not payload or payload == "[DONE]":
+        return None
+    try:
+        return EVENT_ADAPTER.validate_json(payload)
+    except (ValidationError, ValueError):
+        return None
+
+
+async def iter_events(transport: AsyncTransport, path: str = EVENTS_PATH) -> AsyncIterator[Event]:
+    """Stream typed lifecycle events until the connection ends."""
+    frame_lines: list[str] = []
+    async for line in transport.stream_sse(path):
+        if line == "":
+            if frame_lines:
+                event = parse_sse_frame("\n".join(frame_lines))
+                frame_lines = []
+                if event is not None:
+                    yield event
+        else:
+            frame_lines.append(line)
+    if frame_lines:
+        event = parse_sse_frame("\n".join(frame_lines))
+        if event is not None:
+            yield event