austial-terminus 0.1.5__tar.gz

austial_terminus-0.1.5/.gitignore

@@ -0,0 +1,11 @@
+__pycache__/
+*.py[cod]
+.venv/
+.env
+*.db
+.pytest_cache/
+.coverage
+htmlcov/
+dist/
+build/
+*.egg-info/

austial_terminus-0.1.5/PKG-INFO

@@ -0,0 +1,7 @@
+Metadata-Version: 2.4
+Name: austial-terminus
+Version: 0.1.5
+Summary: Health-check aggregator and indicators (memory, database) -- mirrors @nestjs/terminus (no main-monorepo equivalent).
+Requires-Python: >=3.11
+Requires-Dist: austial-common
+Requires-Dist: austial-orm

austial_terminus-0.1.5/pyproject.toml

@@ -0,0 +1,26 @@
+[project]
+name = "austial-terminus"
+dynamic = ["version"]
+description = "Health-check aggregator and indicators (memory, database) -- mirrors @nestjs/terminus (no main-monorepo equivalent)."
+requires-python = ">=3.11"
+dependencies = [
+    "austial-common",
+    "austial-orm",
+]
+
+[build-system]
+requires = ["hatchling", "hatch-vcs"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/austial"]
+
+[tool.uv.sources]
+austial-common = { workspace = true }
+austial-orm = { workspace = true }
+
+[tool.hatch.version]
+source = "vcs"
+
+[tool.hatch.version.raw-options]
+root = "../.."

austial_terminus-0.1.5/src/austial/terminus/__init__.py

@@ -0,0 +1,14 @@
+from austial.terminus.database_health_indicator import DatabaseHealthIndicator
+from austial.terminus.health_check_service import HealthCheckService, HealthIndicatorFunction
+from austial.terminus.health_indicator import HealthCheckError, HealthIndicator, HealthIndicatorResult
+from austial.terminus.memory_health_indicator import MemoryHealthIndicator
+
+__all__ = [
+    "DatabaseHealthIndicator",
+    "HealthCheckService",
+    "HealthIndicatorFunction",
+    "HealthCheckError",
+    "HealthIndicator",
+    "HealthIndicatorResult",
+    "MemoryHealthIndicator",
+]

austial_terminus-0.1.5/src/austial/terminus/database_health_indicator.py

@@ -0,0 +1,26 @@
+"""``DatabaseHealthIndicator`` -- mirrors ``@nestjs/terminus``'s ``TypeOrmHealthIndicator``."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from sqlalchemy import text
+
+from austial.common.decorators.injectable import Inject, Injectable
+from austial.orm.database_module import DATABASE_SESSION_FACTORY
+from austial.terminus.health_indicator import HealthCheckError, HealthIndicator, HealthIndicatorResult
+
+
+@Injectable()
+class DatabaseHealthIndicator(HealthIndicator):
+    def __init__(self, session_factory: Any = Inject(DATABASE_SESSION_FACTORY)):
+        self._session_factory = session_factory
+
+    async def ping_check(self, key: str) -> HealthIndicatorResult:
+        try:
+            async with self._session_factory() as session:
+                await session.execute(text("SELECT 1"))
+            return self.get_status(key, True)
+        except Exception as exc:  # noqa: BLE001
+            result = self.get_status(key, False, {"message": str(exc)})
+            raise HealthCheckError("Database health check failed", result) from exc

austial_terminus-0.1.5/src/austial/terminus/health_check_service.py

@@ -0,0 +1,42 @@
+"""``HealthCheckService`` -- mirrors ``@nestjs/terminus``'s ``HealthCheckService``.
+
+Usage, identical in shape to real Nest/Terminus code::
+
+    result = await self.health_check_service.check([
+        lambda: self.memory.check_heap("memory_heap", 300 * 1024 * 1024),
+        lambda: self.database.ping_check("database"),
+    ])
+"""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable
+
+from austial.common.decorators.injectable import Injectable
+from austial.terminus.health_indicator import HealthCheckError, HealthIndicatorResult
+
+HealthIndicatorFunction = Callable[[], Awaitable[HealthIndicatorResult]]
+
+
+@Injectable()
+class HealthCheckService:
+    async def check(self, indicators: list[HealthIndicatorFunction]) -> dict:
+        info: HealthIndicatorResult = {}
+        error: HealthIndicatorResult = {}
+        details: HealthIndicatorResult = {}
+
+        for indicator in indicators:
+            try:
+                result = await indicator()
+                info.update(result)
+                details.update(result)
+            except HealthCheckError as exc:
+                error.update(exc.causes)
+                details.update(exc.causes)
+            except Exception as exc:  # noqa: BLE001 - an indicator blew up unexpectedly
+                failure = {"unknown": {"status": "down", "message": str(exc)}}
+                error.update(failure)
+                details.update(failure)
+
+        status = "error" if error else "ok"
+        return {"status": status, "info": info, "error": error, "details": details}

austial_terminus-0.1.5/src/austial/terminus/health_indicator.py

@@ -0,0 +1,28 @@
+"""Base types for health indicators -- mirrors ``@nestjs/terminus``."""
+
+from __future__ import annotations
+
+from typing import Any
+
+HealthIndicatorResult = dict[str, dict[str, Any]]
+
+
+class HealthCheckError(Exception):
+    """Raised by an indicator to signal it's unhealthy; carries the same
+    ``HealthIndicatorResult`` shape that a healthy check would have returned."""
+
+    def __init__(self, message: str, causes: HealthIndicatorResult):
+        super().__init__(message)
+        self.causes = causes
+
+
+class HealthIndicator:
+    """Base class for health indicators. Subclasses expose one or more
+    ``async def xxx_check(self, key: str, ...) -> HealthIndicatorResult``
+    methods built on top of :meth:`get_status`."""
+
+    def get_status(self, key: str, is_healthy: bool, data: dict | None = None) -> HealthIndicatorResult:
+        payload: dict[str, Any] = {"status": "up" if is_healthy else "down"}
+        if data:
+            payload.update(data)
+        return {key: payload}

austial_terminus-0.1.5/src/austial/terminus/memory_health_indicator.py

@@ -0,0 +1,20 @@
+"""``MemoryHealthIndicator`` -- mirrors ``@nestjs/terminus``'s ``MemoryHealthIndicator``."""
+
+from __future__ import annotations
+
+import resource
+
+from austial.common.decorators.injectable import Injectable
+from austial.terminus.health_indicator import HealthCheckError, HealthIndicator, HealthIndicatorResult
+
+
+@Injectable()
+class MemoryHealthIndicator(HealthIndicator):
+    async def check_heap(self, key: str, threshold_bytes: int) -> HealthIndicatorResult:
+        # ru_maxrss is KB on Linux, bytes on macOS -- close enough for a demo indicator.
+        used_bytes = resource.getrusage(resource.RUSAGE_SELF).ru_maxrss * 1024
+        is_healthy = used_bytes < threshold_bytes
+        result = self.get_status(key, is_healthy, {"used_bytes": used_bytes, "threshold_bytes": threshold_bytes})
+        if not is_healthy:
+            raise HealthCheckError("Memory usage exceeded threshold", result)
+        return result

austial_terminus-0.1.5/test/health_check_service_spec.py

@@ -0,0 +1,48 @@
+"""Unit test for ``HealthCheckService`` -- the framework's own Terminus-style
+health-check aggregator, exercised directly (no consumer app required): this
+is a library test, so it builds indicators inline instead of importing a
+sample app's ``HealthService``.
+"""
+
+from __future__ import annotations
+
+import pytest
+
+from austial.terminus import (
+    HealthCheckError,
+    HealthCheckService,
+    HealthIndicator,
+    HealthIndicatorResult,
+    MemoryHealthIndicator,
+)
+
+
+@pytest.mark.asyncio
+async def test_reports_ok_status_when_all_indicators_pass():
+    service = HealthCheckService()
+    memory = MemoryHealthIndicator()
+
+    result = await service.check([lambda: memory.check_heap("memory_heap", 1024 * 1024 * 1024)])
+
+    assert result["status"] == "ok"
+    assert result["error"] == {}
+    assert result["info"]["memory_heap"]["status"] == "up"
+    assert result["details"] == result["info"]
+
+
+@pytest.mark.asyncio
+async def test_reports_error_status_when_an_indicator_fails():
+    service = HealthCheckService()
+
+    class _AlwaysDownIndicator(HealthIndicator):
+        async def ping(self, key: str) -> HealthIndicatorResult:
+            raise HealthCheckError("simulated failure", self.get_status(key, False, {"reason": "simulated"}))
+
+    indicator = _AlwaysDownIndicator()
+
+    result = await service.check([lambda: indicator.ping("dependency")])
+
+    assert result["status"] == "error"
+    assert result["info"] == {}
+    assert result["error"]["dependency"]["status"] == "down"
+    assert result["details"] == result["error"]