devzero-sandbox 0.1.0__py3-none-any.whl
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.
- devzero_sandbox/__init__.py +41 -0
- devzero_sandbox/_bgscript.py +104 -0
- devzero_sandbox/_proto/__init__.py +1 -0
- devzero_sandbox/_proto/sandbox/__init__.py +1 -0
- devzero_sandbox/_proto/sandbox/v1/__init__.py +1 -0
- devzero_sandbox/_proto/sandbox/v1/error_pb2.py +40 -0
- devzero_sandbox/_proto/sandbox/v1/error_pb2.pyi +23 -0
- devzero_sandbox/_proto/sandbox/v1/service_connect.py +381 -0
- devzero_sandbox/_proto/sandbox/v1/service_pb2.py +227 -0
- devzero_sandbox/_proto/sandbox/v1/service_pb2.pyi +898 -0
- devzero_sandbox/auth.py +363 -0
- devzero_sandbox/commands.py +818 -0
- devzero_sandbox/connect.py +381 -0
- devzero_sandbox/errors.py +453 -0
- devzero_sandbox/files.py +217 -0
- devzero_sandbox/incluster.py +42 -0
- devzero_sandbox/mcp/__init__.py +55 -0
- devzero_sandbox/mcp/__main__.py +7 -0
- devzero_sandbox/mcp/config.py +132 -0
- devzero_sandbox/mcp/server.py +259 -0
- devzero_sandbox/mcp/tools.py +1007 -0
- devzero_sandbox/py.typed +0 -0
- devzero_sandbox/redaction.py +78 -0
- devzero_sandbox/sandbox.py +634 -0
- devzero_sandbox/terminal.py +428 -0
- devzero_sandbox/transport.py +546 -0
- devzero_sandbox-0.1.0.dist-info/METADATA +113 -0
- devzero_sandbox-0.1.0.dist-info/RECORD +31 -0
- devzero_sandbox-0.1.0.dist-info/WHEEL +4 -0
- devzero_sandbox-0.1.0.dist-info/entry_points.txt +2 -0
- devzero_sandbox-0.1.0.dist-info/licenses/LICENSE +202 -0
|
@@ -0,0 +1,453 @@
|
|
|
1
|
+
"""Typed errors: the gateway's (data plane) and DevZero's (control plane).
|
|
2
|
+
|
|
3
|
+
Every SDK exception derives from :class:`DevZeroSandboxError`.
|
|
4
|
+
|
|
5
|
+
Data plane (ADR-007 §Error-code table). The gateway answers every failure with
|
|
6
|
+
``{"error": {"code", "message", "sandbox_id", "retryable"}}``;
|
|
7
|
+
:func:`from_response` turns one into the :class:`GatewayError` subclass for its
|
|
8
|
+
code or status. Files the gateway proxies to ``sandboxd`` answer in
|
|
9
|
+
``sandboxd``'s own shape, ``{"code": "NOT_FOUND", "message": ...}``, which maps
|
|
10
|
+
to :class:`SandboxFileNotFound` and friends. Exec streams add
|
|
11
|
+
:class:`StreamInterrupted` (the stream ended before the process reported its
|
|
12
|
+
exit) and :class:`UpstreamTimeout` with the pid.
|
|
13
|
+
|
|
14
|
+
Control plane (ADR-003 §API contract). A failed ``SandboxService`` RPC carries
|
|
15
|
+
a Connect code and one ``SandboxError{code, retryable, details}`` detail;
|
|
16
|
+
:func:`control_plane_error` picks the :class:`ControlPlaneError` subclass for
|
|
17
|
+
the ``SandboxError.code`` (``cluster_unreachable`` → :class:`ClusterUnreachable`,
|
|
18
|
+
and so on).
|
|
19
|
+
|
|
20
|
+
Every message passes through :func:`devzero_sandbox.redaction.redact`, so a
|
|
21
|
+
server (or a proxy in front of it) that echoes a credential cannot put it into
|
|
22
|
+
an exception, a traceback or a log line.
|
|
23
|
+
"""
|
|
24
|
+
|
|
25
|
+
from __future__ import annotations
|
|
26
|
+
|
|
27
|
+
import json
|
|
28
|
+
from collections.abc import Mapping
|
|
29
|
+
from typing import Any
|
|
30
|
+
|
|
31
|
+
import httpx
|
|
32
|
+
|
|
33
|
+
from devzero_sandbox.redaction import redact
|
|
34
|
+
|
|
35
|
+
|
|
36
|
+
class DevZeroSandboxError(Exception):
|
|
37
|
+
"""Base of every exception the SDK raises on purpose."""
|
|
38
|
+
|
|
39
|
+
|
|
40
|
+
# --- data plane: the gateway ----------------------------------------------------
|
|
41
|
+
|
|
42
|
+
|
|
43
|
+
class GatewayError(DevZeroSandboxError):
|
|
44
|
+
"""A non-2xx answer from the sandbox gateway (or a failure it reported on a stream)."""
|
|
45
|
+
|
|
46
|
+
def __init__(
|
|
47
|
+
self,
|
|
48
|
+
*,
|
|
49
|
+
status: int,
|
|
50
|
+
code: str,
|
|
51
|
+
message: str,
|
|
52
|
+
sandbox_id: str | None = None,
|
|
53
|
+
retryable: bool = False,
|
|
54
|
+
retry_after_s: float | None = None,
|
|
55
|
+
pid: int | None = None,
|
|
56
|
+
) -> None:
|
|
57
|
+
self.status = status
|
|
58
|
+
self.code = code
|
|
59
|
+
self.message = redact(message)
|
|
60
|
+
self.sandbox_id = sandbox_id
|
|
61
|
+
self.retryable = retryable
|
|
62
|
+
self.retry_after_s = retry_after_s
|
|
63
|
+
self.pid = pid
|
|
64
|
+
super().__init__(self.__str__())
|
|
65
|
+
|
|
66
|
+
def __str__(self) -> str:
|
|
67
|
+
where = f" (sandbox {self.sandbox_id})" if self.sandbox_id else ""
|
|
68
|
+
proc = f" (pid {self.pid})" if self.pid is not None else ""
|
|
69
|
+
return f"{self.status} {self.code or 'error'}{where}{proc}: {self.message}"
|
|
70
|
+
|
|
71
|
+
def __repr__(self) -> str:
|
|
72
|
+
return (
|
|
73
|
+
f"{type(self).__name__}(status={self.status}, code={self.code!r}, "
|
|
74
|
+
f"retryable={self.retryable}, message={self.message!r})"
|
|
75
|
+
)
|
|
76
|
+
|
|
77
|
+
|
|
78
|
+
class AuthError(GatewayError):
|
|
79
|
+
"""``401``: the gateway refused the credential (``token_*``, ``sa_token_*``, ...)."""
|
|
80
|
+
|
|
81
|
+
|
|
82
|
+
class PermissionDenied(GatewayError):
|
|
83
|
+
"""``403``: authenticated, but not allowed (scope, SubjectAccessReview, creator)."""
|
|
84
|
+
|
|
85
|
+
|
|
86
|
+
class PolicyMismatch(PermissionDenied):
|
|
87
|
+
"""``403 sandbox_policy_mismatch``: the sandbox is not under the URL's policy or team."""
|
|
88
|
+
|
|
89
|
+
|
|
90
|
+
class BadRequest(GatewayError):
|
|
91
|
+
"""``400 bad_request`` / ``bad_sandbox_id``: the request itself is malformed."""
|
|
92
|
+
|
|
93
|
+
|
|
94
|
+
class SandboxNotFound(GatewayError):
|
|
95
|
+
"""``404 sandbox_not_found``: terminal once 10 s have passed since create/ready."""
|
|
96
|
+
|
|
97
|
+
|
|
98
|
+
class ProcessNotFound(GatewayError):
|
|
99
|
+
"""``404 process_not_found``: the sandbox exists, the pid does not (or has exited)."""
|
|
100
|
+
|
|
101
|
+
|
|
102
|
+
class SandboxGone(GatewayError):
|
|
103
|
+
"""``409 sandbox_terminating`` or ``410 sandbox_expired``: the sandbox will not come back.
|
|
104
|
+
|
|
105
|
+
Never retried (ADR-010-W11). ``reason`` is why it went, as ADR-010 names
|
|
106
|
+
the deleters: ``Expired`` (its shutdown time passed), ``Idle``,
|
|
107
|
+
``Deleted`` (``DeleteSandbox``), ``PolicyDraining``, ``CrashLoop``, ...
|
|
108
|
+
A ``410`` is ``Expired`` by definition; otherwise the SDK asks DevZero,
|
|
109
|
+
and ``phase`` and ``reason`` stay ``None`` when DevZero cannot say (no
|
|
110
|
+
client in-cluster, or the deletion has not reached it yet).
|
|
111
|
+
``SandboxGoneError`` is the same class under ADR-010's name.
|
|
112
|
+
"""
|
|
113
|
+
|
|
114
|
+
def __init__(self, **kwargs: Any) -> None:
|
|
115
|
+
self.phase: str | None = None
|
|
116
|
+
self.reason: str | None = (
|
|
117
|
+
"Expired" if kwargs.get("code") == "sandbox_expired" else None
|
|
118
|
+
)
|
|
119
|
+
self.reason_message = ""
|
|
120
|
+
super().__init__(**kwargs)
|
|
121
|
+
|
|
122
|
+
def explain(self, phase: str, reason: str, message: str = "") -> None:
|
|
123
|
+
"""Record what DevZero says about the sandbox (``GetSandbox``)."""
|
|
124
|
+
self.phase = phase
|
|
125
|
+
if reason:
|
|
126
|
+
self.reason, self.reason_message = reason, redact(message)
|
|
127
|
+
self.args = (self.__str__(),)
|
|
128
|
+
|
|
129
|
+
def __str__(self) -> str:
|
|
130
|
+
why = ""
|
|
131
|
+
if self.reason:
|
|
132
|
+
detail = f": {self.reason_message}" if self.reason_message else ""
|
|
133
|
+
why = f" [reason {self.reason}{detail}]"
|
|
134
|
+
return super().__str__() + why
|
|
135
|
+
|
|
136
|
+
|
|
137
|
+
SandboxGoneError = SandboxGone
|
|
138
|
+
|
|
139
|
+
|
|
140
|
+
class SandboxPaused(GatewayError):
|
|
141
|
+
"""``409 sandbox_paused``: the sandbox is suspended (Phase 2 pause/resume)."""
|
|
142
|
+
|
|
143
|
+
|
|
144
|
+
class PayloadTooLarge(GatewayError):
|
|
145
|
+
"""``413 payload_too_large`` / ``431 headers_too_large``.
|
|
146
|
+
|
|
147
|
+
On ``POST /v1/exec`` it means the command's stdout or stderr passed 4 MiB:
|
|
148
|
+
the command ran; run it again with ``stream=True`` to get all of its output.
|
|
149
|
+
"""
|
|
150
|
+
|
|
151
|
+
|
|
152
|
+
class RateLimited(GatewayError):
|
|
153
|
+
"""``429``: too many streams for the sandbox or the principal, or auth failures."""
|
|
154
|
+
|
|
155
|
+
|
|
156
|
+
class Unavailable(GatewayError):
|
|
157
|
+
"""``503``: the gateway cannot serve the request now (retryable)."""
|
|
158
|
+
|
|
159
|
+
|
|
160
|
+
class SandboxNotReady(Unavailable):
|
|
161
|
+
"""``503 sandbox_not_ready``: the gateway does not route the sandbox yet. Retryable."""
|
|
162
|
+
|
|
163
|
+
|
|
164
|
+
class UpstreamTimeout(GatewayError):
|
|
165
|
+
"""``504 upstream_timeout`` (unary) or ``event: error`` ``upstream_timeout`` (stream).
|
|
166
|
+
|
|
167
|
+
The command outlived ``timeout_s`` (or a stream outlived the gateway's idle
|
|
168
|
+
or lifetime limit) and was killed. ``pid`` is set for a stream.
|
|
169
|
+
"""
|
|
170
|
+
|
|
171
|
+
|
|
172
|
+
CommandTimeout = UpstreamTimeout
|
|
173
|
+
|
|
174
|
+
|
|
175
|
+
class SandboxFileNotFound(GatewayError, FileNotFoundError):
|
|
176
|
+
"""``404 NOT_FOUND`` from ``sandboxd``: no such file or directory in the sandbox."""
|
|
177
|
+
|
|
178
|
+
|
|
179
|
+
_BY_CODE: dict[str, type[GatewayError]] = {
|
|
180
|
+
"sandbox_not_ready": SandboxNotReady,
|
|
181
|
+
"sandbox_not_found": SandboxNotFound,
|
|
182
|
+
"process_not_found": ProcessNotFound,
|
|
183
|
+
"sandbox_terminating": SandboxGone,
|
|
184
|
+
"sandbox_expired": SandboxGone,
|
|
185
|
+
"sandbox_paused": SandboxPaused,
|
|
186
|
+
"sandbox_policy_mismatch": PolicyMismatch,
|
|
187
|
+
"payload_too_large": PayloadTooLarge,
|
|
188
|
+
"headers_too_large": PayloadTooLarge,
|
|
189
|
+
"upstream_timeout": UpstreamTimeout,
|
|
190
|
+
# sandboxd's own codes (REST file routes, passed through by the gateway).
|
|
191
|
+
"NOT_FOUND": SandboxFileNotFound,
|
|
192
|
+
}
|
|
193
|
+
|
|
194
|
+
_BY_STATUS: dict[int, type[GatewayError]] = {
|
|
195
|
+
400: BadRequest,
|
|
196
|
+
401: AuthError,
|
|
197
|
+
403: PermissionDenied,
|
|
198
|
+
413: PayloadTooLarge,
|
|
199
|
+
429: RateLimited,
|
|
200
|
+
503: Unavailable,
|
|
201
|
+
504: UpstreamTimeout,
|
|
202
|
+
}
|
|
203
|
+
|
|
204
|
+
|
|
205
|
+
class StreamInterrupted(DevZeroSandboxError):
|
|
206
|
+
"""An exec stream ended before the process reported its exit.
|
|
207
|
+
|
|
208
|
+
A gateway rollout (``event: drain``, then the stream closes at the end of
|
|
209
|
+
the drain window), a dropped connection, or ``sandboxd`` failing mid-stream.
|
|
210
|
+
``sandboxd`` kills a process whose stream closes, so the process is gone;
|
|
211
|
+
``pid`` says which. ``code`` is the gateway's ``event: error`` code, if one
|
|
212
|
+
arrived (``sandbox_unreachable``), else ``drain`` or ``disconnected``.
|
|
213
|
+
|
|
214
|
+
A unary exec whose command the drain window cut short (``503
|
|
215
|
+
exec_interrupted``) raises it too, with ``code`` ``drain`` and no ``pid``
|
|
216
|
+
(unary exec reports none): the command ran and is not re-run.
|
|
217
|
+
"""
|
|
218
|
+
|
|
219
|
+
def __init__(self, *, pid: int | None, code: str, message: str) -> None:
|
|
220
|
+
self.pid = pid
|
|
221
|
+
self.code = code
|
|
222
|
+
self.message = redact(message)
|
|
223
|
+
super().__init__(f"exec stream interrupted (pid {pid}, {code}): {self.message}")
|
|
224
|
+
|
|
225
|
+
|
|
226
|
+
def _retry_after(value: str | None) -> float | None:
|
|
227
|
+
if value is None:
|
|
228
|
+
return None
|
|
229
|
+
try:
|
|
230
|
+
seconds = float(value)
|
|
231
|
+
except ValueError:
|
|
232
|
+
return None # an HTTP-date; the gateway sends seconds only
|
|
233
|
+
return seconds if seconds >= 0 else None
|
|
234
|
+
|
|
235
|
+
|
|
236
|
+
def classify(status: int, code: str) -> type[GatewayError]:
|
|
237
|
+
"""The :class:`GatewayError` subclass for a status and code."""
|
|
238
|
+
if status == 401:
|
|
239
|
+
return AuthError
|
|
240
|
+
cls = _BY_CODE.get(code)
|
|
241
|
+
if cls is not None and (code != "NOT_FOUND" or status == 404):
|
|
242
|
+
return cls
|
|
243
|
+
return _BY_STATUS.get(status, GatewayError)
|
|
244
|
+
|
|
245
|
+
|
|
246
|
+
def from_response(response: httpx.Response, *, pid: int | None = None) -> GatewayError:
|
|
247
|
+
"""Build the typed error for a non-2xx response whose body has been read."""
|
|
248
|
+
code, message, sandbox_id, retryable = "", "", None, None
|
|
249
|
+
try:
|
|
250
|
+
body = json.loads(response.content)
|
|
251
|
+
except ValueError:
|
|
252
|
+
body = None
|
|
253
|
+
err = body.get("error") if isinstance(body, dict) else None
|
|
254
|
+
if isinstance(err, dict):
|
|
255
|
+
code = str(err.get("code") or "")
|
|
256
|
+
message = str(err.get("message") or "")
|
|
257
|
+
sandbox_id = str(err["sandbox_id"]) if err.get("sandbox_id") else None
|
|
258
|
+
if isinstance(err.get("retryable"), bool):
|
|
259
|
+
retryable = err["retryable"]
|
|
260
|
+
elif isinstance(body, dict) and isinstance(body.get("code"), str):
|
|
261
|
+
# sandboxd's own error shape on the REST routes the gateway proxies.
|
|
262
|
+
code, message = body["code"], str(body.get("message") or "")
|
|
263
|
+
else:
|
|
264
|
+
# Not the gateway's envelope (a load balancer, a proxy): keep a bounded excerpt.
|
|
265
|
+
message = response.text[:300] if response.content else response.reason_phrase
|
|
266
|
+
if retryable is None:
|
|
267
|
+
# Pre-W8 gateways and envelope-less 503s from the path to the gateway.
|
|
268
|
+
retryable = response.status_code == 503
|
|
269
|
+
return classify(response.status_code, code)(
|
|
270
|
+
status=response.status_code,
|
|
271
|
+
code=code,
|
|
272
|
+
message=message,
|
|
273
|
+
sandbox_id=sandbox_id,
|
|
274
|
+
retryable=retryable,
|
|
275
|
+
retry_after_s=_retry_after(response.headers.get("retry-after")),
|
|
276
|
+
pid=pid,
|
|
277
|
+
)
|
|
278
|
+
|
|
279
|
+
|
|
280
|
+
# --- control plane: DevZero's SandboxService ------------------------------------
|
|
281
|
+
|
|
282
|
+
|
|
283
|
+
class ControlPlaneError(DevZeroSandboxError):
|
|
284
|
+
"""A failed ``SandboxService`` RPC: its Connect code and ``SandboxError`` detail.
|
|
285
|
+
|
|
286
|
+
``connect_code`` is the Connect code (``unavailable``); ``code`` is the
|
|
287
|
+
``SandboxError.code`` of ADR-003's table (``cluster_unreachable``), or the
|
|
288
|
+
Connect code when the server sent no detail (a proxy, an old server).
|
|
289
|
+
"""
|
|
290
|
+
|
|
291
|
+
def __init__(
|
|
292
|
+
self,
|
|
293
|
+
*,
|
|
294
|
+
connect_code: str,
|
|
295
|
+
code: str,
|
|
296
|
+
message: str,
|
|
297
|
+
retryable: bool = False,
|
|
298
|
+
details: Mapping[str, str] | None = None,
|
|
299
|
+
) -> None:
|
|
300
|
+
self.connect_code = connect_code
|
|
301
|
+
self.code = code
|
|
302
|
+
self.message = redact(message)
|
|
303
|
+
self.retryable = retryable
|
|
304
|
+
self.details = {k: redact(v) for k, v in (details or {}).items()}
|
|
305
|
+
super().__init__(self.__str__())
|
|
306
|
+
|
|
307
|
+
def __str__(self) -> str:
|
|
308
|
+
extra = f" {self.details}" if self.details else ""
|
|
309
|
+
return f"{self.connect_code}/{self.code}: {self.message}{extra}"
|
|
310
|
+
|
|
311
|
+
def __repr__(self) -> str:
|
|
312
|
+
return (
|
|
313
|
+
f"{type(self).__name__}(connect_code={self.connect_code!r}, code={self.code!r}, "
|
|
314
|
+
f"retryable={self.retryable}, message={self.message!r})"
|
|
315
|
+
)
|
|
316
|
+
|
|
317
|
+
|
|
318
|
+
class Unauthenticated(ControlPlaneError):
|
|
319
|
+
"""``unauthenticated``: the DevZero credential (``dzu-``/``dzs-``) is missing or invalid."""
|
|
320
|
+
|
|
321
|
+
|
|
322
|
+
class Forbidden(ControlPlaneError):
|
|
323
|
+
"""``forbidden``: the caller's team role is too low, or the policy's ``access.teams`` excludes it."""
|
|
324
|
+
|
|
325
|
+
|
|
326
|
+
class NotFound(ControlPlaneError):
|
|
327
|
+
"""``not_found``: unknown to the caller (identical for a resource the caller cannot see)."""
|
|
328
|
+
|
|
329
|
+
|
|
330
|
+
class InvalidRequest(ControlPlaneError):
|
|
331
|
+
"""``invalid_request`` and the override pre-checks (``image_not_allowed``, ...); see ``details``."""
|
|
332
|
+
|
|
333
|
+
|
|
334
|
+
class QuotaExceeded(ControlPlaneError):
|
|
335
|
+
"""``policy_max_sandboxes_exceeded``."""
|
|
336
|
+
|
|
337
|
+
|
|
338
|
+
class ControlPlaneRateLimited(ControlPlaneError):
|
|
339
|
+
"""``rate_limited``: the per-cluster create limiter."""
|
|
340
|
+
|
|
341
|
+
|
|
342
|
+
class SandboxStateConflict(ControlPlaneError):
|
|
343
|
+
"""``sandbox_paused`` / ``sandbox_terminating`` / ``sandbox_not_extendable`` /
|
|
344
|
+
``policy_draining`` / ``max_ttl_reached``."""
|
|
345
|
+
|
|
346
|
+
|
|
347
|
+
class SandboxNotExtendable(SandboxStateConflict):
|
|
348
|
+
"""``sandbox_not_extendable``: ``extend`` refused for the sandbox's state.
|
|
349
|
+
|
|
350
|
+
``details['reason']`` is ``Phase`` (not ready, pending, recreating or
|
|
351
|
+
paused) or ``Expired`` (its shutdown time already passed).
|
|
352
|
+
"""
|
|
353
|
+
|
|
354
|
+
|
|
355
|
+
class MaxTTLReached(SandboxStateConflict):
|
|
356
|
+
"""``max_ttl_reached``: the sandbox already shuts down at its policy's ``maxTTL`` ceiling."""
|
|
357
|
+
|
|
358
|
+
|
|
359
|
+
class IdempotencyConflict(ControlPlaneError):
|
|
360
|
+
"""``idempotency_conflict``: the key was used for a different request."""
|
|
361
|
+
|
|
362
|
+
|
|
363
|
+
class RejectedInCluster(ControlPlaneError):
|
|
364
|
+
"""``rejected_in_cluster``: the cluster refused the sandbox; ``details['reason']`` says why."""
|
|
365
|
+
|
|
366
|
+
|
|
367
|
+
class ClusterUnreachable(ControlPlaneError):
|
|
368
|
+
"""``cluster_unreachable``: DevZero has not heard from the cluster (~150 s). Retryable."""
|
|
369
|
+
|
|
370
|
+
|
|
371
|
+
class ClusterNotReady(ControlPlaneError):
|
|
372
|
+
"""``cluster_not_ready``: the policy is not ``Ready``; ``details['condition']``."""
|
|
373
|
+
|
|
374
|
+
|
|
375
|
+
_CP_BY_CODE: dict[str, type[ControlPlaneError]] = {
|
|
376
|
+
"unauthenticated": Unauthenticated,
|
|
377
|
+
"forbidden": Forbidden,
|
|
378
|
+
"not_found": NotFound,
|
|
379
|
+
"invalid_request": InvalidRequest,
|
|
380
|
+
"image_not_allowed": InvalidRequest,
|
|
381
|
+
"resources_exceed_max": InvalidRequest,
|
|
382
|
+
"env_not_allowed": InvalidRequest,
|
|
383
|
+
"policy_max_sandboxes_exceeded": QuotaExceeded,
|
|
384
|
+
"rate_limited": ControlPlaneRateLimited,
|
|
385
|
+
"sandbox_paused": SandboxStateConflict,
|
|
386
|
+
"sandbox_terminating": SandboxStateConflict,
|
|
387
|
+
"sandbox_not_extendable": SandboxNotExtendable,
|
|
388
|
+
"policy_draining": SandboxStateConflict,
|
|
389
|
+
"max_ttl_reached": MaxTTLReached,
|
|
390
|
+
"idempotency_conflict": IdempotencyConflict,
|
|
391
|
+
"rejected_in_cluster": RejectedInCluster,
|
|
392
|
+
"cluster_unreachable": ClusterUnreachable,
|
|
393
|
+
"cluster_not_ready": ClusterNotReady,
|
|
394
|
+
}
|
|
395
|
+
|
|
396
|
+
# Without a SandboxError detail, the Connect code alone.
|
|
397
|
+
_CP_BY_CONNECT: dict[str, type[ControlPlaneError]] = {
|
|
398
|
+
"unauthenticated": Unauthenticated,
|
|
399
|
+
"permission_denied": Forbidden,
|
|
400
|
+
"not_found": NotFound,
|
|
401
|
+
"invalid_argument": InvalidRequest,
|
|
402
|
+
}
|
|
403
|
+
|
|
404
|
+
|
|
405
|
+
def control_plane_error(
|
|
406
|
+
*,
|
|
407
|
+
connect_code: str,
|
|
408
|
+
message: str,
|
|
409
|
+
code: str | None = None,
|
|
410
|
+
retryable: bool | None = None,
|
|
411
|
+
details: Mapping[str, str] | None = None,
|
|
412
|
+
) -> ControlPlaneError:
|
|
413
|
+
"""The typed error for a Connect error and its ``SandboxError`` detail (if any)."""
|
|
414
|
+
if code:
|
|
415
|
+
cls = _CP_BY_CODE.get(code, ControlPlaneError)
|
|
416
|
+
else:
|
|
417
|
+
cls = _CP_BY_CONNECT.get(connect_code, ControlPlaneError)
|
|
418
|
+
if retryable is None:
|
|
419
|
+
# No detail: Connect's own guidance (unavailable is the retryable code).
|
|
420
|
+
retryable = connect_code == "unavailable"
|
|
421
|
+
return cls(
|
|
422
|
+
connect_code=connect_code,
|
|
423
|
+
code=code or connect_code,
|
|
424
|
+
message=message,
|
|
425
|
+
retryable=retryable,
|
|
426
|
+
details=details,
|
|
427
|
+
)
|
|
428
|
+
|
|
429
|
+
|
|
430
|
+
# --- sandbox lifecycle seen through the control plane ----------------------------
|
|
431
|
+
|
|
432
|
+
|
|
433
|
+
class SandboxFailed(DevZeroSandboxError):
|
|
434
|
+
"""The sandbox reached a phase it will not leave for ``ready`` (failed, deleted, ...)."""
|
|
435
|
+
|
|
436
|
+
def __init__(
|
|
437
|
+
self, sandbox_id: str, phase: str, reason: str = "", message: str = ""
|
|
438
|
+
) -> None:
|
|
439
|
+
self.sandbox_id = sandbox_id
|
|
440
|
+
self.phase = phase
|
|
441
|
+
self.reason = reason
|
|
442
|
+
self.message = redact(message)
|
|
443
|
+
detail = f" ({reason}: {self.message})" if reason or message else ""
|
|
444
|
+
super().__init__(f"sandbox {sandbox_id} is {phase}{detail}")
|
|
445
|
+
|
|
446
|
+
|
|
447
|
+
class SandboxWaitTimeout(DevZeroSandboxError, TimeoutError):
|
|
448
|
+
"""The sandbox was not ``ready`` within ``timeout_s``. It may still become ready."""
|
|
449
|
+
|
|
450
|
+
def __init__(self, sandbox_id: str, phase: str, timeout_s: float) -> None:
|
|
451
|
+
self.sandbox_id = sandbox_id
|
|
452
|
+
self.phase = phase
|
|
453
|
+
super().__init__(f"sandbox {sandbox_id} still {phase} after {timeout_s:g}s")
|
devzero_sandbox/files.py
ADDED
|
@@ -0,0 +1,217 @@
|
|
|
1
|
+
"""Files in a sandbox: ``sandbox.files`` (ADR-007-W13).
|
|
2
|
+
|
|
3
|
+
The gateway proxies ``/v1/files/{path}`` to ``sandboxd``'s REST API
|
|
4
|
+
(ADR-007 §URL scheme): ``GET`` reads a file (``Range`` supported) or lists a
|
|
5
|
+
directory, ``PUT`` writes (atomically, or ``?append=true``), ``DELETE``
|
|
6
|
+
removes. Paths are relative to the sandbox root (``/workspace``); an absolute
|
|
7
|
+
path under the root is accepted too. Errors are the typed gateway errors,
|
|
8
|
+
with ``sandboxd``'s ``404 NOT_FOUND`` as
|
|
9
|
+
:class:`~devzero_sandbox.errors.SandboxFileNotFound`.
|
|
10
|
+
|
|
11
|
+
Uploads stream. The policy's ``limits.maxUploadBytes`` (default 2 GiB) caps
|
|
12
|
+
one request body (``413 payload_too_large``); ``write(..., chunk_size=n)``
|
|
13
|
+
splits a large upload into one ``PUT`` and appending ``PUT`` s of at most
|
|
14
|
+
``n`` bytes each.
|
|
15
|
+
"""
|
|
16
|
+
|
|
17
|
+
from __future__ import annotations
|
|
18
|
+
|
|
19
|
+
import posixpath
|
|
20
|
+
from collections.abc import Iterable, Iterator
|
|
21
|
+
from dataclasses import dataclass
|
|
22
|
+
from typing import IO, Literal
|
|
23
|
+
from urllib.parse import quote
|
|
24
|
+
|
|
25
|
+
from devzero_sandbox import errors
|
|
26
|
+
from devzero_sandbox.transport import GatewayTransport
|
|
27
|
+
|
|
28
|
+
#: Read size for streamed uploads from a file object.
|
|
29
|
+
_READ = 1 << 20
|
|
30
|
+
|
|
31
|
+
|
|
32
|
+
@dataclass(frozen=True)
|
|
33
|
+
class EntryInfo:
|
|
34
|
+
"""One directory entry, as ``sandboxd`` lists it."""
|
|
35
|
+
|
|
36
|
+
name: str
|
|
37
|
+
path: str
|
|
38
|
+
type: Literal["file", "directory"]
|
|
39
|
+
size: int
|
|
40
|
+
modified_at: str
|
|
41
|
+
mode: str = ""
|
|
42
|
+
|
|
43
|
+
|
|
44
|
+
Data = bytes | str | IO[bytes] | Iterable[bytes]
|
|
45
|
+
|
|
46
|
+
|
|
47
|
+
class Files:
|
|
48
|
+
"""Read, write, list and delete files in one sandbox."""
|
|
49
|
+
|
|
50
|
+
def __init__(
|
|
51
|
+
self, transport: GatewayTransport, *, workspace: str = "/workspace"
|
|
52
|
+
) -> None:
|
|
53
|
+
self._t = transport
|
|
54
|
+
self.workspace = workspace.rstrip("/") or "/"
|
|
55
|
+
|
|
56
|
+
def relative(self, path: str) -> str:
|
|
57
|
+
"""``path`` relative to the sandbox root; refuses one that leaves it."""
|
|
58
|
+
if path.startswith("/"):
|
|
59
|
+
root = (
|
|
60
|
+
self.workspace if self.workspace.endswith("/") else self.workspace + "/"
|
|
61
|
+
)
|
|
62
|
+
if path != self.workspace and not path.startswith(root):
|
|
63
|
+
raise ValueError(
|
|
64
|
+
f"{path!r} is outside the sandbox root {self.workspace}"
|
|
65
|
+
)
|
|
66
|
+
path = path[len(self.workspace) :]
|
|
67
|
+
norm = posixpath.normpath(path.lstrip("/") or ".")
|
|
68
|
+
if norm == ".." or norm.startswith("../"):
|
|
69
|
+
raise ValueError(f"{path!r} leaves the sandbox root")
|
|
70
|
+
return "" if norm == "." else norm
|
|
71
|
+
|
|
72
|
+
def _url(self, path: str) -> str:
|
|
73
|
+
rel = self.relative(path)
|
|
74
|
+
return (
|
|
75
|
+
"/v1/files/" + "/".join(quote(seg, safe="") for seg in rel.split("/"))
|
|
76
|
+
if rel
|
|
77
|
+
else "/v1/files/"
|
|
78
|
+
)
|
|
79
|
+
|
|
80
|
+
def read(self, path: str, *, tail_bytes: int | None = None) -> bytes:
|
|
81
|
+
"""The file's bytes, or only its last ``tail_bytes``."""
|
|
82
|
+
headers = {}
|
|
83
|
+
if tail_bytes is not None:
|
|
84
|
+
if tail_bytes <= 0:
|
|
85
|
+
return b""
|
|
86
|
+
headers["Range"] = f"bytes=-{int(tail_bytes)}"
|
|
87
|
+
try:
|
|
88
|
+
resp = self._t.request(
|
|
89
|
+
"GET",
|
|
90
|
+
self._url(path),
|
|
91
|
+
scope="files",
|
|
92
|
+
params={"type": "file"},
|
|
93
|
+
headers=headers,
|
|
94
|
+
)
|
|
95
|
+
except errors.GatewayError as e:
|
|
96
|
+
if e.status == 416: # an empty file has no last N bytes
|
|
97
|
+
return b""
|
|
98
|
+
raise
|
|
99
|
+
return resp.content
|
|
100
|
+
|
|
101
|
+
def read_text(self, path: str, encoding: str = "utf-8") -> str:
|
|
102
|
+
return self.read(path).decode(encoding)
|
|
103
|
+
|
|
104
|
+
def write(
|
|
105
|
+
self,
|
|
106
|
+
path: str,
|
|
107
|
+
data: Data,
|
|
108
|
+
*,
|
|
109
|
+
mode: str | None = None,
|
|
110
|
+
append: bool = False,
|
|
111
|
+
chunk_size: int | None = None,
|
|
112
|
+
) -> None:
|
|
113
|
+
"""Write ``data`` to ``path`` (created or replaced; ``append`` adds to it).
|
|
114
|
+
|
|
115
|
+
``bytes`` and ``str`` are sent in one request (retried on a ``503``
|
|
116
|
+
before it is accepted); a file object or an iterable of ``bytes`` is
|
|
117
|
+
streamed and never replayed. ``chunk_size`` splits the upload into
|
|
118
|
+
requests of at most that many bytes, to stay under the policy's
|
|
119
|
+
``maxUploadBytes``. ``mode`` is an octal string such as ``"0755"``.
|
|
120
|
+
"""
|
|
121
|
+
if isinstance(data, str):
|
|
122
|
+
data = data.encode()
|
|
123
|
+
if chunk_size is not None:
|
|
124
|
+
if chunk_size <= 0:
|
|
125
|
+
raise ValueError("chunk_size must be positive")
|
|
126
|
+
first = True
|
|
127
|
+
for chunk in _chunks(data, chunk_size):
|
|
128
|
+
self._put(path, chunk, mode=mode, append=append or not first)
|
|
129
|
+
first = False
|
|
130
|
+
if first: # nothing to send: still create (or truncate) the file
|
|
131
|
+
self._put(path, b"", mode=mode, append=append)
|
|
132
|
+
return
|
|
133
|
+
body: bytes | Iterator[bytes] = (
|
|
134
|
+
data if isinstance(data, bytes) else _stream(data)
|
|
135
|
+
)
|
|
136
|
+
self._put(path, body, mode=mode, append=append)
|
|
137
|
+
|
|
138
|
+
def _put(
|
|
139
|
+
self,
|
|
140
|
+
path: str,
|
|
141
|
+
body: bytes | Iterator[bytes],
|
|
142
|
+
*,
|
|
143
|
+
mode: str | None,
|
|
144
|
+
append: bool,
|
|
145
|
+
) -> None:
|
|
146
|
+
params = {}
|
|
147
|
+
if mode is not None:
|
|
148
|
+
params["mode"] = mode
|
|
149
|
+
if append:
|
|
150
|
+
params["append"] = "true"
|
|
151
|
+
self._t.request(
|
|
152
|
+
"PUT",
|
|
153
|
+
self._url(path),
|
|
154
|
+
scope="files",
|
|
155
|
+
content=body,
|
|
156
|
+
params=params or None,
|
|
157
|
+
headers={"Content-Type": "application/octet-stream"},
|
|
158
|
+
)
|
|
159
|
+
|
|
160
|
+
def list(self, path: str = "") -> list[EntryInfo]:
|
|
161
|
+
"""The entries of a directory, sorted by name."""
|
|
162
|
+
resp = self._t.request(
|
|
163
|
+
"GET", self._url(path), scope="files", params={"type": "directory"}
|
|
164
|
+
)
|
|
165
|
+
listing = resp.json()
|
|
166
|
+
base = self.relative(path)
|
|
167
|
+
return [
|
|
168
|
+
EntryInfo(
|
|
169
|
+
name=e["name"],
|
|
170
|
+
path=posixpath.join(base, e["name"]) if base else e["name"],
|
|
171
|
+
type="directory" if e.get("type") == "directory" else "file",
|
|
172
|
+
size=int(e.get("size", 0)),
|
|
173
|
+
modified_at=str(e.get("modified_at", "")),
|
|
174
|
+
mode=str(e.get("mode", "")),
|
|
175
|
+
)
|
|
176
|
+
for e in listing.get("entries") or ()
|
|
177
|
+
]
|
|
178
|
+
|
|
179
|
+
def exists(self, path: str) -> bool:
|
|
180
|
+
try:
|
|
181
|
+
self._t.request("HEAD", self._url(path), scope="files")
|
|
182
|
+
except errors.SandboxFileNotFound:
|
|
183
|
+
return False
|
|
184
|
+
except errors.GatewayError as e:
|
|
185
|
+
if e.status == 404 and e.code != "sandbox_not_found":
|
|
186
|
+
return False # HEAD answers carry no body, so no code
|
|
187
|
+
raise
|
|
188
|
+
return True
|
|
189
|
+
|
|
190
|
+
def delete(self, path: str) -> None:
|
|
191
|
+
"""Remove a file or an empty directory."""
|
|
192
|
+
if not self.relative(path):
|
|
193
|
+
raise ValueError("refusing to delete the sandbox root")
|
|
194
|
+
self._t.request("DELETE", self._url(path), scope="files")
|
|
195
|
+
|
|
196
|
+
|
|
197
|
+
def _stream(data: IO[bytes] | Iterable[bytes]) -> Iterator[bytes]:
|
|
198
|
+
if hasattr(data, "read"):
|
|
199
|
+
while chunk := data.read(_READ):
|
|
200
|
+
yield chunk
|
|
201
|
+
else:
|
|
202
|
+
yield from data
|
|
203
|
+
|
|
204
|
+
|
|
205
|
+
def _chunks(data: bytes | IO[bytes] | Iterable[bytes], size: int) -> Iterator[bytes]:
|
|
206
|
+
if isinstance(data, bytes):
|
|
207
|
+
for i in range(0, len(data), size):
|
|
208
|
+
yield data[i : i + size]
|
|
209
|
+
return
|
|
210
|
+
buf = b""
|
|
211
|
+
for piece in _stream(data):
|
|
212
|
+
buf += piece
|
|
213
|
+
while len(buf) >= size:
|
|
214
|
+
yield buf[:size]
|
|
215
|
+
buf = buf[size:]
|
|
216
|
+
if buf:
|
|
217
|
+
yield buf
|