python-dmon 0.4.0__py3-none-any.whl → 0.5.0__py3-none-any.whl

dmon/api.py

@@ -17,6 +17,7 @@ from .control import (
     stop_single,
     task_snapshot,
     task_environment,
+    task_owns_listener,
 )
 from .results import (
     ActionResult,
@@ -39,10 +40,19 @@ class DmonConfigError(DmonError):
 
 
 class Dmon:
+    """Silent, structured Python interface to dmon task operations.
+
+    Args:
+        config: Optional dmon YAML/TOML file or directory. When omitted, dmon
+            uses the same configuration discovery rules as the CLI.
+    """
+
     def __init__(self, config: Optional[Union[str, os.PathLike]] = None) -> None:
         self.config = str(config) if config is not None else None
 
     def start(self, *tasks: str) -> BatchResult:
+        """Start one or more configured tasks in the background."""
+
         names, configs, _ = self._tasks(tasks)
         self._validate_environments(configs)
         results = []
@@ -59,12 +69,14 @@ class Dmon:
                         ok=result.exit_code == 0,
                         exit_code=result.exit_code,
                         snapshot=snapshot,
-                        error="" if result.exit_code == 0 else "task did not start",
+                        error=result.error,
                     )
                 )
         return BatchResult("start", tuple(results))
 
     def stop(self, *tasks: str) -> BatchResult:
+        """Stop one or more configured tasks using their recorded identities."""
+
         names, configs, _ = self._tasks(tasks)
         results = []
         with self._operation():
@@ -82,6 +94,8 @@ class Dmon:
         return BatchResult("stop", tuple(results))
 
     def restart(self, *tasks: str) -> BatchResult:
+        """Restart one or more configured tasks."""
+
         names, configs, _ = self._tasks(tasks)
         self._validate_environments(configs)
         results = []
@@ -103,6 +117,8 @@ class Dmon:
         return BatchResult("restart", tuple(results))
 
     def status(self, task: Optional[str] = None) -> TaskResult:
+        """Inspect one configured task without changing its lifecycle."""
+
         names, configs, _ = self._tasks(() if task is None else (task,))
         if len(names) != 1:
             raise DmonConfigError("status requires exactly one task")
@@ -110,6 +126,8 @@ class Dmon:
             return self._task_result(names[0], Path(configs[0].meta_path))
 
     def list_tasks(self) -> Tuple[TaskResult, ...]:
+        """Return recorded task results for the selected project."""
+
         project = self._project()
         results = []
         with self._operation():
@@ -126,6 +144,8 @@ class Dmon:
         return tuple(results)
 
     def stack_status(self, stack: str) -> StackResult:
+        """Inspect one recorded stack without changing its lifecycle."""
+
         if not isinstance(stack, str) or not stack:
             raise DmonConfigError("stack name must not be empty")
         project = self._project()
@@ -138,6 +158,8 @@ class Dmon:
             )
 
     def list_stacks(self) -> Tuple[StackResult, ...]:
+        """Return recorded stack results for the selected project."""
+
         project = self._project()
         results = []
         with self._operation():
@@ -154,6 +176,8 @@ class Dmon:
         timeout: Optional[float] = None,
         interval: Optional[float] = None,
     ) -> Tuple[WaitResult, ...]:
+        """Wait for configured readiness without starting or stopping tasks."""
+
         for name, value in (("timeout", timeout), ("interval", interval)):
             if value is not None and (
                 not isinstance(value, (int, float))
@@ -208,6 +232,13 @@ class Dmon:
                         process_running=lambda meta=meta: check_running(
                             meta.pid, meta.create_time
                         ),
+                        listener_owned=(
+                            lambda: task_owns_listener(
+                                meta, spec.tcp_host, spec.tcp_port
+                            )
+                        )
+                        if spec.require_owned
+                        else None,
                     )
                 )
         return tuple(results)

dmon/cli.py

@@ -43,6 +43,7 @@ from .constants import (
 from .logs import show_stack_logs
 from .inspection import inspect_stack, inspect_task
 from .readiness import ready_spec, wait_for_readiness
+from .repair import request_repair
 from .results import WaitResult
 from .serialization import stack_result_data, task_result_data, wait_result_data
 from .supervisor import (
@@ -308,6 +309,17 @@ def main():
         nargs="?",
     )
 
+    sp_stack_repair = stack_subparsers.add_parser(
+        "repair", help="Repair one exited member without restarting peers"
+    )
+    sp_stack_repair.add_argument("stack")
+    sp_stack_repair.add_argument("task")
+    sp_stack_repair.add_argument("--timeout", type=float, default=30)
+    sp_stack_repair.add_argument(
+        "--operation-id", help="Recheck the same repair without starting another"
+    )
+    sp_stack_repair.add_argument("--format", choices=("human", "json"), default="human")
+
     sp_stack_status = stack_subparsers.add_parser(
         "status",
         help="Show stack and member task status",
@@ -370,6 +382,7 @@ def main():
         sp_stack_up,
         sp_stack_down,
         sp_stack_restart,
+        sp_stack_repair,
         sp_stack_status,
         sp_stack_logs,
         sp_stack_list,
@@ -393,6 +406,7 @@ def main():
             "up": sp_stack_up,
             "down": sp_stack_down,
             "restart": sp_stack_restart,
+            "repair": sp_stack_repair,
             "status": sp_stack_status,
             "logs": sp_stack_logs,
             "list": sp_stack_list,
@@ -477,6 +491,16 @@ def main():
             meta_path = Path(STACK_META_PATH_TEMPLATE.format(stack=stack))
         except Exception as error:
             sp.error(str(error))
+        if args.stack_command == "repair":
+            sp.exit(
+                request_repair(
+                    meta_path,
+                    args.task.lower(),
+                    args.timeout,
+                    args.operation_id,
+                    args.format == "json",
+                )
+            )
         if args.stack_command == "down":
             sp.exit(stop_stack(meta_path))
         if args.stack_command == "status":
@@ -557,7 +581,9 @@ def main():
             meta_paths.extend([META_PATH_TEMPLATE.format(task=task) for task in tasks])
 
         # Remove duplicates
-        unique_meta_paths = sorted(set(Path(p).resolve() for p in meta_paths))
+        unique_meta_paths = sorted(
+            set(Path(p).absolute().resolve() for p in meta_paths)
+        )
 
         if args.command == "stop":
             sp.exit(stop(unique_meta_paths))

dmon/config.py

@@ -1,4 +1,5 @@
 import math
+import ipaddress
 import sys
 from pathlib import Path
 from typing import Dict, List, Optional, Sequence, Tuple, Union, cast
@@ -216,7 +217,7 @@ def validate_task(task, name: str) -> DmonTaskConfig:
 def validate_ready(ready, name: str) -> Dict[str, object]:
     if not isinstance(ready, dict):
         raise TypeError(f"Task '{name}' 'ready' field must be a table")
-    allowed = {"http", "tcp", "command", "timeout", "interval"}
+    allowed = {"http", "tcp", "command", "timeout", "interval", "require_owned"}
     unknown = set(ready) - allowed
     if unknown:
         raise TypeError(
@@ -262,6 +263,26 @@ def validate_ready(ready, name: str) -> Dict[str, object]:
             raise TypeError(
                 f"Task '{name}' readiness 'tcp' value must contain a host string and valid port"
             )
+    if "require_owned" in ready:
+        if not isinstance(ready["require_owned"], bool):
+            raise TypeError(
+                f"Task '{name}' readiness 'require_owned' must be a boolean"
+            )
+        if ready["require_owned"]:
+            host = (
+                urlsplit(ready["http"]).hostname
+                if "http" in ready
+                else ready.get("tcp", {}).get("host", "")
+            )
+            try:
+                local = ipaddress.ip_address(host).is_loopback
+            except ValueError:
+                local = False
+            if not local:
+                raise TypeError(
+                    f"Task '{name}' readiness 'require_owned' needs an HTTP or TCP "
+                    "probe with a literal loopback IP address"
+                )
     for key, default in (("timeout", 30.0), ("interval", 0.2)):
         value = ready.get(key, default)
         if (

dmon/control.py

@@ -3,9 +3,9 @@ from contextvars import ContextVar
 from dataclasses import dataclass
 import os
 from pathlib import Path
-import shlex
 import shutil
 import signal
+import socket
 import sys
 import subprocess
 import time
@@ -19,7 +19,7 @@ from termcolor import colored
 
 from .constants import DEFAULT_META_DIR, META_SUFFIX, ON_WINDOWS
 from .results import CommandSnapshot, TaskSnapshot
-from .types import DmonTaskConfig, DmonMeta, PathType
+from .types import DmonTaskConfig, DmonMeta, PathType, ProcessIdentity
 from .utils import len_ansi, pad_ansi
 
 
@@ -49,6 +49,7 @@ def diagnostic_output(stream: TextIO) -> Iterator[None]:
 class StartResult:
     exit_code: int
     meta: Optional[DmonMeta] = None
+    error: str = ""
 
 
 def background_process_kwargs() -> dict:
@@ -102,8 +103,10 @@ def start_single(cfg: DmonTaskConfig) -> int:
 
 
 def start_single_result(cfg: DmonTaskConfig) -> StartResult:
-    meta_path = Path(cfg.meta_path).resolve()
-    log_path = Path(cfg.log_path).resolve()
+    # Python 3.8 on Windows may leave resolve() relative if a parent is missing.
+    # Anchor before resolving so newly created records have durable locations.
+    meta_path = Path(cfg.meta_path).absolute().resolve()
+    log_path = Path(cfg.log_path).absolute().resolve()
     cwd = Path(cfg.cwd).resolve()
 
     try:
@@ -117,7 +120,7 @@ def start_single_result(cfg: DmonTaskConfig) -> StartResult:
             ),
             file=sys.stderr,
         )
-        return StartResult(1)
+        return StartResult(1, error=f"cannot read metadata {meta_path}: {error}")
     if existing_meta and existing_meta.state == "starting":
         print(
             colored(
@@ -131,7 +134,7 @@ def start_single_result(cfg: DmonTaskConfig) -> StartResult:
             "If the earlier start was interrupted, run 'dmon stop' to remove its reservation.",
             file=sys.stderr,
         )
-        return StartResult(1)
+        return StartResult(1, error="task is already being started")
     if existing_meta and check_running(existing_meta.pid, existing_meta.create_time):
         print(
             f"{colored('Start failed: meta file already exists', color='red', attrs=['bold'])}",
@@ -142,8 +145,18 @@ def start_single_result(cfg: DmonTaskConfig) -> StartResult:
             "\nRun 'dmon status' / 'dmon list' to check, or 'dmon stop' to stop it.",
             file=sys.stderr,
         )
-        return StartResult(1)
+        return StartResult(1, error="task is already running")
     if existing_meta:
+        if any(
+            check_running(child.pid, child.create_time)
+            for child in existing_meta.descendants
+        ) or unverified_group_remains(existing_meta):
+            print(
+                f"Start failed: task '{cfg.task}' still has residual processes; "
+                "stop its owning stack or inspect its preserved metadata first.",
+                file=sys.stderr,
+            )
+            return StartResult(1, error="task still has residual processes")
         print(
             colored(
                 f"Removing stale metadata for exited task '{cfg.task}'.",
@@ -167,7 +180,8 @@ def start_single_result(cfg: DmonTaskConfig) -> StartResult:
             ),
             file=sys.stderr,
         )
-        return StartResult(1)
+        # Detailed environment diagnostics belong in the log, not persisted state.
+        return StartResult(1, error="environment setup failed; see startup diagnostics")
 
     shell = isinstance(cfg.cmd, str)
 
@@ -203,11 +217,11 @@ def start_single_result(cfg: DmonTaskConfig) -> StartResult:
             ),
             file=sys.stderr,
         )
-        return StartResult(1)
+        return StartResult(1, error="another dmon process is starting this task")
 
     try:
         if cfg.log_rotate:
-            rotate_log_path = Path(cfg.rotate_log_path).resolve()
+            rotate_log_path = Path(cfg.rotate_log_path).absolute().resolve()
 
             meta.rotate_log_path = str(rotate_log_path)
             meta.log_max_size = cfg.log_max_size
@@ -219,8 +233,9 @@ def start_single_result(cfg: DmonTaskConfig) -> StartResult:
 
             # use runner to start user process and handle log rotation
             if isinstance(command, str):
-                # when cmd is str, we need to split it into list for subprocess
-                cmd = shlex.split(command)
+                # Transport shell text as one argument. Splitting and joining
+                # would discard quotes, escapes, and significant whitespace.
+                cmd = [command]
             else:
                 cmd = command
             args = [
@@ -271,15 +286,31 @@ def start_single_result(cfg: DmonTaskConfig) -> StartResult:
                 )
     except OSError as error:
         meta_path.unlink(missing_ok=True)
+        detail = str(error)
+        if not error.filename and isinstance(cfg.cmd, list):
+            # CreateProcess may omit the filename. Keep the executable useful
+            # for diagnostics without copying potentially sensitive arguments.
+            detail = f"command {cfg.cmd[0]!r}: {detail}"
+        if (
+            isinstance(error, FileNotFoundError)
+            and cfg.override_env
+            and env is not None
+            and "PATH" not in env
+            and cwd.is_dir()
+        ):
+            detail += (
+                "; override_env=true removes the inherited environment, including PATH. "
+                "Use env without override_env for variable overrides, or supply PATH explicitly."
+            )
         print(
             colored(
-                f"Start failed for task '{cfg.task}': {error}",
+                f"Start failed for task '{cfg.task}': {detail}",
                 color="red",
                 attrs=["bold"],
             ),
             file=sys.stderr,
         )
-        return StartResult(1)
+        return StartResult(1, error=detail)
 
     meta.pid = proc.pid
     meta.state = "running"
@@ -313,7 +344,7 @@ def start_single_result(cfg: DmonTaskConfig) -> StartResult:
             ),
             file=sys.stderr,
         )
-        return StartResult(1)
+        return StartResult(1, error=f"cannot save metadata: {error}")
 
     print_status(meta)
     with warnings.catch_warnings():
@@ -397,6 +428,8 @@ def stop_single(
     try:
         proc = psutil.Process(pid)
     except (psutil.NoSuchProcess, ValueError):
+        if stop_owned_processes(meta, timeout):
+            return 1
         print(
             colored(
                 f"Process {pid} not found (already exited); removing stale meta file",
@@ -411,6 +444,8 @@ def stop_single(
 
     # check if it's the same process by comparing create_time
     if not check_same_process(proc, meta.create_time):
+        if stop_owned_processes(meta, timeout):
+            return 1
         print(
             colored(
                 f"Warning: PID {pid} exists but create_time does not match (maybe reused by another process); removing stale meta file",
@@ -423,6 +458,8 @@ def stop_single(
         meta_path.unlink(missing_ok=True)
         return 0
     if not process_is_alive(proc):
+        if stop_owned_processes(meta, timeout):
+            return 1
         print(
             colored(
                 f"Process {pid} already exited; removing stale meta file",
@@ -435,13 +472,119 @@ def stop_single(
         meta_path.unlink(missing_ok=True)
         return 0
 
-    ret = terminate_process(proc, timeout)
+    refresh_descendants(meta)
+    ret = stop_owned_processes(meta, timeout)
     print_status(meta)
     if ret == 0:
         meta_path.unlink(missing_ok=True)
     return ret
 
 
+def owned_identities(meta: DmonMeta) -> List[ProcessIdentity]:
+    identities = list(meta.descendants)
+    if meta.pid > 0 and meta.create_time >= 0:
+        identities.insert(0, ProcessIdentity(meta.pid, meta.create_time))
+    return identities
+
+
+def refresh_descendants(meta: DmonMeta) -> bool:
+    """Retain observed live identities, even after their parent has exited.
+
+    This is ancestry evidence within the user's trust domain, not a security
+    boundary. Children that escape before observation cannot be recovered by
+    guessing from names, ports or process group numbers.
+    """
+    observed = set()
+    for identity in owned_identities(meta):
+        process = get_unique_process(identity.pid, identity.create_time)
+        if process is None:
+            continue
+        if identity.pid != meta.pid:
+            observed.add(identity)
+        try:
+            children = process.children(recursive=True)
+            if not check_same_process(process, identity.create_time):
+                continue
+            for child in children:
+                if process_is_alive(child):
+                    observed.add(ProcessIdentity(child.pid, child.create_time()))
+        except (psutil.NoSuchProcess, psutil.AccessDenied):
+            continue
+    descendants = sorted(observed, key=lambda item: (item.pid, item.create_time))
+    changed = descendants != meta.descendants
+    meta.descendants = descendants
+    return changed
+
+
+def task_owns_listener(meta: DmonMeta, host: str, port: int) -> bool:
+    """Positive evidence only; unavailable process sockets never imply ownership.
+
+    Callers validate a literal loopback endpoint. Never inspect or signal a
+    foreign listener, and never treat a successful network probe as identity.
+    """
+    root = get_unique_process(meta.pid, meta.create_time)
+    if root is None:
+        return False
+    try:
+        processes = [root, *root.children(recursive=True)]
+        for process in processes:
+            try:
+                birth = process.create_time()
+                for connection in process.net_connections(kind="tcp"):
+                    if (
+                        connection.status == psutil.CONN_LISTEN
+                        and connection.laddr.port == port
+                        and (
+                            connection.laddr.ip == host
+                            or connection.laddr.ip
+                            == (
+                                "::"
+                                if connection.family == socket.AF_INET6
+                                else "0.0.0.0"
+                            )
+                            and (
+                                (":" in host) == (connection.family == socket.AF_INET6)
+                            )
+                        )
+                        and check_running(process.pid, birth)
+                        and check_running(meta.pid, meta.create_time)
+                    ):
+                        return True
+            except (psutil.NoSuchProcess, psutil.AccessDenied):
+                continue
+    except (psutil.NoSuchProcess, psutil.AccessDenied):
+        pass
+    return False
+
+
+def stop_owned_processes(meta: DmonMeta, timeout: float) -> int:
+    """Stop verified identities; preserve evidence when cleanup is uncertain."""
+    failed = False
+    for identity in owned_identities(meta):
+        process = get_unique_process(identity.pid, identity.create_time)
+        if process is not None and terminate_process(process, timeout):
+            failed = True
+    if unverified_group_remains(meta):
+        print(
+            f"Task '{meta.task}' exited but its former process group still has "
+            "unverified members; refusing to signal them. Metadata was preserved.",
+            file=sys.stderr,
+        )
+        failed = True
+    return int(failed)
+
+
+def unverified_group_remains(meta: DmonMeta) -> bool:
+    if ON_WINDOWS or meta.pid <= 0 or not meta.popen_kwargs.get("start_new_session"):
+        return False
+    try:
+        if not check_same_process(psutil.Process(meta.pid), meta.create_time):
+            return False  # A recycled group leader is not ours.
+    except (psutil.NoSuchProcess, ValueError):
+        pass
+    return process_group_exists(meta.pid)
+
+
 def terminate_process(proc: psutil.Process, timeout: float) -> int:
     if not ON_WINDOWS:
         try:
@@ -666,6 +809,11 @@ def task_snapshot(meta: DmonMeta) -> TaskSnapshot:
         log_backup_count=meta.log_backup_count,
         rotate_log_max_size=meta.rotate_log_max_size,
         rotate_log_backup_count=meta.rotate_log_backup_count,
+        live_descendant_pids=tuple(
+            identity.pid
+            for identity in meta.descendants
+            if check_running(identity.pid, identity.create_time)
+        ),
     )
 
 

dmon/readiness.py

@@ -6,6 +6,7 @@ import subprocess
 import time
 from typing import Callable, Mapping, Optional
 from urllib.request import urlopen
+from urllib.parse import urlsplit
 
 from .results import CommandSnapshot, WaitResult
 
@@ -22,6 +23,7 @@ class ReadySpec:
     tcp_host: str = ""
     tcp_port: int = 0
     command: CommandSnapshot = ""
+    require_owned: bool = False
 
 
 def ready_spec(
@@ -37,11 +39,15 @@ def ready_spec(
         interval if interval is not None else ready.get("interval", 0.2)
     )
     if "http" in ready:
+        url = urlsplit(str(ready["http"]))
         return ReadySpec(
             "http",
             resolved_timeout,
             resolved_interval,
             http_url=str(ready["http"]),
+            tcp_host=url.hostname or "",
+            tcp_port=url.port or (443 if url.scheme == "https" else 80),
+            require_owned=bool(ready.get("require_owned")),
         )
     if "tcp" in ready:
         tcp = ready["tcp"]
@@ -52,6 +58,7 @@ def ready_spec(
             resolved_interval,
             tcp_host=str(tcp["host"]),
             tcp_port=int(tcp["port"]),
+            require_owned=bool(ready.get("require_owned")),
         )
     command = ready.get("command", "")
     if isinstance(command, list):
@@ -76,10 +83,12 @@ def wait_for_readiness(
     env: Optional[Mapping[str, str]],
     process_running: Optional[Check] = None,
     stop_requested: Optional[Check] = None,
+    listener_owned: Optional[Check] = None,
 ) -> WaitResult:
     started = time.monotonic()
     deadline = started + spec.timeout
     attempts = 0
+    ownership_verified = not spec.require_owned
     while True:
         if stop_requested is not None and stop_requested():
             return WaitResult(
@@ -99,17 +108,43 @@ def wait_for_readiness(
             return WaitResult(
                 target,
                 ready,
-                "ready" if ready else "timeout",
+                "ready"
+                if ready
+                else "timeout"
+                if ownership_verified
+                else "listener-unverified",
                 time.monotonic() - started,
                 attempts,
             )
         if spec.kind != "process":
             attempts += 1
             attempt_timeout = min(max(1.0, spec.interval), remaining)
-            if probe(spec, cwd=cwd, env=env, timeout=attempt_timeout):
-                return WaitResult(
-                    target, True, "ready", time.monotonic() - started, attempts
-                )
+            ownership_verified = not spec.require_owned or (
+                listener_owned is not None and listener_owned()
+            )
+            if ownership_verified and probe(
+                spec, cwd=cwd, env=env, timeout=attempt_timeout
+            ):
+                if process_running is not None and not process_running():
+                    return WaitResult(
+                        target,
+                        False,
+                        "process-exited",
+                        time.monotonic() - started,
+                        attempts,
+                    )
+                if stop_requested is not None and stop_requested():
+                    return WaitResult(
+                        target, False, "stopped", time.monotonic() - started, attempts
+                    )
+                if spec.require_owned and (
+                    listener_owned is None or not listener_owned()
+                ):
+                    ownership_verified = False
+                else:
+                    return WaitResult(
+                        target, True, "ready", time.monotonic() - started, attempts
+                    )
         time.sleep(min(spec.interval, max(0.0, deadline - time.monotonic())))