1"""``fm devenv``: local development environments by name, in docker or on the host.
3An environment is a forge with its runners and its seeded accounts,
4brought up by name, kept until removed, and removed whole by one
5verb. Its state is one directory under the runner's data directory,
6`forge-dev/envs/<name>/`: the forge's data, the runners' registrations
7and working directories, the seed's credentials, the port it took, the
8pid files of its processes, and what a pass of the loop places there:
9each variable an extension declares with a directory of its own
10(``{place}`` in its ``[env]`` table). A tool's home placed there, say
11one that keeps the remotes a release writes, names the environment's
12forge and goes with the environment. A job's own placement is under
13the runner's temporary directory for that job, which the runner
14creates in its working directory and removes after the job. The caches
15every environment shares, the tool store, uv's cache and footman's
16data for the jobs, live beside them in `forge-dev/cache/`, and removing
17an environment removes none of them. A new environment is warm from
18its first job, except for what a job places in its own directory: every
19job starts without it, and so does the first pass on a new
20environment.
22A removal takes the whole directory or refuses. A part this user may
23not remove, such as a file a build container left owned by root, is
24named with the command that makes it removable, and nothing is stopped
25or removed ([livery.workshop._devenv.remove][]).
27Host mode runs Gitea and its runners as processes of this machine,
28from the `gitea` and `gitea_runner` records the store supplies; no
29system service, no daemon registered with the operating system, so
30`fm devenv.rm` leaves no trace. Docker mode is the compose rig
31`fm forge.dev.up` runs, the one environment named `dev`, until the
32rig takes a name of its own. A runner is labelled
33`<env>-<host>-<arch>-<nn>`, the host and architecture its own.
34"""
41 pass
95 """The rig's own directory under the runner's data directory."""
96 from livery.footman import data_dir
98 return data_dir() / "forge-dev"
102 """Where the environments live, one directory each."""
103 return rig_dir() / "envs"
107 """The caches every environment shares."""
108 return rig_dir() / "cache"
112 """This machine's host key, `macos-arm`."""
113 from livery.workshop._tools import this_host as here
115 return here()
119 """The label a runner registers under: `<env>-<host>-<arch>-<nn>`."""
120 return f"{env}-{host}-{number:02d}"
124 """The runner shapes *spec* names, one per runner, in order.
126 A comma-separated list of `host`, or `host*<n>` for that many.
127 Container shapes come with the container setups and refuse here
128 by name.
129 """
130 shapes: list[str] = []
131 for token in (part.strip() for part in spec.split(",")):
132 if not token:
133 continue
134 shape, _, count = token.partition("*")
135 if shape != "host":
136 fail(
137 f"--runners names {shape!r}; the host shape is the one this"
138 " machine runs, and a container shape comes with the container"
139 " setups"
140 )
141 times = 1
142 if count:
143 if not count.isdigit() or int(count) < 1:
144 fail(f"--runners: {token!r} is not host*<n> with n at least 1")
145 times = int(count)
146 shapes.extend([shape] * times)
147 if not shapes:
148 fail("--runners names no runner; the default is one host runner")
149 return tuple(shapes)
154 """One environment as its directory holds it.
156 Attributes:
157 name: The environment's name, its directory's.
158 mode: `host` or `docker`.
159 directory: Where its state lives.
160 """
168 """The environment's own `KEY=VALUE` file: its port and credentials."""
169 return self.directory / "env"
173 """Gitea's work path: its configuration, data and log."""
174 return self.directory / "gitea"
178 """Gitea's configuration file."""
179 return self.gitea_dir / "custom" / "conf" / "app.ini"
183 """One directory per runner, numbered from `01`."""
184 return self.directory / "runners"
187 """Runner *number*'s directory."""
188 return self.runners_dir / f"{number:02d}"
191 self, extensions: Iterable[str], environ: Mapping[str, str]
192 ) -> dict[str, str]:
193 """The variables *extensions* declare, placed for a pass on this environment.
195 Each by name, to the value it takes against *environ*. The pass
196 forms the environment of the processes it starts, so one
197 *environ* carries wins unless the declaration says ``always``,
198 and a value naming ``{place}`` takes this environment's
199 directory, so what the pass and the processes it starts keep
200 there goes with the environment. Each job a runner takes places
201 its own under the job's temporary directory, which
202 `setup.sh github` names, so no two of the pass and its jobs
203 share one.
205 Raises:
206 Failed: when two of *extensions* declare one variable.
207 """
208 from livery.workshop._variables import declared_variables, placed
210 return placed(
211 declared_variables(extensions),
212 str(self.directory),
213 environ,
214 forming=True,
215 )
218 """The env file's pairs; empty when there is none yet."""
219 if not self.env_file.is_file():
220 return {}
221 pairs: dict[str, str] = {}
222 for line in self.env_file.read_text("utf-8").splitlines():
223 if "=" in line and not line.startswith("#"):223 ↛ 222line 223 didn't jump to line 222 because the condition on line 223 was always true
224 key, _, value = line.partition("=")
225 pairs[key.strip()] = value.strip()
226 return pairs
229 """Set *updates* in the env file, key by key, keeping the rest."""
230 pairs = self.values()
231 pairs.update(updates)
232 self.directory.mkdir(parents=True, exist_ok=True)
233 self.env_file.write_text(
234 "".join(f"{key}={value}\n" for key, value in sorted(pairs.items())),
235 encoding="utf-8",
236 )
240 """Gitea's URL, empty before the first `up`."""
241 return self.values().get("GITEA_URL", "")
245 """The seeded API token, empty before the first `up`."""
246 return self.values().get("GITEA_TOKEN", "")
250 """The environment *name* as its directory records it; a refusal for a bad name."""
251 if not name or not all(c.isalnum() or c == "-" for c in name) or name[0] == "-":
252 fail(f"{name!r} is not an environment name: letters, digits and dashes")
253 directory = envs_dir() / name
254 mode = Environment(name, "", directory).values().get("MODE", "")
255 return Environment(name, mode, directory)
259 """Every environment the rig holds, by name."""
260 if not envs_dir().is_dir():
261 return ()
262 return tuple(
263 environment(child.name)
264 for child in sorted(envs_dir().iterdir())
265 if child.is_dir() and (child / "env").is_file()
266 )
269# --- processes -------------------------------------------------------------------
272#: The variables that belong to the checkout a verb was run from, and
273#: never to a daemon: uv sets them for the one command it runs.
278 """The environment a daemon starts with: *environ* without the checkout's own.
280 A daemon inherits the entered environment on purpose: the store's
281 node on PATH is what the runner's JavaScript actions need. What it
282 must not inherit is the checkout the verb ran from: ``VIRTUAL_ENV``
283 and ``UV_RUN_RECURSION_DEPTH``, which uv sets for one command, and
284 that venv's bin directory leading PATH. A job's own setup enters
285 its own venv, and a runner whose PATH led with another checkout's
286 would resolve a tool there, at that checkout's version, ahead of
287 the job's lock, and print uv's warning on every sync.
288 """
289 cleaned = {
290 key: value for key, value in environ.items() if key not in _CHECKOUT_VARIABLES
291 }
292 venv = environ.get("VIRTUAL_ENV", "")
293 if venv and cleaned.get("PATH"):
294 own = {str(Path(venv) / "bin"), str(Path(venv) / "Scripts")}
295 cleaned["PATH"] = os.pathsep.join(
296 entry for entry in cleaned["PATH"].split(os.pathsep) if entry not in own
297 )
298 return cleaned
302 """Start *argv* as a process of its own that outlives this one; its pid.
304 Stdout and stderr go to *log*, appended; stdin is closed. The
305 child leads its own session (its own process group on Windows), so
306 the shell that ran the verb never owns it and `down` can stop it
307 by its pid alone. The environment is this process's own less the
308 checkout's ([livery.workshop._devenv.daemon_environment][]).
309 """
310 log.parent.mkdir(parents=True, exist_ok=True)
311 environment = daemon_environment(os.environ)
312 with log.open("ab") as sink:
313 if sys.platform == "win32":
314 flags = getattr(subprocess, "CREATE_NEW_PROCESS_GROUP", 0) | getattr(
315 subprocess, "CREATE_NO_WINDOW", 0
316 )
317 child = subprocess.Popen(
318 list(argv),
319 cwd=cwd,
320 stdin=subprocess.DEVNULL,
321 stdout=sink,
322 stderr=subprocess.STDOUT,
323 creationflags=flags,
324 env=environment,
325 )
326 else:
327 child = subprocess.Popen(
328 list(argv),
329 cwd=cwd,
330 stdin=subprocess.DEVNULL,
331 stdout=sink,
332 stderr=subprocess.STDOUT,
333 start_new_session=True,
334 env=environment,
335 )
336 return child.pid
340 """Stop the process *pid* and wait for it to go; whether it went."""
341 if not footman.alive(pid):
342 return True
343 if sys.platform == "win32":
344 subprocess.run(
345 [TASKKILL, "/F", "/T", "/PID", str(pid)],
346 capture_output=True,
347 check=False,
348 )
349 else:
350 try:
351 os.kill(pid, signal.SIGTERM)
352 except ProcessLookupError:
353 return True
354 deadline = time.monotonic() + timeout
355 while time.monotonic() < deadline:
356 if not footman.alive(pid):
357 return True
358 time.sleep(0.2)
359 if sys.platform != "win32":
360 try:
361 os.kill(pid, signal.SIGKILL)
362 except ProcessLookupError:
363 return True
364 time.sleep(0.5)
365 return not footman.alive(pid)
368#: The seams a test replaces: how a process is started, whether one
369#: lives, how one is stopped, and how a file is removed.
377 try:
378 return int(path.read_text("utf-8").strip() or "0")
379 except (OSError, ValueError):
380 return 0
384 """Every pid file the environment's processes left, Gitea's first."""
385 found = [env.directory / "gitea.pid"]
386 if env.runners_dir.is_dir():
387 found += sorted(env.runners_dir.glob("*/runner.pid"))
388 return found
392 """A TCP port nothing listens on right now."""
393 with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as probe:
394 probe.bind(("127.0.0.1", 0))
395 return int(probe.getsockname()[1])
398# --- the binaries ----------------------------------------------------------------
402 """The executable of *name* at *version* from the store; supplied when absent.
404 The record comes from the workspace's catalogue and the artifact
405 through the store's sources and the origin, verified by the
406 record's digest; a second call finds it present and downloads
407 nothing.
408 """
409 from livery.toolroom.store import Store
410 from livery.workshop._extensions import workspace_root
411 from livery.workshop._tools import catalogue, sources, store_home
413 root = workspace_root()
414 if root is None:
415 fail("no workspace: no workshop.toml above the working directory")
416 listing = catalogue(root, offline=offline)
417 store = Store(store_home(), sources=sources(root), offline=offline)
418 deployment = listing.deployment(name, version, store.host)
419 ensured = store.supply(name, "download", version, deployment)
420 return ensured.tool_dir / deployment.entry_points[0]
423#: The seam a test replaces: where the binaries come from.
427# --- gitea in host mode ------------------------------------------------------------
431 """Gitea's configuration for *env* on *port*: sqlite, actions on, no ssh."""
432 gitea = env.gitea_dir
433 return (
434 "APP_NAME = livery dev\n"
435 "RUN_MODE = prod\n"
436 f"WORK_PATH = {gitea}\n"
437 "\n"
438 "[server]\n"
439 "PROTOCOL = http\n"
440 "DOMAIN = localhost\n"
441 "HTTP_ADDR = 127.0.0.1\n"
442 f"HTTP_PORT = {port}\n"
443 f"ROOT_URL = http://localhost:{port}/\n"
444 "START_SSH_SERVER = false\n"
445 "DISABLE_SSH = true\n"
446 "LFS_START_SERVER = false\n"
447 "OFFLINE_MODE = true\n"
448 f"APP_DATA_PATH = {gitea / 'data'}\n"
449 "\n"
450 "[database]\n"
451 "DB_TYPE = sqlite3\n"
452 f"PATH = {gitea / 'data' / 'gitea.db'}\n"
453 "\n"
454 "[repository]\n"
455 f"ROOT = {gitea / 'data' / 'repositories'}\n"
456 "\n"
457 "[security]\n"
458 "INSTALL_LOCK = true\n"
459 f"SECRET_KEY = {secrets.token_hex(32)}\n"
460 f"INTERNAL_TOKEN = {secrets.token_hex(32)}\n"
461 "\n"
462 "[service]\n"
463 "DISABLE_REGISTRATION = true\n"
464 "REQUIRE_SIGNIN_VIEW = false\n"
465 "\n"
466 "[actions]\n"
467 "ENABLED = true\n"
468 "DEFAULT_ACTIONS_URL = github\n"
469 "\n"
470 "[packages]\n"
471 "ENABLED = true\n"
472 "\n"
473 "[log]\n"
474 "MODE = file\n"
475 "LEVEL = Info\n"
476 f"ROOT_PATH = {gitea / 'log'}\n"
477 )
481 """The runner's configuration: the rig's shared caches, in every job's environment.
483 A variable an extension declares with a directory of its own is not
484 among them: the runner takes *capacity* jobs at once, so each job
485 places it under the temporary directory the runner creates for it,
486 where `setup.sh github` places it, whatever value the job inherits.
487 It goes with the job.
488 """
489 from livery.footman import directory_variable
491 caches = cache_dir()
492 return (
493 "log:\n"
494 " level: info\n"
495 "runner:\n"
496 " file: .runner\n"
497 f" capacity: {capacity}\n"
498 " envs:\n"
499 f" {directory_variable('DATA_DIR')}: {caches / 'footman'}\n"
500 f" UV_CACHE_DIR: {caches / 'uv'}\n"
501 " timeout: 3h\n"
502 " fetch_interval: 2s\n"
503 "cache:\n"
504 " enabled: true\n"
505 f" dir: {caches / 'actcache'}\n"
506 "host:\n"
507 f" workdir_parent: {env.runner_dir(number) / 'work'}\n"
508 )
512 """One gitea CLI call against *env*'s configuration and work path."""
513 return footman.run(
514 [
515 str(exe),
516 "--config",
517 str(env.app_ini),
518 "--work-path",
519 str(env.gitea_dir),
520 *args,
521 ],
522 cwd=env.gitea_dir,
523 nofail=True,
524 timeout=120.0,
525 )
529 url: str, path: str, token: str, *, method: str = "GET", body: str = ""
530) -> int:
531 """One API call; the HTTP status, 0 when the server does not answer."""
532 request = urllib.request.Request(
533 f"{url}/api/v1{path}",
534 data=body.encode() if body else None,
535 method=method,
536 headers={"Authorization": f"token {token}", "Content-Type": "application/json"},
537 )
538 try:
539 with urllib.request.urlopen(request, timeout=10) as response:
540 return int(response.status)
541 except urllib.error.HTTPError as error:
542 return error.code
543 except (urllib.error.URLError, OSError):
544 return 0
548 try:
549 with urllib.request.urlopen(f"{url}/api/healthz", timeout=2):
550 return True
551 except (urllib.error.URLError, OSError):
552 return False
555#: The seams a test replaces: the health probe and the API call.
561 """Start Gitea for *env* unless it runs; its URL and its pid."""
562 values = env.values()
563 port = int(values.get("GITEA_PORT", "0") or 0)
564 if not port:
565 port = free_port()
566 url = f"http://localhost:{port}"
567 pid_file = env.directory / "gitea.pid"
568 pid = _read_pid(pid_file)
569 if pid and ALIVE(pid) and HEALTHY(url):
570 return url, pid
571 # The env file first: a directory with files and no env file is what
572 # a refused removal leaves, which a bring-up refuses (`up_host`), and
573 # the port it names is the one the configuration below is written for.
574 env.update({"MODE": "host", "GITEA_PORT": str(port), "GITEA_URL": url})
575 if not env.app_ini.is_file():
576 env.app_ini.parent.mkdir(parents=True, exist_ok=True)
577 env.app_ini.write_text(app_ini(env, port), encoding="utf-8")
578 (env.gitea_dir / "data").mkdir(parents=True, exist_ok=True)
579 pid = SPAWN(
580 [
581 str(exe),
582 "--config",
583 str(env.app_ini),
584 "--work-path",
585 str(env.gitea_dir),
586 "web",
587 ],
588 cwd=env.gitea_dir,
589 log=env.gitea_dir / "gitea.log",
590 )
591 pid_file.write_text(f"{pid}\n", encoding="utf-8")
592 deadline = time.monotonic() + HEALTH_TIMEOUT
593 while time.monotonic() < deadline:
594 if HEALTHY(url):
595 return url, pid
596 if not ALIVE(pid):
597 fail(
598 f"gitea for {env.name} exited before it answered; its log is"
599 f" {env.gitea_dir / 'gitea.log'}"
600 )
601 time.sleep(0.5)
602 fail(
603 f"gitea for {env.name} did not answer {url}/api/healthz within"
604 f" {HEALTH_TIMEOUT:.0f}s; its log is {env.gitea_dir / 'gitea.log'}"
605 )
609 """Seed *env*'s Gitea: the admin, an API token, the org, a runner token.
611 A token that still answers is kept; a missing or dead one is
612 minted again. The runner token is minted on every up, since one
613 registers one runner.
614 """
615 token = env.token
616 if not (token and API(url, "/user", token) == 200):
617 created = _gitea(
618 env,
619 exe,
620 "admin",
621 "user",
622 "create",
623 "--username",
624 ADMIN,
625 "--password",
626 footman.Secret("livery-dev-password"),
627 "--email",
628 "admin@livery.local",
629 "--admin",
630 "--must-change-password=false",
631 )
632 said = created.stdout + created.stderr
633 if created.code != 0 and "already exists" not in said:633 ↛ 634line 633 didn't jump to line 634 because the condition on line 633 was never true
634 fail(f"gitea for {env.name}: the admin user was not created:\n{said}")
635 minted = _gitea(
636 env,
637 exe,
638 "admin",
639 "user",
640 "generate-access-token",
641 "--username",
642 ADMIN,
643 "--token-name",
644 f"seed-{int(time.time())}",
645 "--scopes",
646 "all",
647 "--raw",
648 )
649 if minted.code != 0:649 ↛ 650line 649 didn't jump to line 650 because the condition on line 649 was never true
650 fail(
651 f"gitea for {env.name}: no API token minted:"
652 f"\n{minted.stdout}{minted.stderr}"
653 )
654 token = minted.stdout.strip().split()[-1]
655 if API(url, f"/orgs/{ORG}", token) != 200:655 ↛ 656line 655 didn't jump to line 656 because the condition on line 655 was never true
656 status = API(
657 url, "/orgs", token, method="POST", body=f'{{"username": "{ORG}"}}'
658 )
659 if status not in (201, 422):
660 fail(f"gitea for {env.name}: the {ORG} org answered HTTP {status}")
661 runner = _gitea(env, exe, "actions", "generate-runner-token")
662 if runner.code != 0:662 ↛ 663line 662 didn't jump to line 663 because the condition on line 662 was never true
663 fail(
664 f"gitea for {env.name}: no runner token minted:"
665 f"\n{runner.stdout}{runner.stderr}"
666 )
667 values = {
668 "GITEA_URL": url,
669 "GITEA_TOKEN": token,
670 "GITEA_RUNNER_TOKEN": runner.stdout.strip(),
671 }
672 env.update(values)
673 return values
677 env: Environment, exe: Path, number: int, url: str, registration: str
678) -> tuple[str, int]:
679 """Register runner *number* once and start it unless it runs; its label and pid."""
680 home = env.runner_dir(number)
681 home.mkdir(parents=True, exist_ok=True)
682 label = runner_label(env.name, this_host(), number)
683 pid_file = home / "runner.pid"
684 pid = _read_pid(pid_file)
685 if pid and ALIVE(pid):
686 return label, pid
687 if not (home / ".runner").is_file():687 ↛ 711line 687 didn't jump to line 711 because the condition on line 687 was always true
688 registered = footman.run(
689 [
690 str(exe),
691 "register",
692 "--instance",
693 url,
694 "--token",
695 footman.Secret(registration),
696 "--name",
697 label,
698 "--labels",
699 f"{label}:host",
700 "--no-interactive",
701 ],
702 cwd=home,
703 nofail=True,
704 timeout=120.0,
705 )
706 if registered.code != 0:706 ↛ 707line 706 didn't jump to line 707 because the condition on line 706 was never true
707 fail(
708 f"runner {label} was not registered:"
709 f"\n{registered.stdout}{registered.stderr}"
710 )
711 (home / "config.yaml").write_text(runner_config(env, number), encoding="utf-8")
712 for name in CACHES:
713 (cache_dir() / name).mkdir(parents=True, exist_ok=True)
714 pid = SPAWN(
715 [str(exe), "daemon", "--config", str(home / "config.yaml")],
716 cwd=home,
717 log=home / "runner.log",
718 )
719 pid_file.write_text(f"{pid}\n", encoding="utf-8")
720 return label, pid
724 """Make *values* the cascade's current forge: the shared env file, key by key."""
725 from livery.footman import config_dir
727 path = config_dir() / ".repo.shared.env"
728 lines = path.read_text("utf-8").splitlines() if path.is_file() else []
729 for key, value in sorted(values.items()):
730 entry = f"{key}={value}"
731 for index, line in enumerate(lines):
732 if line.split("=", 1)[0].strip() == key:
733 lines[index] = entry
734 break
735 else:
736 lines.append(entry)
737 path.parent.mkdir(parents=True, exist_ok=True)
738 path.write_text("\n".join(lines) + "\n", encoding="utf-8")
742 env: Environment, runners: tuple[str, ...], *, offline: bool = False
743) -> None:
744 """Bring *env* up in host mode: Gitea, the seed, then each runner.
746 Raises:
747 Failed: when *env*'s directory holds files and no env file, which
748 is what a refused removal leaves; the message names the
749 removal that finishes it.
750 """
751 if (
752 env.directory.is_dir()
753 and not env.env_file.is_file()
754 and any(env.directory.iterdir())
755 ):
756 fail(
757 f"{env.name}: {env.directory} holds what a refused removal left,"
758 " and no environment; remove it first:"
759 f" `{footman.prog()} devenv.rm --env={env.name}`"
760 )
761 gitea = BINARY("gitea", GITEA_VERSION, offline=offline)
762 runner = BINARY("gitea_runner", RUNNER_VERSION, offline=offline)
763 url, _pid = _start_gitea(env, gitea)
764 values = _seed(env, gitea, url)
765 labels: list[str] = []
766 for number, _shape in enumerate(runners, start=1):
767 label, _ = _start_runner(env, runner, number, url, values["GITEA_RUNNER_TOKEN"])
768 labels.append(label)
769 env.update({"RUNNERS": ",".join(runners), "LABELS": ",".join(labels)})
770 _share({"GITEA_URL": url, "GITEA_TOKEN": values["GITEA_TOKEN"]})
771 print(f" {env.name}: gitea {url}, host mode, {len(labels)} runner(s)")
772 for label in labels:
773 print(f" {env.name}: runner {label}")
777 """Bring the docker-mode environment up through the compose rig."""
778 if env.name != DEFAULT_ENV:778 ↛ 783line 778 didn't jump to line 783 because the condition on line 778 was always true
779 fail(
780 f"docker mode has one environment, {DEFAULT_ENV}, until the compose"
781 f" rig takes a name; {env.name!r} is a host-mode name"
782 )
783 result = footman.run(
784 [
785 sys.executable,
786 "-m",
787 "livery.footman",
788 "forge.dev.up",
789 "--profile=gitea",
790 "--with-docker",
791 ],
792 nofail=True,
793 timeout=1800.0,
794 )
795 print(result.stdout.rstrip("\n"))
796 if result.code != 0:
797 fail(f"forge.dev.up exited {result.code}:\n{result.stderr}")
798 env.update({"MODE": "docker", "GITEA_URL": "http://localhost:3000"})
802 """Stop *env*'s processes and keep its directory; the lines to print."""
803 if env.mode == "docker":803 ↛ 804line 803 didn't jump to line 804 because the condition on line 803 was never true
804 result = footman.run(
805 [
806 sys.executable,
807 "-m",
808 "livery.footman",
809 "forge.dev.down",
810 "--profile=gitea",
811 ],
812 nofail=True,
813 timeout=600.0,
814 )
815 if result.code != 0:
816 fail(f"forge.dev.down exited {result.code}:\n{result.stderr}")
817 return [f" {env.name}: stopped (docker)"]
818 lines: list[str] = []
819 for pid_file in _pid_files(env):
820 pid = _read_pid(pid_file)
821 if pid and ALIVE(pid):
822 went = STOP(pid)
823 what = "runner" if pid_file.name == "runner.pid" else "gitea"
824 lines.append(
825 f" {env.name}: {what} {pid} {'stopped' if went else 'did not stop'}"
826 )
827 pid_file.unlink(missing_ok=True)
828 if not lines:
829 lines.append(f" {env.name}: nothing was running")
830 return lines
834 """Stop *env* and remove its directory whole; the lines to print.
836 The directory is checked first
837 ([livery.workshop._devenv.removal_blocker][]): a part this user may
838 not remove refuses before anything is stopped or removed, so the
839 environment stays as it was. A delete refused after the check,
840 a file that changed hands or is held open, leaves the processes
841 stopped and every other part removed, the env file with them; a
842 bring-up under the name then refuses until the removal runs again.
844 Raises:
845 Failed: when a part of the directory cannot be removed, naming
846 it, the reason, and the command that makes it removable.
847 """
848 if not env.directory.is_dir():
849 return [f" {env.name}: no such environment"]
850 blocker = removal_blocker(env.directory)
851 if blocker:
852 fail(
853 f"{env.name}: {blocker}, so nothing was stopped or removed. Make it"
854 f" this user's, then remove it again: {_hand_back(env.directory)}"
855 )
856 lines = down(env)
857 shared_url = env.url
858 if shared_url:
859 _forget(shared_url)
860 stayed = remove_tree(env.directory)
861 if stayed:
862 fail(
863 f"{env.name}: {env.directory} is not removed whole; {_stayed(stayed)}."
864 " The processes are stopped and everything else is removed. Make"
865 " what stayed this user's, then remove it again:"
866 f" {_hand_back(env.directory)}"
867 )
868 lines.append(f" {env.name}: removed {env.directory}")
869 return lines
873 """Why this user cannot remove *path* whole; empty when every part of it can go.
875 A file goes when its directory may be changed by the user removing
876 it, whoever owns the file, so the answer names the first directory
877 under *path*, or *path*'s own parent, that this user may not change,
878 with its owner, or the first one it may not list. A build container
879 that writes into a mounted directory as root leaves such a
880 directory. Windows decides by other rules: there a removal finds out
881 by trying ([livery.workshop._devenv.remove_tree][]), and the answer
882 is empty.
883 """
884 if sys.platform == "win32":
885 return ""
886 wanted = os.W_OK | os.X_OK
887 if not os.access(path.parent, wanted):
888 return _not_changeable(str(path.parent))
889 unlisted: list[OSError] = []
890 for current, _directories, _files in os.walk(path, onerror=unlisted.append):
891 if not os.access(current, wanted):
892 return _not_changeable(current)
893 if unlisted:
894 return f"{unlisted[0].filename} cannot be listed ({unlisted[0].strerror})"
895 return ""
899 """The refusal's words for *directory*, which this user may not change."""
900 return f"{directory} belongs to {_owner(directory)} and this user may not change it"
904 """The name of the user who owns *path*; its number when the system has none."""
905 uid = os.stat(path).st_uid
906 if sys.platform != "win32":906 ↛ 911line 906 didn't jump to line 911 because the condition on line 906 was always true
907 import pwd
909 with contextlib.suppress(KeyError):
910 return pwd.getpwuid(uid).pw_name
911 return f"uid {uid}"
915 """Remove *path* whole, going on past each part that refuses; what stayed.
917 Every part this user may remove goes, so what stays is what refused
918 and the directories above it. Each entry is a path and the system's
919 reason, the deepest first. A file marked read-only on Windows is
920 made writable and removed, as git marks its pack files.
921 """
922 stayed: list[str] = []
924 def note(error: OSError) -> None:
925 stayed.append(f"{error.filename}: {error.strerror}")
927 for current, directories, files in os.walk(path, topdown=False, onerror=note):
928 linked = [name for name in directories if os.path.islink(Path(current, name))]
929 for name in (*files, *linked):
930 try:
931 _unlink(str(Path(current, name)))
932 except OSError as error:
933 note(error)
934 try:
935 os.rmdir(current)
936 except OSError as error:
937 # A directory that holds what stayed is no cause of its own.
938 if error.errno != errno.ENOTEMPTY:
939 note(error)
940 if not stayed and os.path.lexists(path):
941 stayed.append(f"{path}: {os.strerror(errno.ENOTEMPTY)}")
942 return stayed
946 """Remove the file or link at *path*; a Windows read-only one is made writable."""
947 try:
948 UNLINK(path)
949 except PermissionError:
950 if sys.platform != "win32":
951 raise
952 os.chmod(path, stat.S_IWRITE)
953 UNLINK(path)
957 """The first of *stayed*, and how many more there are."""
958 more = len(stayed) - 1
959 return stayed[0] + (f" and {more} more path(s)" if more else "")
963 """The command that makes everything under *directory* removable by this user."""
964 if sys.platform == "win32":
965 return f"close each program that holds a file under {directory} open"
966 return f"sudo chown -R {getpass.getuser()} {directory}"
970 """Drop the cascade's forge keys when they name *url*, a forge that is gone."""
971 from livery.footman import config_dir
973 path = config_dir() / ".repo.shared.env"
974 if not path.is_file():974 ↛ 975line 974 didn't jump to line 975 because the condition on line 974 was never true
975 return
976 lines = path.read_text("utf-8").splitlines()
977 if f"GITEA_URL={url}" not in lines:977 ↛ 978line 977 didn't jump to line 978 because the condition on line 977 was never true
978 return
979 kept = [
980 line
981 for line in lines
982 if line.split("=", 1)[0].strip() not in ("GITEA_URL", "GITEA_TOKEN")
983 ]
984 path.write_text("\n".join(kept) + ("\n" if kept else ""), encoding="utf-8")
988 """Remove the rig's shared caches, naming each; the lines to print.
990 Each cache is checked before it is removed, as an environment is
991 ([livery.workshop._devenv.remove][]).
993 Raises:
994 Failed: when a part of a cache cannot be removed, naming it, the
995 reason, and the command that makes it removable; the caches
996 before it are removed.
997 """
998 lines: list[str] = []
999 for name in CACHES:
1000 target = cache_dir() / name
1001 if not target.is_dir():
1002 continue
1003 blocker = removal_blocker(target)
1004 stayed = [blocker] if blocker else remove_tree(target)
1005 if stayed:
1006 fail(
1007 f"cache: {name}: {_stayed(stayed)}, so it is not removed. Make it"
1008 f" this user's, then purge again: {_hand_back(target)}"
1009 )
1010 lines.append(f" cache: {name} removed ({target})")
1011 if not lines:
1012 lines.append(" cache: nothing to remove")
1013 return lines
1017 """One line on *env*: its mode, its URL, and what runs."""
1018 values = env.values()
1019 if env.mode == "docker":1019 ↛ 1020line 1019 didn't jump to line 1020 because the condition on line 1019 was never true
1020 return f" {env.name}: docker, {values.get('GITEA_URL', '')}"
1021 running = sum(1 for pid_file in _pid_files(env) if ALIVE(_read_pid(pid_file)))
1022 total = len(_pid_files(env))
1023 labels = values.get("LABELS", "")
1024 return (
1025 f" {env.name}: host, {values.get('GITEA_URL', '')}, {running}/{total}"
1026 f" process(es) running" + (f", runners {labels}" if labels else "")
1027 )
1030# --- the verbs ---------------------------------------------------------------------
1035 env: Annotated[str, doc("the environment's name")] = DEFAULT_ENV,
1036 mode: Annotated[str, doc("host or docker")] = "host",
1037 runners: Annotated[str, doc("the runners: host, or host*<n>")] = "host",
1038 offline: Annotated[bool, doc("supply the binaries from the store alone")] = False,
1039) -> None:
1040 """Bring an environment up by name; idempotent, and the recovery procedure.
1042 Host mode starts Gitea and each runner as processes of this
1043 machine from the store's records, seeds the administrator, the
1044 API token and the organisation, registers each runner once under
1045 its label, and makes the environment the cascade's current forge.
1046 Docker mode is the compose rig, the one environment named `dev`.
1047 """
1048 if mode not in MODES:
1049 fail(f"--mode={mode!r} is not one of {', '.join(MODES)}")
1050 found = environment(env)
1051 if found.mode and found.mode != mode:
1052 fail(
1053 f"{env} exists in {found.mode} mode; `{footman.prog()} devenv.rm"
1054 f" --env={env}` first, or name another environment"
1055 )
1056 shapes = parse_runners(runners)
1057 if mode == "docker":1057 ↛ 1058line 1057 didn't jump to line 1058 because the condition on line 1057 was never true
1058 up_docker(found)
1059 return
1060 up_host(found, shapes, offline=offline)
1065 """List the environments: mode, URL, and what runs."""
1066 found = environments()
1067 if not found:
1068 print(f" no environments under {envs_dir()}")
1069 return
1070 for env in found:
1071 print(describe(env))
1076 env: Annotated[str, doc("the environment's name")] = DEFAULT_ENV,
1077) -> None:
1078 """Stop an environment's processes and keep its state."""
1079 found = environment(env)
1080 if not found.mode:
1081 fail(f"{env}: no such environment; `{footman.prog()} devenv.ls` lists them")
1082 for line in down(found):
1083 print(line)
1088 env: Annotated[str, doc("the environment's name")] = DEFAULT_ENV,
1089 purge_caches: Annotated[bool, doc("remove the rig's shared caches too")] = False,
1090) -> None:
1091 """Stop an environment and remove its directory; the caches stay unless asked."""
1092 found = environment(env)
1093 for line in remove(found):
1094 print(line)
1095 if purge_caches:
1096 for line in purge_cache():
1097 print(line)