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

{cocoonstack_sandbox-0.1.2/cocoonstack_sandbox.egg-info → cocoonstack_sandbox-0.1.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cocoonstack-sandbox
-Version: 0.1.2
+Version: 0.1.4
 Summary: Python SDK for the cocoon sandbox control plane
 License: Apache-2.0
 Requires-Python: >=3.9

cocoonstack_sandbox-0.1.4/cocoonsandbox/checkpoint.py

@@ -0,0 +1,55 @@
+"""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
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .sandbox import Sandbox
+
+
+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) -> Sandbox:
+        """Claims a fresh sandbox branched from the checkpoint, following a
+        redirect to the node that actually holds it; if every candidate
+        fails transiently, the claim falls back to the origin once so it
+        heals (pulls the checkpoint) locally."""
+        # Local import: a top-level one would close the client -> sandbox ->
+        # checkpoint cycle.
+        from .client import _redirect_fallback
+
+        claim = {"ttl_seconds": ttl_seconds} if ttl_seconds else {}
+        path = f"/v1/checkpoints/{self.id}/claim"
+        reply = self._client._post_json(self._addr, path, claim, "claim checkpoint")
+        redirect = reply.get("redirect") or []
+        if not redirect:
+            return self._client._handle_from(self._addr, reply)
+        claim["no_redirect"] = True
+
+        def post(peer):
+            return self._client._post_json(peer, path, claim, "claim checkpoint")
+
+        addr, reply = _redirect_fallback(self._addr, redirect, post, "claim checkpoint")
+        return self._client._handle_from(addr, reply)
+
+    def delete(self) -> None:
+        """Removes the checkpoint from its node and asks every peer that node
+        currently sees to drop any replica a heal pulled — best-effort eventual
+        cleanup, not a fleet-wide revocation. A peer that misses that broadcast
+        (offline, partitioned, or joined later) keeps serving branches from its
+        replica until the node's checkpoint_ttl_hours ages it out; with that
+        TTL at its default of 0 (keep forever), an unreachable peer's replica
+        has no cleanup bound at all."""
+        self._client._request(self._addr, "DELETE", f"/v1/checkpoints/{self.id}", None, "delete checkpoint")

{cocoonstack_sandbox-0.1.2 → cocoonstack_sandbox-0.1.4}/cocoonsandbox/client.py

@@ -29,20 +29,21 @@ class Client:
 
     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."""
+        miss may redirect to a peer, followed transparently; if every
+        candidate fails transiently, the claim falls back to the origin
+        once so it provisions or heals locally."""
         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)
+        if not redirect:
+            return self._handle_from(self.addr, reply)
+        claim["no_redirect"] = True
+
+        def post(peer):
+            return self._post_json(peer, "/v1/claim", claim, "claim")
+
+        addr, reply = _redirect_fallback(self.addr, redirect, post, "claim")
+        return self._handle_from(addr, reply)
 
     def delete_template(self, template: str, net: str = "", size: str = "") -> None:
         """Removes a promoted template by name; on a cluster the delete
@@ -191,6 +192,48 @@ def _try_each(candidates, call, retry=lambda exc: exc.status in (404, 0)):
     raise last_error
 
 
+def _retry_transient(exc: APIError) -> bool:
+    """Origin-fallback policy: worth the round-trip for a transport failure
+    (status 0), a miss (404), full (429), mid-heal (503), an engine/proxy
+    failure (500/502/504), or a mid-rotation 401 (the origin proved the
+    token valid by issuing the redirect). A served 4xx like a bad request,
+    a forbidden token, or an egress conflict is definitive: the origin
+    would fail the same way."""
+    return exc.status in (0, 401, 404, 429, 503, 500, 502, 504)
+
+
+def _redirect_fallback(origin: str, candidates: list, post, verb: str):
+    """Walks candidates via post(addr) -> raw reply dict, retrying broadly
+    (any candidate failure moves to the next) so one wrong candidate doesn't
+    cost a candidate that would still succeed. If every candidate is
+    exhausted and the last failure was transient (_retry_transient), gives
+    the origin one more no_redirect attempt -- the node that issued the
+    redirect provisions or heals locally instead of leaving the claim stuck
+    on stale gossip. A definitive last failure skips the fallback: the origin
+    would fail the same way. A second-level redirect (a compliant server
+    never sends one once no_redirect is set) fails the candidate rather than
+    being followed. Returns (addr, reply)."""
+    def attempt(addr):
+        reply = post(addr)
+        if reply.get("redirect"):
+            raise APIError(verb, 0, f"{addr} redirected again despite no_redirect")
+        return addr, reply
+
+    try:
+        return _try_each(candidates, attempt, retry=lambda _: True)
+    except APIError as exc:
+        if not _retry_transient(exc):
+            raise
+        try:
+            return attempt(origin)
+        except APIError as origin_exc:
+            # Both halves matter to whoever reads this: the peers' failure says
+            # why the claim left the origin, the origin's why returning did not help.
+            origin_exc.message = f"{origin_exc.message} (after redirect targets failed: {exc.message})"
+            origin_exc.args = (f"{verb}: {origin_exc.message} (HTTP {origin_exc.status})",)
+            raise
+
+
 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

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

@@ -69,6 +69,8 @@ def dial_agent(addr: str, sandbox_id: str, token: str, timeout: float) -> Conn:
             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)
+    # Nagle off: exec/write send small back-to-back frames before the first read.
+    sock.setsockopt(socket.IPPROTO_TCP, socket.TCP_NODELAY, 1)
     reader = None
     try:
         request = (

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

@@ -10,7 +10,7 @@ import json
 
 PROTO_VERSION = 1
 MAX_FRAME = 8 * 1024 * 1024
-FS_CHUNK = 32 * 1024
+FS_CHUNK = 256 * 1024  # silkd's per-frame chunk size, distinct from BULK_CHUNK below
 # 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
@@ -32,12 +32,10 @@ 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.
+    # base64 is JSON-escape-free, so a frame shaped exactly {"type":...,
+    # "data":...} can be sliced directly, skipping json.loads; any other
+    # shape (extra fields, trailing bytes, non-alphabet bytes) falls through
+    # to the full parse instead of risking 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):

{cocoonstack_sandbox-0.1.2 → cocoonstack_sandbox-0.1.4}/cocoonsandbox/sandbox.py

@@ -67,12 +67,11 @@ class Sandbox:
         return code
 
     def spawn(self, *argv: str, cwd: str = "", env: dict | None = None,
-              user: str = "", session: str = "") -> int:
+              user: 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)
+                             env=env, user=user or None, detach=True)
         return started["pid"]
 
     def ps(self) -> list[dict]:

{cocoonstack_sandbox-0.1.2 → cocoonstack_sandbox-0.1.4/cocoonstack_sandbox.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cocoonstack-sandbox
-Version: 0.1.2
+Version: 0.1.4
 Summary: Python SDK for the cocoon sandbox control plane
 License: Apache-2.0
 Requires-Python: >=3.9

{cocoonstack_sandbox-0.1.2 → cocoonstack_sandbox-0.1.4}/cocoonstack_sandbox.egg-info/SOURCES.txt

@@ -13,6 +13,7 @@ cocoonstack_sandbox.egg-info/PKG-INFO
 cocoonstack_sandbox.egg-info/SOURCES.txt
 cocoonstack_sandbox.egg-info/dependency_links.txt
 cocoonstack_sandbox.egg-info/top_level.txt
+tests/test_checkpoint.py
 tests/test_client.py
 tests/test_fault_matrix.py
 tests/test_fixtures.py

{cocoonstack_sandbox-0.1.2 → cocoonstack_sandbox-0.1.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "cocoonstack-sandbox"
-version = "0.1.2"
+version = "0.1.4"
 description = "Python SDK for the cocoon sandbox control plane"
 requires-python = ">=3.9"
 license = { text = "Apache-2.0" }

cocoonstack_sandbox-0.1.4/tests/test_checkpoint.py

@@ -0,0 +1,122 @@
+"""Checkpoint claim redirect: mirrors the cluster redirect follow tested for
+Client.new in test_fault_matrix.py, applied to Checkpoint.new."""
+
+import socket
+import threading
+from http.server import HTTPServer
+
+import pytest
+from test_client import FakeNode
+
+from cocoonsandbox import APIError, Client
+
+
+@pytest.fixture
+def spawn_node():
+    servers = []
+
+    def spawn(routes):
+        handler = type("Node", (FakeNode,), {"routes": routes})
+        server = HTTPServer(("127.0.0.1", 0), handler)
+        threading.Thread(target=server.serve_forever, daemon=True).start()
+        servers.append(server)
+        return f"127.0.0.1:{server.server_port}"
+
+    yield spawn
+    for server in servers:
+        server.shutdown()
+
+
+@pytest.fixture
+def dead_addr():
+    sock = socket.socket()
+    sock.bind(("127.0.0.1", 0))
+    port = sock.getsockname()[1]
+    sock.close()
+    return f"127.0.0.1:{port}"
+
+
+def test_checkpoint_new_follows_redirect(spawn_node):
+    seen = []
+
+    def claim_at_b(body, path):
+        seen.append(body)
+        return 200, {"id": "sb_ck1", "token": "tok"}
+
+    node_b = spawn_node({("POST", "/v1/checkpoints/ck_1/claim"): claim_at_b})
+
+    entry_hits = []
+
+    def redirect(body, path):
+        entry_hits.append(body)
+        return 200, {"redirect": [node_b]}
+
+    entry = spawn_node({("POST", "/v1/checkpoints/ck_1/claim"): redirect})
+
+    sb = Client(entry).checkpoint("ck_1").new()
+    assert sb.id == "sb_ck1"
+    assert sb.owner == node_b
+    assert len(entry_hits) == 1
+    assert seen[0]["no_redirect"] is True
+
+
+def test_checkpoint_new_all_candidates_fail(spawn_node):
+    # The probed owner transiently fails (500); once exhausted, new() falls
+    # back to the origin, which this time fails definitively too.
+    path = "/v1/checkpoints/ck_2/claim"
+    broken = spawn_node({("POST", path): lambda body, p: (500, {"error": "boom"})})
+
+    calls = []
+
+    def entry_claim(body, p):
+        calls.append(body)
+        if len(calls) == 1:
+            return 200, {"redirect": [broken]}
+        return 409, {"error": "origin also failed"}
+
+    entry = spawn_node({("POST", path): entry_claim})
+    with pytest.raises(APIError) as exc:
+        Client(entry).checkpoint("ck_2").new()
+    assert exc.value.status == 409 and "origin also failed" in exc.value.message
+    assert len(calls) == 2 and calls[1]["no_redirect"] is True
+
+
+def test_checkpoint_new_redirect_fallback_heals(spawn_node):
+    # The only probed owner is mid-heal (503); once exhausted, new() falls
+    # back to the origin, which heals (pulls the checkpoint) locally.
+    path = "/v1/checkpoints/ck_5/claim"
+    busy = spawn_node({("POST", path): lambda body, p: (503, {"error": "healing"})})
+
+    calls = []
+
+    def entry_claim(body, p):
+        calls.append(body)
+        if len(calls) == 1:
+            return 200, {"redirect": [busy]}
+        return 200, {"id": "sb_healed", "token": "t"}
+
+    entry = spawn_node({("POST", path): entry_claim})
+    sb = Client(entry).checkpoint("ck_5").new()
+    assert sb.id == "sb_healed" and sb.owner == entry
+    assert len(calls) == 2 and calls[1]["no_redirect"] is True
+
+
+def test_checkpoint_new_redirect_never_yields_empty_id(spawn_node, dead_addr):
+    # Regression: new() used to hand a bare redirect reply straight to
+    # _handle_from, producing a Sandbox with no id/token. It must now follow
+    # the redirect and raise when no candidate answers.
+    entry = spawn_node({("POST", "/v1/checkpoints/ck_3/claim"): lambda body, path: (200, {"redirect": [dead_addr]})})
+
+    with pytest.raises(APIError):
+        Client(entry).checkpoint("ck_3").new()
+
+
+def test_checkpoint_new_second_level_redirect_fails(spawn_node):
+    # A compliant server never redirects a no_redirect retry; if one does
+    # anyway, it must be treated as a failed candidate rather than followed.
+    path = "/v1/checkpoints/ck_4/claim"
+    node_b = spawn_node({("POST", path): lambda body, p: (200, {"redirect": ["127.0.0.1:1"]})})
+    entry = spawn_node({("POST", path): lambda body, p: (200, {"redirect": [node_b]})})
+
+    with pytest.raises(APIError):
+        Client(entry).checkpoint("ck_4").new()

{cocoonstack_sandbox-0.1.2 → cocoonstack_sandbox-0.1.4}/tests/test_fault_matrix.py

@@ -1,6 +1,8 @@
 """Fault matrix for the cluster redirect follow and the lookup scatter:
-dead first candidate (connection refused), 404 first candidate, all-404 —
-and lookup must not pay a hung or dead peer's full timeout."""
+dead first candidate (connection refused), 404 first candidate, a definitive
+candidate error that still tries the next one, every candidate exhausted
+(then the origin fallback heals, fails, or is skipped for a definitive
+error) — and lookup must not pay a hung or dead peer's full timeout."""
 
 import socket
 import threading
@@ -61,13 +63,107 @@ def test_claim_redirect_skips_404_candidate(spawn_node):
     assert Client(entry).new("rt:24.04").id == "sb_2"
 
 
-def test_claim_redirect_all_404_propagates_last(spawn_node):
+def test_claim_redirect_all_candidates_fail_then_origin_fallback_fails(spawn_node):
+    # Every candidate is a stale miss (404); once exhausted, new() falls
+    # back to the origin, which this time fails definitively too.
     a = spawn_node({("POST", "/v1/claim"): lambda body, path: (404, {"error": "gone a"})})
     b = spawn_node({("POST", "/v1/claim"): lambda body, path: (404, {"error": "gone b"})})
-    entry = spawn_node({("POST", "/v1/claim"): lambda body, path: (200, {"redirect": [a, b]})})
+
+    calls = []
+
+    def entry_claim(body, path):
+        calls.append(body)
+        if len(calls) == 1:
+            return 200, {"redirect": [a, b]}
+        return 409, {"error": "origin also failed"}
+
+    entry = spawn_node({("POST", "/v1/claim"): entry_claim})
+    with pytest.raises(APIError) as exc:
+        Client(entry).new("rt:24.04")
+    assert exc.value.status == 409 and "origin also failed" in exc.value.message
+    # The last candidate's failure must survive into the message: it is what
+    # says why the claim left the origin in the first place.
+    assert "gone b" in exc.value.message
+    assert len(calls) == 2 and calls[1]["no_redirect"] is True
+
+
+def test_claim_redirect_all_candidates_fail_then_origin_heals(spawn_node):
+    # The only candidate holds the record but is full (429); once exhausted,
+    # new() falls back to the origin, which heals (provisions locally).
+    full_calls = []
+
+    def full_claim(body, path):
+        full_calls.append(body)
+        return 429, {"error": "full"}
+
+    full = spawn_node({("POST", "/v1/claim"): full_claim})
+
+    calls = []
+
+    def entry_claim(body, path):
+        calls.append(body)
+        if len(calls) == 1:
+            return 200, {"redirect": [full]}
+        return 200, {"id": "sb_healed", "token": "t"}
+
+    entry = spawn_node({("POST", "/v1/claim"): entry_claim})
+    sb = Client(entry).new("rt:24.04")
+    assert sb.id == "sb_healed" and sb.owner == entry
+    assert len(calls) == 2 and calls[1]["no_redirect"] is True
+    assert len(full_calls) == 1
+
+
+@pytest.mark.parametrize(("status", "message"), [(409, "no egress"), (403, "tenant not allowed")])
+def test_claim_redirect_definitive_error_skips_origin_fallback(spawn_node, status, message):
+    # A definitive 4xx is not worth trying another candidate, and not worth
+    # falling back to the origin either -- the origin would fail the same way.
+    bad = spawn_node({("POST", "/v1/claim"): lambda body, path: (status, {"error": message})})
+
+    calls = []
+
+    def entry_claim(body, path):
+        calls.append(body)
+        return 200, {"redirect": [bad]}
+
+    entry = spawn_node({("POST", "/v1/claim"): entry_claim})
     with pytest.raises(APIError) as exc:
         Client(entry).new("rt:24.04")
-    assert exc.value.status == 404 and "gone b" in exc.value.message
+    assert exc.value.status == status
+    assert len(calls) == 1
+
+
+def test_claim_redirect_401_candidate_falls_back_to_origin(spawn_node):
+    stale_calls = []
+
+    def stale_claim(body, path):
+        stale_calls.append(body)
+        return 401, {"error": "invalid api token"}
+
+    stale = spawn_node({("POST", "/v1/claim"): stale_claim})
+
+    calls = []
+
+    def entry_claim(body, path):
+        calls.append(body)
+        if len(calls) == 1:
+            return 200, {"redirect": [stale]}
+        return 200, {"id": "sb_local", "token": "t"}
+
+    entry = spawn_node({("POST", "/v1/claim"): entry_claim})
+    sb = Client(entry).new("rt:24.04")
+    assert sb.id == "sb_local" and sb.owner == entry
+    assert len(calls) == 2 and calls[1]["no_redirect"] is True
+    assert len(stale_calls) == 1
+
+
+def test_claim_redirect_candidate_definitive_error_still_tries_next_candidate(spawn_node):
+    # Candidate one is wrong for this claim (403, definitive) but candidate
+    # two would still succeed -- the per-candidate walk retries broadly, so
+    # one ill-suited candidate must not cost a candidate that would answer.
+    forbidden = spawn_node({("POST", "/v1/claim"): lambda body, path: (403, {"error": "tenant not allowed"})})
+    good = spawn_node({("POST", "/v1/claim"): lambda body, path: (200, {"id": "sb_3", "token": "t"})})
+    entry = spawn_node({("POST", "/v1/claim"): lambda body, path: (200, {"redirect": [forbidden, good]})})
+    assert Client(entry).new("rt:24.04").id == "sb_3"
 
 
 def test_delete_template_skips_dead_owner(spawn_node, dead_addr):

cocoonstack_sandbox-0.1.2/cocoonsandbox/checkpoint.py

@@ -1,32 +0,0 @@
-"""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
-
-from typing import TYPE_CHECKING
-
-if TYPE_CHECKING:
-    from .sandbox import Sandbox
-
-
-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) -> 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")
-        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")