chap-checker 0.1.0__tar.gz

chap_checker-0.1.0/PKG-INFO

@@ -0,0 +1,139 @@
+Metadata-Version: 2.3
+Name: chap-checker
+Version: 0.1.0
+Summary: Health-check CLI for DHIS2 instances integrated with chap-core; cron-friendly with Slack alerts on status transitions.
+Keywords: dhis2,chap,chap-core,healthcheck,monitoring,slack,cli
+Author: Morten Hansen
+Author-email: Morten Hansen <morten@dhis2.org>
+License: AGPL-3.0-or-later
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: System :: Monitoring
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Dist: typer>=0.24.2
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: pydantic>=2.9.0
+Requires-Dist: rich>=13.9.0
+Requires-Dist: textual>=8.0.0
+Requires-Dist: fastapi>=0.115.0
+Requires-Dist: uvicorn[standard]>=0.30.0
+Requires-Python: >=3.13
+Project-URL: Homepage, https://github.com/dhis2-chap/chap-checker
+Project-URL: Repository, https://github.com/dhis2-chap/chap-checker
+Project-URL: Issues, https://github.com/dhis2-chap/chap-checker/issues
+Description-Content-Type: text/markdown
+
+# chap-checker
+
+[![CI](https://github.com/dhis2-chap/chap-checker/actions/workflows/ci.yml/badge.svg)](https://github.com/dhis2-chap/chap-checker/actions/workflows/ci.yml)
+[![PyPI version](https://img.shields.io/pypi/v/chap-checker)](https://pypi.org/project/chap-checker/)
+[![Python 3.13+](https://img.shields.io/badge/python-3.13+-blue.svg)](https://www.python.org/downloads/)
+[![License: AGPL v3](https://img.shields.io/badge/License-AGPL_v3-blue.svg)](https://www.gnu.org/licenses/agpl-3.0)
+[![Documentation](https://img.shields.io/badge/docs-mkdocs-blue.svg)](https://dhis2-chap.github.io/chap-checker/)
+
+A small command-line health-check and alerting tool for DHIS2 instances that
+integrate with `chap-core` via a DHIS2 route. Cron-friendly, with optional
+Slack alerts on status transitions and a Textual TUI dashboard for the
+at-a-glance "leave it on a TV" view.
+
+**Documentation:** <https://dhis2-chap.github.io/chap-checker>
+
+## Install
+
+```bash
+# One-shot run without installing (no PATH pollution):
+uvx chap-checker --version
+uvx chap-checker verify --url https://dhis2.example.com --token-env DHIS2_TOKEN
+
+# Persistent install into uv's isolated tool environment:
+uv tool install chap-checker
+chap-checker --version
+
+# Upgrade to the latest release later:
+uv tool upgrade chap-checker
+
+# Or, if you're embedding into another uv project:
+uv add chap-checker
+```
+
+## Quick start
+
+Ad-hoc against a single instance (credentials resolved safely):
+
+```bash
+# With a DHIS2 Personal Access Token (recommended on modern servers):
+export PROD_TOKEN=...
+chap-checker verify \
+    --url https://dhis2.example.com \
+    --token-env PROD_TOKEN
+
+# With a password (Basic auth) read from a named env var:
+export PROD_PASSWORD=...
+chap-checker verify \
+    --url https://dhis2.example.com \
+    --username admin \
+    --password-env PROD_PASSWORD
+
+# Omit --password / --token entirely and you'll be prompted on the
+# terminal (hidden input). DHIS2_TOKEN / DHIS2_PASSWORD env vars
+# work as defaults too. Passing --password / --token inline still
+# works but is discouraged - the value lands in shell history and
+# `ps` output. Token and password flags are mutually exclusive.
+```
+
+Multiple instances in `./chap-checker.toml`:
+
+```toml
+[instances.prod]
+url = "https://dhis2.example.com"
+username = "ops"
+password_env = "PROD_PASS"
+alerts = ["slack"]
+
+[alerts.slack]
+webhook_url_env = "SLACK_WEBHOOK_URL"
+```
+
+Then `chap-checker verify` runs every configured instance and pages Slack on
+status transitions. See [chap-checker.toml.example](./chap-checker.toml.example)
+for the full template.
+
+The TUI:
+
+```bash
+chap-checker dashboard
+```
+
+## Built-in checks
+
+Two namespaces — `dhis2_*` probes DHIS2 itself, `dhis2_chap_*` probes
+chap-core through the DHIS2 route. Each tile in the dashboard, each row in
+`chap-checker checks list`, each entry in the JSON output:
+
+- `dhis2_ping` — `/api/me`
+- `dhis2_system_info` — `/api/system/info`
+- `dhis2_chap_route` — `/api/routes?filter=code:eq:chap`
+- `dhis2_chap_ping` — `/api/routes/chap/run/health`
+- `dhis2_chap_system_info` — `/api/routes/chap/run/system/info`
+- `dhis2_chap_modeling_app` — `/api/apps` (matched by `app_hub_id`)
+
+Full reference + endpoint details: [Built-in checks](https://dhis2-chap.github.io/chap-checker/guides/checks/).
+
+## Development
+
+```bash
+make install
+make lint        # ruff + mypy + pyright
+make test
+make docs        # serve docs locally
+```
+
+See [Development](https://dhis2-chap.github.io/chap-checker/guides/development/)
+for repo layout and house rules.
+
+## License
+
+AGPL-3.0-or-later

chap_checker-0.1.0/README.md

@@ -0,0 +1,111 @@
+# chap-checker
+
+[![CI](https://github.com/dhis2-chap/chap-checker/actions/workflows/ci.yml/badge.svg)](https://github.com/dhis2-chap/chap-checker/actions/workflows/ci.yml)
+[![PyPI version](https://img.shields.io/pypi/v/chap-checker)](https://pypi.org/project/chap-checker/)
+[![Python 3.13+](https://img.shields.io/badge/python-3.13+-blue.svg)](https://www.python.org/downloads/)
+[![License: AGPL v3](https://img.shields.io/badge/License-AGPL_v3-blue.svg)](https://www.gnu.org/licenses/agpl-3.0)
+[![Documentation](https://img.shields.io/badge/docs-mkdocs-blue.svg)](https://dhis2-chap.github.io/chap-checker/)
+
+A small command-line health-check and alerting tool for DHIS2 instances that
+integrate with `chap-core` via a DHIS2 route. Cron-friendly, with optional
+Slack alerts on status transitions and a Textual TUI dashboard for the
+at-a-glance "leave it on a TV" view.
+
+**Documentation:** <https://dhis2-chap.github.io/chap-checker>
+
+## Install
+
+```bash
+# One-shot run without installing (no PATH pollution):
+uvx chap-checker --version
+uvx chap-checker verify --url https://dhis2.example.com --token-env DHIS2_TOKEN
+
+# Persistent install into uv's isolated tool environment:
+uv tool install chap-checker
+chap-checker --version
+
+# Upgrade to the latest release later:
+uv tool upgrade chap-checker
+
+# Or, if you're embedding into another uv project:
+uv add chap-checker
+```
+
+## Quick start
+
+Ad-hoc against a single instance (credentials resolved safely):
+
+```bash
+# With a DHIS2 Personal Access Token (recommended on modern servers):
+export PROD_TOKEN=...
+chap-checker verify \
+    --url https://dhis2.example.com \
+    --token-env PROD_TOKEN
+
+# With a password (Basic auth) read from a named env var:
+export PROD_PASSWORD=...
+chap-checker verify \
+    --url https://dhis2.example.com \
+    --username admin \
+    --password-env PROD_PASSWORD
+
+# Omit --password / --token entirely and you'll be prompted on the
+# terminal (hidden input). DHIS2_TOKEN / DHIS2_PASSWORD env vars
+# work as defaults too. Passing --password / --token inline still
+# works but is discouraged - the value lands in shell history and
+# `ps` output. Token and password flags are mutually exclusive.
+```
+
+Multiple instances in `./chap-checker.toml`:
+
+```toml
+[instances.prod]
+url = "https://dhis2.example.com"
+username = "ops"
+password_env = "PROD_PASS"
+alerts = ["slack"]
+
+[alerts.slack]
+webhook_url_env = "SLACK_WEBHOOK_URL"
+```
+
+Then `chap-checker verify` runs every configured instance and pages Slack on
+status transitions. See [chap-checker.toml.example](./chap-checker.toml.example)
+for the full template.
+
+The TUI:
+
+```bash
+chap-checker dashboard
+```
+
+## Built-in checks
+
+Two namespaces — `dhis2_*` probes DHIS2 itself, `dhis2_chap_*` probes
+chap-core through the DHIS2 route. Each tile in the dashboard, each row in
+`chap-checker checks list`, each entry in the JSON output:
+
+- `dhis2_ping` — `/api/me`
+- `dhis2_system_info` — `/api/system/info`
+- `dhis2_chap_route` — `/api/routes?filter=code:eq:chap`
+- `dhis2_chap_ping` — `/api/routes/chap/run/health`
+- `dhis2_chap_system_info` — `/api/routes/chap/run/system/info`
+- `dhis2_chap_modeling_app` — `/api/apps` (matched by `app_hub_id`)
+
+Full reference + endpoint details: [Built-in checks](https://dhis2-chap.github.io/chap-checker/guides/checks/).
+
+## Development
+
+```bash
+make install
+make lint        # ruff + mypy + pyright
+make test
+make docs        # serve docs locally
+```
+
+See [Development](https://dhis2-chap.github.io/chap-checker/guides/development/)
+for repo layout and house rules.
+
+## License
+
+AGPL-3.0-or-later

chap_checker-0.1.0/pyproject.toml

@@ -0,0 +1,124 @@
+[project]
+name = "chap-checker"
+version = "0.1.0"
+description = "Health-check CLI for DHIS2 instances integrated with chap-core; cron-friendly with Slack alerts on status transitions."
+readme = "README.md"
+authors = [{ name = "Morten Hansen", email = "morten@dhis2.org" }]
+license = { text = "AGPL-3.0-or-later" }
+requires-python = ">=3.13"
+keywords = ["dhis2", "chap", "chap-core", "healthcheck", "monitoring", "slack", "cli"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "Intended Audience :: System Administrators",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: System :: Monitoring",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+  "typer>=0.24.2",
+  "httpx>=0.28.1",
+  "pydantic>=2.9.0",
+  "rich>=13.9.0",
+  "textual>=8.0.0",
+  "fastapi>=0.115.0",
+  "uvicorn[standard]>=0.30.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/dhis2-chap/chap-checker"
+Repository = "https://github.com/dhis2-chap/chap-checker"
+Issues = "https://github.com/dhis2-chap/chap-checker/issues"
+
+[project.scripts]
+chap-checker = "chap_checker.cli:main"
+
+[dependency-groups]
+dev = [
+  "coverage[toml]>=7.6.0",
+  "mkdocs>=1.6.0",
+  "mkdocs-material>=9.5.0",
+  "mypy>=1.13.0",
+  "pyright>=1.1.400",
+  "pytest>=8.3.0",
+  "pytest-asyncio>=0.24.0",
+  "ruff>=0.7.0",
+]
+
+[build-system]
+requires = ["uv_build>=0.9.0,<0.12.0"]
+build-backend = "uv_build"
+
+[tool.ruff]
+target-version = "py313"
+line-length = 120
+
+[tool.ruff.lint]
+fixable = ["ALL"]
+select = ["E", "W", "F", "I", "D"]
+ignore = ["D203", "D213"]
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**/*.py" = ["D"]
+"**/__init__.py" = ["D104"]
+"src/**/*.py" = ["D102", "D105", "D107"]
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+skip-magic-trailing-comma = false
+docstring-code-format = true
+docstring-code-line-length = "dynamic"
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+norecursedirs = [".git", ".venv", "__pycache__"]
+
+[tool.coverage.run]
+branch = true
+relative_files = true
+source = ["chap_checker"]
+
+[tool.coverage.report]
+exclude_also = ["if TYPE_CHECKING:"]
+precision = 2
+show_missing = true
+skip_covered = true
+
+[tool.mypy]
+python_version = "3.13"
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = true
+check_untyped_defs = true
+no_implicit_optional = true
+warn_unused_ignores = true
+strict_equality = true
+mypy_path = ["src"]
+
+[[tool.mypy.overrides]]
+module = "tests.*"
+disallow_untyped_defs = false
+
+[tool.pyright]
+include = ["src", "tests"]
+exclude = ["**/.venv"]
+pythonVersion = "3.13"
+typeCheckingMode = "strict"
+useLibraryCodeForTypes = true
+reportPrivateUsage = false
+reportUnusedFunction = false
+reportUnknownMemberType = false
+reportUnknownArgumentType = false
+reportUnknownParameterType = false
+reportUnknownVariableType = false
+reportUnknownLambdaType = false
+reportMissingTypeArgument = false
+reportMissingTypeStubs = false
+reportMissingImports = "warning"
+reportMissingModuleSource = false

chap_checker-0.1.0/src/chap_checker/__init__.py

@@ -0,0 +1,10 @@
+"""chap-checker - run a suite of checks against a DHIS2 server."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("chap-checker")
+except PackageNotFoundError:  # pragma: no cover
+    __version__ = "0.0.0"
+
+__all__ = ["__version__"]

chap_checker-0.1.0/src/chap_checker/__main__.py

@@ -0,0 +1,6 @@
+"""Allow ``python -m chap_checker`` to invoke the CLI."""
+
+from chap_checker.cli import main
+
+if __name__ == "__main__":
+    main()

chap_checker-0.1.0/src/chap_checker/alerts/__init__.py

@@ -0,0 +1,6 @@
+"""Alerter implementations (currently: Slack Incoming Webhook)."""
+
+from chap_checker.alerts.base import Alerter, AlerterBinding, Transition, TransitionKind
+from chap_checker.alerts.slack import SlackAlerter
+
+__all__ = ["Alerter", "AlerterBinding", "SlackAlerter", "Transition", "TransitionKind"]

chap_checker-0.1.0/src/chap_checker/alerts/base.py

@@ -0,0 +1,99 @@
+"""Alerter protocol and the Transition pydantic model that drives it."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from datetime import datetime
+from typing import ClassVar, Literal, Protocol, TypeVar, runtime_checkable
+
+from pydantic import BaseModel, ConfigDict
+
+from chap_checker.checks.base import Status
+
+TransitionKind = Literal["failure", "recovery"]
+
+
+class Transition(BaseModel):
+    """A single status change worth alerting on.
+
+    Emitted by :func:`chap_checker.state_store.compute_transitions` when a
+    check's status flips between OK and a non-OK family member.
+    """
+
+    kind: TransitionKind
+    target_name: str
+    target_url: str
+    check_name: str
+    previous_status: Status
+    current_status: Status
+    message: str
+    duration_ms: float
+    occurred_at: datetime
+
+
+@runtime_checkable
+class Alerter(Protocol):
+    """Protocol all alerters implement.
+
+    Implementations *may* raise on delivery failure - the dispatcher
+    (:func:`chap_checker.cli._dispatch_alerts`) catches the exception, logs
+    it, and skips the state-file save so the transition is retried on the
+    next run. Alert delivery failures never change the run's exit code
+    regardless of whether the alerter raises or swallows.
+    """
+
+    name: ClassVar[str]
+
+    async def notify(self, transitions: list[Transition]) -> None:
+        """Send the given transitions out-of-band.
+
+        May raise on transport / non-2xx responses; the dispatcher decides
+        whether to surface the failure.
+        """
+        ...
+
+
+class AlerterBinding(BaseModel):
+    """Pairs a runtime :class:`Alerter` instance with the statuses it cares about."""
+
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    alerter: Alerter
+    notify_on: set[Status]
+
+
+_ALERTER_CLASSES: dict[str, type[Alerter]] = {}
+
+_TAlerter = TypeVar("_TAlerter", bound=type[Alerter])
+
+
+def register_alerter(name: str) -> Callable[[_TAlerter], _TAlerter]:
+    """Class decorator: register an alerter class under ``name``.
+
+    This is currently a discovery aid - the CLI's per-alerter config wiring
+    (:func:`chap_checker.cli._build_alerters`) still instantiates known
+    alerters by hand, but the registry makes new alerters introspectable
+    and is the seam for a future plugin-style config layer.
+
+    Example:
+        @register_alerter("slack")
+        class SlackAlerter:
+            name = "slack"
+            ...
+    """
+
+    def deco(cls: _TAlerter) -> _TAlerter:
+        _ALERTER_CLASSES[name] = cls
+        return cls
+
+    return deco
+
+
+def alerter_class(name: str) -> type[Alerter] | None:
+    """Return the registered alerter class for ``name``, or ``None``."""
+    return _ALERTER_CLASSES.get(name)
+
+
+def all_alerter_classes() -> dict[str, type[Alerter]]:
+    """Return a copy of the alerter-class registry keyed by name."""
+    return dict(_ALERTER_CLASSES)

chap_checker-0.1.0/src/chap_checker/alerts/slack.py

@@ -0,0 +1,125 @@
+"""Slack Incoming Webhook alerter."""
+
+from __future__ import annotations
+
+from typing import ClassVar, Literal
+
+import httpx
+from pydantic import BaseModel
+
+from chap_checker.alerts.base import Transition, register_alerter
+from chap_checker.checks.base import Status
+from chap_checker.logging import get_logger
+
+_log = get_logger("alerts.slack")
+
+# Slack's status colors (from their brand guide; render well on dark and light).
+_COLOR_BY_STATUS: dict[Status, str] = {
+    Status.OK: "#2EB67D",  # green
+    Status.WARN: "#ECB22E",  # yellow
+    Status.FAIL: "#E01E5A",  # red
+    Status.ERROR: "#E01E5A",  # red (same family as FAIL)
+}
+
+
+class SlackBlockText(BaseModel):
+    """Slack Block Kit text element (``plain_text`` or ``mrkdwn``)."""
+
+    type: Literal["plain_text", "mrkdwn"]
+    text: str
+
+
+class SlackBlock(BaseModel):
+    """Single Slack Block Kit block (header or section)."""
+
+    type: Literal["header", "section"]
+    text: SlackBlockText
+
+
+class SlackAttachment(BaseModel):
+    """Legacy Slack attachment that gives Block Kit a colored left border.
+
+    Block Kit blocks on their own can't render the vertical color stripe;
+    wrapping the same blocks in an attachment with ``color`` gets it back.
+    """
+
+    color: str
+    blocks: list[SlackBlock]
+
+
+class SlackPayload(BaseModel):
+    """Body posted to a Slack Incoming Webhook."""
+
+    text: str
+    blocks: list[SlackBlock]
+    attachments: list[SlackAttachment]
+
+
+@register_alerter("slack")
+class SlackAlerter:
+    """POST a Block Kit message to a Slack Incoming Webhook URL.
+
+    Always raises on transport / 5xx so the cron-side dispatcher can decide
+    whether to commit state (it doesn't) and whether to surface the failure
+    in exit code (it doesn't - just logs).
+    """
+
+    name: ClassVar[str] = "slack"
+
+    def __init__(
+        self,
+        webhook_url: str,
+        timeout_s: float = 10.0,
+        transport: httpx.AsyncBaseTransport | None = None,
+    ) -> None:
+        self._webhook_url = webhook_url
+        self._timeout_s = timeout_s
+        self._transport = transport
+
+    async def notify(self, transitions: list[Transition]) -> None:
+        """POST the transitions to Slack.
+
+        Raises on transport errors or non-2xx responses. The caller is
+        responsible for deciding what to do with the failure (the cron-side
+        dispatcher swallows it but skips the state save so the transition
+        retries next run).
+        """
+        if not transitions:
+            return
+        payload = _build_payload(transitions)
+        async with httpx.AsyncClient(timeout=self._timeout_s, transport=self._transport) as client:
+            response = await client.post(self._webhook_url, json=payload.model_dump(mode="json"))
+        if response.status_code >= 400:
+            raise RuntimeError(f"slack webhook returned {response.status_code}: {response.text[:200]}")
+
+
+def _color_for(transition: Transition) -> str:
+    if transition.kind == "recovery":
+        return _COLOR_BY_STATUS[Status.OK]
+    return _COLOR_BY_STATUS.get(transition.current_status, _COLOR_BY_STATUS[Status.FAIL])
+
+
+def _build_payload(transitions: list[Transition]) -> SlackPayload:
+    failures = [t for t in transitions if t.kind == "failure"]
+    recoveries = [t for t in transitions if t.kind == "recovery"]
+    failure_word = "failure" if len(failures) == 1 else "failures"
+    recovery_word = "recovery" if len(recoveries) == 1 else "recoveries"
+    summary = f"chap-checker: {len(failures)} new {failure_word}, {len(recoveries)} {recovery_word}"
+
+    header_blocks: list[SlackBlock] = [
+        SlackBlock(type="header", text=SlackBlockText(type="plain_text", text=summary)),
+    ]
+
+    attachments: list[SlackAttachment] = []
+    for t in transitions:
+        label = "FAILURE" if t.kind == "failure" else "RECOVERY"
+        status_label = t.current_status.value.upper()
+        body = f"*{label} — `{t.target_name}`*\n{t.target_url}\n`{t.check_name}`  *{status_label}*  {t.message}"
+        attachments.append(
+            SlackAttachment(
+                color=_color_for(t),
+                blocks=[SlackBlock(type="section", text=SlackBlockText(type="mrkdwn", text=body))],
+            )
+        )
+
+    return SlackPayload(text=summary, blocks=header_blocks, attachments=attachments)

chap_checker-0.1.0/src/chap_checker/checks/__init__.py

@@ -0,0 +1,37 @@
+"""Check implementations.
+
+Importing this package triggers each check module, which registers itself
+via :func:`chap_checker.checks.base.register_check`.
+"""
+
+from chap_checker.checks import (
+    dhis2_chap_modeling_app,
+    dhis2_chap_ping,
+    dhis2_chap_route,
+    dhis2_chap_system_info,
+    dhis2_ping,
+    dhis2_system_info,
+)
+from chap_checker.checks.base import (
+    Check,
+    CheckResult,
+    Status,
+    all_checks,
+    register_check,
+    resolve_checks,
+)
+
+__all__ = [
+    "Check",
+    "CheckResult",
+    "Status",
+    "all_checks",
+    "dhis2_chap_modeling_app",
+    "dhis2_chap_ping",
+    "dhis2_chap_route",
+    "dhis2_chap_system_info",
+    "dhis2_ping",
+    "dhis2_system_info",
+    "register_check",
+    "resolve_checks",
+]