docker-orb 1.0.0__py3-none-any.whl

docker_orb/compose.py

@@ -0,0 +1,391 @@
+"""
+Docker Compose abstraction layer.
+
+All interaction goes through this module via subprocess calls to the user's
+existing `docker` CLI (Compose v2, i.e. `docker compose ...`) — inheriting
+their Docker context/auth. No Python Docker SDK dependency, same philosophy
+as kube-orb's kubectl.py: shell out, parse JSON, keep the rest of the app
+ignorant of the underlying tool.
+
+Log streaming uses `docker logs -f --timestamps <container>` per container
+rather than a single multiplexed `docker compose logs -f`. Functionally this
+is the same data `docker compose logs` streams (compose containers are
+ordinary Docker containers carrying `com.docker.compose.*` labels) but
+keeping one subprocess per container mirrors kube-orb's per-pod architecture
+exactly, so the merge/color/filter machinery in viewer/ needed no changes.
+
+NOTE: --since duration semantics below are carried over from kube-orb's
+kubectl quirk-handling as a defensive default. Docker's own duration parsing
+for `docker logs --since` has not been verified against a live daemon in
+this environment — worth a smoke test against a real `docker compose`
+project before relying on it in production.
+"""
+from __future__ import annotations
+
+import asyncio
+import json
+import re
+import subprocess
+from collections.abc import AsyncIterator
+from datetime import datetime
+
+from .models import Service, LogLine, Container, ContainerStatus
+
+
+# ─── Helpers ─────────────────────────────────────────────────────────────────
+
+def _run(args: list[str], check: bool = True) -> str:
+    """Run a `docker` command, return stdout as str. Raises on non-zero exit."""
+    result = subprocess.run(
+        ["docker", *args],
+        capture_output=True,
+        text=True,
+        check=check,
+    )
+    return result.stdout.strip()
+
+
+def _run_json_lines(args: list[str]) -> list[dict]:
+    """
+    Run a docker/compose command that emits `--format json` output and parse
+    it. Compose has shipped two shapes for this over the years: a single
+    JSON array, or newline-delimited JSON objects (one per line). Handle
+    both rather than pinning to one Compose version.
+    """
+    out = _run(args)
+    if not out:
+        return []
+    try:
+        parsed = json.loads(out)
+        return parsed if isinstance(parsed, list) else [parsed]
+    except json.JSONDecodeError:
+        pass
+    items = []
+    for line in out.splitlines():
+        line = line.strip()
+        if not line:
+            continue
+        items.append(json.loads(line))
+    return items
+
+
+# docker logs --timestamps prefixes each line with an RFC3339Nano timestamp
+# (up to 9 fractional-second digits) and a space, e.g.
+# "2026-07-08T12:34:56.789012345Z log line content here".
+_TIMESTAMP_RE = re.compile(
+    r"^(\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2})(?:\.(\d+))?(Z|[+-]\d{2}:\d{2}) "
+)
+
+
+def _split_timestamp(raw: str) -> tuple[datetime | None, str]:
+    """
+    Split a `docker logs --timestamps` line into (parsed timestamp, content).
+    Returns (None, raw) unchanged if the line doesn't start with a
+    recognizable timestamp (defensive — should always match in practice).
+    """
+    m = _TIMESTAMP_RE.match(raw)
+    if not m:
+        return None, raw
+    base, frac, tz = m.groups()
+    # datetime.fromisoformat only accepts up to microsecond (6-digit)
+    # precision on Python 3.10/3.11; truncate rather than pad-and-fail.
+    frac = (frac or "").ljust(6, "0")[:6]
+    tz = "+00:00" if tz == "Z" else tz
+    try:
+        timestamp = datetime.fromisoformat(f"{base}.{frac}{tz}")
+    except ValueError:
+        return None, raw
+    return timestamp, raw[m.end():]
+
+
+# A --since value that is empty/zero in every unit ("0", "0s", "0h", ...).
+_ZERO_SINCE_RE = re.compile(r"^0+(?:\.0+)?(ns|us|µs|ms|s|m|h)?$")
+
+
+def _normalize_since(since: str | None) -> str:
+    """
+    Without a meaningful --since bound, `docker logs -f` dumps a container's
+    entire buffered history before it starts following. For a live stream
+    that means replaying everything the container has ever logged instead
+    of only new lines. Substitute a tiny positive duration for None/empty/
+    zero so the default (and a user typing a literal "0") gets "only new
+    lines" behavior instead of an unbounded history dump — same defensive
+    trick kube-orb uses for kubectl.
+    """
+    if not since or _ZERO_SINCE_RE.match(since.strip()):
+        return "1s"
+    return since
+
+
+def wants_backfill(since: str | None) -> bool:
+    """
+    True if `since` represents a genuine, non-trivial look-back window —
+    i.e. whether the caller should expect (and handle) a historical
+    backfill burst. Mirrors _normalize_since()'s zero-detection.
+    """
+    return bool(since) and not _ZERO_SINCE_RE.match(since.strip())
+
+
+# ─── Context / project ───────────────────────────────────────────────────────
+
+def get_current_project() -> str:
+    """
+    Return the Compose project name for the current working directory, the
+    way `docker compose` itself would resolve it (COMPOSE_PROJECT_NAME env
+    var, `name:` in the compose file, or the containing directory name).
+    Falls back to the first running project, then 'default', if the cwd
+    isn't a compose project.
+    """
+    try:
+        data = json.loads(_run(["compose", "config", "--format", "json"]))
+        name = data.get("name")
+        if name:
+            return name
+    except (subprocess.CalledProcessError, json.JSONDecodeError):
+        pass
+    projects = get_projects()
+    return projects[0] if projects else "default"
+
+
+def get_projects() -> list[str]:
+    """Return names of all Compose projects Docker currently knows about."""
+    items = _run_json_lines(["compose", "ls", "--all", "--format", "json"])
+    return [item["Name"] for item in items if item.get("Name")]
+
+
+# ─── Services / containers ────────────────────────────────────────────────────
+
+def _list_containers(project: str) -> list[dict]:
+    """Raw `docker compose ps` rows for every container in a project."""
+    return _run_json_lines([
+        "compose", "-p", project, "ps", "--all", "--format", "json",
+    ])
+
+
+def get_services(project: str) -> list[Service]:
+    """
+    Return services in the project, each with the count of containers
+    currently backing it (a service may have 0 if it isn't running, or
+    more than 1 if scaled).
+    """
+    rows = _list_containers(project)
+    counts: dict[str, int] = {}
+    for row in rows:
+        name = row.get("Service")
+        if name:
+            counts[name] = counts.get(name, 0) + 1
+
+    # Include services defined in the compose file even if currently
+    # stopped (0 containers), so they're still selectable in the wizard.
+    try:
+        defined = json.loads(_run(["compose", "-p", project, "config", "--format", "json"]))
+        for name in defined.get("services", {}):
+            counts.setdefault(name, 0)
+    except (subprocess.CalledProcessError, json.JSONDecodeError):
+        pass
+
+    services = [
+        Service(name=name, project=project, container_count=count)
+        for name, count in counts.items()
+    ]
+    return sorted(services, key=lambda s: s.name)
+
+
+def get_containers_for_service(project: str, service: Service) -> list[Container]:
+    """Return containers currently backing a single service."""
+    return get_containers_for_services(project, [service])
+
+
+def get_containers_for_services(project: str, services: list[Service]) -> list[Container]:
+    """Return all containers across a list of services."""
+    if not services:
+        return []
+    wanted = {s.name for s in services}
+    containers: list[Container] = []
+    for row in _list_containers(project):
+        service_name = row.get("Service")
+        if service_name not in wanted:
+            continue
+        containers.append(Container(
+            name=row.get("Name", ""),
+            project=project,
+            service=service_name,
+            phase=_state_to_phase(row.get("State", "")),
+            restart_count=0,   # not exposed by `ps`; see get_container_statuses
+            ready=(row.get("State") == "running" and row.get("Health", "") in ("", "healthy")),
+        ))
+    return containers
+
+
+def _state_to_phase(state: str) -> str:
+    """Map Docker's lowercase container State to a k8s-style Title Case phase."""
+    return {
+        "running": "Running",
+        "exited": "Exited",
+        "restarting": "Restarting",
+        "paused": "Paused",
+        "created": "Created",
+        "dead": "Dead",
+        "removing": "Removing",
+    }.get(state, state.title() or "Unknown")
+
+
+# ─── Container health polling ─────────────────────────────────────────────────
+
+def get_container_statuses(project: str, container_names: list[str]) -> list[ContainerStatus]:
+    """
+    Poll current health for a specific list of container names via
+    `docker inspect` (batched into a single call). Used by the health panel
+    on its interval. Unlike `docker compose ps`, inspect exposes the exact
+    RestartCount and StartedAt Docker tracks natively per container.
+    """
+    if not container_names:
+        return []
+
+    try:
+        raw = _run(["inspect", *container_names])
+        items = json.loads(raw) if raw else []
+    except subprocess.CalledProcessError as exc:
+        # `docker inspect` still prints JSON for the containers it *did*
+        # find on stdout even when one name doesn't exist; fall back to that.
+        try:
+            items = json.loads(exc.stdout) if exc.stdout else []
+        except (json.JSONDecodeError, TypeError):
+            return []
+
+    statuses = []
+    for item in items:
+        name = item.get("Name", "").lstrip("/")
+        state = item.get("State", {})
+        phase = _state_to_phase(state.get("Status", ""))
+        health = state.get("Health", {}).get("Status")
+        ready = state.get("Running", False) and health in (None, "healthy")
+        restarts = item.get("RestartCount", 0)
+
+        started_at = state.get("StartedAt")
+        age = 0.0
+        if started_at:
+            try:
+                start = datetime.fromisoformat(started_at.replace("Z", "+00:00"))
+                age = (datetime.now(start.tzinfo) - start).total_seconds()
+            except ValueError:
+                pass
+
+        labels = item.get("Config", {}).get("Labels", {}) or {}
+        service = labels.get("com.docker.compose.service", name)
+
+        statuses.append(ContainerStatus(
+            name=name,
+            service=service,
+            phase=phase,
+            restart_count=restarts,
+            ready=ready,
+            age_seconds=age,
+        ))
+
+    return statuses
+
+
+# ─── Log streaming ─────────────────────────────────────────────────────────────
+
+async def stream_logs(
+    container_name: str,
+    project: str,
+    since: str | None = None,
+    tail: int | None = None,
+) -> AsyncIterator[LogLine]:
+    """
+    Async generator yielding LogLine objects from a single container.
+    Runs `docker logs -f --timestamps <container>` in a subprocess, reads
+    lines as they arrive. Caller should run one coroutine per container and
+    merge with asyncio — same pattern as kube-orb's per-pod streaming.
+
+    Requests --timestamps so each LogLine gets a real log_timestamp (see
+    models.LogLine) — used to interleave a backfill burst across containers
+    correctly. The timestamp is parsed and stripped back out of `content`,
+    so displayed/matched text is identical to what --timestamps=false would
+    have produced.
+    """
+    args = ["docker", "logs", "-f", "--timestamps", "--since", _normalize_since(since)]
+    if tail is not None:
+        args += ["--tail", str(tail)]
+    args.append(container_name)
+
+    proc = await asyncio.create_subprocess_exec(
+        *args,
+        stdout=asyncio.subprocess.PIPE,
+        stderr=asyncio.subprocess.DEVNULL,
+    )
+
+    assert proc.stdout is not None
+    try:
+        while True:
+            line_bytes = await proc.stdout.readline()
+            if not line_bytes:
+                break
+            raw = line_bytes.decode(errors="replace").rstrip("\n")
+            log_time, content = _split_timestamp(raw)
+            yield LogLine(
+                container_name=container_name,
+                content=content,
+                log_timestamp=log_time,
+            )
+    finally:
+        try:
+            proc.kill()
+        except ProcessLookupError:
+            pass
+        await proc.wait()
+
+
+async def dump_logs(
+    container_name: str,
+    project: str,
+    since: str | None = None,
+    tail: int | None = None,
+) -> list[LogLine]:
+    """
+    Fetch a bounded set of log lines from a container (no follow).
+    Used in dump mode.
+    """
+    args = ["docker", "logs", "--timestamps=false"]
+    if since:
+        args += ["--since", since]
+    if tail is not None:
+        args += ["--tail", str(tail)]
+    args.append(container_name)
+
+    proc = await asyncio.create_subprocess_exec(
+        *args,
+        stdout=asyncio.subprocess.PIPE,
+        stderr=asyncio.subprocess.DEVNULL,
+    )
+    stdout, _ = await proc.communicate()
+    lines = stdout.decode(errors="replace").splitlines()
+    return [LogLine(container_name=container_name, content=line) for line in lines if line]
+
+
+# ─── Container restart actions ─────────────────────────────────────────────────
+
+def restart_container(container_name: str, project: str) -> bool:
+    """
+    Restart a single container in place (same container, same image —
+    Compose will not recreate it). Returns True on success.
+    """
+    try:
+        _run(["restart", container_name])
+        return True
+    except subprocess.CalledProcessError:
+        return False
+
+
+def restart_service(service_name: str, project: str) -> bool:
+    """
+    Recreate every container backing a service (picks up a new image/env if
+    one is available, unlike restart_container). Returns True on success.
+    """
+    try:
+        _run(["compose", "-p", project, "up", "-d", "--force-recreate", "--no-deps", service_name])
+        return True
+    except subprocess.CalledProcessError:
+        return False

docker_orb/config.py

@@ -0,0 +1,244 @@
+"""
+Config management for docker-orb.
+
+Storage layout under ~/.config/docker-orb/:
+  strings.yaml               — global saved string lists (filters/highlights/monitors)
+  projects/<proj>.yaml       — per-project saved session configs
+"""
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+import yaml
+
+from .models import HealthConfig, LogMode, SavedStrings, SessionConfig
+
+CONFIG_DIR = Path.home() / ".config" / "docker-orb"
+STRINGS_FILE = CONFIG_DIR / "strings.yaml"
+PROJECTS_DIR = CONFIG_DIR / "projects"
+
+
+# ─── Helpers ─────────────────────────────────────────────────────────────────
+
+def _ensure_dirs() -> None:
+    CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+    PROJECTS_DIR.mkdir(parents=True, exist_ok=True)
+
+
+def _load_yaml(path: Path) -> dict:
+    if not path.exists():
+        return {}
+    with path.open() as f:
+        return yaml.safe_load(f) or {}
+
+
+def _normalize_string_list(value: object) -> list[str]:
+    if not isinstance(value, list):
+        return []
+    normalized: list[str] = []
+    for item in value:
+        if isinstance(item, str):
+            normalized.append(item)
+        elif isinstance(item, list):
+            # A hand-edited strings.yaml with an unquoted bracketed literal
+            # like "[debug]" parses as YAML flow-sequence syntax (a nested
+            # list) instead of the string the user meant. Reconstruct the
+            # original bracketed text rather than losing the pattern or
+            # emitting Python's list repr (e.g. "['debug']").
+            normalized.append(f"[{', '.join(str(x) for x in item)}]")
+        elif item is not None:
+            normalized.append(str(item))
+    return normalized
+
+
+def _save_yaml(path: Path, data: dict) -> None:
+    _ensure_dirs()
+    with path.open("w") as f:
+        yaml.dump(data, f, default_flow_style=False, sort_keys=False, allow_unicode=True)
+
+
+# ─── String parsing ───────────────────────────────────────────────────────────
+
+def parse_string_input(raw: str) -> list[str]:
+    """
+    Parse a comma-separated input string into individual match patterns.
+    Quoted tokens (for strings containing commas) are handled.
+    Each token is stripped of whitespace.
+
+    Examples:
+        'ERROR, timeout'         → ['ERROR', 'timeout']
+        '/5[0-9]{2}/, WARN'     → ['/5[0-9]{2}/', 'WARN']
+        '"GET /api, POST /api"'  → ['GET /api, POST /api']
+    """
+    tokens: list[str] = []
+    current = ""
+    in_quote = False
+
+    for char in raw:
+        if char == '"':
+            in_quote = not in_quote
+        elif char == "," and not in_quote:
+            token = current.strip()
+            if token:
+                tokens.append(token)
+            current = ""
+        else:
+            current += char
+
+    token = current.strip()
+    if token:
+        tokens.append(token)
+
+    return tokens
+
+
+def is_regex_pattern(s: str) -> bool:
+    """Return True if the string uses /pattern/ regex syntax."""
+    return s.startswith("/") and s.endswith("/") and len(s) > 2
+
+
+def compile_pattern(s: str, ignore_case: bool = False) -> re.Pattern:
+    """
+    Compile a match string into a regex Pattern.
+    /pattern/ strings are compiled as regex.
+    Plain strings are compiled as literal (re.escape).
+    """
+    flags = re.IGNORECASE if ignore_case else 0
+    if is_regex_pattern(s):
+        return re.compile(s[1:-1], flags)
+    return re.compile(re.escape(s), flags)
+
+
+def matches(line: str, patterns: list[re.Pattern]) -> bool:
+    """Return True if line matches any of the compiled patterns."""
+    return any(p.search(line) for p in patterns)
+
+
+def compile_patterns(strings: list[str], ignore_case: bool = False) -> list[re.Pattern]:
+    return [compile_pattern(s, ignore_case) for s in strings]
+
+
+# ─── Saved strings ────────────────────────────────────────────────────────────
+
+def load_saved_strings() -> SavedStrings:
+    data = _load_yaml(STRINGS_FILE)
+    return SavedStrings(
+        filters=_normalize_string_list(data.get("filters", [])),
+        highlights=_normalize_string_list(data.get("highlights", [])),
+        monitors=_normalize_string_list(data.get("monitors", [])),
+    )
+
+
+def save_saved_strings(strings: SavedStrings) -> None:
+    _save_yaml(STRINGS_FILE, {
+        "filters": strings.filters,
+        "highlights": strings.highlights,
+        "monitors": strings.monitors,
+    })
+
+
+def add_to_saved_strings(
+    category: str,
+    new_strings: list[str],
+) -> None:
+    """
+    Append new_strings to the given category ('filters'|'highlights'|'monitors')
+    in the global strings file, deduplicating.
+    """
+    saved = load_saved_strings()
+    existing = getattr(saved, category)
+    merged = existing + [s for s in new_strings if s not in existing]
+    setattr(saved, category, merged)
+    save_saved_strings(saved)
+
+
+# ─── Session configs ──────────────────────────────────────────────────────────
+
+def _ns_config_path(project: str, name: str) -> Path:
+    safe_name = re.sub(r"[^\w\-]", "_", name)
+    return PROJECTS_DIR / project / f"{safe_name}.yaml"
+
+
+def list_saved_configs(project: str) -> list[str]:
+    """Return names of saved configs for a project."""
+    proj_dir = PROJECTS_DIR / project
+    if not proj_dir.exists():
+        return []
+    return [p.stem for p in sorted(proj_dir.glob("*.yaml"))]
+
+
+def list_all_saved_configs() -> list[tuple[str, str]]:
+    """Return (project, name) for every saved config across all projects."""
+    if not PROJECTS_DIR.exists():
+        return []
+    result = []
+    for proj_dir in sorted(PROJECTS_DIR.iterdir()):
+        if proj_dir.is_dir():
+            for p in sorted(proj_dir.glob("*.yaml")):
+                result.append((proj_dir.name, p.stem))
+    return result
+
+
+def load_session_config(project: str, name: str) -> SessionConfig | None:
+    path = _ns_config_path(project, name)
+    data = _load_yaml(path)
+    if not data:
+        return None
+
+    health_data = data.get("health", {})
+    return SessionConfig(
+        project=project,
+        services=data.get("services", []),
+        mode=LogMode(data.get("mode", "stream")),
+        tail=data.get("tail"),
+        since=data.get("since"),
+        filters=_normalize_string_list(data.get("filters", [])),
+        highlights=_normalize_string_list(data.get("highlights", [])),
+        monitors=_normalize_string_list(data.get("monitors", [])),
+        filters_ignore_case=data.get("filters_ignore_case", False),
+        highlights_ignore_case=data.get("highlights_ignore_case", False),
+        monitors_ignore_case=data.get("monitors_ignore_case", False),
+        line_wrap=data.get("line_wrap", True),
+        color_full_line=data.get("color_full_line", False),
+        json_format=data.get("json_format", False),
+        collapse_repeats=data.get("collapse_repeats", False),
+        health=HealthConfig(
+            enabled=health_data.get("enabled", False),
+            interval_minutes=health_data.get("interval_minutes", 5),
+            restart_threshold=health_data.get("restart_threshold", 1),
+        ),
+        name=name,
+    )
+
+
+def save_session_config(config: SessionConfig) -> None:
+    """Save a session config under its project. config.name must be set."""
+    if not config.name:
+        raise ValueError("SessionConfig.name must be set before saving")
+
+    proj_dir = PROJECTS_DIR / config.project
+    proj_dir.mkdir(parents=True, exist_ok=True)
+
+    path = _ns_config_path(config.project, config.name)
+    _save_yaml(path, {
+        "services": config.services,
+        "mode": config.mode.value,
+        "tail": config.tail,
+        "since": config.since,
+        "filters": config.filters,
+        "highlights": config.highlights,
+        "monitors": config.monitors,
+        "filters_ignore_case": config.filters_ignore_case,
+        "highlights_ignore_case": config.highlights_ignore_case,
+        "monitors_ignore_case": config.monitors_ignore_case,
+        "line_wrap": config.line_wrap,
+        "color_full_line": config.color_full_line,
+        "json_format": config.json_format,
+        "collapse_repeats": config.collapse_repeats,
+        "health": {
+            "enabled": config.health.enabled,
+            "interval_minutes": config.health.interval_minutes,
+            "restart_threshold": config.health.restart_threshold,
+        },
+    })