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.
- impulse_compute/__init__.py +73 -0
- impulse_compute/_client_async.py +943 -0
- impulse_compute/_client_sync.py +943 -0
- impulse_compute/_core.py +238 -0
- impulse_compute/_errors.py +166 -0
- impulse_compute/_generated.py +6568 -0
- impulse_compute/_models.py +100 -0
- impulse_compute/_sse.py +69 -0
- impulse_compute/_support_async.py +61 -0
- impulse_compute/_support_sync.py +52 -0
- impulse_compute/_transport_async.py +132 -0
- impulse_compute/_transport_sync.py +132 -0
- impulse_compute/_version.py +1 -0
- impulse_compute/py.typed +0 -0
- impulse_compute/types.py +4 -0
- impulse_compute-0.1.0.dist-info/METADATA +247 -0
- impulse_compute-0.1.0.dist-info/RECORD +19 -0
- impulse_compute-0.1.0.dist-info/WHEEL +4 -0
- impulse_compute-0.1.0.dist-info/licenses/LICENSE +21 -0
|
@@ -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}
|