cocoonstack-sandbox 0.1.0__py3-none-any.whl

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",
+]

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")
+

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()
+

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

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)."""

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

cocoonsandbox/sandbox.py

@@ -0,0 +1,499 @@
+"""Sandbox: the data-plane handle. Every RPC opens one relayed silkd
+connection via the owner node; sessions and processes are server-side state,
+so nothing is lost between calls — including across a transparent hibernate
+wake."""
+
+from __future__ import annotations
+
+import contextlib
+import socket
+import threading
+
+from .checkpoint import Checkpoint
+from .conn import Conn, dial_agent
+from .errors import APIError, ExitError, ProtocolError, SandboxError
+from .frames import BULK_CHUNK, FS_CHUNK
+from .template import Template
+
+
+class Sandbox:
+    """One claimed microVM."""
+
+    def __init__(self, client, id: str, token: str, owner: str,
+                 deadline: str = "", from_checkpoint: str = ""):
+        self._client = client
+        self.id = id
+        self.token = token
+        self.owner = owner
+        self.deadline = deadline
+        self.from_checkpoint = from_checkpoint
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *exc):
+        with contextlib.suppress(Exception):
+            self.close()
+
+    def exec(self, *argv: str, cwd: str = "", env: dict | None = None,
+             user: str = "", session: str = "", stdin: bytes = b"") -> str:
+        """Runs argv to completion and returns stdout; a non-zero exit raises
+        ExitError carrying stderr."""
+        out, err = bytearray(), bytearray()
+        code = self.run(list(argv), cwd=cwd, env=env, user=user, session=session,
+                        stdin=stdin, on_stdout=out.extend, on_stderr=err.extend)
+        if code != 0:
+            raise ExitError(code, err.decode(errors="replace"))
+        return out.decode(errors="replace")
+
+    def run(self, argv: list[str], cwd: str = "", env: dict | None = None,
+            user: str = "", session: str = "", stdin: bytes = b"",
+            on_stdout=None, on_stderr=None) -> int:
+        """Runs argv streaming stdio through the callbacks (raw bytes — chunk
+        boundaries may split multi-byte sequences); returns the exit code."""
+        with self._dial() as conn:
+            conn.send("exec", argv=argv, cwd=cwd or None, env=env,
+                      user=user or None, session=session or None)
+            if stdin:
+                _send_chunks(conn, stdin, op="stdin")
+            conn.send("stdin_close")
+            for frame in conn.recv_until("exit"):
+                if frame["type"] == "stdout" and on_stdout:
+                    on_stdout(frame["data"])
+                elif frame["type"] == "stderr" and on_stderr:
+                    on_stderr(frame["data"])
+                elif frame["type"] == "exit":
+                    return frame["code"]
+        raise ProtocolError("exec stream ended without an exit frame")
+
+    def spawn(self, *argv: str, cwd: str = "", env: dict | None = None,
+              user: str = "", session: str = "") -> int:
+        """Starts argv detached, returning its pid immediately; the process
+        keeps a bounded output ring readable later via logs()/attach()."""
+        started = self._call("exec", "started", argv=list(argv), cwd=cwd or None,
+                             env=env, user=user or None, session=session or None,
+                             detach=True)
+        return started["pid"]
+
+    def ps(self) -> list[dict]:
+        """Lists tracked processes: {pid, argv, detached, state,
+        exit_code?, started_at_epoch_secs}."""
+        return self._call("ps", "procs")["procs"]
+
+    def kill(self, pid: int, signal: int | None = None) -> None:
+        """Signals a tracked process (default SIGKILL); killing one that
+        already exited is a no-op success."""
+        self._done_rpc("kill", pid=pid, signal=signal)
+
+    def logs(self, pid: int, on_stdout=None, on_stderr=None) -> int | None:
+        """Replays a process's ring-buffered output through the callbacks;
+        returns its exit code if it already exited, else None."""
+        return self._drain_proc("logs", pid, on_stdout, on_stderr)
+
+    def attach(self, pid: int, on_stdout=None, on_stderr=None) -> int | None:
+        """Replays buffered output then follows live output until the
+        process exits, returning its exit code (None only if the proc table
+        dropped it mid-attach)."""
+        return self._drain_proc("attach", pid, on_stdout, on_stderr)
+
+    def write_file(self, path: str, data: bytes, mode: int | None = None) -> None:
+        """Writes data to path atomically (temp + rename on the guest)."""
+        with self._dial() as conn:
+            conn.send("fs_write", path=path, mode=mode)
+            _send_chunks(conn, data)
+            conn.send("data_end")
+            _expect(conn, "done")
+
+    def read_file(self, path: str) -> bytes:
+        with self._dial() as conn:
+            conn.send("fs_read", path=path)
+            return _drain_data(conn)
+
+    def list_dir(self, path: str) -> list[dict]:
+        with self._dial() as conn:
+            conn.send("fs_list", path=path)
+            entries: list[dict] = []
+            for frame in conn.recv_until("done"):
+                entries.extend(frame.get("entries") or [])
+            return entries
+
+    def stat(self, path: str) -> dict:
+        """Returns {kind, size, mode, mtime_epoch_secs} for path."""
+        return self._call("fs_stat", "stat", path=path)["info"]
+
+    def mkdir(self, path: str, parents: bool = False) -> None:
+        self._done_rpc("fs_mkdir", path=path, parents=parents or None)
+
+    def remove(self, path: str, recursive: bool = False) -> None:
+        self._done_rpc("fs_rm", path=path, recursive=recursive or None)
+
+    def rename(self, src: str, dst: str) -> None:
+        self._done_rpc("fs_rename", **{"from": src, "to": dst})
+
+    def push(self, dest: str, tar_stream: bytes) -> None:
+        """Extracts a tar archive into dest — atomic against a truncated
+        stream; the only project-ingestion path on the no-network lane."""
+        with self._dial() as conn:
+            conn.send("fs_push", dest=dest)
+            _send_chunks(conn, tar_stream, chunk=BULK_CHUNK)
+            conn.send("data_end")
+            _expect(conn, "done")
+
+    def pull(self, path: str) -> bytes:
+        """Returns path (file or tree) as a tar archive."""
+        with self._dial() as conn:
+            conn.send("fs_pull", path=path)
+            return _drain_data(conn)
+
+    def find(self, path: str, pattern: str, glob: str = "") -> list[dict]:
+        with self._dial() as conn:
+            conn.send("fs_find", path=path, pattern=pattern, glob=glob or None)
+            return [f for f in conn.recv_until("done") if f["type"] == "match"]
+
+    def replace(self, files: list[str], pattern: str, replacement: str) -> list[dict]:
+        with self._dial() as conn:
+            conn.send("fs_replace", files=files, pattern=pattern, replacement=replacement)
+            return [f for f in conn.recv_until("done") if f["type"] == "replaced"]
+
+    def git_clone(self, url: str, path: str, branch: str = "", depth: int = 0, auth: str = "") -> None:
+        """Clones into path (egress lane only; the none lane answers a typed
+        unimplemented error pointing at push)."""
+        self._done_rpc("git_clone", url=url, path=path, branch=branch or None,
+                       depth=depth or None, auth=auth or None)
+
+    def git_status(self, path: str) -> dict:
+        return self._call("git_status", "git_status_result", path=path)
+
+    def git_add(self, path: str, files: list[str]) -> None:
+        self._done_rpc("git_add", path=path, files=files)
+
+    def git_commit(self, path: str, message: str, author: str) -> str:
+        """Commits staged changes; returns the commit hash."""
+        return self._call("git_commit", "git_commit_result",
+                          path=path, message=message, author=author).get("hash", "")
+
+    def git_push(self, path: str, auth: str = "") -> None:
+        self._done_rpc("git_push", path=path, auth=auth or None)
+
+    def git_pull(self, path: str, auth: str = "") -> None:
+        self._done_rpc("git_pull", path=path, auth=auth or None)
+
+    def git_branches(self, path: str) -> dict:
+        return self._call("git_branch", "git_branches", path=path, action="list")
+
+    def git_checkout(self, path: str, name: str) -> None:
+        self._done_rpc("git_branch", path=path, action="checkout", name=name)
+
+    def git_create_branch(self, path: str, name: str) -> None:
+        self._done_rpc("git_branch", path=path, action="create", name=name)
+
+    def git_delete_branch(self, path: str, name: str) -> None:
+        self._done_rpc("git_branch", path=path, action="delete", name=name)
+
+    def watch(self, path: str, recursive: bool = False) -> Watcher:
+        """Streams filesystem events under path; events after the returned
+        Watcher exists are guaranteed captured. Close it to stop."""
+        conn, _ = self._open_stream("fs_watch", path=path, recursive=recursive or None)
+        return Watcher(conn)
+
+    def session(self, cwd: str = "", env: dict | None = None) -> Session:
+        """Creates a persistent shell: cd/export/aliases survive across exec
+        calls routed into it."""
+        created = self._call("session_create", "session_created", cwd=cwd or None, env=env)
+        return Session(self, created["id"])
+
+    def sessions(self) -> list[str]:
+        return self._call("session_list", "sessions").get("sessions") or []
+
+    def fork(self, count: int, ttl_seconds: int = 0) -> list[Sandbox]:
+        """Clones this sandbox into count independent children carrying its
+        exact memory and disk state; all-or-nothing."""
+        body = {"token": self.token, "count": count}
+        if ttl_seconds:
+            body["ttl_seconds"] = ttl_seconds
+        reply = self._client._post_json(self.owner, f"/v1/sandboxes/{self.id}/fork", body, "fork")
+        return [self._client._handle_from(self.owner, child) for child in reply.get("children") or []]
+
+    def hibernate(self) -> None:
+        """Snapshots and stops the VM, freeing its memory; the next call that
+        reaches the guest wakes it transparently, state intact."""
+        self._client._request(self.owner, "POST", f"/v1/sandboxes/{self.id}/hibernate",
+                              None, "hibernate", bearer=self.token)
+
+    def checkpoint(self, name: str = "") -> Checkpoint:
+        """Captures full state without stopping the sandbox; the returned
+        Checkpoint branches fresh sandboxes from that exact moment."""
+        body = {"token": self.token}
+        if name:
+            body["name"] = name
+        reply = self._client._post_json(self.owner, f"/v1/sandboxes/{self.id}/checkpoint", body, "checkpoint")
+        return Checkpoint(self._client, self.owner, reply["checkpoint"])
+
+    def promote(self, template: str) -> Template:
+        """Publishes this sandbox's state as a claimable template on its
+        node; the returned handle is bound to that node."""
+        reply = self._client._post_json(self.owner, f"/v1/sandboxes/{self.id}/promote",
+                                        {"token": self.token, "template": template}, "promote")
+        key = reply["key"]
+        return Template(self._client, self.owner, key["template"], key.get("net", ""), key.get("size", ""))
+
+    def start_lsp(self, language: str, root: str = "") -> Lsp:
+        """Spawns the language server the flavor image provides for language;
+        the base image ships none, so it raises SilkdError(kind="not_found").
+        The returned handle streams JSON-RPC over the relay."""
+        started = self._call("lsp_start", "lsp_started", language=language, root=root or None)
+        return Lsp(self, started["server_id"])
+
+    def open_pty(self, cols: int = 80, rows: int = 24, cwd: str = "",
+                 env: dict | None = None, user: str = "") -> Pty:
+        """Runs the guest shell under a pty; returns a byte-stream handle.
+        A pty is a process guest-side: resize goes through its pid."""
+        conn, started = self._open_stream("pty_open", expect="started", cols=cols,
+                                          rows=rows, cwd=cwd or None, env=env, user=user or None)
+        return Pty(self, conn, started["pid"])
+
+    def proxy_port(self, local_addr: str, port: int) -> socket.socket:
+        """Serves a guest port on a local listener for unmodified local
+        tools; returns the listening socket (close it to stop). local_addr
+        is "host:port"; port 0 picks a free one."""
+        host, _, lport = local_addr.rpartition(":")
+        listener = socket.create_server((host or "127.0.0.1", int(lport)))
+        threading.Thread(target=self._proxy_accept_loop,
+                         args=(listener, port), daemon=True).start()
+        return listener
+
+    def preview_url(self, port: int, ttl_seconds: int = 0) -> str:
+        """Mints a shareable URL serving the guest HTTP port from a browser,
+        valid for ttl_seconds (the node clamps it to the claim's lease).
+        Requires the node to have preview configured."""
+        body = {"token": self.token, "port": port}
+        if ttl_seconds:
+            body["ttl_seconds"] = ttl_seconds
+        reply = self._client._post_json(self.owner, f"/v1/sandboxes/{self.id}/preview", body, "preview")
+        return reply["url"]
+
+    def dial_port(self, port: int) -> PortConn:
+        """Opens a byte stream to 127.0.0.1:port inside the guest."""
+        conn, _ = self._open_stream("port_forward", port=port)
+        return PortConn(conn)
+
+    def close(self) -> None:
+        """Releases the sandbox; its VM is destroyed. Releasing one already
+        gone is not an error — double-release and reap races stay silent,
+        matching the Go SDK."""
+        try:
+            self._client._request(self.owner, "POST", f"/v1/sandboxes/{self.id}/release",
+                                  None, "release", bearer=self.token)
+        except APIError as exc:
+            if exc.status != 404:
+                raise
+
+    def _dial(self) -> Conn:
+        return dial_agent(self.owner, self.id, self.token, self._client.timeout)
+
+    def _open_stream(self, op: str, expect: str = "ready", **fields) -> tuple[Conn, dict]:
+        """Dials, sends op, and waits for the handshake frame, closing the
+        conn on any failure so no socket leaks on the error path."""
+        conn = self._dial()
+        try:
+            conn.send(op, **fields)
+            frame = _expect(conn, expect)
+        except Exception:
+            conn.close()
+            raise
+        return conn, frame
+
+    def _proxy_accept_loop(self, listener: socket.socket, port: int) -> None:
+        with contextlib.suppress(OSError):
+            while True:
+                local, _ = listener.accept()
+                threading.Thread(target=self._proxy_conn,
+                                 args=(local, port), daemon=True).start()
+
+    def _proxy_conn(self, local: socket.socket, port: int) -> None:
+        try:
+            guest = self.dial_port(port)
+        except Exception:
+            local.close()
+            return
+
+        def pump_out():
+            with contextlib.suppress(Exception):
+                while True:
+                    chunk = guest.recv()
+                    if not chunk:
+                        break
+                    local.sendall(chunk)
+            with contextlib.suppress(OSError):
+                local.close()
+
+        threading.Thread(target=pump_out, daemon=True).start()
+        try:
+            while True:
+                chunk = local.recv(FS_CHUNK)
+                if not chunk:
+                    break
+                guest.send(chunk)
+            guest.close_write()
+        except Exception:
+            guest.close()
+
+    def _call(self, op: str, expect: str, **fields) -> dict:
+        with self._dial() as conn:
+            conn.send(op, **fields)
+            return _expect(conn, expect)
+
+    def _done_rpc(self, op: str, **fields) -> None:
+        self._call(op, "done", **fields)
+
+    def _drain_proc(self, op: str, pid: int, on_stdout, on_stderr) -> int | None:
+        with self._dial() as conn:
+            conn.send(op, pid=pid)
+            for frame in conn.recv_until("exit", "done"):
+                t = frame["type"]
+                if t == "stdout" and on_stdout:
+                    on_stdout(frame["data"])
+                elif t == "stderr" and on_stderr:
+                    on_stderr(frame["data"])
+                elif t == "exit":
+                    return frame["code"]
+        return None
+
+class Session:
+    """A persistent shell inside the sandbox, addressed by id."""
+
+    def __init__(self, sandbox: Sandbox, id: str):
+        self._sandbox = sandbox
+        self.id = id
+
+    def exec(self, *argv: str) -> str:
+        """Runs argv inside the session's shell; state persists."""
+        return self._sandbox.exec(*argv, session=self.id)
+
+    def close(self) -> None:
+        self._sandbox._done_rpc("session_rm", id=self.id)
+
+class Watcher:
+    """A live filesystem event stream; iterate for {kind, path} events."""
+
+    def __init__(self, conn: Conn):
+        self._conn = conn
+
+    def __iter__(self):
+        # The stream is connection-bound: closing the watcher (or the server
+        # dropping the conn) ends iteration rather than raising.
+        while True:
+            try:
+                frame = self._conn.recv()
+            except (SandboxError, OSError, ValueError):
+                return
+            if frame["type"] == "event":
+                yield frame
+
+    def close(self) -> None:
+        self._conn.close()
+
+class Pty:
+    """An interactive shell under a guest pty; read/write are raw bytes."""
+
+    def __init__(self, sandbox: Sandbox, conn: Conn, pid: int):
+        self._sandbox = sandbox
+        self._conn = conn
+        self.pid = pid
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *exc):
+        self.close()
+
+    def read(self) -> bytes:
+        """The next output chunk; b'' once the shell exits."""
+        frame = self._conn.recv()
+        if frame["type"] == "exit":
+            return b""
+        return frame.get("data") or b""
+
+    def write(self, data: bytes) -> None:
+        self._conn.send("stdin", data=data)
+
+    def resize(self, cols: int, rows: int) -> None:
+        self._sandbox._done_rpc("pty_resize", pid=self.pid, cols=cols, rows=rows)
+
+    def close(self) -> None:
+        self._conn.close()
+
+
+class Lsp:
+    """A language server in the sandbox, spoken to over the relay. silkd is a
+    broker: it pipes JSON-RPC bytes; the caller frames and correlates."""
+
+    def __init__(self, sandbox: Sandbox, server_id: str):
+        self._sandbox = sandbox
+        self.server_id = server_id
+
+    def request(self) -> PortConn:
+        """Opens the JSON-RPC byte stream: writes go to the server's stdin,
+        recv returns its stdout. A server serves one request for its
+        lifetime; closing the stream ends the session and reaps it."""
+        conn, _ = self._sandbox._open_stream("lsp_request", server_id=self.server_id)
+        return PortConn(conn)
+
+    def stop(self) -> None:
+        """Kills the language server."""
+        self._sandbox._done_rpc("lsp_stop", server_id=self.server_id)
+
+
+class PortConn:
+    """A byte stream to a guest port, relayed over the silkd connection."""
+
+    def __init__(self, conn: Conn):
+        self._conn = conn
+        self._eof = False
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *exc):
+        self.close()
+
+    def send(self, data: bytes) -> None:
+        _send_chunks(self._conn, data, chunk=BULK_CHUNK)
+
+    def recv(self) -> bytes:
+        """Returns the next chunk from the guest; b'' on stream end."""
+        if self._eof:
+            return b""
+        frame = self._conn.recv()
+        if frame["type"] in ("done", "exit"):
+            self._eof = True
+            return b""
+        return frame.get("data") or b""
+
+    def close_write(self) -> None:
+        """Half-close: signals EOF to the guest side; reads keep working."""
+        self._conn.send("data_end")
+        self._conn.close_write()
+
+    def close(self) -> None:
+        self._conn.close()
+
+
+def _send_chunks(conn: Conn, data: bytes, op: str = "data", chunk: int = FS_CHUNK) -> None:
+    view = memoryview(data)
+    for off in range(0, len(view), chunk):
+        conn.send(op, data=view[off:off + chunk])
+
+
+def _expect(conn: Conn, frame_type: str) -> dict:
+    frame = conn.recv()
+    if frame["type"] != frame_type:
+        raise ProtocolError(f"expected {frame_type}, got {frame['type']}")
+    return frame
+
+def _drain_data(conn: Conn) -> bytes:
+    chunks = []
+    for frame in conn.recv_until("done"):
+        if frame["type"] == "data":
+            chunks.append(frame["data"])
+    return b"".join(chunks)

cocoonsandbox/template.py

@@ -0,0 +1,40 @@
+"""Template: a promoted sandbox state, claimable by name. The handle is
+bound to the node that holds it, so it works the instant promote returns —
+name-based Client calls route via gossip and lag a promote by about a tick."""
+
+from __future__ import annotations
+
+import urllib.parse
+
+
+class Template:
+    """A promoted template on its owner node."""
+
+    def __init__(self, client, addr: str, name: str, net: str, size: str):
+        self._client = client
+        self._addr = addr
+        self.name = name
+        self.net = net
+        self.size = size
+
+    def new(self, ttl_seconds: int = 0):
+        """Claims a sandbox cloned from the template, on the template's
+        node; the key axes are the template's own."""
+        # Local import: a top-level one would close the client → sandbox →
+        # template cycle.
+        from .client import _claim_body
+
+        claim = _claim_body(self.name, self.net, self.size, ttl_seconds)
+        claim["no_redirect"] = True
+        reply = self._client._post_json(self._addr, "/v1/claim", claim, "claim")
+        return self._client._handle_from(self._addr, reply)
+
+    def delete(self) -> None:
+        """Removes the template from its node."""
+        query = {"template": self.name, "no_redirect": "1"}
+        if self.net:
+            query["net"] = self.net
+        if self.size:
+            query["size"] = self.size
+        self._client._request(self._addr, "DELETE", "/v1/templates?" + urllib.parse.urlencode(query),
+                              None, "delete template")

cocoonstack_sandbox-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,12 @@
+cocoonsandbox/__init__.py,sha256=zAqiwobV2Ps_mLgMeBfws5VwDZytfMaZDBtG0HmQAFI,869
+cocoonsandbox/checkpoint.py,sha256=WIcp_gJgCOMZwiOgG6U0Zi4eq779HqKH6L0Tk3-UIqw,1156
+cocoonsandbox/client.py,sha256=yXZotPK6I78OXBBSMeZiuMTShbx0Gil2pa8KGeCJCY4,6019
+cocoonsandbox/conn.py,sha256=Etd34Iqvrg1MErng5BQMjtf04YWyDqgP-2huRw4nQdU,3338
+cocoonsandbox/errors.py,sha256=R20up-zVgz5TBURYZm7Fb4QHC6HEbFLkuD9lBnT7st8,1126
+cocoonsandbox/frames.py,sha256=CYE0hVKmrhNq4x5Yaox33mQ0cNw7T95GnhdyHlSOL34,1510
+cocoonsandbox/sandbox.py,sha256=g1twBAqe7FpZss0uzPzomtTKiCr3W5t944XYxwa8aMU,20600
+cocoonsandbox/template.py,sha256=QPvC5LDHf2dDmctggip_kRxfNe-PzlDaeZOh7A5peFM,1536
+cocoonstack_sandbox-0.1.0.dist-info/METADATA,sha256=PQYpetdPDBpAhKEDTRCPOlrWM8nx55EIHw8F4_VEgVM,1226
+cocoonstack_sandbox-0.1.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+cocoonstack_sandbox-0.1.0.dist-info/top_level.txt,sha256=WUonHQ4lXa4-Qqy-HMEFjVCndRg-xu7-AkNYqXsYqKQ,14
+cocoonstack_sandbox-0.1.0.dist-info/RECORD,,

cocoonstack_sandbox-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

cocoonstack_sandbox-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+cocoonsandbox