feat: add debug option that prints trace id + close reason (#40)

Author: marvinhagemeister

src/deno_sandbox/rpc.py

@@ -51,6 +51,7 @@ def __init__(self, transport: WebSocketTransport):
         self.__loop: asyncio.AbstractEventLoop | None = None
         self._signal_id = 0
         self._stream_id = 0
+        self._debug = transport._debug
 
     @property
     def _loop(self) -> asyncio.AbstractEventLoop:

src/deno_sandbox/sandbox.py

@@ -184,7 +184,7 @@ async def create(
         url = self._client._options["sandbox_ws_url"].join("/api/v3/sandboxes/create")
         token = self._client._options["token"]
 
-        transport = WebSocketTransport()
+        transport = WebSocketTransport(debug=debug if debug is not None else False)
         ws = await transport.connect(
             url=url,
             headers={
@@ -204,10 +204,18 @@ async def create(
         if sandbox_id is None:
             raise Exception("Sandbox ID not found in response headers")
 
+        if debug:
+            print(f"Trace ID: {response.headers.get('x-deno-trace-id', 'n/a')}")
+
         sandbox = None
         try:
             rpc = AsyncRpcClient(transport)
-            sandbox = AsyncSandbox(self._client, rpc, sandbox_id)
+            sandbox = AsyncSandbox(
+                self._client,
+                rpc,
+                sandbox_id,
+                trace_id=response.headers.get("x-deno-trace-id"),
+            )
             yield sandbox
         finally:
             if sandbox is not None:
@@ -217,17 +225,20 @@ async def create(
     async def connect(
         self,
         sandbox_id: str,
+        *,
+        debug: Optional[bool] = None,
     ) -> AsyncIterator[AsyncSandbox]:
         """Connects to an existing sandbox instance.
 
         Args:
             sandbox_id: The unique id of the sandbox to connect to.
+            debug: Enable debug logging for the sandbox connection.
         """
         url = self._client._options["sandbox_ws_url"].join(
             f"/api/v3/sandbox/{sandbox_id}/connect"
         )
         token = self._client._options["token"]
-        transport = WebSocketTransport()
+        transport = WebSocketTransport(debug=debug if debug is not None else False)
         await transport.connect(
             url=url,
             headers={
@@ -331,16 +342,16 @@ def create(
     def connect(
         self,
         sandbox_id: str,
+        *,
+        debug: Optional[bool] = None,
     ):
         """Connects to an existing sandbox instance.
 
         Args:
             sandbox_id: The unique id of the sandbox to connect to.
-            region: If the sandbox was created in a non-default region, the region where the sandbox is running.
             debug: Enable debug logging for the sandbox connection.
-            ssh: Whether to expose SSH access to the sandbox.
         """
-        async_cm = self._async.connect(sandbox_id)
+        async_cm = self._async.connect(sandbox_id, debug=debug)
         async_handle = self._bridge.run(async_cm.__aenter__())
 
         try:
@@ -885,7 +896,11 @@ def deploy(
 
 class AsyncSandbox:
     def __init__(
-        self, client: AsyncConsoleClient, rpc: AsyncRpcClient, sandbox_id: str
+        self,
+        client: AsyncConsoleClient,
+        rpc: AsyncRpcClient,
+        sandbox_id: str,
+        trace_id: str | None = None,
     ):
         self._client = client
         self._rpc = rpc
@@ -894,6 +909,7 @@ def __init__(
         self.url: str | None = None
         self.ssh: None = None
         self.id = sandbox_id
+        self.trace_id: str | None = trace_id
         self.fs = AsyncSandboxFs(rpc)
         self.deno = AsyncSandboxDeno(rpc, self._processes, client, sandbox_id)
         self.env = AsyncSandboxEnv(rpc)
@@ -1088,6 +1104,7 @@ def __init__(
         self.url: str | None = None
         self.ssh: None = None
         self.id = async_sandbox.id
+        self.trace_id: str | None = async_sandbox.trace_id
         self.fs = SandboxFs(rpc, bridge)
         self.deno = SandboxDeno(
             rpc, bridge, self._async._processes, client, async_sandbox.id

src/deno_sandbox/transport.py

@@ -6,10 +6,56 @@
 from .errors import AuthenticationError
 
 
+# WebSocket close status codes
+class WebSocketStatus:
+    NORMAL_CLOSURE = 1000
+    GOING_AWAY = 1001
+    PROTOCOL_ERROR = 1002
+    UNSUPPORTED_DATA = 1003
+    NO_STATUS_RECEIVED = 1005
+    ABNORMAL_CLOSURE = 1006
+    INVALID_FRAME_PAYLOAD_DATA = 1007
+    POLICY_VIOLATION = 1008
+    MESSAGE_TOO_BIG = 1009
+    MANDATORY_EXT = 1010
+    INTERNAL_SERVER_ERROR = 1011
+    INVALID_JSON = 4000
+    INVALID_JSON_RPC = 4001
+
+
+def get_close_code_description(code: int) -> str:
+    """Returns a human-readable description for a WebSocket close code."""
+    descriptions = {
+        WebSocketStatus.NORMAL_CLOSURE: "Normal closure (1000)",
+        WebSocketStatus.GOING_AWAY: "Server going away (1001)",
+        WebSocketStatus.PROTOCOL_ERROR: "Protocol error (1002)",
+        WebSocketStatus.UNSUPPORTED_DATA: "Unsupported data (1003)",
+        WebSocketStatus.NO_STATUS_RECEIVED: "No status received (1005)",
+        WebSocketStatus.ABNORMAL_CLOSURE: "Abnormal closure (1006)",
+        WebSocketStatus.INVALID_FRAME_PAYLOAD_DATA: "Invalid frame payload data (1007)",
+        WebSocketStatus.POLICY_VIOLATION: "Policy violation (1008)",
+        WebSocketStatus.MESSAGE_TOO_BIG: "Message too big (1009)",
+        WebSocketStatus.MANDATORY_EXT: "Mandatory extension (1010)",
+        WebSocketStatus.INTERNAL_SERVER_ERROR: "Internal server error (1011)",
+        WebSocketStatus.INVALID_JSON: "Invalid JSON (4000)",
+        WebSocketStatus.INVALID_JSON_RPC: "Invalid JSON-RPC (4001)",
+    }
+
+    if code in descriptions:
+        return descriptions[code]
+    elif 3000 <= code < 4000:
+        return f"Library/framework code ({code})"
+    elif 4000 <= code < 5000:
+        return f"Application code ({code})"
+    else:
+        return f"Unknown code ({code})"
+
+
 class WebSocketTransport:
-    def __init__(self) -> None:
+    def __init__(self, debug: bool = False) -> None:
         self._ws: ClientConnection | None = None
         self._closed = False
+        self._debug = debug
 
     @property
     def closed(self) -> bool:
@@ -49,5 +95,22 @@ async def __aiter__(self):
         try:
             async for message in self._ws:
                 yield message
-        except ConnectionClosed:
+        except ConnectionClosed as e:
+            if self._debug:
+                # Extract close code and reason from the received close frame
+                code = e.rcvd.code if e.rcvd else WebSocketStatus.NO_STATUS_RECEIVED
+                reason = e.rcvd.reason if e.rcvd else ""
+
+                if code in (
+                    WebSocketStatus.NORMAL_CLOSURE,
+                    WebSocketStatus.GOING_AWAY,
+                    WebSocketStatus.NO_STATUS_RECEIVED,
+                ):
+                    # Expected closure (including sandbox timeout)
+                    print(f"Sandbox connection closed: {reason or 'server going away'}")
+                else:
+                    # Unexpected closure
+                    code_description = get_close_code_description(code)
+                    reason_str = f" ({reason})" if reason else ""
+                    print(f"WebSocket closed: {code_description}{reason_str}")
             return

tests/conftest.py

@@ -7,13 +7,28 @@
 async def async_shared_sandbox():
     sdk = AsyncDenoDeploy()
 
-    async with sdk.sandbox.create() as sandbox:
+    async with sdk.sandbox.create(debug=True) as sandbox:
         yield sandbox
 
 
 @pytest.fixture(scope="session")
 def shared_sandbox():
     sdk = DenoDeploy()
 
-    with sdk.sandbox.create() as sandbox:
+    with sdk.sandbox.create(debug=True) as sandbox:
         yield sandbox
+
+
+@pytest.hookimpl(tryfirst=True, hookwrapper=True)
+def pytest_runtest_makereport(item, call):  # noqa: ARG001
+    outcome = yield
+    report = outcome.get_result()
+
+    if report.when == "call" and report.failed:
+        # Check for sandbox fixtures
+        for name in ("async_shared_sandbox", "shared_sandbox"):
+            if name in item.funcargs:
+                sandbox = item.funcargs[name]
+                if hasattr(sandbox, "trace_id") and sandbox.trace_id:
+                    print(f"\nTrace ID: {sandbox.trace_id}")
+                break