pingmonitor 1.0.0__py3-none-any.whl

pingmon/app.tcss

@@ -0,0 +1,183 @@
+/* pingmon dark theme */
+
+Screen {
+    background: #14141c;
+    color: #e0e0f0;
+}
+
+#banner {
+    height: 1;
+    padding: 0 1;
+    background: #1c1c28;
+    color: #e0e0f0;
+}
+
+#body {
+    height: 1fr;
+}
+
+#left {
+    width: 1fr;
+    min-width: 70;
+    border-right: tall #2a2a3a;
+}
+
+#table {
+    height: 1fr;
+    background: #14141c;
+}
+
+DataTable > .datatable--header {
+    background: #1c1c28;
+    color: #8a8aa0;
+    text-style: bold;
+}
+
+DataTable > .datatable--cursor {
+    background: #2d3354;
+}
+
+DataTable > .datatable--hover {
+    background: #20202e;
+}
+
+#detail {
+    width: 54;
+    padding: 1 2;
+    background: #16161f;
+}
+
+#detail-title {
+    text-style: bold;
+    margin-bottom: 1;
+}
+
+#detail-meta {
+    margin-bottom: 1;
+    color: #9a9ab0;
+}
+
+.detail-h {
+    color: #7a7a8c;
+    text-style: bold;
+    margin-top: 1;
+}
+
+#detail-spark {
+    height: 6;
+    margin: 0 0 1 0;
+}
+
+#detail-spark > .sparkline--max-color {
+    color: #7aa2f7;
+}
+
+#detail-spark > .sparkline--min-color {
+    color: #3ddc84;
+}
+
+#detail-quality {
+    margin-bottom: 1;
+}
+
+#detail-stats {
+    margin-top: 1;
+}
+
+#detail-hint {
+    margin-top: 2;
+    color: #6a6a7c;
+}
+
+/* Add / edit target modal */
+TargetFormScreen {
+    align: center middle;
+}
+
+#add-dialog {
+    width: 60;
+    height: auto;
+    padding: 1 2;
+    background: #1c1c28;
+    border: thick #7aa2f7;
+}
+
+#add-title {
+    text-style: bold;
+    color: #7aa2f7;
+    margin-bottom: 1;
+}
+
+#add-dialog Input {
+    margin-bottom: 1;
+}
+
+#add-hint {
+    color: #6a6a7c;
+    margin-bottom: 1;
+}
+
+#add-buttons {
+    height: auto;
+    align: right middle;
+}
+
+#add-buttons Button {
+    margin-left: 2;
+}
+
+/* Region Advisor modal */
+AdvisorScreen {
+    align: center middle;
+}
+
+#advisor-dialog {
+    width: 116;
+    height: auto;
+    max-height: 90%;
+    padding: 1 2;
+    background: #1c1c28;
+    border: thick #7aa2f7;
+}
+
+#advisor-head {
+    margin-bottom: 1;
+}
+
+#advisor-table {
+    height: auto;
+    max-height: 24;
+    background: #1c1c28;
+}
+
+#advisor-foot {
+    margin-top: 1;
+}
+
+/* Traceroute modal */
+TracerouteScreen {
+    align: center middle;
+}
+
+#trace-dialog {
+    width: 108;
+    height: auto;
+    max-height: 90%;
+    padding: 1 2;
+    background: #1c1c28;
+    border: thick #c9a0dc;
+}
+
+#trace-head {
+    margin-bottom: 1;
+}
+
+#trace-table {
+    height: auto;
+    max-height: 26;
+    background: #1c1c28;
+}
+
+#trace-foot {
+    margin-top: 1;
+}

pingmon/config.py

@@ -0,0 +1,163 @@
+"""Load/save target configuration. Format is TOML, meant to be hand-edited."""
+
+from __future__ import annotations
+
+import os
+import tomllib
+from dataclasses import dataclass, field
+from pathlib import Path
+
+# Built-in set: 1-2 reachable hosts per country from the VPS list + the US.
+# All verified reachable over TCP. The port is configurable per target.
+DEFAULT_TARGETS: list[dict] = [
+    {"country": "Netherlands", "flag": "🇳🇱", "host": "speedtest.ams1.nl.leaseweb.net", "port": 80},
+    {"country": "Netherlands", "flag": "🇳🇱", "host": "ams.speedtest.clouvider.net", "port": 80},
+    {"country": "Germany", "flag": "🇩🇪", "host": "speedtest.frankfurt.linode.com", "port": 443},
+    {"country": "Germany", "flag": "🇩🇪", "host": "ftp.fau.de", "port": 80},
+    {"country": "United Kingdom", "flag": "🇬🇧", "host": "speedtest.london.linode.com", "port": 443},
+    {"country": "United Kingdom", "flag": "🇬🇧", "host": "lon.speedtest.clouvider.net", "port": 443},
+    {"country": "France", "flag": "🇫🇷", "host": "scaleway.testdebit.info", "port": 80},
+    {"country": "Cyprus", "flag": "🇨🇾", "host": "ftp.cs.ucy.ac.cy", "port": 80},
+    {"country": "Cyprus", "flag": "🇨🇾", "host": "mirror.library.ucy.ac.cy", "port": 80},
+    {"country": "Italy", "flag": "🇮🇹", "host": "mirror.garr.it", "port": 80},
+    {"country": "Italy", "flag": "🇮🇹", "host": "giano.com.dist.unige.it", "port": 80},
+    {"country": "Spain", "flag": "🇪🇸", "host": "ftp.cica.es", "port": 80},
+    {"country": "Greece", "flag": "🇬🇷", "host": "ftp.ntua.gr", "port": 80},
+    {"country": "Greece", "flag": "🇬🇷", "host": "ftp.cc.uoc.gr", "port": 80},
+    {"country": "Sweden", "flag": "🇸🇪", "host": "speedtest.tele2.net", "port": 80},
+    {"country": "Ireland", "flag": "🇮🇪", "host": "ftp.heanet.ie", "port": 80},
+    {"country": "United States", "flag": "🇺🇸", "host": "speedtest.newark.linode.com", "port": 443},
+    {"country": "United States", "flag": "🇺🇸", "host": "la.speedtest.clouvider.net", "port": 443},
+    {"country": "United States", "flag": "🇺🇸", "host": "mirror.us.leaseweb.net", "port": 80},
+]
+
+DEFAULTS = {
+    "interval": 2.0,        # poll period per target, seconds
+    "timeout": 2.0,         # TCP connect timeout, seconds
+    "history": 90,          # number of samples kept in memory for the graph
+    "alert_latency": 300.0, # alert if latency exceeds this (ms); 0 disables
+    "alert_loss": 20.0,     # alert if loss over the window exceeds this (%); 0 disables
+    "alert_window": 3,      # consecutive bad samples before an alert fires
+    "desktop_notify": True, # also raise an OS desktop notification on alert
+}
+
+
+@dataclass
+class Target:
+    country: str
+    flag: str
+    host: str
+    port: int = 443
+    source: str = "builtin"  # "builtin" = shipped default, "user" = added/edited
+
+    @property
+    def key(self) -> str:
+        return f"{self.host}:{self.port}"
+
+
+@dataclass
+class Config:
+    interval: float = DEFAULTS["interval"]
+    timeout: float = DEFAULTS["timeout"]
+    history: int = DEFAULTS["history"]
+    alert_latency: float = DEFAULTS["alert_latency"]
+    alert_loss: float = DEFAULTS["alert_loss"]
+    alert_window: int = DEFAULTS["alert_window"]
+    desktop_notify: bool = DEFAULTS["desktop_notify"]
+    targets: list[Target] = field(default_factory=list)
+    path: Path | None = None
+
+
+def config_path() -> Path:
+    """Resolve the config file location, htop-style.
+
+    Order: $PINGMON_CONFIG → a local ./config.toml if it already exists (handy
+    for development) → $XDG_CONFIG_HOME/pingmon/config.toml (the default for an
+    installed, run-from-anywhere command).
+    """
+    env = os.environ.get("PINGMON_CONFIG")
+    if env:
+        return Path(env).expanduser()
+    local = Path.cwd() / "config.toml"
+    if local.exists():
+        return local
+    xdg = Path(os.environ.get("XDG_CONFIG_HOME", Path.home() / ".config"))
+    return xdg / "pingmon" / "config.toml"
+
+
+def load_config() -> Config:
+    path = config_path()
+    if not path.exists():
+        cfg = Config(
+            targets=[Target(**t) for t in DEFAULT_TARGETS],
+            path=path,
+        )
+        save_config(cfg)
+        return cfg
+
+    with path.open("rb") as fh:
+        data = tomllib.load(fh)
+
+    default_hosts = {t["host"] for t in DEFAULT_TARGETS}
+    targets = [
+        Target(
+            country=t.get("country", "Unknown"),
+            flag=t.get("flag", "🏳"),
+            host=t["host"],
+            port=int(t.get("port", 443)),
+            # honour an explicit source; otherwise infer from the built-in set
+            source=t.get("source") or ("builtin" if t["host"] in default_hosts else "user"),
+        )
+        for t in data.get("targets", [])
+    ]
+    if not targets:
+        targets = [Target(**t) for t in DEFAULT_TARGETS]
+
+    return Config(
+        interval=float(data.get("interval", DEFAULTS["interval"])),
+        timeout=float(data.get("timeout", DEFAULTS["timeout"])),
+        history=int(data.get("history", DEFAULTS["history"])),
+        alert_latency=float(data.get("alert_latency", DEFAULTS["alert_latency"])),
+        alert_loss=float(data.get("alert_loss", DEFAULTS["alert_loss"])),
+        alert_window=int(data.get("alert_window", DEFAULTS["alert_window"])),
+        desktop_notify=bool(data.get("desktop_notify", DEFAULTS["desktop_notify"])),
+        targets=targets,
+        path=path,
+    )
+
+
+def _toml_escape(s: str) -> str:
+    return s.replace("\\", "\\\\").replace('"', '\\"')
+
+
+def save_config(cfg: Config) -> None:
+    """Minimal serialiser for our schema (no external dependencies)."""
+    path = cfg.path or config_path()
+    path.parent.mkdir(parents=True, exist_ok=True)
+
+    lines = [
+        "# pingmon configuration. Edit freely: add your own hosts/IPs.",
+        "# interval — poll period per target (s), timeout — connect timeout (s).",
+        "",
+        f"interval = {cfg.interval}",
+        f"timeout = {cfg.timeout}",
+        f"history = {cfg.history}",
+        "",
+        "# Alerts: fire when a target stays bad for `alert_window` samples.",
+        "# Set alert_latency or alert_loss to 0 to disable that trigger.",
+        f"alert_latency = {cfg.alert_latency}",
+        f"alert_loss = {cfg.alert_loss}",
+        f"alert_window = {cfg.alert_window}",
+        f"desktop_notify = {'true' if cfg.desktop_notify else 'false'}",
+        "",
+    ]
+    for t in cfg.targets:
+        lines.append("[[targets]]")
+        lines.append(f'country = "{_toml_escape(t.country)}"')
+        lines.append(f'flag = "{_toml_escape(t.flag)}"')
+        lines.append(f'host = "{_toml_escape(t.host)}"')
+        lines.append(f"port = {t.port}")
+        lines.append(f'source = "{_toml_escape(t.source)}"')
+        lines.append("")
+
+    path.write_text("\n".join(lines), encoding="utf-8")

pingmon/netutil.py

@@ -0,0 +1,139 @@
+"""System helpers: async traceroute and OS desktop notifications."""
+
+from __future__ import annotations
+
+import asyncio
+import re
+import sys
+
+_TIME_RE = re.compile(r"([\d.]+)\s*ms")
+_IP_RE = re.compile(r"\b\d{1,3}(?:\.\d{1,3}){3}\b")
+
+
+def parse_hop(line: str) -> dict | None:
+    """Parse one traceroute line into {hop, host, times, loss}."""
+    line = line.strip()
+    m = re.match(r"^\s*(\d+)\s+(.*)$", line)
+    if not m:
+        return None
+    hop = int(m.group(1))
+    rest = m.group(2)
+
+    times: list[float | None] = []
+    # count probes: every "* " is a loss, every "N ms" is a sample
+    for token in re.findall(r"\*|[\d.]+\s*ms", rest):
+        if token == "*":
+            times.append(None)
+        else:
+            tm = _TIME_RE.search(token)
+            times.append(float(tm.group(1)) if tm else None)
+
+    ip_match = _IP_RE.search(rest)
+    host = ip_match.group(0) if ip_match else ("*" if rest.strip().startswith("*") else rest.split()[0])
+
+    sent = len(times) or 1
+    lost = sum(1 for t in times if t is None)
+    loss = 100.0 * lost / sent
+    return {"hop": hop, "host": host, "times": times, "loss": loss}
+
+
+async def traceroute(host: str, max_hops: int = 20, queries: int = 3):
+    """Async generator yielding parsed hops as traceroute emits them."""
+    if sys.platform == "win32":
+        cmd = ["tracert", "-d", "-h", str(max_hops), host]
+    else:
+        cmd = ["traceroute", "-n", "-q", str(queries), "-w", "1",
+               "-m", str(max_hops), host]
+    try:
+        proc = await asyncio.create_subprocess_exec(
+            *cmd,
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.STDOUT,
+        )
+    except FileNotFoundError:
+        yield {"error": f"`{cmd[0]}` not found on this system"}
+        return
+
+    try:
+        assert proc.stdout is not None
+        async for raw in proc.stdout:
+            text = raw.decode(errors="replace").rstrip()
+            hop = parse_hop(text)
+            if hop:
+                yield hop
+    finally:
+        if proc.returncode is None:
+            try:
+                proc.terminate()
+            except ProcessLookupError:
+                pass
+        await proc.wait()
+
+
+def is_global_ip(value: str) -> bool:
+    """True if `value` is a public, internet-routable IP address."""
+    import ipaddress
+
+    try:
+        return ipaddress.ip_address(value).is_global
+    except ValueError:
+        return False
+
+
+def flag_emoji(iso2: str | None) -> str:
+    """ISO-3166 alpha-2 code -> regional-indicator flag emoji ('NL' -> 🇳🇱)."""
+    if not iso2 or len(iso2) != 2 or not iso2.isalpha():
+        return "🏳"
+    iso2 = iso2.upper()
+    return chr(0x1F1E6 + ord(iso2[0]) - 65) + chr(0x1F1E6 + ord(iso2[1]) - 65)
+
+
+_GEO_FIELDS = "status,country,countryCode,regionName,city,isp,as,query"
+
+
+async def geo_lookup(host: str) -> dict | None:
+    """Look a host/IP up via ip-api.com (free, no key); returns a geo dict.
+
+    Keys: country, countryCode, regionName, city, isp, as (ASN + name), query
+    (the resolved IP). Returns None on any failure. The blocking HTTP call runs
+    in a thread so the UI event loop is never stalled.
+    """
+    def fetch() -> dict:
+        import json
+        import urllib.request
+
+        url = f"http://ip-api.com/json/{host}?fields={_GEO_FIELDS}"
+        with urllib.request.urlopen(url, timeout=4) as resp:
+            return json.load(resp)
+
+    try:
+        data = await asyncio.to_thread(fetch)
+    except Exception:
+        return None
+    if data.get("status") != "success":
+        return None
+    if not data.get("country") and not data.get("countryCode"):
+        return None
+    return data
+
+
+async def desktop_notify(title: str, message: str) -> None:
+    """Best-effort OS desktop notification; silently ignored if unavailable."""
+    safe = message.replace('"', "'")
+    safe_title = title.replace('"', "'")
+    if sys.platform == "darwin":
+        script = f'display notification "{safe}" with title "{safe_title}"'
+        cmd = ["osascript", "-e", script]
+    elif sys.platform.startswith("linux"):
+        cmd = ["notify-send", safe_title, safe]
+    else:
+        return
+    try:
+        proc = await asyncio.create_subprocess_exec(
+            *cmd,
+            stdout=asyncio.subprocess.DEVNULL,
+            stderr=asyncio.subprocess.DEVNULL,
+        )
+        await proc.wait()
+    except (FileNotFoundError, OSError):
+        pass

pingmon/pinger.py

@@ -0,0 +1,44 @@
+"""Asynchronous TCP ping: measure connect time to host:port."""
+
+from __future__ import annotations
+
+import asyncio
+
+
+async def tcp_ping(host: str, port: int, timeout: float = 2.0) -> float | None:
+    """Return latency in milliseconds, or None if unreachable.
+
+    Measures the full TCP connect round-trip (SYN -> SYN/ACK), which is
+    close to the real network latency to the service on the given port.
+    """
+    loop = asyncio.get_running_loop()
+    start = loop.time()
+    writer = None
+    try:
+        fut = asyncio.open_connection(host, port)
+        reader, writer = await asyncio.wait_for(fut, timeout=timeout)
+        elapsed = (loop.time() - start) * 1000.0
+        return elapsed
+    except (OSError, asyncio.TimeoutError):
+        return None
+    finally:
+        if writer is not None:
+            try:
+                writer.close()
+                # don't await wait_closed — close timing is irrelevant here
+            except Exception:
+                pass
+
+
+async def resolve(host: str) -> str | None:
+    """Resolve a host to an IP (for display in the detail panel)."""
+    loop = asyncio.get_running_loop()
+    try:
+        infos = await asyncio.wait_for(
+            loop.getaddrinfo(host, None), timeout=3.0
+        )
+        if infos:
+            return infos[0][4][0]
+    except (OSError, asyncio.TimeoutError):
+        return None
+    return None

pingmon/render.py

@@ -0,0 +1,129 @@
+"""Visual helpers: latency colours, status meta, text sparklines."""
+
+from __future__ import annotations
+
+from rich.text import Text
+
+from .stats import EXCELLENT, FAIR, GOOD, POOR, TargetStats
+
+BARS = "▁▂▃▄▅▆▇█"
+
+# status -> (label, colour, marker)
+STATUS_META = {
+    "EXCELLENT": ("EXCELLENT", "#3ddc84", "●"),
+    "GOOD": ("GOOD", "#a6e22e", "●"),
+    "FAIR": ("FAIR", "#f4bf4f", "●"),
+    "POOR": ("POOR", "#fd8d3c", "▲"),
+    "UNSTABLE": ("UNSTABLE", "#ff6f91", "◆"),
+    "DOWN": ("DOWN", "#ff3860", "✕"),
+    "PENDING": ("PENDING", "#7a7a8c", "◌"),
+}
+
+
+def latency_color(ms: float | None) -> str:
+    if ms is None:
+        return "#ff3860"
+    if ms < EXCELLENT:
+        return "#3ddc84"
+    if ms < GOOD:
+        return "#a6e22e"
+    if ms < FAIR:
+        return "#f4bf4f"
+    if ms < POOR:
+        return "#fd8d3c"
+    return "#ff3860"
+
+
+def fmt_ms(value: float | None, width: int = 0) -> str:
+    s = "—" if value is None else f"{value:.0f}"
+    return s.rjust(width) if width else s
+
+
+def status_text(stats: TargetStats) -> Text:
+    label, color, glyph = STATUS_META[stats.status]
+    return Text(f"{glyph} {label}", style=f"bold {color}")
+
+
+def latency_text(value: float | None, suffix: str = "") -> Text:
+    color = latency_color(value)
+    s = "—" if value is None else f"{value:.0f}{suffix}"
+    return Text(s, style=color)
+
+
+def sparkline(samples, width: int = 18, lo: float | None = None, hi: float | None = None) -> Text:
+    """Coloured text sparkline from the last `width` samples.
+
+    Failures (None) render as a red cross; every bar is tinted with the
+    colour of its own latency, giving a lively mini graph.
+    """
+    data = list(samples)[-width:]
+    if not data:
+        return Text("·" * width, style="#3a3a4a")
+
+    ok = [s for s in data if s is not None]
+    lo = min(ok) if (lo is None and ok) else (lo if lo is not None else 0.0)
+    hi = max(ok) if (hi is None and ok) else (hi if hi is not None else 1.0)
+    span = (hi - lo) or 1.0
+
+    out = Text()
+    for s in data:
+        if s is None:
+            out.append("╳", style="bold #ff3860")
+            continue
+        idx = int((s - lo) / span * (len(BARS) - 1))
+        idx = max(0, min(len(BARS) - 1, idx))
+        out.append(BARS[idx], style=latency_color(s))
+    pad = width - len(data)
+    if pad > 0:
+        return Text("·" * pad, style="#3a3a4a") + out
+    return out
+
+
+def distribution_strip(samples, width: int = 24) -> Text:
+    """SmokePing-style density strip across the latency range of the window.
+
+    The x-axis runs from the window's min to max latency; each column is a bin
+    shaded by how many samples fall in it (darker = denser), tinted by the
+    latency at that point. Reveals whether a link is tight or smeared.
+    """
+    ok = [s for s in samples if s is not None]
+    if len(ok) < 2:
+        return Text("·" * width, style="#3a3a4a")
+    lo, hi = min(ok), max(ok)
+    span = (hi - lo) or 1.0
+    bins = [0] * width
+    for v in ok:
+        idx = int((v - lo) / span * (width - 1))
+        bins[min(width - 1, max(0, idx))] += 1
+    peak = max(bins) or 1
+    shades = " ░▒▓█"
+    out = Text()
+    for i, count in enumerate(bins):
+        if count == 0:
+            out.append("·", style="#2a2a38")
+            continue
+        level = max(1, int(count / peak * (len(shades) - 1)))
+        center = lo + (i + 0.5) / width * span
+        out.append(shades[level], style=latency_color(center))
+    return out
+
+
+def loss_text(loss: float) -> Text:
+    if loss <= 0:
+        return Text("0%", style="#3ddc84")
+    if loss < 5:
+        return Text(f"{loss:.0f}%", style="#f4bf4f")
+    return Text(f"{loss:.0f}%", style="bold #ff3860")
+
+
+def quality_bar(value: float | None, width: int = 20) -> Text:
+    """Horizontal quality gauge: lower latency -> longer bar."""
+    if value is None:
+        return Text("░" * width, style="#ff3860")
+    # 0ms -> full, 400ms+ -> empty
+    frac = max(0.0, min(1.0, 1.0 - value / 400.0))
+    filled = int(round(frac * width))
+    color = latency_color(value)
+    bar = Text("█" * filled, style=color)
+    bar.append("░" * (width - filled), style="#2a2a38")
+    return bar