sinapsis-api 1.0.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.
sinapsis_api/client.py ADDED
@@ -0,0 +1,135 @@
1
+ """ZeroMQ client used by stateless API workers."""
2
+
3
+ import uuid
4
+ from collections.abc import AsyncIterator
5
+ from dataclasses import dataclass
6
+ from typing import Any
7
+
8
+ import zmq
9
+ import zmq.asyncio
10
+ from sinapsis.logging import sinapsis_logger
11
+
12
+ from sinapsis_api.constants import StreamFrame, StreamOperation
13
+ from sinapsis_api.env_vars import (
14
+ SINAPSIS_API_ROUTER_API_ENDPOINT,
15
+ SINAPSIS_API_ROUTER_STREAM_ENDPOINT,
16
+ SINAPSIS_API_ZMQ_RECEIVE_HWM,
17
+ SINAPSIS_API_ZMQ_SEND_HWM,
18
+ )
19
+ from sinapsis_api.protocol import EventRecord, pack_control, unpack_control
20
+
21
+
22
+ @dataclass(frozen=True, slots=True)
23
+ class ReplayPage:
24
+ """Bounded replay page plus Router-provided cursor metadata."""
25
+
26
+ events: tuple[EventRecord, ...]
27
+ metadata: dict[str, Any]
28
+
29
+
30
+ class SubscriberLaggedError(RuntimeError):
31
+ """Raised when a live subscriber cannot keep up with its bounded queue."""
32
+
33
+ def __init__(self, metadata: dict[str, Any]) -> None:
34
+ self.metadata = metadata
35
+ super().__init__(f"Subscriber lagged: {metadata}.")
36
+
37
+
38
+ class RouterClient:
39
+ """Short-lived request sockets and dedicated stream sockets for API workers."""
40
+
41
+ def __init__(
42
+ self,
43
+ api_endpoint: str = SINAPSIS_API_ROUTER_API_ENDPOINT,
44
+ stream_endpoint: str = SINAPSIS_API_ROUTER_STREAM_ENDPOINT,
45
+ ) -> None:
46
+ self.context = zmq.asyncio.Context.instance()
47
+ self.api_endpoint = api_endpoint
48
+ self.stream_endpoint = stream_endpoint
49
+
50
+ async def request(self, request: dict[str, Any]) -> dict[str, Any]:
51
+ """Send one control request to the Router."""
52
+ socket = self._dealer_socket("api", self.api_endpoint)
53
+ try:
54
+ await socket.send(pack_control(request))
55
+ return unpack_control(await socket.recv())
56
+ except Exception:
57
+ sinapsis_logger.exception("Router control request failed.")
58
+ raise
59
+ finally:
60
+ socket.close()
61
+
62
+ async def replay(
63
+ self, *, agent_id: str, after: int, job_id: str | None = None, limit: int | None = None
64
+ ) -> ReplayPage:
65
+ """Fetch one bounded replay page for an agent stream."""
66
+ parameters: dict[str, Any] = {"agent_id": agent_id, "after": after, "job_id": job_id}
67
+ if limit is not None:
68
+ parameters["limit"] = limit
69
+ events: list[EventRecord] = []
70
+ socket = self._dealer_socket("replay", self.stream_endpoint)
71
+ await socket.send_multipart([StreamOperation.REPLAY.value, pack_control(parameters)])
72
+ try:
73
+ while True:
74
+ frames = await socket.recv_multipart(copy=False)
75
+ frame_type = bytes(frames[0])
76
+ if frame_type == StreamFrame.EVENT.value:
77
+ events.append(self._event_from_frames(frames[1], frames[2]))
78
+ elif frame_type == StreamFrame.DONE.value:
79
+ metadata = unpack_control(frames[1].buffer)
80
+ if not metadata.get("ok", True):
81
+ sinapsis_logger.error("Router replay error: %s", metadata)
82
+ raise RuntimeError(metadata.get("detail", "Replay failed."))
83
+ return ReplayPage(tuple(events), metadata)
84
+ except Exception:
85
+ sinapsis_logger.exception("Replay failed for agent %s.", agent_id)
86
+ raise
87
+ finally:
88
+ socket.close()
89
+
90
+ async def subscribe(
91
+ self, *, agent_id: str, after: int | None = None, job_id: str | None = None
92
+ ) -> AsyncIterator[EventRecord]:
93
+ """Replay optionally, then yield live events for one logical agent."""
94
+ parameters = {"agent_id": agent_id, "after": after, "job_id": job_id}
95
+ socket = self._dealer_socket("subscribe", self.stream_endpoint)
96
+ await socket.send_multipart([StreamOperation.SUBSCRIBE.value, pack_control(parameters)])
97
+ try:
98
+ while True:
99
+ frames = await socket.recv_multipart(copy=False)
100
+ frame_type = bytes(frames[0])
101
+ if frame_type == StreamFrame.EVENT.value:
102
+ yield self._event_from_frames(frames[1], frames[2])
103
+ elif frame_type == StreamFrame.LIVE.value:
104
+ continue
105
+ elif frame_type == StreamFrame.LAGGED.value:
106
+ metadata = unpack_control(frames[1].buffer)
107
+ sinapsis_logger.warning("Subscriber lagged: %s", metadata)
108
+ raise SubscriberLaggedError(metadata)
109
+ except Exception:
110
+ sinapsis_logger.exception("Subscription ended for agent %s.", agent_id)
111
+ raise
112
+ finally:
113
+ socket.close()
114
+
115
+ def _dealer_socket(self, prefix: str, endpoint: str) -> zmq.asyncio.Socket:
116
+ socket = self.context.socket(zmq.DEALER)
117
+ socket.setsockopt(zmq.LINGER, 0)
118
+ socket.setsockopt(zmq.SNDHWM, SINAPSIS_API_ZMQ_SEND_HWM)
119
+ socket.setsockopt(zmq.RCVHWM, SINAPSIS_API_ZMQ_RECEIVE_HWM)
120
+ socket.setsockopt(zmq.IDENTITY, f"{prefix}:{uuid.uuid4()}".encode())
121
+ socket.connect(endpoint)
122
+ return socket
123
+
124
+ @staticmethod
125
+ def _event_from_frames(metadata_frame: Any, payload_frame: Any) -> EventRecord:
126
+ metadata = unpack_control(metadata_frame.buffer)
127
+ return EventRecord(
128
+ stream_id=metadata["stream_id"],
129
+ cursor=metadata["cursor"],
130
+ created_ns=metadata["created_ns"],
131
+ agent_id=metadata["agent_id"],
132
+ instance_id=metadata["instance_id"],
133
+ job_id=metadata.get("job_id"),
134
+ payload=bytes(payload_frame.buffer),
135
+ )
@@ -0,0 +1,57 @@
1
+ """Shared protocol and lifecycle constants."""
2
+
3
+ from enum import Enum
4
+
5
+
6
+ class ControlType(str, Enum):
7
+ HEALTH = "health"
8
+ LIST_AGENTS = "list_agents"
9
+ START_AGENT = "start_agent"
10
+ STOP_AGENT = "stop_agent"
11
+ START_JOB = "start_job"
12
+ CANCEL_JOB = "cancel_job"
13
+ APPROVAL_RESPONSE = "approval_response"
14
+ GET_JOB = "get_job"
15
+ EVENT_BOUNDS = "event_bounds"
16
+ INIT = "init"
17
+ STOP = "stop"
18
+
19
+
20
+ class WorkerFrame(bytes, Enum):
21
+ HELLO = b"HELLO"
22
+ COMMAND = b"COMMAND"
23
+ READY = b"READY"
24
+ EVENT = b"EVENT"
25
+ JOB_STATE = b"JOB_STATE"
26
+
27
+
28
+ class StreamOperation(bytes, Enum):
29
+ REPLAY = b"REPLAY"
30
+ SUBSCRIBE = b"SUBSCRIBE"
31
+
32
+
33
+ class StreamFrame(bytes, Enum):
34
+ EVENT = b"EVENT"
35
+ DONE = b"DONE"
36
+ LIVE = b"LIVE"
37
+ LAGGED = b"LAGGED"
38
+
39
+
40
+ class JobStatus(str, Enum):
41
+ QUEUED = "queued"
42
+ RUNNING = "running"
43
+ COMPLETED = "completed"
44
+ FAILED = "failed"
45
+ CANCELLED = "cancelled"
46
+
47
+
48
+ class AgentStatus(str, Enum):
49
+ RUNNING = "running"
50
+ STOPPED = "stopped"
51
+
52
+
53
+ class RouterError(str, Enum):
54
+ NOT_FOUND = "not_found"
55
+ CONFLICT = "conflict"
56
+ UNAVAILABLE = "unavailable"
57
+ INTERNAL = "internal"
@@ -0,0 +1,42 @@
1
+ from docker.models.containers import Container
2
+
3
+ import docker
4
+
5
+ from .base import DockerRuntimeError, ServiceStatus
6
+ from .services import get_runtime
7
+
8
+
9
+ def ensure_services(client: docker.DockerClient | None = None, *, rebuild_image: bool = False) -> dict[str, Container]:
10
+ """Ensure the Sinapsis router and API are running and healthy."""
11
+ return get_runtime().ensure(client, rebuild_image=rebuild_image)
12
+
13
+
14
+ def stop_services(client: docker.DockerClient | None = None) -> None:
15
+ """Stop the Sinapsis router and API."""
16
+ get_runtime().stop(client)
17
+
18
+
19
+ def restart_services(client: docker.DockerClient | None = None) -> dict[str, Container]:
20
+ """Restart the Sinapsis router and API and wait until ready."""
21
+ return get_runtime().restart(client)
22
+
23
+
24
+ def remove_services(client: docker.DockerClient | None = None, *, remove_network: bool = False) -> None:
25
+ """Remove Sinapsis containers and optionally their network."""
26
+ get_runtime().remove(client, remove_network=remove_network)
27
+
28
+
29
+ def get_service_status(client: docker.DockerClient | None = None) -> dict[str, ServiceStatus]:
30
+ """Return the current state of the Sinapsis runtime services."""
31
+ return get_runtime().status(client)
32
+
33
+
34
+ __all__ = [
35
+ "DockerRuntimeError",
36
+ "ServiceStatus",
37
+ "ensure_services",
38
+ "get_service_status",
39
+ "remove_services",
40
+ "restart_services",
41
+ "stop_services",
42
+ ]
@@ -0,0 +1,71 @@
1
+ import re
2
+ from importlib.metadata import version
3
+ from urllib.parse import urlparse
4
+
5
+ from sinapsis_api.env_vars import SINAPSIS_API_HOST_PORT, SINAPSIS_PACKAGE_INDEX
6
+
7
+ PACKAGE_DISTRIBUTION = "sinapsis-api"
8
+ # TODO: delete next line
9
+ SINAPSIS_PACKAGE_INDEX = "http://host.docker.internal:8080/simple"
10
+ PYTHON_VERSION = "3.13"
11
+
12
+ DOCKERFILE_TEMPLATE = """
13
+ FROM python:{python_version}-slim
14
+
15
+ COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv
16
+
17
+ ENV PYTHONUNBUFFERED=1 \\
18
+ PYTHONDONTWRITEBYTECODE=1 \\
19
+ UV_NO_CACHE=1
20
+
21
+ RUN uv pip install \\
22
+ --system \\
23
+ --index {package_index} \\
24
+ "{package_distribution}=={package_version}"
25
+
26
+ WORKDIR /app
27
+
28
+ EXPOSE {api_host_port}
29
+ """.strip()
30
+
31
+
32
+ def get_insecure_host(index_url: str) -> str | None:
33
+ """Return the host for an HTTP index that requires uv opt-in."""
34
+ parsed = urlparse(index_url)
35
+
36
+ if parsed.scheme != "http":
37
+ return None
38
+
39
+ return parsed.netloc
40
+
41
+
42
+ def get_installed_package_version() -> str:
43
+ """Return the installed version of the Sinapsis API package."""
44
+ return version(PACKAGE_DISTRIBUTION)
45
+
46
+
47
+ def get_runtime_image_name(package_version: str) -> str:
48
+ """Return the local Docker image name for a package version."""
49
+ return f"{PACKAGE_DISTRIBUTION}:{_docker_tag(package_version)}"
50
+
51
+
52
+ def get_runtime_dockerfile(package_version: str) -> str:
53
+ """Return the Dockerfile used to build the local runtime image."""
54
+ insecure_host = get_insecure_host(SINAPSIS_PACKAGE_INDEX)
55
+
56
+ allow_insecure = f"--allow-insecure-host {insecure_host} \\\n " if insecure_host else ""
57
+ return DOCKERFILE_TEMPLATE.format(
58
+ python_version=PYTHON_VERSION,
59
+ package_index=SINAPSIS_PACKAGE_INDEX,
60
+ allow_insecure=allow_insecure,
61
+ package_distribution=PACKAGE_DISTRIBUTION,
62
+ package_version=package_version,
63
+ api_host_port=int(SINAPSIS_API_HOST_PORT),
64
+ )
65
+
66
+
67
+ def _docker_tag(value: str) -> str:
68
+ """Convert a package version into a valid Docker tag."""
69
+ tag = re.sub(r"[^A-Za-z0-9_.-]+", "-", value).strip(".-")
70
+
71
+ return tag or "local"
@@ -0,0 +1,290 @@
1
+ import hashlib
2
+ import json
3
+ import time
4
+ from collections.abc import Mapping, Sequence
5
+ from dataclasses import asdict, dataclass, field
6
+
7
+ from docker.errors import APIError, DockerException, NotFound
8
+ from docker.models.containers import Container
9
+ from docker.models.networks import Network
10
+
11
+ import docker
12
+
13
+ SECOND_IN_NS = 1_000_000_000
14
+
15
+
16
+ class DockerRuntimeError(RuntimeError):
17
+ """Raised when a Docker runtime operation fails."""
18
+
19
+
20
+ @dataclass(frozen=True, slots=True)
21
+ class HealthCheck:
22
+ """Docker health-check configuration for a managed service."""
23
+
24
+ command: Sequence[str]
25
+ interval_seconds: int = 10
26
+ timeout_seconds: int = 5
27
+ retries: int = 5
28
+ start_period_seconds: int = 5
29
+
30
+ def as_docker_config(self) -> dict[str, object]:
31
+ """Return this health check in Docker SDK format."""
32
+ return {
33
+ "test": ["CMD", *self.command],
34
+ "interval": self.interval_seconds * SECOND_IN_NS,
35
+ "timeout": self.timeout_seconds * SECOND_IN_NS,
36
+ "retries": self.retries,
37
+ "start_period": self.start_period_seconds * SECOND_IN_NS,
38
+ }
39
+
40
+
41
+ @dataclass(frozen=True, slots=True)
42
+ class ContainerSpec:
43
+ """Declarative configuration for a Docker-managed service."""
44
+
45
+ name: str
46
+ image: str
47
+ command: Sequence[str]
48
+ environment: Mapping[str, str] = field(default_factory=dict)
49
+ ports: Mapping[str, int] = field(default_factory=dict)
50
+ labels: Mapping[str, str] = field(default_factory=dict)
51
+ healthcheck: HealthCheck | None = None
52
+ restart_policy: str = "unless-stopped"
53
+ startup_timeout_seconds: float = 60.0
54
+
55
+ def fingerprint(self) -> str:
56
+ """Return a stable fingerprint used to detect configuration changes."""
57
+ payload = {
58
+ "name": self.name,
59
+ "image": self.image,
60
+ "command": list(self.command),
61
+ "environment": dict(sorted(self.environment.items())),
62
+ "ports": dict(sorted(self.ports.items())),
63
+ "labels": dict(sorted(self.labels.items())),
64
+ "healthcheck": (asdict(self.healthcheck) if self.healthcheck is not None else None),
65
+ "restart_policy": self.restart_policy,
66
+ "startup_timeout_seconds": self.startup_timeout_seconds,
67
+ }
68
+
69
+ encoded = json.dumps(payload, sort_keys=True, separators=(",", ":")).encode("utf-8")
70
+
71
+ return hashlib.sha256(encoded).hexdigest()
72
+
73
+
74
+ @dataclass(frozen=True, slots=True)
75
+ class ServiceStatus:
76
+ """Current Docker state for a managed service."""
77
+
78
+ status: str
79
+ health: str | None
80
+
81
+
82
+ def get_docker_client() -> docker.DockerClient:
83
+ """Create a Docker client and verify that the daemon is reachable."""
84
+ try:
85
+ client = docker.from_env()
86
+ client.ping()
87
+ return client
88
+ except DockerException as exc:
89
+ raise DockerRuntimeError(
90
+ "Docker is unavailable. Ensure Docker Desktop or the Docker daemon is running."
91
+ ) from exc
92
+
93
+
94
+ def ensure_network(client: docker.DockerClient, name: str, *, labels: Mapping[str, str] | None = None) -> Network:
95
+ """Return an existing Docker network or create a bridge network."""
96
+ try:
97
+ return client.networks.get(name)
98
+ except NotFound:
99
+ try:
100
+ return client.networks.create(name=name, driver="bridge", labels=dict(labels or {}))
101
+ except APIError as exc:
102
+ raise DockerRuntimeError(f"Failed to create Docker network {name!r}.") from exc
103
+
104
+
105
+ def get_container(client: docker.DockerClient, name: str) -> Container | None:
106
+ """Return a container by name, or None when it does not exist."""
107
+ try:
108
+ return client.containers.get(name)
109
+ except NotFound:
110
+ return None
111
+
112
+
113
+ def get_container_health(container: Container) -> str | None:
114
+ """Return the Docker health state for a container."""
115
+ container.reload()
116
+
117
+ return container.attrs.get("State", {}).get("Health", {}).get("Status")
118
+
119
+
120
+ def get_container_logs(container: Container, *, tail: int = 100) -> str:
121
+ """Return recent combined stdout and stderr from a container."""
122
+ try:
123
+ output = container.logs(stdout=True, stderr=True, tail=tail)
124
+ except DockerException:
125
+ return "<unable to retrieve container logs>"
126
+
127
+ return output.decode("utf-8", errors="replace")
128
+
129
+
130
+ def create_container(
131
+ client: docker.DockerClient,
132
+ spec: ContainerSpec,
133
+ *,
134
+ network_name: str,
135
+ managed_labels: Mapping[str, str],
136
+ ) -> Container:
137
+ """Create and start a managed container."""
138
+ labels = {**dict(spec.labels), **dict(managed_labels)}
139
+
140
+ kwargs: dict[str, object] = {
141
+ "image": spec.image,
142
+ "command": list(spec.command),
143
+ "name": spec.name,
144
+ "network": network_name,
145
+ "environment": dict(spec.environment),
146
+ "restart_policy": {"Name": spec.restart_policy},
147
+ "labels": labels,
148
+ }
149
+
150
+ if spec.ports:
151
+ kwargs["ports"] = dict(spec.ports)
152
+
153
+ if spec.healthcheck is not None:
154
+ kwargs["healthcheck"] = spec.healthcheck.as_docker_config()
155
+
156
+ try:
157
+ container = client.containers.create(**kwargs)
158
+ container.start()
159
+ return container
160
+
161
+ except APIError as exc:
162
+ container = get_container(client, spec.name)
163
+
164
+ if container is not None:
165
+ try:
166
+ container.remove(force=True)
167
+ except DockerException:
168
+ pass
169
+
170
+ raise DockerRuntimeError(f"Failed to create container {spec.name!r}.") from exc
171
+
172
+
173
+ def ensure_container(
174
+ client: docker.DockerClient,
175
+ spec: ContainerSpec,
176
+ *,
177
+ network_name: str,
178
+ managed_label: str,
179
+ spec_fingerprint_label: str,
180
+ ) -> Container:
181
+ """Ensure a managed container exists with the expected configuration.
182
+
183
+ Containers are recreated automatically when their configuration or
184
+ underlying image changes.
185
+ """
186
+ expected_image = client.images.get(spec.image)
187
+ expected_fingerprint = spec.fingerprint()
188
+
189
+ managed_labels = {managed_label: "true", spec_fingerprint_label: expected_fingerprint}
190
+
191
+ container = get_container(client, spec.name)
192
+
193
+ if container is None:
194
+ return create_container(client, spec, network_name=network_name, managed_labels=managed_labels)
195
+
196
+ container.reload()
197
+
198
+ labels: Mapping[str, str] = container.attrs.get("Config", {}).get("Labels", {}) or {}
199
+
200
+ if labels.get(managed_label) != "true":
201
+ raise DockerRuntimeError(f"Container {spec.name!r} already exists but is not managed by this runtime.")
202
+
203
+ config_changed = labels.get(spec_fingerprint_label) != expected_fingerprint
204
+
205
+ image_changed = container.attrs.get("Image") != expected_image.id
206
+
207
+ if config_changed or image_changed:
208
+ remove_container(container)
209
+
210
+ return create_container(client, spec, network_name=network_name, managed_labels=managed_labels)
211
+
212
+ if container.status != "running":
213
+ try:
214
+ container.start()
215
+ except APIError as exc:
216
+ raise DockerRuntimeError(f"Failed to start container {spec.name!r}.") from exc
217
+
218
+ elif get_container_health(container) == "unhealthy":
219
+ try:
220
+ container.restart(timeout=10)
221
+ except APIError as exc:
222
+ raise DockerRuntimeError(f"Failed to restart unhealthy container {spec.name!r}.") from exc
223
+
224
+ return container
225
+
226
+
227
+ def wait_for_ready(container: Container, *, timeout_seconds: float = 60.0, poll_interval_seconds: float = 0.5) -> None:
228
+ """Wait for a container to be running and, when configured, healthy."""
229
+ deadline = time.monotonic() + timeout_seconds
230
+
231
+ while time.monotonic() < deadline:
232
+ container.reload()
233
+
234
+ state = container.attrs.get("State", {})
235
+ status = state.get("Status")
236
+ health = state.get("Health", {}).get("Status")
237
+
238
+ if status in {"dead", "exited"}:
239
+ raise DockerRuntimeError(
240
+ f"Container {container.name!r} exited during startup.\n\n{get_container_logs(container)}"
241
+ )
242
+
243
+ if status == "running" and health is None:
244
+ return
245
+
246
+ if health == "healthy":
247
+ return
248
+
249
+ if health == "unhealthy":
250
+ raise DockerRuntimeError(
251
+ f"Container {container.name!r} became unhealthy.\n\n{get_container_logs(container)}"
252
+ )
253
+
254
+ time.sleep(poll_interval_seconds)
255
+
256
+ raise DockerRuntimeError(
257
+ f"Container {container.name!r} did not become ready within "
258
+ f"{timeout_seconds:.0f} seconds.\n\n"
259
+ f"{get_container_logs(container)}"
260
+ )
261
+
262
+
263
+ def stop_container(container: Container, *, timeout_seconds: int = 10) -> None:
264
+ """Stop a container if it is currently running."""
265
+ container.reload()
266
+
267
+ if container.status != "running":
268
+ return
269
+
270
+ try:
271
+ container.stop(timeout=timeout_seconds)
272
+ except APIError as exc:
273
+ raise DockerRuntimeError(f"Failed to stop container {container.name!r}.") from exc
274
+
275
+
276
+ def remove_container(container: Container) -> None:
277
+ """Stop and remove a container."""
278
+ try:
279
+ container.reload()
280
+
281
+ if container.status == "running":
282
+ container.stop(timeout=10)
283
+
284
+ container.remove(force=True)
285
+
286
+ except NotFound:
287
+ return
288
+
289
+ except APIError as exc:
290
+ raise DockerRuntimeError(f"Failed to remove container {container.name!r}.") from exc
@@ -0,0 +1,83 @@
1
+ import io
2
+ import tarfile
3
+ from dataclasses import dataclass
4
+
5
+ from docker.errors import APIError, BuildError, ImageNotFound
6
+ from docker.models.images import Image
7
+
8
+ import docker
9
+
10
+ from .base import DockerRuntimeError
11
+
12
+
13
+ @dataclass(frozen=True, slots=True)
14
+ class ImageSpec:
15
+ """Declarative configuration for a locally built Docker image."""
16
+
17
+ name: str
18
+ dockerfile: str
19
+
20
+
21
+ def ensure_image(client: docker.DockerClient, spec: ImageSpec, *, rebuild: bool = False) -> Image:
22
+ """Return the requested image, building it locally when necessary."""
23
+ if not rebuild:
24
+ try:
25
+ return client.images.get(spec.name)
26
+ except ImageNotFound:
27
+ pass
28
+
29
+ return build_image(client, spec)
30
+
31
+
32
+ def build_image(client: docker.DockerClient, spec: ImageSpec) -> Image:
33
+ """Build an image from an in-memory Dockerfile."""
34
+ context = _build_context(spec.dockerfile)
35
+
36
+ try:
37
+ image, _ = client.images.build(
38
+ fileobj=context,
39
+ custom_context=True,
40
+ dockerfile="Dockerfile",
41
+ tag=spec.name,
42
+ rm=True,
43
+ forcerm=True,
44
+ pull=True,
45
+ extra_hosts={"host.docker.internal": "host-gateway"},
46
+ )
47
+
48
+ return image
49
+
50
+ except BuildError as exc:
51
+ raise DockerRuntimeError(f"Failed to build Docker image {spec.name!r}.\n\n{_format_build_error(exc)}") from exc
52
+
53
+ except APIError as exc:
54
+ raise DockerRuntimeError(f"Docker failed while building image {spec.name!r}.") from exc
55
+
56
+
57
+ def _build_context(dockerfile: str) -> io.BytesIO:
58
+ """Create an in-memory tar build context containing a Dockerfile."""
59
+ buffer = io.BytesIO()
60
+ dockerfile_bytes = dockerfile.encode("utf-8")
61
+
62
+ with tarfile.open(fileobj=buffer, mode="w") as archive:
63
+ info = tarfile.TarInfo(name="Dockerfile")
64
+ info.size = len(dockerfile_bytes)
65
+
66
+ archive.addfile(info, io.BytesIO(dockerfile_bytes))
67
+
68
+ buffer.seek(0)
69
+
70
+ return buffer
71
+
72
+
73
+ def _format_build_error(exc: BuildError) -> str:
74
+ """Convert Docker build output into readable error text."""
75
+ messages: list[str] = []
76
+
77
+ for entry in exc.build_log:
78
+ message = entry.get("error") or entry.get("stream")
79
+
80
+ if message:
81
+ messages.append(message.strip())
82
+
83
+ return "\n".join(messages)