cocoonstack-sandbox 0.1.0__tar.gz → 0.1.2__tar.gz

cocoonstack_sandbox-0.1.2/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

{cocoonstack_sandbox-0.1.0 → cocoonstack_sandbox-0.1.2}/PKG-INFO

@@ -1,10 +1,12 @@
 Metadata-Version: 2.4
 Name: cocoonstack-sandbox
-Version: 0.1.0
+Version: 0.1.2
 Summary: Python SDK for the cocoon sandbox control plane
 License: Apache-2.0
 Requires-Python: >=3.9
 Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
 
 # cocoonstack-sandbox
 
@@ -25,8 +27,9 @@ with client.new("ghcr.io/cocoonstack/sandbox/rt:24.04") as sb:
 stdlib-only and synchronous — `pip install cocoonstack-sandbox` brings no
 dependencies. The surface mirrors the Go SDK: exec/run, streaming files,
 tar push/pull, find/replace, watch, persistent sessions, git verbs, pty,
-port dial/proxy/preview URLs, fork, hibernate, promote, checkpoints, and
-the LSP broker. Wire fidelity is pinned by the shared protocol fixture
-corpus (Rust + Go + Python all round-trip it in CI).
+port dial/proxy/preview URLs, background processes (spawn/ps/kill/
+logs/attach), fork, hibernate, promote, checkpoints, and the LSP broker.
+Wire fidelity is pinned by the shared protocol fixture corpus (Rust + Go +
+Python all round-trip it in CI).
 
 Full reference: https://cocoonstack.github.io/sandbox/sdk-python

{cocoonstack_sandbox-0.1.0 → cocoonstack_sandbox-0.1.2}/README.md

@@ -17,8 +17,9 @@ with client.new("ghcr.io/cocoonstack/sandbox/rt:24.04") as sb:
 stdlib-only and synchronous — `pip install cocoonstack-sandbox` brings no
 dependencies. The surface mirrors the Go SDK: exec/run, streaming files,
 tar push/pull, find/replace, watch, persistent sessions, git verbs, pty,
-port dial/proxy/preview URLs, fork, hibernate, promote, checkpoints, and
-the LSP broker. Wire fidelity is pinned by the shared protocol fixture
-corpus (Rust + Go + Python all round-trip it in CI).
+port dial/proxy/preview URLs, background processes (spawn/ps/kill/
+logs/attach), fork, hibernate, promote, checkpoints, and the LSP broker.
+Wire fidelity is pinned by the shared protocol fixture corpus (Rust + Go +
+Python all round-trip it in CI).
 
 Full reference: https://cocoonstack.github.io/sandbox/sdk-python

{cocoonstack_sandbox-0.1.0 → cocoonstack_sandbox-0.1.2}/cocoonsandbox/checkpoint.py

@@ -4,6 +4,11 @@ keeps running and can be checkpointed again, so captures form a tree."""
 
 from __future__ import annotations
 
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .sandbox import Sandbox
+
 
 class Checkpoint:
     """A captured sandbox state on its owner node."""
@@ -16,7 +21,7 @@ class Checkpoint:
         self.sandbox_id = rec.get("sandbox_id", "")
         self.created_at = rec.get("created_at", "")
 
-    def new(self, ttl_seconds: int = 0):
+    def new(self, ttl_seconds: int = 0) -> Sandbox:
         """Claims a fresh sandbox branched from the checkpoint."""
         body = {"ttl_seconds": ttl_seconds} if ttl_seconds else {}
         reply = self._client._post_json(self._addr, f"/v1/checkpoints/{self.id}/claim", body, "claim checkpoint")
@@ -25,4 +30,3 @@ class Checkpoint:
     def delete(self) -> None:
         """Removes the checkpoint from its node."""
         self._client._request(self._addr, "DELETE", f"/v1/checkpoints/{self.id}", None, "delete checkpoint")
-

cocoonstack_sandbox-0.1.2/cocoonsandbox/client.py

@@ -0,0 +1,215 @@
+"""Client: the control-plane entry point. Dial any node of a cluster; a
+claim either lands locally or follows one MOVED-style redirect to the node
+that has capacity, and the returned Sandbox is bound to its owner."""
+
+from __future__ import annotations
+
+import http.client
+import json
+import queue
+import threading
+import urllib.error
+import urllib.parse
+import urllib.request
+
+from .checkpoint import Checkpoint
+from .errors import APIError
+from .sandbox import Sandbox
+
+_PEERS_TIMEOUT = 5.0
+
+
+class Client:
+    """Talks to one sandboxd node (and, transparently, its cluster)."""
+
+    def __init__(self, addr: str, api_token: str = "", timeout: float = 120.0):
+        self.addr = addr.split(",")[0].strip()
+        self.api_token = api_token
+        self.timeout = timeout
+
+    def new(self, template: str, net: str = "", size: str = "", ttl_seconds: int = 0) -> Sandbox:
+        """Claims a sandbox; a warm hit is milliseconds. On a cluster a warm
+        miss may redirect to a peer, followed transparently."""
+        claim = _claim_body(template, net, size, ttl_seconds)
+        reply = self._post_json(self.addr, "/v1/claim", claim, "claim")
+        redirect = reply.get("redirect") or []
+        if redirect:
+            # Retry at a peer with no_redirect set: it warm-or-provisions and
+            # cannot bounce us again.
+            claim["no_redirect"] = True
+            # A candidate that is full (429) or erroring must not abort the
+            # follow — try every one until a node answers, matching the Go SDK.
+            return _try_each(redirect, lambda peer: self._handle_from(
+                peer, self._post_json(peer, "/v1/claim", claim, "claim")),
+                retry=lambda _: True)
+        return self._handle_from(self.addr, reply)
+
+    def delete_template(self, template: str, net: str = "", size: str = "") -> None:
+        """Removes a promoted template by name; on a cluster the delete
+        follows gossip to the owner node (one hop)."""
+        query = _template_query(template, net, size)
+        path = "/v1/templates?" + urllib.parse.urlencode(query)
+        reply = self._request(self.addr, "DELETE", path, None, "delete template")
+        candidates = (reply or {}).get("redirect") or []
+        if not candidates:
+            return
+        # The retry carries no_redirect, mirroring the claim protocol: the
+        # owner answers for itself, never a second hop.
+        query["no_redirect"] = "1"
+        path = "/v1/templates?" + urllib.parse.urlencode(query)
+        _try_each(candidates, lambda peer: self._request(peer, "DELETE", path, None, "delete template"))
+
+    def lookup(self, id: str, token: str) -> Sandbox:
+        """Relocates a handle from id + token: asks the entry node and every
+        mesh peer concurrently, binding to whichever confirms ownership
+        first — one dead peer must not cost its full timeout."""
+        def probe(addr: str) -> Sandbox:
+            reply = self._request(addr, "GET", f"/v1/sandboxes/{id}/owner", None, "owner", bearer=token)
+            return Sandbox(client=self, id=id, token=token,
+                           owner=reply.get("owner_addr") or addr)
+
+        addrs = [self.addr, *self._peers()]
+        try:
+            return _scatter(addrs, probe)
+        except APIError:
+            raise APIError("lookup", 404, f"no owner found for {id}") from None
+
+    def checkpoint(self, id: str) -> Checkpoint:
+        """A handle for a known checkpoint id, bound to the entry node — no
+        listing round-trip; an unknown id surfaces as 404 at claim time."""
+        return Checkpoint(self, self.addr, {"id": id})
+
+    def checkpoints(self) -> list[Checkpoint]:
+        """Lists the connected node's checkpoints, newest first."""
+        reply = self._request(self.addr, "GET", "/v1/checkpoints", None, "list checkpoints")
+        return [Checkpoint(self, self.addr, rec) for rec in reply.get("checkpoints") or []]
+
+    def info(self) -> dict:
+        """The node's pool/claim counters, as served by GET /v1/info."""
+        return self._request(self.addr, "GET", "/v1/info", None, "info")
+
+    def _peers(self) -> list:
+        # /v1/peers is tenant-accessible (cluster topology); /v1/info is
+        # operator-only, so a tenant lookup cannot read peers from it. A
+        # single node has none — degrade to just the entry node. Bounded
+        # tighter than the client default (mirrors the Go SDK's peersTimeout)
+        # so one slow entry node cannot stall the scatter it feeds.
+        try:
+            return self._request(self.addr, "GET", "/v1/peers", None, "peers",
+                                 timeout=min(_PEERS_TIMEOUT, self.timeout)).get("peers") or []
+        except APIError:
+            return []
+
+    def _handle_from(self, dialed: str, reply: dict) -> Sandbox:
+        return Sandbox(
+            client=self,
+            id=reply["id"],
+            token=reply["token"],
+            owner=reply.get("owner_addr") or dialed,
+            deadline=reply.get("deadline", ""),
+            from_checkpoint=reply.get("from_checkpoint", ""),
+        )
+
+    def _post_json(self, addr: str, path: str, body: dict, verb: str) -> dict:
+        return self._request(addr, "POST", path, body, verb)
+
+    def _request(self, addr: str, method: str, path: str, body, verb: str, bearer: str = "",
+                 timeout: float = 0.0) -> dict:
+        """Issues one control-plane request. bearer overrides the api token —
+        sandbox-scoped verbs (release, hibernate) authenticate with the
+        per-sandbox token instead; timeout overrides the client default (0 keeps it)."""
+        data = json.dumps(body).encode() if body is not None else None
+        req = urllib.request.Request(f"http://{addr}{path}", data=data, method=method)
+        if data is not None:
+            req.add_header("Content-Type", "application/json")
+        token = bearer or self.api_token
+        if token:
+            req.add_header("Authorization", f"Bearer {token}")
+        try:
+            with urllib.request.urlopen(req, timeout=timeout or self.timeout) as resp:
+                raw = resp.read()
+        except urllib.error.HTTPError as exc:
+            try:
+                detail = _error_message(exc.read())
+            except (OSError, http.client.HTTPException) as read_exc:
+                detail = str(read_exc)
+            raise APIError(verb, exc.code, detail) from None
+        except urllib.error.URLError as exc:
+            raise APIError(verb, 0, str(exc.reason)) from None
+        except (OSError, http.client.HTTPException) as exc:
+            # A reset or truncated body read is neither HTTPError nor URLError.
+            raise APIError(verb, 0, str(exc)) from None
+        if not raw:
+            return {}
+        try:
+            return json.loads(raw)
+        except json.JSONDecodeError as exc:
+            raise APIError(verb, 0, "malformed JSON in response") from exc
+
+
+def _claim_body(template: str, net: str, size: str, ttl_seconds: int) -> dict:
+    claim = {"template": template}
+    if net:
+        claim["net"] = net
+    if size:
+        claim["size"] = size
+    if ttl_seconds:
+        claim["ttl_seconds"] = ttl_seconds
+    return claim
+
+
+def _template_query(template: str, net: str, size: str) -> dict:
+    query = {"template": template}
+    if net:
+        query["net"] = net
+    if size:
+        query["size"] = size
+    return query
+
+
+def _error_message(raw: bytes) -> str:
+    try:
+        return json.loads(raw)["error"]
+    except (ValueError, KeyError, TypeError):
+        return raw.decode(errors="replace").strip()
+
+
+def _try_each(candidates, call, retry=lambda exc: exc.status in (404, 0)):
+    """Calls call against each candidate in turn, returning the first
+    success. An APIError for which retry(exc) is true moves on to the next
+    candidate and the last such error propagates; any other raises at once.
+    The default retries only a miss (404 or a dead peer, status 0);
+    candidates must be non-empty."""
+    last_error = None
+    for addr in candidates:
+        try:
+            return call(addr)
+        except APIError as exc:
+            if not retry(exc):
+                raise
+            last_error = exc
+    raise last_error
+
+
+def _scatter(addrs, probe):
+    """Probes every addr concurrently and returns the first success; when
+    all probes fail the last error propagates. Loser threads are daemons
+    whose requests die with _request's own timeout; the queue is bounded by
+    len(addrs) so they never block. addrs must be non-empty."""
+    results = queue.Queue(maxsize=len(addrs))
+
+    def run(addr):
+        try:
+            results.put((probe(addr), None))
+        except Exception as exc:  # any escape would hang the drain below
+            results.put((None, exc))
+
+    for addr in addrs:
+        threading.Thread(target=run, args=(addr,), daemon=True).start()
+    last_error = None
+    for _ in addrs:
+        value, error = results.get()
+        if error is None:
+            return value
+        last_error = error
+    raise last_error

{cocoonstack_sandbox-0.1.0 → cocoonstack_sandbox-0.1.2}/cocoonsandbox/conn.py

@@ -5,6 +5,7 @@ from __future__ import annotations
 
 import contextlib
 import socket
+from collections.abc import Iterator
 
 from .errors import APIError, ProtocolError, SilkdError
 from .frames import MAX_FRAME, decode_response, encode_request
@@ -17,10 +18,10 @@ class Conn:
         self._sock = sock
         self._reader = reader
 
-    def __enter__(self):
+    def __enter__(self) -> Conn:
         return self
 
-    def __exit__(self, *exc):
+    def __exit__(self, *exc) -> None:
         self.close()
 
     def send(self, op: str, **fields) -> None:
@@ -39,7 +40,7 @@ class Conn:
             raise SilkdError(frame.get("kind", "internal"), frame.get("message", ""))
         return frame
 
-    def recv_until(self, *terminal: str):
+    def recv_until(self, *terminal: str) -> Iterator[dict]:
         """Yields frames until one of the terminal types arrives; the
         terminal frame is yielded last."""
         while True:
@@ -58,11 +59,17 @@ class Conn:
         finally:
             self._sock.close()
 
+
 def dial_agent(addr: str, sandbox_id: str, token: str, timeout: float) -> Conn:
     """Opens the data-plane connection: TCP dial plus a hand-rolled HTTP
     Upgrade, so nothing pools or proxies underneath the byte stream."""
+    # id/token interpolate into the raw request line; CR/LF would inject headers.
+    for name, value in (("sandbox id", sandbox_id), ("token", token)):
+        if any(c in value for c in "\r\n\0"):
+            raise APIError("agent upgrade", 0, f"{name} contains a control character")
     host, port = addr.rsplit(":", 1)
     sock = socket.create_connection((host, int(port)), timeout=timeout)
+    reader = None
     try:
         request = (
             f"GET /v1/sandboxes/{sandbox_id}/agent HTTP/1.1\r\n"
@@ -84,11 +91,20 @@ def dial_agent(addr: str, sandbox_id: str, token: str, timeout: float) -> Conn:
                 break
             name, _, value = header.decode(errors="replace").partition(":")
             if name.strip().lower() == "content-length":
-                body_len = int(value.strip())
+                try:
+                    body_len = int(value.strip())
+                    if body_len < 0:
+                        raise ValueError("negative content-length")
+                except ValueError as exc:
+                    raise ProtocolError("invalid content-length in upgrade reply") from exc
         if code != 101:
-            body = reader.read(body_len).decode(errors="replace") if body_len else ""
+            # A bogus content-length must not buffer unbounded bytes.
+            body = reader.read(min(body_len, MAX_FRAME)).decode(errors="replace") if body_len else ""
             raise APIError("agent upgrade", code, body.strip() or status.strip())
         return Conn(sock, reader)
     except Exception:
+        # makefile() holds a ref on the socket; close it too or the fd lingers.
+        if reader is not None:
+            reader.close()
         sock.close()
         raise

{cocoonstack_sandbox-0.1.0 → cocoonstack_sandbox-0.1.2}/cocoonsandbox/frames.py

@@ -1,10 +1,11 @@
 """silkd wire frames: newline-delimited JSON, requests tagged by "op",
 responses by "type", binary payloads base64 in "data" fields. Mirrors the Go
-and Rust implementations; all three round-trip protocol/fixtures/v1."""
+and Rust implementations; all three round-trip protocol/wire/fixtures/v1."""
 
 from __future__ import annotations
 
 import base64
+import binascii
 import json
 
 PROTO_VERSION = 1
@@ -31,6 +32,21 @@ def encode_request(op: str, **fields) -> bytes:
 def decode_response(line: bytes) -> dict:
     """Parses one response frame; the returned dict carries its tag under
     "type" and any binary payload decoded under "data"."""
+    # Bulk frames (stdout/stderr/data) are the throughput path where json.loads
+    # of the big base64 string dominates. base64 is JSON-escape-free and these
+    # frames carry exactly {"type":...,"data":...}, so slice both out and skip
+    # json — but only for that exact shape; anything else (extra fields,
+    # trailing bytes, non-alphabet bytes in the segment) gets the full parse
+    # instead of a silently wrong slice.
+    if line.startswith(b'{"type":"'):
+        te = line.find(b'"', 9)
+        if te > 0 and line[9:te] in (b"stdout", b"stderr", b"data") and line.startswith(b'","data":"', te):
+            de = line.find(b'"', te + 10)
+            if de > 0 and line[de:] in (b'"}', b'"}\n'):
+                try:
+                    return {"type": line[9:te].decode(), "data": base64.b64decode(line[te + 10 : de], validate=True)}
+                except binascii.Error:
+                    pass
     frame = json.loads(line)
     if not isinstance(frame, dict) or "type" not in frame:
         raise ValueError(f"frame without a type tag: {line[:80]!r}")