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