cocoonstack-sandbox 0.1.22__tar.gz → 0.1.24__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (37) hide show
  1. {cocoonstack_sandbox-0.1.22 → cocoonstack_sandbox-0.1.24}/PKG-INFO +2 -2
  2. {cocoonstack_sandbox-0.1.22 → cocoonstack_sandbox-0.1.24}/cocoonsandbox/__init__.py +1 -10
  3. {cocoonstack_sandbox-0.1.22 → cocoonstack_sandbox-0.1.24}/cocoonsandbox/checkpoint.py +2 -2
  4. {cocoonstack_sandbox-0.1.22 → cocoonstack_sandbox-0.1.24}/cocoonsandbox/client.py +56 -40
  5. {cocoonstack_sandbox-0.1.22 → cocoonstack_sandbox-0.1.24}/cocoonsandbox/conn.py +22 -13
  6. {cocoonstack_sandbox-0.1.22 → cocoonstack_sandbox-0.1.24}/cocoonsandbox/endpoint.py +2 -2
  7. {cocoonstack_sandbox-0.1.22 → cocoonstack_sandbox-0.1.24}/cocoonsandbox/errors.py +26 -4
  8. {cocoonstack_sandbox-0.1.22 → cocoonstack_sandbox-0.1.24}/cocoonsandbox/frames.py +3 -6
  9. {cocoonstack_sandbox-0.1.22 → cocoonstack_sandbox-0.1.24}/cocoonsandbox/sandbox.py +121 -64
  10. {cocoonstack_sandbox-0.1.22 → cocoonstack_sandbox-0.1.24}/cocoonsandbox/template.py +3 -7
  11. {cocoonstack_sandbox-0.1.22 → cocoonstack_sandbox-0.1.24}/cocoonstack_sandbox.egg-info/PKG-INFO +2 -2
  12. {cocoonstack_sandbox-0.1.22 → cocoonstack_sandbox-0.1.24}/pyproject.toml +2 -10
  13. {cocoonstack_sandbox-0.1.22 → cocoonstack_sandbox-0.1.24}/tests/test_checkpoint.py +0 -1
  14. {cocoonstack_sandbox-0.1.22 → cocoonstack_sandbox-0.1.24}/tests/test_client.py +28 -33
  15. {cocoonstack_sandbox-0.1.22 → cocoonstack_sandbox-0.1.24}/tests/test_endpoint.py +12 -10
  16. {cocoonstack_sandbox-0.1.22 → cocoonstack_sandbox-0.1.24}/tests/test_fault_matrix.py +98 -84
  17. {cocoonstack_sandbox-0.1.22 → cocoonstack_sandbox-0.1.24}/tests/test_fixtures.py +1 -4
  18. {cocoonstack_sandbox-0.1.22 → cocoonstack_sandbox-0.1.24}/tests/test_frames.py +0 -1
  19. {cocoonstack_sandbox-0.1.22 → cocoonstack_sandbox-0.1.24}/tests/test_hardening.py +5 -5
  20. cocoonstack_sandbox-0.1.24/tests/test_keepalive.py +269 -0
  21. {cocoonstack_sandbox-0.1.22 → cocoonstack_sandbox-0.1.24}/tests/test_proc.py +21 -22
  22. {cocoonstack_sandbox-0.1.22 → cocoonstack_sandbox-0.1.24}/tests/test_stream.py +21 -47
  23. {cocoonstack_sandbox-0.1.22 → cocoonstack_sandbox-0.1.24}/tests/test_upgrade.py +12 -12
  24. {cocoonstack_sandbox-0.1.22 → cocoonstack_sandbox-0.1.24}/tests/test_volume_controller.py +3 -2
  25. {cocoonstack_sandbox-0.1.22 → cocoonstack_sandbox-0.1.24}/tests/test_volumes.py +14 -25
  26. {cocoonstack_sandbox-0.1.22 → cocoonstack_sandbox-0.1.24}/tests/test_wire_binding.py +19 -26
  27. cocoonstack_sandbox-0.1.22/tests/test_keepalive.py +0 -179
  28. {cocoonstack_sandbox-0.1.22 → cocoonstack_sandbox-0.1.24}/LICENSE +0 -0
  29. {cocoonstack_sandbox-0.1.22 → cocoonstack_sandbox-0.1.24}/README.md +0 -0
  30. {cocoonstack_sandbox-0.1.22 → cocoonstack_sandbox-0.1.24}/cocoonsandbox/py.typed +0 -0
  31. {cocoonstack_sandbox-0.1.22 → cocoonstack_sandbox-0.1.24}/cocoonsandbox/volumes.py +0 -0
  32. {cocoonstack_sandbox-0.1.22 → cocoonstack_sandbox-0.1.24}/cocoonstack_sandbox.egg-info/SOURCES.txt +0 -0
  33. {cocoonstack_sandbox-0.1.22 → cocoonstack_sandbox-0.1.24}/cocoonstack_sandbox.egg-info/dependency_links.txt +0 -0
  34. {cocoonstack_sandbox-0.1.22 → cocoonstack_sandbox-0.1.24}/cocoonstack_sandbox.egg-info/top_level.txt +0 -0
  35. {cocoonstack_sandbox-0.1.22 → cocoonstack_sandbox-0.1.24}/setup.cfg +0 -0
  36. {cocoonstack_sandbox-0.1.22 → cocoonstack_sandbox-0.1.24}/tests/test_packaging.py +0 -0
  37. {cocoonstack_sandbox-0.1.22 → cocoonstack_sandbox-0.1.24}/tests/test_proxy.py +0 -0
@@ -1,9 +1,9 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: cocoonstack-sandbox
3
- Version: 0.1.22
3
+ Version: 0.1.24
4
4
  Summary: Python SDK for the cocoon sandbox control plane
5
5
  License: Apache-2.0
6
- Requires-Python: >=3.9
6
+ Requires-Python: >=3.10
7
7
  Description-Content-Type: text/markdown
8
8
  License-File: LICENSE
9
9
  Dynamic: license-file
@@ -1,13 +1,4 @@
1
- """Python SDK for the cocoon sandbox control plane: claim a microVM from a
2
- sandboxd node, run commands over the relayed silkd protocol, branch it with
3
- checkpoints, release it. stdlib-only.
4
-
5
- from cocoonsandbox import Client
6
-
7
- client = Client("node:7777", api_token="...")
8
- with client.new("ghcr.io/cocoonstack/sandbox/rt:24.04") as sb:
9
- print(sb.exec("echo", "hello"))
10
- """
1
+ """Python SDK for the cocoon sandbox control plane; stdlib-only."""
11
2
 
12
3
  from .checkpoint import Checkpoint
13
4
  from .client import Client
@@ -4,7 +4,7 @@ from __future__ import annotations
4
4
 
5
5
  from typing import TYPE_CHECKING, Any
6
6
 
7
- from .errors import require_field
7
+ from .errors import _require_field
8
8
 
9
9
  if TYPE_CHECKING:
10
10
  from .client import Client
@@ -17,7 +17,7 @@ class Checkpoint:
17
17
  def __init__(self, client: Client, addr: str, rec: dict[str, Any]) -> None:
18
18
  self._client = client
19
19
  self._addr = addr
20
- self.id = require_field(rec, "id", "checkpoint")
20
+ self.id = _require_field(rec, "id", "checkpoint")
21
21
  self.name = rec.get("name", "")
22
22
  self.sandbox_id = rec.get("sandbox_id", "")
23
23
  self.created_at = rec.get("created_at", "")
@@ -13,20 +13,20 @@ from collections.abc import Callable, Iterable, Sequence
13
13
  from typing import Any, TypeVar, cast
14
14
 
15
15
  from .checkpoint import Checkpoint
16
- from .conn import Conn, dial_agent, is_quiet, remaining_timeout
16
+ from .conn import Conn, _Closeable, dial_agent, is_quiet, remaining_timeout
17
17
  from .endpoint import _endpoint_url
18
- from .errors import APIError, SandboxTimeout, require_field
18
+ from .errors import APIError, SandboxTimeout, _DialError, _error_message, _require_field
19
19
  from .sandbox import Sandbox
20
20
  from .template import _claim_body, _template_query
21
21
  from .volumes import Volume
22
22
 
23
- T = TypeVar("T")
23
+ _T = TypeVar("_T")
24
24
 
25
25
  _PEERS_TIMEOUT = 5.0
26
26
  _IDLE_CONNS = 8
27
27
 
28
28
 
29
- class Client:
29
+ class Client(_Closeable):
30
30
  """Talks to one sandboxd node (and, transparently, its cluster)."""
31
31
 
32
32
  def __init__(
@@ -38,11 +38,11 @@ class Client:
38
38
  ssl_context: ssl.SSLContext | None = None,
39
39
  keep_alive: float = 30.0,
40
40
  ) -> None:
41
- """keep_alive keeps a handle's idle relay connection, which holds the sandbox's idle clock; 0 dials per call.
41
+ """keep_alive parks idle connections, 0 dials per call; a parked relay one holds the sandbox's idle clock.
42
42
 
43
43
  ssl_context is set to offer ALPN http/1.1, which the relay upgrade needs; pass a dedicated context.
44
44
  """
45
- endpoint = _endpoint_url(addr.split(",")[0].strip())
45
+ endpoint = _endpoint_url(addr.strip())
46
46
  self.addr = endpoint.geturl().removeprefix("http://")
47
47
  self._scheme = endpoint.scheme
48
48
  self._ssl_context = ssl_context
@@ -62,12 +62,11 @@ class Client:
62
62
  ttl_seconds: int = 0,
63
63
  claim_ref: str = "",
64
64
  volumes: list[str | Volume] | None = None,
65
- mount: bool = True,
66
65
  *,
67
66
  deadline: float | None = None,
68
67
  ) -> Sandbox:
69
68
  """Claims a sandbox; a warm hit is milliseconds. deadline is a time.monotonic() bound over the whole claim."""
70
- claim = _claim_body(template, net, size, ttl_seconds, volumes, mount, claim_ref)
69
+ claim = _claim_body(template, net, size, ttl_seconds, volumes, claim_ref)
71
70
  return self._claim_from(self.addr, claim, deadline=deadline)
72
71
 
73
72
  def delete_template(self, template: str, net: str = "", size: str = "") -> None:
@@ -75,7 +74,7 @@ class Client:
75
74
  query = _template_query(template, net, size)
76
75
  path = "/v1/templates?" + urllib.parse.urlencode(query)
77
76
  reply = self._request(self.addr, "DELETE", path, None, "delete template")
78
- candidates = (reply or {}).get("redirect") or []
77
+ candidates = reply.get("redirect") or []
79
78
  if not candidates:
80
79
  return
81
80
  query["no_redirect"] = "1"
@@ -83,7 +82,7 @@ class Client:
83
82
  _try_each(candidates, lambda peer: self._request(peer, "DELETE", path, None, "delete template"))
84
83
 
85
84
  def lookup(self, id: str, token: str) -> Sandbox:
86
- """Finds the owner by probing the entry and peers concurrently."""
85
+ """Finds the owner by listing the peers, then probing the entry and every peer concurrently."""
87
86
 
88
87
  def probe(addr: str) -> Sandbox:
89
88
  reply = self._request(
@@ -113,12 +112,20 @@ class Client:
113
112
  return [dict(sb) for sb in reply.get("sandboxes") or []]
114
113
 
115
114
  def drain(self) -> dict[str, Any]:
116
- """Cordons the node (root token): new claims are refused, live ones run to their leases."""
115
+ """Drains the node (root token): new claims are refused, live ones run to their leases."""
117
116
  return self._request(self.addr, "POST", "/v1/drain", None, "drain")
118
117
 
119
- def uncordon(self) -> dict[str, Any]:
118
+ def undrain(self) -> dict[str, Any]:
120
119
  """Lifts a drain on the node (root token)."""
121
- return self._request(self.addr, "DELETE", "/v1/drain", None, "uncordon")
120
+ return self._request(self.addr, "DELETE", "/v1/drain", None, "undrain")
121
+
122
+ def cordon(self) -> dict[str, Any]:
123
+ """Refuses new claims across restarts (root token); live claims and moves in stay admitted."""
124
+ return self._request(self.addr, "POST", "/v1/cordon", None, "cordon")
125
+
126
+ def uncordon(self) -> dict[str, Any]:
127
+ """Lifts a cordon on the node (root token); a drain stays."""
128
+ return self._request(self.addr, "DELETE", "/v1/cordon", None, "uncordon")
122
129
 
123
130
  def checkpoint(self, id: str) -> Checkpoint:
124
131
  """Binds a checkpoint handle to the entry node without a lookup."""
@@ -138,6 +145,14 @@ class Client:
138
145
  """The node's pool/claim counters, as served by GET /v1/info."""
139
146
  return self._request(self.addr, "GET", "/v1/info", None, "info")
140
147
 
148
+ def close(self) -> None:
149
+ """Closes the parked control connections; a later call dials afresh."""
150
+ with self._idle_lock:
151
+ while self._idle:
152
+ _, idle = self._idle.popitem()
153
+ for conn, _ in idle:
154
+ conn.close()
155
+
141
156
  def _claim_from(
142
157
  self,
143
158
  addr: str,
@@ -147,7 +162,7 @@ class Client:
147
162
  *,
148
163
  deadline: float | None = None,
149
164
  ) -> Sandbox:
150
- reply = self._post_json(addr, path, claim, verb, deadline=deadline)
165
+ reply = self._request(addr, "POST", path, claim, verb, deadline=deadline)
151
166
  redirect = reply.get("redirect") or []
152
167
  if not redirect:
153
168
  return self._handle_from(addr, reply, verb)
@@ -156,7 +171,7 @@ class Client:
156
171
  claim["require_promoted"] = True
157
172
 
158
173
  def post(peer: str) -> dict[str, Any]:
159
- return self._post_json(peer, path, claim, verb, deadline=deadline)
174
+ return self._request(peer, "POST", path, claim, verb, deadline=deadline)
160
175
 
161
176
  owner, reply = _redirect_fallback(addr, redirect, post, verb)
162
177
  return self._handle_from(owner, reply, verb)
@@ -175,8 +190,8 @@ class Client:
175
190
  def _handle_from(self, dialed: str, reply: dict[str, Any], verb: str = "claim") -> Sandbox:
176
191
  return Sandbox(
177
192
  client=self,
178
- id=require_field(reply, "id", verb),
179
- token=require_field(reply, "token", verb),
193
+ id=_require_field(reply, "id", verb),
194
+ token=_require_field(reply, "token", verb),
180
195
  owner=reply.get("owner_addr") or dialed,
181
196
  deadline=reply.get("deadline", ""),
182
197
  from_checkpoint=reply.get("from_checkpoint", ""),
@@ -184,11 +199,6 @@ class Client:
184
199
  volumes=reply.get("volumes") or [],
185
200
  )
186
201
 
187
- def _post_json(
188
- self, addr: str, path: str, body: dict[str, Any], verb: str, *, deadline: float | None = None
189
- ) -> dict[str, Any]:
190
- return self._request(addr, "POST", path, body, verb, deadline=deadline)
191
-
192
202
  def _request(
193
203
  self,
194
204
  addr: str,
@@ -212,7 +222,7 @@ class Client:
212
222
  except (OSError, http.client.HTTPException) as exc:
213
223
  if deadline is not None and time.monotonic() >= deadline:
214
224
  raise SandboxTimeout(f"{verb} timed out") from None
215
- raise APIError(verb, 0, str(exc)) from None
225
+ raise APIError(verb, 0, str(exc)) from exc
216
226
  if status >= 400:
217
227
  try:
218
228
  reply = json.loads(raw)
@@ -229,13 +239,21 @@ class Client:
229
239
  def _dial(self, addr: str, sandbox_id: str, token: str, deadline: float | None = None) -> Conn:
230
240
  origin = addr if "://" in addr else f"{self._scheme}://{addr}"
231
241
  context = self._tls() if origin.startswith("https://") else None
232
- return dial_agent(origin, sandbox_id, token, self.timeout, deadline, ssl_context=context)
242
+ return dial_agent(
243
+ origin, sandbox_id, token, self.timeout, deadline, ssl_context=context, tag=(sandbox_id, addr)
244
+ )
233
245
 
234
246
  def _roundtrip(
235
247
  self, url: urllib.parse.SplitResult, method: str, data: bytes | None, headers: dict[str, str], timeout: float
236
248
  ) -> tuple[int, bytes]:
237
249
  key = (url.scheme, url.netloc)
238
250
  conn = self._take(key, timeout)
251
+ if conn.sock is None:
252
+ try:
253
+ conn.connect()
254
+ except OSError as exc:
255
+ conn.close()
256
+ raise _DialError(str(exc)) from exc
239
257
  status = 0
240
258
  try:
241
259
  conn.request(method, url.path + (f"?{url.query}" if url.query else ""), body=data, headers=headers)
@@ -259,7 +277,6 @@ class Client:
259
277
  return resp.status, raw
260
278
 
261
279
  def _take(self, key: tuple[str, str], timeout: float) -> http.client.HTTPConnection:
262
- """Reuses a parked connection the node has not closed within keep_alive, else dials."""
263
280
  with self._idle_lock:
264
281
  idle = self._idle.get(key, [])
265
282
  while idle:
@@ -280,20 +297,13 @@ class Client:
280
297
  return self._ssl_context
281
298
 
282
299
 
283
- def _error_message(raw: bytes) -> str:
284
- try:
285
- return cast(str, json.loads(raw)["error"])
286
- except (ValueError, KeyError, TypeError):
287
- return raw.decode(errors="replace").strip()
288
-
289
-
290
300
  def _retry_miss(exc: APIError) -> bool:
291
301
  return exc.status in (404, 0)
292
302
 
293
303
 
294
304
  def _try_each(
295
- candidates: Iterable[str], call: Callable[[str], T], retry: Callable[[APIError], bool] = _retry_miss
296
- ) -> T:
305
+ candidates: Iterable[str], call: Callable[[str], _T], retry: Callable[[APIError], bool] = _retry_miss
306
+ ) -> _T:
297
307
  last_error = None
298
308
  for addr in candidates:
299
309
  try:
@@ -306,7 +316,13 @@ def _try_each(
306
316
 
307
317
 
308
318
  def _retry_transient(exc: APIError) -> bool:
309
- return exc.status in (0, 401, 404, 429, 503, 500, 502, 504)
319
+ return exc.status in (0, 401, 404, 429, 500, 503)
320
+
321
+
322
+ def _claim_refused(exc: APIError) -> bool:
323
+ if exc.status:
324
+ return exc.status not in (502, 504)
325
+ return exc.__cause__ is None or isinstance(exc.__cause__, _DialError)
310
326
 
311
327
 
312
328
  def _redirect_fallback(
@@ -319,9 +335,9 @@ def _redirect_fallback(
319
335
  return addr, reply
320
336
 
321
337
  try:
322
- return _try_each(candidates, attempt, retry=lambda _: True)
338
+ return _try_each(candidates, attempt, retry=_claim_refused)
323
339
  except APIError as exc:
324
- if not _retry_transient(exc):
340
+ if not (_claim_refused(exc) and _retry_transient(exc)):
325
341
  raise
326
342
  try:
327
343
  return attempt(origin)
@@ -330,8 +346,8 @@ def _redirect_fallback(
330
346
  raise APIError(verb, origin_exc.status, combined) from origin_exc
331
347
 
332
348
 
333
- def _scatter(addrs: Sequence[str], probe: Callable[[str], T]) -> T:
334
- results: queue.Queue[tuple[T | None, Exception | None]] = queue.Queue(maxsize=len(addrs))
349
+ def _scatter(addrs: Sequence[str], probe: Callable[[str], _T]) -> _T:
350
+ results: queue.Queue[tuple[_T | None, Exception | None]] = queue.Queue(maxsize=len(addrs))
335
351
 
336
352
  def run(addr: str) -> None:
337
353
  try:
@@ -345,6 +361,6 @@ def _scatter(addrs: Sequence[str], probe: Callable[[str], T]) -> T:
345
361
  for _ in addrs:
346
362
  value, error = results.get()
347
363
  if error is None:
348
- return cast(T, value)
364
+ return cast(_T, value)
349
365
  last_error = error
350
366
  raise cast(Exception, last_error)
@@ -12,10 +12,10 @@ import urllib.parse
12
12
  from collections.abc import Callable, Iterator
13
13
  from typing import Any, BinaryIO, Protocol, TypeVar, cast
14
14
 
15
- from .errors import APIError, ProtocolError, SandboxError, SandboxTimeout, SilkdError
15
+ from .errors import APIError, ProtocolError, SandboxError, SandboxTimeout, SilkdError, _error_message, _mark_gone
16
16
  from .frames import MAX_FRAME, decode_response, encode_request
17
17
 
18
- KEEP_ALIVE_CONNS = 8
18
+ _KEEP_ALIVE_CONNS = 8
19
19
  _FD_SETSIZE = 1024
20
20
  _READ_BUFFER = 64 * 1024
21
21
  _TCP_KEEPALIVE = {"TCP_KEEPIDLE": 15, "TCP_KEEPALIVE": 15, "TCP_KEEPINTVL": 15, "TCP_KEEPCNT": 9}
@@ -24,8 +24,6 @@ _CloseableT = TypeVar("_CloseableT", bound="_Closeable")
24
24
 
25
25
 
26
26
  class _Closeable(Protocol):
27
- """Context-manager mixin for handles whose exit is just close()."""
28
-
29
27
  def __enter__(self: _CloseableT) -> _CloseableT:
30
28
  return self
31
29
 
@@ -39,12 +37,18 @@ class Conn(_Closeable):
39
37
  """A frame stream to one sandbox's silkd; a plain-HTTP upgrade rides the first send, its 101 the first recv."""
40
38
 
41
39
  def __init__(
42
- self, sock: socket.socket, reader: BinaryIO, request: bytes = b"", upgrade_timeout: float | None = None
40
+ self,
41
+ sock: socket.socket,
42
+ reader: BinaryIO,
43
+ request: bytes = b"",
44
+ upgrade_timeout: float | None = None,
45
+ tag: tuple[str, str] = ("", ""),
43
46
  ) -> None:
44
47
  self._sock = sock
45
48
  self._reader = reader
46
49
  self._request = request
47
50
  self._upgrade_timeout = upgrade_timeout
51
+ self._tag = tag
48
52
 
49
53
  def send(self, op: str, **fields: object) -> None:
50
54
  frame = encode_request(op, **fields)
@@ -109,7 +113,9 @@ class Conn(_Closeable):
109
113
  deadline = time.monotonic() + limit
110
114
  try:
111
115
  _read_upgrade(
112
- self._reader, lambda: self._sock.settimeout(remaining_timeout(limit, deadline, "agent upgrade"))
116
+ self._reader,
117
+ lambda: self._sock.settimeout(remaining_timeout(limit, deadline, "agent upgrade")),
118
+ self._tag,
113
119
  )
114
120
  self._sock.settimeout(caller)
115
121
  except Exception as exc:
@@ -140,7 +146,7 @@ class ConnPool:
140
146
 
141
147
  def park(self, conn: Conn) -> None:
142
148
  with self._lock:
143
- if self._idle > 0 and len(self._parked) < KEEP_ALIVE_CONNS:
149
+ if self._idle > 0 and len(self._parked) < _KEEP_ALIVE_CONNS:
144
150
  self._parked.append((time.monotonic() + self._idle, conn))
145
151
  if self._sweep is None:
146
152
  self._arm(self._idle)
@@ -181,6 +187,7 @@ def dial_agent(
181
187
  deadline: float | None = None,
182
188
  *,
183
189
  ssl_context: ssl.SSLContext | None = None,
190
+ tag: tuple[str, str] = ("", ""),
184
191
  ) -> Conn:
185
192
  """Opens one TCP/HTTP Upgrade relay within timeout and the optional deadline."""
186
193
  budget = time.monotonic() + timeout
@@ -194,7 +201,8 @@ def dial_agent(
194
201
  try:
195
202
  sock = socket.create_connection((host, port), timeout=remaining_timeout(timeout, deadline))
196
203
  except OSError as exc:
197
- raise _handshake_error(f"dial {addr}", exc) from exc
204
+ err = _handshake_error(f"dial {addr}", exc)
205
+ raise (_mark_gone(err, tag) if isinstance(exc, ConnectionRefusedError) else err) from exc
198
206
  sock.setsockopt(socket.IPPROTO_TCP, socket.TCP_NODELAY, 1)
199
207
  sock.setsockopt(socket.SOL_SOCKET, socket.SO_KEEPALIVE, 1)
200
208
  for opt, setting in _TCP_KEEPALIVE.items():
@@ -212,7 +220,7 @@ def dial_agent(
212
220
  try:
213
221
  if endpoint.scheme != "https":
214
222
  sock.settimeout(None)
215
- return Conn(sock, _buffered_reader(sock), request, timeout)
223
+ return Conn(sock, _buffered_reader(sock), request, timeout, tag)
216
224
  context = ssl_context or ssl.create_default_context()
217
225
  sock = context.wrap_socket(sock, server_hostname=host, do_handshake_on_connect=False)
218
226
  sock.settimeout(remaining_timeout(timeout, deadline))
@@ -224,7 +232,7 @@ def dial_agent(
224
232
  sock.settimeout(remaining_timeout(timeout, deadline))
225
233
  sock.sendall(request)
226
234
  reader = _buffered_reader(sock)
227
- _read_upgrade(reader, lambda: sock.settimeout(remaining_timeout(timeout, deadline)))
235
+ _read_upgrade(reader, lambda: sock.settimeout(remaining_timeout(timeout, deadline)), tag)
228
236
  remaining_timeout(timeout, deadline)
229
237
  sock.settimeout(None)
230
238
  return Conn(sock, reader)
@@ -271,7 +279,7 @@ def _handshake_error(what: str, exc: OSError) -> SandboxError:
271
279
  return ProtocolError(f"{what}: {exc}")
272
280
 
273
281
 
274
- def _read_upgrade(reader: BinaryIO, arm: Callable[[], None]) -> None:
282
+ def _read_upgrade(reader: BinaryIO, arm: Callable[[], None], tag: tuple[str, str]) -> None:
275
283
  arm()
276
284
  status = reader.readline(1024).decode(errors="replace")
277
285
  if not status:
@@ -294,5 +302,6 @@ def _read_upgrade(reader: BinaryIO, arm: Callable[[], None]) -> None:
294
302
  raise ProtocolError("invalid content-length in upgrade reply") from exc
295
303
  if code != 101:
296
304
  arm()
297
- body = reader.read(min(body_len, MAX_FRAME)).decode(errors="replace") if body_len else ""
298
- raise APIError("agent upgrade", code, body.strip() or status.strip())
305
+ body = reader.read(min(body_len, MAX_FRAME)) if body_len else b""
306
+ err = APIError("agent upgrade", code, _error_message(body) or status.strip())
307
+ raise _mark_gone(err, tag) if code == 404 else err
@@ -5,11 +5,11 @@ from __future__ import annotations
5
5
  import urllib.parse
6
6
 
7
7
 
8
- def _endpoint_url(addr: str, scheme: str = "http") -> urllib.parse.SplitResult:
8
+ def _endpoint_url(addr: str) -> urllib.parse.SplitResult:
9
9
  if any(ord(c) <= 32 or ord(c) == 127 for c in addr):
10
10
  raise ValueError("sandboxd endpoint contains whitespace or a control character")
11
11
  if "://" not in addr:
12
- addr = f"{scheme}://{addr}"
12
+ addr = f"http://{addr}"
13
13
  endpoint = urllib.parse.urlsplit(addr)
14
14
  if (
15
15
  endpoint.scheme not in ("http", "https")
@@ -2,15 +2,20 @@
2
2
 
3
3
  from __future__ import annotations
4
4
 
5
- from typing import TYPE_CHECKING, Any
5
+ import json
6
+ from typing import TYPE_CHECKING, Any, TypeVar, cast
6
7
 
7
8
  if TYPE_CHECKING:
8
9
  from .volumes import SandboxVolumesResponse
9
10
 
11
+ _E = TypeVar("_E", bound="SandboxError")
12
+
10
13
 
11
14
  class SandboxError(Exception):
12
15
  """Base class for all SDK errors."""
13
16
 
17
+ _owner_gone: tuple[str, str] | None = None
18
+
14
19
 
15
20
  class SandboxTimeout(SandboxError, TimeoutError):
16
21
  """A caller's timeout or deadline expired before the call finished."""
@@ -48,7 +53,8 @@ class ExitError(SandboxError):
48
53
  """A command exited non-zero; carries the code, stderr, and the stdout produced before it failed."""
49
54
 
50
55
  def __init__(self, code: int, stderr: str, stdout: str = "") -> None:
51
- super().__init__(f"exit status {code}: {stderr.strip()}")
56
+ detail = stderr.strip()
57
+ super().__init__(f"exit status {code}: {detail}" if detail else f"exit status {code}")
52
58
  self.code = code
53
59
  self.stderr = stderr
54
60
  self.stdout = stdout
@@ -58,8 +64,24 @@ class ProtocolError(SandboxError):
58
64
  """The peer broke the frame protocol (unexpected frame, oversized line)."""
59
65
 
60
66
 
61
- def require_field(reply: dict[str, Any], key: str, verb: str) -> Any:
62
- """The named member of a control-plane reply, or an APIError naming the verb that got a truncated one."""
67
+ class _DialError(OSError):
68
+ pass
69
+
70
+
71
+ def _require_field(reply: dict[str, Any], key: str, verb: str) -> Any:
63
72
  if key not in reply:
64
73
  raise APIError(verb, 0, f"reply without {key}")
65
74
  return reply[key]
75
+
76
+
77
+ def _error_message(raw: bytes) -> str:
78
+ try:
79
+ return cast(str, json.loads(raw)["error"])
80
+ except (ValueError, KeyError, TypeError):
81
+ return raw.decode(errors="replace").strip()
82
+
83
+
84
+ def _mark_gone(exc: _E, tag: tuple[str, str]) -> _E:
85
+ """Tags an owner's 404 or refused dial with its (sandbox id, owner address)."""
86
+ exc._owner_gone = tag
87
+ return exc
@@ -10,19 +10,17 @@ import sys
10
10
  from typing import Any
11
11
 
12
12
  PROTO_VERSION = 1
13
- # the info proto from which silkd serves RPCs back to back on one connection
14
- KEEP_ALIVE_PROTO = 2
15
13
  MAX_FRAME = 8 * 1024 * 1024
16
- FS_CHUNK = 256 * 1024
14
+ BULK_CHUNK = 256 * 1024
17
15
  # tar and port streams chunk at 1 MiB, still under MAX_FRAME after base64
18
- BULK_CHUNK = 1 << 20
16
+ STREAM_CHUNK = 1 << 20
19
17
  _FAST_DATA = sys.version_info >= (3, 11)
20
18
 
21
19
 
22
20
  def encode_request(op: str, **fields: object) -> bytes:
23
21
  """Encodes one request, omitting None fields and base64-encoding byte values."""
24
22
  if len(fields) == 1 and isinstance(data := fields.get("data"), (bytes, bytearray, memoryview)):
25
- # base64 needs no JSON escaping, so a bare data frame renders without a str round trip
23
+ # base64 needs no JSON escaping
26
24
  return b'{"v":%d,"op":"%s","data":"%s"}\n' % (PROTO_VERSION, op.encode(), base64.b64encode(data))
27
25
  frame = {"v": PROTO_VERSION, "op": op}
28
26
  for key, value in fields.items():
@@ -36,7 +34,6 @@ def encode_request(op: str, **fields: object) -> bytes:
36
34
 
37
35
  def decode_response(line: bytes) -> dict[str, Any]:
38
36
  """Decodes one response with binary payloads under data."""
39
- # base64 is JSON-escape-free, so an exactly-shaped data frame slices without json.loads.
40
37
  if _FAST_DATA and line.startswith(b'{"type":"'):
41
38
  te = line.find(b'"', 9)
42
39
  if te > 0 and line[9:te] in (b"stdout", b"stderr", b"data") and line.startswith(b'","data":"', te):