django-health-check 3.23.3__tar.gz → 4.0rc1__tar.gz

{django_health_check-3.23.3 → django_health_check-4.0rc1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: django-health-check
-Version: 3.23.3
+Version: 4.0rc1
 Summary: Monitor the health of your Django app and its connected services.
 Keywords: django,postgresql
 Author-email: Kristian Ollegaard <kristian@oellegaard.com>, Johannes Maron <johannes@maron.family>
@@ -8,7 +8,6 @@ Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 Classifier: Development Status :: 5 - Production/Stable
 Classifier: Framework :: Django
-Classifier: Framework :: Django :: 4.2
 Classifier: Framework :: Django :: 5.2
 Classifier: Framework :: Django :: 6.0
 Classifier: Intended Audience :: Developers
@@ -27,11 +26,14 @@ Classifier: Topic :: System :: Logging
 Classifier: Topic :: System :: Monitoring
 Classifier: Topic :: Utilities
 License-File: LICENSE
-Requires-Dist: Django>=4.2
+Requires-Dist: Django>=5.2
+Requires-Dist: dnspython>=2.0.0
 Requires-Dist: psutil
 Requires-Dist: celery>=5.0.0 ; extra == "celery"
-Requires-Dist: kombu>=5.0.0 ; extra == "rabbitmq"
-Requires-Dist: redis>=3.0.0 ; extra == "redis"
+Requires-Dist: confluent-kafka>=2.0.0 ; extra == "kafka"
+Requires-Dist: aio-pika>=9.0.0 ; extra == "rabbitmq"
+Requires-Dist: redis>=4.2.0 ; extra == "redis"
+Requires-Dist: httpx>=0.27.0 ; extra == "rss"
 Project-URL: Changelog, https://github.com/codingjoe/django-health-check/releases
 Project-URL: Documentation, https://codingjoe.dev/django-health-check/
 Project-URL: Homepage, https://codingjoe.dev/django-health-check/
@@ -39,8 +41,10 @@ Project-URL: Issues, https://github.com/codingjoe/django-health-check/issues
 Project-URL: Releasenotes, https://github.com/codingjoe/django-health-check/releases/latest
 Project-URL: Source, https://github.com/codingjoe/django-health-check
 Provides-Extra: celery
+Provides-Extra: kafka
 Provides-Extra: rabbitmq
 Provides-Extra: redis
+Provides-Extra: rss
 
 <p align="center">
   <picture>

django_health_check-4.0rc1/health_check/__init__.py

@@ -0,0 +1,21 @@
+"""Monitor the health of your Django app and its connected services."""
+
+from . import _version  # noqa
+from .base import HealthCheck
+from .checks import Cache, DNS, Database, Disk, Mail, Memory, Storage
+
+__version__ = _version.__version__
+VERSION = _version.__version_tuple__
+
+__all__ = [
+    "__version__",
+    "VERSION",
+    "HealthCheck",
+    "Cache",
+    "DNS",
+    "Database",
+    "Disk",
+    "Mail",
+    "Memory",
+    "Storage",
+]

{django_health_check-3.23.3 → django_health_check-4.0rc1}/health_check/_version.py

@@ -28,7 +28,7 @@ version_tuple: VERSION_TUPLE
 commit_id: COMMIT_ID
 __commit_id__: COMMIT_ID
 
-__version__ = version = '3.23.3'
-__version_tuple__ = version_tuple = (3, 23, 3)
+__version__ = version = '4.0rc1'
+__version_tuple__ = version_tuple = (4, 0, 'rc1')
 
-__commit_id__ = commit_id = 'gea6fbff62'
+__commit_id__ = commit_id = 'g9814c8393'

django_health_check-4.0rc1/health_check/base.py

@@ -0,0 +1,93 @@
+from __future__ import annotations
+
+import abc
+import asyncio
+import dataclasses
+import inspect
+import logging
+import timeit
+
+from health_check.exceptions import HealthCheckException
+
+logger = logging.getLogger(__name__)
+
+
+@dataclasses.dataclass
+class HealthCheckResult:
+    """Result of a health check execution."""
+
+    check: HealthCheck
+    error: HealthCheckException | None
+    time_taken: float
+
+
+@dataclasses.dataclass
+class HealthCheck(abc.ABC):
+    """
+    Base class for defining health checks.
+
+    Subclasses should implement the `run` method to perform the actual health check logic.
+    The `run` method can be either synchronous or asynchronous.
+
+    Examples:
+        >>> import dataclasses
+        >>> from health_check.base import HealthCheck
+        >>>
+        >>> @dataclasses.dataclass
+        >>> class MyHealthCheck(HealthCheck):
+        ...
+        ...    async def run(self):
+        ...        # Implement health check logic here
+
+    Subclasses should be [dataclasses][dataclasses.dataclass] or implement their own `__repr__` method
+    to provide meaningful representations in health check reports.
+
+    Warning:
+        The `__repr__` method is used in health check reports.
+        Consider setting `repr=False` for sensitive dataclass fields
+        to avoid leaking sensitive information or credentials.
+
+    """
+
+    @abc.abstractmethod
+    async def run(self) -> None:
+        """
+        Run the health check logic and raise human-readable exceptions as needed.
+
+        Exception must be reraised to indicate the health status and provide context.
+        Any unexpected exceptions will be caught and logged for security purposes
+        while returning a generic error message.
+
+        Warning:
+            Exception messages must not contain sensitive information.
+
+        Raises:
+            ServiceWarning: If the service is at a critical state but still operational.
+            ServiceUnavailable: If the service is not operational.
+            ServiceReturnedUnexpectedResult: If the check performs a computation that returns an unexpected result.
+
+        """
+        ...
+
+    def pretty_status(self) -> str:
+        """Return human-readable status string, always 'OK' for the check itself."""
+        return "OK"
+
+    async def get_result(self: HealthCheck) -> HealthCheckResult:
+        start = timeit.default_timer()
+        try:
+            await self.run() if inspect.iscoroutinefunction(
+                self.run
+            ) else await asyncio.to_thread(self.run)
+        except HealthCheckException as e:
+            error = e
+        except BaseException:
+            logger.exception("Unexpected exception during health check")
+            error = HealthCheckException("unknown error")
+        else:
+            error = None
+        return HealthCheckResult(
+            check=self,
+            error=error,
+            time_taken=timeit.default_timer() - start,
+        )

django_health_check-4.0rc1/health_check/checks.py

@@ -0,0 +1,329 @@
+"""Health check implementations for Django built-in services."""
+
+import dataclasses
+import datetime
+import logging
+import os
+import pathlib
+import smtplib
+import socket
+import uuid
+
+import dns.asyncresolver
+import psutil
+from django import db
+from django.conf import settings
+from django.core.cache import CacheKeyWarning, caches
+from django.core.files.base import ContentFile
+from django.core.files.storage import Storage as DjangoStorage
+from django.core.files.storage import storages
+from django.core.mail import get_connection
+from django.core.mail.backends.base import BaseEmailBackend
+from django.db import connections
+from django.db.models import Expression
+
+from health_check.base import HealthCheck
+from health_check.exceptions import (
+    ServiceReturnedUnexpectedResult,
+    ServiceUnavailable,
+    ServiceWarning,
+)
+
+try:
+    # Exceptions thrown by Redis do not subclass builtin exceptions like ConnectionError.
+    # Additionally, not only connection errors (ConnectionError -> RedisError) can be raised,
+    # but also errors for time-outs (TimeoutError -> RedisError)
+    # and if the backend is read-only (ReadOnlyError -> ResponseError -> RedisError).
+    # Since we know what we are trying to do here, we are not picky and catch the global exception RedisError.
+    from redis.exceptions import RedisError
+except ModuleNotFoundError:
+    # In case Redis is not installed and another cache backend is used.
+    class RedisError(Exception):
+        pass
+
+
+logger = logging.getLogger(__name__)
+
+
+@dataclasses.dataclass
+class Cache(HealthCheck):
+    """
+    Check that the cache backend is able to set and get a value.
+
+    It can be setup multiple times for different cache aliases if needed.
+
+    Args:
+        alias: The cache alias to test against.
+        cache_key: The cache key to use for the test.
+
+    """
+
+    alias: str = "default"
+    cache_key: str = dataclasses.field(default="djangohealthcheck_test", repr=False)
+
+    async def run(self):
+        cache = caches[self.alias]
+        ts = datetime.datetime.now().timestamp()
+        try:
+            await cache.aset(self.cache_key, f"itworks-{ts}")
+            if not await cache.aget(self.cache_key) == f"itworks-{ts}":
+                raise ServiceUnavailable(f"Cache key {self.cache_key} does not match")
+        except CacheKeyWarning as e:
+            raise ServiceReturnedUnexpectedResult("Cache key warning") from e
+        except ValueError as e:
+            raise ServiceReturnedUnexpectedResult("ValueError") from e
+        except (ConnectionError, RedisError) as e:
+            raise ServiceReturnedUnexpectedResult("Connection Error") from e
+
+
+class _SelectOne(Expression):
+    """An expression that represents a simple SELECT 1; query."""
+
+    def as_sql(self, compiler, connection):
+        return "SELECT 1", []
+
+    def as_oracle(self, compiler, connection):
+        return "SELECT 1 FROM DUAL", []
+
+
+@dataclasses.dataclass
+class Database(HealthCheck):
+    """
+    Check database operation by executing a simple SELECT 1 query.
+
+    It can be setup multiple times for different database connections if needed.
+    No actual data is read from or written to the database to minimize the performance impact
+    and work with conservative database user permissions.
+
+    Args:
+        alias: The alias of the database connection to check.
+
+    """
+
+    alias: str = "default"
+
+    def run(self):
+        connection = connections[self.alias]
+        result = None
+        try:
+            compiler = connection.ops.compiler("SQLCompiler")(
+                _SelectOne(), connection, None
+            )
+            with connection.cursor() as cursor:
+                cursor.execute(*compiler.compile(_SelectOne()))
+                result = cursor.fetchone()
+        except db.Error as e:
+            raise ServiceUnavailable(str(e).rsplit(":")[0]) from e
+        else:
+            if result != (1,):
+                raise ServiceUnavailable(
+                    "Health Check query did not return the expected result."
+                )
+        finally:
+            connection.close_if_unusable_or_obsolete()
+
+
+@dataclasses.dataclass
+class DNS(HealthCheck):
+    """
+    Check DNS resolution by resolving the server's hostname.
+
+    Verifies that DNS resolution is working using the system's configured
+    DNS servers, as well as nameserver resolution for the provided hostname.
+
+    Args:
+        hostname: The hostname to resolve.
+        timeout: DNS query timeout.
+
+    """
+
+    hostname: str = dataclasses.field(default_factory=socket.gethostname)
+    timeout: datetime.timedelta = dataclasses.field(
+        default=datetime.timedelta(seconds=5), repr=False
+    )
+    nameservers: list[str] | None = dataclasses.field(default=None, repr=False)
+
+    async def run(self):
+        logger.debug("Attempting to resolve hostname: %s", self.hostname)
+
+        resolver = dns.asyncresolver.Resolver()
+        resolver.lifetime = self.timeout.total_seconds()
+        if self.nameservers is not None:
+            resolver.nameservers = self.nameservers
+
+        try:
+            # Perform DNS resolution (A record by default)
+            answers = await resolver.resolve(self.hostname, "A")
+        except dns.resolver.NXDOMAIN as e:
+            raise ServiceUnavailable(
+                f"DNS resolution failed: hostname {self.hostname} does not exist"
+            ) from e
+        except dns.resolver.NoAnswer as e:
+            raise ServiceUnavailable(
+                f"DNS resolution failed: no answer for {self.hostname}"
+            ) from e
+        except dns.resolver.Timeout as e:
+            raise ServiceUnavailable(
+                f"DNS resolution failed: timeout resolving {self.hostname}"
+            ) from e
+        except dns.resolver.NoNameservers as e:
+            raise ServiceUnavailable(
+                "DNS resolution failed: no nameservers available"
+            ) from e
+        except dns.exception.DNSException as e:
+            raise ServiceUnavailable(f"DNS resolution failed: {e}") from e
+        else:
+            logger.debug(
+                "Successfully resolved %s to %s",
+                self.hostname,
+                [str(rdata) for rdata in answers],
+            )
+
+
+@dataclasses.dataclass()
+class Disk(HealthCheck):
+    """
+    Warn about disk usage for a given system path.
+
+    It can be setup multiple times at different system paths,
+    e.g. one at your application root and one at your media storage root.
+
+    Args:
+        path: Path to check disk usage for.
+        max_disk_usage_percent: Maximum disk usage in percent or None to disable the check.
+
+    """
+
+    path: pathlib.Path | str = dataclasses.field(default_factory=os.getcwd)
+    max_disk_usage_percent: float | None = dataclasses.field(default=90.0, repr=False)
+    hostname: str = dataclasses.field(default_factory=socket.gethostname, init=False)
+
+    def run(self):
+        try:
+            du = psutil.disk_usage(str(self.path))
+            if (
+                self.max_disk_usage_percent
+                and du.percent >= self.max_disk_usage_percent
+            ):
+                raise ServiceWarning(f"{du.percent}\u202f% disk usage")
+        except ValueError as e:
+            raise ServiceReturnedUnexpectedResult("ValueError") from e
+
+
+@dataclasses.dataclass
+class Mail(HealthCheck):
+    """
+    Check that mail backend is able to open and close connection.
+
+    Args:
+        backend: The email backend to test against.
+        timeout: Timeout for connection to mail server in seconds.
+
+    """
+
+    backend: str = settings.EMAIL_BACKEND
+    timeout: datetime.timedelta = dataclasses.field(
+        default=datetime.timedelta(seconds=15), repr=False
+    )
+
+    def run(self) -> None:
+        connection: BaseEmailBackend = get_connection(self.backend, fail_silently=False)
+        connection.timeout = self.timeout.total_seconds()
+        logger.debug("Trying to open connection to mail backend.")
+        try:
+            connection.open()
+        except smtplib.SMTPException as e:
+            raise ServiceUnavailable(
+                "Failed to open connection with SMTP server"
+            ) from e
+        except ConnectionRefusedError as e:
+            raise ServiceUnavailable("Connection refused error") from e
+        finally:
+            connection.close()
+        logger.debug(
+            "Connection established. Mail backend %r is healthy.", self.backend
+        )
+
+
+@dataclasses.dataclass()
+class Memory(HealthCheck):
+    """
+    Warn about system memory utilization.
+
+    Args:
+        min_gibibytes_available: Minimum available memory in gibibytes or None to disable the check.
+        max_memory_usage_percent: Maximum memory usage in percent or None to disable the check.
+
+    """
+
+    min_gibibytes_available: float | None = dataclasses.field(default=None, repr=False)
+    max_memory_usage_percent: float | None = dataclasses.field(default=90.0, repr=False)
+    hostname: str = dataclasses.field(default_factory=socket.gethostname, init=False)
+
+    def run(self):
+        try:
+            memory = psutil.virtual_memory()
+            available_gibi = memory.available / (1024**3)
+            total_gibi = memory.total / (1024**3)
+            msg = f"RAM {available_gibi:.1f}/{total_gibi:.1f}GiB ({memory.percent}\u202f%)"
+            if (
+                self.min_gibibytes_available
+                and available_gibi < self.min_gibibytes_available
+            ):
+                raise ServiceWarning(msg)
+            if (
+                self.max_memory_usage_percent
+                and memory.percent >= self.max_memory_usage_percent
+            ):
+                raise ServiceWarning(msg)
+        except ValueError as e:
+            raise ServiceReturnedUnexpectedResult("ValueError") from e
+
+
+@dataclasses.dataclass
+class Storage(HealthCheck):
+    """
+    Check file storage backends by saving, reading, and deleting a test file.
+
+    It can be setup multiple times for different storage backends if needed.
+
+    Args:
+        alias: The alias of the storage backend to check.
+
+    """
+
+    alias: str = "default"
+
+    @property
+    def storage(self) -> DjangoStorage:
+        return storages[self.alias]
+
+    def get_file_name(self):
+        return f"health_check_storage_test/test-{uuid.uuid4()}.txt"
+
+    def get_file_content(self):
+        return f"# generated by health_check.Storage at {datetime.datetime.now().timestamp()}".encode()
+
+    def check_save(self, file_name, file_content):
+        # save the file
+        file_name = self.storage.save(file_name, ContentFile(content=file_content))
+        # read the file and compare
+        if not self.storage.exists(file_name):
+            raise ServiceUnavailable("File does not exist")
+        with self.storage.open(file_name) as f:
+            if not f.read() == file_content:
+                raise ServiceUnavailable("File content does not match")
+        return file_name
+
+    def check_delete(self, file_name):
+        # delete the file and make sure it is gone
+        self.storage.delete(file_name)
+        if self.storage.exists(file_name):
+            raise ServiceUnavailable("File was not deleted")
+
+    def run(self):
+        # write the file to the storage backend
+        file_name = self.get_file_name()
+        file_content = self.get_file_content()
+        file_name = self.check_save(file_name, file_content)
+        self.check_delete(file_name)

django_health_check-4.0rc1/health_check/contrib/celery.py

@@ -0,0 +1,70 @@
+"""Celery health check."""
+
+import dataclasses
+import datetime
+import typing
+
+import celery
+from celery.app import app_or_default
+
+from health_check.base import HealthCheck
+from health_check.exceptions import ServiceUnavailable
+
+
+@dataclasses.dataclass
+class Ping(HealthCheck):
+    """
+    Check Celery worker availability using the ping control command.
+
+    Args:
+        app: Celery application instance to use for the health check, defaults to the [default Celery app][celery.app.default_app].
+        timeout: Timeout duration for the ping command.
+
+    """
+
+    CORRECT_PING_RESPONSE: typing.ClassVar[dict[str, str]] = {"ok": "pong"}
+    app: celery.Celery = dataclasses.field(default_factory=app_or_default)
+    timeout: datetime.timedelta = dataclasses.field(
+        default=datetime.timedelta(seconds=1), repr=False
+    )
+
+    def run(self):
+        try:
+            ping_result = self.app.control.ping(timeout=self.timeout.total_seconds())
+        except OSError as e:
+            raise ServiceUnavailable("IOError") from e
+        except NotImplementedError as e:
+            raise ServiceUnavailable(
+                "NotImplementedError: Make sure CELERY_RESULT_BACKEND is set"
+            ) from e
+        else:
+            if not ping_result:
+                raise ServiceUnavailable("Celery workers unavailable")
+            else:
+                self.check_active_queues(*self.active_workers(ping_result))
+
+    def active_workers(self, ping_result):
+        for result in ping_result:
+            worker, response = list(result.items())[0]
+            if response != self.CORRECT_PING_RESPONSE:
+                raise ServiceUnavailable(
+                    f"Celery worker {worker} response was incorrect"
+                )
+            yield worker
+
+    def check_active_queues(self, *active_workers):
+        defined_queues = {
+            queue.name
+            for queue in getattr(self.app.conf, "task_queues", None)
+            or getattr(self.app.conf, "CELERY_QUEUES", None)
+        }
+        active_queues = {
+            queue.get("name")
+            for queues in self.app.control.inspect(active_workers)
+            .active_queues()
+            .values()
+            for queue in queues
+        }
+
+        for queue in defined_queues - active_queues:
+            raise ServiceUnavailable(f"No worker for Celery task queue {queue}")

django_health_check-4.0rc1/health_check/contrib/kafka.py

@@ -0,0 +1,69 @@
+"""Kafka health check."""
+
+import dataclasses
+import datetime
+import logging
+
+from confluent_kafka.aio import AIOConsumer
+from confluent_kafka.error import KafkaException
+
+from health_check.base import HealthCheck
+from health_check.exceptions import ServiceUnavailable
+
+logger = logging.getLogger(__name__)
+
+
+@dataclasses.dataclass
+class Kafka(HealthCheck):
+    """
+    Check Kafka service by connecting to a Kafka broker and listing topics.
+
+    Args:
+        bootstrap_servers: List of Kafka bootstrap servers, e.g., ['localhost:9092'].
+        timeout: Timeout duration for the connection check as a datetime.timedelta.
+
+    """
+
+    bootstrap_servers: list[str]
+    timeout: datetime.timedelta = dataclasses.field(
+        default=datetime.timedelta(seconds=10), repr=False
+    )
+
+    async def run(self):
+        logger.debug(
+            "Connecting to Kafka bootstrap servers %r ...",
+            self.bootstrap_servers,
+        )
+
+        # Create a consumer with minimal configuration for health check
+        timeout_ms = int(self.timeout.total_seconds() * 1000)
+        consumer = AIOConsumer(
+            {
+                "bootstrap.servers": ",".join(self.bootstrap_servers),
+                "client.id": "health-check",
+                "group.id": "health-check",
+                "session.timeout.ms": timeout_ms,
+                "socket.timeout.ms": timeout_ms,
+            }
+        )
+
+        try:
+            if not (
+                (
+                    cluster_metadata := await consumer.list_topics(
+                        timeout=self.timeout.total_seconds()
+                    )
+                )
+                and cluster_metadata.topics
+            ):
+                raise ServiceUnavailable("Failed to retrieve Kafka topics.")
+
+        except KafkaException as e:
+            raise ServiceUnavailable("Unable to connect") from e
+        else:
+            logger.debug(
+                "Connection established. Kafka is healthy. Found %d topics.",
+                len(cluster_metadata.topics),
+            )
+        finally:
+            await consumer.close()

django_health_check-4.0rc1/health_check/contrib/rabbitmq.py

@@ -0,0 +1,43 @@
+"""RabbitMQ health check."""
+
+import dataclasses
+import logging
+
+import aio_pika
+
+from health_check.base import HealthCheck
+from health_check.exceptions import ServiceUnavailable
+
+logger = logging.getLogger(__name__)
+
+
+@dataclasses.dataclass
+class RabbitMQ(HealthCheck):
+    """
+    Check RabbitMQ service by opening and closing a broker channel.
+
+    Args:
+        amqp_url (str): The URL of the RabbitMQ broker to connect to, e.g., 'amqp://guest:guest@localhost:5672//'.
+
+    """
+
+    amqp_url: str
+
+    async def run(self):
+        logger.debug("Attempting to connect to %r...", self.amqp_url)
+        try:
+            # conn is used as a context to release opened resources later
+            connection = await aio_pika.connect_robust(self.amqp_url)
+            await connection.close()
+        except ConnectionRefusedError as e:
+            raise ServiceUnavailable(
+                "Unable to connect to RabbitMQ: Connection was refused."
+            ) from e
+        except aio_pika.exceptions.ProbableAuthenticationError as e:
+            raise ServiceUnavailable(
+                "Unable to connect to RabbitMQ: Authentication error."
+            ) from e
+        except OSError as e:
+            raise ServiceUnavailable("IOError") from e
+        else:
+            logger.debug("Connection established. RabbitMQ is healthy.")