cocoonstack-sandbox 0.1.0__tar.gz

cocoonstack_sandbox-0.1.0/PKG-INFO

@@ -0,0 +1,32 @@
+Metadata-Version: 2.4
+Name: cocoonstack-sandbox
+Version: 0.1.0
+Summary: Python SDK for the cocoon sandbox control plane
+License: Apache-2.0
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# cocoonstack-sandbox
+
+Python SDK for the cocoon sandbox control plane: microVM sandboxes with
+warm-pool claims, checkpoint branching, transparent hibernate/wake, and a
+relay-only data plane that works on no-network guests.
+
+```python
+from cocoonsandbox import Client
+
+client = Client("10.0.0.5:7777", api_token="...")
+with client.new("ghcr.io/cocoonstack/sandbox/rt:24.04") as sb:
+    print(sb.exec("echo", "hello"))
+    ckpt = sb.checkpoint("after-setup")
+    branch = ckpt.new()          # a fresh sandbox at the captured moment
+```
+
+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).
+
+Full reference: https://cocoonstack.github.io/sandbox/sdk-python

cocoonstack_sandbox-0.1.0/README.md

@@ -0,0 +1,24 @@
+# cocoonstack-sandbox
+
+Python SDK for the cocoon sandbox control plane: microVM sandboxes with
+warm-pool claims, checkpoint branching, transparent hibernate/wake, and a
+relay-only data plane that works on no-network guests.
+
+```python
+from cocoonsandbox import Client
+
+client = Client("10.0.0.5:7777", api_token="...")
+with client.new("ghcr.io/cocoonstack/sandbox/rt:24.04") as sb:
+    print(sb.exec("echo", "hello"))
+    ckpt = sb.checkpoint("after-setup")
+    branch = ckpt.new()          # a fresh sandbox at the captured moment
+```
+
+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).
+
+Full reference: https://cocoonstack.github.io/sandbox/sdk-python

cocoonstack_sandbox-0.1.0/cocoonsandbox/__init__.py

@@ -0,0 +1,33 @@
+"""Python SDK for the cocoon sandbox control plane: claim a microVM from a
+sandboxd node, run commands over the relayed silkd protocol, branch it with
+checkpoints, release it. stdlib-only.
+
+    from cocoonsandbox import Client
+
+    client = Client("node:7777", api_token="...")
+    with client.new("ghcr.io/cocoonstack/sandbox/rt:24.04") as sb:
+        print(sb.exec("echo", "hello"))
+"""
+
+from .checkpoint import Checkpoint
+from .client import Client
+from .errors import APIError, ExitError, ProtocolError, SandboxError, SilkdError
+from .sandbox import Lsp, PortConn, Pty, Sandbox, Session, Watcher
+from .template import Template
+
+__all__ = [
+    "APIError",
+    "Checkpoint",
+    "Client",
+    "ExitError",
+    "Lsp",
+    "PortConn",
+    "ProtocolError",
+    "Pty",
+    "Sandbox",
+    "SandboxError",
+    "Session",
+    "SilkdError",
+    "Template",
+    "Watcher",
+]

cocoonstack_sandbox-0.1.0/cocoonsandbox/checkpoint.py

@@ -0,0 +1,28 @@
+"""Checkpoint: a captured sandbox state bound to the node that holds it.
+Branch any number of fresh sandboxes from the captured moment; the source
+keeps running and can be checkpointed again, so captures form a tree."""
+
+from __future__ import annotations
+
+
+class Checkpoint:
+    """A captured sandbox state on its owner node."""
+
+    def __init__(self, client, addr: str, rec: dict):
+        self._client = client
+        self._addr = addr
+        self.id = rec["id"]
+        self.name = rec.get("name", "")
+        self.sandbox_id = rec.get("sandbox_id", "")
+        self.created_at = rec.get("created_at", "")
+
+    def new(self, ttl_seconds: int = 0):
+        """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")
+        return self._client._handle_from(self._addr, reply)
+
+    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.0/cocoonsandbox/client.py

@@ -0,0 +1,141 @@
+"""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 json
+import urllib.error
+import urllib.parse
+import urllib.request
+
+from .checkpoint import Checkpoint
+from .errors import APIError
+from .sandbox import Sandbox
+
+
+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:
+            claim["no_redirect"] = True
+            last_error = None
+            for peer in redirect:
+                try:
+                    return self._handle_from(peer, self._post_json(peer, "/v1/claim", claim, "claim"))
+                except APIError as exc:
+                    last_error = exc
+            raise last_error
+        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": template}
+        if net:
+            query["net"] = net
+        if size:
+            query["size"] = size
+        path = "/v1/templates?" + urllib.parse.urlencode(query)
+        reply = self._request(self.addr, "DELETE", path, None, "delete template")
+        candidates = (reply or {}).get("redirect") or []
+        query["no_redirect"] = "1"
+        path = "/v1/templates?" + urllib.parse.urlencode(query)
+        # Each candidate once, like the Go SDK: a peer that lost the template
+        # answers 404, the next may own it; the last 404 propagates.
+        for i, peer in enumerate(candidates):
+            try:
+                self._request(peer, "DELETE", path, None, "delete template")
+                return
+            except APIError as exc:
+                if exc.status != 404 or i == len(candidates) - 1:
+                    raise
+
+    def lookup(self, id: str, token: str) -> Sandbox:
+        """Relocates a handle from id + token: asks the entry node, then
+        each mesh peer, and binds to whichever confirms ownership."""
+        for addr in [self.addr, *(self.info().get("peers") or [])]:
+            try:
+                reply = self._request(addr, "GET", f"/v1/sandboxes/{id}/owner", None, "owner", bearer=token)
+            except APIError:
+                continue
+            return Sandbox(client=self, id=id, token=token,
+                           owner=reply.get("owner_addr") or addr)
+        raise APIError("lookup", 404, f"no owner found for {id}")
+
+    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 _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 = "") -> dict:
+        """Issues one control-plane request. bearer overrides the api token —
+        sandbox-scoped verbs (release, hibernate) authenticate with the
+        per-sandbox token instead."""
+        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=self.timeout) as resp:
+                raw = resp.read()
+        except urllib.error.HTTPError as exc:
+            raise APIError(verb, exc.code, _error_message(exc.read())) from None
+        except urllib.error.URLError as exc:
+            raise APIError(verb, 0, str(exc.reason)) from None
+        return json.loads(raw) if raw else {}
+
+
+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 _error_message(raw: bytes) -> str:
+    try:
+        return json.loads(raw)["error"]
+    except (ValueError, KeyError, TypeError):
+        return raw.decode(errors="replace").strip()
+

cocoonstack_sandbox-0.1.0/cocoonsandbox/conn.py

@@ -0,0 +1,94 @@
+"""One relayed silkd connection per RPC: a raw TCP socket hand-upgraded to
+the sandboxd agent relay (Upgrade: silkd), then newline-JSON frames."""
+
+from __future__ import annotations
+
+import contextlib
+import socket
+
+from .errors import APIError, ProtocolError, SilkdError
+from .frames import MAX_FRAME, decode_response, encode_request
+
+
+class Conn:
+    """A live frame stream to one sandbox's silkd, via the owner node."""
+
+    def __init__(self, sock: socket.socket, reader):
+        self._sock = sock
+        self._reader = reader
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *exc):
+        self.close()
+
+    def send(self, op: str, **fields) -> None:
+        self._sock.sendall(encode_request(op, **fields))
+
+    def recv(self) -> dict:
+        """Returns the next frame; raises SilkdError on an error frame and
+        ProtocolError on EOF or an oversized line."""
+        line = self._reader.readline(MAX_FRAME + 1)
+        if not line:
+            raise ProtocolError("connection closed mid-stream")
+        if len(line) > MAX_FRAME:
+            raise ProtocolError("frame exceeds the 8MiB cap")
+        frame = decode_response(line)
+        if frame["type"] == "error":
+            raise SilkdError(frame.get("kind", "internal"), frame.get("message", ""))
+        return frame
+
+    def recv_until(self, *terminal: str):
+        """Yields frames until one of the terminal types arrives; the
+        terminal frame is yielded last."""
+        while True:
+            frame = self.recv()
+            yield frame
+            if frame["type"] in terminal:
+                return
+
+    def close_write(self) -> None:
+        with contextlib.suppress(OSError):
+            self._sock.shutdown(socket.SHUT_WR)
+
+    def close(self) -> None:
+        try:
+            self._reader.close()
+        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."""
+    host, port = addr.rsplit(":", 1)
+    sock = socket.create_connection((host, int(port)), timeout=timeout)
+    try:
+        request = (
+            f"GET /v1/sandboxes/{sandbox_id}/agent HTTP/1.1\r\n"
+            f"Host: {addr}\r\n"
+            "Connection: Upgrade\r\n"
+            "Upgrade: silkd\r\n"
+            f"Authorization: Bearer {token}\r\n"
+            "\r\n"
+        )
+        sock.sendall(request.encode())
+        reader = sock.makefile("rb")
+        status = reader.readline(1024).decode(errors="replace")
+        parts = status.split(" ", 2)
+        code = int(parts[1]) if len(parts) > 1 and parts[1].isdigit() else 0
+        body_len = 0
+        while True:
+            header = reader.readline(4096)
+            if header in (b"\r\n", b"\n", b""):
+                break
+            name, _, value = header.decode(errors="replace").partition(":")
+            if name.strip().lower() == "content-length":
+                body_len = int(value.strip())
+        if code != 101:
+            body = reader.read(body_len).decode(errors="replace") if body_len else ""
+            raise APIError("agent upgrade", code, body.strip() or status.strip())
+        return Conn(sock, reader)
+    except Exception:
+        sock.close()
+        raise

cocoonstack_sandbox-0.1.0/cocoonsandbox/errors.py

@@ -0,0 +1,41 @@
+"""Error types raised by the SDK."""
+
+
+class SandboxError(Exception):
+    """Base class for all SDK errors."""
+
+
+class APIError(SandboxError):
+    """A sandboxd control-plane call failed."""
+
+    def __init__(self, verb: str, status: int, message: str):
+        super().__init__(f"{verb}: {message} (HTTP {status})")
+        self.verb = verb
+        self.status = status
+        self.message = message
+
+
+class SilkdError(SandboxError):
+    """The in-guest daemon answered an error frame.
+
+    kind is the typed wire kind: bad_request, not_found, unimplemented,
+    internal.
+    """
+
+    def __init__(self, kind: str, message: str):
+        super().__init__(f"{kind}: {message}")
+        self.kind = kind
+        self.message = message
+
+
+class ExitError(SandboxError):
+    """A command exited non-zero; carries the exit code and stderr."""
+
+    def __init__(self, code: int, stderr: str):
+        super().__init__(f"exit status {code}: {stderr.strip()}")
+        self.code = code
+        self.stderr = stderr
+
+
+class ProtocolError(SandboxError):
+    """The peer broke the frame protocol (unexpected frame, oversized line)."""

cocoonstack_sandbox-0.1.0/cocoonsandbox/frames.py

@@ -0,0 +1,39 @@
+"""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."""
+
+from __future__ import annotations
+
+import base64
+import json
+
+PROTO_VERSION = 1
+MAX_FRAME = 8 * 1024 * 1024
+FS_CHUNK = 32 * 1024
+# Bulk streams (push tars, port bytes) chunk larger — fewer frames for the
+# same bytes, still far under MAX_FRAME after base64; mirrors the Go SDK.
+BULK_CHUNK = 1 << 20
+
+
+def encode_request(op: str, **fields) -> bytes:
+    """Renders {"v":1,"op":...,fields} with a trailing newline; None fields
+    are omitted and bytes values ride base64 under their field name."""
+    frame = {"v": PROTO_VERSION, "op": op}
+    for key, value in fields.items():
+        if value is None:
+            continue
+        if isinstance(value, (bytes, bytearray, memoryview)):
+            value = base64.b64encode(value).decode()
+        frame[key] = value
+    return json.dumps(frame, separators=(",", ":")).encode() + b"\n"
+
+
+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"."""
+    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}")
+    if isinstance(frame.get("data"), str):
+        frame["data"] = base64.b64decode(frame["data"])
+    return frame