tabsail 0.1.0__py3-none-any.whl

tabsail/__init__.py

@@ -0,0 +1,69 @@
+"""TabSail v1 asynchronous SDK; browser actions belong to your CDP client."""
+
+from .client import AsyncTabSail, OwnedSession
+from .errors import (
+    APIError,
+    CleanupError,
+    ConfigurationError,
+    HandoffCancelledError,
+    NetworkError,
+    ProtocolError,
+    RequestCancelledError,
+    RequestTimeoutError,
+    ResultUnknownError,
+    SDKError,
+    SessionTerminatedError,
+    WaitTimeoutError,
+)
+from .models import (
+    BrowserSession,
+    Profile,
+    ConnectionGrant,
+    Controller,
+    FileOrigin,
+    FileStatus,
+    Handoff,
+    HandoffCheckpoint,
+    HandoffStatus,
+    HandoffSummary,
+    Page,
+    ResourceError,
+    SessionFile,
+    SessionStatus,
+)
+from .resources import DownloadStream
+from .transport import RequestOptions
+
+__version__ = "0.1.0"
+__all__ = [
+    "AsyncTabSail",
+    "OwnedSession",
+    "RequestOptions",
+    "BrowserSession",
+    "Profile",
+    "ConnectionGrant",
+    "Handoff",
+    "HandoffSummary",
+    "HandoffCheckpoint",
+    "SessionFile",
+    "Page",
+    "ResourceError",
+    "SessionStatus",
+    "Controller",
+    "HandoffStatus",
+    "FileStatus",
+    "FileOrigin",
+    "DownloadStream",
+    "SDKError",
+    "APIError",
+    "ConfigurationError",
+    "NetworkError",
+    "RequestTimeoutError",
+    "WaitTimeoutError",
+    "ProtocolError",
+    "RequestCancelledError",
+    "ResultUnknownError",
+    "SessionTerminatedError",
+    "HandoffCancelledError",
+    "CleanupError",
+]

tabsail/client.py

@@ -0,0 +1,286 @@
+"""Async HTTP client and ownership scoped session context."""
+
+from __future__ import annotations
+
+import asyncio
+from dataclasses import replace
+from copy import deepcopy
+import math
+import os
+import time
+from types import TracebackType
+from typing import Any, Literal
+
+import httpx
+
+from .errors import (
+    APIError,
+    CleanupError,
+    ConfigurationError,
+    ProtocolError,
+    ResultUnknownError,
+    WaitTimeoutError,
+)
+from .models import BrowserSession
+from .resources import Profiles, Sessions, keyed
+from .transport import RequestOptions, Transport
+
+
+class AsyncTabSail:
+    def __init__(
+        self,
+        *,
+        base_url: str | None = None,
+        api_key: str | None = None,
+        request_timeout_ms: float = 15000,
+        max_retries: int = 0,
+        transport: httpx.AsyncBaseTransport | None = None,
+    ) -> None:
+        base_url = base_url if base_url is not None else os.environ.get("TABSAIL_BASE_URL")
+        api_key = api_key if api_key is not None else os.environ.get("TABSAIL_API_KEY")
+        if not base_url or not api_key:
+            raise ConfigurationError(
+                "Set base_url and api_key or TABSAIL_BASE_URL and TABSAIL_API_KEY."
+            )
+        self._transport = Transport(base_url, api_key, request_timeout_ms, max_retries, transport)
+        self.sessions = Sessions(self._transport)
+        self.profiles = Profiles(self._transport)
+
+    def __repr__(self) -> str:
+        return "<AsyncTabSail credentials=[REDACTED]>"
+
+    async def __aenter__(self) -> AsyncTabSail:
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> None:
+        await self.aclose()
+
+    async def aclose(self) -> None:
+        """Close local HTTP connections; remote BrowserSessions are unchanged."""
+        await self._transport.aclose()
+
+    def with_session(
+        self,
+        *,
+        timeout_seconds: int | None = None,
+        viewport: dict[str, int] | None = None,
+        metadata: dict[str, str] | None = None,
+        region: Literal["auto", "west", "asia"] | None = None,
+        options: RequestOptions | None = None,
+        ready_timeout_ms: float = 60000,
+        cleanup_timeout_ms: float = 30000,
+        poll_interval_ms: float = 500,
+        wait_for_capacity: bool = False,
+        idle_timeout_seconds: int | None = None,
+        browser: dict[str, Any] | None = None,
+        profile: dict[str, Any] | None = None,
+    ) -> OwnedSession:
+        return OwnedSession(
+            self,
+            timeout_seconds,
+            viewport,
+            metadata,
+            region,
+            options,
+            ready_timeout_ms,
+            cleanup_timeout_ms,
+            poll_interval_ms,
+            wait_for_capacity,
+            idle_timeout_seconds,
+            browser,
+            profile,
+        )
+
+
+class OwnedSession:
+    def __init__(
+        self,
+        client: AsyncTabSail,
+        timeout_seconds: int | None,
+        viewport: dict[str, int] | None,
+        metadata: dict[str, str] | None,
+        region: Literal["auto", "west", "asia"] | None,
+        options: RequestOptions | None,
+        ready_timeout_ms: float,
+        cleanup_timeout_ms: float,
+        poll_interval_ms: float,
+        wait_for_capacity: bool,
+        idle_timeout_seconds: int | None = None,
+        browser: dict[str, Any] | None = None,
+        profile: dict[str, Any] | None = None,
+    ) -> None:
+        if any(
+            not math.isfinite(v) or v <= 0
+            for v in (ready_timeout_ms, cleanup_timeout_ms, poll_interval_ms)
+        ):
+            raise ConfigurationError(
+                "Session wait and cleanup budgets must be finite positive milliseconds."
+            )
+        self._client = client
+        self._timeout_seconds = timeout_seconds
+        self._idle_timeout_seconds = idle_timeout_seconds
+        self._browser = deepcopy(browser)
+        self._profile = deepcopy(profile)
+        self._viewport = deepcopy(viewport)
+        self._metadata = deepcopy(metadata)
+        self._region = region
+        self._options = keyed(options)
+        if wait_for_capacity and self._options.timeout_ms is None:
+            self._options = replace(self._options, timeout_ms=300000)
+        self._wait_for_capacity = wait_for_capacity
+        self._ready_timeout_ms = ready_timeout_ms
+        self._cleanup_timeout_ms = cleanup_timeout_ms
+        self._poll_interval_ms = poll_interval_ms
+        self.session_id: str | None = None
+        self._unknown = False
+        self._entered = False
+
+    async def __aenter__(self) -> BrowserSession:
+        if self._entered:
+            raise ConfigurationError("An owned session context may only be entered once.")
+        self._entered = True
+        try:
+            # Cancellation here proves creation was not sent.
+            await asyncio.sleep(0)
+            started = time.monotonic()
+            capacity_attempt = 0
+            while True:
+                remaining_create = (
+                    None if self._options.timeout_ms is None
+                    else self._options.timeout_ms - (time.monotonic() - started) * 1000
+                )
+                if remaining_create is not None and remaining_create <= 0:
+                    raise WaitTimeoutError("Browser capacity wait timed out.", code="CAPACITY_WAIT_TIMEOUT")
+                try:
+                    session = await self._client.sessions.create(
+                        timeout_seconds=self._timeout_seconds,
+                        idle_timeout_seconds=self._idle_timeout_seconds,
+                        browser=self._browser,
+                        profile=self._profile,
+                        viewport=self._viewport,
+                        metadata=self._metadata,
+                        region=self._region,
+                        options=replace(self._options, timeout_ms=remaining_create),
+                    )
+                    break
+                except APIError as error:
+                    if not (
+                        self._wait_for_capacity and error.retryable and (
+                            (error.status == 503 and error.code in ("NO_CAPACITY", "STARTUP_BUSY"))
+                            or (error.status == 429 and error.code == "CREATE_RATE_LIMITED")
+                        )
+                    ):
+                        raise
+                    assert self._options.timeout_ms is not None
+                    left = self._options.timeout_ms - (time.monotonic() - started) * 1000
+                    if left <= 0:
+                        raise WaitTimeoutError("Browser capacity wait timed out.", code="CAPACITY_WAIT_TIMEOUT") from None
+                    delay = self._client._transport._delay(capacity_attempt, error.retry_after, 10.0)
+                    capacity_attempt += 1
+                    await asyncio.sleep(min(left / 1000, delay))
+                    if delay >= left / 1000:
+                        raise WaitTimeoutError("Browser capacity wait timed out.", code="CAPACITY_WAIT_TIMEOUT") from None
+            self.session_id = session.id
+            remaining = self._ready_timeout_ms
+            if self._options.timeout_ms is not None:
+                remaining = min(
+                    remaining, self._options.timeout_ms - (time.monotonic() - started) * 1000
+                )
+            if remaining <= 0:
+                raise WaitTimeoutError(
+                    "The owned session readiness deadline elapsed.", session_id=session.id
+                )
+            return await self._client.sessions.wait_until_ready(
+                session.id,
+                timeout_ms=remaining,
+                poll_interval_ms=self._poll_interval_ms,
+                options=self._options,
+            )
+        except BaseException as primary:
+            self._unknown = isinstance(primary, (ResultUnknownError, ProtocolError)) or getattr(
+                primary, "result_unknown", False
+            )
+            if self.session_id is not None or self._unknown:
+                await self._finish(primary)
+            raise
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> Literal[False]:
+        await self._finish(exc)
+        return False
+
+    async def _cleanup(self) -> None:
+        # This deadline covers recovery, close, all requests/retries and released confirmation.
+        async with asyncio.timeout(self._cleanup_timeout_ms / 1000):
+            options = replace(
+                self._options,
+                timeout_ms=None,
+                max_retries=2,
+                request_timeout_ms=min(self._cleanup_timeout_ms, 5000),
+            )
+            if self.session_id is None:
+                recovered = await self._client.sessions.create(
+                    timeout_seconds=self._timeout_seconds,
+                    idle_timeout_seconds=self._idle_timeout_seconds,
+                        browser=self._browser,
+                        profile=self._profile,
+                    viewport=self._viewport,
+                    metadata=self._metadata,
+                        region=self._region,
+                    options=options,
+                )
+                self.session_id = recovered.id
+            await self._client.sessions.close(self.session_id, options=options)
+            await self._client.sessions.wait_until_released(
+                self.session_id,
+                timeout_ms=self._cleanup_timeout_ms,
+                poll_interval_ms=self._poll_interval_ms,
+                options=options,
+            )
+
+    async def _finish(self, primary: BaseException | None) -> None:
+        task = asyncio.create_task(self._cleanup())
+        cancellation: asyncio.CancelledError | None = None
+        # Shield makes business cancellation independent of the bounded cleanup task.
+        while not task.done():
+            try:
+                await asyncio.shield(task)
+            except asyncio.CancelledError as error:
+                if task.done():
+                    break
+                cancellation = cancellation or error
+                continue
+            except BaseException:
+                break
+        cleanup_error: BaseException | None
+        try:
+            task.result()
+            cleanup_error = None
+        except BaseException as error:
+            cleanup_error = CleanupError(
+                error,
+                session_id=self.session_id,
+                idempotency_key=self._options.idempotency_key or "",
+            )
+        original = primary or cancellation
+        if original is not None:
+            original.session_id = self.session_id  # type: ignore[attr-defined]
+            original.idempotency_key = self._options.idempotency_key  # type: ignore[attr-defined]
+            if cleanup_error is not None:
+                original.cleanup_error = cleanup_error  # type: ignore[attr-defined]
+                original.add_note(
+                    "Owned session cleanup failed; see cleanup_error and session_id/idempotency_key."
+                )
+            if primary is None:
+                raise original
+        elif cleanup_error is not None:
+            raise cleanup_error from None

tabsail/errors.py

@@ -0,0 +1,125 @@
+"""Safe errors: credentials and connection URLs never appear in SDK error messages."""
+
+from __future__ import annotations
+
+import asyncio
+import re
+
+
+def redact(value: str, api_key: str = "") -> str:
+    if api_key:
+        value = value.replace(api_key, "[REDACTED]")
+    value = re.sub(r"(?i)Bearer\s+\S+", "Bearer [REDACTED]", value)
+    value = re.sub(r"(?:https?|wss?)://[^\s<>\"']+", "[REDACTED URL]", value)
+    value = re.sub(
+        r"(?i)(?:api[_-]?key|authorization|token)\s*[=:]\s*[^\s,;]+", "[REDACTED]", value
+    )
+    return value[:512]
+
+
+class SDKError(Exception):
+    def __init__(
+        self,
+        message: str,
+        *,
+        status: int | None = None,
+        code: str | None = None,
+        retryable: bool = False,
+        request_id: str | None = None,
+        retry_after: str | None = None,
+        session_id: str | None = None,
+    ) -> None:
+        super().__init__(redact(message))
+        self.status = status
+        self.code = code
+        self.retryable = retryable
+        self.request_id = request_id
+        self.retry_after = retry_after
+        self.session_id = session_id
+
+
+class ConfigurationError(SDKError):
+    pass
+
+
+class APIError(SDKError):
+    pass
+
+
+class NetworkError(SDKError):
+    pass
+
+
+class RequestTimeoutError(SDKError):
+    pass
+
+
+class WaitTimeoutError(SDKError):
+    pass
+
+
+class ProtocolError(SDKError):
+    pass
+
+
+class SessionTerminatedError(SDKError):
+    pass
+
+
+class HandoffCancelledError(SDKError):
+    pass
+
+
+class RequestCancelledError(asyncio.CancelledError):
+    """Cancellation retains normal asyncio cancellation semantics."""
+
+    def __init__(
+        self,
+        *,
+        session_id: str | None = None,
+        idempotency_key: str | None = None,
+        result_unknown: bool = False,
+    ) -> None:
+        super().__init__("TabSail request was cancelled.")
+        self.session_id = session_id
+        self.idempotency_key = idempotency_key
+        self.result_unknown = result_unknown
+        self.cleanup_error: BaseException | None = None
+
+
+class ResultUnknownError(SDKError):
+    def __init__(
+        self,
+        primary_error: SDKError,
+        *,
+        idempotency_key: str | None = None,
+        session_id: str | None = None,
+    ) -> None:
+        super().__init__(
+            "The request outcome is unknown. Do not blindly repeat this operation; "
+            "recover session creation with the same idempotency key or inspect session files.",
+            status=primary_error.status,
+            code=primary_error.code,
+            retryable=primary_error.retryable,
+            retry_after=primary_error.retry_after,
+            request_id=primary_error.request_id,
+            session_id=session_id,
+        )
+        self.primary_error = primary_error
+        self.idempotency_key = idempotency_key
+        self.result_unknown = True
+        self.cleanup_error: BaseException | None = None
+
+
+class CleanupError(SDKError):
+    def __init__(
+        self, cleanup_error: BaseException, *, session_id: str | None, idempotency_key: str
+    ) -> None:
+        super().__init__(
+            "Owned session cleanup could not confirm release. Recover using the same "
+            "idempotency key, close the session, and wait for released_at.",
+            session_id=session_id,
+        )
+        self.cleanup_error = cleanup_error
+        self.idempotency_key = idempotency_key
+        self.result_unknown = session_id is None