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,546 @@
|
|
|
1
|
+
"""Authenticated HTTP transport to one sandbox through the gateway (ADR-005-W11).
|
|
2
|
+
|
|
3
|
+
This is the layer the Phase 1 client (ADR-007-W13) builds files, exec, SSE and
|
|
4
|
+
the terminal on. It owns:
|
|
5
|
+
|
|
6
|
+
- the sandbox's base URL on either route: ``https://<host>/t/<team>/s/<id>``
|
|
7
|
+
(the ``connect.url`` DevZero returns) or, in-cluster,
|
|
8
|
+
``https://devzero-sandbox-gateway.devzero-system.svc/p/<policy>/s/<id>``;
|
|
9
|
+
- the bearer: ``Authorization: Bearer <token>`` on every request, chosen per
|
|
10
|
+
request scope from :mod:`devzero_sandbox.auth` credentials, never in the URL,
|
|
11
|
+
a cookie or the WebSocket subprotocol (that carrier is for browsers);
|
|
12
|
+
- TLS trust: the in-cluster CA bundle, or a caller's bundle for a BYO gateway,
|
|
13
|
+
re-read when the file changes; verification cannot be turned off here;
|
|
14
|
+
- retries: ``503`` answers the gateway marks retryable (``Retry-After`` honoured,
|
|
15
|
+
otherwise backoff) for up to 10 s, and ``404 sandbox_not_found`` for 10 s
|
|
16
|
+
after :meth:`GatewayTransport.mark_ready` (the informer-lag window of
|
|
17
|
+
ADR-007 §Request pipeline step 4); one retry after a ``401`` when the
|
|
18
|
+
credentials have another token to offer;
|
|
19
|
+
- a gone sandbox (``409 sandbox_terminating`` / ``410 sandbox_expired``):
|
|
20
|
+
never retried, and handed to :attr:`GatewayTransport.on_gone` before it is
|
|
21
|
+
raised, so the owner can say why it went (ADR-010-W11).
|
|
22
|
+
"""
|
|
23
|
+
|
|
24
|
+
from __future__ import annotations
|
|
25
|
+
|
|
26
|
+
import os
|
|
27
|
+
import re
|
|
28
|
+
import ssl
|
|
29
|
+
import threading
|
|
30
|
+
import time
|
|
31
|
+
from collections.abc import Callable, Collection, Iterator, Mapping
|
|
32
|
+
from contextlib import contextmanager
|
|
33
|
+
from dataclasses import dataclass
|
|
34
|
+
from types import TracebackType
|
|
35
|
+
from typing import Any, Literal, Self
|
|
36
|
+
from urllib.parse import urlsplit
|
|
37
|
+
|
|
38
|
+
import httpx
|
|
39
|
+
|
|
40
|
+
from devzero_sandbox import errors
|
|
41
|
+
from devzero_sandbox.auth import (
|
|
42
|
+
BearerToken,
|
|
43
|
+
Credentials,
|
|
44
|
+
ProjectedTokenCredentials,
|
|
45
|
+
SandboxToken,
|
|
46
|
+
Scope,
|
|
47
|
+
TokenCredentials,
|
|
48
|
+
)
|
|
49
|
+
from devzero_sandbox.incluster import (
|
|
50
|
+
IN_CLUSTER_CA_PATH,
|
|
51
|
+
IN_CLUSTER_GATEWAY_URL,
|
|
52
|
+
IN_CLUSTER_TOKEN_PATH,
|
|
53
|
+
in_cluster_ssl_context,
|
|
54
|
+
)
|
|
55
|
+
from devzero_sandbox.redaction import get_logger
|
|
56
|
+
|
|
57
|
+
log = get_logger(__name__)
|
|
58
|
+
|
|
59
|
+
# ADR-007 §URL scheme grammar.
|
|
60
|
+
_ID = re.compile(r"sb[a-z0-9]{10}")
|
|
61
|
+
_TEAM = re.compile(r"[a-z0-9]([a-z0-9-]{0,22}[a-z0-9])?")
|
|
62
|
+
_POLICY = re.compile(r"[a-z0-9]([a-z0-9-]{0,38}[a-z0-9])?")
|
|
63
|
+
_PATH = re.compile(r"/v1(/[^?#]*)?")
|
|
64
|
+
|
|
65
|
+
|
|
66
|
+
@dataclass(frozen=True)
|
|
67
|
+
class SandboxEndpoint:
|
|
68
|
+
"""One sandbox's base URL at the gateway.
|
|
69
|
+
|
|
70
|
+
``route`` is ``"t"`` (external; ``scope_key`` is the team slug) or ``"p"``
|
|
71
|
+
(in-cluster; ``scope_key`` is the policy name).
|
|
72
|
+
"""
|
|
73
|
+
|
|
74
|
+
origin: str
|
|
75
|
+
route: Literal["t", "p"]
|
|
76
|
+
scope_key: str
|
|
77
|
+
sandbox_id: str
|
|
78
|
+
|
|
79
|
+
@classmethod
|
|
80
|
+
def external(cls, connect_url: str) -> SandboxEndpoint:
|
|
81
|
+
"""Parse ``connect.url`` (``https://<host>/t/<team>/s/<id>``)."""
|
|
82
|
+
u = urlsplit(connect_url)
|
|
83
|
+
parts = u.path.rstrip("/").split("/")
|
|
84
|
+
if u.scheme != "https":
|
|
85
|
+
raise ValueError(
|
|
86
|
+
"the gateway URL must be https; a bearer is never sent in clear text"
|
|
87
|
+
)
|
|
88
|
+
if u.username is not None or u.password is not None or u.query or u.fragment:
|
|
89
|
+
raise ValueError(
|
|
90
|
+
"the gateway URL must not carry credentials, a query or a fragment"
|
|
91
|
+
)
|
|
92
|
+
if len(parts) != 5 or parts[0] != "" or parts[1] != "t" or parts[3] != "s":
|
|
93
|
+
raise ValueError(
|
|
94
|
+
"expected a sandbox URL of the form https://<host>/t/<team>/s/<id>"
|
|
95
|
+
)
|
|
96
|
+
_check(_TEAM, parts[2], "team slug")
|
|
97
|
+
_check(_ID, parts[4], "sandbox id")
|
|
98
|
+
return cls(f"https://{u.netloc}", "t", parts[2], parts[4])
|
|
99
|
+
|
|
100
|
+
@classmethod
|
|
101
|
+
def in_cluster(
|
|
102
|
+
cls, policy: str, sandbox_id: str, gateway_url: str = IN_CLUSTER_GATEWAY_URL
|
|
103
|
+
) -> SandboxEndpoint:
|
|
104
|
+
u = urlsplit(gateway_url)
|
|
105
|
+
if u.scheme != "https" or u.path not in ("", "/") or u.username or u.query:
|
|
106
|
+
raise ValueError("the in-cluster gateway URL must be https://<host>[:port]")
|
|
107
|
+
_check(_POLICY, policy, "policy name")
|
|
108
|
+
_check(_ID, sandbox_id, "sandbox id")
|
|
109
|
+
return cls(f"https://{u.netloc}", "p", policy, sandbox_id)
|
|
110
|
+
|
|
111
|
+
@property
|
|
112
|
+
def base_url(self) -> str:
|
|
113
|
+
return f"{self.origin}/{self.route}/{self.scope_key}/s/{self.sandbox_id}"
|
|
114
|
+
|
|
115
|
+
def url(self, path: str) -> str:
|
|
116
|
+
"""The absolute URL of a gateway path such as ``/v1/exec`` for this sandbox."""
|
|
117
|
+
if not _PATH.fullmatch(path) or any(
|
|
118
|
+
seg in (".", "..") for seg in path.split("/")
|
|
119
|
+
):
|
|
120
|
+
raise ValueError(f"not a sandbox API path: {path!r}")
|
|
121
|
+
return self.base_url + path
|
|
122
|
+
|
|
123
|
+
|
|
124
|
+
def _check(pattern: re.Pattern[str], value: str, what: str) -> None:
|
|
125
|
+
if not pattern.fullmatch(value):
|
|
126
|
+
raise ValueError(f"invalid {what} {value!r}")
|
|
127
|
+
|
|
128
|
+
|
|
129
|
+
@dataclass(frozen=True)
|
|
130
|
+
class RetryPolicy:
|
|
131
|
+
"""How long the transport keeps trying before surfacing a gateway error.
|
|
132
|
+
|
|
133
|
+
``window_s`` bounds both retries of retryable answers (from the first
|
|
134
|
+
attempt of a request) and retries of ``404 sandbox_not_found`` (from
|
|
135
|
+
:meth:`GatewayTransport.mark_ready`); ADR-007 sets both at 10 s.
|
|
136
|
+
"""
|
|
137
|
+
|
|
138
|
+
window_s: float = 10.0
|
|
139
|
+
initial_backoff_s: float = 0.5
|
|
140
|
+
max_backoff_s: float = 4.0
|
|
141
|
+
|
|
142
|
+
|
|
143
|
+
class GatewayTransport:
|
|
144
|
+
"""Sends authenticated requests to one sandbox; see the module docstring."""
|
|
145
|
+
|
|
146
|
+
def __init__(
|
|
147
|
+
self,
|
|
148
|
+
endpoint: SandboxEndpoint,
|
|
149
|
+
credentials: Credentials,
|
|
150
|
+
*,
|
|
151
|
+
ca_bundle: str | None = None,
|
|
152
|
+
retry: RetryPolicy | None = None,
|
|
153
|
+
timeout: float | httpx.Timeout = 60.0,
|
|
154
|
+
http_transport: httpx.BaseTransport | None = None,
|
|
155
|
+
clock: Callable[[], float] = time.monotonic,
|
|
156
|
+
sleep: Callable[[float], None] = time.sleep,
|
|
157
|
+
) -> None:
|
|
158
|
+
if credentials.route != endpoint.route:
|
|
159
|
+
raise ValueError(
|
|
160
|
+
f"credentials for the /{credentials.route}/ route cannot be used on the "
|
|
161
|
+
f"/{endpoint.route}/ route (the gateway answers 401 wrong_auth_for_route)"
|
|
162
|
+
)
|
|
163
|
+
self.endpoint = endpoint
|
|
164
|
+
self.credentials = credentials
|
|
165
|
+
self._in_cluster = endpoint.route == "p"
|
|
166
|
+
# In-cluster, the operator's CA bundle is the only trust there is.
|
|
167
|
+
self._ca_bundle = (
|
|
168
|
+
IN_CLUSTER_CA_PATH if self._in_cluster and ca_bundle is None else ca_bundle
|
|
169
|
+
)
|
|
170
|
+
self._retry = retry or RetryPolicy()
|
|
171
|
+
self._timeout = timeout
|
|
172
|
+
self._http_transport = http_transport
|
|
173
|
+
self._clock = clock
|
|
174
|
+
self._sleep = sleep
|
|
175
|
+
self._lock = threading.Lock()
|
|
176
|
+
#: Called with a :class:`~devzero_sandbox.errors.SandboxGone` before it is
|
|
177
|
+
#: raised; :class:`~devzero_sandbox.sandbox.Sandbox` asks DevZero for the reason.
|
|
178
|
+
self.on_gone: Callable[[errors.SandboxGone], None] | None = None
|
|
179
|
+
self._ready_at: float | None = None
|
|
180
|
+
self._ca_key: tuple[int, int, int] | None = None
|
|
181
|
+
self._ssl: ssl.SSLContext | None = None
|
|
182
|
+
self._client: httpx.Client | None = None
|
|
183
|
+
# Requests and open streams per client, and clients a CA rotation
|
|
184
|
+
# replaced: a retired client is closed only once nothing uses it, so a
|
|
185
|
+
# rotation never cuts an open SSE stream or another thread's request.
|
|
186
|
+
self._users: dict[httpx.Client, int] = {}
|
|
187
|
+
self._retired: set[httpx.Client] = set()
|
|
188
|
+
self._ensure_client() # fail now, not on the first request, if the bundle is missing
|
|
189
|
+
|
|
190
|
+
@classmethod
|
|
191
|
+
def external(
|
|
192
|
+
cls,
|
|
193
|
+
connect_url: str,
|
|
194
|
+
token: TokenCredentials | SandboxToken | str,
|
|
195
|
+
*,
|
|
196
|
+
ca_bundle: str | None = None,
|
|
197
|
+
**kwargs: Any,
|
|
198
|
+
) -> GatewayTransport:
|
|
199
|
+
"""A transport for ``connect.url`` with sandbox JWT(s).
|
|
200
|
+
|
|
201
|
+
``ca_bundle`` is a PEM file for a gateway whose certificate a private
|
|
202
|
+
CA issued (a BYO endpoint); it replaces the default trust store, as
|
|
203
|
+
``curl --cacert`` does. Without it, public CAs are trusted.
|
|
204
|
+
"""
|
|
205
|
+
creds = (
|
|
206
|
+
token if isinstance(token, TokenCredentials) else TokenCredentials(token)
|
|
207
|
+
)
|
|
208
|
+
return cls(
|
|
209
|
+
SandboxEndpoint.external(connect_url), creds, ca_bundle=ca_bundle, **kwargs
|
|
210
|
+
)
|
|
211
|
+
|
|
212
|
+
@classmethod
|
|
213
|
+
def in_cluster(
|
|
214
|
+
cls,
|
|
215
|
+
policy: str,
|
|
216
|
+
sandbox_id: str,
|
|
217
|
+
*,
|
|
218
|
+
gateway_url: str = IN_CLUSTER_GATEWAY_URL,
|
|
219
|
+
token_path: str = IN_CLUSTER_TOKEN_PATH,
|
|
220
|
+
ca_path: str = IN_CLUSTER_CA_PATH,
|
|
221
|
+
**kwargs: Any,
|
|
222
|
+
) -> GatewayTransport:
|
|
223
|
+
"""A transport for a pod in the cluster: SA token and CA from ``/var/run/dz-sandbox``.
|
|
224
|
+
|
|
225
|
+
No DevZero credential is needed. The CA bundle is required: there is
|
|
226
|
+
no fallback to the system trust store or to an unverified connection.
|
|
227
|
+
"""
|
|
228
|
+
return cls(
|
|
229
|
+
SandboxEndpoint.in_cluster(policy, sandbox_id, gateway_url),
|
|
230
|
+
ProjectedTokenCredentials(token_path),
|
|
231
|
+
ca_bundle=ca_path,
|
|
232
|
+
**kwargs,
|
|
233
|
+
)
|
|
234
|
+
|
|
235
|
+
# --- TLS -------------------------------------------------------------------
|
|
236
|
+
|
|
237
|
+
def _build_ssl(self) -> ssl.SSLContext:
|
|
238
|
+
if self._in_cluster and self._ca_bundle is not None:
|
|
239
|
+
return in_cluster_ssl_context(self._ca_bundle)
|
|
240
|
+
if self._ca_bundle is not None:
|
|
241
|
+
ctx = ssl.create_default_context(
|
|
242
|
+
ssl.Purpose.SERVER_AUTH, cafile=self._ca_bundle
|
|
243
|
+
)
|
|
244
|
+
else:
|
|
245
|
+
ctx = httpx.create_ssl_context()
|
|
246
|
+
ctx.minimum_version = ssl.TLSVersion.TLSv1_2
|
|
247
|
+
return ctx
|
|
248
|
+
|
|
249
|
+
def _ensure_client(self) -> httpx.Client:
|
|
250
|
+
"""The HTTP client, rebuilt when the CA bundle file has changed."""
|
|
251
|
+
with self._lock:
|
|
252
|
+
return self._current_client_locked()
|
|
253
|
+
|
|
254
|
+
def _current_client_locked(self) -> httpx.Client:
|
|
255
|
+
""":meth:`_ensure_client` with ``self._lock`` held.
|
|
256
|
+
|
|
257
|
+
The client a rotation replaces is retired, not closed, while requests
|
|
258
|
+
or streams still use it; :meth:`_release` closes it after the last one.
|
|
259
|
+
"""
|
|
260
|
+
key = None
|
|
261
|
+
if self._ca_bundle is not None:
|
|
262
|
+
try:
|
|
263
|
+
st = os.stat(self._ca_bundle)
|
|
264
|
+
key = (st.st_ino, st.st_size, st.st_mtime_ns)
|
|
265
|
+
except FileNotFoundError:
|
|
266
|
+
key = None # _build_ssl raises the typed error
|
|
267
|
+
if self._client is None or key != self._ca_key:
|
|
268
|
+
ctx = self._build_ssl()
|
|
269
|
+
old, self._client = (
|
|
270
|
+
self._client,
|
|
271
|
+
httpx.Client(
|
|
272
|
+
verify=ctx,
|
|
273
|
+
transport=self._http_transport,
|
|
274
|
+
follow_redirects=False,
|
|
275
|
+
timeout=self._timeout,
|
|
276
|
+
),
|
|
277
|
+
)
|
|
278
|
+
self._ssl, self._ca_key = ctx, key
|
|
279
|
+
if old is not None:
|
|
280
|
+
log.debug(
|
|
281
|
+
"CA bundle %s changed; rebuilt the TLS context", self._ca_bundle
|
|
282
|
+
)
|
|
283
|
+
if self._users.get(old, 0) > 0:
|
|
284
|
+
self._retired.add(old)
|
|
285
|
+
else:
|
|
286
|
+
old.close()
|
|
287
|
+
return self._client
|
|
288
|
+
|
|
289
|
+
def _acquire(self) -> httpx.Client:
|
|
290
|
+
"""The current client, counted as in use until :meth:`_release`."""
|
|
291
|
+
with self._lock:
|
|
292
|
+
client = self._current_client_locked()
|
|
293
|
+
self._users[client] = self._users.get(client, 0) + 1
|
|
294
|
+
return client
|
|
295
|
+
|
|
296
|
+
def _release(self, client: httpx.Client) -> None:
|
|
297
|
+
with self._lock:
|
|
298
|
+
n = self._users.get(client, 0) - 1
|
|
299
|
+
if n > 0:
|
|
300
|
+
self._users[client] = n
|
|
301
|
+
return
|
|
302
|
+
self._users.pop(client, None)
|
|
303
|
+
if client in self._retired:
|
|
304
|
+
self._retired.discard(client)
|
|
305
|
+
client.close()
|
|
306
|
+
|
|
307
|
+
def ssl_context(self) -> ssl.SSLContext | None:
|
|
308
|
+
"""The current TLS context, for a WebSocket client (the terminal)."""
|
|
309
|
+
self._ensure_client()
|
|
310
|
+
return self._ssl
|
|
311
|
+
|
|
312
|
+
# --- requests --------------------------------------------------------------
|
|
313
|
+
|
|
314
|
+
def mark_ready(self) -> None:
|
|
315
|
+
"""Start the 10 s window in which ``404 sandbox_not_found`` is retried.
|
|
316
|
+
|
|
317
|
+
``sandboxes.create`` calls it when the control plane reports ``ready``:
|
|
318
|
+
the gateway's routing index may lag that by a few seconds.
|
|
319
|
+
"""
|
|
320
|
+
self._ready_at = self._clock()
|
|
321
|
+
|
|
322
|
+
def auth_headers(self, scope: Scope) -> dict[str, str]:
|
|
323
|
+
"""The headers that authenticate a request of ``scope`` (for a WebSocket upgrade)."""
|
|
324
|
+
bearer = self.credentials.bearer_for(scope, self.endpoint.sandbox_id)
|
|
325
|
+
return {"Authorization": f"Bearer {bearer.reveal()}"}
|
|
326
|
+
|
|
327
|
+
def request(
|
|
328
|
+
self,
|
|
329
|
+
method: str,
|
|
330
|
+
path: str,
|
|
331
|
+
*,
|
|
332
|
+
scope: Scope,
|
|
333
|
+
json: Any = None,
|
|
334
|
+
content: bytes | Iterator[bytes] | None = None,
|
|
335
|
+
params: Mapping[str, str] | None = None,
|
|
336
|
+
headers: Mapping[str, str] | None = None,
|
|
337
|
+
timeout: float | httpx.Timeout | None = None,
|
|
338
|
+
retry_codes: Collection[str] | None = None,
|
|
339
|
+
) -> httpx.Response:
|
|
340
|
+
"""Send a request and return the read ``2xx`` response; raise :class:`GatewayError` otherwise.
|
|
341
|
+
|
|
342
|
+
``timeout`` overrides the transport's for this request. ``retry_codes``,
|
|
343
|
+
when given, limits the retried answers to those codes (a command must
|
|
344
|
+
not run twice: exec retries only codes that mean it never started).
|
|
345
|
+
"""
|
|
346
|
+
resp, client = self._send(
|
|
347
|
+
method,
|
|
348
|
+
path,
|
|
349
|
+
scope,
|
|
350
|
+
json,
|
|
351
|
+
content,
|
|
352
|
+
params,
|
|
353
|
+
headers,
|
|
354
|
+
stream=False,
|
|
355
|
+
timeout=timeout,
|
|
356
|
+
retry_codes=retry_codes,
|
|
357
|
+
)
|
|
358
|
+
self._release(client)
|
|
359
|
+
return resp
|
|
360
|
+
|
|
361
|
+
@contextmanager
|
|
362
|
+
def stream(
|
|
363
|
+
self,
|
|
364
|
+
method: str,
|
|
365
|
+
path: str,
|
|
366
|
+
*,
|
|
367
|
+
scope: Scope,
|
|
368
|
+
json: Any = None,
|
|
369
|
+
content: bytes | Iterator[bytes] | None = None,
|
|
370
|
+
params: Mapping[str, str] | None = None,
|
|
371
|
+
headers: Mapping[str, str] | None = None,
|
|
372
|
+
timeout: float | httpx.Timeout | None = None,
|
|
373
|
+
retry_codes: Collection[str] | None = None,
|
|
374
|
+
) -> Iterator[httpx.Response]:
|
|
375
|
+
"""Like :meth:`request`, but yields the ``2xx`` response unread (SSE, downloads).
|
|
376
|
+
|
|
377
|
+
Retries happen only before a ``2xx`` arrives; once streaming, an
|
|
378
|
+
interruption is the caller's to handle (ADR-007-W13).
|
|
379
|
+
"""
|
|
380
|
+
resp, client = self._send(
|
|
381
|
+
method,
|
|
382
|
+
path,
|
|
383
|
+
scope,
|
|
384
|
+
json,
|
|
385
|
+
content,
|
|
386
|
+
params,
|
|
387
|
+
headers,
|
|
388
|
+
stream=True,
|
|
389
|
+
timeout=timeout,
|
|
390
|
+
retry_codes=retry_codes,
|
|
391
|
+
)
|
|
392
|
+
try:
|
|
393
|
+
yield resp
|
|
394
|
+
finally:
|
|
395
|
+
try:
|
|
396
|
+
resp.close()
|
|
397
|
+
finally:
|
|
398
|
+
self._release(client)
|
|
399
|
+
|
|
400
|
+
def _send(
|
|
401
|
+
self,
|
|
402
|
+
method: str,
|
|
403
|
+
path: str,
|
|
404
|
+
scope: Scope,
|
|
405
|
+
json: Any,
|
|
406
|
+
content: bytes | Iterator[bytes] | None,
|
|
407
|
+
params: Mapping[str, str] | None,
|
|
408
|
+
headers: Mapping[str, str] | None,
|
|
409
|
+
*,
|
|
410
|
+
stream: bool,
|
|
411
|
+
timeout: float | httpx.Timeout | None = None,
|
|
412
|
+
retry_codes: Collection[str] | None = None,
|
|
413
|
+
) -> tuple[httpx.Response, httpx.Client]:
|
|
414
|
+
"""Send with retries; the returned client stays acquired for the caller to release."""
|
|
415
|
+
url = self.endpoint.url(path)
|
|
416
|
+
replayable = content is None or isinstance(content, bytes)
|
|
417
|
+
extra = {
|
|
418
|
+
k: v for k, v in (headers or {}).items() if k.lower() != "authorization"
|
|
419
|
+
}
|
|
420
|
+
start = self._clock()
|
|
421
|
+
attempt = 0
|
|
422
|
+
reauthed = False
|
|
423
|
+
while True:
|
|
424
|
+
bearer: BearerToken = self.credentials.bearer_for(
|
|
425
|
+
scope, self.endpoint.sandbox_id
|
|
426
|
+
)
|
|
427
|
+
client = self._acquire()
|
|
428
|
+
try:
|
|
429
|
+
req = client.build_request(
|
|
430
|
+
method,
|
|
431
|
+
url,
|
|
432
|
+
json=json,
|
|
433
|
+
content=content,
|
|
434
|
+
params=params,
|
|
435
|
+
headers={**extra, "Authorization": f"Bearer {bearer.reveal()}"},
|
|
436
|
+
timeout=self._timeout if timeout is None else timeout,
|
|
437
|
+
)
|
|
438
|
+
resp = client.send(req, stream=stream)
|
|
439
|
+
if resp.is_success:
|
|
440
|
+
return resp, client
|
|
441
|
+
try:
|
|
442
|
+
resp.read()
|
|
443
|
+
finally:
|
|
444
|
+
resp.close()
|
|
445
|
+
except BaseException:
|
|
446
|
+
self._release(client)
|
|
447
|
+
raise
|
|
448
|
+
self._release(client)
|
|
449
|
+
err = errors.from_response(resp)
|
|
450
|
+
log.debug(
|
|
451
|
+
"gateway %s %s -> %d %s (attempt %d)",
|
|
452
|
+
method,
|
|
453
|
+
path,
|
|
454
|
+
err.status,
|
|
455
|
+
err.code,
|
|
456
|
+
attempt + 1,
|
|
457
|
+
)
|
|
458
|
+
if (
|
|
459
|
+
isinstance(err, errors.AuthError)
|
|
460
|
+
and not reauthed
|
|
461
|
+
and replayable
|
|
462
|
+
and self.credentials.on_rejected(
|
|
463
|
+
bearer, err.code, scope, self.endpoint.sandbox_id
|
|
464
|
+
)
|
|
465
|
+
):
|
|
466
|
+
reauthed = True
|
|
467
|
+
log.debug("retrying %s %s with a fresh credential", method, path)
|
|
468
|
+
continue
|
|
469
|
+
limited = retry_codes is not None and err.code not in retry_codes
|
|
470
|
+
delay = (
|
|
471
|
+
self._retry_delay(err, attempt, start)
|
|
472
|
+
if replayable and not limited
|
|
473
|
+
else None
|
|
474
|
+
)
|
|
475
|
+
if delay is None:
|
|
476
|
+
raise self.surface(err)
|
|
477
|
+
log.debug("retrying %s %s in %.1fs after %s", method, path, delay, err.code)
|
|
478
|
+
self._sleep(delay)
|
|
479
|
+
attempt += 1
|
|
480
|
+
|
|
481
|
+
def surface(self, err: errors.GatewayError) -> errors.GatewayError:
|
|
482
|
+
"""The error to raise for a final refusal: a gone sandbox goes through :attr:`on_gone` first."""
|
|
483
|
+
if isinstance(err, errors.SandboxGone) and self.on_gone is not None:
|
|
484
|
+
self.on_gone(err)
|
|
485
|
+
return err
|
|
486
|
+
|
|
487
|
+
def now(self) -> float:
|
|
488
|
+
"""The transport's monotonic clock (the start of a retry window)."""
|
|
489
|
+
return self._clock()
|
|
490
|
+
|
|
491
|
+
def retry_delay(
|
|
492
|
+
self, err: errors.GatewayError, attempt: int, start: float
|
|
493
|
+
) -> float | None:
|
|
494
|
+
"""How long to wait before attempt ``attempt + 1`` of a request first sent at
|
|
495
|
+
``start`` (``None``: surface ``err``). The rules :meth:`request` follows,
|
|
496
|
+
for a client that sends outside it (the terminal's WebSocket upgrade)."""
|
|
497
|
+
return self._retry_delay(err, attempt, start)
|
|
498
|
+
|
|
499
|
+
def pause(self, seconds: float) -> None:
|
|
500
|
+
self._sleep(seconds)
|
|
501
|
+
|
|
502
|
+
def _retry_delay(
|
|
503
|
+
self, err: errors.GatewayError, attempt: int, start: float
|
|
504
|
+
) -> float | None:
|
|
505
|
+
now = self._clock()
|
|
506
|
+
if isinstance(err, errors.SandboxNotFound):
|
|
507
|
+
if self._ready_at is None:
|
|
508
|
+
return None
|
|
509
|
+
deadline = self._ready_at + self._retry.window_s
|
|
510
|
+
elif err.retryable and err.status in (429, 503):
|
|
511
|
+
deadline = start + self._retry.window_s
|
|
512
|
+
else:
|
|
513
|
+
return None
|
|
514
|
+
if now >= deadline:
|
|
515
|
+
return None
|
|
516
|
+
backoff = min(
|
|
517
|
+
self._retry.initial_backoff_s * 2**attempt, self._retry.max_backoff_s
|
|
518
|
+
)
|
|
519
|
+
delay = err.retry_after_s if err.retry_after_s is not None else backoff
|
|
520
|
+
return min(delay, deadline - now)
|
|
521
|
+
|
|
522
|
+
# --- lifecycle -------------------------------------------------------------
|
|
523
|
+
|
|
524
|
+
def close(self) -> None:
|
|
525
|
+
"""Close the current client and every retired one, open streams included."""
|
|
526
|
+
with self._lock:
|
|
527
|
+
for client in (*self._retired, self._client):
|
|
528
|
+
if client is not None:
|
|
529
|
+
client.close()
|
|
530
|
+
self._client = None
|
|
531
|
+
self._retired.clear()
|
|
532
|
+
self._users.clear()
|
|
533
|
+
|
|
534
|
+
def __enter__(self) -> Self:
|
|
535
|
+
return self
|
|
536
|
+
|
|
537
|
+
def __exit__(
|
|
538
|
+
self,
|
|
539
|
+
exc_type: type[BaseException] | None,
|
|
540
|
+
exc: BaseException | None,
|
|
541
|
+
tb: TracebackType | None,
|
|
542
|
+
) -> None:
|
|
543
|
+
self.close()
|
|
544
|
+
|
|
545
|
+
def __repr__(self) -> str:
|
|
546
|
+
return f"GatewayTransport({self.endpoint.base_url!r}, credentials={self.credentials!r})"
|
|
@@ -0,0 +1,113 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: devzero-sandbox
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: DevZero self-hosted sandboxes SDK (control plane + data plane clients) and MCP server
|
|
5
|
+
License-Expression: Apache-2.0
|
|
6
|
+
License-File: LICENSE
|
|
7
|
+
Requires-Python: >=3.11
|
|
8
|
+
Requires-Dist: googleapis-common-protos>=1.63
|
|
9
|
+
Requires-Dist: httpx-sse>=0.4
|
|
10
|
+
Requires-Dist: httpx>=0.27
|
|
11
|
+
Requires-Dist: protobuf>=5.29.3
|
|
12
|
+
Requires-Dist: pydantic>=2
|
|
13
|
+
Requires-Dist: websockets>=13
|
|
14
|
+
Provides-Extra: mcp
|
|
15
|
+
Requires-Dist: mcp<3,>=2.3; extra == 'mcp'
|
|
16
|
+
Description-Content-Type: text/markdown
|
|
17
|
+
|
|
18
|
+
# devzero-sandbox
|
|
19
|
+
|
|
20
|
+
The Python SDK and MCP server for DevZero self-hosted sandboxes: isolated Linux containers that
|
|
21
|
+
run in your own Kubernetes cluster, created through DevZero. Python 3.11+, Apache-2.0.
|
|
22
|
+
|
|
23
|
+
```bash
|
|
24
|
+
pip install devzero-sandbox # the SDK
|
|
25
|
+
pip install 'devzero-sandbox[mcp]' # the SDK and the sandbox-mcp server
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
## A script
|
|
29
|
+
|
|
30
|
+
Set `DEVZERO_TOKEN` to a DevZero personal access token (`dzu-...`) or team service-account token
|
|
31
|
+
(`dzs-...`) of a Developer on the cluster's team. `DEVZERO_DAKR_URL` points at a DevZero API
|
|
32
|
+
other than the default.
|
|
33
|
+
|
|
34
|
+
```python
|
|
35
|
+
from devzero_sandbox import Client
|
|
36
|
+
|
|
37
|
+
client = Client() # DEVZERO_TOKEN, DEVZERO_DAKR_URL
|
|
38
|
+
sbx = client.sandboxes.create("default", cluster_id="<cluster id>") # waits until ready
|
|
39
|
+
|
|
40
|
+
result = sbx.commands.run("echo hello")
|
|
41
|
+
print(result.exit_code, result.stdout_text)
|
|
42
|
+
|
|
43
|
+
sbx.files.write("data.bin", b"\x00\x01 any bytes")
|
|
44
|
+
assert sbx.files.read("data.bin") == b"\x00\x01 any bytes"
|
|
45
|
+
|
|
46
|
+
sbx.delete()
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
`cluster_id` is needed only when the policy name exists on more than one cluster;
|
|
50
|
+
`client.policies()` lists the policies you can use. When the cluster's gateway endpoint serves a
|
|
51
|
+
certificate from a private CA (a bring-your-own endpoint), pass it:
|
|
52
|
+
`Client(gateway_options={"ca_bundle": "/path/to/ca.crt"})`.
|
|
53
|
+
|
|
54
|
+
The same calls run against preproduction in `make real-cp-run`
|
|
55
|
+
(`operators/sandbox-operator/hack/lib/real_cp_sdk.py script`).
|
|
56
|
+
|
|
57
|
+
More: `sbx.commands.run(cmd, background=True)` returns a `Process` you can `attach` to again from
|
|
58
|
+
any process, `sbx.terminal()` opens an interactive terminal, `sbx.extend(ttl)` keeps the sandbox
|
|
59
|
+
longer, `sbx.tokens.mint(scope=[...])` / `.revoke(jti)` manage its tokens. Every failure is a
|
|
60
|
+
typed exception from `devzero_sandbox.errors`.
|
|
61
|
+
|
|
62
|
+
## In the cluster
|
|
63
|
+
|
|
64
|
+
A pod in the cluster reaches a sandbox without a DevZero credential, with its ServiceAccount, when
|
|
65
|
+
the sandbox's policy lists that ServiceAccount in `access.serviceAccounts`. Mount a projected token
|
|
66
|
+
for the gateway's audience and the CA bundle the sandbox operator publishes into the pod's
|
|
67
|
+
namespace:
|
|
68
|
+
|
|
69
|
+
```yaml
|
|
70
|
+
volumes:
|
|
71
|
+
- name: dz-sandbox
|
|
72
|
+
projected:
|
|
73
|
+
sources:
|
|
74
|
+
- serviceAccountToken: { audience: sandbox-gateway.devzero.io, expirationSeconds: 3600, path: token }
|
|
75
|
+
- configMap: { name: devzero-sandbox-ca, items: [{ key: ca.crt, path: ca.crt }] }
|
|
76
|
+
# containers[].volumeMounts: [{ name: dz-sandbox, mountPath: /var/run/dz-sandbox, readOnly: true }]
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
```python
|
|
80
|
+
from devzero_sandbox import Sandbox
|
|
81
|
+
|
|
82
|
+
# reads /var/run/dz-sandbox/{token,ca.crt}
|
|
83
|
+
sbx = Sandbox.in_cluster("<policy>", "<sandbox id>")
|
|
84
|
+
print(sbx.commands.run("echo hello").stdout_text)
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
The sandbox id is the `sandbox.devzero.io/sandbox-id` label of the `SandboxClaim` the pod's
|
|
88
|
+
ServiceAccount created in the policy's namespace.
|
|
89
|
+
|
|
90
|
+
## MCP server
|
|
91
|
+
|
|
92
|
+
`sandbox-mcp` is a stdio MCP server with seven tools: `create_sandbox`, `run_command`,
|
|
93
|
+
`read_file`, `write_file`, `list_files`, `upload` and `delete_sandbox`. Sandboxes a session created
|
|
94
|
+
are deleted when it ends, and it writes nothing to disk. It is configured from its environment only:
|
|
95
|
+
|
|
96
|
+
```json
|
|
97
|
+
{
|
|
98
|
+
"mcpServers": {
|
|
99
|
+
"devzero-sandbox": {
|
|
100
|
+
"command": "sandbox-mcp",
|
|
101
|
+
"env": {
|
|
102
|
+
"DEVZERO_TOKEN": "dzu-...",
|
|
103
|
+
"DEVZERO_SANDBOX_POLICY": "default",
|
|
104
|
+
"DEVZERO_SANDBOX_CLUSTER_ID": "<cluster id>"
|
|
105
|
+
}
|
|
106
|
+
}
|
|
107
|
+
}
|
|
108
|
+
}
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
The other variables (`DEVZERO_SANDBOX_CA_BUNDLE`, `DEVZERO_SANDBOX_MCP_UPLOAD_ROOT`, which turns
|
|
112
|
+
`upload` on, and the output and timeout limits) are listed by `sandbox-mcp --help` and in
|
|
113
|
+
`devzero_sandbox/mcp/config.py`.
|
|
@@ -0,0 +1,31 @@
|
|
|
1
|
+
devzero_sandbox/__init__.py,sha256=CKV9xMet69EPrRMGfPPWaqvlJ_ArexAxv-v_t5biyvE,1274
|
|
2
|
+
devzero_sandbox/_bgscript.py,sha256=ekRfpHmC5gWZyINp0iBC2uVzQx_hq7kcDBpJMz12KwE,4049
|
|
3
|
+
devzero_sandbox/auth.py,sha256=YicFQjtjqRg6xU5pNk5qCib5-6VG4po69yvIWeNZTmM,13464
|
|
4
|
+
devzero_sandbox/commands.py,sha256=5H_5pUU-qV-_9qcPnxderuXUE1f7HSAzhfwlFcsz1U0,30497
|
|
5
|
+
devzero_sandbox/connect.py,sha256=QfvrnRoNuhtDDdKa1RT32ZNXN1wjSNufDekYhI60ZwY,14417
|
|
6
|
+
devzero_sandbox/errors.py,sha256=DyWWOKsuR0Y3nyB2zMVC9qwNaZtZ5qIhsKXZCTezCMI,16182
|
|
7
|
+
devzero_sandbox/files.py,sha256=WZ-nfKK35c-behb_2P095JAvffAbqleLUEkcgdpvDZg,7428
|
|
8
|
+
devzero_sandbox/incluster.py,sha256=FWxK4jfnwgZc1i0lh3IvKdo-eDSWaIkIPBNtv0Lpq4s,1887
|
|
9
|
+
devzero_sandbox/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
|
|
10
|
+
devzero_sandbox/redaction.py,sha256=qo3rzvyjty2V5FcpaMonMifz8ny8C3KsMlGAsEK6-2g,3135
|
|
11
|
+
devzero_sandbox/sandbox.py,sha256=JDcHFnxF_nFxq_J1cmsAoZt6dbjsfmuUWKKL83gIH8U,24414
|
|
12
|
+
devzero_sandbox/terminal.py,sha256=k4hIAksbEZy5HmG7bCi_XwUEZX00lZa6EVBaKTIkXZY,18561
|
|
13
|
+
devzero_sandbox/transport.py,sha256=nOHA7-91ydnlQGVZsjlq7r667DhWx66dcmYkIjhRYwo,20195
|
|
14
|
+
devzero_sandbox/_proto/__init__.py,sha256=B_0Yscb1i6s4ngKwiLVwqv4nRbmLkVvcekMU2Zf2sT0,83
|
|
15
|
+
devzero_sandbox/_proto/sandbox/__init__.py,sha256=B_0Yscb1i6s4ngKwiLVwqv4nRbmLkVvcekMU2Zf2sT0,83
|
|
16
|
+
devzero_sandbox/_proto/sandbox/v1/__init__.py,sha256=B_0Yscb1i6s4ngKwiLVwqv4nRbmLkVvcekMU2Zf2sT0,83
|
|
17
|
+
devzero_sandbox/_proto/sandbox/v1/error_pb2.py,sha256=U9KDALHsN52UV0vZnA7K9SzgwukwAp9-9RxzKZGbfGI,1870
|
|
18
|
+
devzero_sandbox/_proto/sandbox/v1/error_pb2.pyi,sha256=hWlsOK45CV-NwRi7Tjbdj5mL05NLixOmBedEDTpw4gA,1007
|
|
19
|
+
devzero_sandbox/_proto/sandbox/v1/service_connect.py,sha256=po-GelHcOOVsSgqSgU8dSH7G-ddCr4hw_lwkAcWH0O0,13689
|
|
20
|
+
devzero_sandbox/_proto/sandbox/v1/service_pb2.py,sha256=GapxUFCbDWFAJliSKSkVAX501zB-Ww2Elqz4u8WV74U,35962
|
|
21
|
+
devzero_sandbox/_proto/sandbox/v1/service_pb2.pyi,sha256=FJcgWuLawDwFiuhdftzqRYksMn8uPRsAR0JONBbCDTI,44325
|
|
22
|
+
devzero_sandbox/mcp/__init__.py,sha256=utia6nvwodwb-BRFNqr_ft3RwucQkO89Ef0iPD1v1SE,1620
|
|
23
|
+
devzero_sandbox/mcp/__main__.py,sha256=lqV2oQ0wprUO6xB2dwItAKA5LGzCDQqYLikAGECokjw,150
|
|
24
|
+
devzero_sandbox/mcp/config.py,sha256=rUq3Hu15rKmbnjAx2UijxvbiXxjedubiFYSuqrWd20E,5885
|
|
25
|
+
devzero_sandbox/mcp/server.py,sha256=o7cqeO2HQcrGxRt70Jk25OQe1kfprDdu8y2m_s5RqtY,9955
|
|
26
|
+
devzero_sandbox/mcp/tools.py,sha256=CyPgx5bovuIZ6BBs5Y46NKYPJSoLIyzr_MKe7E27F8I,41061
|
|
27
|
+
devzero_sandbox-0.1.0.dist-info/METADATA,sha256=kVePtvp8xENbOfDO95LL4lHplONfn1ooVWhNiA7yH1k,4085
|
|
28
|
+
devzero_sandbox-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
|
|
29
|
+
devzero_sandbox-0.1.0.dist-info/entry_points.txt,sha256=BkN5_ocEfktR18IXfbK_6YMZ_wH5CG6KCGDCdJZPu6k,57
|
|
30
|
+
devzero_sandbox-0.1.0.dist-info/licenses/LICENSE,sha256=mxc313jymA4pAKMY0xHPXlvEyadngzmQsm16LrAsW68,11344
|
|
31
|
+
devzero_sandbox-0.1.0.dist-info/RECORD,,
|