Merge pull request #31 from community-of-python/feature/health-checks-support

Add health checks support

Author: insani7y

README.md

@@ -41,6 +41,7 @@ With <b>microbootstrap</b>, you receive an application with lightweight built-in
 - `logging`
 - `cors`
 - `swagger` - with additional offline version support
+- `health checks` - with additional offline version support
 
 Those instruments can be bootstrapped for:
 
@@ -62,6 +63,7 @@ Interested? Let's dive right in ⚡
   - [Logging](#logging)
   - [CORS](#cors)
   - [Swagger](#swagger)
+  - [Health checks](#health-checks)
 - [Configuration](#configuration)
   - [Instruments configuration](#instruments-configuration)
   - [Application configuration](#application-configuration)
@@ -405,6 +407,27 @@ Parameter descriptions:
 - `swagger_offline_docs` - A boolean value that, when set to True, allows the Swagger JS bundles to be accessed offline. This is because the service starts to host via static.
 - `swagger_extra_params` - Additional parameters to pass into the OpenAPI configuration.
 
+### Health checks
+
+```python
+from microbootstrap.settings import BaseServiceSettings
+
+
+class YourSettings(BaseServiceSettings):
+    service_name: str = "micro-service"
+    service_version: str = "1.0.0"
+
+    health_checks_enabled: bool = True
+    health_checks_path: str = "/health/"
+```
+
+Parameter descriptions:
+
+- `service_name` - Will be displayed in health check response.
+- `service_version` - Will be displayed in health check response.
+- `health_checks_enabled` - Must be True to enable health checks.
+- `health_checks_path` - Path for health check handler.
+
 ## Configuration
 
 While settings provide a convenient mechanism, it's not always feasible to store everything within them.

microbootstrap/__init__.py

@@ -1,4 +1,5 @@
 from microbootstrap.instruments.cors_instrument import CorsConfig
+from microbootstrap.instruments.health_checks_instrument import HealthChecksConfig
 from microbootstrap.instruments.logging_instrument import LoggingConfig
 from microbootstrap.instruments.opentelemetry_instrument import OpentelemetryConfig
 from microbootstrap.instruments.prometheus_instrument import FastApiPrometheusConfig, LitestarPrometheusConfig
@@ -13,9 +14,9 @@
     "FastApiPrometheusConfig",
     "LitestarPrometheusConfig",
     "LoggingConfig",
-    "LitestarBootstrapper",
     "LitestarSettings",
     "FastApiSettings",
     "CorsConfig",
     "SwaggerConfig",
+    "HealthChecksConfig",
 )

microbootstrap/bootstrappers/fastapi.py

@@ -4,13 +4,15 @@
 import typing_extensions
 from fastapi.middleware.cors import CORSMiddleware
 from fastapi_offline_docs import enable_offline_docs
+from health_checks.fastapi_healthcheck import build_fastapi_health_check_router
 from opentelemetry.instrumentation.fastapi import FastAPIInstrumentor
 from prometheus_fastapi_instrumentator import Instrumentator
 from sentry_sdk.integrations.fastapi import FastApiIntegration
 
 from microbootstrap.bootstrappers.base import ApplicationBootstrapper
 from microbootstrap.config.fastapi import FastApiConfig
 from microbootstrap.instruments.cors_instrument import CorsInstrument
+from microbootstrap.instruments.health_checks_instrument import HealthChecksInstrument
 from microbootstrap.instruments.logging_instrument import LoggingInstrument
 from microbootstrap.instruments.opentelemetry_instrument import OpentelemetryInstrument
 from microbootstrap.instruments.prometheus_instrument import FastApiPrometheusConfig, PrometheusInstrument
@@ -114,3 +116,12 @@ def bootstrap_after(self, application: fastapi.FastAPI) -> fastapi.FastAPI:
     @classmethod
     def get_config_type(cls) -> type[FastApiPrometheusConfig]:
         return FastApiPrometheusConfig
+
+
+@FastApiBootstrapper.use_instrument()
+class FastApiHealthChecksInstrument(HealthChecksInstrument):
+    def bootstrap_after(self, application: fastapi.FastAPI) -> fastapi.FastAPI:
+        application.include_router(
+            build_fastapi_health_check_router(self.health_check, self.instrument_config.health_checks_path),
+        )
+        return application

microbootstrap/bootstrappers/litestar.py

@@ -4,6 +4,7 @@
 import litestar
 import litestar.types
 import typing_extensions
+from health_checks.litestar_healthcheck import build_litestar_health_check_router
 from litestar import openapi
 from litestar.config.cors import CORSConfig as LitestarCorsConfig
 from litestar.contrib.opentelemetry.config import OpenTelemetryConfig as LitestarOpentelemetryConfig
@@ -15,6 +16,7 @@
 from microbootstrap.bootstrappers.base import ApplicationBootstrapper
 from microbootstrap.config.litestar import LitestarConfig
 from microbootstrap.instruments.cors_instrument import CorsInstrument
+from microbootstrap.instruments.health_checks_instrument import HealthChecksInstrument
 from microbootstrap.instruments.logging_instrument import LoggingInstrument
 from microbootstrap.instruments.opentelemetry_instrument import OpentelemetryInstrument
 from microbootstrap.instruments.prometheus_instrument import LitestarPrometheusConfig, PrometheusInstrument
@@ -75,7 +77,7 @@ def bootstrap_before(self) -> dict[str, typing.Any]:
         } | self.instrument_config.swagger_extra_params
 
         bootstrap_result: typing.Final[dict[str, typing.Any]] = {
-            "openapi_config": openapi.OpenAPIConfig(**all_swagger_params)
+            "openapi_config": openapi.OpenAPIConfig(**all_swagger_params),
         }
         if self.instrument_config.swagger_offline_docs:
             bootstrap_result["static_files_config"] = [
@@ -137,3 +139,16 @@ class LitestarPrometheusController(PrometheusController):
     @classmethod
     def get_config_type(cls) -> type[LitestarPrometheusConfig]:
         return LitestarPrometheusConfig
+
+
+@LitestarBootstrapper.use_instrument()
+class LitestarHealthChecksInstrument(HealthChecksInstrument):
+    def bootstrap_before(self) -> dict[str, typing.Any]:
+        return {
+            "route_handlers": [
+                build_litestar_health_check_router(
+                    self.health_check,
+                    self.instrument_config.health_checks_path,
+                ),
+            ],
+        }

microbootstrap/instruments/health_checks_instrument.py

@@ -0,0 +1,31 @@
+from __future__ import annotations
+
+from health_checks.http_based import DefaultHTTPHealthCheck
+
+from microbootstrap.instruments.base import BaseInstrumentConfig, Instrument
+
+
+class HealthChecksConfig(BaseInstrumentConfig):
+    service_name: str = "micro-service"
+    service_version: str = "1.0.0"
+
+    health_checks_enabled: bool = True
+    health_checks_path: str = "/health/"
+
+
+class HealthChecksInstrument(Instrument[HealthChecksConfig]):
+    instrument_name = "Health checks"
+    ready_condition = "Set health_checks_enabled to True"
+
+    def bootstrap(self) -> None:
+        self.health_check = DefaultHTTPHealthCheck(
+            service_version=self.instrument_config.service_version,
+            service_name=self.instrument_config.service_name,
+        )
+
+    def is_ready(self) -> bool:
+        return self.instrument_config.health_checks_enabled
+
+    @classmethod
+    def get_config_type(cls) -> type[HealthChecksConfig]:
+        return HealthChecksConfig

microbootstrap/settings.py

@@ -28,11 +28,13 @@ class BaseServiceSettings(
     service_debug: bool = False
     service_environment: str | None = None
     service_name: str = pydantic.Field(
-        "micro-service", validation_alias=pydantic.AliasChoices("SERVICE_NAME", f"{ENV_PREFIX}SERVICE_NAME")
+        "micro-service",
+        validation_alias=pydantic.AliasChoices("SERVICE_NAME", f"{ENV_PREFIX}SERVICE_NAME"),
     )
     service_description: str = "Micro service description"
     service_version: str = pydantic.Field(
-        "1.0.0", validation_alias=pydantic.AliasChoices("CI_COMMIT_TAG", f"{ENV_PREFIX}SERVICE_VERSION")
+        "1.0.0",
+        validation_alias=pydantic.AliasChoices("CI_COMMIT_TAG", f"{ENV_PREFIX}SERVICE_VERSION"),
     )
     service_static_path: str = "/static"
 
@@ -50,24 +52,24 @@ class BaseServiceSettings(
 
 
 class LitestarSettings(
-    BaseServiceSettings,
     LoggingConfig,
     OpentelemetryConfig,
     SentryConfig,
     LitestarPrometheusConfig,
     SwaggerConfig,
     CorsConfig,
+    BaseServiceSettings,
 ):
     """Settings for a litestar botstrap."""
 
 
 class FastApiSettings(
-    BaseServiceSettings,
     LoggingConfig,
     OpentelemetryConfig,
     SentryConfig,
     FastApiPrometheusConfig,
     SwaggerConfig,
     CorsConfig,
+    BaseServiceSettings,
 ):
     """Settings for a fastapi botstrap."""

poetry.lock

@@ -66,6 +66,7 @@ fastapi = { version = "^0.111.0", optional = true }
 prometheus-fastapi-instrumentator = { version = "^6.1.0", optional = true }
 opentelemetry-instrumentation-fastapi = { version = "^0.46b0", optional = true }
 fastapi-offline-docs = { version = "^1.0.1", optional = true }
+health-checks = "^1.0.0"
 
 [tool.poetry.group.dev.dependencies]
 pytest = "^8.2.2"

pyproject.toml

@@ -16,6 +16,7 @@
 )
 from microbootstrap.console_writer import ConsoleWriter
 from microbootstrap.instruments.cors_instrument import CorsConfig
+from microbootstrap.instruments.health_checks_instrument import HealthChecksConfig
 from microbootstrap.instruments.prometheus_instrument import BasePrometheusConfig
 from microbootstrap.instruments.swagger_instrument import SwaggerConfig
 from microbootstrap.settings import BaseServiceSettings
@@ -69,6 +70,11 @@ def minimal_cors_config() -> CorsConfig:
     return CorsConfig(cors_allowed_origins=["*"])
 
 
+@pytest.fixture
+def minimal_health_checks_config() -> HealthChecksConfig:
+    return HealthChecksConfig()
+
+
 @pytest.fixture
 def minimal_opentelemetry_config() -> OpentelemetryConfig:
     return OpentelemetryConfig(

tests/conftest.py

@@ -0,0 +1,71 @@
+import typing
+
+import fastapi
+import litestar
+from httpx import AsyncClient
+from litestar import status_codes
+from litestar.testing import AsyncTestClient
+
+from microbootstrap.bootstrappers.fastapi import FastApiHealthChecksInstrument
+from microbootstrap.bootstrappers.litestar import LitestarHealthChecksInstrument
+from microbootstrap.instruments.health_checks_instrument import (
+    HealthChecksConfig,
+    HealthChecksInstrument,
+)
+
+
+def test_health_checks_is_ready(minimal_health_checks_config: HealthChecksConfig) -> None:
+    health_checks_instrument: typing.Final = HealthChecksInstrument(minimal_health_checks_config)
+    assert health_checks_instrument.is_ready()
+
+
+def test_health_checks_bootstrap_is_not_ready(minimal_health_checks_config: HealthChecksConfig) -> None:
+    minimal_health_checks_config.health_checks_enabled = False
+    health_checks_instrument: typing.Final = HealthChecksInstrument(minimal_health_checks_config)
+    assert not health_checks_instrument.is_ready()
+
+
+def test_health_checks_bootstrap_after(
+    default_litestar_app: litestar.Litestar,
+    minimal_health_checks_config: HealthChecksConfig,
+) -> None:
+    health_checks_instrument: typing.Final = HealthChecksInstrument(minimal_health_checks_config)
+    assert health_checks_instrument.bootstrap_after(default_litestar_app) == default_litestar_app
+
+
+def test_health_checks_teardown(
+    minimal_health_checks_config: HealthChecksConfig,
+) -> None:
+    health_checks_instrument: typing.Final = HealthChecksInstrument(minimal_health_checks_config)
+    assert health_checks_instrument.teardown() is None  # type: ignore[func-returns-value]
+
+
+async def test_litestar_health_checks_bootstrap() -> None:
+    test_health_checks_path: typing.Final = "/test-path/"
+    heatlh_checks_config: typing.Final = HealthChecksConfig(health_checks_path=test_health_checks_path)
+    health_checks_instrument: typing.Final = LitestarHealthChecksInstrument(heatlh_checks_config)
+
+    health_checks_instrument.bootstrap()
+    litestar_application: typing.Final = litestar.Litestar(
+        **health_checks_instrument.bootstrap_before(),
+    )
+
+    async with AsyncTestClient(app=litestar_application) as async_client:
+        response = await async_client.get(heatlh_checks_config.health_checks_path)
+        assert response.status_code == status_codes.HTTP_200_OK
+
+
+async def test_fastapi_health_checks_bootstrap() -> None:
+    test_health_checks_path: typing.Final = "/test-path/"
+    heatlh_checks_config: typing.Final = HealthChecksConfig(health_checks_path=test_health_checks_path)
+    health_checks_instrument: typing.Final = FastApiHealthChecksInstrument(heatlh_checks_config)
+
+    health_checks_instrument.bootstrap()
+    fastapi_application = fastapi.FastAPI(
+        **health_checks_instrument.bootstrap_before(),
+    )
+    fastapi_application = health_checks_instrument.bootstrap_after(fastapi_application)
+
+    async with AsyncClient(app=fastapi_application, base_url="http://testserver") as async_client:
+        response = await async_client.get(heatlh_checks_config.health_checks_path)
+        assert response.status_code == status_codes.HTTP_200_OK