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,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})"