feat: Deno process wrapper + new sandbox methods (#14)

Author: marvinhagemeister

src/deno_sandbox/console.py

@@ -1,4 +1,5 @@
-from typing import Any, Literal, Optional, cast
+from datetime import datetime, timezone
+from typing import Any, Literal, Optional, TypedDict, cast
 import httpx
 
 from deno_sandbox.api_types_generated import (
@@ -24,6 +25,16 @@ class Revision(RevisionWithoutTimelines):
     """The timelines associated with the revision."""
 
 
+class ExposeSSHResult(TypedDict):
+    hostname: str
+    username: str
+    port: int
+
+
+class ExposeHTTPResult(TypedDict):
+    domain: str
+
+
 class AsyncPaginatedList[T, O]:
     def __init__(
         self,
@@ -123,7 +134,10 @@ def client(self) -> httpx.AsyncClient:
         return self._client
 
     async def _request(
-        self, method: Literal["POST", "GET"], url: httpx.URL, data: Optional[Any] = None
+        self,
+        method: Literal["POST", "GET", "PATCH", "PUT", "DELETE"],
+        url: httpx.URL,
+        data: Optional[Any] = None,
     ) -> httpx.Response:
         response = await self.client.request(
             method=method, url=url, json=data, timeout=10.0
@@ -135,13 +149,11 @@ async def _request(
     async def post(self, path: str, data: any) -> dict:
         req_url = self._options["console_url"].join(path)
         response = await self._request("POST", req_url, data)
-        response.raise_for_status()
         return response.json()
 
     async def patch(self, path: str, data: any) -> dict:
         req_url = self._options["console_url"].join(path)
         response = await self._request("PATCH", req_url, data)
-        response.raise_for_status()
         return response.json()
 
     async def get(
@@ -153,7 +165,6 @@ async def get(
             req_url = req_url.copy_add_params(params)
 
         response = await self._request("GET", req_url)
-        response.raise_for_status()
         return response.json()
 
     async def get_or_none(
@@ -166,10 +177,10 @@ async def get_or_none(
                 return None
             raise
 
-    async def delete(self, path: str) -> None:
+    async def delete(self, path: str) -> httpx.Response:
         req_url = self._options["console_url"].join(path)
         response = await self._request("DELETE", req_url)
-        response.raise_for_status()
+        return response
 
     async def get_paginated[T](
         self, path: str, cursor: Optional[str], params: Optional[dict[str, Any]] = None
@@ -261,6 +272,36 @@ async def _volumes_list(
         )
         return volumes
 
+    async def _kill_sandbox(self, sandbox_id: str) -> None:
+        await self.delete(f"/api/v3/sandboxes/{sandbox_id}")
+
+    async def _extend_timeout(self, sandbox_id: str, stop_at_ms: int) -> datetime:
+        url = self._options["sandbox_url"].join(f"/api/v3/sandbox/{sandbox_id}")
+
+        result = await self._request("PATCH", url, {"stop_at_ms": stop_at_ms})
+
+        data = result.json()
+
+        return datetime.fromtimestamp(data["stop_at_ms"] / 1000, tz=timezone.utc)
+
+    async def _expose_http(self, sandbox_id: str, params: dict[str, int]) -> str:
+        url = self._options["sandbox_url"].join(
+            f"/api/v3/sandbox/{sandbox_id}/expose/http"
+        )
+
+        result = await self._request("POST", url, params)
+
+        data = cast(ExposeHTTPResult, result.json())
+        return data["domain"]
+
+    async def _expose_ssh(self, sandbox_id: str) -> ExposeSSHResult:
+        url = self._options["sandbox_url"].join(
+            f"/api/v3/sandbox/{sandbox_id}/expose/ssh"
+        )
+        response = await self._request("POST", url, {})
+
+        return cast(ExposeSSHResult, response.json())
+
 
 class ConsoleClient:
     def __init__(self, options: InternalOptions, bridge: AsyncBridge):
@@ -342,5 +383,17 @@ def _volumes_list(
         )
         return PaginatedList(self._bridge, paginated)
 
+    def _kill_sandbox(self, sandbox_id: str) -> None:
+        self._bridge.run(self._async._kill_sandbox(sandbox_id))
+
+    def _extend_timeout(self, sandbox_id: str, stop_at_ms: int) -> None:
+        self._bridge.run(self._async._extend_timeout(sandbox_id, stop_at_ms))
+
+    def _expose_http(self, sandbox_id: str, params: dict[str, int]) -> str:
+        return self._bridge.run(self._async._expose_http(sandbox_id, params))
+
+    def _expose_ssh(self, sandbox_id: str) -> ExposeSSHResult:
+        return self._bridge.run(self._async._expose_ssh(sandbox_id))
+
 
 __all__ = ["AsyncConsoleClient", "ConsoleClient"]

src/deno_sandbox/errors.py

@@ -19,6 +19,21 @@ class UnknownRpcMethod(Exception):
     pass
 
 
+class ProcessAlreadyExited(Exception):
+    """Raised when trying to interact with a process that has already exited."""
+
+    pass
+
+
+class HTTPStatusError(Exception):
+    """Raised when an HTTP request returns a non-success status code."""
+
+    def __init__(self, status_code: int, message: str) -> None:
+        self.status_code = status_code
+        self.message = message
+        super().__init__(f"HTTP Status {status_code}: {message}")
+
+
 class ZodErrorRaw(TypedDict):
     expected: str
     code: str

src/deno_sandbox/options.py

@@ -14,6 +14,7 @@ class Options(TypedDict):
 
 class InternalOptions(TypedDict):
     sandbox_ws_url: URL
+    sandbox_url: URL
     console_url: URL
     token: str
     regions: list[str]
@@ -45,6 +46,7 @@ def get_internal_options(options: Optional[Options] = None) -> InternalOptions:
     return InternalOptions(
         console_url=console_url,
         sandbox_ws_url=sandbox_ws_url,
+        sandbox_url=sandbox_url,
         token=token,
         regions=regions,
     )

src/deno_sandbox/rpc.py

@@ -1,11 +1,17 @@
 import asyncio
 import base64
 import json
-from typing import Any, Dict, TypedDict, cast
+from typing import Any, Dict, Literal, Optional, TypedDict, cast
 from websockets import ConnectionClosed
 
 from deno_sandbox.bridge import AsyncBridge
-from deno_sandbox.errors import RpcValidationError, UnknownRpcMethod, ZodErrorRaw
+from deno_sandbox.errors import (
+    HTTPStatusError,
+    ProcessAlreadyExited,
+    RpcValidationError,
+    UnknownRpcMethod,
+    ZodErrorRaw,
+)
 from deno_sandbox.transport import WebSocketTransport
 from deno_sandbox.utils import (
     convert_to_camel_case,
@@ -41,6 +47,7 @@ def __init__(self, transport: WebSocketTransport):
         self._listen_task: asyncio.Task[Any] | None = None
         self._pending_processes: Dict[int, asyncio.StreamReader] = {}
         self._loop: asyncio.AbstractEventLoop | None = None
+        self._signal_id = 0
 
     async def close(self):
         await self._transport.close()
@@ -89,7 +96,16 @@ async def call(self, method: str, params: Dict[str, Any]) -> Any:
             raise Exception(response["error"])
 
         if response.get("result") and response["result"].get("error"):
-            raise Exception(f"Application Error: {response['result']['error']}")
+            err = response["result"]["error"]
+            if (
+                "constructor_name" in err
+                and err["constructor_name"] == "TypeError"
+                and "code" in err
+                and err["code"] == "ENOENT"
+            ):
+                raise ProcessAlreadyExited("Process has already exited")
+
+            raise Exception(f"Application Error: {err}")
         return response["result"]["ok"] if response.get("result") else None
 
     async def _listener(self) -> None:
@@ -128,6 +144,34 @@ async def _listener(self) -> None:
                 if not future.done():
                     future.set_exception(e)
 
+    async def fetch(
+        self,
+        url: str,
+        method: Optional[str] = "GET",
+        headers: Optional[dict[str, str]] = None,
+        redirect: Literal["follow", "manual"] = None,
+        pid: Optional[int] = None,
+    ) -> AsyncFetchResponse:
+        self._signal_id += 1
+        signal_id = self._signal_id
+
+        params: FetchParams = {
+            "url": url,
+            "method": method or "GET",
+            "headers": list(headers.items()) if headers else [],
+            "redirect": redirect or "follow",
+            "abortId": signal_id,
+        }
+
+        if pid is not None:
+            params["pid"] = pid
+
+        response_data = await self.call("fetch", params)
+        response = cast(FetchResponseData, response_data)
+
+        fetch_response = AsyncFetchResponse(self, response)
+        return fetch_response
+
 
 class RpcClient:
     def __init__(self, async_client: AsyncRpcClient, bridge: AsyncBridge):
@@ -137,5 +181,154 @@ def __init__(self, async_client: AsyncRpcClient, bridge: AsyncBridge):
     def call(self, method: str, params: Dict[str, Any]) -> Any:
         return self._bridge.run(self._async_client.call(method, params))
 
+    def fetch(
+        self,
+        url: str,
+        method: Optional[str] = "GET",
+        headers: Optional[dict[str, str]] = None,
+        redirect: Literal["follow", "manual"] = None,
+        pid: Optional[int] = None,
+    ) -> FetchResponse:
+        response = self._bridge.run(
+            self._async_client.fetch(url, method, headers, redirect, pid)
+        )
+
+        return FetchResponse(self, response)
+
     def close(self):
         self._bridge.run(self._async_client.close())
+
+
+class FetchParams(TypedDict):
+    method: str
+    url: str
+    headers: list[tuple[str, str]]
+    redirect: str
+    pid: int
+    abortId: int
+
+
+class FetchResponseData(TypedDict):
+    status: int
+    status_text: str
+    headers: list[tuple[str, str]]
+    body_stream_id: int
+
+
+class AsyncFetchResponse:
+    def __init__(self, rpc: AsyncRpcClient, response: FetchResponseData):
+        self._rpc = rpc
+        self._response = response
+
+    def raise_for_status(self) -> HTTPStatusError | None:
+        if self.is_success:
+            return
+
+        message = "{self} resulted in a {error_type} (status code: {self.status})"
+        status_class = self.status // 100
+        error_types = {
+            1: "Informational response",
+            3: "Redirect response",
+            4: "Client error",
+            5: "Server error",
+        }
+        error_type = error_types.get(status_class, "Invalid status code")
+        message = message.format(self, error_type=error_type)
+
+        return HTTPStatusError(self.status, message)
+
+    @property
+    def headers(self) -> list[tuple[str, str]]:
+        return self._response["headers"]
+
+    @property
+    def status_code(self) -> int:
+        return self._response["status"]
+
+    @property
+    def is_informational(self) -> int:
+        return 100 <= self.status_code <= 199
+
+    @property
+    def is_success(self) -> int:
+        return 200 <= self.status_code <= 299
+
+    @property
+    def is_redirect(self) -> int:
+        return 300 <= self.status_code <= 399
+
+    @property
+    def is_client_error(self) -> int:
+        return 400 <= self.status_code <= 499
+
+    @property
+    def is_server_error(self) -> int:
+        return 500 <= self.status_code <= 599
+
+    @property
+    def is_error(self) -> int:
+        return 400 <= self.status_code <= 599
+
+    @property
+    def has_redirect_location(self) -> bool:
+        return (
+            self.status_code in (301, 302, 303, 307, 308)
+            and "location" in self._response["headers"]
+        )
+
+    async def cancel(self) -> None:
+        await self._rpc.call("abort", {"abortId": self._response["abortId"]})
+
+    def __repr__(self) -> str:
+        return f"<Response [{self.status_code}]>"
+
+
+class FetchResponse(AsyncFetchResponse):
+    def __init__(self, rpc: AsyncRpcClient, async_res: AsyncFetchResponse):
+        self._rpc = rpc
+        self._async = async_res
+
+    def raise_for_status(self) -> HTTPStatusError | None:
+        return self._async.raise_for_status()
+
+    @property
+    def headers(self) -> list[tuple[str, str]]:
+        return self._async.headers
+
+    @property
+    def status_code(self) -> int:
+        return self._async.status_code
+
+    @property
+    def is_informational(self) -> int:
+        return self._async.is_informational
+
+    @property
+    def is_success(self) -> int:
+        return self._async.is_success
+
+    @property
+    def is_redirect(self) -> int:
+        return self._async.is_redirect
+
+    @property
+    def is_client_error(self) -> int:
+        return self._async.is_client_error
+
+    @property
+    def is_server_error(self) -> int:
+        return self._async.is_server_error
+
+    @property
+    def is_error(self) -> int:
+        return self._async.is_error
+
+    @property
+    def has_redirect_location(self) -> bool:
+        return self._async.has_redirect_location
+
+    def cancel(self) -> None:
+        self._rpc._bridge.run(self._async.cancel())
+
+    def __repr__(self) -> str:
+        return f"<Response [{self.status_code}]>"