kaleido-cli 0.1.2__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,463 @@
1
+ """Docker Compose wrapper for RLN node lifecycle management."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import os
6
+ import shutil
7
+ import socket
8
+ import subprocess
9
+ import sys
10
+ from dataclasses import dataclass, field
11
+ from pathlib import Path
12
+
13
+ import yaml
14
+
15
+ from .config import DEFAULT_NETWORK, normalize_network_name
16
+ from .output import print_error, print_info, print_success, print_warning
17
+
18
+ COMPOSE_FILE = "docker-compose.yml"
19
+
20
+ RLN_IMAGE_REPO = "kaleidoswap/rgb-lightning-node"
21
+ RLN_IMAGE = f"{RLN_IMAGE_REPO}:0.10.0"
22
+
23
+ DEFAULT_BASE_DAEMON_PORT = 3001
24
+ DEFAULT_BASE_PEER_PORT = 9735
25
+ DEFAULT_NETWORK_NAME = "kaleidoswap-network"
26
+ DEFAULT_SPAWN_DIR = Path.home() / ".kaleido"
27
+
28
+
29
+ # ---------------------------------------------------------------------------
30
+ # Helpers
31
+ # ---------------------------------------------------------------------------
32
+
33
+
34
+ def list_spawn_names(base_dir: Path) -> list[str]:
35
+ """Return the names of all environments found under *base_dir*.
36
+
37
+ An environment is a sub-directory that contains a ``docker-compose.yml``.
38
+ """
39
+ if not base_dir.exists():
40
+ return []
41
+ return sorted(d.name for d in base_dir.iterdir() if d.is_dir() and (d / COMPOSE_FILE).exists())
42
+
43
+
44
+ def port_in_use(port: int) -> bool:
45
+ """True if *port* cannot be bound on the IPv4 or IPv6 wildcard address."""
46
+ for family, host in ((socket.AF_INET, "0.0.0.0"), (socket.AF_INET6, "::")):
47
+ try:
48
+ with socket.socket(family, socket.SOCK_STREAM) as sock:
49
+ sock.bind((host, port))
50
+ except OSError as exc:
51
+ if family == socket.AF_INET6 and exc.errno == getattr(socket, "EAFNOSUPPORT", None):
52
+ continue
53
+ return True
54
+ return False
55
+
56
+
57
+ def reserved_ports(base_dir: Path, exclude: str | None = None) -> set[int]:
58
+ """Host ports published by existing environments under *base_dir*, running or not."""
59
+ ports: set[int] = set()
60
+ for name in list_spawn_names(base_dir):
61
+ if name == exclude:
62
+ continue
63
+ try:
64
+ compose = yaml.safe_load((base_dir / name / COMPOSE_FILE).read_text()) or {}
65
+ except (OSError, yaml.YAMLError):
66
+ continue
67
+ for service in (compose.get("services") or {}).values():
68
+ for mapping in (service or {}).get("ports") or []:
69
+ host = str(mapping).split(":")[-2] if ":" in str(mapping) else str(mapping)
70
+ if host.isdigit():
71
+ ports.add(int(host))
72
+ return ports
73
+
74
+
75
+ def find_free_base_ports(
76
+ count: int,
77
+ base_dir: Path,
78
+ exclude_env: str | None = None,
79
+ daemon_base: int = DEFAULT_BASE_DAEMON_PORT,
80
+ peer_base: int = DEFAULT_BASE_PEER_PORT,
81
+ max_tries: int = 100,
82
+ ) -> tuple[int, int]:
83
+ """First (daemon_base, peer_base) pair whose *count* consecutive ports are all free."""
84
+ taken = reserved_ports(base_dir, exclude=exclude_env)
85
+
86
+ def block_free(start: int) -> bool:
87
+ return all(p not in taken and not port_in_use(p) for p in range(start, start + count))
88
+
89
+ def first_free(start: int) -> int:
90
+ for offset in range(max_tries):
91
+ candidate = start + offset * count
92
+ if block_free(candidate):
93
+ return candidate
94
+ raise RuntimeError(f"No free port block of {count} found from {start}")
95
+
96
+ return first_free(daemon_base), first_free(peer_base)
97
+
98
+
99
+ def container_user() -> str | None:
100
+ """On Linux, run as the invoking user so bind-mounted data dirs stay writable.
101
+
102
+ The image runs as uid 1000; Docker Desktop maps bind-mount ownership, plain
103
+ Linux Docker does not.
104
+ """
105
+ if not sys.platform.startswith("linux") or os.getuid() == 0:
106
+ return None
107
+ return f"{os.getuid()}:{os.getgid()}"
108
+
109
+
110
+ def upgrade_compose(compose_path: Path, image: str = RLN_IMAGE) -> list[tuple[str, str]]:
111
+ """Point every RLN service in *compose_path* at *image*.
112
+
113
+ Returns ``(service, old_image)`` for each service that changed. Also drops the
114
+ ``linux/amd64`` pin older CLIs wrote (the image is multi-arch) and creates the
115
+ bind-mounted data dirs so a non-root container can write to them.
116
+ """
117
+ compose = yaml.safe_load(compose_path.read_text()) or {}
118
+ changed: list[tuple[str, str]] = []
119
+ user = container_user()
120
+ for name, service in (compose.get("services") or {}).items():
121
+ old = str((service or {}).get("image", ""))
122
+ if not old.startswith(RLN_IMAGE_REPO):
123
+ continue
124
+ dirty = False
125
+ if old != image:
126
+ service["image"] = image
127
+ changed.append((name, old))
128
+ dirty = True
129
+ if service.pop("platform", None) is not None:
130
+ dirty = True
131
+ if user and service.get("user") != user:
132
+ service["user"] = user
133
+ dirty = True
134
+ for volume in service.get("volumes") or []:
135
+ host = str(volume).split(":")[0]
136
+ if host.startswith("."):
137
+ (compose_path.parent / host).mkdir(parents=True, exist_ok=True)
138
+ if dirty and (name, old) not in changed:
139
+ changed.append((name, old))
140
+ if changed:
141
+ compose_path.write_text(yaml.dump(compose, default_flow_style=False, sort_keys=False))
142
+ return changed
143
+
144
+
145
+ def compose_images(compose_path: Path) -> set[str]:
146
+ """RLN images referenced by *compose_path*."""
147
+ try:
148
+ compose = yaml.safe_load(compose_path.read_text()) or {}
149
+ except (OSError, yaml.YAMLError):
150
+ return set()
151
+ return {
152
+ str(svc.get("image"))
153
+ for svc in (compose.get("services") or {}).values()
154
+ if svc and str(svc.get("image", "")).startswith(RLN_IMAGE_REPO)
155
+ }
156
+
157
+
158
+ # ---------------------------------------------------------------------------
159
+ # Spawn configuration dataclasses
160
+ # ---------------------------------------------------------------------------
161
+
162
+
163
+ @dataclass
164
+ class NodeConfig:
165
+ """Per-node port / volume overrides for a spawned RGB Lightning Node."""
166
+
167
+ index: int # 0-based
168
+ daemon_port: int = 0 # 0 = auto → base_daemon_port + index
169
+ peer_port: int = 0 # 0 = auto → base_peer_port + index
170
+ data_dir: str = "" # "" = auto → <spawn_dir>/volumes/dataldk<index>
171
+ base_daemon_port: int = DEFAULT_BASE_DAEMON_PORT
172
+ base_peer_port: int = DEFAULT_BASE_PEER_PORT
173
+
174
+ def resolved_daemon_port(self) -> int:
175
+ return self.daemon_port or (self.base_daemon_port + self.index)
176
+
177
+ def resolved_peer_port(self) -> int:
178
+ return self.peer_port or (self.base_peer_port + self.index)
179
+
180
+ def resolved_data_dir(self, spawn_dir: Path) -> Path:
181
+ if self.data_dir:
182
+ return Path(self.data_dir).expanduser().resolve()
183
+ return spawn_dir / "volumes" / f"dataldk{self.index}"
184
+
185
+
186
+ @dataclass
187
+ class SpawnConfig:
188
+ """Configuration for a named set of RGB Lightning Nodes."""
189
+
190
+ # Environment identity
191
+ name: str = "default"
192
+ spawn_base_dir: str = "" # "" → ~/.kaleido (env lives at base/name)
193
+
194
+ count: int = 1
195
+ network: str = DEFAULT_NETWORK
196
+ # Docker network
197
+ network_name: str = DEFAULT_NETWORK_NAME
198
+ network_external: bool = False
199
+ # Node options
200
+ disable_authentication: bool = True
201
+ base_daemon_port: int = DEFAULT_BASE_DAEMON_PORT
202
+ base_peer_port: int = DEFAULT_BASE_PEER_PORT
203
+ # Optional per-node port / path overrides keyed by 0-based index
204
+ node_overrides: dict[int, NodeConfig] = field(default_factory=dict)
205
+
206
+ def resolved_base_dir(self) -> Path:
207
+ """The root spawn directory (parent of all environments)."""
208
+ if self.spawn_base_dir:
209
+ return Path(self.spawn_base_dir).expanduser().resolve()
210
+ return DEFAULT_SPAWN_DIR
211
+
212
+ def resolved_spawn_dir(self) -> Path:
213
+ """The directory for *this* environment (base / name)."""
214
+ return self.resolved_base_dir() / self.name
215
+
216
+ def get_nodes(self) -> list[NodeConfig]:
217
+ return [
218
+ self.node_overrides.get(
219
+ i,
220
+ NodeConfig(
221
+ index=i,
222
+ base_daemon_port=self.base_daemon_port,
223
+ base_peer_port=self.base_peer_port,
224
+ ),
225
+ )
226
+ for i in range(self.count)
227
+ ]
228
+
229
+
230
+ class DockerManager:
231
+ def __init__(self, compose_dir: str) -> None:
232
+ self.compose_dir = Path(compose_dir).expanduser().resolve()
233
+
234
+ def _validate(self) -> bool:
235
+ if not self.compose_dir.exists():
236
+ print_error(f"Environment directory not found: {self.compose_dir}")
237
+ print_info("Run 'kaleido node create' to create it.")
238
+ return False
239
+ if not (self.compose_dir / COMPOSE_FILE).exists():
240
+ print_error(f"No {COMPOSE_FILE} found in {self.compose_dir}")
241
+ print_info("Run 'kaleido node create' to regenerate it.")
242
+ return False
243
+ if shutil.which("docker") is None:
244
+ print_error("Docker is not installed or not in PATH.")
245
+ return False
246
+ return True
247
+
248
+ def _run(self, args: list[str], *, stream: bool = False) -> int:
249
+ cmd = ["docker", "compose", "--file", COMPOSE_FILE] + args
250
+ try:
251
+ if stream:
252
+ result = subprocess.run(cmd, cwd=self.compose_dir)
253
+ else:
254
+ result = subprocess.run(cmd, cwd=self.compose_dir, capture_output=False)
255
+ return result.returncode
256
+ except KeyboardInterrupt:
257
+ return 0
258
+
259
+ # ------------------------------------------------------------------
260
+ # Public commands
261
+ # ------------------------------------------------------------------
262
+
263
+ def stop(self) -> int:
264
+ if not self._validate():
265
+ return 1
266
+ print_info("Stopping services …")
267
+ return self._run(["stop"])
268
+
269
+ def down(self) -> int:
270
+ if not self._validate():
271
+ return 1
272
+ print_info("Stopping and removing containers …")
273
+ return self._run(["down"])
274
+
275
+ def logs(self, service: str | None = None, follow: bool = True) -> int:
276
+ if not self._validate():
277
+ return 1
278
+ args = ["logs"]
279
+ if follow:
280
+ args.append("-f")
281
+ if service:
282
+ args.append(service)
283
+ return self._run(args, stream=True)
284
+
285
+ def ps(self) -> int:
286
+ if not self._validate():
287
+ return 1
288
+ return self._run(["ps"])
289
+
290
+ def node_urls(self) -> list[str]:
291
+ """Read the compose file and return the HTTP URL for each rgb_node_* service."""
292
+ compose_path = self.compose_dir / COMPOSE_FILE
293
+ if not compose_path.exists():
294
+ return []
295
+ doc = yaml.safe_load(compose_path.read_text())
296
+ urls: list[str] = []
297
+ services = doc.get("services", {})
298
+ i = 1
299
+ while True:
300
+ svc = services.get(f"rgb_node_{i}")
301
+ if svc is None:
302
+ break
303
+ # port mapping can be "HOST:CONTAINER" or "BIND:HOST:CONTAINER"
304
+ ports = svc.get("ports", [])
305
+ if ports:
306
+ host_port = str(ports[0]).split(":")[-2]
307
+ urls.append(f"http://localhost:{host_port}")
308
+ i += 1
309
+ return urls
310
+
311
+ def clean(self) -> int:
312
+ if not self._validate():
313
+ return 1
314
+ removed = False
315
+ for candidate in self.compose_dir.iterdir():
316
+ if candidate.is_dir():
317
+ print_info(f"Removing {candidate}")
318
+ shutil.rmtree(candidate)
319
+ removed = True
320
+ if not removed:
321
+ print_warning("No data directories found — nothing to clean.")
322
+ else:
323
+ print_info("Data removed.")
324
+ return 0
325
+
326
+
327
+ # ---------------------------------------------------------------------------
328
+ # SpawnManager — generates a compose file and manages spawned RLN nodes
329
+ # ---------------------------------------------------------------------------
330
+
331
+
332
+ class SpawnManager(DockerManager):
333
+ """Generates a docker-compose.yml for a named environment and manages its lifecycle."""
334
+
335
+ def __init__(self, config: SpawnConfig) -> None:
336
+ self.spawn_config = config
337
+ super().__init__(str(config.resolved_spawn_dir()))
338
+
339
+ # Override _validate — before generate_compose() the dir may not exist yet
340
+ def _validate(self) -> bool:
341
+ if shutil.which("docker") is None:
342
+ print_error("Docker is not installed or not in PATH.")
343
+ return False
344
+ compose_path = self.compose_dir / COMPOSE_FILE
345
+ if not compose_path.exists():
346
+ print_error(f"No {COMPOSE_FILE} found in {self.compose_dir}")
347
+ print_info("Run 'kaleido node create' to generate it.")
348
+ return False
349
+ return True
350
+
351
+ # ------------------------------------------------------------------
352
+ # Compose generation
353
+ # ------------------------------------------------------------------
354
+
355
+ def generate_compose(self) -> Path:
356
+ """Write docker-compose.yml from SpawnConfig. Returns the compose file path."""
357
+ spawn_dir = self.spawn_config.resolved_spawn_dir()
358
+ spawn_dir.mkdir(parents=True, exist_ok=True)
359
+
360
+ compose_dict = self._build_compose_dict(spawn_dir)
361
+ compose_path = spawn_dir / COMPOSE_FILE
362
+ compose_path.write_text(yaml.dump(compose_dict, default_flow_style=False, sort_keys=False))
363
+ print_success(f"Compose file written to {compose_path}")
364
+ return compose_path
365
+
366
+ def _build_compose_dict(self, spawn_dir: Path) -> dict:
367
+ cfg = self.spawn_config
368
+ services: dict = {}
369
+
370
+ # ----------------------------------------------------------------
371
+ # RGB Lightning Nodes
372
+ # ----------------------------------------------------------------
373
+ for node in cfg.get_nodes():
374
+ idx = node.index
375
+ daemon_port = node.resolved_daemon_port()
376
+ peer_port = node.resolved_peer_port()
377
+ container_data = f"/tmp/kaleidoswap/dataldk{idx}"
378
+ host_data = f"./volumes/dataldk{idx}"
379
+
380
+ cmd_parts = [
381
+ f"{container_data}/",
382
+ f"--daemon-listening-port {daemon_port}",
383
+ f"--ldk-peer-listening-port {peer_port}",
384
+ ]
385
+ if cfg.disable_authentication:
386
+ cmd_parts.append("--disable-authentication")
387
+ rln_network = normalize_network_name(cfg.network)
388
+ cmd_parts.append(f"--network {rln_network}")
389
+
390
+ service: dict = {
391
+ "image": RLN_IMAGE,
392
+ "command": " ".join(cmd_parts),
393
+ "networks": [cfg.network_name],
394
+ "ports": [
395
+ f"{daemon_port}:{daemon_port}",
396
+ f"{peer_port}:{peer_port}",
397
+ ],
398
+ "volumes": [f"{host_data}:{container_data}"],
399
+ "environment": {
400
+ "APP_ENV": "${APP_ENV:-test}",
401
+ "NETWORK": "${NETWORK:-" + rln_network + "}",
402
+ "DAEMON_PORT": daemon_port,
403
+ },
404
+ "healthcheck": {
405
+ "test": [
406
+ "CMD",
407
+ "curl",
408
+ "-f",
409
+ f"http://localhost:{daemon_port}/nodeinfo",
410
+ ],
411
+ "interval": "10s",
412
+ "timeout": "10s",
413
+ "retries": 3,
414
+ "start_period": "10s",
415
+ },
416
+ "extra_hosts": ["myproxy.local:host-gateway"],
417
+ "stop_grace_period": "1m",
418
+ "stop_signal": "SIGTERM",
419
+ }
420
+
421
+ if user := container_user():
422
+ service["user"] = user
423
+ (spawn_dir / host_data).mkdir(parents=True, exist_ok=True)
424
+
425
+ services[f"rgb_node_{idx + 1}"] = service
426
+
427
+ network_def: dict = {}
428
+ if cfg.network_external:
429
+ network_def["external"] = True
430
+ # else: let Docker create the bridge automatically (no extra keys needed)
431
+
432
+ return {
433
+ "services": services,
434
+ "networks": {cfg.network_name: network_def},
435
+ }
436
+
437
+ # ------------------------------------------------------------------
438
+ # Lifecycle helpers
439
+ # ------------------------------------------------------------------
440
+
441
+ def spawn(self, start: bool = True) -> int:
442
+ """Generate compose file and optionally start the containers."""
443
+ self.generate_compose()
444
+ if not start:
445
+ return 0
446
+ if shutil.which("docker") is None:
447
+ print_error("Docker is not installed or not in PATH.")
448
+ return 1
449
+ n = self.spawn_config.count
450
+ label = f"{n} node(s)"
451
+ print_info(f"Starting {label} …")
452
+ return self._run(["up", "-d"])
453
+
454
+ def node_urls(self) -> list[str]:
455
+ """Return the HTTP URLs of each spawned node."""
456
+ return [
457
+ f"http://localhost:{node.resolved_daemon_port()}"
458
+ for node in self.spawn_config.get_nodes()
459
+ ]
460
+
461
+
462
+ def get_spawn_manager(config: SpawnConfig) -> SpawnManager:
463
+ return SpawnManager(config)