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