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/__init__.py +1 -0
- sinapsis_api/agent_router.py +482 -0
- sinapsis_api/agent_worker.py +240 -0
- sinapsis_api/api/__init__.py +1 -0
- sinapsis_api/api/healthcheck.py +25 -0
- sinapsis_api/api/main.py +40 -0
- sinapsis_api/api/routes/_common.py +85 -0
- sinapsis_api/api/routes/agents.py +91 -0
- sinapsis_api/api/routes/health.py +18 -0
- sinapsis_api/api/routes/jobs.py +81 -0
- sinapsis_api/client.py +135 -0
- sinapsis_api/constants.py +57 -0
- sinapsis_api/docker_runtime/__init__.py +42 -0
- sinapsis_api/docker_runtime/_file.py +71 -0
- sinapsis_api/docker_runtime/base.py +290 -0
- sinapsis_api/docker_runtime/image.py +83 -0
- sinapsis_api/docker_runtime/runtime.py +143 -0
- sinapsis_api/docker_runtime/services.py +127 -0
- sinapsis_api/env_vars/__init__.py +19 -0
- sinapsis_api/env_vars/env_vars.py +202 -0
- sinapsis_api/journal.py +298 -0
- sinapsis_api/models.py +30 -0
- sinapsis_api/onexth_runtime.py +68 -0
- sinapsis_api/protocol.py +106 -0
- sinapsis_api/telemetry.py +186 -0
- sinapsis_api-1.0.0.dist-info/METADATA +280 -0
- sinapsis_api-1.0.0.dist-info/RECORD +30 -0
- sinapsis_api-1.0.0.dist-info/WHEEL +4 -0
- sinapsis_api-1.0.0.dist-info/licenses/LICENSE-APACHE +202 -0
- sinapsis_api-1.0.0.dist-info/licenses/LICENSE-MIT +21 -0
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)
|