isitup-cli 0.1.0__py3-none-any.whl

isitup/__init__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+__all__ = ["main"]

isitup/checks.py

@@ -0,0 +1,202 @@
+from __future__ import annotations
+
+import platform
+import socket
+import subprocess
+import time
+from collections.abc import Callable
+from concurrent.futures import ThreadPoolExecutor
+from dataclasses import dataclass
+from enum import StrEnum
+
+import requests
+
+from .config import Target, TargetKind
+
+PhaseCallback = Callable[[str], None]
+
+# Distinguishes *why* a probe (HTTP or TCP) failed. None means it didn't fail.
+ErrorKind = str | None
+
+
+class Status(StrEnum):
+    OK = "ok"
+    WARN = "warn"
+    DOWN = "down"
+    UNKNOWN = "unknown"
+
+
+@dataclass
+class CheckResult:
+    target: Target
+    ping_status: Status
+    ping_latency_ms: float | None
+    http_status: Status | None  # set only when target.kind is HTTP
+    http_code: int | None
+    http_latency_ms: float | None
+    tcp_status: Status | None  # set only when target.kind is TCP_PORT
+    tcp_latency_ms: float | None
+    error_kind: ErrorKind
+    detail: str
+    checked_at: float
+
+    @property
+    def latency_ms(self) -> float | None:
+        """Whichever probe latency applies to this target's kind (HTTP
+        response time, TCP connect time, or None for a ping-only target)."""
+        if self.target.kind == TargetKind.HTTP:
+            return self.http_latency_ms
+        if self.target.kind == TargetKind.TCP_PORT:
+            return self.tcp_latency_ms
+        return None
+
+
+def ping_once(host: str, timeout_s: float = 2.0) -> tuple[bool, float | None]:
+    """Send a single ICMP echo request using the OS ping binary. Returns (reachable, latency_ms)."""
+    is_windows = platform.system().lower() == "windows"
+    if is_windows:
+        cmd = ["ping", "-n", "1", "-w", str(int(timeout_s * 1000)), host]
+    else:
+        cmd = ["ping", "-c", "1", "-W", str(int(timeout_s)), host]
+
+    start = time.monotonic()
+    try:
+        proc = subprocess.run(
+            cmd,
+            capture_output=True,
+            timeout=timeout_s + 2,
+        )
+    except subprocess.TimeoutExpired, OSError:
+        return False, None
+    elapsed_ms = (time.monotonic() - start) * 1000
+
+    return proc.returncode == 0, elapsed_ms
+
+
+def run_pings(
+    targets: list[Target], ping_enabled: bool, ping_timeout: float
+) -> dict[str, tuple[Status, float | None]]:
+    """Ping each unique ping-host once — targets that point at the same host
+    (e.g. "example.com" and "https://example.com/health") share one ping."""
+    if not ping_enabled:
+        return {}
+    hosts = sorted({t.ping_host for t in targets if t.ping})
+    if not hosts:
+        return {}
+    with ThreadPoolExecutor(max_workers=min(len(hosts), 16) or 1) as pool:
+        futures = {pool.submit(ping_once, host, ping_timeout): host for host in hosts}
+        results: dict[str, tuple[Status, float | None]] = {}
+        for future, host in futures.items():
+            reachable, latency_ms = future.result()
+            results[host] = (Status.OK if reachable else Status.DOWN, latency_ms)
+    return results
+
+
+def ping_status_for(
+    target: Target, ping_enabled: bool, ping_results: dict[str, tuple[Status, float | None]]
+) -> tuple[Status, float | None]:
+    if target.ping and ping_enabled:
+        return ping_results.get(target.ping_host, (Status.DOWN, None))
+    return Status.UNKNOWN, None
+
+
+def _caused_by(exc: BaseException, cls: type[BaseException]) -> bool:
+    """Walk an exception's __cause__/__context__ chain looking for `cls`."""
+    seen: set[int] = set()
+    current: BaseException | None = exc
+    while current is not None and id(current) not in seen:
+        if isinstance(current, cls):
+            return True
+        seen.add(id(current))
+        current = current.__cause__ or current.__context__
+    return False
+
+
+def http_check(url: str, timeout_s: float = 5.0) -> tuple[Status, int | None, float | None, ErrorKind, str]:
+    try:
+        response = requests.get(url, timeout=timeout_s, allow_redirects=True)
+    except requests.exceptions.SSLError as exc:
+        return Status.DOWN, None, None, "tls", f"TLS/certificate error: {exc}"
+    except requests.exceptions.TooManyRedirects:
+        return Status.DOWN, None, None, "redirect", "too many redirects (possible redirect loop)"
+    except requests.exceptions.Timeout:
+        return Status.DOWN, None, None, "timeout", "request timed out"
+    except requests.exceptions.ConnectionError as exc:
+        if _caused_by(exc, socket.gaierror):
+            return Status.DOWN, None, None, "dns", "DNS resolution failed"
+        return Status.DOWN, None, None, "connection", "connection failed"
+    except requests.exceptions.RequestException as exc:
+        return Status.DOWN, None, None, "request_error", str(exc)
+
+    latency_ms = response.elapsed.total_seconds() * 1000
+    code = response.status_code
+    if code >= 500:
+        return Status.DOWN, code, latency_ms, "server_error", f"HTTP {code} server error"
+    if code >= 400:
+        return Status.WARN, code, latency_ms, "client_error", f"HTTP {code} client error"
+    return Status.OK, code, latency_ms, None, f"HTTP {code}"
+
+
+def tcp_check(
+    hostname: str, port: int, timeout_s: float = 5.0
+) -> tuple[Status, float | None, ErrorKind, str]:
+    start = time.monotonic()
+    try:
+        with socket.create_connection((hostname, port), timeout=timeout_s):
+            pass
+    except TimeoutError:
+        return Status.DOWN, None, "timeout", f"connection to port {port} timed out"
+    except socket.gaierror:
+        return Status.DOWN, None, "dns", "DNS resolution failed"
+    except OSError as exc:
+        return Status.DOWN, None, "connection", f"connection to port {port} failed: {exc.strerror or exc}"
+
+    latency_ms = (time.monotonic() - start) * 1000
+    return Status.OK, latency_ms, None, f"port {port} open"
+
+
+def probe_target(
+    target: Target,
+    ping_status: Status,
+    ping_latency_ms: float | None,
+    timeout_s: float,
+    on_phase: PhaseCallback | None = None,
+) -> CheckResult:
+    """Run whatever follow-up check `target.kind` calls for (HTTP, a TCP
+    connect, or nothing for a ping-only target). Ping is assumed to have
+    already been done — see `run_pings` for why it's handled separately."""
+    checked_at = time.time()
+
+    http_status = http_code = http_latency_ms = None
+    tcp_status = tcp_latency_ms = None
+    error_kind: ErrorKind = None
+
+    if target.kind == TargetKind.HTTP:
+        assert target.url is not None
+        if on_phase:
+            on_phase("http")
+        http_status, http_code, http_latency_ms, error_kind, detail = http_check(target.url, timeout_s)
+    elif target.kind == TargetKind.TCP_PORT:
+        assert target.port is not None
+        if on_phase:
+            on_phase("tcp")
+        tcp_status, tcp_latency_ms, error_kind, detail = tcp_check(target.hostname, target.port, timeout_s)
+    else:
+        detail = "ping-only target (no scheme or port given)"
+
+    if ping_status == Status.DOWN and (http_status == Status.DOWN or tcp_status == Status.DOWN):
+        detail = "host did not respond to ping, and " + detail
+
+    return CheckResult(
+        target=target,
+        ping_status=ping_status,
+        ping_latency_ms=ping_latency_ms,
+        http_status=http_status,
+        http_code=http_code,
+        http_latency_ms=http_latency_ms,
+        tcp_status=tcp_status,
+        tcp_latency_ms=tcp_latency_ms,
+        error_kind=error_kind,
+        detail=detail,
+        checked_at=checked_at,
+    )

isitup/cli.py

@@ -0,0 +1,190 @@
+from __future__ import annotations
+
+import argparse
+import time
+from pathlib import Path
+
+from rich.console import Console, RenderableType
+from rich.live import Live
+
+from .config import Target, config_mtime, load_targets, reload_if_changed
+from .history import HistoryStore
+from .output import compute_exit_code, format_json_line, format_plain_line, run_checks
+from .render import build_table, countdown, framed, is_online, run_round, waiting_placeholder
+
+
+def parse_args(argv: list[str] | None = None) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        prog="isitup",
+        description="Periodically check whether servers respond to ping, HTTP, and TCP ports.",
+    )
+    parser.add_argument(
+        "-c",
+        "--config",
+        type=Path,
+        default=None,
+        help="path to a YAML config file listing targets (see config.example.yaml); "
+        "reloaded automatically whenever it changes",
+    )
+    parser.add_argument(
+        "-u",
+        "--url",
+        action="append",
+        default=[],
+        dest="urls",
+        help="a target to monitor; can be passed multiple times. A bare hostname "
+        "('example.com') is ping-only, 'hostname:port' also does a TCP connect check, "
+        "and a URL with a scheme ('https://example.com') also does an HTTP check",
+    )
+    parser.add_argument(
+        "-i",
+        "--interval",
+        type=float,
+        default=30.0,
+        help="seconds between check rounds (default: 30)",
+    )
+    parser.add_argument(
+        "--ping-timeout",
+        type=float,
+        default=2.0,
+        help="seconds to wait for a ping reply (default: 2)",
+    )
+    parser.add_argument(
+        "--http-timeout",
+        type=float,
+        default=5.0,
+        help="seconds to wait for an HTTP response or TCP connection (default: 5)",
+    )
+    parser.add_argument(
+        "--no-ping",
+        action="store_true",
+        help="skip ICMP ping entirely and only perform HTTP/TCP checks "
+        "(useful when targets sit behind firewalls that drop ICMP)",
+    )
+    parser.add_argument(
+        "--once",
+        action="store_true",
+        help="run a single check round and exit instead of looping — "
+        "exit code is 1 if any target is down, 0 otherwise",
+    )
+    output_group = parser.add_mutually_exclusive_group()
+    output_group.add_argument(
+        "--plain",
+        action="store_true",
+        help="print one plain-text line per target per round instead of the live UI (for logging/piping)",
+    )
+    output_group.add_argument(
+        "--json",
+        action="store_true",
+        dest="json_output",
+        help="print one JSON object per target per round instead of the live UI (for machine consumption)",
+    )
+    return parser.parse_args(argv)
+
+
+def run_headless(
+    console: Console,
+    args: argparse.Namespace,
+    targets: list[Target],
+    ping_enabled: bool,
+    history: HistoryStore,
+) -> int:
+    emit = format_json_line if args.json_output else format_plain_line
+    config_path = args.config
+    mtime = config_mtime(config_path)
+
+    while True:
+        results = run_checks(targets, ping_enabled, args.ping_timeout, args.http_timeout)
+        history.update(results, {r.target.raw: is_online(r) for r in results})
+        for result in results:
+            print(emit(result, history), flush=True)
+
+        if args.once:
+            return compute_exit_code(results)
+
+        reload = reload_if_changed(config_path, args.urls, mtime)
+        mtime = reload.mtime
+        if reload.error:
+            console.print(f"[yellow]warning:[/yellow] config reload failed: {reload.error}")
+        if reload.targets is not None:
+            targets = reload.targets
+
+        time.sleep(args.interval)
+
+
+def run_interactive(
+    console: Console,
+    args: argparse.Namespace,
+    targets: list[Target],
+    ping_enabled: bool,
+    history: HistoryStore,
+) -> int:
+    if args.once:
+        with Live(console=console, refresh_per_second=12, transient=True) as live:
+            results = run_round(
+                console,
+                targets,
+                ping_enabled,
+                args.ping_timeout,
+                args.http_timeout,
+                live,
+                waiting_placeholder(),
+            )
+        history.update(results, {r.target.raw: is_online(r) for r in results})
+        console.print(framed(build_table(results, history)))
+        return compute_exit_code(results)
+
+    config_path = args.config
+    mtime = config_mtime(config_path)
+    base: RenderableType = waiting_placeholder()
+    try:
+        with Live(console=console, refresh_per_second=12) as live:
+            live.update(framed(base))
+            while True:
+                results = run_round(
+                    console,
+                    targets,
+                    ping_enabled,
+                    args.ping_timeout,
+                    args.http_timeout,
+                    live,
+                    base,
+                )
+                history.update(results, {r.target.raw: is_online(r) for r in results})
+                base = build_table(results, history)
+                live.update(framed(base))
+
+                reload = reload_if_changed(config_path, args.urls, mtime)
+                mtime = reload.mtime
+                if reload.error:
+                    console.print(f"[yellow]warning:[/yellow] config reload failed: {reload.error}")
+                if reload.targets is not None:
+                    targets = reload.targets
+
+                countdown(console, live, base, args.interval)
+    except KeyboardInterrupt:
+        console.print("\n[dim]stopped[/dim]")
+
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = parse_args(argv)
+    console = Console()
+
+    try:
+        targets = load_targets(args.config, args.urls)
+    except (FileNotFoundError, ValueError) as exc:
+        console.print(f"[bold red]error:[/bold red] {exc}")
+        return 1
+
+    ping_enabled = not args.no_ping
+    history = HistoryStore()
+
+    if args.plain or args.json_output:
+        return run_headless(console, args, targets, ping_enabled, history)
+    return run_interactive(console, args, targets, ping_enabled, history)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

isitup/config.py

@@ -0,0 +1,160 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import StrEnum
+from pathlib import Path
+from urllib.parse import urlparse
+
+import yaml
+
+
+class TargetKind(StrEnum):
+    PING_ONLY = "ping_only"  # bare hostname, e.g. "example.com"
+    HTTP = "http"  # has a scheme, e.g. "https://example.com"
+    TCP_PORT = "tcp_port"  # bare hostname:port, e.g. "example.com:1337"
+
+
+@dataclass
+class Target:
+    """A single server to monitor.
+
+    What gets checked besides ping is derived from how it was written:
+    a bare hostname is ping-only, a URL with a scheme also gets an HTTP
+    check, and a bare "hostname:port" also gets a TCP connect check.
+    """
+
+    raw: str
+    hostname: str
+    kind: TargetKind
+    url: str | None = None  # set when kind is HTTP
+    port: int | None = None  # set when kind is TCP_PORT
+    name: str | None = None
+    host: str | None = None
+    ping: bool = True
+
+    @property
+    def display_name(self) -> str:
+        return self.name or self.raw
+
+    @property
+    def ping_host(self) -> str:
+        return self.host or self.hostname
+
+
+def parse_target_string(
+    raw: str,
+    *,
+    name: str | None = None,
+    host: str | None = None,
+    ping: bool = True,
+) -> Target:
+    if "://" in raw:
+        hostname = urlparse(raw).hostname
+        if not hostname:
+            raise ValueError(f"could not determine a hostname from '{raw}'")
+        return Target(
+            raw=raw, hostname=hostname, kind=TargetKind.HTTP, url=raw, name=name, host=host, ping=ping
+        )
+
+    parsed = urlparse(f"//{raw}")
+    hostname = parsed.hostname
+    if not hostname:
+        raise ValueError(f"could not determine a hostname from '{raw}'")
+    if parsed.path or parsed.query or parsed.fragment:
+        raise ValueError(
+            f"'{raw}' has a path/query but no scheme — did you mean http://{raw} or https://{raw}?"
+        )
+
+    if parsed.port is not None:
+        target = Target(
+            raw=raw,
+            hostname=hostname,
+            kind=TargetKind.TCP_PORT,
+            port=parsed.port,
+            name=name,
+            host=host,
+            ping=ping,
+        )
+    else:
+        target = Target(
+            raw=raw, hostname=hostname, kind=TargetKind.PING_ONLY, name=name, host=host, ping=ping
+        )
+
+    if not target.ping and target.kind == TargetKind.PING_ONLY:
+        raise ValueError(
+            f"target '{raw}' has ping disabled but is a bare hostname with no scheme or port — "
+            "there would be nothing left to check"
+        )
+
+    return target
+
+
+def _target_from_dict(raw: dict) -> Target:
+    if "url" not in raw:
+        raise ValueError(f"target entry is missing required 'url' field: {raw!r}")
+    return parse_target_string(
+        raw["url"],
+        name=raw.get("name"),
+        host=raw.get("host"),
+        ping=raw.get("ping", True),
+    )
+
+
+def load_targets(config_path: Path | None, cli_urls: list[str]) -> list[Target]:
+    """Combine targets from a YAML config file and/or CLI-supplied URLs."""
+    targets: list[Target] = []
+
+    if config_path is not None:
+        if not config_path.exists():
+            raise FileNotFoundError(f"config file not found: {config_path}")
+        data = yaml.safe_load(config_path.read_text(encoding="utf-8")) or {}
+        raw_targets = data.get("targets", [])
+        if not isinstance(raw_targets, list):
+            raise ValueError("config 'targets' must be a list")
+        targets.extend(_target_from_dict(item) for item in raw_targets)
+
+    targets.extend(parse_target_string(url) for url in cli_urls)
+
+    if not targets:
+        raise ValueError("no targets configured — pass --url one or more times, or provide a --config file")
+
+    return targets
+
+
+def config_mtime(config_path: Path | None) -> float | None:
+    if config_path is None:
+        return None
+    try:
+        return config_path.stat().st_mtime
+    except OSError:
+        return None
+
+
+@dataclass
+class ReloadResult:
+    """Result of checking whether the config file changed since `last_mtime`.
+
+    `targets` is None when nothing changed (or reload failed) — callers
+    should keep using whatever target list they already have.
+    """
+
+    targets: list[Target] | None
+    mtime: float | None
+    error: str | None = None
+
+
+def reload_if_changed(
+    config_path: Path | None, cli_urls: list[str], last_mtime: float | None
+) -> ReloadResult:
+    current = config_mtime(config_path)
+    if config_path is None or current == last_mtime:
+        return ReloadResult(targets=None, mtime=last_mtime)
+
+    try:
+        targets = load_targets(config_path, cli_urls)
+    except (FileNotFoundError, ValueError) as exc:
+        # Update mtime even on failure so a still-broken file isn't retried
+        # every round — only a further edit triggers another attempt.
+        return ReloadResult(targets=None, mtime=current, error=str(exc))
+
+    return ReloadResult(targets=targets, mtime=current)

isitup/history.py

@@ -0,0 +1,62 @@
+from __future__ import annotations
+
+from collections import deque
+from dataclasses import dataclass, field
+
+from .checks import CheckResult
+
+MAX_SAMPLES = 20
+
+SPARK_BLOCKS = "▁▂▃▄▅▆▇█"
+
+
+@dataclass
+class TargetHistory:
+    latencies: deque[float] = field(default_factory=lambda: deque(maxlen=MAX_SAMPLES))
+    last_online: float | None = None
+    last_offline: float | None = None
+
+    def record(self, result: CheckResult, is_online: bool) -> None:
+        if result.latency_ms is not None:
+            self.latencies.append(result.latency_ms)
+        if is_online:
+            self.last_online = result.checked_at
+        else:
+            self.last_offline = result.checked_at
+
+    @property
+    def min_latency(self) -> float | None:
+        return min(self.latencies) if self.latencies else None
+
+    @property
+    def max_latency(self) -> float | None:
+        return max(self.latencies) if self.latencies else None
+
+    @property
+    def sparkline(self) -> str:
+        return sparkline(self.latencies)
+
+
+def sparkline(values: deque[float] | list[float]) -> str:
+    """A tiny one-line chart of recent values using unicode block characters."""
+    if not values:
+        return ""
+    lo, hi = min(values), max(values)
+    if hi == lo:
+        mid = SPARK_BLOCKS[len(SPARK_BLOCKS) // 2]
+        return mid * len(values)
+    span = hi - lo
+    scale = len(SPARK_BLOCKS) - 1
+    return "".join(SPARK_BLOCKS[int((v - lo) / span * scale)] for v in values)
+
+
+class HistoryStore:
+    def __init__(self) -> None:
+        self._by_target: dict[str, TargetHistory] = {}
+
+    def get(self, target_key: str) -> TargetHistory:
+        return self._by_target.setdefault(target_key, TargetHistory())
+
+    def update(self, results: list[CheckResult], is_online: dict[str, bool]) -> None:
+        for result in results:
+            self.get(result.target.raw).record(result, is_online[result.target.raw])