watasu 0.1.1__py3-none-any.whl

watasu/__init__.py

@@ -0,0 +1,206 @@
+"""Python SDK for Watasu sandboxes.
+
+The public sync surface talks to Watasu REST and WebSocket runtime endpoints.
+"""
+
+from .api import ApiClient, client
+from .connection_config import ApiParams, ConnectionConfig, ProxyTypes, Username
+from .exceptions import (
+    AuthenticationException,
+    BuildException,
+    FileNotFoundException,
+    FileUploadException,
+    GitAuthException,
+    GitUpstreamException,
+    InvalidArgumentException,
+    NotEnoughSpaceException,
+    NotFoundException,
+    RateLimitException,
+    SandboxException,
+    SandboxNotFoundException,
+    TemplateException,
+    TimeoutException,
+    VolumeException,
+)
+from .sandbox.commands.command_handle import (
+    CommandExitException,
+    CommandResult,
+    PtyOutput,
+    PtySize,
+    Stderr,
+    Stdout,
+)
+from .sandbox.commands.main import ProcessInfo
+from .sandbox.filesystem.filesystem import (
+    EntryInfo,
+    FileType,
+    FilesystemEvent,
+    FilesystemEventType,
+    WriteInfo,
+)
+from .sandbox.sandbox_api import (
+    ALL_TRAFFIC,
+    GitBranches,
+    GitFileStatus,
+    GitResetMode,
+    GitStatus,
+    GitHubMcpServer,
+    GitHubMcpServerConfig,
+    McpServer,
+    SandboxInfo,
+    SandboxInfoLifecycle,
+    SandboxLifecycle,
+    SandboxMetrics,
+    SandboxNetworkInfo,
+    SandboxNetworkOpts,
+    SandboxNetworkRule,
+    SandboxNetworkRuleInfo,
+    SandboxNetworkRules,
+    SandboxNetworkSelector,
+    SandboxNetworkSelectorContext,
+    SandboxNetworkTransform,
+    SandboxNetworkUpdate,
+    SandboxQuery,
+    SandboxState,
+    SnapshotInfo,
+    get_signature,
+)
+from .sandbox_async.main import AsyncSandbox
+from .sandbox_sync.commands.command_handle import CommandHandle
+from .sandbox_sync.filesystem.watch_handle import WatchHandle
+from .sandbox_sync.main import Sandbox
+from .sandbox_sync.paginator import SandboxPaginator, SnapshotPaginator
+from .stubs import (
+    AsyncSnapshotPaginator,
+    AsyncTemplate,
+    AsyncVolume,
+    AsyncWatchHandle,
+    BuildInfo,
+    BuildStatusReason,
+    CopyItem,
+    LogEntry,
+    LogEntryEnd,
+    LogEntryLevel,
+    LogEntryStart,
+    OutputHandler,
+    ReadyCmd,
+    Template,
+    TemplateBase,
+    TemplateBuildStatus,
+    TemplateBuildStatusResponse,
+    TemplateClass,
+    TemplateTag,
+    TemplateTagInfo,
+    Volume,
+    VolumeAndToken,
+    VolumeApiParams,
+    VolumeConnectionConfig,
+    VolumeEntryStat,
+    VolumeFileType,
+    VolumeInfo,
+    default_build_logger,
+    wait_for_file,
+    wait_for_port,
+    wait_for_process,
+    wait_for_timeout,
+    wait_for_url,
+)
+
+__all__ = [
+    "ALL_TRAFFIC",
+    "ApiClient",
+    "ApiParams",
+    "AsyncSandbox",
+    "AsyncSnapshotPaginator",
+    "AsyncTemplate",
+    "AsyncVolume",
+    "AsyncWatchHandle",
+    "AuthenticationException",
+    "BuildException",
+    "BuildInfo",
+    "BuildStatusReason",
+    "CommandExitException",
+    "CommandHandle",
+    "CommandResult",
+    "ConnectionConfig",
+    "CopyItem",
+    "EntryInfo",
+    "FileNotFoundException",
+    "FileType",
+    "FileUploadException",
+    "FilesystemEvent",
+    "FilesystemEventType",
+    "GitAuthException",
+    "GitBranches",
+    "GitFileStatus",
+    "GitHubMcpServer",
+    "GitHubMcpServerConfig",
+    "GitResetMode",
+    "GitStatus",
+    "GitUpstreamException",
+    "InvalidArgumentException",
+    "LogEntry",
+    "LogEntryEnd",
+    "LogEntryLevel",
+    "LogEntryStart",
+    "McpServer",
+    "NotEnoughSpaceException",
+    "NotFoundException",
+    "OutputHandler",
+    "ProxyTypes",
+    "PtyOutput",
+    "PtySize",
+    "RateLimitException",
+    "ReadyCmd",
+    "Sandbox",
+    "SandboxException",
+    "SandboxInfo",
+    "SandboxInfoLifecycle",
+    "SandboxLifecycle",
+    "SandboxMetrics",
+    "SandboxNetworkInfo",
+    "SandboxNetworkOpts",
+    "SandboxNetworkRule",
+    "SandboxNetworkRuleInfo",
+    "SandboxNetworkRules",
+    "SandboxNetworkSelector",
+    "SandboxNetworkSelectorContext",
+    "SandboxNetworkTransform",
+    "SandboxNetworkUpdate",
+    "SandboxNotFoundException",
+    "SandboxPaginator",
+    "SandboxQuery",
+    "SandboxState",
+    "SnapshotInfo",
+    "SnapshotPaginator",
+    "Stderr",
+    "Stdout",
+    "Template",
+    "TemplateBase",
+    "TemplateBuildStatus",
+    "TemplateBuildStatusResponse",
+    "TemplateClass",
+    "TemplateException",
+    "TemplateTag",
+    "TemplateTagInfo",
+    "TimeoutException",
+    "Username",
+    "Volume",
+    "VolumeAndToken",
+    "VolumeApiParams",
+    "VolumeConnectionConfig",
+    "VolumeEntryStat",
+    "VolumeException",
+    "VolumeFileType",
+    "VolumeInfo",
+    "WatchHandle",
+    "WriteInfo",
+    "client",
+    "default_build_logger",
+    "get_signature",
+    "wait_for_file",
+    "wait_for_port",
+    "wait_for_process",
+    "wait_for_timeout",
+    "wait_for_url",
+]

watasu/_transport/__init__.py

@@ -0,0 +1,6 @@
+from .control import ControlClient
+from .data_plane import DataPlaneClient
+from .errors import map_http_error
+from .process_ws import ProcessSocket
+
+__all__ = ["ControlClient", "DataPlaneClient", "ProcessSocket", "map_http_error"]

watasu/_transport/control.py

@@ -0,0 +1,71 @@
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+
+import requests
+
+from watasu.connection_config import ConnectionConfig
+from watasu.exceptions import format_request_timeout_error
+from watasu._transport.errors import map_http_error
+
+
+class ControlClient:
+    def __init__(self, config: ConnectionConfig):
+        self.config = config
+        self._session = requests.Session()
+        self._session.trust_env = False
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: Optional[Dict[str, Any]] = None,
+        params: Optional[Dict[str, Any]] = None,
+        request_timeout: Optional[float] = None,
+        resource: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        try:
+            response = self._session.request(
+                method,
+                self.config.control_url(path),
+                headers=self.config.auth_headers,
+                json=json,
+                params=params,
+                timeout=self.config.get_request_timeout(request_timeout),
+                proxies=_requests_proxies(self.config.proxy),
+            )
+        except requests.Timeout:
+            raise format_request_timeout_error()
+
+        if response.status_code < 400:
+            if not response.content:
+                return {}
+            return response.json()
+
+        payload: Any
+        try:
+            payload = response.json()
+        except ValueError:
+            payload = response.text
+        raise map_http_error(response.status_code, payload, response.text, resource=resource)
+
+    def get(self, path: str, **kwargs: Any) -> Dict[str, Any]:
+        return self.request("GET", path, **kwargs)
+
+    def post(self, path: str, **kwargs: Any) -> Dict[str, Any]:
+        return self.request("POST", path, **kwargs)
+
+    def patch(self, path: str, **kwargs: Any) -> Dict[str, Any]:
+        return self.request("PATCH", path, **kwargs)
+
+    def delete(self, path: str, **kwargs: Any) -> Dict[str, Any]:
+        return self.request("DELETE", path, **kwargs)
+
+
+def _requests_proxies(proxy: Any):
+    if proxy is None:
+        return None
+    if isinstance(proxy, str):
+        return {"http": proxy, "https": proxy}
+    return proxy

watasu/_transport/data_plane.py

@@ -0,0 +1,93 @@
+from __future__ import annotations
+
+from typing import Any, Dict, Iterator, Optional
+
+import requests
+
+from watasu.connection_config import ConnectionConfig
+from watasu.exceptions import format_request_timeout_error
+from watasu._transport.errors import map_http_error
+
+
+class DataPlaneClient:
+    def __init__(
+        self,
+        base_url: str,
+        token: str,
+        config: ConnectionConfig,
+    ) -> None:
+        self.base_url = base_url.rstrip("/")
+        self.token = token
+        self.config = config
+        self._session = requests.Session()
+        self._session.trust_env = False
+
+    @property
+    def headers(self) -> Dict[str, str]:
+        return {"Authorization": f"Bearer {self.token}"}
+
+    def url(self, path: str) -> str:
+        return f"{self.base_url}/{path.lstrip('/')}"
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: Optional[Dict[str, Any]] = None,
+        json: Optional[Dict[str, Any]] = None,
+        data: Optional[bytes] = None,
+        request_timeout: Optional[float] = None,
+        resource: Optional[str] = None,
+        stream: bool = False,
+    ) -> requests.Response:
+        try:
+            response = self._session.request(
+                method,
+                self.url(path),
+                headers=self.headers,
+                params=params,
+                json=json,
+                data=data,
+                timeout=self.config.get_request_timeout(request_timeout),
+                proxies=_requests_proxies(self.config.proxy),
+                stream=stream,
+            )
+        except requests.Timeout:
+            raise format_request_timeout_error()
+
+        if response.status_code < 400:
+            return response
+
+        try:
+            payload: Any = response.json()
+        except ValueError:
+            payload = response.text
+        raise map_http_error(response.status_code, payload, response.text, resource=resource)
+
+    def get_json(self, path: str, **kwargs: Any) -> Dict[str, Any]:
+        return self.request("GET", path, **kwargs).json()
+
+    def post_json(self, path: str, **kwargs: Any) -> Dict[str, Any]:
+        return self.request("POST", path, **kwargs).json()
+
+    def put_json(self, path: str, **kwargs: Any) -> Dict[str, Any]:
+        return self.request("PUT", path, **kwargs).json()
+
+    def delete_json(self, path: str, **kwargs: Any) -> Dict[str, Any]:
+        return self.request("DELETE", path, **kwargs).json()
+
+    def get_bytes(self, path: str, **kwargs: Any) -> bytes:
+        return self.request("GET", path, **kwargs).content
+
+    def iter_bytes(self, path: str, chunk_size: int = 65_536, **kwargs: Any) -> Iterator[bytes]:
+        response = self.request("GET", path, stream=True, **kwargs)
+        return response.iter_content(chunk_size=chunk_size)
+
+
+def _requests_proxies(proxy: Any):
+    if proxy is None:
+        return None
+    if isinstance(proxy, str):
+        return {"http": proxy, "https": proxy}
+    return proxy

watasu/_transport/errors.py

@@ -0,0 +1,55 @@
+from __future__ import annotations
+
+from typing import Any, Mapping, Optional
+
+from watasu.exceptions import (
+    AuthenticationException,
+    FileNotFoundException,
+    InvalidArgumentException,
+    NotEnoughSpaceException,
+    NotFoundException,
+    RateLimitException,
+    SandboxException,
+    SandboxNotFoundException,
+    TimeoutException,
+)
+
+
+def error_message(payload: Any, fallback: str) -> str:
+    if isinstance(payload, Mapping):
+        errors = payload.get("errors")
+        if isinstance(errors, list) and errors:
+            return "; ".join(str(item) for item in errors)
+        for key in ("message", "reason", "error"):
+            value = payload.get(key)
+            if value:
+                return str(value)
+    return fallback
+
+
+def map_http_error(
+    status_code: int,
+    payload: Any,
+    fallback: str,
+    *,
+    resource: Optional[str] = None,
+) -> Exception:
+    message = error_message(payload, fallback)
+
+    if status_code in {401, 403}:
+        return AuthenticationException(message)
+    if status_code == 404:
+        if resource in {"file", "directory"}:
+            return FileNotFoundException(message)
+        if resource == "sandbox":
+            return SandboxNotFoundException(message)
+        return NotFoundException(message)
+    if status_code in {408, 504}:
+        return TimeoutException(message)
+    if status_code == 429:
+        return RateLimitException(message)
+    if status_code == 507:
+        return NotEnoughSpaceException(message)
+    if status_code in {400, 409, 413, 422}:
+        return InvalidArgumentException(message)
+    return SandboxException(message)

watasu/_transport/process_ws.py

@@ -0,0 +1,180 @@
+from __future__ import annotations
+
+import base64
+import json
+import queue
+import threading
+import time
+from typing import Any, Dict, Iterable, Iterator, Optional, Union
+
+from watasu.connection_config import KEEPALIVE_PING_INTERVAL_SEC
+from watasu.exceptions import SandboxException, format_request_timeout_error
+
+
+class ProcessSocket:
+    def __init__(
+        self,
+        base_url: str,
+        token: str,
+        path: str,
+        *,
+        keepalive_interval: float = KEEPALIVE_PING_INTERVAL_SEC,
+        request_timeout: Optional[float] = None,
+    ) -> None:
+        self.base_url = base_url.rstrip("/")
+        self.token = token
+        self.path = path
+        self.keepalive_interval = keepalive_interval
+        self.request_timeout = request_timeout
+        self._ws = None
+        self._closed = False
+
+    def connect(self) -> "ProcessSocket":
+        try:
+            import websocket
+        except ImportError as error:
+            raise SandboxException(
+                "The 'websocket-client' package is required for command streaming."
+            ) from error
+
+        ws_url = _ws_url(self.base_url, self.path)
+        self._ws = websocket.create_connection(
+            ws_url,
+            header=[f"Authorization: Bearer {self.token}"],
+            timeout=self.request_timeout,
+        )
+        return self
+
+    def send_json(self, payload: Dict[str, Any]) -> None:
+        self._require_open().send(json.dumps(payload))
+
+    def send_stdin(self, data: Union[str, bytes]) -> None:
+        if isinstance(data, bytes):
+            raw = data
+        else:
+            raw = data.encode("utf-8")
+        self.send_json({"type": "stdin", "data": base64.b64encode(raw).decode("ascii")})
+
+    def send_signal(self, signal: str = "SIGKILL") -> None:
+        self.send_json({"type": "signal", "signal": signal})
+
+    def close(self) -> None:
+        self._closed = True
+        if self._ws is not None:
+            self._ws.close()
+
+    def frames(self, timeout: Optional[float] = None) -> Iterator[Dict[str, Any]]:
+        ws = self._require_open()
+        deadline = None if timeout in (None, 0) else time.monotonic() + float(timeout)
+        next_ping = time.monotonic() + self.keepalive_interval
+
+        while not self._closed:
+            now = time.monotonic()
+            if now >= next_ping:
+                try:
+                    ws.ping("watasu-sdk")
+                except Exception as error:
+                    raise SandboxException(f"process websocket ping failed: {error}") from error
+                next_ping = now + self.keepalive_interval
+
+            socket_timeout = min(1.0, max(0.1, next_ping - now))
+            if deadline is not None:
+                remaining = deadline - now
+                if remaining <= 0:
+                    raise format_request_timeout_error()
+                socket_timeout = min(socket_timeout, remaining)
+
+            ws.settimeout(socket_timeout)
+            try:
+                message = ws.recv()
+            except TimeoutError:
+                continue
+            except Exception as error:
+                if _is_timeout_error(error):
+                    continue
+                if self._closed:
+                    return
+                raise SandboxException(f"process websocket failed: {error}") from error
+
+            if message is None:
+                return
+            if isinstance(message, bytes):
+                raise SandboxException("process websocket returned binary frame")
+            try:
+                frame = json.loads(message)
+            except json.JSONDecodeError as error:
+                raise SandboxException(f"process websocket returned invalid JSON: {message}") from error
+            if frame.get("type") in {"ready", "pong"}:
+                continue
+            if frame.get("type") == "error":
+                raise SandboxException(frame.get("message") or frame.get("code") or "process error")
+            yield frame
+
+    def _require_open(self):
+        if self._ws is None:
+            raise SandboxException("process websocket is not connected")
+        return self._ws
+
+
+class ProcessEventStream:
+    def __init__(self, socket: ProcessSocket, frames: Iterable[Dict[str, Any]]) -> None:
+        self.socket = socket
+        self._frames = iter(frames)
+
+    def __iter__(self) -> "ProcessEventStream":
+        return self
+
+    def __next__(self) -> Dict[str, Any]:
+        return next(self._frames)
+
+    def close(self) -> None:
+        self.socket.close()
+
+
+class QueuedProcessEventStream:
+    def __init__(self, socket: ProcessSocket, first_frame: Dict[str, Any], frames: Iterable[Dict[str, Any]]) -> None:
+        self.socket = socket
+        self._queue: "queue.Queue[Optional[Dict[str, Any]]]" = queue.Queue()
+        self._queue.put(first_frame)
+        self._closed = False
+
+        def pump() -> None:
+            try:
+                for frame in frames:
+                    self._queue.put(frame)
+            finally:
+                self._queue.put(None)
+
+        self._thread = threading.Thread(target=pump, daemon=True)
+        self._thread.start()
+
+    def __iter__(self) -> "QueuedProcessEventStream":
+        return self
+
+    def __next__(self) -> Dict[str, Any]:
+        item = self._queue.get()
+        if item is None:
+            raise StopIteration
+        return item
+
+    def close(self) -> None:
+        self._closed = True
+        self.socket.close()
+
+
+def _ws_url(base_url: str, path: str) -> str:
+    if base_url.startswith("https://"):
+        prefix = "wss://"
+        rest = base_url[len("https://") :]
+    elif base_url.startswith("http://"):
+        prefix = "ws://"
+        rest = base_url[len("http://") :]
+    else:
+        prefix = "wss://"
+        rest = base_url
+    return f"{prefix}{rest.rstrip('/')}/{path.lstrip('/')}"
+
+
+def _is_timeout_error(error: Exception) -> bool:
+    name = error.__class__.__name__.lower()
+    return "timeout" in name

watasu/api/__init__.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+from typing import Any
+
+from watasu._transport.control import ControlClient
+from watasu.connection_config import ConnectionConfig
+
+
+class ApiClient(ControlClient):
+    def __init__(self, **opts: Any):
+        super().__init__(ConnectionConfig(**opts))
+
+
+def client(**opts: Any) -> ApiClient:
+    return ApiClient(**opts)
+
+
+__all__ = ["ApiClient", "client"]