glab-cli-extras 0.1.0__py3-none-any.whl

glab_cli_extras/daemon/locks.py

@@ -0,0 +1,85 @@
+"""Exclusive OS file locks: `fcntl.flock` on POSIX, `msvcrt.locking` on Windows.
+
+The OS releases the lock when the holding process dies, so a lock file left on disk means nothing. Being able to take
+the daemon lock proves that no daemon is running.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+import time
+from pathlib import Path
+from types import TracebackType
+
+
+class LockTimeout(TimeoutError):
+    pass
+
+
+class FileLock:
+    def __init__(self, path: Path) -> None:
+        self.path = path
+        self._fd: int | None = None
+
+    @property
+    def held(self) -> bool:
+        return self._fd is not None
+
+    def _try_lock(self, fd: int) -> bool:
+        if sys.platform == "win32":
+            import msvcrt
+
+            try:
+                os.lseek(fd, 0, os.SEEK_SET)
+                msvcrt.locking(fd, msvcrt.LK_NBLCK, 1)
+            except OSError:
+                return False
+            return True
+        import fcntl
+
+        try:
+            fcntl.flock(fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
+        except OSError:
+            return False
+        return True
+
+    def try_acquire(self) -> bool:
+        if self._fd is not None:
+            return True
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        fd = os.open(self.path, os.O_RDWR | os.O_CREAT, 0o600)
+        if self._try_lock(fd):
+            self._fd = fd
+            return True
+        os.close(fd)
+        return False
+
+    def acquire(self, timeout: float) -> None:
+        deadline = time.monotonic() + timeout
+        while not self.try_acquire():
+            if time.monotonic() >= deadline:
+                raise LockTimeout(f"could not lock {self.path} within {timeout:.0f} s")
+            time.sleep(0.05)
+
+    def release(self) -> None:
+        fd, self._fd = self._fd, None
+        if fd is None:
+            return
+        if sys.platform == "win32":
+            import msvcrt
+
+            try:
+                os.lseek(fd, 0, os.SEEK_SET)
+                msvcrt.locking(fd, msvcrt.LK_UNLCK, 1)
+            except OSError:
+                pass
+        os.close(fd)
+
+    def __enter__(self) -> FileLock:
+        return self
+
+    def __exit__(
+        self, exc_type: type[BaseException] | None, exc: BaseException | None, tb: TracebackType | None
+    ) -> None:
+        self.release()

glab_cli_extras/daemon/scheduler.py

@@ -0,0 +1,52 @@
+"""Which resource polls next.
+
+Resources wait in due-time order. Among those that are due, urgent ones go first (probes that can end a watch), then
+the one served longest ago. That round-robin keeps one busy pipeline from starving a quiet MR watch when the budget
+is short. The scheduler holds no clock and does no I/O; the engine passes the time in.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass
+class _Entry:
+    due: float
+    urgent: bool
+
+
+class Scheduler:
+    def __init__(self) -> None:
+        self._entries: dict[str, _Entry] = {}
+        self._last_served: dict[str, float] = {}
+
+    def schedule(self, key: str, due: float, *, urgent: bool = False) -> None:
+        self._entries[key] = _Entry(due, urgent)
+
+    def remove(self, key: str) -> None:
+        self._entries.pop(key, None)
+
+    def forget(self, key: str) -> None:
+        self._entries.pop(key, None)
+        self._last_served.pop(key, None)
+
+    def __contains__(self, key: str) -> bool:
+        return key in self._entries
+
+    def due_at(self, key: str) -> float | None:
+        entry = self._entries.get(key)
+        return entry.due if entry else None
+
+    def next_due(self) -> float | None:
+        return min((e.due for e in self._entries.values()), default=None)
+
+    def ready(self, now: float) -> list[str]:
+        """Due keys in serving order: urgent first, then least recently served, then earliest due."""
+        due = [(key, entry) for key, entry in self._entries.items() if entry.due <= now]
+        due.sort(key=lambda item: (not item[1].urgent, self._last_served.get(item[0], float("-inf")), item[1].due))
+        return [key for key, _ in due]
+
+    def mark_served(self, key: str, now: float) -> None:
+        self._entries.pop(key, None)
+        self._last_served[key] = now

glab_cli_extras/daemon/server.py

@@ -0,0 +1,79 @@
+"""Dispatch of daemon requests to the engine."""
+
+from __future__ import annotations
+
+import asyncio
+import os
+from typing import Any
+
+from glab_cli_extras import __version__
+from glab_cli_extras.artifacts.job_logs import LOGS_MODES, LogsMode
+from glab_cli_extras.daemon.engine import Engine, EngineError
+from glab_cli_extras.daemon.transport import PROTOCOL_VERSION
+from glab_cli_extras.events import ALL_KINDS
+from glab_cli_extras.gitlab.refs import RefError, ResourceRef
+
+
+class RequestError(ValueError):
+    pass
+
+
+def _str(request: dict[str, Any], name: str) -> str:
+    value = request.get(name)
+    if not isinstance(value, str) or not value:
+        raise RequestError(f"{name} must be a non-empty string")
+    return value
+
+
+def handle(engine: Engine, request: dict[str, Any], stop: asyncio.Event) -> dict[str, Any]:
+    op = request.get("op")
+    try:
+        if op == "hello":
+            return {"ok": True, "protocol": PROTOCOL_VERSION, "version": __version__, "pid": os.getpid()}
+        if op == "subscribe":
+            options = request.get("options") or {}
+            if not isinstance(options, dict):
+                raise RequestError("options must be an object")
+            raw_events = options.get("events")
+            if not isinstance(raw_events, list) or not all(isinstance(e, str) for e in raw_events):
+                raise RequestError("options.events must be a list of event kinds")
+            unknown = set(raw_events) - ALL_KINDS
+            if unknown:
+                raise RequestError(f"unknown event kinds: {', '.join(sorted(unknown))}")
+            logs = options.get("logs", "failed")
+            if logs not in LOGS_MODES:
+                raise RequestError(f"options.logs must be one of {', '.join(LOGS_MODES)}")
+            logs_mode: LogsMode = logs
+            result = engine.subscribe(
+                _str(request, "client_id"),
+                ResourceRef.from_wire(request.get("resource")),
+                frozenset(raw_events),
+                logs_mode,
+                options.get("baseline"),
+            )
+            return {"ok": True, **result}
+        if op == "poll":
+            cursors = request.get("cursors") or {}
+            if not isinstance(cursors, dict) or not all(isinstance(v, int) for v in cursors.values()):
+                raise RequestError("cursors must map subscription ids to integers")
+            return {"ok": True, **engine.poll(_str(request, "client_id"), cursors)}
+        if op == "unsubscribe":
+            removed = engine.unsubscribe(_str(request, "client_id"), _str(request, "subscription_id"))
+            return {"ok": True, "removed": removed}
+        if op == "status":
+            now = engine.clock()
+            return {
+                "ok": True,
+                "pid": os.getpid(),
+                "version": __version__,
+                "protocol": PROTOCOL_VERSION,
+                "uptime_s": round(now - engine.started_at, 1),
+                "idle_s": round(engine.idle_for(now), 1),
+                **engine.status(),
+            }
+        if op == "stop":
+            stop.set()
+            return {"ok": True, "pid": os.getpid()}
+        return {"ok": False, "error": f"unknown op {op!r}"}
+    except (RequestError, RefError, EngineError) as exc:
+        return {"ok": False, "error": str(exc)}

glab_cli_extras/daemon/transport.py

@@ -0,0 +1,185 @@
+"""The daemon transport: NDJSON, one request and one response per connection.
+
+POSIX uses a Unix socket in the private state dir. Windows uses loopback TCP on a random port; the port and a random
+token are in a file only the user can read, and every request must carry the token, because any local user can
+connect to a loopback port. Setting `GLAB_CLI_EXTRAS_TRANSPORT=tcp` selects TCP on POSIX too, which is how the
+Windows path is tested on Linux.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import hmac
+import json
+import os
+import secrets
+import socket
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from glab_cli_extras.paths import daemon_state_dir, ensure_private_dir
+
+PROTOCOL_VERSION = 1
+MAX_LINE = 4 * 1024 * 1024
+TRANSPORT_ENV = "GLAB_CLI_EXTRAS_TRANSPORT"
+
+Handler = Callable[[dict[str, Any]], Awaitable[dict[str, Any]]]
+
+
+class DaemonUnavailable(ConnectionError):
+    """No daemon answers on the endpoint."""
+
+
+def use_tcp() -> bool:
+    return os.name == "nt" or os.environ.get(TRANSPORT_ENV) == "tcp" or not hasattr(socket, "AF_UNIX")
+
+
+@dataclass(frozen=True)
+class DaemonFiles:
+    state_dir: Path
+
+    @classmethod
+    def default(cls) -> DaemonFiles:
+        return cls(daemon_state_dir())
+
+    def _name(self, suffix: str) -> Path:
+        return self.state_dir / f"daemon-v{PROTOCOL_VERSION}.{suffix}"
+
+    @property
+    def lock(self) -> Path:
+        return self._name("lock")
+
+    @property
+    def spawn_lock(self) -> Path:
+        return self.state_dir / f"spawn-v{PROTOCOL_VERSION}.lock"
+
+    @property
+    def socket(self) -> Path:
+        return self._name("sock")
+
+    @property
+    def endpoint(self) -> Path:
+        return self._name("json")
+
+    @property
+    def log(self) -> Path:
+        return self._name("log")
+
+    def describe_endpoint(self) -> str:
+        if use_tcp():
+            return str(self.endpoint)
+        return str(self.socket)
+
+
+def _write_private(path: Path, content: str) -> None:
+    tmp = path.with_suffix(".tmp")
+    fd = os.open(tmp, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
+    with os.fdopen(fd, "w", encoding="utf-8") as fh:
+        fh.write(content)
+    os.replace(tmp, path)
+
+
+async def _read_line(reader: asyncio.StreamReader) -> bytes:
+    return await reader.readuntil(b"\n")
+
+
+async def start_server(files: DaemonFiles, handler: Handler) -> tuple[asyncio.AbstractServer, Callable[[], None]]:
+    """Start listening. Return the server and a cleanup function that removes the endpoint file."""
+    ensure_private_dir(files.state_dir)
+    token = secrets.token_hex(16) if use_tcp() else None
+
+    async def on_connection(reader: asyncio.StreamReader, writer: asyncio.StreamWriter) -> None:
+        try:
+            line = await asyncio.wait_for(_read_line(reader), 10)
+            request = json.loads(line)
+            if not isinstance(request, dict):
+                response: dict[str, Any] = {"ok": False, "error": "request must be a JSON object"}
+            elif token is not None and not hmac.compare_digest(str(request.get("token", "")), token):
+                response = {"ok": False, "error": "bad token"}
+            else:
+                request.pop("token", None)
+                response = await handler(request)
+            writer.write(json.dumps(response, separators=(",", ":")).encode() + b"\n")
+            await writer.drain()
+        except (TimeoutError, asyncio.IncompleteReadError, asyncio.LimitOverrunError, ValueError, OSError):
+            pass
+        finally:
+            writer.close()
+            with contextlib.suppress(OSError, ConnectionError):
+                await writer.wait_closed()
+
+    if token is None:
+        with contextlib.suppress(FileNotFoundError):
+            files.socket.unlink()
+        server = await asyncio.start_unix_server(on_connection, path=str(files.socket), limit=MAX_LINE)
+        os.chmod(files.socket, 0o600)
+
+        def cleanup() -> None:
+            with contextlib.suppress(OSError):
+                files.socket.unlink()
+
+        return server, cleanup
+
+    server = await asyncio.start_server(on_connection, host="127.0.0.1", port=0, limit=MAX_LINE)
+    port = server.sockets[0].getsockname()[1]
+    _write_private(files.endpoint, json.dumps({"port": port, "token": token, "pid": os.getpid()}))
+
+    def cleanup_tcp() -> None:
+        with contextlib.suppress(OSError):
+            files.endpoint.unlink()
+
+    return server, cleanup_tcp
+
+
+def _connect(files: DaemonFiles, timeout: float) -> tuple[socket.socket, str | None]:
+    if use_tcp():
+        try:
+            endpoint = json.loads(files.endpoint.read_text(encoding="utf-8"))
+            port, token = int(endpoint["port"]), str(endpoint["token"])
+        except (OSError, ValueError, KeyError, TypeError) as exc:
+            raise DaemonUnavailable(f"no daemon endpoint in {files.endpoint}") from exc
+        try:
+            return socket.create_connection(("127.0.0.1", port), timeout=timeout), token
+        except OSError as exc:
+            raise DaemonUnavailable(str(exc)) from exc
+    sock = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
+    sock.settimeout(timeout)
+    try:
+        sock.connect(str(files.socket))
+    except OSError as exc:
+        sock.close()
+        raise DaemonUnavailable(str(exc)) from exc
+    return sock, None
+
+
+def request(files: DaemonFiles, payload: dict[str, Any], timeout: float = 10.0) -> dict[str, Any]:
+    """Send one request and return the response. Raises DaemonUnavailable when nothing answers."""
+    sock, token = _connect(files, timeout)
+    with sock:
+        body = dict(payload)
+        if token is not None:
+            body["token"] = token
+        try:
+            sock.sendall(json.dumps(body, separators=(",", ":")).encode() + b"\n")
+            chunks = []
+            total = 0
+            while True:
+                chunk = sock.recv(65536)
+                if not chunk:
+                    break
+                chunks.append(chunk)
+                total += len(chunk)
+                if chunk.endswith(b"\n") or total > MAX_LINE:
+                    break
+        except OSError as exc:
+            raise DaemonUnavailable(str(exc)) from exc
+    raw = b"".join(chunks)
+    if not raw.strip():
+        raise DaemonUnavailable("the daemon closed the connection without answering")
+    response = json.loads(raw)
+    if not isinstance(response, dict):
+        raise DaemonUnavailable("the daemon sent an unexpected response")
+    return response

glab_cli_extras/events.py

@@ -0,0 +1,165 @@
+"""The event model, the catalogue of event kinds per resource, and the `--events`/`--exclude-events` filter."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Mapping
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+from typing import Any
+
+WATCH_STARTED = "watch_started"
+WATCH_DEGRADED = "watch_degraded"
+WATCH_ENDED = "watch_ended"
+LIFECYCLE_KINDS: tuple[str, ...] = (WATCH_STARTED, WATCH_DEGRADED, WATCH_ENDED)
+
+PIPELINE_KINDS: tuple[str, ...] = ("status_changed", "job_started", "job_finished", "downstream_created", "finished")
+MR_OWN_KINDS: tuple[str, ...] = (
+    "state_changed",
+    "draft_changed",
+    "title_changed",
+    "description_changed",
+    "pushed",
+    "merge_status_changed",
+    "approvals_changed",
+    "reviewers_changed",
+    "head_pipeline_changed",
+    "thread_created",
+    "thread_updated",
+    "thread_resolved",
+    "thread_unresolved",
+)
+MRS_KINDS: tuple[str, ...] = ("mr_opened", "mr_updated", "mr_merged", "mr_closed", "mr_reopened")
+BRANCH_KINDS: tuple[str, ...] = (
+    "pushed",
+    "force_pushed",
+    "created",
+    "deleted",
+    "pipeline_created",
+    "pipeline_finished",
+)
+
+KINDS_BY_RESOURCE: Mapping[str, tuple[str, ...]] = {
+    "pipeline": PIPELINE_KINDS,
+    "mr": MR_OWN_KINDS + PIPELINE_KINDS,
+    "mrs": MRS_KINDS,
+    "branch": BRANCH_KINDS,
+}
+
+GROUPS: Mapping[str, tuple[str, ...]] = {
+    "status": (
+        "state_changed",
+        "draft_changed",
+        "merge_status_changed",
+        "approvals_changed",
+        "reviewers_changed",
+        "title_changed",
+        "description_changed",
+        *MRS_KINDS,
+    ),
+    "comments": ("thread_created", "thread_updated", "thread_resolved", "thread_unresolved"),
+    "push": ("pushed", "force_pushed", "created", "deleted"),
+    "pipeline": (
+        "head_pipeline_changed",
+        *PIPELINE_KINDS,
+        "pipeline_created",
+        "pipeline_finished",
+    ),
+    "lifecycle": LIFECYCLE_KINDS,
+}
+
+ALL_KINDS: frozenset[str] = frozenset(k for kinds in KINDS_BY_RESOURCE.values() for k in kinds) | frozenset(
+    LIFECYCLE_KINDS
+)
+
+
+class FilterError(ValueError):
+    pass
+
+
+def _expand(resource_kind: str, values: Iterable[str], option: str) -> set[str]:
+    produced = set(KINDS_BY_RESOURCE[resource_kind]) | set(LIFECYCLE_KINDS)
+    expanded: set[str] = set()
+    for raw in values:
+        name = raw.strip()
+        if not name:
+            continue
+        if name in GROUPS:
+            members = set(GROUPS[name]) & produced
+            if not members:
+                raise FilterError(f"{option}: the group {name!r} has no events for a {resource_kind} watch")
+            expanded |= members
+        elif name in ALL_KINDS:
+            if name not in produced:
+                raise FilterError(f"{option}: a {resource_kind} watch never produces {name!r}")
+            expanded.add(name)
+        else:
+            known = ", ".join(sorted(GROUPS))
+            raise FilterError(f"{option}: unknown event kind or group {name!r} (groups: {known})")
+    return expanded
+
+
+def split_values(values: Iterable[str] | None) -> list[str]:
+    """Flatten repeated and comma-separated option values."""
+    return [part for value in values or () for part in value.split(",") if part.strip()]
+
+
+def resolve_filter(resource_kind: str, include: Iterable[str] | None, exclude: Iterable[str] | None) -> frozenset[str]:
+    """Return the event kinds a watch reports. Lifecycle events are always in, and cannot be excluded."""
+    include_list = split_values(include)
+    exclude_list = split_values(exclude)
+    if include_list:
+        selected = _expand(resource_kind, include_list, "--events")
+    else:
+        selected = set(KINDS_BY_RESOURCE[resource_kind])
+    if exclude_list:
+        excluded = _expand(resource_kind, exclude_list, "--exclude-events")
+        if excluded & set(LIFECYCLE_KINDS):
+            raise FilterError("--exclude-events: lifecycle events are always reported and cannot be excluded")
+        selected -= excluded
+    return frozenset(selected | set(LIFECYCLE_KINDS))
+
+
+def utc_now_iso() -> str:
+    return datetime.now(UTC).strftime("%Y-%m-%dT%H:%M:%S.%f")[:-3] + "Z"
+
+
+@dataclass(frozen=True, slots=True)
+class RawEvent:
+    """An event as a poller produces it, before the daemon assigns its sequence number."""
+
+    kind: str
+    data: dict[str, Any] = field(default_factory=dict)
+    artifacts: tuple[str, ...] = ()
+
+
+@dataclass(frozen=True, slots=True)
+class Event:
+    kind: str
+    resource: str
+    seq: int
+    observed_at: str
+    data: dict[str, Any]
+    artifacts: tuple[str, ...] = ()
+
+    def to_json(self) -> dict[str, Any]:
+        payload: dict[str, Any] = {
+            "kind": self.kind,
+            "resource": self.resource,
+            "seq": self.seq,
+            "observed_at": self.observed_at,
+            "data": self.data,
+        }
+        if self.artifacts:
+            payload["artifacts"] = list(self.artifacts)
+        return payload
+
+    @classmethod
+    def from_json(cls, data: Mapping[str, Any]) -> Event:
+        return cls(
+            kind=str(data["kind"]),
+            resource=str(data["resource"]),
+            seq=int(data["seq"]),
+            observed_at=str(data["observed_at"]),
+            data=dict(data.get("data") or {}),
+            artifacts=tuple(str(a) for a in data.get("artifacts") or ()),
+        )