PyTaskWireCheck 0.1.0__py3-none-any.whl

pytaskwirecheck/notifications/webhook.py

@@ -0,0 +1,71 @@
+"""HTTP webhook notifications.
+
+The webhook notifier is opt-in and disabled by default. It uses only the
+standard library, applies an explicit network timeout, and retries a bounded
+number of times with a short delay. Failures are reported as ``False`` (and
+optionally as an error string); they never raise into the run.
+"""
+
+from __future__ import annotations
+
+import json
+import time
+import urllib.error
+import urllib.request
+from typing import List, Optional, Tuple
+
+from pytaskwirecheck.notifications.base import RunNotification
+
+
+class WebhookNotifier:
+    """Posts run notifications as JSON to a single HTTP endpoint."""
+
+    def __init__(
+        self,
+        url: str,
+        *,
+        timeout_seconds: float = 5.0,
+        max_attempts: int = 2,
+        retry_delay_seconds: float = 0.5,
+        events: Tuple[str, ...] = ("failure",),
+    ) -> None:
+        if not url:
+            raise ValueError("webhook url must not be empty")
+        self._url = url
+        self._timeout = timeout_seconds
+        self._max_attempts = max(1, max_attempts)
+        self._retry_delay = retry_delay_seconds
+        self._events = events
+        self.errors: List[str] = []
+
+    def wants(self, event: str) -> bool:
+        return event in self._events
+
+    def send(self, notification: RunNotification) -> bool:
+        if not self.wants(notification.event):
+            return True
+        body = json.dumps(notification.to_payload()).encode("utf-8")
+        last_error: Optional[str] = None
+        for attempt in range(1, self._max_attempts + 1):
+            request = urllib.request.Request(
+                self._url,
+                data=body,
+                headers={"Content-Type": "application/json"},
+                method="POST",
+            )
+            try:
+                with urllib.request.urlopen(request, timeout=self._timeout) as response:
+                    status = getattr(response, "status", 200)
+                    if 200 <= status < 300:
+                        return True
+                    last_error = "HTTP %s" % status
+            except urllib.error.URLError as exc:
+                # Do not leak response bodies; str(exc) may include the URL.
+                last_error = "network error: %s" % exc.reason
+            except (TimeoutError, OSError) as exc:
+                last_error = "network error: %s" % type(exc).__name__
+            if attempt < self._max_attempts:
+                time.sleep(self._retry_delay)
+        if last_error:
+            self.errors.append(last_error)
+        return False

pytaskwirecheck/processes/runner.py

@@ -0,0 +1,265 @@
+"""Subprocess lifecycle management.
+
+This module runs a single configured command and reports its outcome. It has no
+knowledge of the DAG, scheduling, caching, or presentation. It is responsible
+for correctness under cancellation, timeouts, large output, and start-up
+failures.
+
+Design notes:
+
+* Commands are executed as argument arrays. Shell execution is opt-in and
+  explicit (``shell=True`` requires a single-element ``argv``).
+* Output is streamed to a callback from dedicated reader threads, which avoids
+  the classic pipe-buffer deadlock and keeps memory bounded.
+* On POSIX, each command runs in its own session/process group so that the
+  whole descendant tree can be signalled. On Windows a new process group is
+  created and descendants are terminated best-effort.
+"""
+
+from __future__ import annotations
+
+import os
+import subprocess
+import sys
+import threading
+import time
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Callable, Mapping, Optional, Sequence, Tuple, Union
+
+from pytaskwirecheck.diagnostics.errors import ProcessStartError
+
+#: Signature for streaming consumers: (stream_name, chunk) where stream_name is
+#: ``"stdout"`` or ``"stderr"``.
+OutputCallback = Callable[[str, bytes], None]
+
+_POLL_INTERVAL = 0.05
+_GRACE_PERIOD_SECONDS = 5.0
+_READ_CHUNK = 65536
+
+_IS_WINDOWS = sys.platform.startswith("win")
+
+
+@dataclass(frozen=True)
+class CommandSpec:
+    """Everything needed to run one command."""
+
+    argv: Tuple[str, ...]
+    cwd: Path
+    env: Mapping[str, str]
+    shell: bool = False
+    timeout_seconds: Optional[float] = None
+    max_output_bytes: Optional[int] = None
+
+
+@dataclass
+class ProcessResult:
+    """The outcome of a single command execution."""
+
+    exit_code: Optional[int]
+    timed_out: bool = False
+    cancelled: bool = False
+    duration_seconds: float = 0.0
+    output_bytes: int = 0
+    output_truncated: bool = False
+    start_error: Optional[str] = None
+
+    @property
+    def succeeded(self) -> bool:
+        return (
+            self.start_error is None
+            and not self.timed_out
+            and not self.cancelled
+            and self.exit_code == 0
+        )
+
+
+class _OutputSink:
+    """Thread-safe, optionally size-bounded output accumulator.
+
+    The sink forwards every chunk to the consumer callback immediately; the
+    byte counter is only used to enforce ``max_output_bytes`` once the limit is
+    reached (further bytes are dropped from *recording* but the process is not
+    killed, matching typical build-tool behaviour).
+    """
+
+    def __init__(
+        self,
+        callback: Optional[OutputCallback],
+        limit: Optional[int],
+    ) -> None:
+        self._callback = callback
+        self._limit = limit
+        self._lock = threading.Lock()
+        self.total = 0
+        self.truncated = False
+
+    def write(self, stream: str, chunk: bytes) -> None:
+        with self._lock:
+            if self._limit is not None:
+                remaining = self._limit - self.total
+                if remaining <= 0:
+                    self.truncated = True
+                    return
+                if len(chunk) > remaining:
+                    chunk = chunk[:remaining]
+                    self.truncated = True
+            self.total += len(chunk)
+        if self._callback is not None:
+            self._callback(stream, chunk)
+
+
+def _reader(pipe, stream: str, sink: _OutputSink) -> None:
+    try:
+        while True:
+            chunk = pipe.read(_READ_CHUNK)
+            if not chunk:
+                break
+            sink.write(stream, chunk)
+    except (ValueError, OSError):
+        # Pipe closed during shutdown; treat as end of stream.
+        pass
+    finally:
+        try:
+            pipe.close()
+        except OSError:
+            pass
+
+
+def _popen_kwargs(spec: CommandSpec) -> dict:
+    kwargs: dict = {}
+    if _IS_WINDOWS:
+        kwargs["creationflags"] = getattr(subprocess, "CREATE_NEW_PROCESS_GROUP", 0)
+    else:
+        kwargs["start_new_session"] = True
+    return kwargs
+
+
+def _signal_group(proc: "subprocess.Popen", sig: int, *, force: bool) -> None:
+    """Best-effort delivery of a signal to the process and its descendants."""
+    if proc.poll() is not None:
+        return
+    if _IS_WINDOWS:  # pragma: no cover - exercised on Windows only
+        if force:
+            try:
+                subprocess.run(
+                    ["taskkill", "/F", "/T", "/PID", str(proc.pid)],
+                    capture_output=True,
+                    check=False,
+                )
+                return
+            except OSError:
+                pass
+        proc.terminate()
+        return
+    try:
+        pgid = os.getpgid(proc.pid)
+        os.killpg(pgid, sig)
+    except (ProcessLookupError, PermissionError, OSError):
+        try:
+            proc.terminate() if not force else proc.kill()
+        except OSError:
+            pass
+
+
+def _terminate(proc: "subprocess.Popen", grace: float) -> None:
+    """Ask politely, then force if needed. Never hangs indefinitely."""
+    import signal
+
+    _signal_group(proc, signal.SIGTERM, force=False)
+    try:
+        proc.wait(timeout=grace)
+        return
+    except subprocess.TimeoutExpired:
+        pass
+    _signal_group(proc, signal.SIGKILL, force=True)
+    try:
+        proc.wait(timeout=grace)
+    except subprocess.TimeoutExpired:  # pragma: no cover - extreme fallback
+        pass
+
+
+def run_command(
+    spec: CommandSpec,
+    *,
+    on_output: Optional[OutputCallback] = None,
+    cancel_event: Optional[threading.Event] = None,
+    grace_seconds: float = _GRACE_PERIOD_SECONDS,
+) -> ProcessResult:
+    """Run ``spec`` to completion and return a :class:`ProcessResult`.
+
+    Raises:
+        ProcessStartError: if the process cannot be started at all.
+    """
+    sink = _OutputSink(on_output, spec.max_output_bytes)
+
+    if spec.shell:
+        if len(spec.argv) != 1:
+            raise ProcessStartError("shell execution requires a single command string")
+        popen_argv: Union[str, Sequence[str]] = spec.argv[0]
+    else:
+        popen_argv = list(spec.argv)
+
+    try:
+        proc = subprocess.Popen(  # noqa: S603 - argv, no shell by default
+            popen_argv,
+            cwd=str(spec.cwd),
+            env=dict(spec.env),
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            stdin=subprocess.DEVNULL,
+            shell=spec.shell,
+            **_popen_kwargs(spec),
+        )
+    except FileNotFoundError as exc:
+        raise ProcessStartError(
+            "executable not found: %s" % (spec.argv[0] if spec.argv else "")
+        ) from exc
+    except PermissionError as exc:
+        raise ProcessStartError(
+            "permission denied executing: %s" % (spec.argv[0] if spec.argv else "")
+        ) from exc
+    except OSError as exc:
+        raise ProcessStartError("failed to start process: %s" % exc) from exc
+
+    assert proc.stdout is not None and proc.stderr is not None
+    stdout_thread = threading.Thread(
+        target=_reader, args=(proc.stdout, "stdout", sink), daemon=True
+    )
+    stderr_thread = threading.Thread(
+        target=_reader, args=(proc.stderr, "stderr", sink), daemon=True
+    )
+    stdout_thread.start()
+    stderr_thread.start()
+
+    start = time.monotonic()
+    deadline = (
+        start + spec.timeout_seconds if spec.timeout_seconds is not None else None
+    )
+    timed_out = False
+    cancelled = False
+
+    while proc.poll() is None:
+        if cancel_event is not None and cancel_event.is_set():
+            cancelled = True
+            _terminate(proc, grace_seconds)
+            break
+        if deadline is not None and time.monotonic() >= deadline:
+            timed_out = True
+            _terminate(proc, grace_seconds)
+            break
+        time.sleep(_POLL_INTERVAL)
+
+    exit_code = proc.wait()
+    stdout_thread.join(timeout=grace_seconds)
+    stderr_thread.join(timeout=grace_seconds)
+    duration = time.monotonic() - start
+
+    return ProcessResult(
+        exit_code=exit_code,
+        timed_out=timed_out,
+        cancelled=cancelled,
+        duration_seconds=duration,
+        output_bytes=sink.total,
+        output_truncated=sink.truncated,
+    )

pytaskwirecheck/processes/signals.py

@@ -0,0 +1,65 @@
+"""Signal handling helpers for graceful cancellation.
+
+PyTaskWireCheck installs temporary handlers so that Ctrl-C (SIGINT) and SIGTERM set a
+cancellation event rather than abruptly killing the scheduler. Handlers are
+restored on exit to avoid surprising the embedding process.
+"""
+
+from __future__ import annotations
+
+import signal
+import threading
+from contextlib import contextmanager
+from typing import Callable, Iterator, List, Optional
+
+
+@contextmanager
+def install_cancel_handlers(
+    set_cancel: Callable[[], None],
+    *,
+    signals: Optional[List[int]] = None,
+) -> Iterator[None]:
+    """Register handlers that call ``set_cancel`` on interruption.
+
+    On the second signal (an impatient Ctrl-C), the default behaviour is
+    restored and the signal is re-raised, so a user can always escape.
+    """
+    if signals is None:
+        signals = [signal.SIGINT, signal.SIGTERM]
+
+    previous: List[tuple] = []
+    fired = {"count": 0}
+
+    def _handler(signum: int, frame: object) -> None:  # pragma: no cover
+        fired["count"] += 1
+        if fired["count"] == 1:
+            set_cancel()
+            return
+        # Second signal: restore defaults and re-raise for a hard exit.
+        _restore()
+        if signum == signal.SIGINT:
+            raise KeyboardInterrupt
+        raise SystemExit(128 + signum)
+
+    def _restore() -> None:
+        for signum, old in previous:
+            try:
+                signal.signal(signum, old)
+            except (ValueError, OSError):  # pragma: no cover
+                pass
+
+    for signum in signals:
+        try:
+            old = signal.signal(signum, _handler)
+            previous.append((signum, old))
+        except (ValueError, OSError):
+            # Non-main thread or unsupported signal: skip quietly.
+            continue
+    try:
+        yield
+    finally:
+        _restore()
+
+
+def new_cancel_event() -> threading.Event:
+    return threading.Event()

pytaskwirecheck/tui/app.py

@@ -0,0 +1,204 @@
+"""A minimal live terminal dashboard.
+
+Design constraints (from the specification):
+
+* Rendering must never block the scheduler. Events only mutate an in-memory
+  snapshot under a lock; a separate daemon thread redraws at a fixed interval.
+* It must degrade safely: when the target stream is not a TTY it does nothing.
+* Redraws use cursor-home + clear-to-end so they do not scroll task logs away.
+* The core engine never imports this module; it is an optional listener.
+"""
+
+from __future__ import annotations
+
+import shutil
+import sys
+import threading
+import time
+from dataclasses import dataclass, field
+from typing import Dict, Optional, TextIO
+
+from pytaskwirecheck.engine.events import (
+    Event,
+    RunFinished,
+    RunStarted,
+    TaskStateChanged,
+)
+from pytaskwirecheck.engine.state import TaskStatus
+
+_HEAVY = TaskStatus.RUNNING
+_CLEAR = "\033[2J"
+_HOME = "\033[H"
+
+_SYMBOL = {
+    TaskStatus.PENDING: "·",
+    TaskStatus.READY: "·",
+    TaskStatus.RUNNING: "▶",
+    TaskStatus.SUCCEEDED: "✓",
+    TaskStatus.CACHED: "✓",
+    TaskStatus.FAILED: "✗",
+    TaskStatus.TIMED_OUT: "✗",
+    TaskStatus.BLOCKED: "✗",
+    TaskStatus.CANCELLED: "⊘",
+    TaskStatus.SKIPPED: "⊘",
+}
+
+
+@dataclass
+class _TaskView:
+    status: TaskStatus = TaskStatus.PENDING
+    attempt: int = 1
+    max_attempts: int = 1
+    message: str = ""
+    started_at: Optional[float] = None
+    finished_at: Optional[float] = None
+
+
+@dataclass
+class _Snapshot:
+    run_id: str = ""
+    total: int = 0
+    started_at: float = field(default_factory=time.monotonic)
+    tasks: Dict[str, _TaskView] = field(default_factory=dict)
+    finished: bool = False
+    succeeded: bool = False
+
+
+class LiveDashboard:
+    """A thread-safe, event-driven terminal dashboard."""
+
+    def __init__(
+        self,
+        stream: Optional[TextIO] = None,
+        *,
+        refresh_interval: float = 0.2,
+        color: bool = False,
+    ) -> None:
+        self._stream = stream if stream is not None else sys.stdout
+        self._interval = max(0.05, refresh_interval)
+        self._snapshot = _Snapshot()
+        self._lock = threading.Lock()
+        self._stop = threading.Event()
+        self._thread: Optional[threading.Thread] = None
+        self._color = color
+        self._enabled = False
+
+    # -- listener interface -------------------------------------------------
+
+    def handle(self, event: Event) -> None:
+        with self._lock:
+            if isinstance(event, RunStarted):
+                self._snapshot = _Snapshot(
+                    run_id=event.run_id,
+                    total=event.total_tasks,
+                    started_at=time.monotonic(),
+                )
+                self._snapshot.tasks = {task_id: _TaskView() for task_id in event.tasks}
+            elif isinstance(event, TaskStateChanged):
+                view = self._snapshot.tasks.get(event.task_id, _TaskView())
+                now = time.monotonic()
+                if event.status is TaskStatus.RUNNING and view.started_at is None:
+                    view.started_at = now
+                if event.status.is_terminal:
+                    view.finished_at = now
+                view.status = event.status
+                if event.message:
+                    view.message = event.message
+                self._snapshot.tasks[event.task_id] = view
+            elif isinstance(event, RunFinished):
+                self._snapshot.finished = True
+                self._snapshot.succeeded = event.succeeded
+
+    # -- lifecycle ----------------------------------------------------------
+
+    def start(self) -> None:
+        try:
+            self._enabled = bool(self._stream.isatty())
+        except (ValueError, AttributeError):
+            self._enabled = False
+        if not self._enabled:
+            return
+        self._stop.clear()
+        self._thread = threading.Thread(target=self._loop, daemon=True)
+        self._thread.start()
+
+    def stop(self) -> None:
+        self._stop.set()
+        if self._thread is not None:
+            self._thread.join(timeout=2.0)
+            self._thread = None
+        if self._enabled:
+            self._write(self._render())
+            self._write("\n")
+
+    def _loop(self) -> None:
+        while not self._stop.wait(self._interval):
+            try:
+                self._write(_HOME + self._render())
+            except (BrokenPipeError, ValueError):
+                return
+
+    # -- rendering ----------------------------------------------------------
+
+    def _counts(self) -> Dict[str, int]:
+        counts: Dict[str, int] = {}
+        for view in self._snapshot.tasks.values():
+            counts[view.status.value] = counts.get(view.status.value, 0) + 1
+        return counts
+
+    def _render(self) -> str:
+        with self._lock:
+            snapshot = self._snapshot
+            total = snapshot.total
+            done = sum(1 for view in snapshot.tasks.values() if view.status.is_terminal)
+            elapsed = time.monotonic() - snapshot.started_at
+            counts = self._counts()
+            tasks = sorted(
+                snapshot.tasks.items(),
+                key=lambda item: (item[1].status.value, item[0]),
+            )
+            run_id = snapshot.run_id
+
+        columns, lines = shutil.get_terminal_size((80, 24))
+        header = "PyTaskWireCheck  run %s   %d/%d done   %6.1fs" % (
+            run_id,
+            done,
+            total,
+            elapsed,
+        )
+        count_line = "  ".join("%d %s" % (counts[key], key) for key in sorted(counts))
+        rows = [
+            header[:columns],
+            count_line[:columns],
+            "",
+        ]
+        available = max(1, lines - len(rows) - 1)
+        for task_id, view in tasks:
+            if len(rows) >= available + 3:
+                rows.append("  ... (%d more)" % (len(tasks) - (len(rows) - 3)))
+                break
+            symbol = _SYMBOL.get(view.status, "?")
+            duration = ""
+            if view.started_at is not None:
+                end = view.finished_at or time.monotonic()
+                duration = "%5.1fs" % (end - view.started_at)
+            attempt = (
+                " (%d/%d)" % (view.attempt, view.max_attempts)
+                if view.max_attempts > 1
+                else ""
+            )
+            suffix = ""
+            if view.message and view.status.is_failure:
+                suffix = "  %s" % view.message
+            rows.append(
+                "  %s %-24s %8s%s%s" % (symbol, task_id, duration, attempt, suffix)
+            )
+        rows.append("")
+        return _CLEAR + "\n".join(row[:columns] for row in rows)
+
+    def _write(self, text: str) -> None:
+        try:
+            self._stream.write(text)
+            self._stream.flush()
+        except (BrokenPipeError, ValueError):
+            pass