microbootstrap 0__py3-none-any.whl

microbootstrap/config/faststream.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+import dataclasses
+import typing
+
+
+if typing.TYPE_CHECKING:
+    import faststream.asyncapi.schema as asyncapi
+    from faststream.asgi.types import ASGIApp
+    from faststream.broker.core.usecase import BrokerUsecase
+    from faststream.types import AnyDict, AnyHttpUrl, Lifespan
+
+
+@dataclasses.dataclass
+class FastStreamConfig:
+    broker: BrokerUsecase[typing.Any, typing.Any] | None = None
+    asgi_routes: typing.Sequence[tuple[str, ASGIApp]] = ()
+    lifespan: Lifespan | None = None
+    terms_of_service: AnyHttpUrl | None = None
+    license: asyncapi.License | asyncapi.LicenseDict | AnyDict | None = None
+    contact: asyncapi.Contact | asyncapi.ContactDict | AnyDict | None = None
+    tags: typing.Sequence[asyncapi.Tag | asyncapi.TagDict | AnyDict] | None = None
+    external_docs: asyncapi.ExternalDocs | asyncapi.ExternalDocsDict | AnyDict | None = None
+    identifier: str | None = None
+    on_startup: typing.Sequence[typing.Callable[..., typing.Any]] = ()
+    after_startup: typing.Sequence[typing.Callable[..., typing.Any]] = ()
+    on_shutdown: typing.Sequence[typing.Callable[..., typing.Any]] = ()
+    after_shutdown: typing.Sequence[typing.Callable[..., typing.Any]] = ()

microbootstrap/config/litestar.py

@@ -0,0 +1,21 @@
+from __future__ import annotations
+import dataclasses
+import typing
+
+from litestar.config.app import AppConfig
+from litestar.logging import LoggingConfig
+
+
+if typing.TYPE_CHECKING:
+    from litestar.types import OnAppInitHandler
+
+
+@dataclasses.dataclass
+class LitestarConfig(AppConfig):
+    on_app_init: typing.Sequence[OnAppInitHandler] | None = None
+    logging_config: LoggingConfig = dataclasses.field(
+        default_factory=lambda: LoggingConfig(
+            # required for foreign logs json formatting
+            configure_root_logger=False,
+        )
+    )

microbootstrap/console_writer.py

@@ -0,0 +1,34 @@
+from __future__ import annotations
+import dataclasses
+import typing
+
+from rich.console import Console
+from rich.rule import Rule
+from rich.table import Table
+
+
+@dataclasses.dataclass
+class ConsoleWriter:
+    writer_enabled: bool = True
+    rich_console: Console = dataclasses.field(init=False, default_factory=Console)
+    rich_table: Table = dataclasses.field(init=False)
+
+    def __post_init__(self) -> None:
+        self.rich_table = Table(show_header=False, header_style="cyan")
+        self.rich_table.add_column("Item", style="cyan")
+        self.rich_table.add_column("Status")
+        self.rich_table.add_column("Reason", style="yellow")
+
+    def write_instrument_status(
+        self,
+        instrument_name: str,
+        is_enabled: bool,
+        disable_reason: str | None = None,
+    ) -> None:
+        is_enabled_value: typing.Final = "[green]Enabled[/green]" if is_enabled else "[red]Disabled[/red]"
+        self.rich_table.add_row(rf"{instrument_name}", is_enabled_value, disable_reason or "")
+
+    def print_bootstrap_table(self) -> None:
+        if self.writer_enabled:
+            self.rich_console.print(Rule("[yellow]Bootstrapping application[/yellow]", align="left"))
+            self.rich_console.print(self.rich_table)

microbootstrap/exceptions.py

@@ -0,0 +1,10 @@
+class MicroBootstrapBaseError(Exception):
+    """Base for all exceptions."""
+
+
+class ConfigMergeError(MicroBootstrapBaseError):
+    """Raises when it's impossible to merge configs due to type mismatch."""
+
+
+class MissingInstrumentError(MicroBootstrapBaseError):
+    """Raises when attempting to configure instrument, that is not supported yet."""

microbootstrap/granian_server.py

@@ -0,0 +1,41 @@
+from __future__ import annotations
+import logging
+import typing
+
+import granian
+from granian.constants import Interfaces
+from granian.log import LogLevels
+
+
+if typing.TYPE_CHECKING:
+    from granian.server.common import AbstractServer as GranianServer
+
+    from microbootstrap.settings import ServerConfig
+
+
+GRANIAN_LOG_LEVELS_MAP = {
+    logging.CRITICAL: LogLevels.critical,
+    logging.ERROR: LogLevels.error,
+    logging.WARNING: LogLevels.warning,
+    logging.WARNING: LogLevels.warn,
+    logging.INFO: LogLevels.info,
+    logging.DEBUG: LogLevels.debug,
+}
+
+
+# TODO: create bootstrappers for application servers. granian/uvicorn  # noqa: TD002
+def create_granian_server(
+    target: str,
+    settings: ServerConfig,
+    **granian_options: typing.Any,  # noqa: ANN401
+) -> GranianServer[typing.Any]:
+    return granian.Granian(
+        target=target,
+        address=settings.server_host,
+        port=settings.server_port,
+        interface=Interfaces.ASGI,
+        workers=settings.server_workers_count,
+        log_level=GRANIAN_LOG_LEVELS_MAP[getattr(settings, "logging_log_level", logging.INFO)],
+        reload=settings.server_reload,
+        **granian_options,
+    )

microbootstrap/helpers.py

@@ -0,0 +1,111 @@
+import dataclasses
+import re
+import typing
+from dataclasses import _MISSING_TYPE
+
+from microbootstrap import exceptions
+
+
+if typing.TYPE_CHECKING:
+    from dataclasses import _DataclassT
+
+    from pydantic import BaseModel
+
+
+PydanticConfigT = typing.TypeVar("PydanticConfigT", bound="BaseModel")
+VALID_PATH_PATTERN: typing.Final = r"^(/[a-zA-Z0-9_-]+)+/?$"
+
+
+def dataclass_to_dict_no_defaults(dataclass_to_convert: "_DataclassT") -> dict[str, typing.Any]:
+    conversion_result: typing.Final = {}
+    for dataclass_field in dataclasses.fields(dataclass_to_convert):
+        value = getattr(dataclass_to_convert, dataclass_field.name)
+        if isinstance(dataclass_field.default, _MISSING_TYPE):
+            conversion_result[dataclass_field.name] = value
+            continue
+        if dataclass_field.default != value and isinstance(dataclass_field.default_factory, _MISSING_TYPE):
+            conversion_result[dataclass_field.name] = value
+            continue
+        if value != dataclass_field.default and value != dataclass_field.default_factory():  # type: ignore[misc]
+            conversion_result[dataclass_field.name] = value
+
+    return conversion_result
+
+
+def merge_pydantic_configs(
+    config_to_merge: PydanticConfigT,
+    config_with_changes: PydanticConfigT,
+) -> PydanticConfigT:
+    initial_fields: typing.Final = dict(config_to_merge)
+    changed_fields: typing.Final = {
+        one_field_name: getattr(config_with_changes, one_field_name)
+        for one_field_name in config_with_changes.model_fields_set
+    }
+    merged_fields: typing.Final = merge_dict_configs(initial_fields, changed_fields)
+    return config_to_merge.model_copy(update=merged_fields)
+
+
+def merge_dataclasses_configs(
+    config_to_merge: "_DataclassT",
+    config_with_changes: "_DataclassT",
+) -> "_DataclassT":
+    config_class: typing.Final = config_to_merge.__class__
+    resulting_dict_config: typing.Final = merge_dict_configs(
+        dataclass_to_dict_no_defaults(config_to_merge),
+        dataclass_to_dict_no_defaults(config_with_changes),
+    )
+    return config_class(**resulting_dict_config)
+
+
+def merge_dict_configs(
+    config_dict: dict[str, typing.Any],
+    changes_dict: dict[str, typing.Any],
+) -> dict[str, typing.Any]:
+    for change_key, change_value in changes_dict.items():
+        config_value = config_dict.get(change_key)
+
+        if isinstance(config_value, set):
+            if not isinstance(change_value, set):
+                raise exceptions.ConfigMergeError(f"Can't merge {config_value} and {change_value}")
+            config_dict[change_key] = {*config_value, *change_value}
+            continue
+
+        if isinstance(config_value, tuple):
+            if not isinstance(change_value, tuple):
+                raise exceptions.ConfigMergeError(f"Can't merge {config_value} and {change_value}")
+            config_dict[change_key] = (*config_value, *change_value)
+            continue
+
+        if isinstance(config_value, list):
+            if not isinstance(change_value, list):
+                raise exceptions.ConfigMergeError(f"Can't merge {config_value} and {change_value}")
+            config_dict[change_key] = [*config_value, *change_value]
+            continue
+
+        if isinstance(config_value, dict):
+            if not isinstance(change_value, dict):
+                raise exceptions.ConfigMergeError(f"Can't merge {config_value} and {change_value}")
+            config_dict[change_key] = {**config_value, **change_value}
+            continue
+
+        config_dict[change_key] = change_value
+
+    return config_dict
+
+
+def is_valid_path(maybe_path: str) -> bool:
+    return bool(re.fullmatch(VALID_PATH_PATTERN, maybe_path))
+
+
+def optimize_exclude_paths(
+    exclude_endpoints: typing.Iterable[str],
+) -> typing.Collection[str]:
+    # `in` operator is faster for tuples than for lists
+    endpoints_to_ignore: typing.Collection[str] = tuple(exclude_endpoints)
+
+    # 10 is just an empirical value, based of measuring the performance
+    # iterating over a tuple of <10 elements is faster than hashing
+    if len(endpoints_to_ignore) >= 10:  # noqa: PLR2004
+        endpoints_to_ignore = set(endpoints_to_ignore)
+
+    return endpoints_to_ignore

microbootstrap/instruments/base.py

@@ -0,0 +1,62 @@
+from __future__ import annotations
+import abc
+import dataclasses
+import typing
+
+import pydantic
+
+from microbootstrap.helpers import merge_pydantic_configs
+
+
+if typing.TYPE_CHECKING:
+    from microbootstrap.console_writer import ConsoleWriter
+
+
+InstrumentConfigT = typing.TypeVar("InstrumentConfigT", bound="BaseInstrumentConfig")
+ApplicationT = typing.TypeVar("ApplicationT", bound=typing.Any)
+
+
+class BaseInstrumentConfig(pydantic.BaseModel):
+    model_config = pydantic.ConfigDict(arbitrary_types_allowed=True)
+
+
+@dataclasses.dataclass
+class Instrument(abc.ABC, typing.Generic[InstrumentConfigT]):
+    instrument_config: InstrumentConfigT
+    instrument_name: typing.ClassVar[str]
+    ready_condition: typing.ClassVar[str]
+
+    def configure_instrument(
+        self,
+        incoming_config: InstrumentConfigT,
+    ) -> None:
+        self.instrument_config = merge_pydantic_configs(self.instrument_config, incoming_config)
+
+    def write_status(self, console_writer: ConsoleWriter) -> None:
+        console_writer.write_instrument_status(
+            self.instrument_name,
+            is_enabled=self.is_ready(),
+            disable_reason=None if self.is_ready() else self.ready_condition,
+        )
+
+    @abc.abstractmethod
+    def is_ready(self) -> bool: ...
+
+    @classmethod
+    @abc.abstractmethod
+    def get_config_type(cls) -> type[InstrumentConfigT]:
+        raise NotImplementedError
+
+    def bootstrap(self) -> None:
+        return None
+
+    def teardown(self) -> None:
+        return None
+
+    def bootstrap_before(self) -> dict[str, typing.Any]:
+        """Add some framework-related parameters to final bootstrap result before application creation."""
+        return {}
+
+    def bootstrap_after(self, application: ApplicationT) -> ApplicationT:
+        """Add some framework-related parameters to final bootstrap result after application creation."""
+        return application

microbootstrap/instruments/cors_instrument.py

@@ -0,0 +1,29 @@
+from __future__ import annotations
+
+import pydantic
+
+from microbootstrap.instruments.base import BaseInstrumentConfig, Instrument
+
+
+class CorsConfig(BaseInstrumentConfig):
+    cors_allowed_origins: list[str] = pydantic.Field(default_factory=list)
+    cors_allowed_methods: list[str] = pydantic.Field(default_factory=list)
+    cors_allowed_headers: list[str] = pydantic.Field(default_factory=list)
+    cors_exposed_headers: list[str] = pydantic.Field(default_factory=list)
+    cors_allowed_credentials: bool = False
+    cors_allowed_origin_regex: str | None = None
+    cors_max_age: int = 600
+
+
+class CorsInstrument(Instrument[CorsConfig]):
+    instrument_name = "Cors"
+    ready_condition = "Provide allowed origins or regex"
+
+    def is_ready(self) -> bool:
+        return bool(self.instrument_config.cors_allowed_origins) or bool(
+            self.instrument_config.cors_allowed_origin_regex,
+        )
+
+    @classmethod
+    def get_config_type(cls) -> type[CorsConfig]:
+        return CorsConfig

microbootstrap/instruments/health_checks_instrument.py

@@ -0,0 +1,39 @@
+from __future__ import annotations
+
+import typing_extensions
+
+from microbootstrap.instruments.base import BaseInstrumentConfig, Instrument
+
+
+class HealthCheckTypedDict(typing_extensions.TypedDict, total=False):
+    service_version: str | None
+    service_name: str | None
+    health_status: bool
+
+
+class HealthChecksConfig(BaseInstrumentConfig):
+    service_name: str = "micro-service"
+    service_version: str = "1.0.0"
+
+    health_checks_enabled: bool = True
+    health_checks_path: str = "/health/"
+    health_checks_include_in_schema: bool = False
+
+
+class HealthChecksInstrument(Instrument[HealthChecksConfig]):
+    instrument_name = "Health checks"
+    ready_condition = "Set health_checks_enabled to True"
+
+    def render_health_check_data(self) -> HealthCheckTypedDict:
+        return {
+            "service_version": self.instrument_config.service_version,
+            "service_name": self.instrument_config.service_name,
+            "health_status": True,
+        }
+
+    def is_ready(self) -> bool:
+        return self.instrument_config.health_checks_enabled
+
+    @classmethod
+    def get_config_type(cls) -> type[HealthChecksConfig]:
+        return HealthChecksConfig

microbootstrap/instruments/instrument_box.py

@@ -0,0 +1,50 @@
+import dataclasses
+import typing
+
+from microbootstrap import exceptions
+from microbootstrap.instruments.base import Instrument, InstrumentConfigT
+from microbootstrap.settings import SettingsT
+
+
+@dataclasses.dataclass
+class InstrumentBox:
+    __instruments__: list[type[Instrument[typing.Any]]] = dataclasses.field(default_factory=list)
+    __initialized_instruments__: list[Instrument[typing.Any]] = dataclasses.field(default_factory=list)
+
+    def initialize(self, settings: SettingsT) -> None:
+        settings_dump = settings.model_dump()
+        self.__initialized_instruments__ = [
+            instrument_type(instrument_type.get_config_type()(**settings_dump))
+            for instrument_type in self.__instruments__
+        ]
+
+    def configure_instrument(
+        self,
+        instrument_config: InstrumentConfigT,
+    ) -> None:
+        for instrument in self.__initialized_instruments__:
+            if isinstance(instrument_config, instrument.get_config_type()):
+                instrument.configure_instrument(instrument_config)
+                return
+
+        raise exceptions.MissingInstrumentError(
+            f"Instrument for config {instrument_config.__class__.__name__} is not supported yet.",
+        )
+
+    def extend_instruments(
+        self,
+        instrument_class: type[Instrument[InstrumentConfigT]],
+    ) -> type[Instrument[InstrumentConfigT]]:
+        """Extend list of instruments, excluding one whose config is already in use."""
+        self.__instruments__ = list(
+            filter(
+                lambda instrument: instrument.get_config_type() is not instrument_class.get_config_type(),
+                self.__instruments__,
+            ),
+        )
+        self.__instruments__.append(instrument_class)
+        return instrument_class
+
+    @property
+    def instruments(self) -> list[Instrument[typing.Any]]:
+        return self.__initialized_instruments__

microbootstrap/instruments/logging_instrument.py

@@ -0,0 +1,202 @@
+from __future__ import annotations
+import logging
+import logging.handlers
+import sys
+import time
+import typing
+import urllib.parse
+
+import orjson
+import pydantic
+import structlog
+import typing_extensions
+from opentelemetry import trace
+
+from microbootstrap.instruments.base import BaseInstrumentConfig, Instrument
+
+
+if typing.TYPE_CHECKING:
+    import fastapi
+    import litestar
+    from structlog.typing import EventDict, WrappedLogger
+
+
+ScopeType = typing.MutableMapping[str, typing.Any]
+
+access_logger: typing.Final = structlog.get_logger("api.access")
+
+
+def make_path_with_query_string(scope: ScopeType) -> str:
+    path_with_query_string: typing.Final = urllib.parse.quote(scope["path"])
+    if scope["query_string"]:
+        return f"{path_with_query_string}?{scope['query_string'].decode('ascii')}"
+    return path_with_query_string
+
+
+def fill_log_message(
+    log_level: str,
+    request: litestar.Request[typing.Any, typing.Any, typing.Any] | fastapi.Request,
+    status_code: int,
+    start_time: int,
+) -> None:
+    process_time: typing.Final = time.perf_counter_ns() - start_time
+    url_with_query: typing.Final = make_path_with_query_string(typing.cast("ScopeType", request.scope))
+    client_host: typing.Final = request.client.host if request.client is not None else None
+    client_port: typing.Final = request.client.port if request.client is not None else None
+    http_method: typing.Final = request.method
+    http_version: typing.Final = request.scope["http_version"]
+    log_on_correct_level: typing.Final = getattr(access_logger, log_level)
+    log_on_correct_level(
+        http={
+            "url": url_with_query,
+            "status_code": status_code,
+            "method": http_method,
+            "version": http_version,
+        },
+        network={"client": {"ip": client_host, "port": client_port}},
+        duration=process_time,
+    )
+
+
+def tracer_injection(_: WrappedLogger, __: str, event_dict: EventDict) -> EventDict:
+    current_span = trace.get_current_span()
+    if not current_span.is_recording():
+        event_dict["tracing"] = {}
+        return event_dict
+
+    current_span_context = current_span.get_span_context()
+    event_dict["tracing"] = {
+        "span_id": trace.format_span_id(current_span_context.span_id),
+        "trace_id": trace.format_trace_id(current_span_context.trace_id),
+    }
+    return event_dict
+
+
+STRUCTLOG_PRE_CHAIN_PROCESSORS: typing.Final[list[typing.Any]] = [
+    structlog.stdlib.add_log_level,
+    structlog.stdlib.add_logger_name,
+    tracer_injection,
+    structlog.stdlib.PositionalArgumentsFormatter(),
+    structlog.processors.TimeStamper(fmt="%Y-%m-%d %H:%M:%S"),
+    structlog.processors.StackInfoRenderer(),
+    structlog.processors.format_exc_info,
+    structlog.processors.UnicodeDecoder(),
+]
+
+
+def _serialize_log_with_orjson_to_string(value: typing.Any, **kwargs: typing.Any) -> str:  # noqa: ANN401
+    return orjson.dumps(value, **kwargs).decode()
+
+
+STRUCTLOG_FORMATTER_PROCESSOR: typing.Final = structlog.processors.JSONRenderer(
+    serializer=_serialize_log_with_orjson_to_string
+)
+
+
+class MemoryLoggerFactory(structlog.stdlib.LoggerFactory):
+    def __init__(
+        self,
+        *args: typing.Any,  # noqa: ANN401
+        logging_buffer_capacity: int,
+        logging_flush_level: int,
+        logging_log_level: int,
+        log_stream: typing.Any = sys.stdout,  # noqa: ANN401
+        **kwargs: typing.Any,  # noqa: ANN401
+    ) -> None:
+        super().__init__(*args, **kwargs)
+        self.logging_buffer_capacity = logging_buffer_capacity
+        self.logging_flush_level = logging_flush_level
+        self.logging_log_level = logging_log_level
+        self.log_stream = log_stream
+
+    def __call__(self, *args: typing.Any) -> logging.Logger:  # noqa: ANN401
+        logger: typing.Final = super().__call__(*args)
+        stream_handler: typing.Final = logging.StreamHandler(stream=self.log_stream)
+        handler: typing.Final = logging.handlers.MemoryHandler(
+            capacity=self.logging_buffer_capacity,
+            flushLevel=self.logging_flush_level,
+            target=stream_handler,
+        )
+        logger.addHandler(handler)
+        logger.setLevel(self.logging_log_level)
+        logger.propagate = False
+        return logger
+
+
+class LoggingConfig(BaseInstrumentConfig):
+    service_debug: bool = True
+
+    logging_log_level: int = logging.INFO
+    logging_flush_level: int = logging.ERROR
+    logging_buffer_capacity: int = 10
+    logging_extra_processors: list[typing.Any] = pydantic.Field(default_factory=list)
+    logging_unset_handlers: list[str] = pydantic.Field(
+        default_factory=lambda: ["uvicorn", "uvicorn.access"],
+    )
+    logging_exclude_endpoints: list[str] = pydantic.Field(default_factory=lambda: ["/health/", "/metrics"])
+    logging_turn_off_middleware: bool = False
+
+    @pydantic.model_validator(mode="after")
+    def remove_trailing_slashes_from_logging_exclude_endpoints(self) -> typing_extensions.Self:
+        self.logging_exclude_endpoints = [
+            one_endpoint.removesuffix("/") for one_endpoint in self.logging_exclude_endpoints
+        ]
+        return self
+
+
+class LoggingInstrument(Instrument[LoggingConfig]):
+    instrument_name = "Logging"
+    ready_condition = "Works only in non-debug mode"
+
+    def is_ready(self) -> bool:
+        return not self.instrument_config.service_debug
+
+    def teardown(self) -> None:
+        structlog.reset_defaults()
+
+    def _unset_handlers(self) -> None:
+        for unset_handlers_logger in self.instrument_config.logging_unset_handlers:
+            logging.getLogger(unset_handlers_logger).handlers = []
+
+    def _configure_structlog_loggers(self) -> None:
+        structlog.configure(
+            processors=[
+                structlog.stdlib.filter_by_level,
+                *STRUCTLOG_PRE_CHAIN_PROCESSORS,
+                *self.instrument_config.logging_extra_processors,
+                STRUCTLOG_FORMATTER_PROCESSOR,
+            ],
+            context_class=dict,
+            logger_factory=MemoryLoggerFactory(
+                logging_buffer_capacity=self.instrument_config.logging_buffer_capacity,
+                logging_flush_level=self.instrument_config.logging_flush_level,
+                logging_log_level=self.instrument_config.logging_log_level,
+            ),
+            wrapper_class=structlog.stdlib.BoundLogger,
+            cache_logger_on_first_use=True,
+        )
+
+    def _configure_foreign_loggers(self) -> None:
+        root_logger: typing.Final = logging.getLogger()
+        stream_handler: typing.Final = logging.StreamHandler(sys.stdout)
+        stream_handler.setFormatter(
+            structlog.stdlib.ProcessorFormatter(
+                foreign_pre_chain=STRUCTLOG_PRE_CHAIN_PROCESSORS,
+                processors=[
+                    structlog.stdlib.ProcessorFormatter.remove_processors_meta,
+                    STRUCTLOG_FORMATTER_PROCESSOR,
+                ],
+                logger=root_logger,
+            )
+        )
+        root_logger.addHandler(stream_handler)
+        root_logger.setLevel(self.instrument_config.logging_log_level)
+
+    def bootstrap(self) -> None:
+        self._unset_handlers()
+        self._configure_structlog_loggers()
+        self._configure_foreign_loggers()
+
+    @classmethod
+    def get_config_type(cls) -> type[LoggingConfig]:
+        return LoggingConfig