virtx 0.2.0__py3-none-win_amd64.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.
virtx/image.py ADDED
@@ -0,0 +1,288 @@
1
+ """The images the server keeps, and the names it keeps them under.
2
+
3
+ - Digest: the name of an image, the hash of its manifest, as ``algorithm:hex`` (such as
4
+ ``sha256:0123abcd...``). It identifies one image's content and never changes.
5
+ - Reference: a name a person gives an image, as ``name:tag`` (such as ``alpine:3.20``). It points
6
+ at one image, and can be moved to another. Any number of references may point at one image.
7
+ """
8
+
9
+ from __future__ import annotations
10
+
11
+ import builtins
12
+ import re
13
+ import sys
14
+ from collections.abc import AsyncIterator, Iterable, Mapping
15
+ from contextlib import aclosing
16
+ from dataclasses import dataclass, field
17
+ from enum import Enum
18
+ from typing import TYPE_CHECKING, Any
19
+
20
+ from ._library import VirtxError, args
21
+ from .job import LogEntry, Truncated
22
+
23
+ if TYPE_CHECKING:
24
+ from .client import Client
25
+
26
+
27
+ @dataclass(frozen=True)
28
+ class ImageTag:
29
+ """An image by a tag on it, as ``name:tag``."""
30
+
31
+ tag: str
32
+
33
+ def to_dict(self) -> dict[str, Any]:
34
+ """As the wire has it."""
35
+ return {"type": "tag", "tag": self.tag}
36
+
37
+
38
+ @dataclass(frozen=True)
39
+ class ImageDigest:
40
+ """An image by the digest of its manifest, as ``algorithm:hex``."""
41
+
42
+ digest: str
43
+
44
+ def to_dict(self) -> dict[str, Any]:
45
+ """As the wire has it."""
46
+ return {"type": "digest", "digest": self.digest}
47
+
48
+
49
+ ImageName = ImageTag | ImageDigest
50
+ """An image, by a tag on it or by its digest."""
51
+
52
+ _DIGEST = re.compile(r"(sha256:[0-9a-f]{64}|sha512:[0-9a-f]{128})")
53
+
54
+
55
+ def image_name(image: str | ImageName) -> ImageName:
56
+ """``image`` as the wire names one: a full ``sha256:`` or ``sha512:`` digest is a digest, any
57
+ other string a tag. An ``ImageName`` is taken as it is."""
58
+ if not isinstance(image, str):
59
+ return image
60
+ if _DIGEST.fullmatch(image):
61
+ return ImageDigest(image)
62
+ return ImageTag(image)
63
+
64
+
65
+ class Recipe:
66
+ """A base and the steps over it, which the server builds: ``Recipe("alpine:3.20").run("apk
67
+ add jq")``. Each step returns the recipe, so they chain."""
68
+
69
+ def __init__(self, base: str, steps: Iterable[Mapping[str, Any]] = ()) -> None:
70
+ self.base = base
71
+ self.steps: list[Mapping[str, Any]] = list(steps)
72
+
73
+ def run(self, command: str) -> Recipe:
74
+ """A command, run through ``sh -c`` with every earlier ``env``."""
75
+ self.steps.append({"run": command})
76
+ return self
77
+
78
+ def env(self, key: str, value: str) -> Recipe:
79
+ """A variable for every later ``run`` and the built image's config."""
80
+ self.steps.append({"env": {"key": key, "value": value}})
81
+ return self
82
+
83
+ def workdir(self, directory: str) -> Recipe:
84
+ """Where later steps run, and the built image's working directory."""
85
+ self.steps.append({"workdir": directory})
86
+ return self
87
+
88
+ def to_dict(self) -> dict[str, Any]:
89
+ """As the wire has it."""
90
+ return {"v": 1, "base": self.base, "steps": list(self.steps)}
91
+
92
+
93
+ @dataclass(frozen=True)
94
+ class BasicAuth:
95
+ """A username, and a password or an access token the registry takes in its place."""
96
+
97
+ username: str
98
+ password: str = field(repr=False)
99
+
100
+ def to_dict(self) -> dict[str, Any]:
101
+ """As the wire has it."""
102
+ return {"type": "basic", "username": self.username, "password": self.password}
103
+
104
+
105
+ @dataclass(frozen=True)
106
+ class BearerAuth:
107
+ """A token taken as it is, sent as ``Authorization: Bearer <token>``: a registry's, or the
108
+ server's own, as :meth:`Client.connect` takes it."""
109
+
110
+ token: str = field(repr=False)
111
+
112
+ def to_dict(self) -> dict[str, Any]:
113
+ """As the wire has it."""
114
+ return {"type": "bearer", "token": self.token}
115
+
116
+
117
+ RegistryAuth = BasicAuth | BearerAuth
118
+ """Credentials for a remote image registry."""
119
+
120
+
121
+ class ImageJobKind(str, Enum):
122
+ """What an image job does."""
123
+
124
+ PULL = "pull"
125
+ PUSH = "push"
126
+ BUILD = "build"
127
+
128
+
129
+ @dataclass(frozen=True)
130
+ class ImageJob:
131
+ """A build, pull or push the server runs, as ``build_image``, ``pull_image``,
132
+ ``push_image`` and ``get_image_job`` answer it, and the client that reaches it: what reads
133
+ its log. Dropping it leaves the job; ``remove`` removes it."""
134
+
135
+ client: Client = field(repr=False, compare=False)
136
+ """The client its requests go through."""
137
+
138
+ id: str
139
+ """The job's id, which every request about it names it by."""
140
+
141
+ kind: ImageJobKind
142
+
143
+ reference: str
144
+ """The reference it was started with."""
145
+
146
+ running: bool
147
+ """Whether it runs still."""
148
+
149
+ digest: str | None = None
150
+ """Once it has succeeded, as ``algorithm:hex``: the digest of the image a pull or build
151
+ left here, or of the manifest a push put on the registry."""
152
+
153
+ error: str | None = None
154
+ """Once it has failed, why, for a person."""
155
+
156
+ @classmethod
157
+ def from_dict(cls, client: Client, value: Mapping[str, Any]) -> ImageJob:
158
+ return cls(
159
+ client,
160
+ value["id"],
161
+ ImageJobKind(value["kind"]),
162
+ value["reference"],
163
+ value["running"],
164
+ value.get("digest"),
165
+ value.get("error"),
166
+ )
167
+
168
+ async def get(self) -> ImageJob:
169
+ """It as the server has it now."""
170
+ output = await self.client._call("virtx_client_get_image_job", args(id=self.id))
171
+ return ImageJob.from_dict(self.client, output)
172
+
173
+ async def log(self, after: int | None = None) -> AsyncIterator[LogEntry[ImageJobEntry]]:
174
+ """Its log, from its start or after its ``after``th entry, until its ``ImageJobEnd``,
175
+ or the ``VirtxError`` in its place if the job failed. Closing it leaves the job as it
176
+ is."""
177
+ async for item in self.client._items(
178
+ "virtx_client_image_job_log", args(id=self.id, after=after)
179
+ ):
180
+ yield image_job_entry(item)
181
+
182
+ async def complete(self, print: bool = False) -> str:
183
+ """Follow it to its end, printing each line of its log if ``print``: the digest it ended
184
+ with. Raises ``VirtxError`` with why it failed."""
185
+ async with aclosing(self.log()) as log:
186
+ async for item in log:
187
+ match item.entry:
188
+ case Log(line) if print:
189
+ builtins.print(line)
190
+ case Truncated() if print:
191
+ builtins.print(
192
+ "(the log reached the server's limit; the rest is not kept)",
193
+ file=sys.stderr,
194
+ )
195
+ case ImageJobEnd(digest):
196
+ return digest
197
+ raise VirtxError("the job was removed before it ended", source="job")
198
+
199
+ async def remove(self) -> None:
200
+ """Cancel it if it runs, and forget it."""
201
+ await self.client._call("virtx_client_remove_image_job", args(id=self.id))
202
+
203
+
204
+ @dataclass(frozen=True)
205
+ class Log:
206
+ """A line of an image job's log."""
207
+
208
+ line: str
209
+
210
+
211
+ @dataclass(frozen=True)
212
+ class ImageJobEnd:
213
+ """How an image job that succeeded ended, last in its log. One that failed ends its log
214
+ with the ``VirtxError`` it failed with instead."""
215
+
216
+ digest: str
217
+ """The digest of the image a pull or build left here, or of the manifest a push put on
218
+ the registry, as ``algorithm:hex``."""
219
+
220
+
221
+ ImageJobEntry = Log | Truncated | ImageJobEnd
222
+ """An entry of an image job's log."""
223
+
224
+
225
+ def image_job_entry(item: Mapping[str, Any]) -> LogEntry[ImageJobEntry]:
226
+ """An item of ``ImageJob.log``'s stream, as ``{"id": n, "log": "..."}`` and the like."""
227
+ entry: ImageJobEntry
228
+ if "log" in item:
229
+ entry = Log(item["log"])
230
+ elif "truncated" in item:
231
+ entry = Truncated()
232
+ else:
233
+ entry = ImageJobEnd(item["end"]["digest"])
234
+ return LogEntry(item["id"], entry)
235
+
236
+
237
+ @dataclass(frozen=True)
238
+ class ImageListOutputItem:
239
+ """One tag on the server's images."""
240
+
241
+ reference: str
242
+ """The tag, as ``name:tag``."""
243
+
244
+ digest: str
245
+ """The digest of the manifest it points at, as ``algorithm:hex``."""
246
+
247
+ @classmethod
248
+ def from_dict(cls, value: Mapping[str, Any]) -> ImageListOutputItem:
249
+ return cls(value["reference"], value["digest"])
250
+
251
+
252
+ @dataclass(frozen=True)
253
+ class ImageDownloadOutput:
254
+ """What ``download_image`` wrote."""
255
+
256
+ digest: str
257
+ """The digest of the manifest written, as ``algorithm:hex``."""
258
+
259
+ @classmethod
260
+ def from_dict(cls, value: Mapping[str, Any]) -> ImageDownloadOutput:
261
+ return cls(value["digest"])
262
+
263
+
264
+ @dataclass(frozen=True)
265
+ class ImageUploadOutput:
266
+ """What ``upload_image`` uploaded."""
267
+
268
+ digest: str
269
+ """The digest of the manifest uploaded, as ``algorithm:hex``."""
270
+
271
+ @classmethod
272
+ def from_dict(cls, value: Mapping[str, Any]) -> ImageUploadOutput:
273
+ return cls(value["digest"])
274
+
275
+
276
+ @dataclass(frozen=True)
277
+ class ImagePruneOutput:
278
+ """What ``prune_image`` deleted."""
279
+
280
+ images: list[str]
281
+ """The digest of each image deleted, as ``algorithm:hex``."""
282
+
283
+ reclaimed: int
284
+ """How many bytes the server freed."""
285
+
286
+ @classmethod
287
+ def from_dict(cls, value: Mapping[str, Any]) -> ImagePruneOutput:
288
+ return cls(list(value["images"]), value["reclaimed"])
virtx/job.py ADDED
@@ -0,0 +1,75 @@
1
+ """What every job's log shares: each entry numbered, and the mark of a log cut short.
2
+
3
+ A job, an image's build, pull or push or a process in a sandbox, runs on the server apart from
4
+ the request that started it. Its log is read with the client's ``*_job_log``, from its start or
5
+ after an entry's ``id``, until its end entry, or the ``VirtxError`` it failed with. A request
6
+ that starts one answers a ``StartedJob``: awaited, the job; iterated, its log; or followed to its
7
+ end with ``complete``.
8
+ """
9
+
10
+ from __future__ import annotations
11
+
12
+ import asyncio
13
+ from collections.abc import AsyncGenerator, AsyncIterator, Awaitable, Callable, Generator
14
+ from dataclasses import dataclass
15
+ from typing import Any, Generic, Protocol, TypeVar
16
+
17
+ J = TypeVar("J")
18
+ E = TypeVar("E")
19
+ T = TypeVar("T")
20
+ T_co = TypeVar("T_co", covariant=True)
21
+
22
+
23
+ class _Completes(Protocol[T_co]):
24
+ """A job, which ``complete`` follows to its end."""
25
+
26
+ def complete(self, print: bool = False) -> Awaitable[T_co]: ...
27
+
28
+
29
+ @dataclass(frozen=True)
30
+ class LogEntry(Generic[E]):
31
+ """One entry of a job's log, and its number in it, ``1`` for the first: what ``after``
32
+ resumes after."""
33
+
34
+ id: int
35
+ entry: E
36
+
37
+
38
+ @dataclass(frozen=True)
39
+ class Truncated:
40
+ """The log reached the server's limit: nothing after it is kept or sent, but the end."""
41
+
42
+
43
+ class StartedJob(Generic[J, E]):
44
+ """A request that starts a job, sent the first time this is awaited or iterated, and only
45
+ then: awaited, it answers the job; iterated, it yields the job's log, each a ``LogEntry``,
46
+ until its end entry; ``complete``, the job's own ``complete`` once started. Each way reads
47
+ the one job it started. Closing the iteration leaves the job running; cancelling it is the
48
+ client's ``remove_*_job``."""
49
+
50
+ def __init__(
51
+ self,
52
+ start: Callable[[], Awaitable[J]],
53
+ log: Callable[[J], AsyncIterator[LogEntry[E]]],
54
+ ) -> None:
55
+ self._start = start
56
+ self._log = log
57
+ self._job: asyncio.Future[J] | None = None
58
+
59
+ def __await__(self) -> Generator[Any, None, J]:
60
+ if self._job is None:
61
+ self._job = asyncio.ensure_future(self._start())
62
+ return self._job.__await__()
63
+
64
+ async def complete(self: StartedJob[_Completes[T], E], print: bool = False) -> T:
65
+ """Start the job and follow it to its end, as its ``complete`` does."""
66
+ return await (await self).complete(print=print)
67
+
68
+ async def __aiter__(self) -> AsyncIterator[LogEntry[E]]:
69
+ log = self._log(await self)
70
+ try:
71
+ async for entry in log:
72
+ yield entry
73
+ finally:
74
+ if isinstance(log, AsyncGenerator):
75
+ await log.aclose()
virtx/portforward.py ADDED
@@ -0,0 +1,67 @@
1
+ """A sandbox's port, forwarded to this machine's loopback: a ``VirtxPortForwarder*`` held."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import ctypes
6
+ import json
7
+ from typing import TYPE_CHECKING, Self
8
+
9
+ from ._library import Library, _Bytes
10
+
11
+ if TYPE_CHECKING:
12
+ from .client import Client
13
+
14
+
15
+ class PortForwarder:
16
+ """A sandbox's port at an address on this machine's loopback, until it is closed.
17
+
18
+ It runs on its client's session, so the client's last close stops it. Over stdio the server
19
+ is on this machine and its own address is the forwarder's; over HTTP each connection to the
20
+ forwarder is carried to the port in a WebSocket.
21
+ """
22
+
23
+ def __init__(self, raw: int, lib: Library, address: str) -> None:
24
+ self._raw: int | None = raw
25
+ self._lib = lib
26
+ self.address = address
27
+ """Where the port is reached, as ``host:port``."""
28
+
29
+ @classmethod
30
+ def open(cls, client: Client, url: str) -> PortForwarder:
31
+ """Forward the port a sandbox answered ``url`` for, as ``create_sandbox`` answers one in
32
+ ``ports``, over ``client``'s session. Blocks until it is open."""
33
+ lib = client._lib
34
+ args = json.dumps({"url": url}).encode()
35
+ raw = ctypes.c_void_p()
36
+ out = _Bytes()
37
+ status = lib.virtx_port_forwarder_open(
38
+ client._held(), args, len(args), ctypes.byref(raw), ctypes.byref(out)
39
+ )
40
+ output = lib.take(status, out)
41
+ return cls(raw.value or 0, lib, output["address"])
42
+
43
+ @property
44
+ def host(self) -> str:
45
+ """The address's host: a loopback IP."""
46
+ return self.address.rsplit(":", 1)[0].strip("[]")
47
+
48
+ @property
49
+ def port(self) -> int:
50
+ """The address's port."""
51
+ return int(self.address.rsplit(":", 1)[1])
52
+
53
+ def close(self) -> None:
54
+ """Stop forwarding. Closing twice does nothing."""
55
+ raw, self._raw = self._raw, None
56
+ if raw is not None:
57
+ self._lib.virtx_port_forwarder_free(raw)
58
+
59
+ def __enter__(self) -> Self:
60
+ return self
61
+
62
+ def __exit__(self, *exc: object) -> None:
63
+ self.close()
64
+
65
+ def __del__(self) -> None:
66
+ if getattr(self, "_raw", None) is not None:
67
+ self.close()
virtx/project.py ADDED
@@ -0,0 +1,91 @@
1
+ """Projects: what everything a server keeps belongs to, and the members of each, in a role.
2
+
3
+ A client's requests are in the project ``Client.set_project`` names, or the user's own project
4
+ without one.
5
+ """
6
+
7
+ from __future__ import annotations
8
+
9
+ from collections.abc import Mapping
10
+ from dataclasses import dataclass, field
11
+ from enum import Enum
12
+ from typing import TYPE_CHECKING, Any
13
+
14
+ from ._library import args
15
+
16
+ if TYPE_CHECKING:
17
+ from .client import Client
18
+
19
+
20
+ class Role(str, Enum):
21
+ """What a member of a project may do there."""
22
+
23
+ MEMBER = "member"
24
+ """Reaches everything in the project, reads it and its members, and leaves it."""
25
+
26
+ OWNER = "owner"
27
+ """Also adds, removes and changes members, and deletes the project."""
28
+
29
+
30
+ @dataclass(frozen=True)
31
+ class Project:
32
+ """One project the client has a role in, as ``list_project``, ``get_project`` and
33
+ ``create_project`` answer it, and the client that reaches it: its members, and its removal.
34
+ What is in it, a client reaches with the project set (``Client.set_project``). Dropping it
35
+ leaves the project; ``remove`` removes it."""
36
+
37
+ client: Client = field(repr=False, compare=False)
38
+ """The client its requests go through."""
39
+
40
+ id: str
41
+ """What names it on any server, given it once."""
42
+
43
+ name: str
44
+ """What its owner names it, among their projects."""
45
+
46
+ owner: str | None
47
+ """The user whose project it is: ``None`` for one of no user's, such as one made over stdio."""
48
+
49
+ role: Role
50
+ """The client's role in it, as the server answered it."""
51
+
52
+ @classmethod
53
+ def from_dict(cls, client: Client, value: Mapping[str, Any]) -> Project:
54
+ return cls(client, value["id"], value["name"], value.get("owner"), Role(value["role"]))
55
+
56
+ async def members(self) -> list[ProjectMemberListOutputItem]:
57
+ """Its members, with their roles."""
58
+ items = await self.client._call("virtx_client_list_project_member", args(project=self.id))
59
+ return [ProjectMemberListOutputItem.from_dict(item) for item in items]
60
+
61
+ async def set_member(self, user: str, role: Role) -> ProjectMemberListOutputItem:
62
+ """Give ``user`` ``role`` in it, adding them if they are no member."""
63
+ output = await self.client._call(
64
+ "virtx_client_set_project_member",
65
+ args(project=self.id, user=user, role=role),
66
+ )
67
+ return ProjectMemberListOutputItem.from_dict(output)
68
+
69
+ async def remove_member(self, user: str) -> None:
70
+ """Take ``user``'s role in it away: theirs to do, leaving it, or an owner's."""
71
+ await self.client._call(
72
+ "virtx_client_remove_project_member", args(project=self.id, user=user)
73
+ )
74
+
75
+ async def remove(self) -> None:
76
+ """Delete it and everything in it."""
77
+ await self.client._call("virtx_client_remove_project", args(name=self.id))
78
+
79
+
80
+ @dataclass(frozen=True)
81
+ class ProjectMemberListOutputItem:
82
+ """One member of a project, as ``Project.members`` and ``Project.set_member`` answer it."""
83
+
84
+ user: str
85
+ """The user as the server names them, such as an email address."""
86
+
87
+ role: Role
88
+
89
+ @classmethod
90
+ def from_dict(cls, value: Mapping[str, Any]) -> ProjectMemberListOutputItem:
91
+ return cls(value["user"], Role(value["role"]))
virtx/py.typed ADDED
File without changes