webstat 0.1.0__py3-none-any.whl

webstat/core/notifier.py

@@ -0,0 +1,157 @@
+"""Notification dispatcher for Omarchy and standard desktop environments."""
+
+from __future__ import annotations
+
+import abc
+import re
+import shutil
+import subprocess
+import sys
+from typing import Any
+
+from webstat.core.models import CheckResult, MonitoredSite
+
+
+def _clean_notification_text(text: str) -> str:
+    """Sanitize notification text by stripping control characters and carriage returns/newlines."""
+    cleaned = text.replace("\r", " ").replace("\n", " ")
+    return re.sub(r"[\x00-\x1f\x7f-\x9f]", "", cleaned).strip()
+
+
+class BaseNotifier(abc.ABC):
+    """Abstract base class for notification providers."""
+
+    @abc.abstractmethod
+    def notify_up(self, site: MonitoredSite, result: CheckResult) -> bool:
+        """Trigger notification that a site is back up."""
+        pass
+
+
+class OmarchyNotifier(BaseNotifier):
+    """Native Omarchy desktop notification using `omarchy notification send`."""
+
+    def __init__(self):
+        self.omarchy_bin = shutil.which("omarchy")
+
+    def is_available(self) -> bool:
+        return self.omarchy_bin is not None
+
+    def notify_up(self, site: MonitoredSite, result: CheckResult) -> bool:
+        if not self.is_available():
+            return False
+
+        headline = _clean_notification_text(f"Site is UP: {site.display_name}")
+        latency_str = f" in {result.latency_ms}ms" if result.latency_ms else ""
+        code_str = f"{result.status_code} " if result.status_code else ""
+        desc = _clean_notification_text(f"{site.url} is back online ({code_str}OK{latency_str}). Click to open.")
+
+        cmd = [
+            self.omarchy_bin,
+            "notification",
+            "send",
+            "--app-name",
+            "webstat",
+            "-g",
+            "globe",
+            "-u",
+            "normal",
+            headline,
+            desc,
+            "--exec",
+            "xdg-open",
+            site.url,
+        ]
+
+        try:
+            subprocess.run(cmd, check=True, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
+            return True
+        except Exception:
+            return False
+
+
+class FreeDesktopNotifier(BaseNotifier):
+    """Standard Linux desktop notification via `notify-send`."""
+
+    def __init__(self):
+        self.notify_bin = shutil.which("notify-send")
+
+    def is_available(self) -> bool:
+        return self.notify_bin is not None
+
+    def notify_up(self, site: MonitoredSite, result: CheckResult) -> bool:
+        if not self.is_available():
+            return False
+
+        headline = _clean_notification_text(f"Site is UP: {site.display_name}")
+        desc = _clean_notification_text(f"{site.url} is back online!")
+        cmd = [self.notify_bin, "-a", "webstat", "-i", "network-idle", headline, desc]
+
+        try:
+            subprocess.run(cmd, check=True, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
+            return True
+        except Exception:
+            return False
+
+
+class BrowserLauncher(BaseNotifier):
+    """Directly opens the default browser using xdg-open."""
+
+    def notify_up(self, site: MonitoredSite, result: CheckResult) -> bool:
+        if not site.auto_open:
+            return False
+        xdg_bin = shutil.which("xdg-open")
+        if not xdg_bin:
+            return False
+        try:
+            subprocess.Popen(
+                [xdg_bin, site.url],
+                stdout=subprocess.DEVNULL,
+                stderr=subprocess.DEVNULL,
+                start_new_session=True,
+            )
+            return True
+        except Exception:
+            return False
+
+
+class TerminalBellNotifier(BaseNotifier):
+    """Audible terminal bell trigger."""
+
+    def notify_up(self, site: MonitoredSite, result: CheckResult) -> bool:
+        try:
+            sys.stdout.write("\a")
+            sys.stdout.flush()
+            return True
+        except Exception:
+            return False
+
+
+class NotificationDispatcher:
+    """Dispatches notifications across all applicable channels."""
+
+    def __init__(self, with_bell: bool = True):
+        self.omarchy = OmarchyNotifier()
+        self.freedesktop = FreeDesktopNotifier()
+        self.browser = BrowserLauncher()
+        self.bell = TerminalBellNotifier()
+        self.with_bell = with_bell
+
+    def dispatch_site_up(self, site: MonitoredSite, result: CheckResult) -> dict[str, bool]:
+        results: dict[str, bool] = {}
+
+        # 1. Desktop Notification (Omarchy first, fallback to notify-send)
+        if site.notify_on_up:
+            if self.omarchy.is_available():
+                results["omarchy"] = self.omarchy.notify_up(site, result)
+            elif self.freedesktop.is_available():
+                results["desktop"] = self.freedesktop.notify_up(site, result)
+
+        # 2. Browser Auto-Open
+        if site.auto_open:
+            results["browser_open"] = self.browser.notify_up(site, result)
+
+        # 3. Terminal Bell
+        if self.with_bell:
+            results["bell"] = self.bell.notify_up(site, result)
+
+        return results

webstat/core/scheduler.py

@@ -0,0 +1,110 @@
+"""Monitoring loop and scheduler for watching website status and triggering reminders."""
+
+from __future__ import annotations
+
+import asyncio
+import time
+from typing import Callable
+
+from webstat.core.checker import HttpChecker
+from webstat.core.models import CheckResult, MonitoredSite, SiteStatus
+from webstat.core.notifier import NotificationDispatcher
+from webstat.core.store import SiteStore
+
+
+class WatchScheduler:
+    """Orchestrates polling sites, detecting recovery, and dispatching notifications."""
+
+    def __init__(
+        self,
+        store: SiteStore | None = None,
+        dispatcher: NotificationDispatcher | None = None,
+        checker: HttpChecker | None = None,
+        poll_interval: float = 5.0,
+        max_interval: float = 60.0,
+        adaptive_backoff: bool = True,
+        notification_cooldown: float = 60.0,
+    ):
+        self.store = store or SiteStore()
+        self.dispatcher = dispatcher or NotificationDispatcher()
+        self.checker = checker or HttpChecker()
+        self.poll_interval = poll_interval
+        self.max_interval = max_interval
+        self.adaptive_backoff = adaptive_backoff
+        self.notification_cooldown = notification_cooldown
+        self._running = False
+
+    def compute_delay(self, retries: int) -> float:
+        """Compute poll delay with optional adaptive backoff."""
+        if not self.adaptive_backoff:
+            return self.poll_interval
+        factor = min(retries // 3, 4)
+        return min(self.poll_interval * (1.5**factor), self.max_interval)
+
+    async def check_and_update(self, site: MonitoredSite) -> tuple[CheckResult, bool]:
+        """Check a single site, update store, and dispatch notification if recovered.
+
+        Returns (CheckResult, just_recovered: bool).
+        """
+        was_down = not site.is_up and site.status != SiteStatus.UNKNOWN
+        result = await self.checker.check(site.url)
+
+        site.status = result.status
+        site.status_code = result.status_code
+        site.latency_ms = result.latency_ms
+        site.last_checked = result.timestamp
+        site.last_error = result.error_message
+
+        just_recovered = False
+        now = time.time()
+        if result.is_up:
+            if was_down or site.retries > 0:
+                # Enforce cooldown window to debounce flapping endpoints and prevent browser/notification floods
+                if site.last_notified_at is None or (now - site.last_notified_at) >= self.notification_cooldown:
+                    just_recovered = True
+                    site.last_notified_at = now
+                    self.dispatcher.dispatch_site_up(site, result)
+            site.retries = 0
+        else:
+            site.retries += 1
+
+        self.store.update_site(site)
+        return result, just_recovered
+
+    async def watch_sites(
+        self,
+        sites: list[MonitoredSite],
+        on_tick: Callable[[MonitoredSite, CheckResult, bool], None] | None = None,
+    ) -> None:
+        """Watch a list of sites until all are online (unless keep_watching is True)."""
+        self._running = True
+        active_sites = list(sites)
+
+        try:
+            while self._running and active_sites:
+                remaining: list[MonitoredSite] = []
+
+                for site in active_sites:
+                    result, just_recovered = await self.check_and_update(site)
+                    if on_tick:
+                        on_tick(site, result, just_recovered)
+
+                    if result.is_up and not site.keep_watching:
+                        # Site is up and completed reminder
+                        continue
+                    remaining.append(site)
+
+                active_sites = remaining
+                if not active_sites:
+                    break
+
+                # Determine sleep delay from min retry count
+                min_retries = min(s.retries for s in active_sites)
+                delay = self.compute_delay(min_retries)
+                await asyncio.sleep(delay)
+
+        finally:
+            self._running = False
+
+    def stop(self) -> None:
+        self._running = False

webstat/core/store.py

@@ -0,0 +1,210 @@
+"""Atomic XDG state storage for webstat monitored sites."""
+
+from __future__ import annotations
+
+from contextlib import contextmanager
+import fcntl
+import hashlib
+import json
+import os
+from pathlib import Path
+import tempfile
+from typing import Any
+
+from webstat.core.models import MonitoredSite
+from webstat.utils.url import get_display_name, normalize_url
+
+
+def get_default_state_path() -> Path:
+    """Return the state file path respecting XDG_STATE_HOME with 0700 permissions."""
+    state_dir = os.environ.get("XDG_STATE_HOME")
+    if state_dir:
+        base = Path(state_dir)
+    else:
+        base = Path.home() / ".local" / "state"
+    target_dir = base / "webstat"
+    target_dir.mkdir(parents=True, exist_ok=True)
+    try:
+        os.chmod(target_dir, 0o700)
+    except OSError:
+        pass
+    return target_dir / "sites.json"
+
+
+def generate_site_id(url: str) -> str:
+    """Generate a stable, clean identifier for a URL."""
+    normalized = normalize_url(url)
+    h = hashlib.sha256(normalized.encode("utf-8")).hexdigest()[:10]
+    host = get_display_name(normalized).replace(".", "-").replace(":", "-")
+    return f"{host}-{h}"
+
+
+class SiteStore:
+    """Thread-safe and process-safe state store using atomic JSON file replacement and POSIX file locking."""
+
+    def __init__(self, file_path: Path | None = None):
+        self.file_path = file_path or get_default_state_path()
+        self._lock_depth = 0
+        self._lock_fd: int | None = None
+
+    @contextmanager
+    def _file_lock(self, shared: bool = False):
+        """Re-entrant file lock coordinator for multi-process safety (daemon, CLI, QML)."""
+        if self._lock_depth > 0:
+            self._lock_depth += 1
+            try:
+                yield
+            finally:
+                self._lock_depth -= 1
+            return
+
+        lock_path = self.file_path.with_suffix(".lock")
+        target_dir = lock_path.parent
+        target_dir.mkdir(parents=True, exist_ok=True)
+        try:
+            os.chmod(target_dir, 0o700)
+        except OSError:
+            pass
+
+        flags = fcntl.LOCK_SH if shared else fcntl.LOCK_EX
+        try:
+            fd = os.open(lock_path, os.O_CREAT | os.O_RDWR, 0o600)
+            try:
+                os.chmod(lock_path, 0o600)
+            except OSError:
+                pass
+            fcntl.flock(fd, flags)
+            self._lock_fd = fd
+            self._lock_depth = 1
+            try:
+                yield
+            finally:
+                self._lock_depth = 0
+                self._lock_fd = None
+                try:
+                    fcntl.flock(fd, fcntl.LOCK_UN)
+                except OSError:
+                    pass
+                os.close(fd)
+        except OSError:
+            # Fallback if filesystem does not support flock
+            yield
+
+    def load_all(self) -> list[MonitoredSite]:
+        with self._file_lock(shared=True):
+            if not self.file_path.exists():
+                return []
+            try:
+                with open(self.file_path, "r", encoding="utf-8") as f:
+                    data: list[dict[str, Any]] = json.load(f)
+                    return [MonitoredSite.from_dict(item) for item in data]
+            except Exception:
+                return []
+
+    def save_all(self, sites: list[MonitoredSite]) -> None:
+        raw_data = [s.to_dict() for s in sites]
+        target_dir = self.file_path.parent
+        target_dir.mkdir(parents=True, exist_ok=True)
+        try:
+            os.chmod(target_dir, 0o700)
+        except OSError:
+            pass
+
+        with self._file_lock(shared=False):
+            # Unpredictable atomic temp file with 0600 permissions
+            with tempfile.NamedTemporaryFile(
+                mode="w",
+                dir=target_dir,
+                encoding="utf-8",
+                delete=False,
+                prefix=".sites_",
+                suffix=".tmp",
+            ) as tmp:
+                temp_path = Path(tmp.name)
+                try:
+                    os.chmod(temp_path, 0o600)
+                except OSError:
+                    pass
+                json.dump(raw_data, tmp, indent=2, ensure_ascii=False)
+                tmp.flush()
+                os.fsync(tmp.fileno())
+
+            # Atomic replacement on POSIX
+            temp_path.replace(self.file_path)
+            try:
+                os.chmod(self.file_path, 0o600)
+            except OSError:
+                pass
+
+    def get_by_id_or_url(self, id_or_url: str) -> MonitoredSite | None:
+        sites = self.load_all()
+        clean = id_or_url.strip()
+        for s in sites:
+            if s.id == clean or s.url == clean or s.display_name == clean or s.raw_input == clean:
+                return s
+        try:
+            normalized = normalize_url(clean)
+            for s in sites:
+                if s.url == normalized:
+                    return s
+        except Exception:
+            pass
+        return None
+
+    def add(
+        self,
+        raw_url: str,
+        auto_open: bool = False,
+        notify_on_up: bool = True,
+        keep_watching: bool = False,
+    ) -> MonitoredSite:
+        with self._file_lock(shared=False):
+            normalized = normalize_url(raw_url)
+            site_id = generate_site_id(normalized)
+            sites = self.load_all()
+
+            existing = next((s for s in sites if s.id == site_id), None)
+            if existing:
+                existing.auto_open = auto_open or existing.auto_open
+                existing.notify_on_up = notify_on_up
+                existing.keep_watching = keep_watching
+                self.save_all(sites)
+                return existing
+
+            site = MonitoredSite(
+                id=site_id,
+                url=normalized,
+                display_name=get_display_name(normalized),
+                raw_input=raw_url,
+                auto_open=auto_open,
+                notify_on_up=notify_on_up,
+                keep_watching=keep_watching,
+            )
+            sites.append(site)
+            self.save_all(sites)
+            return site
+
+    def update_site(self, site: MonitoredSite) -> None:
+        with self._file_lock(shared=False):
+            sites = self.load_all()
+            for idx, s in enumerate(sites):
+                if s.id == site.id:
+                    sites[idx] = site
+                    break
+            else:
+                sites.append(site)
+            self.save_all(sites)
+
+    def remove(self, id_or_url: str) -> bool:
+        with self._file_lock(shared=False):
+            site = self.get_by_id_or_url(id_or_url)
+            if not site:
+                return False
+            sites = self.load_all()
+            sites = [s for s in sites if s.id != site.id]
+            self.save_all(sites)
+            return True
+
+    def clear(self) -> None:
+        with self._file_lock(shared=False):
+            self.save_all([])

webstat/utils/__init__.py

@@ -0,0 +1,5 @@
+"""Utility functions for webstat."""
+
+from webstat.utils.url import get_display_name, normalize_url
+
+__all__ = ["normalize_url", "get_display_name"]

webstat/utils/formatting.py

@@ -0,0 +1,74 @@
+"""Formatting helpers for rich terminal output."""
+
+from __future__ import annotations
+
+from rich.table import Table
+from rich.text import Text
+
+from webstat.core.models import CheckResult, MonitoredSite, SiteStatus
+
+
+def get_status_badge(status: SiteStatus, status_code: int | None = None) -> Text:
+    """Generate a stylized text badge for a site status."""
+    code_text = f" {status_code}" if status_code else ""
+
+    if status == SiteStatus.ONLINE:
+        return Text(f"● ONLINE{code_text}", style="bold green")
+    elif status == SiteStatus.REDIRECT:
+        return Text(f"↗ REDIRECT{code_text}", style="bold cyan")
+    elif status == SiteStatus.CLIENT_ERROR:
+        return Text(f"▲ CLIENT ERROR{code_text}", style="bold yellow")
+    elif status == SiteStatus.SERVER_ERROR:
+        return Text(f"✖ SERVER ERROR{code_text}", style="bold red")
+    elif status == SiteStatus.UNREACHABLE:
+        return Text("✖ UNREACHABLE", style="bold red on default")
+    else:
+        return Text("? UNKNOWN", style="dim")
+
+
+def get_latency_text(latency_ms: float | None) -> Text:
+    """Format latency with appropriate color coding."""
+    if latency_ms is None:
+        return Text("—", style="dim")
+    if latency_ms < 200:
+        return Text(f"{latency_ms} ms", style="green")
+    elif latency_ms < 800:
+        return Text(f"{latency_ms} ms", style="yellow")
+    else:
+        return Text(f"{latency_ms} ms", style="magenta")
+
+
+def build_sites_table(sites: list[MonitoredSite]) -> Table:
+    """Construct a clean Rich table of all monitored sites."""
+    table = Table(
+        title="Webstat Monitored Sites",
+        title_style="bold cyan",
+        header_style="bold",
+        border_style="dim",
+        expand=True,
+    )
+
+    table.add_column("Site", style="bold white", no_wrap=True)
+    table.add_column("Status", justify="left")
+    table.add_column("Latency", justify="right")
+    table.add_column("Retries", justify="right")
+    table.add_column("Auto Open", justify="center")
+    table.add_column("Last Error / Details", style="dim")
+
+    for site in sites:
+        badge = get_status_badge(site.status, site.status_code)
+        latency = get_latency_text(site.latency_ms)
+        retries = str(site.retries) if site.retries > 0 else "—"
+        auto_open = "✓ Yes" if site.auto_open else "No"
+        details = site.last_error or "—"
+
+        table.add_row(
+            site.display_name,
+            badge,
+            latency,
+            retries,
+            auto_open,
+            details,
+        )
+
+    return table

webstat/utils/url.py

@@ -0,0 +1,62 @@
+"""URL utilities for webstat."""
+
+import re
+from urllib.parse import urlparse
+
+
+def _strip_ansi_and_control(text: str) -> str:
+    """Remove ANSI escape sequences and non-printable control characters."""
+    # First strip ANSI escape sequences (e.g. \x1b[31m)
+    no_ansi = re.sub(r"\x1b\[[0-9;]*[a-zA-Z]", "", text)
+    # Then strip ASCII/Latin-1 C0 and C1 control characters
+    return re.sub(r"[\x00-\x1f\x7f-\x9f]", "", no_ansi).strip()
+
+
+def normalize_url(raw_url: str) -> str:
+    """Normalize a user-provided URL or hostname.
+
+    Examples:
+        - "github.com" -> "https://github.com"
+        - "localhost:3000" -> "http://localhost:3000"
+        - "127.0.0.1:8000" -> "http://127.0.0.1:8000"
+        - "http://example.com" -> "http://example.com"
+        - "https://mysite.org/health" -> "https://mysite.org/health"
+    """
+    url = _strip_ansi_and_control(raw_url)
+    if not url:
+        raise ValueError("URL cannot be empty")
+
+    # If scheme is already present, validate that it is HTTP or HTTPS
+    if "://" in url:
+        if not re.match(r"^https?://", url, re.IGNORECASE):
+            raise ValueError(f"Unsupported URL scheme. Only http:// and https:// are supported: {raw_url}")
+        parsed = urlparse(url)
+        if not parsed.netloc:
+            raise ValueError(f"Invalid URL: {raw_url}")
+        return url
+
+    # Default to http:// for localhost or IP with port, https:// otherwise
+    if url.startswith("localhost") or url.startswith("127.0.0.1") or url.startswith("0.0.0.0"):
+        url = f"http://{url}"
+    else:
+        url = f"https://{url}"
+
+    parsed = urlparse(url)
+    if not parsed.netloc:
+        raise ValueError(f"Invalid URL or hostname: {raw_url}")
+
+    return url
+
+
+def get_display_name(url: str) -> str:
+    """Extract a friendly clean name for display and notifications, omitting embedded credentials."""
+    try:
+        parsed = urlparse(url)
+        host = parsed.hostname or parsed.path
+        if parsed.port and parsed.port not in (80, 443):
+            host = f"{host}:{parsed.port}"
+        # Strip any ANSI escape sequences or control characters
+        host = _strip_ansi_and_control(host)
+        return host or _strip_ansi_and_control(url)
+    except Exception:
+        return _strip_ansi_and_control(url)