impulse-compute 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,943 @@
1
+ """The async client and its helpers.
2
+
3
+ The sync client (_client_sync) is made from this one by scripts/unasync.py: edit this file, then run it.
4
+ """
5
+
6
+ from __future__ import annotations
7
+
8
+ import codecs
9
+ import json
10
+ import time
11
+ from datetime import datetime
12
+ from typing import Any, AsyncIterator, Callable, Dict, List, Mapping, Optional, Sequence, Union, cast
13
+
14
+ import httpx
15
+
16
+ from . import _core
17
+ from ._core import Body, Duration
18
+ from ._errors import (
19
+ CommandExitError,
20
+ ComputeConnectionError,
21
+ ComputeError,
22
+ DisconnectedError,
23
+ OperationFailedError,
24
+ OperationTimeoutError,
25
+ status_of,
26
+ )
27
+ from ._generated import (
28
+ AsyncApi,
29
+ CreateTemplateRequest,
30
+ Environment,
31
+ ExecCreate,
32
+ ExecSession,
33
+ Operation,
34
+ SandboxActAs,
35
+ SandboxBindingRef,
36
+ SandboxCreate,
37
+ SandboxCreateActAs,
38
+ SandboxGrant,
39
+ Template,
40
+ )
41
+ from ._generated import Sandbox as SandboxInfo
42
+ from ._models import CommandEvent, CommandResult, FileInfo, Listing, Preview
43
+ from ._sse import EventParser
44
+ from ._support_async import Flag, Lock, alongside, file_chunks, sleep
45
+ from ._transport_async import AsyncTransport
46
+
47
+ #: A command: a string runs under /bin/sh -c, a list as it is.
48
+ Command = Union[str, Sequence[str]]
49
+
50
+
51
+ class AsyncCompute:
52
+ """The ImpulseCompute client."""
53
+
54
+ def __init__(
55
+ self,
56
+ *,
57
+ api_key: Optional[str] = None,
58
+ base_url: Optional[str] = None,
59
+ timeout: float = _core.DEFAULT_TIMEOUT,
60
+ max_retries: int = _core.DEFAULT_MAX_RETRIES,
61
+ http_client: Optional[httpx.AsyncClient] = None,
62
+ headers: Optional[Mapping[str, str]] = None,
63
+ ) -> None:
64
+ """
65
+ :param api_key: the API key (``COMPUTE_API_KEY`` when not given).
66
+ :param base_url: the API's base URL (``COMPUTE_API_URL`` when not given, else the public API).
67
+ :param timeout: how long a call waits for its answer, in seconds.
68
+ :param max_retries: how many times a call that failed for a passing reason is tried again.
69
+ :param http_client: an httpx client to use in place of the SDK's own.
70
+ :param headers: headers sent with every call.
71
+ """
72
+ self._transport = AsyncTransport(
73
+ api_key=api_key, base_url=base_url, timeout=timeout, max_retries=max_retries, http_client=http_client, headers=headers
74
+ )
75
+ #: One method per API operation, for what the helpers do not cover.
76
+ self.api = AsyncApi(self._transport)
77
+ self.operations = AsyncOperations(self.api)
78
+ self.sandboxes = AsyncSandboxes(self.api, self._transport)
79
+ self.templates = AsyncTemplates(self.api, self.operations)
80
+
81
+ async def environment(self, *, request_timeout: Optional[float] = None) -> Environment:
82
+ """The environment the API key belongs to: its plan, limits and egress addresses."""
83
+ return await self.api.get_environment(timeout=request_timeout)
84
+
85
+ async def aclose(self) -> None:
86
+ """Closes the client's connections (a client given as http_client is the caller's to close)."""
87
+ await self._transport.aclose()
88
+
89
+ async def __aenter__(self) -> AsyncCompute:
90
+ return self
91
+
92
+ async def __aexit__(self, *exc: object) -> None:
93
+ await self.aclose()
94
+
95
+
96
+ class AsyncOperations:
97
+ """Operations: the work an asynchronous call started."""
98
+
99
+ def __init__(self, api: AsyncApi) -> None:
100
+ self._api = api
101
+
102
+ async def get(self, id: str, *, request_timeout: Optional[float] = None) -> Operation:
103
+ return await self._api.get_operation(id, timeout=request_timeout)
104
+
105
+ async def wait(self, operation: Union[Operation, str], *, timeout: float = 600.0) -> Operation:
106
+ """Waits for an operation to end: its last state when it succeeded, OperationFailedError when it failed.
107
+
108
+ :param timeout: how long to wait, in seconds (OperationTimeoutError past it).
109
+ """
110
+ began = time.monotonic()
111
+ op = await self.get(operation) if isinstance(operation, str) else operation
112
+ interval = 0.5
113
+ while not op["terminal"]:
114
+ left = timeout - (time.monotonic() - began)
115
+ if left <= 0:
116
+ raise OperationTimeoutError(op, timeout)
117
+ await sleep(min(interval, left))
118
+ interval = min(interval * 1.5, 5.0)
119
+ op = await self.get(op["id"])
120
+ if op["state"] == "failed":
121
+ raise OperationFailedError(op)
122
+ return op
123
+
124
+
125
+ class AsyncTemplates:
126
+ """Templates: what sandboxes are made from."""
127
+
128
+ def __init__(self, api: AsyncApi, operations: AsyncOperations) -> None:
129
+ self._api = api
130
+ self._operations = operations
131
+
132
+ async def list(self, *, request_timeout: Optional[float] = None) -> List[Template]:
133
+ """The built-in templates and yours."""
134
+ return (await self._api.list_templates(timeout=request_timeout))["items"]
135
+
136
+ async def get(self, ref: str, *, request_timeout: Optional[float] = None) -> Template:
137
+ return await self._api.get_template(ref, timeout=request_timeout)
138
+
139
+ async def delete(self, ref: str, *, request_timeout: Optional[float] = None) -> None:
140
+ await self._api.delete_template(ref, timeout=request_timeout)
141
+
142
+ async def build(
143
+ self,
144
+ name: str,
145
+ *,
146
+ upload: Optional[str] = None,
147
+ dockerfile_path: Optional[str] = None,
148
+ root: Optional[str] = None,
149
+ image: Optional[str] = None,
150
+ registry_secret: Optional[str] = None,
151
+ user: Optional[str] = None,
152
+ description: Optional[str] = None,
153
+ timeout: float = 1800.0,
154
+ idempotency_key: Optional[str] = None,
155
+ request_timeout: Optional[float] = None,
156
+ ) -> Template:
157
+ """Builds a template from an upload or an image, and waits for it: OperationFailedError when the build fails.
158
+
159
+ A name the environment has rebuilds that template, which serves creates as it was until the new one is built.
160
+
161
+ :param upload: an upload's ID: a packed source tree, built with its Dockerfile.
162
+ :param dockerfile_path: the Dockerfile's path in the upload (default: Dockerfile).
163
+ :param root: the directory within the upload to build from (default: its top).
164
+ :param image: an OCI image (linux/amd64) to build from instead: ``name:tag`` or ``name@sha256:…``.
165
+ :param registry_secret: one of the environment's secrets holding ``username:password`` to pull the image with.
166
+ :param user: the user a sandbox's commands and files act as by default (default: root).
167
+ :param timeout: how long to wait for the build, in seconds.
168
+ """
169
+ if (upload is None) == (image is None):
170
+ raise TypeError("a template is built from an upload or an image: one of them")
171
+ source: Dict[str, Any] = (
172
+ _without_none({"upload": upload, "dockerfile_path": dockerfile_path, "root": root})
173
+ if upload is not None
174
+ else _without_none({"image": image, "registry_secret": registry_secret})
175
+ )
176
+ body = cast(CreateTemplateRequest, _without_none({"name": name, "source": source, "user": user, "description": description}))
177
+ op = await self._api.create_template(body, idempotency_key=idempotency_key, timeout=request_timeout)
178
+ await self._operations.wait(op, timeout=timeout)
179
+ return await self.get(name, request_timeout=request_timeout)
180
+
181
+
182
+ class AsyncSandboxes:
183
+ """An environment's sandboxes."""
184
+
185
+ def __init__(self, api: AsyncApi, transport: AsyncTransport) -> None:
186
+ self._api = api
187
+ self._transport = transport
188
+
189
+ async def create(
190
+ self,
191
+ *,
192
+ template: Optional[str] = None,
193
+ name: Optional[str] = None,
194
+ ttl: Optional[Duration] = None,
195
+ idle_suspend: Union[Duration, None, bool] = None,
196
+ vcpu: Optional[float] = None,
197
+ memory_mb: Optional[int] = None,
198
+ env: Optional[Mapping[str, str]] = None,
199
+ secrets: Optional[List[str]] = None,
200
+ firewall_policy: Optional[str] = None,
201
+ labels: Optional[Mapping[str, str]] = None,
202
+ grant: Optional[SandboxBindingRef] = None,
203
+ act_as: Optional[SandboxCreateActAs] = None,
204
+ idempotency_key: Optional[str] = None,
205
+ request_timeout: Optional[float] = None,
206
+ ) -> AsyncSandbox:
207
+ """Creates a sandbox from a template (restored from its snapshot, not booted): ready when this returns.
208
+
209
+ :param template: a built-in template (base, node or deno) or one of yours (default: base).
210
+ :param name: its name, unique in the environment: lowercase letters, digits and hyphens.
211
+ :param ttl: how long it lives: ``"30m"``, seconds, or a timedelta.
212
+ :param idle_suspend: how long it may sit idle before it is suspended (``"10m"`` by default); False never
213
+ suspends it.
214
+ :param secrets: names of the environment's secrets to give it.
215
+ :param firewall_policy: the firewall policy its traffic out follows: one of the environment's, or open, none or
216
+ allowlist. Default: allowlist, which is empty: a sandbox made without a policy reaches no network at all.
217
+ :param grant: a scoped sandbox's grant, a prefix of one of the environment's per-workload storage bindings:
218
+ ``{"binding": "agent-data", "prefix": "runs/1/"}``, read-only unless ``"access": "read_write"``. The
219
+ sandbox holds no standing key: its host serves it keys of that scope alone, an hour each, which the AWS
220
+ SDKs fetch and refresh themselves; its firewall policy reaches the binding's Objects server by name. Needs
221
+ a key with compute:manage as well as compute:sandbox.
222
+ :param act_as: act as one of an Impulse Auth service's users: ``{"auth_binding": "users",
223
+ "user_access_token": token}``, the token the service issued the user (the user's own, ending at least a
224
+ minute from now, within the hour and no later than the sandbox). Its host serves the token at
225
+ IMPULSE_ACT_AS_TOKEN_URI to a request carrying IMPULSE_ACT_AS_AUTHORIZATION. The token is the user's
226
+ whole credential: anything in the sandbox can read it.
227
+ :param idempotency_key: makes the create happen once, however often it is sent with this key.
228
+ """
229
+ if idle_suspend is True:
230
+ raise TypeError("idle_suspend is a duration, or False to never suspend")
231
+ body: Dict[str, Any] = _without_none(
232
+ {
233
+ "template": template,
234
+ "name": name,
235
+ "ttl": _core.duration(ttl),
236
+ "vcpu": vcpu,
237
+ "memory_mb": memory_mb,
238
+ "env": dict(env) if env is not None else None,
239
+ "secrets": secrets,
240
+ "firewall_policy": firewall_policy,
241
+ "labels": dict(labels) if labels is not None else None,
242
+ "bindings": [dict(grant)] if grant is not None else None,
243
+ "act_as": dict(act_as) if act_as is not None else None,
244
+ }
245
+ )
246
+ if idle_suspend is False:
247
+ body["idle_suspend"] = None
248
+ elif idle_suspend is not None:
249
+ body["idle_suspend"] = _core.duration(idle_suspend)
250
+ info = await self._api.create_sandbox(cast(SandboxCreate, body), idempotency_key=idempotency_key, timeout=request_timeout)
251
+ return AsyncSandbox(self._api, self._transport, info)
252
+
253
+ async def get(self, ref: str, *, request_timeout: Optional[float] = None) -> AsyncSandbox:
254
+ """A sandbox, by its ID or name."""
255
+ return AsyncSandbox(self._api, self._transport, await self._api.get_sandbox(ref, timeout=request_timeout))
256
+
257
+ async def list(
258
+ self, *, label: Optional[str] = None, page_size: Optional[int] = None, request_timeout: Optional[float] = None
259
+ ) -> AsyncIterator[AsyncSandbox]:
260
+ """Every sandbox (with label, those labelled ``key=value``), page by page as they are read."""
261
+ cursor: Optional[str] = None
262
+ while True:
263
+ page = await self._api.list_sandboxes(cursor=cursor, limit=page_size, label=label, timeout=request_timeout)
264
+ for info in page["items"]:
265
+ yield AsyncSandbox(self._api, self._transport, info)
266
+ cursor = page["next_cursor"]
267
+ if not cursor:
268
+ return
269
+
270
+
271
+ class AsyncSandbox:
272
+ """A sandbox: a microVM of its own, with commands, files and ports."""
273
+
274
+ def __init__(self, api: AsyncApi, transport: AsyncTransport, info: SandboxInfo) -> None:
275
+ self._api = api
276
+ #: The sandbox as the API last showed it.
277
+ self.info = info
278
+ self.commands = AsyncCommands(api, transport, info["id"])
279
+ self.files = AsyncFiles(api, transport, info["id"])
280
+ self.ports = AsyncPorts(api, info["id"])
281
+
282
+ def __repr__(self) -> str:
283
+ return f"<Sandbox {self.id} {self.name!r} {self.state}>"
284
+
285
+ @property
286
+ def id(self) -> str:
287
+ return self.info["id"]
288
+
289
+ @property
290
+ def name(self) -> str:
291
+ return self.info["name"]
292
+
293
+ @property
294
+ def template(self) -> str:
295
+ return self.info["template"]
296
+
297
+ @property
298
+ def state(self) -> str:
299
+ return self.info["state"]
300
+
301
+ @property
302
+ def labels(self) -> Dict[str, str]:
303
+ return dict(self.info.get("labels") or {})
304
+
305
+ @property
306
+ def expires_at(self) -> datetime:
307
+ return _core.parse_time(self.info["expires_at"])
308
+
309
+ @property
310
+ def created_at(self) -> datetime:
311
+ return _core.parse_time(self.info["created_at"])
312
+
313
+ @property
314
+ def grant(self) -> Optional[SandboxGrant]:
315
+ """Its grant as its VM booted with it (None for a sandbox made without one)."""
316
+ grants = self.info.get("bindings") or []
317
+ return grants[0] if grants else None
318
+
319
+ @property
320
+ def act_as(self) -> Optional[SandboxActAs]:
321
+ """What it acts as, never the token (None for a sandbox made without act_as)."""
322
+ return self.info.get("act_as")
323
+
324
+ async def replace_act_as(
325
+ self,
326
+ user_access_token: str,
327
+ *,
328
+ auth_binding: Optional[str] = None,
329
+ idempotency_key: Optional[str] = None,
330
+ request_timeout: Optional[float] = None,
331
+ ) -> AsyncSandbox:
332
+ """Gives a sandbox made with act_as another access token for the same user, checked as at its create; its host
333
+ serves it in place of the one before within seconds (a copy of that one a process made stays valid until it
334
+ ends).
335
+
336
+ :param auth_binding: the auth binding the sandbox acts through. Default: the one it was made with.
337
+ """
338
+ acting = self.info.get("act_as")
339
+ binding = auth_binding or (acting["auth_binding"] if acting else None)
340
+ if not binding:
341
+ raise TypeError("this sandbox was made without act_as: what a sandbox acts as is fixed when it is made")
342
+ self.info = await self._api.replace_sandbox_act_as(
343
+ self.id,
344
+ {"auth_binding": binding, "user_access_token": user_access_token},
345
+ idempotency_key=idempotency_key,
346
+ timeout=request_timeout,
347
+ )
348
+ return self
349
+
350
+ async def drop_act_as(self, *, idempotency_key: Optional[str] = None, request_timeout: Optional[float] = None) -> AsyncSandbox:
351
+ """Stops serving its act_as token; replace_act_as can give it one again. A copy a process made stays valid until
352
+ it ends."""
353
+ self.info = await self._api.drop_sandbox_act_as(self.id, idempotency_key=idempotency_key, timeout=request_timeout)
354
+ return self
355
+
356
+ async def refresh(self, *, request_timeout: Optional[float] = None) -> AsyncSandbox:
357
+ """Reads the sandbox's state again."""
358
+ self.info = await self._api.get_sandbox(self.id, timeout=request_timeout)
359
+ return self
360
+
361
+ async def suspend(self, *, request_timeout: Optional[float] = None) -> AsyncSandbox:
362
+ """Suspends it: its memory and disk are saved and its memory released, kept until it expires."""
363
+ self.info = await self._api.suspend_sandbox(self.id, timeout=request_timeout)
364
+ return self
365
+
366
+ async def resume(self, *, request_timeout: Optional[float] = None) -> AsyncSandbox:
367
+ """Resumes it as it was."""
368
+ self.info = await self._api.resume_sandbox(self.id, timeout=request_timeout)
369
+ return self
370
+
371
+ async def extend(self, ttl: Duration, *, request_timeout: Optional[float] = None) -> AsyncSandbox:
372
+ """Makes it expire ttl from now (``"1h"``, seconds, or a timedelta), within its plan's longest life."""
373
+ self.info = await self._api.extend_sandbox(self.id, {"ttl": cast(str, _core.duration(ttl))}, timeout=request_timeout)
374
+ return self
375
+
376
+ async def destroy(self, *, request_timeout: Optional[float] = None) -> None:
377
+ """Destroys it, and everything in it."""
378
+ await self._api.destroy_sandbox(self.id, timeout=request_timeout)
379
+
380
+
381
+ class AsyncCommands:
382
+ """Commands run in one sandbox."""
383
+
384
+ def __init__(self, api: AsyncApi, transport: AsyncTransport, sandbox: str) -> None:
385
+ self._api = api
386
+ self._transport = transport
387
+ self._sandbox = sandbox
388
+
389
+ async def run(
390
+ self,
391
+ cmd: Command,
392
+ *,
393
+ cwd: Optional[str] = None,
394
+ env: Optional[Mapping[str, str]] = None,
395
+ user: Optional[str] = None,
396
+ timeout: Optional[float] = None,
397
+ stdin: Union[str, bytes, None] = None,
398
+ on_stdout: Optional[Callable[[str], None]] = None,
399
+ on_stderr: Optional[Callable[[str], None]] = None,
400
+ check: bool = False,
401
+ request_timeout: Optional[float] = None,
402
+ ) -> CommandResult:
403
+ """Runs a command to its end.
404
+
405
+ Without callbacks or input it is one call that waits; with them, the command's output is read as it comes. A
406
+ non-zero exit is the result's to say, unless check asks for CommandExitError.
407
+
408
+ :param cmd: a string runs under ``/bin/sh -c``, a list as it is.
409
+ :param cwd: the working directory: absolute, or relative to the user's home (the default).
410
+ :param user: a user of the sandbox, by name or ID (the sandbox's own when absent).
411
+ :param timeout: how long the command may run, in seconds, before it is killed (default: 300).
412
+ :param stdin: written to the command's standard input, which is then closed.
413
+ :param on_stdout: called with each piece of standard output (a terminal's output too), as it arrives.
414
+ :param on_stderr: called with each piece of standard error, as it arrives.
415
+ """
416
+ seconds = _core.timeout_seconds(timeout)
417
+ result: CommandResult
418
+ if on_stdout is None and on_stderr is None and stdin is None and (seconds or 300) <= _core.MAX_WAIT:
419
+ create = _create(cmd, cwd, env, user)
420
+ create["wait"] = True
421
+ if seconds is not None:
422
+ create["timeout_seconds"] = seconds
423
+ # The answer comes when the command ends: up to its timeout, and what the API may take besides.
424
+ limit = max(request_timeout or self._transport.timeout, (seconds or 300) + _core.WAIT_GRACE)
425
+ exec = await self._api.start_exec(self._sandbox, create, timeout=limit)
426
+ # An answer without output is a retry's: its first attempt read the output.
427
+ lost = exec.get("stdout") is None and exec.get("stderr") is None
428
+ result = CommandResult(
429
+ exit_code=exec.get("exit_code"),
430
+ stdout=exec.get("stdout") or "",
431
+ stderr=exec.get("stderr") or "",
432
+ state=exec["state"],
433
+ signal=exec.get("signal"),
434
+ truncated=bool(exec.get("truncated")) or lost,
435
+ exec=exec,
436
+ )
437
+ else:
438
+ handle = await self.start(
439
+ cmd,
440
+ cwd=cwd,
441
+ env=env,
442
+ user=user,
443
+ timeout=timeout,
444
+ stdin=stdin is not None,
445
+ on_stdout=on_stdout,
446
+ on_stderr=on_stderr,
447
+ request_timeout=request_timeout,
448
+ )
449
+ if stdin is None:
450
+ result = await handle.wait()
451
+ else:
452
+ # The input is written while the output is read. A read that fails stops the writing; input that
453
+ # cannot be written whole ends the command, rather than leave it waiting for the rest.
454
+ data = stdin
455
+ stop = Flag()
456
+ failed: List[BaseException] = []
457
+
458
+ async def write() -> None:
459
+ try:
460
+ await handle._send(data, stop)
461
+ if not stop.is_set():
462
+ await handle.close_stdin()
463
+ return
464
+ except ComputeError as e:
465
+ if stop.is_set() or e.code == "lifecycle_conflict":
466
+ return # the read failed, or the command ended or closed its input: its result says how
467
+ failed.append(e)
468
+ except Exception as e:
469
+ if stop.is_set():
470
+ return
471
+ failed.append(e)
472
+ try:
473
+ await handle.kill("KILL")
474
+ except Exception:
475
+ pass
476
+
477
+ result = await alongside(write, handle.wait, stop)
478
+ if failed:
479
+ raise failed[0]
480
+ if check and (result.state != "exited" or result.exit_code != 0):
481
+ raise CommandExitError(result)
482
+ return result
483
+
484
+ async def start(
485
+ self,
486
+ cmd: Command,
487
+ *,
488
+ cwd: Optional[str] = None,
489
+ env: Optional[Mapping[str, str]] = None,
490
+ user: Optional[str] = None,
491
+ timeout: Optional[float] = None,
492
+ stdin: bool = False,
493
+ tty: Union[bool, Mapping[str, int]] = False,
494
+ on_stdout: Optional[Callable[[str], None]] = None,
495
+ on_stderr: Optional[Callable[[str], None]] = None,
496
+ request_timeout: Optional[float] = None,
497
+ ) -> AsyncCommandHandle:
498
+ """Starts a command and returns at once, with a handle to read its output, write its input and signal it.
499
+
500
+ :param stdin: keep standard input open, for send_stdin.
501
+ :param tty: run it on a terminal: True (24 rows by 80 columns), or ``{"rows": r, "cols": c}``.
502
+ """
503
+ create = _create(cmd, cwd, env, user)
504
+ if stdin:
505
+ create["stdin"] = True
506
+ if tty:
507
+ create["tty"] = True
508
+ if not isinstance(tty, bool):
509
+ create["tty_size"] = {"rows": int(tty["rows"]), "cols": int(tty["cols"])}
510
+ seconds = _core.timeout_seconds(timeout)
511
+ if seconds is not None:
512
+ create["timeout_seconds"] = seconds
513
+ exec = await self._api.start_exec(self._sandbox, create, timeout=request_timeout)
514
+ return AsyncCommandHandle(self._api, self._transport, self._sandbox, exec, on_stdout, on_stderr, request_timeout)
515
+
516
+ async def connect(
517
+ self,
518
+ exec: str,
519
+ *,
520
+ on_stdout: Optional[Callable[[str], None]] = None,
521
+ on_stderr: Optional[Callable[[str], None]] = None,
522
+ request_timeout: Optional[float] = None,
523
+ ) -> AsyncCommandHandle:
524
+ """A handle on a command already started (by its ID), to read the rest of its output."""
525
+ e = await self._api.get_exec(self._sandbox, exec, timeout=request_timeout)
526
+ return AsyncCommandHandle(self._api, self._transport, self._sandbox, e, on_stdout, on_stderr, request_timeout)
527
+
528
+
529
+ class AsyncCommandHandle:
530
+ """A running command.
531
+
532
+ Its output is read once: iterate the handle for its events, or wait() for its result (which holds whatever the
533
+ iteration saw too). A stream cut short is resumed after the last record read; output missed meanwhile marks the
534
+ result truncated. Leaving an iteration early keeps the stream open for wait(). Reading the output resumes the
535
+ sandbox if it was suspended, as any call that reaches the sandbox does.
536
+ """
537
+
538
+ def __init__(
539
+ self,
540
+ api: AsyncApi,
541
+ transport: AsyncTransport,
542
+ sandbox: str,
543
+ exec: ExecSession,
544
+ on_stdout: Optional[Callable[[str], None]],
545
+ on_stderr: Optional[Callable[[str], None]],
546
+ request_timeout: Optional[float],
547
+ ) -> None:
548
+ #: The command's ID.
549
+ self.id: str = exec["id"]
550
+ self._api = api
551
+ self._transport = transport
552
+ self._sandbox = sandbox
553
+ self._exec = exec
554
+ self._callbacks = {"stdout": on_stdout, "stderr": on_stderr}
555
+ self._request_timeout = request_timeout
556
+ self._last = 0
557
+ self._done = False
558
+ self._gap = False
559
+ self._stream: Optional[AsyncIterator[CommandEvent]] = None
560
+ #: One read at a time.
561
+ self._lock = Lock()
562
+ #: Guards _stream and _reading, never held while reading.
563
+ self._state = Lock()
564
+ self._reading = False
565
+ #: Counts disconnects: a read begun before one ends with DisconnectedError.
566
+ self._epoch = 0
567
+ self._kept = {"stdout": _Kept(), "stderr": _Kept()}
568
+ self._text = {k: codecs.getincrementaldecoder("utf-8")(errors="replace") for k in ("stdout", "stderr")}
569
+
570
+ @property
571
+ def exec(self) -> ExecSession:
572
+ """The command as last seen."""
573
+ return self._exec
574
+
575
+ def __aiter__(self) -> AsyncCommandHandle:
576
+ return self
577
+
578
+ async def __anext__(self) -> CommandEvent:
579
+ ev = await self._pull(self._epoch)
580
+ if ev is None:
581
+ raise StopAsyncIteration
582
+ return ev
583
+
584
+ async def wait(self) -> CommandResult:
585
+ """Reads the command's output to its end and returns its result."""
586
+ epoch = self._epoch
587
+ while await self._pull(epoch) is not None:
588
+ pass
589
+ e = self._exec
590
+ return CommandResult(
591
+ exit_code=e.get("exit_code"),
592
+ stdout=self._kept["stdout"].text(),
593
+ stderr=self._kept["stderr"].text(),
594
+ state=e["state"],
595
+ signal=e.get("signal"),
596
+ truncated=self._gap or self._kept["stdout"].capped or self._kept["stderr"].capped,
597
+ exec=e,
598
+ )
599
+
600
+ async def kill(self, signal: str = "KILL") -> None:
601
+ """Sends the command's process group a signal (TERM, KILL, INT, HUP, QUIT, USR1 or USR2)."""
602
+ await self._api.signal_exec(self._sandbox, self.id, {"signal": cast(Any, signal)}, timeout=self._request_timeout)
603
+
604
+ async def send_stdin(self, data: Union[str, bytes]) -> None:
605
+ """Writes to the command's standard input (it must have been started with stdin), all of it."""
606
+ await self._send(data, None)
607
+
608
+ async def _send(self, data: Union[str, bytes], stop: Optional[Flag]) -> None:
609
+ raw = data.encode() if isinstance(data, str) else bytes(data)
610
+ at = 0
611
+ stalls = 0
612
+ while at < len(raw) and not (stop is not None and stop.is_set()):
613
+ chunk = raw[at : at + _core.MAX_INPUT]
614
+ r = await self._api.write_exec_input(self._sandbox, self.id, {"data": _core.b64encode(chunk)}, timeout=self._request_timeout)
615
+ at += r["accepted"]
616
+ # The command took less than was sent while it stopped reading: the rest goes again.
617
+ stalls = 0 if r["accepted"] > 0 else stalls + 1
618
+ if stalls:
619
+ await sleep(min(2.0, 0.1 * 2**stalls))
620
+
621
+ async def close_stdin(self) -> None:
622
+ """Closes the command's standard input."""
623
+ await self._api.write_exec_input(self._sandbox, self.id, {"close": True}, timeout=self._request_timeout)
624
+
625
+ async def resize(self, rows: int, cols: int) -> None:
626
+ """Resizes the command's terminal."""
627
+ await self._api.resize_exec(self._sandbox, self.id, {"rows": rows, "cols": cols}, timeout=self._request_timeout)
628
+
629
+ async def disconnect(self) -> None:
630
+ """Stops reading the command's output (the command runs on).
631
+
632
+ A wait() or iteration under way ends with DisconnectedError, at its stream's next record or keep-alive. A later
633
+ read resumes after the last record read: output sent meanwhile on the stream that was stopped is missed, and
634
+ marks the result truncated.
635
+ """
636
+ self._epoch += 1
637
+ stream: Optional[AsyncIterator[CommandEvent]] = None
638
+ async with self._state:
639
+ if not self._reading:
640
+ stream, self._stream = self._stream, None
641
+ if stream is not None:
642
+ await stream.aclose() # type: ignore[attr-defined]
643
+
644
+ async def _pull(self, epoch: int) -> Optional[CommandEvent]:
645
+ async with self._lock:
646
+ if self._done:
647
+ return None
648
+ async with self._state:
649
+ # A read begun before a disconnect ends as its stream starts (_read checks the epoch).
650
+ if self._stream is None:
651
+ self._stream = self._read(epoch)
652
+ stream = self._stream
653
+ self._reading = True
654
+ try:
655
+ ev = await stream.__anext__()
656
+ except StopAsyncIteration:
657
+ raise DisconnectedError() from None # only a disconnect ends the stream before the command's exit
658
+ except BaseException:
659
+ async with self._state:
660
+ if self._stream is stream:
661
+ self._stream = None # a later read starts a new stream, after the last record seen
662
+ raise
663
+ finally:
664
+ async with self._state:
665
+ self._reading = False
666
+ self._apply(ev)
667
+ if ev.type == "exit":
668
+ # The command ended: let go of its stream now.
669
+ async with self._state:
670
+ self._stream = None
671
+ await stream.aclose() # type: ignore[attr-defined]
672
+ return ev
673
+
674
+ def _apply(self, ev: CommandEvent) -> None:
675
+ if ev.type in ("stdout", "stderr"):
676
+ self._kept[ev.type].add(ev.data)
677
+ text = self._text[ev.type].decode(ev.data)
678
+ cb = self._callbacks[ev.type]
679
+ if text and cb is not None:
680
+ cb(text)
681
+ elif ev.type == "gap":
682
+ self._gap = True
683
+ elif ev.type == "exit" and ev.exec is not None:
684
+ self._exec = ev.exec
685
+ self._done = True
686
+ for k in ("stdout", "stderr"):
687
+ rest = self._text[k].decode(b"", final=True)
688
+ cb = self._callbacks[k]
689
+ if rest and cb is not None:
690
+ cb(rest)
691
+
692
+ async def _read(self, epoch: int) -> AsyncIterator[CommandEvent]:
693
+ """The output stream, resumed after the last record seen while the command runs, until a disconnect."""
694
+ failures = 0
695
+ while True:
696
+ if self._epoch != epoch:
697
+ raise DisconnectedError()
698
+ began = time.monotonic()
699
+ progressed = False
700
+ cut: Optional[BaseException] = None
701
+ resp = await self._api.stream_exec_output(
702
+ self._sandbox,
703
+ self.id,
704
+ last_event_id=str(self._last) if self._last else None,
705
+ # A quiet stream sends a keep-alive within half a minute: it may be quiet that long, whatever the
706
+ # timeout asked for a request.
707
+ timeout=max(self._request_timeout or 0.0, _core.STREAM_IDLE),
708
+ )
709
+ try:
710
+ parser = EventParser()
711
+ ended = False
712
+ async for chunk in resp.aiter_bytes():
713
+ if self._epoch != epoch:
714
+ raise DisconnectedError()
715
+ for ev in parser.feed(chunk):
716
+ if ev.event == "exit":
717
+ yield CommandEvent("exit", exec=cast(ExecSession, json.loads(ev.data)))
718
+ return
719
+ if ev.event == "gap":
720
+ g = json.loads(ev.data)
721
+ yield CommandEvent("gap", after_seq=int(g["after_seq"]), next_seq=int(g["next_seq"]))
722
+ elif ev.event == "error":
723
+ e = json.loads(ev.data)
724
+ cut = ComputeError(
725
+ status=status_of(e.get("code", "")),
726
+ code=str(e.get("code")),
727
+ title="the output stream ended early",
728
+ detail=e.get("message"),
729
+ request_id=resp.headers.get("X-Request-Id"),
730
+ )
731
+ ended = True
732
+ break
733
+ elif ev.event in ("stdout", "stderr", "tty"):
734
+ seq = int(ev.id or 0)
735
+ if seq <= self._last:
736
+ continue # read already
737
+ self._last = seq
738
+ progressed = True
739
+ yield CommandEvent("stderr" if ev.event == "stderr" else "stdout", data=_core.b64decode(ev.data), seq=seq)
740
+ if ended:
741
+ break
742
+ except httpx.TransportError as e:
743
+ cut = ComputeConnectionError(f"the output stream was cut: {e or type(e).__name__}")
744
+ finally:
745
+ await resp.aclose()
746
+ if isinstance(cut, ComputeError) and cut.code in _core.FINAL_STREAM_CODES:
747
+ raise cut
748
+ # Only quick failures without output count: a stream that ran a while (they end after an hour) resumes
749
+ # freely.
750
+ failures = 0 if progressed or time.monotonic() - began > 60 else failures + 1
751
+ if failures > self._transport.max_retries:
752
+ raise cut or ComputeConnectionError("the output stream ended before the command did")
753
+ if failures:
754
+ await sleep(_core.backoff(failures))
755
+
756
+
757
+ class AsyncFiles:
758
+ """The files of one sandbox."""
759
+
760
+ def __init__(self, api: AsyncApi, transport: AsyncTransport, sandbox: str) -> None:
761
+ self._api = api
762
+ self._transport = transport
763
+ self._sandbox = sandbox
764
+
765
+ async def read(self, path: str, *, user: Optional[str] = None, request_timeout: Optional[float] = None) -> bytes:
766
+ """A file's bytes. A transfer cut short (the file replaced while it was read, a connection lost) is tried again."""
767
+ attempt = 0
768
+ while True:
769
+ attempt += 1
770
+ resp = await self._api.read_file(self._sandbox, path=path, user=user, timeout=request_timeout)
771
+ try:
772
+ return await resp.aread()
773
+ except httpx.TransportError as e:
774
+ if attempt > self._transport.max_retries:
775
+ raise ComputeConnectionError(
776
+ f"reading {path}: the transfer was cut: {e or type(e).__name__}",
777
+ request_id=resp.headers.get("X-Request-Id"),
778
+ attempts=attempt,
779
+ ) from e
780
+ finally:
781
+ await resp.aclose()
782
+ await sleep(_core.backoff(attempt))
783
+
784
+ async def read_text(self, path: str, *, user: Optional[str] = None, request_timeout: Optional[float] = None) -> str:
785
+ """A file's text, as UTF-8 (invalid bytes replaced)."""
786
+ return (await self.read(path, user=user, request_timeout=request_timeout)).decode("utf-8", "replace")
787
+
788
+ async def read_stream(self, path: str, *, user: Optional[str] = None, request_timeout: Optional[float] = None) -> AsyncIterator[bytes]:
789
+ """A file's bytes as they arrive (a transfer cut short is the reader's to retry)."""
790
+ resp = await self._api.read_file(self._sandbox, path=path, user=user, timeout=request_timeout)
791
+ try:
792
+ async for chunk in resp.aiter_bytes():
793
+ yield chunk
794
+ finally:
795
+ await resp.aclose()
796
+
797
+ async def write(self, path: str, data: Body, *, user: Optional[str] = None, request_timeout: Optional[float] = None) -> None:
798
+ """Writes a file whole, replacing it: a reader never sees half of it. Missing directories are made.
799
+
800
+ Text is written as UTF-8. Text and bytes carry their SHA-256, so the sandbox refuses a body changed on the way;
801
+ a file opened for reading in binary, or an iterator of bytes (an async one for the async client), is sent as
802
+ it comes, once.
803
+ """
804
+ digest: Optional[str] = None
805
+ body: Any = data
806
+ if isinstance(data, str):
807
+ body = data.encode()
808
+ elif isinstance(data, (bytearray, memoryview)):
809
+ body = bytes(data)
810
+ if isinstance(body, bytes):
811
+ digest = _core.content_digest(body)
812
+ elif hasattr(body, "read"):
813
+ body = file_chunks(body)
814
+ await self._api.write_file(
815
+ self._sandbox,
816
+ body,
817
+ path=path,
818
+ user=user,
819
+ content_digest=digest,
820
+ timeout=request_timeout or max(self._transport.timeout, _core.TRANSFER_TIMEOUT),
821
+ )
822
+
823
+ async def list(self, path: str, *, user: Optional[str] = None, request_timeout: Optional[float] = None) -> Listing:
824
+ """A directory's entries (following the path when it is a symlink)."""
825
+ r = await self._api.list_files(self._sandbox, path=path, user=user, timeout=request_timeout)
826
+ return Listing(path=r["path"], entries=[_core.file_info(e) for e in r["entries"]], unlisted=r["unlisted"], partial=r["partial"])
827
+
828
+ async def stat(self, path: str, *, user: Optional[str] = None, request_timeout: Optional[float] = None) -> FileInfo:
829
+ """What is at a path (a symlink itself, with its target)."""
830
+ return _core.file_info(await self._api.stat_file(self._sandbox, path=path, user=user, timeout=request_timeout))
831
+
832
+ async def exists(self, path: str, *, user: Optional[str] = None, request_timeout: Optional[float] = None) -> bool:
833
+ """Whether anything is at a path."""
834
+ try:
835
+ await self.stat(path, user=user, request_timeout=request_timeout)
836
+ return True
837
+ except ComputeError as e:
838
+ if e.path_reason() in ("not_found", "not_a_directory"):
839
+ return False
840
+ raise
841
+
842
+ async def remove(self, path: str, *, recursive: bool = False, user: Optional[str] = None, request_timeout: Optional[float] = None) -> None:
843
+ """Removes a file or a symlink (not what it names), or with recursive a directory and everything in it."""
844
+ await self._api.delete_file(self._sandbox, path=path, user=user, recursive=recursive or None, timeout=request_timeout)
845
+
846
+ async def mkdir(self, path: str, *, parents: bool = True, user: Optional[str] = None, request_timeout: Optional[float] = None) -> bool:
847
+ """Makes a directory, and its missing parents unless parents is False; False when it was there already."""
848
+ body: Dict[str, Any] = _without_none({"path": path, "user": user, "parents": None if parents else False})
849
+ return (await self._api.make_directory(self._sandbox, cast(Any, body), timeout=request_timeout))["created"]
850
+
851
+ async def rename(
852
+ self, src: str, dst: str, *, overwrite: bool = True, user: Optional[str] = None, request_timeout: Optional[float] = None
853
+ ) -> None:
854
+ """Moves a file or directory. One already at the destination is replaced, unless overwrite is False."""
855
+ body: Dict[str, Any] = _without_none({"from": src, "to": dst, "user": user, "overwrite": None if overwrite else False})
856
+ await self._api.rename_file(self._sandbox, cast(Any, body), timeout=request_timeout)
857
+
858
+
859
+ class AsyncPorts:
860
+ """The ports one sandbox exposes."""
861
+
862
+ def __init__(self, api: AsyncApi, sandbox: str) -> None:
863
+ self._api = api
864
+ self._sandbox = sandbox
865
+
866
+ async def expose(
867
+ self, port: int, *, public: Optional[bool] = None, token_ttl: Optional[Duration] = None, request_timeout: Optional[float] = None
868
+ ) -> Preview:
869
+ """Exposes a port, or changes whether an exposed one is public.
870
+
871
+ A port made private gets a new access token, in this answer only; one asked for as it already is stays as it
872
+ is, its token kept.
873
+
874
+ :param public: open to anyone with the URL, for a browser or an iframe (default: token-gated).
875
+ :param token_ttl: when the token this call mints expires, from now.
876
+ """
877
+ body = _without_none({"port": port, "public": public, "token_ttl": _core.duration(token_ttl)})
878
+ try:
879
+ return _core.preview(await self._api.expose_port(self._sandbox, cast(Any, body), timeout=request_timeout))
880
+ except ComputeError as e:
881
+ if not _core.token_lost(e):
882
+ raise
883
+ # An attempt minted the token and its answer was lost: a new one takes its place.
884
+ return await self.rotate_token(port, token_ttl=token_ttl, request_timeout=request_timeout)
885
+
886
+ async def list(self, *, request_timeout: Optional[float] = None) -> List[Preview]:
887
+ """The ports exposed (their tokens are never shown again)."""
888
+ return [_core.preview(p) for p in (await self._api.list_ports(self._sandbox, timeout=request_timeout))["items"]]
889
+
890
+ async def unexpose(self, port: int, *, request_timeout: Optional[float] = None) -> None:
891
+ """Stops exposing a port; its token dies with it."""
892
+ await self._api.unexpose_port(self._sandbox, port, timeout=request_timeout)
893
+
894
+ async def rotate_token(self, port: int, *, token_ttl: Optional[Duration] = None, request_timeout: Optional[float] = None) -> Preview:
895
+ """Gives a private port a new access token in place of its old one.
896
+
897
+ The gateways switch within moments: a 401 for the new token just after is worth retrying for a second or two.
898
+ """
899
+ tries = 0
900
+ while True:
901
+ tries += 1
902
+ try:
903
+ body = _without_none({"token_ttl": _core.duration(token_ttl)})
904
+ return _core.preview(await self._api.rotate_port_token(self._sandbox, port, cast(Any, body), timeout=request_timeout))
905
+ except ComputeError as e:
906
+ if not _core.token_lost(e) or tries >= 3:
907
+ raise
908
+
909
+
910
+ class _Kept:
911
+ """Up to 1 MiB of one stream's bytes."""
912
+
913
+ def __init__(self) -> None:
914
+ self._parts: List[bytes] = []
915
+ self._size = 0
916
+ self.capped = False
917
+
918
+ def add(self, data: bytes) -> None:
919
+ room = _core.KEEP - self._size
920
+ if len(data) > room:
921
+ self.capped = True
922
+ data = data[: max(room, 0)]
923
+ if data:
924
+ self._parts.append(data)
925
+ self._size += len(data)
926
+
927
+ def text(self) -> str:
928
+ return b"".join(self._parts).decode("utf-8", "replace")
929
+
930
+
931
+ def _create(cmd: Command, cwd: Optional[str], env: Optional[Mapping[str, str]], user: Optional[str]) -> ExecCreate:
932
+ create: Dict[str, Any] = {"command": _core.argv(cmd)}
933
+ if cwd is not None:
934
+ create["cwd"] = cwd
935
+ if env is not None:
936
+ create["env"] = dict(env)
937
+ if user is not None:
938
+ create["user"] = user
939
+ return cast(ExecCreate, create)
940
+
941
+
942
+ def _without_none(d: Dict[str, Any]) -> Dict[str, Any]:
943
+ return {k: v for k, v in d.items() if v is not None}