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,428 @@
1
+ """An interactive terminal in a sandbox: ``sandbox.terminal()`` (ADR-007-W13).
2
+
3
+ The gateway's WebSocket terminal bridge (ADR-007 §WebSocket terminal bridge):
4
+ ``wss://.../v1/terminal`` with subprotocol ``devzero.terminal.v1``. The SDK
5
+ authenticates with ``Authorization: Bearer`` on the upgrade request, like
6
+ every other request; the ``devzero.bearer.<token>`` subprotocol is for
7
+ browsers, which cannot set headers, and the SDK never uses it. The first
8
+ frame is a text control message ``{"type": "start", "cmd", "cols", "rows",
9
+ "env"}``; then stdin goes up as binary frames, output comes down as binary
10
+ frames, and ``resize`` / ``signal`` are text control messages. The session
11
+ ends with close code ``1000`` and reason ``exit:<code>``; ``1001`` (drain,
12
+ idle or lifetime limit) and ``1011`` (the process stream failed) end it
13
+ without an exit code and raise
14
+ :class:`~devzero_sandbox.errors.StreamInterrupted`. A ``send`` that times
15
+ out after part of its input was queued raises :class:`PartialSendTimeout` with
16
+ the count of bytes accepted, so the caller can resume from that offset.
17
+ """
18
+
19
+ from __future__ import annotations
20
+
21
+ import errno
22
+ import json
23
+ import select
24
+ import socket
25
+ import ssl
26
+ import threading
27
+ import time
28
+ from collections import deque
29
+ from collections.abc import Iterator, Mapping, Sequence
30
+ from types import TracebackType
31
+ from typing import Any, Literal, Self
32
+
33
+ import httpx
34
+ from websockets.exceptions import ConnectionClosed, InvalidStatus
35
+ from websockets.sync.client import ClientConnection, connect
36
+
37
+ from devzero_sandbox import errors
38
+ from devzero_sandbox.redaction import get_logger
39
+ from devzero_sandbox.transport import GatewayTransport
40
+
41
+ _log = get_logger("devzero_sandbox.terminal.ws")
42
+
43
+ SUBPROTOCOL = "devzero.terminal.v1"
44
+ #: Environment the gateway passes through (anything else closes the session 1008).
45
+ ALLOWED_ENV = ("TERM", "LANG", "COLUMNS", "LINES")
46
+ #: How much stdin :meth:`Terminal.send` puts in one WebSocket frame. A ping
47
+ #: waits for at most one such frame to finish writing (see _SerializedTLS).
48
+ SEND_CHUNK_BYTES = 64 * 1024
49
+ #: How much stdin may wait to be written; :meth:`Terminal.send` blocks above it.
50
+ WRITE_BUFFER_BYTES = 1 << 20
51
+
52
+ _PING, _PONG = 0x9, 0xA
53
+
54
+
55
+ class PartialSendTimeout(TimeoutError):
56
+ """:meth:`Terminal.send` timed out after accepting part of its input.
57
+
58
+ ``bytes_sent`` is how many leading bytes of the input were accepted into
59
+ the write queue before the timeout; they will be written, in order, unless
60
+ the session fails. The rest was not sent: resume with
61
+ ``term.send(data[e.bytes_sent:])`` to deliver the input exactly once.
62
+ """
63
+
64
+ def __init__(self, bytes_sent: int, total: int) -> None:
65
+ self.bytes_sent = bytes_sent
66
+ self.total = total
67
+ super().__init__(
68
+ f"timed out waiting to write to the terminal after {bytes_sent} of {total} bytes"
69
+ )
70
+
71
+
72
+ def _is_ping_or_pong(data: bytes) -> bool:
73
+ """A WebSocket ping or pong frame (RFC 6455 5.2: FIN, then the opcode)."""
74
+ return len(data) >= 2 and data[0] & 0x80 != 0 and data[0] & 0x0F in (_PING, _PONG)
75
+
76
+
77
+ class _SerializedTLS:
78
+ """An ``ssl.SSLSocket`` whose TLS reads and writes never run at the same time,
79
+ and whose writes never hold up reads.
80
+
81
+ websockets' sync client reads in its own thread while the caller's thread
82
+ writes, and CPython releases the GIL inside OpenSSL, so both threads can be
83
+ in the same ``SSL`` object at once, which OpenSSL does not support. Right
84
+ after the TLS 1.3 handshake the gateway sends its session tickets; when the
85
+ reader processes them while the caller writes the HTTP upgrade request, the
86
+ write can be lost: ``sendall`` returns, nothing reaches the wire, and the
87
+ gateway gives up on the handshake. So every TLS operation takes one lock,
88
+ and nothing waits while holding it: reads and writes run without blocking,
89
+ and wait for the socket to be readable or writable with the lock released.
90
+
91
+ Writes are also queued for a writer thread. websockets holds its protocol
92
+ lock across ``sendall``, and its reader needs that lock to take in data, so
93
+ a ``sendall`` blocked by backpressure (a large paste the remote echoes back:
94
+ the remote stops reading until we read its output) would stop the reader
95
+ and deadlock the session. Queued, ``sendall`` returns at once and the
96
+ reader keeps draining. The queue is bounded by :meth:`Terminal.send`,
97
+ which waits in :meth:`wait_for_room` before it enters websockets, while
98
+ no lock is held, until the queue is below ``WRITE_BUFFER_BYTES``.
99
+
100
+ There are two lanes. Each ``sendall`` from websockets is one whole frame.
101
+ Pings and pongs go in a priority lane, written before the next queued
102
+ frame, so a keepalive waits for at most the frame being written (one
103
+ ``SEND_CHUNK_BYTES`` chunk of stdin), never for the backlog behind it, and
104
+ is not answered late enough to close the session with 1011. Every other
105
+ frame (stdin, control messages, close) and ``shutdown`` stays in order in
106
+ the other lane; a ping between two data frames is valid WebSocket. A write
107
+ that fails closes the socket and is raised by the next ``send``.
108
+ """
109
+
110
+ def __init__(self, sock: ssl.SSLSocket) -> None:
111
+ self._sock = sock
112
+ self._lock = threading.Lock() # one TLS operation at a time
113
+ self._timeout = sock.gettimeout()
114
+ self._queue: deque[bytes | int] = deque() # frames, or a shutdown(how)
115
+ self._queued_bytes = 0 # in _queue, and the frame being written from it
116
+ self._priority: deque[bytes] = deque() # pings and pongs
117
+ self._queued = threading.Condition()
118
+ self._error: BaseException | None = None
119
+ self._writer: threading.Thread | None = None
120
+
121
+ def recv(self, bufsize: int) -> bytes:
122
+ while True:
123
+ with self._lock:
124
+ self._sock.settimeout(0.0)
125
+ try:
126
+ return self._sock.recv(bufsize)
127
+ except ssl.SSLWantReadError:
128
+ pass
129
+ finally:
130
+ self._sock.settimeout(self._timeout)
131
+ # close() shuts the socket down first, which wakes this wait.
132
+ if self._sock.fileno() == -1:
133
+ return b""
134
+ select.select([self._sock], [], [], 1.0)
135
+
136
+ def sendall(self, data: Any) -> None:
137
+ self._enqueue(bytes(data))
138
+
139
+ def shutdown(self, how: int) -> None:
140
+ self._enqueue(how) # after the writes before it, such as a close frame
141
+
142
+ def wait_for_room(self, limit: int, timeout: float | None) -> None:
143
+ """Wait until fewer than ``limit`` bytes are queued; raise a write failure.
144
+
145
+ Returns early once the socket is closed, so the caller's next
146
+ websockets call reports the closed connection.
147
+ """
148
+ deadline = None if timeout is None else time.monotonic() + timeout
149
+ with self._queued:
150
+ while True:
151
+ if self._error is not None:
152
+ raise self._error
153
+ if self._queued_bytes < limit or self._sock.fileno() == -1:
154
+ return
155
+ wait = 1.0
156
+ if deadline is not None:
157
+ wait = min(wait, deadline - time.monotonic())
158
+ if wait <= 0:
159
+ raise TimeoutError("timed out waiting to write to the terminal")
160
+ self._queued.wait(wait)
161
+
162
+ def _enqueue(self, item: bytes | int) -> None:
163
+ with self._queued:
164
+ if self._error is not None:
165
+ raise self._error
166
+ if isinstance(item, bytes) and _is_ping_or_pong(item):
167
+ self._priority.append(item)
168
+ else:
169
+ self._queue.append(item)
170
+ if isinstance(item, bytes):
171
+ self._queued_bytes += len(item)
172
+ if self._writer is None:
173
+ self._writer = threading.Thread(
174
+ target=self._write_queued, name="dz-terminal-writer", daemon=True
175
+ )
176
+ self._writer.start()
177
+ self._queued.notify()
178
+
179
+ def _write_queued(self) -> None:
180
+ while True:
181
+ with self._queued:
182
+ while not self._queue and not self._priority:
183
+ if self._sock.fileno() == -1:
184
+ return
185
+ self._queued.wait(1.0)
186
+ item = (
187
+ self._priority.popleft()
188
+ if self._priority
189
+ else self._queue.popleft()
190
+ )
191
+ try:
192
+ if isinstance(item, int):
193
+ with self._lock:
194
+ self._sock.shutdown(item)
195
+ else:
196
+ self._write(item)
197
+ except BaseException as e: # noqa: BLE001 -- raised by the next send
198
+ with self._queued:
199
+ self._error = e
200
+ self._queue.clear()
201
+ self._priority.clear()
202
+ self._queued_bytes = 0
203
+ self._queued.notify_all()
204
+ self.close() # the reader sees the connection end
205
+ return
206
+ with self._queued:
207
+ if isinstance(item, bytes) and not _is_ping_or_pong(item):
208
+ self._queued_bytes -= len(item)
209
+ self._queued.notify_all() # Terminal.send may have room again
210
+
211
+ def _write(self, data: bytes) -> None:
212
+ timeout = self._timeout
213
+ deadline = None if timeout is None else time.monotonic() + timeout
214
+ with memoryview(data) as view:
215
+ sent = 0
216
+ while sent < len(view):
217
+ want: tuple[list[Any], list[Any]]
218
+ with self._lock:
219
+ self._sock.settimeout(0.0)
220
+ try:
221
+ # After SSLWantWriteError OpenSSL needs the same buffer
222
+ # again: the next try resends view[sent:] unchanged.
223
+ sent += self._sock.send(view[sent:])
224
+ continue
225
+ except (ssl.SSLWantWriteError, BlockingIOError):
226
+ want = ([], [self._sock])
227
+ except ssl.SSLWantReadError:
228
+ want = ([self._sock], [])
229
+ finally:
230
+ self._sock.settimeout(self._timeout)
231
+ if self._sock.fileno() == -1:
232
+ raise OSError(errno.EBADF, "the terminal socket is closed")
233
+ wait = 1.0
234
+ if deadline is not None:
235
+ wait = min(wait, deadline - time.monotonic())
236
+ if wait <= 0:
237
+ raise TimeoutError("timed out writing to the terminal")
238
+ select.select(*want, [], wait)
239
+
240
+ def settimeout(self, timeout: float | None) -> None:
241
+ with self._lock:
242
+ self._timeout = timeout
243
+ self._sock.settimeout(timeout)
244
+
245
+ def close(self) -> None:
246
+ # Wake a reader waiting in recv(); the kernel call needs no lock.
247
+ try:
248
+ socket.socket.shutdown(self._sock, socket.SHUT_RDWR)
249
+ except OSError:
250
+ pass
251
+ self._sock.close()
252
+ with self._queued:
253
+ self._queued.notify_all() # the writer, and a send waiting for room
254
+
255
+ def fileno(self) -> int:
256
+ return self._sock.fileno()
257
+
258
+ def __getattr__(self, name: str) -> Any:
259
+ return getattr(self._sock, name)
260
+
261
+
262
+ class _Connection(ClientConnection):
263
+ """websockets' client connection over :class:`_SerializedTLS`."""
264
+
265
+ def __init__(self, sock: socket.socket, *args: Any, **kwargs: Any) -> None:
266
+ if isinstance(sock, ssl.SSLSocket):
267
+ sock = _SerializedTLS(sock) # type: ignore[assignment]
268
+ super().__init__(sock, *args, **kwargs)
269
+
270
+
271
+ class Terminal:
272
+ """One terminal session; iterate it for output, :meth:`send` for input."""
273
+
274
+ def __init__(
275
+ self,
276
+ transport: GatewayTransport,
277
+ *,
278
+ cmd: Sequence[str] = ("/bin/bash",),
279
+ cols: int = 120,
280
+ rows: int = 40,
281
+ env: Mapping[str, str] | None = None,
282
+ open_timeout: float = 30.0,
283
+ ) -> None:
284
+ for name in env or {}:
285
+ if name not in ALLOWED_ENV and not name.startswith("LC_"):
286
+ raise ValueError(
287
+ f"{name} is not passed to a terminal (allowed: TERM, LANG, LC_*, COLUMNS, LINES)"
288
+ )
289
+ self.exit_code: int | None = None
290
+ self.close_code: int | None = None
291
+ self.close_reason = ""
292
+ url = transport.endpoint.url("/v1/terminal").replace("https://", "wss://", 1)
293
+ # The upgrade is retried like any request (ADR-010-W11): a retryable
294
+ # 503 (sandbox_not_ready right after create) for 10 s, a 404 for 10 s
295
+ # after ready; nothing has started yet, so a retry cannot run twice.
296
+ first, attempt = transport.now(), 0
297
+ while True:
298
+ try:
299
+ # Entered at once (websockets >= 17.1 warns about a bare
300
+ # connect()); close() leaves it.
301
+ self._ws: ClientConnection = connect(
302
+ url,
303
+ additional_headers=transport.auth_headers("terminal"),
304
+ subprotocols=[SUBPROTOCOL], # type: ignore[list-item]
305
+ ssl=transport.ssl_context(),
306
+ open_timeout=open_timeout,
307
+ max_size=None,
308
+ create_connection=_Connection,
309
+ # websockets logs handshake headers at DEBUG: through the redactor.
310
+ logger=_log,
311
+ ).__enter__()
312
+ break
313
+ except InvalidStatus as e:
314
+ r = e.response
315
+ err = errors.from_response(
316
+ httpx.Response(
317
+ r.status_code,
318
+ content=bytes(r.body or b""),
319
+ headers=dict(r.headers.raw_items()),
320
+ )
321
+ )
322
+ delay = transport.retry_delay(err, attempt, first)
323
+ if delay is None:
324
+ raise transport.surface(err) from None
325
+ _log.debug(
326
+ "retrying the terminal upgrade in %.1fs after %s", delay, err.code
327
+ )
328
+ transport.pause(delay)
329
+ attempt += 1
330
+ start = {
331
+ "type": "start",
332
+ "cmd": list(cmd),
333
+ "cols": cols,
334
+ "rows": rows,
335
+ "env": {"TERM": "xterm-256color", **(env or {})},
336
+ }
337
+ self._ws.send(json.dumps(start))
338
+
339
+ def send(self, data: bytes | str, timeout: float | None = None) -> None:
340
+ """Keystrokes: stdin is always sent as binary frames.
341
+
342
+ Large input goes out in ``SEND_CHUNK_BYTES`` frames, and this blocks
343
+ while ``WRITE_BUFFER_BYTES`` are still waiting to be written (the
344
+ gateway is not keeping up), so memory stays bounded; output keeps
345
+ being read meanwhile. A failed earlier write is raised at once.
346
+
347
+ If ``timeout`` seconds pass without room, raises
348
+ :class:`PartialSendTimeout` (a :class:`TimeoutError`) whose
349
+ ``bytes_sent`` counts the leading bytes already accepted into the
350
+ write queue (``0`` when nothing was); they still go out, so resume
351
+ with ``send(data[e.bytes_sent:])``, never with the whole input again.
352
+ A ``str`` is encoded as UTF-8 first and the count is in those bytes.
353
+ """
354
+ raw = data.encode() if isinstance(data, str) else bytes(data)
355
+ tls = self._ws.socket if isinstance(self._ws.socket, _SerializedTLS) else None
356
+ deadline = None if timeout is None else time.monotonic() + timeout
357
+ for i in range(0, max(len(raw), 1), SEND_CHUNK_BYTES):
358
+ if tls is not None:
359
+ # Before websockets takes its protocol lock: its reader needs
360
+ # that lock, so waiting here never stops output being drained.
361
+ left = (
362
+ None if deadline is None else max(0.0, deadline - time.monotonic())
363
+ )
364
+ try:
365
+ tls.wait_for_room(WRITE_BUFFER_BYTES, left)
366
+ except TimeoutError:
367
+ # Chunks before i are in the write queue; i onward is not.
368
+ raise PartialSendTimeout(i, len(raw)) from None
369
+ self._ws.send(raw[i : i + SEND_CHUNK_BYTES], text=False)
370
+
371
+ def resize(self, cols: int, rows: int) -> None:
372
+ self._ws.send(json.dumps({"type": "resize", "cols": cols, "rows": rows}))
373
+
374
+ def signal(self, signal: Literal["INT", "TERM", "KILL"]) -> None:
375
+ self._ws.send(json.dumps({"type": "signal", "signal": signal}))
376
+
377
+ def recv(self, timeout: float | None = None) -> bytes | None:
378
+ """The next output frame; ``None`` once the process has exited.
379
+
380
+ Raises :class:`TimeoutError` after ``timeout`` seconds without output,
381
+ and :class:`~devzero_sandbox.errors.StreamInterrupted` if the session
382
+ ended without an exit code.
383
+ """
384
+ try:
385
+ frame = self._ws.recv(timeout)
386
+ except ConnectionClosed as e:
387
+ self._closed(e) # raises unless the process exited
388
+ return None
389
+ return frame.encode() if isinstance(frame, str) else frame
390
+
391
+ def __iter__(self) -> Iterator[bytes]:
392
+ while (frame := self.recv()) is not None:
393
+ yield frame
394
+
395
+ def _closed(self, e: ConnectionClosed) -> None:
396
+ rcvd = e.rcvd
397
+ self.close_code = rcvd.code if rcvd is not None else None
398
+ self.close_reason = rcvd.reason if rcvd is not None else ""
399
+ if self.close_code == 1000 and self.close_reason.startswith("exit:"):
400
+ try:
401
+ self.exit_code = int(self.close_reason[5:])
402
+ except ValueError:
403
+ self.exit_code = None
404
+ return
405
+ raise errors.StreamInterrupted(
406
+ pid=None,
407
+ code="drain" if self.close_code == 1001 else f"ws_{self.close_code}",
408
+ message=self.close_reason
409
+ or "the terminal session closed before the process exited",
410
+ )
411
+
412
+ def close(self) -> None:
413
+ """Hang up (the gateway sends EOF, SIGTERM, then SIGKILL after 5 s)."""
414
+ self._ws.close()
415
+
416
+ def __enter__(self) -> Self:
417
+ return self
418
+
419
+ def __exit__(
420
+ self,
421
+ exc_type: type[BaseException] | None,
422
+ exc: BaseException | None,
423
+ tb: TracebackType | None,
424
+ ) -> None:
425
+ self.close()
426
+
427
+ def __repr__(self) -> str:
428
+ return f"Terminal(close_code={self.close_code}, exit_code={self.exit_code})"