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,381 @@
|
|
|
1
|
+
"""A minimal Connect protocol client for the control plane (ADR-007-W13).
|
|
2
|
+
|
|
3
|
+
dakr serves ``SandboxService`` with connect-go (ADR-003 §API contract). The
|
|
4
|
+
stub in ``_proto/sandbox/v1/service_connect.py`` is generated from the proto;
|
|
5
|
+
this module is the runtime it calls: the Connect protocol, version 1, with the
|
|
6
|
+
binary protobuf codec, over the httpx client the gateway transport already
|
|
7
|
+
uses, so the SDK takes no second HTTP stack.
|
|
8
|
+
|
|
9
|
+
- Unary: ``POST /<service>/<method>``, ``Content-Type: application/proto``,
|
|
10
|
+
the message as the body; ``200`` carries the response message, anything
|
|
11
|
+
else a JSON error ``{"code", "message", "details": [{"type", "value"}]}``.
|
|
12
|
+
- Server streaming: ``Content-Type: application/connect+proto``; request and
|
|
13
|
+
response messages in 5-byte envelopes (flags, big-endian length); the last
|
|
14
|
+
envelope (flag ``0x02``) is JSON ``{"error"?, "metadata"?}``.
|
|
15
|
+
- Errors become :class:`devzero_sandbox.errors.ControlPlaneError` subclasses
|
|
16
|
+
from the ``sandbox.v1.SandboxError`` detail every dakr error carries.
|
|
17
|
+
- ``Connect-Timeout-Ms`` carries the caller's deadline, so the server stops
|
|
18
|
+
waiting when the caller does.
|
|
19
|
+
- The DevZero credential (``dzu-`` or ``dzs-``) is held as a
|
|
20
|
+
:class:`~devzero_sandbox.auth.BearerToken` and sent only as
|
|
21
|
+
``Authorization: Bearer``; logs and errors go through the redactor.
|
|
22
|
+
|
|
23
|
+
Retries happen only when the caller says the call is safe to repeat
|
|
24
|
+
(``retry=True``: reads, and mutations that carry an idempotency key): a
|
|
25
|
+
failure the server marks ``retryable`` (or a transport error) is retried with
|
|
26
|
+
backoff for up to 10 s. A stream is retried only before its first message.
|
|
27
|
+
"""
|
|
28
|
+
|
|
29
|
+
from __future__ import annotations
|
|
30
|
+
|
|
31
|
+
import base64
|
|
32
|
+
import binascii
|
|
33
|
+
import json
|
|
34
|
+
import struct
|
|
35
|
+
import time
|
|
36
|
+
from collections.abc import Callable, Iterator
|
|
37
|
+
from types import TracebackType
|
|
38
|
+
from typing import Any, Self, TypeVar
|
|
39
|
+
|
|
40
|
+
import httpx
|
|
41
|
+
from google.protobuf.message import DecodeError, Message
|
|
42
|
+
|
|
43
|
+
from devzero_sandbox import __version__, errors
|
|
44
|
+
from devzero_sandbox._proto.sandbox.v1 import error_pb2
|
|
45
|
+
from devzero_sandbox.auth import BearerToken
|
|
46
|
+
from devzero_sandbox.redaction import get_logger, redact
|
|
47
|
+
from devzero_sandbox.transport import RetryPolicy
|
|
48
|
+
|
|
49
|
+
log = get_logger(__name__)
|
|
50
|
+
|
|
51
|
+
M = TypeVar("M", bound=Message)
|
|
52
|
+
|
|
53
|
+
_SANDBOX_ERROR = "sandbox.v1.SandboxError"
|
|
54
|
+
_END_STREAM = 0x02
|
|
55
|
+
_COMPRESSED = 0x01
|
|
56
|
+
|
|
57
|
+
# Connect's mapping for an error response that is not Connect JSON (a proxy's page).
|
|
58
|
+
_HTTP_TO_CONNECT = {
|
|
59
|
+
400: "internal",
|
|
60
|
+
401: "unauthenticated",
|
|
61
|
+
403: "permission_denied",
|
|
62
|
+
404: "unimplemented",
|
|
63
|
+
429: "unavailable",
|
|
64
|
+
502: "unavailable",
|
|
65
|
+
503: "unavailable",
|
|
66
|
+
504: "unavailable",
|
|
67
|
+
}
|
|
68
|
+
|
|
69
|
+
|
|
70
|
+
def _b64decode(value: str) -> bytes:
|
|
71
|
+
# Connect allows padded or unpadded, standard or URL-safe base64.
|
|
72
|
+
value = value.strip()
|
|
73
|
+
alt = b"-_" if ("-" in value or "_" in value) else None
|
|
74
|
+
return base64.b64decode(value + "=" * (-len(value) % 4), altchars=alt)
|
|
75
|
+
|
|
76
|
+
|
|
77
|
+
def _error(
|
|
78
|
+
body: Any, *, fallback_code: str, fallback_message: str
|
|
79
|
+
) -> errors.ControlPlaneError:
|
|
80
|
+
"""A typed error from a Connect error JSON object (or a fallback)."""
|
|
81
|
+
if not isinstance(body, dict) or not isinstance(body.get("code"), str):
|
|
82
|
+
return errors.control_plane_error(
|
|
83
|
+
connect_code=fallback_code, message=fallback_message
|
|
84
|
+
)
|
|
85
|
+
code: str | None = None
|
|
86
|
+
retryable: bool | None = None
|
|
87
|
+
details: dict[str, str] = {}
|
|
88
|
+
for d in body.get("details") or ():
|
|
89
|
+
if not isinstance(d, dict) or d.get("type") != _SANDBOX_ERROR:
|
|
90
|
+
continue
|
|
91
|
+
try:
|
|
92
|
+
se = error_pb2.SandboxError.FromString(_b64decode(str(d.get("value", ""))))
|
|
93
|
+
except (binascii.Error, ValueError, DecodeError):
|
|
94
|
+
continue
|
|
95
|
+
code, retryable, details = se.code or None, se.retryable, dict(se.details)
|
|
96
|
+
break
|
|
97
|
+
return errors.control_plane_error(
|
|
98
|
+
connect_code=body["code"],
|
|
99
|
+
message=str(body.get("message") or ""),
|
|
100
|
+
code=code,
|
|
101
|
+
retryable=retryable,
|
|
102
|
+
details=details,
|
|
103
|
+
)
|
|
104
|
+
|
|
105
|
+
|
|
106
|
+
class _Retry(Exception):
|
|
107
|
+
"""Internal: a failure that may be retried, carrying the error to raise otherwise."""
|
|
108
|
+
|
|
109
|
+
def __init__(self, err: errors.ControlPlaneError) -> None:
|
|
110
|
+
self.err = err
|
|
111
|
+
|
|
112
|
+
|
|
113
|
+
def _transport_failure(
|
|
114
|
+
path: str, e: httpx.TransportError
|
|
115
|
+
) -> errors.ControlPlaneError | _Retry:
|
|
116
|
+
"""The typed error for an httpx failure before an answer: unary and streams alike.
|
|
117
|
+
|
|
118
|
+
A timeout is the call's deadline; any other transport failure (refused,
|
|
119
|
+
reset, TLS) is ``unavailable`` and, wrapped in :class:`_Retry`, retried
|
|
120
|
+
when the caller allows it.
|
|
121
|
+
"""
|
|
122
|
+
if isinstance(e, httpx.TimeoutException):
|
|
123
|
+
return errors.control_plane_error(
|
|
124
|
+
connect_code="deadline_exceeded", message=f"{path}: {type(e).__name__}"
|
|
125
|
+
)
|
|
126
|
+
return _Retry(
|
|
127
|
+
errors.control_plane_error(connect_code="unavailable", message=f"{path}: {e!s}")
|
|
128
|
+
)
|
|
129
|
+
|
|
130
|
+
|
|
131
|
+
class ConnectClient:
|
|
132
|
+
"""Connect calls to one base URL (DevZero's API host) with one credential."""
|
|
133
|
+
|
|
134
|
+
def __init__(
|
|
135
|
+
self,
|
|
136
|
+
base_url: str,
|
|
137
|
+
token: BearerToken | str | None,
|
|
138
|
+
*,
|
|
139
|
+
timeout: float = 60.0,
|
|
140
|
+
http_transport: httpx.BaseTransport | None = None,
|
|
141
|
+
verify: Any = True,
|
|
142
|
+
retry: RetryPolicy | None = None,
|
|
143
|
+
clock: Callable[[], float] = time.monotonic,
|
|
144
|
+
sleep: Callable[[float], None] = time.sleep,
|
|
145
|
+
) -> None:
|
|
146
|
+
if not base_url.startswith("https://") and http_transport is None:
|
|
147
|
+
raise ValueError(
|
|
148
|
+
"the DevZero API URL must be https; the credential is never sent in clear text"
|
|
149
|
+
)
|
|
150
|
+
self.base_url = base_url.rstrip("/")
|
|
151
|
+
self._token = BearerToken(token) if isinstance(token, str) else token
|
|
152
|
+
self._timeout = timeout
|
|
153
|
+
self._retry = retry or RetryPolicy()
|
|
154
|
+
self._clock = clock
|
|
155
|
+
self._sleep = sleep
|
|
156
|
+
self._client = httpx.Client(
|
|
157
|
+
transport=http_transport,
|
|
158
|
+
verify=verify,
|
|
159
|
+
timeout=timeout,
|
|
160
|
+
follow_redirects=False,
|
|
161
|
+
headers={"User-Agent": f"devzero-sandbox-python/{__version__}"},
|
|
162
|
+
)
|
|
163
|
+
|
|
164
|
+
# --- calls -------------------------------------------------------------------
|
|
165
|
+
|
|
166
|
+
def unary(
|
|
167
|
+
self,
|
|
168
|
+
path: str,
|
|
169
|
+
request: Message,
|
|
170
|
+
response_type: type[M],
|
|
171
|
+
*,
|
|
172
|
+
timeout_s: float | None = None,
|
|
173
|
+
retry: bool = False,
|
|
174
|
+
) -> M:
|
|
175
|
+
"""One unary call; raises :class:`~devzero_sandbox.errors.ControlPlaneError`."""
|
|
176
|
+
body = request.SerializeToString()
|
|
177
|
+
|
|
178
|
+
def once() -> M:
|
|
179
|
+
try:
|
|
180
|
+
resp = self._client.post(
|
|
181
|
+
self.base_url + path,
|
|
182
|
+
content=body,
|
|
183
|
+
headers=self._headers("application/proto", timeout_s),
|
|
184
|
+
timeout=self._http_timeout(timeout_s),
|
|
185
|
+
)
|
|
186
|
+
except httpx.TransportError as e:
|
|
187
|
+
raise _transport_failure(path, e) from None
|
|
188
|
+
log.debug("connect %s -> %d", path, resp.status_code)
|
|
189
|
+
if resp.status_code == 200:
|
|
190
|
+
try:
|
|
191
|
+
return response_type.FromString(resp.content)
|
|
192
|
+
except DecodeError:
|
|
193
|
+
raise errors.control_plane_error(
|
|
194
|
+
connect_code="internal", message=f"{path}: undecodable response"
|
|
195
|
+
) from None
|
|
196
|
+
raise self._http_error(resp)
|
|
197
|
+
|
|
198
|
+
return self._with_retries(path, once, retry)
|
|
199
|
+
|
|
200
|
+
def server_stream(
|
|
201
|
+
self,
|
|
202
|
+
path: str,
|
|
203
|
+
request: Message,
|
|
204
|
+
response_type: type[M],
|
|
205
|
+
*,
|
|
206
|
+
timeout_s: float | None = None,
|
|
207
|
+
retry: bool = False,
|
|
208
|
+
) -> Iterator[M]:
|
|
209
|
+
"""A server-streaming call; messages as they arrive, then the end-of-stream error, if any."""
|
|
210
|
+
payload = (
|
|
211
|
+
struct.pack(">BI", 0, request.ByteSize()) + request.SerializeToString()
|
|
212
|
+
)
|
|
213
|
+
started = False
|
|
214
|
+
start = self._clock()
|
|
215
|
+
attempt = 0
|
|
216
|
+
while True:
|
|
217
|
+
try:
|
|
218
|
+
with self._client.stream(
|
|
219
|
+
"POST",
|
|
220
|
+
self.base_url + path,
|
|
221
|
+
content=payload,
|
|
222
|
+
headers=self._headers("application/connect+proto", timeout_s),
|
|
223
|
+
timeout=self._http_timeout(timeout_s),
|
|
224
|
+
) as resp:
|
|
225
|
+
log.debug("connect stream %s -> %d", path, resp.status_code)
|
|
226
|
+
if resp.status_code != 200:
|
|
227
|
+
resp.read()
|
|
228
|
+
err = self._http_error(resp)
|
|
229
|
+
if retry and err.retryable:
|
|
230
|
+
raise _Retry(err)
|
|
231
|
+
raise err
|
|
232
|
+
for msg in self._messages(path, resp, response_type):
|
|
233
|
+
started = True
|
|
234
|
+
yield msg
|
|
235
|
+
return
|
|
236
|
+
except httpx.TransportError as e:
|
|
237
|
+
# Opening the stream (connect, TLS, sending the request) failed: the
|
|
238
|
+
# same typed error, and the same retry decision, as unary().
|
|
239
|
+
failure = _transport_failure(path, e)
|
|
240
|
+
if isinstance(failure, _Retry):
|
|
241
|
+
err = failure.err
|
|
242
|
+
elif failure.retryable:
|
|
243
|
+
err = failure
|
|
244
|
+
else:
|
|
245
|
+
raise failure from None
|
|
246
|
+
except _Retry as r:
|
|
247
|
+
err = r.err
|
|
248
|
+
if started or not retry:
|
|
249
|
+
raise err from None
|
|
250
|
+
delay = self._delay(attempt, start)
|
|
251
|
+
if delay is None:
|
|
252
|
+
raise err from None
|
|
253
|
+
log.debug("retrying %s in %.1fs after %s", path, delay, err.code)
|
|
254
|
+
self._sleep(delay)
|
|
255
|
+
attempt += 1
|
|
256
|
+
|
|
257
|
+
# --- internals ---------------------------------------------------------------
|
|
258
|
+
|
|
259
|
+
def _messages(
|
|
260
|
+
self, path: str, resp: httpx.Response, response_type: type[M]
|
|
261
|
+
) -> Iterator[M]:
|
|
262
|
+
buf = b""
|
|
263
|
+
chunks = resp.iter_bytes()
|
|
264
|
+
while True:
|
|
265
|
+
while len(buf) < 5 or len(buf) < 5 + struct.unpack(">I", buf[1:5])[0]:
|
|
266
|
+
try:
|
|
267
|
+
chunk = next(chunks)
|
|
268
|
+
except StopIteration:
|
|
269
|
+
raise _Retry(
|
|
270
|
+
errors.control_plane_error(
|
|
271
|
+
connect_code="unavailable",
|
|
272
|
+
message=f"{path}: stream ended without its end message",
|
|
273
|
+
)
|
|
274
|
+
) from None
|
|
275
|
+
except httpx.TransportError as e:
|
|
276
|
+
raise _Retry(
|
|
277
|
+
errors.control_plane_error(
|
|
278
|
+
connect_code="unavailable", message=f"{path}: {e!s}"
|
|
279
|
+
)
|
|
280
|
+
) from None
|
|
281
|
+
buf += chunk
|
|
282
|
+
flags = buf[0]
|
|
283
|
+
n = struct.unpack(">I", buf[1:5])[0]
|
|
284
|
+
data, buf = buf[5 : 5 + n], buf[5 + n :]
|
|
285
|
+
if flags & _COMPRESSED:
|
|
286
|
+
raise errors.control_plane_error(
|
|
287
|
+
connect_code="internal",
|
|
288
|
+
message=f"{path}: compressed message without negotiation",
|
|
289
|
+
)
|
|
290
|
+
if flags & _END_STREAM:
|
|
291
|
+
try:
|
|
292
|
+
end = json.loads(data or b"{}")
|
|
293
|
+
except ValueError:
|
|
294
|
+
end = {}
|
|
295
|
+
err = end.get("error") if isinstance(end, dict) else None
|
|
296
|
+
if err:
|
|
297
|
+
raise _error(
|
|
298
|
+
err,
|
|
299
|
+
fallback_code="unknown",
|
|
300
|
+
fallback_message=f"{path}: stream failed",
|
|
301
|
+
)
|
|
302
|
+
return
|
|
303
|
+
try:
|
|
304
|
+
yield response_type.FromString(data)
|
|
305
|
+
except DecodeError:
|
|
306
|
+
raise errors.control_plane_error(
|
|
307
|
+
connect_code="internal", message=f"{path}: undecodable message"
|
|
308
|
+
) from None
|
|
309
|
+
|
|
310
|
+
def _headers(self, content_type: str, timeout_s: float | None) -> dict[str, str]:
|
|
311
|
+
h = {"Content-Type": content_type, "Connect-Protocol-Version": "1"}
|
|
312
|
+
if timeout_s is not None:
|
|
313
|
+
h["Connect-Timeout-Ms"] = str(max(1, int(timeout_s * 1000)))
|
|
314
|
+
if self._token is not None:
|
|
315
|
+
h["Authorization"] = f"Bearer {self._token.reveal()}"
|
|
316
|
+
return h
|
|
317
|
+
|
|
318
|
+
def _http_timeout(self, timeout_s: float | None) -> httpx.Timeout:
|
|
319
|
+
# The server ends the call at its deadline; give the answer time to arrive.
|
|
320
|
+
read = self._timeout if timeout_s is None else timeout_s + 10.0
|
|
321
|
+
return httpx.Timeout(self._timeout, read=read)
|
|
322
|
+
|
|
323
|
+
def _http_error(self, resp: httpx.Response) -> errors.ControlPlaneError:
|
|
324
|
+
try:
|
|
325
|
+
body = json.loads(resp.content)
|
|
326
|
+
except ValueError:
|
|
327
|
+
body = None
|
|
328
|
+
return _error(
|
|
329
|
+
body,
|
|
330
|
+
fallback_code=_HTTP_TO_CONNECT.get(resp.status_code, "unknown"),
|
|
331
|
+
fallback_message=redact(resp.text[:300])
|
|
332
|
+
if resp.content
|
|
333
|
+
else resp.reason_phrase,
|
|
334
|
+
)
|
|
335
|
+
|
|
336
|
+
def _with_retries(self, path: str, once: Callable[[], M], retry: bool) -> M:
|
|
337
|
+
start = self._clock()
|
|
338
|
+
attempt = 0
|
|
339
|
+
while True:
|
|
340
|
+
try:
|
|
341
|
+
return once()
|
|
342
|
+
except _Retry as r:
|
|
343
|
+
err = r.err
|
|
344
|
+
except errors.ControlPlaneError as e:
|
|
345
|
+
if not e.retryable:
|
|
346
|
+
raise
|
|
347
|
+
err = e
|
|
348
|
+
delay = self._delay(attempt, start) if retry else None
|
|
349
|
+
if delay is None:
|
|
350
|
+
raise err
|
|
351
|
+
log.debug("retrying %s in %.1fs after %s", path, delay, err.code)
|
|
352
|
+
self._sleep(delay)
|
|
353
|
+
attempt += 1
|
|
354
|
+
|
|
355
|
+
def _delay(self, attempt: int, start: float) -> float | None:
|
|
356
|
+
remaining = start + self._retry.window_s - self._clock()
|
|
357
|
+
if remaining <= 0:
|
|
358
|
+
return None
|
|
359
|
+
backoff: float = min(
|
|
360
|
+
self._retry.initial_backoff_s * 2.0**attempt, self._retry.max_backoff_s
|
|
361
|
+
)
|
|
362
|
+
return min(backoff, remaining)
|
|
363
|
+
|
|
364
|
+
# --- lifecycle -----------------------------------------------------------------
|
|
365
|
+
|
|
366
|
+
def close(self) -> None:
|
|
367
|
+
self._client.close()
|
|
368
|
+
|
|
369
|
+
def __enter__(self) -> Self:
|
|
370
|
+
return self
|
|
371
|
+
|
|
372
|
+
def __exit__(
|
|
373
|
+
self,
|
|
374
|
+
exc_type: type[BaseException] | None,
|
|
375
|
+
exc: BaseException | None,
|
|
376
|
+
tb: TracebackType | None,
|
|
377
|
+
) -> None:
|
|
378
|
+
self.close()
|
|
379
|
+
|
|
380
|
+
def __repr__(self) -> str:
|
|
381
|
+
return f"ConnectClient({self.base_url!r}, token={self._token!r})"
|