microbootstrap 1.5.5__tar.gz → 1.6.1__tar.gz

{microbootstrap-1.5.5 → microbootstrap-1.6.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: microbootstrap
-Version: 1.5.5
+Version: 1.6.1
 Summary: Package for bootstrapping new micro-services
 Keywords: python,microservice,bootstrap,opentelemetry,logging,error-tracing,litestar,fastapi,fastmcp,mcp
 Author: community-of-python
@@ -43,16 +43,16 @@ Requires-Dist: opentelemetry-instrumentation-sqlalchemy>=0.54b1
 Requires-Dist: opentelemetry-instrumentation-asyncio>=0.54b1
 Requires-Dist: opentelemetry-instrumentation-asgi>=0.46b0
 Requires-Dist: orjson>=3.10.18
-Requires-Dist: fastapi>=0.100 ; extra == 'fastapi'
+Requires-Dist: fastapi>=0.110.1 ; extra == 'fastapi'
 Requires-Dist: fastapi-offline-docs>=1 ; extra == 'fastapi'
 Requires-Dist: opentelemetry-instrumentation-fastapi>=0.46b0 ; extra == 'fastapi'
-Requires-Dist: prometheus-fastapi-instrumentator>=6.1 ; extra == 'fastapi'
+Requires-Dist: prometheus-fastapi-instrumentator>=7.1 ; extra == 'fastapi'
 Requires-Dist: fastmcp>=2,<4 ; extra == 'fastmcp'
 Requires-Dist: prometheus-client>=0.20 ; extra == 'fastmcp'
-Requires-Dist: faststream~=0.6.2 ; extra == 'faststream'
+Requires-Dist: faststream>=0.6.7,<0.8 ; extra == 'faststream'
 Requires-Dist: prometheus-client>=0.20 ; extra == 'faststream'
 Requires-Dist: granian[reload]>=1 ; extra == 'granian'
-Requires-Dist: litestar>=2.9 ; extra == 'litestar'
+Requires-Dist: litestar>=2.21.1 ; extra == 'litestar'
 Requires-Dist: litestar-offline-docs>=1 ; extra == 'litestar'
 Requires-Dist: prometheus-client>=0.20 ; extra == 'litestar'
 Requires-Python: >=3.10, <4
@@ -105,7 +105,7 @@ With <b>microbootstrap</b>, you receive an application with lightweight built-in
 - `opentelemetry`
 - `logging`
 - `cors`
-- `swagger` - with additional offline version support
+- `swagger` - offline UI assets, OpenAPI security definitions, and optional Accept-version documentation
 - `health-checks`
 
 Those instruments can be bootstrapped for:
@@ -505,7 +505,7 @@ class YourSettings(BaseServiceSettings):
     opentelemetry_namespace: str | None = None
     opentelemetry_insecure: bool = True
     opentelemetry_instrumentors: list[OpenTelemetryInstrumentor] = []
-    opentelemetry_exclude_urls: list[str] = []
+    opentelemetry_exclude_urls: list[str] = ["/metrics"]
     opentelemetry_baggage_span_attributes: dict[str, str] = {}
 
     ... # Other settings here
@@ -521,9 +521,9 @@ Parameters description:
 - `opentelemetry_insecure` - is opentelemetry connection secure.
 - `opentelemetry_container_name` - will be passed to the `Resource`.
 - `opentelemetry_instrumentors` - a list of extra instrumentors.
-- `opentelemetry_exclude_urls` - list of ignored urls.
+- `opentelemetry_exclude_urls` - list of url regexes that produce no server spans (`["/metrics"]` by default). For Litestar they are combined with `OTEL_PYTHON_LITESTAR_EXCLUDED_URLS` (or `OTEL_PYTHON_EXCLUDED_URLS`).
 - `opentelemetry_log_traces` - traces will be logged to stdout.
-- `opentelemetry_generate_health_check_spans` - generate spans for health check handlers if `True`
+- `opentelemetry_generate_health_check_spans` - generate spans for health check handlers if `True`; if `False`, `health_checks_path` is added to the excluded urls.
 - `opentelemetry_baggage_span_attributes` - maps allowed baggage keys to attributes added to local server and consumer spans.
 
 These settings are subsequently passed to [opentelemetry](https://opentelemetry.io/), finalizing your Opentelemetry integration.
@@ -659,6 +659,64 @@ 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.
 
+#### OpenAPI security schemes
+
+Security schemes are disabled by default. They add reusable OpenAPI definitions under
+`components.securitySchemes`; they do not authenticate requests or add global or operation-level security requirements.
+Keep requirements and authentication in your application routes and dependencies.
+
+```python
+from microbootstrap import (
+    LitestarSettings,
+    OpenApiHttpSecurityScheme,
+)
+
+
+class Settings(LitestarSettings):
+    security_schemes: dict[str, OpenApiHttpSecurityScheme] = {
+        "serviceAuth": OpenApiHttpSecurityScheme(scheme="bearer", bearer_format="JWT"),
+    }
+```
+
+HTTP, API key, OAuth 2.0, and OpenID Connect definitions are supported by `SwaggerConfig`. Annotating a consumer
+setting with a concrete scheme class intentionally rejects other kinds for that consumer. Python field names and
+OpenAPI aliases are accepted; output uses canonical names such as `bearerFormat`, `in`, `tokenUrl`, and
+`openIdConnectUrl`. A same-named definition must be identical to the service-owned definition or schema generation
+raises `ValueError`.
+
+The definitions are added to the framework's normal schema. Repeated schema reads remain stable; after correcting
+a configuration conflict, rebuild the application.
+
+#### API-version documentation
+
+Version documentation is disabled by default. It describes supported versions in OpenAPI without implementing
+runtime version negotiation.
+
+```python
+from microbootstrap import LitestarSettings, OpenApiOperationVersionOverride, OpenApiVersionDocsConfig
+
+
+class Settings(LitestarSettings):
+    openapi_version_docs: OpenApiVersionDocsConfig | None = OpenApiVersionDocsConfig(
+        vendor_media_type="application/vnd.example+json",
+        supported_versions=("1.0",),
+        operation_versions=(
+            OpenApiOperationVersionOverride(path="/widgets", method="post", supported_versions=("2.0",)),
+            OpenApiOperationVersionOverride(path="/internal/widgets", method="get", supported_versions=()),
+        ),
+    )
+```
+
+Set `openapi_version_docs` to `None` to disable version documentation. A configured non-empty global
+`supported_versions` list adds an `x-accept-versioning` extension and matching description text to each operation.
+`operation_versions` replaces that list for one exact path and lower-case HTTP method; an explicit empty tuple skips
+microbootstrap's additions for that operation without asserting that no service-owned version metadata exists. This does
+not negotiate requests, add an `Accept` parameter, change response media types, or provide a Swagger UI version selector.
+
+Repeated schema reads remain stable. A conflicting service-owned `x-accept-versioning` extension raises `ValueError`;
+correct the configuration and rebuild the application. Litestar supports its standard `Operation` type for version
+documentation and rejects other custom operation subclasses.
+
 #### FastStream AsyncAPI documentation
 
 AsyncAPI documentation is available by default under `/asyncapi` route. You can change that by setting `asyncapi_path`:

{microbootstrap-1.5.5 → microbootstrap-1.6.1}/README.md

@@ -40,7 +40,7 @@ With <b>microbootstrap</b>, you receive an application with lightweight built-in
 - `opentelemetry`
 - `logging`
 - `cors`
-- `swagger` - with additional offline version support
+- `swagger` - offline UI assets, OpenAPI security definitions, and optional Accept-version documentation
 - `health-checks`
 
 Those instruments can be bootstrapped for:
@@ -440,7 +440,7 @@ class YourSettings(BaseServiceSettings):
     opentelemetry_namespace: str | None = None
     opentelemetry_insecure: bool = True
     opentelemetry_instrumentors: list[OpenTelemetryInstrumentor] = []
-    opentelemetry_exclude_urls: list[str] = []
+    opentelemetry_exclude_urls: list[str] = ["/metrics"]
     opentelemetry_baggage_span_attributes: dict[str, str] = {}
 
     ... # Other settings here
@@ -456,9 +456,9 @@ Parameters description:
 - `opentelemetry_insecure` - is opentelemetry connection secure.
 - `opentelemetry_container_name` - will be passed to the `Resource`.
 - `opentelemetry_instrumentors` - a list of extra instrumentors.
-- `opentelemetry_exclude_urls` - list of ignored urls.
+- `opentelemetry_exclude_urls` - list of url regexes that produce no server spans (`["/metrics"]` by default). For Litestar they are combined with `OTEL_PYTHON_LITESTAR_EXCLUDED_URLS` (or `OTEL_PYTHON_EXCLUDED_URLS`).
 - `opentelemetry_log_traces` - traces will be logged to stdout.
-- `opentelemetry_generate_health_check_spans` - generate spans for health check handlers if `True`
+- `opentelemetry_generate_health_check_spans` - generate spans for health check handlers if `True`; if `False`, `health_checks_path` is added to the excluded urls.
 - `opentelemetry_baggage_span_attributes` - maps allowed baggage keys to attributes added to local server and consumer spans.
 
 These settings are subsequently passed to [opentelemetry](https://opentelemetry.io/), finalizing your Opentelemetry integration.
@@ -594,6 +594,64 @@ 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.
 
+#### OpenAPI security schemes
+
+Security schemes are disabled by default. They add reusable OpenAPI definitions under
+`components.securitySchemes`; they do not authenticate requests or add global or operation-level security requirements.
+Keep requirements and authentication in your application routes and dependencies.
+
+```python
+from microbootstrap import (
+    LitestarSettings,
+    OpenApiHttpSecurityScheme,
+)
+
+
+class Settings(LitestarSettings):
+    security_schemes: dict[str, OpenApiHttpSecurityScheme] = {
+        "serviceAuth": OpenApiHttpSecurityScheme(scheme="bearer", bearer_format="JWT"),
+    }
+```
+
+HTTP, API key, OAuth 2.0, and OpenID Connect definitions are supported by `SwaggerConfig`. Annotating a consumer
+setting with a concrete scheme class intentionally rejects other kinds for that consumer. Python field names and
+OpenAPI aliases are accepted; output uses canonical names such as `bearerFormat`, `in`, `tokenUrl`, and
+`openIdConnectUrl`. A same-named definition must be identical to the service-owned definition or schema generation
+raises `ValueError`.
+
+The definitions are added to the framework's normal schema. Repeated schema reads remain stable; after correcting
+a configuration conflict, rebuild the application.
+
+#### API-version documentation
+
+Version documentation is disabled by default. It describes supported versions in OpenAPI without implementing
+runtime version negotiation.
+
+```python
+from microbootstrap import LitestarSettings, OpenApiOperationVersionOverride, OpenApiVersionDocsConfig
+
+
+class Settings(LitestarSettings):
+    openapi_version_docs: OpenApiVersionDocsConfig | None = OpenApiVersionDocsConfig(
+        vendor_media_type="application/vnd.example+json",
+        supported_versions=("1.0",),
+        operation_versions=(
+            OpenApiOperationVersionOverride(path="/widgets", method="post", supported_versions=("2.0",)),
+            OpenApiOperationVersionOverride(path="/internal/widgets", method="get", supported_versions=()),
+        ),
+    )
+```
+
+Set `openapi_version_docs` to `None` to disable version documentation. A configured non-empty global
+`supported_versions` list adds an `x-accept-versioning` extension and matching description text to each operation.
+`operation_versions` replaces that list for one exact path and lower-case HTTP method; an explicit empty tuple skips
+microbootstrap's additions for that operation without asserting that no service-owned version metadata exists. This does
+not negotiate requests, add an `Accept` parameter, change response media types, or provide a Swagger UI version selector.
+
+Repeated schema reads remain stable. A conflicting service-owned `x-accept-versioning` extension raises `ValueError`;
+correct the configuration and rebuild the application. Litestar supports its standard `Operation` type for version
+documentation and rejects other custom operation subclasses.
+
 #### FastStream AsyncAPI documentation
 
 AsyncAPI documentation is available by default under `/asyncapi` route. You can change that by setting `asyncapi_path`:

{microbootstrap-1.5.5 → microbootstrap-1.6.1}/microbootstrap/__init__.py

@@ -1,6 +1,18 @@
 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.openapi_security_schemes import (
+    OpenApiApiKeySecurityScheme,
+    OpenApiHttpSecurityScheme,
+    OpenApiOAuth2SecurityScheme,
+    OpenApiOAuthFlow,
+    OpenApiOAuthFlows,
+    OpenApiOpenIdConnectSecurityScheme,
+)
+from microbootstrap.instruments.openapi_version_docs import (
+    OpenApiOperationVersionOverride,
+    OpenApiVersionDocsConfig,
+)
 from microbootstrap.instruments.opentelemetry_instrument import (
     FastStreamOpentelemetryConfig,
     FastStreamTelemetryMiddlewareProtocol,
@@ -42,6 +54,14 @@ __all__ = (
     "LitestarPrometheusConfig",
     "LitestarSettings",
     "LoggingConfig",
+    "OpenApiApiKeySecurityScheme",
+    "OpenApiHttpSecurityScheme",
+    "OpenApiOAuth2SecurityScheme",
+    "OpenApiOAuthFlow",
+    "OpenApiOAuthFlows",
+    "OpenApiOpenIdConnectSecurityScheme",
+    "OpenApiOperationVersionOverride",
+    "OpenApiVersionDocsConfig",
     "OpentelemetryConfig",
     "PyroscopeConfig",
     "SentryConfig",

{microbootstrap-1.5.5 → microbootstrap-1.6.1}/microbootstrap/bootstrappers/fastapi.py

@@ -12,6 +12,8 @@ from microbootstrap.config.fastapi import FastApiConfig
 from microbootstrap.instruments.cors_instrument import CorsInstrument
 from microbootstrap.instruments.health_checks_instrument import HealthChecksInstrument, HealthCheckTypedDict
 from microbootstrap.instruments.logging_instrument import LoggingInstrument
+from microbootstrap.instruments.openapi_security_schemes import serialize_security_schemes
+from microbootstrap.instruments.openapi_version_docs import SUPPORTED_HTTP_METHODS
 from microbootstrap.instruments.opentelemetry_instrument import OpentelemetryInstrument
 from microbootstrap.instruments.prometheus_instrument import FastApiPrometheusConfig, PrometheusInstrument
 from microbootstrap.instruments.pyroscope_instrument import PyroscopeInstrument
@@ -67,8 +69,48 @@ class FastApiSwaggerInstrument(SwaggerInstrument):
     def bootstrap_after(self, application: ApplicationT) -> ApplicationT:
         if self.instrument_config.swagger_offline_docs:
             enable_offline_docs(application, static_files_handler=self.instrument_config.service_static_path)
+        if self.instrument_config.openapi_version_docs is None and not self.instrument_config.security_schemes:
+            return application
+
+        original_openapi: typing.Final = application.openapi
+
+        def documented_openapi() -> dict[str, typing.Any]:
+            openapi_schema: typing.Final = original_openapi()
+            if self.instrument_config.security_schemes:
+                self._merge_security_schemes(openapi_schema)
+            if self.instrument_config.openapi_version_docs is not None:
+                self._document_operations(openapi_schema)
+            return openapi_schema
+
+        application.openapi = documented_openapi  # type: ignore[method-assign]  # FastAPI's public custom OpenAPI hook.
         return application
 
+    def _merge_security_schemes(self, openapi_schema: dict[str, typing.Any]) -> None:
+        expected_schemes: typing.Final = serialize_security_schemes(self.instrument_config.security_schemes)
+        components = openapi_schema.setdefault("components", {})
+        security_schemes = components.setdefault("securitySchemes", {})
+        self._validate_security_scheme_conflicts(security_schemes, expected_schemes)
+        security_schemes.update(
+            {name: scheme for name, scheme in expected_schemes.items() if name not in security_schemes}
+        )
+
+    def _document_operations(self, openapi_schema: dict[str, typing.Any]) -> None:
+        for path, path_item in openapi_schema.get("paths", {}).items():
+            if path.startswith("x-"):
+                continue
+            for method, operation in path_item.items():
+                if method not in SUPPORTED_HTTP_METHODS:
+                    continue
+                documentation = self._build_version_documentation(
+                    path,
+                    method,
+                    operation.get("description"),
+                    operation.get("x-accept-versioning"),
+                    has_existing_extension="x-accept-versioning" in operation,
+                )
+                if documentation is not None:
+                    operation["x-accept-versioning"], operation["description"] = documentation
+
 
 @FastApiBootstrapper.use_instrument()
 class FastApiCorsInstrument(CorsInstrument):

{microbootstrap-1.5.5 → microbootstrap-1.6.1}/microbootstrap/bootstrappers/faststream.py

@@ -57,7 +57,11 @@ def _isolate_faststream_subscribers(application: AsgiFastStream) -> None:
 class KwargsAsgiFastStream(AsgiFastStream):
     def __init__(self, **kwargs: typing.Any) -> None:  # noqa: ANN401
         # `broker` argument is positional-only
-        super().__init__(kwargs.pop("broker", None), **kwargs)
+        broker = kwargs.pop("broker", None)
+        if broker is None:
+            super().__init__(**kwargs)
+        else:
+            super().__init__(broker, **kwargs)
 
 
 class FastStreamBootstrapper(ApplicationBootstrapper[FastStreamSettings, AsgiFastStream, FastStreamConfig]):

{microbootstrap-1.5.5 → microbootstrap-1.6.1}/microbootstrap/bootstrappers/litestar.py

@@ -1,4 +1,5 @@
 from __future__ import annotations
+import dataclasses
 import typing
 
 import litestar
@@ -14,18 +15,27 @@ from litestar.openapi.plugins import SwaggerRenderPlugin
 from litestar.types.asgi_types import ASGIApp, Scope
 from litestar_offline_docs import generate_static_files_config
 from opentelemetry.instrumentation.asgi import OpenTelemetryMiddleware
-from opentelemetry.util.http import get_excluded_urls
+from opentelemetry.util.http import ExcludeList, get_excluded_urls
 from sentry_sdk.integrations.litestar import LitestarIntegration
 
 from microbootstrap.bootstrappers.base import ApplicationBootstrapper
 from microbootstrap.config.litestar import LitestarConfig
+from microbootstrap.instruments import opentelemetry_instrument
 from microbootstrap.instruments.cors_instrument import CorsInstrument
 from microbootstrap.instruments.health_checks_instrument import (
     HealthChecksInstrument,
     HealthCheckTypedDict,
 )
 from microbootstrap.instruments.logging_instrument import LoggingInstrument
-from microbootstrap.instruments.opentelemetry_instrument import OpentelemetryInstrument
+from microbootstrap.instruments.openapi_security_schemes import (
+    OpenApiApiKeySecurityScheme,
+    OpenApiHttpSecurityScheme,
+    OpenApiOAuth2SecurityScheme,
+    OpenApiOpenIdConnectSecurityScheme,
+    _OpenApiSecurityScheme,
+    serialize_security_schemes,
+)
+from microbootstrap.instruments.openapi_version_docs import SUPPORTED_HTTP_METHODS
 from microbootstrap.instruments.prometheus_instrument import (
     LitestarPrometheusConfig,
     PrometheusInstrument,
@@ -37,6 +47,17 @@ from microbootstrap.middlewares.litestar import build_litestar_logging_middlewar
 from microbootstrap.settings import LitestarSettings
 
 
+ApplicationT = typing.TypeVar("ApplicationT", bound=litestar.Litestar)
+
+
+@dataclasses.dataclass
+class AcceptVersionedOperation(openapi.spec.Operation):
+    accept_versioning: dict[str, str | list[str]] | None = dataclasses.field(
+        default=None,
+        metadata={"alias": "x-accept-versioning"},
+    )
+
+
 if typing.TYPE_CHECKING:
     from litestar.contrib.opentelemetry import OpenTelemetryConfig
     from litestar.types import ASGIApp, Scope
@@ -102,6 +123,102 @@ class LitestarSwaggerInstrument(SwaggerInstrument):
             ]
         return bootstrap_result
 
+    def bootstrap_after(self, application: ApplicationT) -> ApplicationT:
+        if (self.instrument_config.openapi_version_docs is None and not self.instrument_config.security_schemes) or (
+            application.openapi_config is None
+        ):
+            return application
+        if self.instrument_config.security_schemes:
+            self._merge_security_schemes(application.openapi_schema)
+        if self.instrument_config.openapi_version_docs is not None:
+            self._document_operations(application.openapi_schema)
+        return application
+
+    def _merge_security_schemes(self, openapi_schema: openapi.spec.OpenAPI) -> None:
+        expected_schemes: typing.Final = serialize_security_schemes(self.instrument_config.security_schemes)
+        security_schemes = openapi_schema.components.security_schemes
+        if security_schemes is not None:
+            canonical_schemes: typing.Final = {
+                name: scheme.to_schema() if isinstance(scheme, openapi.spec.SecurityScheme) else scheme
+                for name, scheme in security_schemes.items()
+            }
+            self._validate_security_scheme_conflicts(canonical_schemes, expected_schemes)
+        configured_schemes = {
+            scheme_name: self._build_litestar_security_scheme(security_scheme)
+            for scheme_name, security_scheme in self.instrument_config.security_schemes.items()
+        }
+        if security_schemes is None:
+            openapi_schema.components.security_schemes = typing.cast(
+                "dict[str, openapi.spec.SecurityScheme | openapi.spec.Reference]",
+                configured_schemes,
+            )
+            return
+        security_schemes.update(
+            {name: scheme for name, scheme in configured_schemes.items() if name not in security_schemes}
+        )
+
+    def _document_operations(self, openapi_schema: openapi.spec.OpenAPI) -> None:
+        if openapi_schema.paths is None:
+            return
+        for path, path_item in openapi_schema.paths.items():
+            for method in SUPPORTED_HTTP_METHODS:
+                operation = getattr(path_item, method)
+                if operation is None:
+                    continue
+                existing_extension = (
+                    operation.accept_versioning if isinstance(operation, AcceptVersionedOperation) else None
+                )
+                documentation = self._build_version_documentation(
+                    path,
+                    method,
+                    operation.description,
+                    existing_extension,
+                    has_existing_extension=existing_extension is not None,
+                )
+                if documentation is None:
+                    continue
+                extension, description = documentation
+                if type(operation) is openapi.spec.Operation:
+                    init_fields = {
+                        field.name: getattr(operation, field.name)
+                        for field in dataclasses.fields(openapi.spec.Operation)
+                        if field.init
+                    }
+                    operation = AcceptVersionedOperation(**init_fields, accept_versioning=extension)
+                    setattr(path_item, method, operation)
+                elif type(operation) is not AcceptVersionedOperation:
+                    message = (
+                        f"OpenAPI operation {type(operation).__name__} is not supported "
+                        "for Accept version documentation."
+                    )
+                    raise TypeError(message)
+                operation.accept_versioning = extension
+                operation.description = description
+
+    @classmethod
+    def _build_litestar_security_scheme(cls, security_scheme: _OpenApiSecurityScheme) -> openapi.spec.SecurityScheme:
+        if not isinstance(
+            security_scheme,
+            (
+                OpenApiHttpSecurityScheme,
+                OpenApiApiKeySecurityScheme,
+                OpenApiOAuth2SecurityScheme,
+                OpenApiOpenIdConnectSecurityScheme,
+            ),
+        ):
+            raise AssertionError("Unsupported OpenAPI security scheme.")  # noqa: TRY004
+        scheme_data = security_scheme.model_dump(by_alias=False, exclude_none=True)
+        if "location" in scheme_data:
+            scheme_data["security_scheme_in"] = scheme_data.pop("location")
+        if "flows" in scheme_data:
+            flow_data = scheme_data["flows"]
+            if "resource_owner" in flow_data:
+                flow_data["password"] = flow_data.pop("resource_owner")
+            scheme_data["flows"] = openapi.spec.OAuthFlows(
+                **{flow_name: openapi.spec.OAuthFlow(**flow) for flow_name, flow in flow_data.items()}
+            )
+        return openapi.spec.SecurityScheme(**scheme_data)
+
 
 @LitestarBootstrapper.use_instrument()
 class LitestarCorsInstrument(CorsInstrument):
@@ -122,12 +239,6 @@ class LitestarCorsInstrument(CorsInstrument):
 LitestarBootstrapper.use_instrument()(PyroscopeInstrument)
 
 
-def build_span_name(method: str, route: str) -> str:
-    if not route:
-        return method
-    return f"{method} {route}"
-
-
 def build_litestar_route_details_from_scope(
     scope: Scope,
 ) -> tuple[str, dict[str, str]]:
@@ -144,18 +255,23 @@ def build_litestar_route_details_from_scope(
     method: typing.Final = str(scope.get("method", "HTTP")).strip()
     if path_template is not None:
         path_template_stripped: typing.Final = path_template.strip()
-        return build_span_name(method, path_template_stripped), {"http.route": path_template_stripped}
+        span_name: typing.Final = opentelemetry_instrument.build_span_name(method, path_template_stripped)
+        return span_name, {"http.route": path_template_stripped}
 
     path: typing.Final = scope.get("path")
     if path is not None:
         path_stripped: typing.Final = path.strip()
-        return build_span_name(method, path_stripped), {"http.route": path_stripped}
+        return opentelemetry_instrument.build_span_name(method, path_stripped), {"http.route": path_stripped}
     return method, {}
 
 
 class LitestarOpenTelemetryInstrumentationMiddleware(ASGIMiddleware):
-    def __init__(self, config: OpenTelemetryConfig) -> None:
+    def __init__(self, config: OpenTelemetryConfig, exclude_urls: typing.Sequence[str] = ()) -> None:
         self.config = config
+        self.excluded_urls = opentelemetry_instrument.CombinedExcludeList(
+            ExcludeList(exclude_urls),
+            get_excluded_urls(self.config.exclude_urls_env_key),
+        )
 
     def create_open_telemetry_middleware(self, app: ASGIApp) -> OpenTelemetryMiddleware:
         return OpenTelemetryMiddleware(
@@ -163,7 +279,7 @@ class LitestarOpenTelemetryInstrumentationMiddleware(ASGIMiddleware):
             client_request_hook=self.config.client_request_hook_handler,
             client_response_hook=self.config.client_response_hook_handler,
             default_span_details=build_litestar_route_details_from_scope,
-            excluded_urls=get_excluded_urls(self.config.exclude_urls_env_key),
+            excluded_urls=self.excluded_urls,
             meter=self.config.meter,
             meter_provider=self.config.meter_provider,
             server_request_hook=self.config.server_request_hook_handler,
@@ -175,7 +291,7 @@ class LitestarOpenTelemetryInstrumentationMiddleware(ASGIMiddleware):
 
 
 @LitestarBootstrapper.use_instrument()
-class LitestarOpentelemetryInstrument(OpentelemetryInstrument):
+class LitestarOpentelemetryInstrument(opentelemetry_instrument.OpentelemetryInstrument):
     def bootstrap_before(self) -> dict[str, typing.Any]:
         return {
             "middleware": [
@@ -183,7 +299,8 @@ class LitestarOpentelemetryInstrument(OpentelemetryInstrument):
                     LitestarOpentelemetryConfig(
                         tracer_provider=self.tracer_provider,
                         middleware_class=LitestarOpenTelemetryInstrumentationMiddleware,  # type: ignore[arg-type]
-                    )
+                    ),
+                    exclude_urls=self.define_exclude_urls(),
                 )
             ]
         }

{microbootstrap-1.5.5 → microbootstrap-1.6.1}/microbootstrap/helpers.py

@@ -26,7 +26,7 @@ def dataclass_to_dict_no_defaults(dataclass_to_convert: "_DataclassT") -> dict[s
         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]
+        if value != dataclass_field.default and value != dataclass_field.default_factory():  # type: ignore[operator]
             conversion_result[dataclass_field.name] = value
 
     return conversion_result

microbootstrap-1.6.1/microbootstrap/instruments/openapi_security_schemes.py

@@ -0,0 +1,127 @@
+from __future__ import annotations
+import typing
+import unicodedata
+
+import pydantic
+
+
+OpenApiApiKeyLocation: typing.TypeAlias = typing.Literal["header", "query", "cookie"]
+
+
+class OpenApiSecuritySchemeModel(pydantic.BaseModel):
+    model_config = pydantic.ConfigDict(extra="forbid", populate_by_name=True)
+
+
+class OpenApiHttpSecurityScheme(OpenApiSecuritySchemeModel):
+    type: typing.Literal["http"] = "http"
+    scheme: str
+    bearer_format: str | None = pydantic.Field(default=None, alias="bearerFormat")
+    description: str | None = None
+
+
+class OpenApiApiKeySecurityScheme(OpenApiSecuritySchemeModel):
+    type: typing.Literal["apiKey"] = "apiKey"
+    name: str
+    location: OpenApiApiKeyLocation = pydantic.Field(alias="in")
+    description: str | None = None
+
+
+class OpenApiOAuthFlow(OpenApiSecuritySchemeModel):
+    authorization_url: str | None = pydantic.Field(default=None, alias="authorizationUrl")
+    token_url: str | None = pydantic.Field(default=None, alias="tokenUrl")
+    refresh_url: str | None = pydantic.Field(default=None, alias="refreshUrl")
+    scopes: dict[str, str] = pydantic.Field(default_factory=dict)
+
+    @pydantic.field_validator("authorization_url", "token_url", "refresh_url")
+    @classmethod
+    def validate_url(cls, value: str | None) -> str | None:
+        return validate_openapi_url(value)
+
+
+class OpenApiOAuthFlows(OpenApiSecuritySchemeModel):
+    implicit: OpenApiOAuthFlow | None = None
+    resource_owner: OpenApiOAuthFlow | None = pydantic.Field(default=None, alias="password")
+    client_credentials: OpenApiOAuthFlow | None = pydantic.Field(default=None, alias="clientCredentials")
+    authorization_code: OpenApiOAuthFlow | None = pydantic.Field(default=None, alias="authorizationCode")
+
+    @pydantic.model_validator(mode="after")
+    def validate_required_urls(self) -> OpenApiOAuthFlows:
+        if all(
+            flow is None
+            for flow in (self.implicit, self.resource_owner, self.client_credentials, self.authorization_code)
+        ):
+            message = "OAuth2 flows must configure at least one grant type."
+            raise ValueError(message)
+        self._validate_flow_urls("implicit", self.implicit, requires_authorization_url=True)
+        self._validate_flow_urls("password", self.resource_owner, requires_token_url=True)
+        self._validate_flow_urls("client credentials", self.client_credentials, requires_token_url=True)
+        self._validate_flow_urls(
+            "authorization code",
+            self.authorization_code,
+            requires_authorization_url=True,
+            requires_token_url=True,
+        )
+        return self
+
+    @staticmethod
+    def _validate_flow_urls(
+        flow_name: str,
+        flow: OpenApiOAuthFlow | None,
+        *,
+        requires_authorization_url: bool = False,
+        requires_token_url: bool = False,
+    ) -> None:
+        if flow is None:
+            return
+        if requires_authorization_url and flow.authorization_url is None:
+            message = f"OAuth2 {flow_name} flow requires authorizationUrl."
+            raise ValueError(message)
+        if requires_token_url and flow.token_url is None:
+            message = f"OAuth2 {flow_name} flow requires tokenUrl."
+            raise ValueError(message)
+
+
+class OpenApiOAuth2SecurityScheme(OpenApiSecuritySchemeModel):
+    type: typing.Literal["oauth2"] = "oauth2"
+    flows: OpenApiOAuthFlows
+    description: str | None = None
+
+
+class OpenApiOpenIdConnectSecurityScheme(OpenApiSecuritySchemeModel):
+    type: typing.Literal["openIdConnect"] = "openIdConnect"
+    open_id_connect_url: str = pydantic.Field(alias="openIdConnectUrl")
+    description: str | None = None
+
+    @pydantic.field_validator("open_id_connect_url")
+    @classmethod
+    def validate_url(cls, value: str) -> str:
+        validated_value = validate_openapi_url(value)
+        assert validated_value is not None  # noqa: S101 - this field is required.
+        return validated_value
+
+
+_OpenApiSecurityScheme: typing.TypeAlias = typing.Annotated[
+    OpenApiHttpSecurityScheme
+    | OpenApiApiKeySecurityScheme
+    | OpenApiOAuth2SecurityScheme
+    | OpenApiOpenIdConnectSecurityScheme,
+    pydantic.Field(discriminator="type"),
+]
+
+
+def validate_openapi_url(value: str | None) -> str | None:
+    if value is None:
+        return value
+    if not value or any(character.isspace() or unicodedata.category(character) == "Cc" for character in value):
+        message = "OpenAPI URL values must be non-empty and contain no whitespace or control characters."
+        raise ValueError(message)
+    return value
+
+
+def serialize_security_schemes(
+    security_schemes: typing.Mapping[str, _OpenApiSecurityScheme],
+) -> dict[str, dict[str, typing.Any]]:
+    return {
+        scheme_name: security_scheme.model_dump(by_alias=True, exclude_none=True)
+        for scheme_name, security_scheme in security_schemes.items()
+    }

microbootstrap-1.6.1/microbootstrap/instruments/openapi_version_docs.py

@@ -0,0 +1,86 @@
+from __future__ import annotations
+import re
+import typing
+
+import pydantic
+
+
+SUPPORTED_HTTP_METHODS: typing.Final = frozenset({"delete", "get", "head", "options", "patch", "post", "put", "trace"})
+SAFE_MEDIA_TYPE_TOKEN: typing.Final[re.Pattern[str]] = re.compile(r"[!#$%&'*+\-.^_|~0-9A-Za-z]+\Z")
+VENDOR_MEDIA_TYPE: typing.Final = re.compile(r"application/vnd\.([!#$%&'*+\-.^_|~0-9A-Za-z]+)\+json\Z")
+
+
+class OpenApiOperationVersionOverride(pydantic.BaseModel):
+    model_config = pydantic.ConfigDict(extra="forbid")
+
+    path: str
+    method: str
+    supported_versions: tuple[str, ...]
+
+    @pydantic.field_validator("path")
+    @classmethod
+    def validate_path(cls, value: str) -> str:
+        if not value.startswith("/") or "?" in value or "#" in value:
+            message = "Operation path must be an absolute path without a query string or fragment."
+            raise ValueError(message)
+        return value
+
+    @pydantic.field_validator("method")
+    @classmethod
+    def validate_method(cls, value: str) -> str:
+        if value not in SUPPORTED_HTTP_METHODS:
+            message = f"Operation method must be one of: {', '.join(sorted(SUPPORTED_HTTP_METHODS))}."
+            raise ValueError(message)
+        return value
+
+    @pydantic.field_validator("supported_versions")
+    @classmethod
+    def validate_supported_versions(cls, value: tuple[str, ...]) -> tuple[str, ...]:
+        return validate_versions(value)
+
+
+class OpenApiVersionDocsConfig(pydantic.BaseModel):
+    model_config = pydantic.ConfigDict(extra="forbid")
+
+    vendor_media_type: str
+    supported_versions: tuple[str, ...]
+    operation_versions: tuple[OpenApiOperationVersionOverride, ...] = ()
+
+    @pydantic.field_validator("vendor_media_type")
+    @classmethod
+    def validate_vendor_media_type(cls, value: str) -> str:
+        if VENDOR_MEDIA_TYPE.fullmatch(value) is None:
+            message = "Vendor media type must use the application/vnd.<name>+json form."
+            raise ValueError(message)
+        return value
+
+    @pydantic.field_validator("supported_versions")
+    @classmethod
+    def validate_supported_versions(cls, value: tuple[str, ...]) -> tuple[str, ...]:
+        validated_versions = validate_versions(value)
+        if not validated_versions:
+            message = "OpenAPI version documentation requires at least one supported API version."
+            raise ValueError(message)
+        return validated_versions
+
+    @pydantic.field_validator("operation_versions")
+    @classmethod
+    def validate_operation_versions(
+        cls,
+        value: tuple[OpenApiOperationVersionOverride, ...],
+    ) -> tuple[OpenApiOperationVersionOverride, ...]:
+        selectors = {(override.path, override.method) for override in value}
+        if len(value) != len(selectors):
+            message = "Operation version overrides must not contain duplicate path and method pairs."
+            raise ValueError(message)
+        return value
+
+
+def validate_versions(value: tuple[str, ...]) -> tuple[str, ...]:
+    if len(value) != len(set(value)):
+        message = "Supported API versions must not contain duplicates."
+        raise ValueError(message)
+    if any(SAFE_MEDIA_TYPE_TOKEN.fullmatch(version) is None for version in value):
+        message = "Each supported API version must be a non-empty safe media-type token."
+        raise ValueError(message)
+    return value

{microbootstrap-1.5.5 → microbootstrap-1.6.1}/microbootstrap/instruments/opentelemetry_instrument.py

@@ -19,6 +19,7 @@ from opentelemetry.sdk.trace.export import BatchSpanProcessor, ConsoleSpanExport
 from opentelemetry.semconv.resource import ResourceAttributes
 from opentelemetry.trace import SpanKind, format_span_id, get_current_span, set_tracer_provider
 from opentelemetry.util._importlib_metadata import entry_points
+from opentelemetry.util.http import ExcludeList
 
 from microbootstrap.instruments.base import BaseInstrumentConfig, Instrument
 from microbootstrap.instruments.sentry_instrument import snapshot_sentry_opentelemetry_baggage
@@ -70,6 +71,21 @@ def opentelemetry_baggage_scope(
         context.detach(token)
 
 
+def build_span_name(method: str, route: str) -> str:
+    if not route:
+        return method
+    return f"{method} {route}"
+
+
+class CombinedExcludeList(ExcludeList):
+    def __init__(self, *exclude_lists: ExcludeList) -> None:
+        super().__init__([])
+        self.exclude_lists = exclude_lists
+
+    def url_disabled(self, url: str) -> bool:
+        return any(one_exclude_list.url_disabled(url) for one_exclude_list in self.exclude_lists)
+
+
 @dataclasses.dataclass()
 class OpenTelemetryInstrumentor:
     instrumentor: BaseInstrumentor
@@ -167,6 +183,16 @@ class BaseOpentelemetryInstrument(Instrument[OpentelemetryConfigT]):
                 LOGGER_OBJ.debug("Instrumenting failed", entry_point_name=entry_point.name)
                 raise
 
+    def define_exclude_urls(self) -> list[str]:
+        exclude_urls: typing.Final = [*self.instrument_config.opentelemetry_exclude_urls]
+        if (
+            not self.instrument_config.opentelemetry_generate_health_check_spans
+            and self.instrument_config.health_checks_path
+            and self.instrument_config.health_checks_path not in exclude_urls
+        ):
+            exclude_urls.append(self.instrument_config.health_checks_path)
+        return exclude_urls
+
     def is_ready(self) -> bool:
         return (
             bool(self.instrument_config.opentelemetry_endpoint)
@@ -222,16 +248,6 @@ class BaseOpentelemetryInstrument(Instrument[OpentelemetryConfigT]):
 
 
 class OpentelemetryInstrument(BaseOpentelemetryInstrument[OpentelemetryConfig]):
-    def define_exclude_urls(self) -> list[str]:
-        exclude_urls: typing.Final = [*self.instrument_config.opentelemetry_exclude_urls]
-        if (
-            not self.instrument_config.opentelemetry_generate_health_check_spans
-            and self.instrument_config.health_checks_path
-            and self.instrument_config.health_checks_path not in exclude_urls
-        ):
-            exclude_urls.append(self.instrument_config.health_checks_path)
-        return exclude_urls
-
     @classmethod
     def get_config_type(cls) -> type[OpentelemetryConfig]:
         return OpentelemetryConfig

microbootstrap-1.6.1/microbootstrap/instruments/swagger_instrument.py

@@ -0,0 +1,121 @@
+from __future__ import annotations
+import re
+import typing
+
+import pydantic
+
+from microbootstrap.helpers import is_valid_path
+from microbootstrap.instruments.base import BaseInstrumentConfig, Instrument
+from microbootstrap.instruments.openapi_security_schemes import _OpenApiSecurityScheme  # noqa: TC001
+from microbootstrap.instruments.openapi_version_docs import (
+    SUPPORTED_HTTP_METHODS,
+    OpenApiVersionDocsConfig,
+)
+
+
+SECURITY_SCHEME_NAME_PATTERN: typing.Final = re.compile(r"^[a-zA-Z0-9._-]+$")
+
+
+class SwaggerConfig(BaseInstrumentConfig):
+    service_name: str = "micro-service"
+    service_description: str = "Micro service description"
+    service_version: str = "1.0.0"
+
+    service_static_path: str = "/static"
+    swagger_path: str = "/docs"
+    swagger_offline_docs: bool = False
+    swagger_extra_params: dict[str, typing.Any] = pydantic.Field(default_factory=dict)
+    security_schemes: typing.Mapping[str, _OpenApiSecurityScheme] = pydantic.Field(default_factory=dict)
+    openapi_version_docs: OpenApiVersionDocsConfig | None = None
+
+    @pydantic.field_validator("security_schemes")
+    @classmethod
+    def validate_security_scheme_names(
+        cls,
+        security_schemes: typing.Mapping[str, _OpenApiSecurityScheme],
+    ) -> typing.Mapping[str, _OpenApiSecurityScheme]:
+        for scheme_name in security_schemes:
+            if SECURITY_SCHEME_NAME_PATTERN.fullmatch(scheme_name) is None:
+                message = "OpenAPI security scheme names must match ^[a-zA-Z0-9._-]+$."
+                raise ValueError(message)
+        return security_schemes
+
+
+class SwaggerInstrument(Instrument[SwaggerConfig]):
+    instrument_name = "Swagger"
+    ready_condition = "Provide valid swagger_path"
+
+    def is_ready(self) -> bool:
+        return bool(self.instrument_config.swagger_path) and is_valid_path(self.instrument_config.swagger_path)
+
+    def _build_version_documentation(
+        self,
+        path: str,
+        method: str,
+        description: object,
+        existing_extension: object,
+        *,
+        has_existing_extension: bool,
+    ) -> tuple[dict[str, str | list[str]], str] | None:
+        configuration = self.instrument_config.openapi_version_docs
+        if configuration is None or method not in SUPPORTED_HTTP_METHODS:
+            return None
+
+        supported_versions = next(
+            (
+                override.supported_versions
+                for override in configuration.operation_versions
+                if override.path == path and override.method == method
+            ),
+            configuration.supported_versions,
+        )
+        if not supported_versions:
+            return None
+        if description is not None and not isinstance(description, str):
+            message = f"OpenAPI operation {method.upper()} {path} has a non-string description."
+            raise ValueError(message)
+
+        expected_extension: typing.Final[dict[str, str | list[str]]] = {
+            "header": "Accept",
+            "mediaType": configuration.vendor_media_type,
+            "parameter": "version",
+            "supportedVersions": list(supported_versions),
+        }
+        if has_existing_extension and existing_extension != expected_extension:
+            message = "OpenAPI operation x-accept-versioning conflicts with configured Accept version documentation."
+            raise ValueError(message)
+        return expected_extension, self._format_version_documentation(description, configuration, supported_versions)
+
+    @staticmethod
+    def _format_version_documentation(
+        description: str | None,
+        configuration: OpenApiVersionDocsConfig,
+        supported_versions: tuple[str, ...],
+    ) -> str:
+        media_types: typing.Final = tuple(
+            f"{configuration.vendor_media_type}; version={version}" for version in supported_versions
+        )
+        version_documentation: typing.Final = (
+            f"Supported API version: `{media_types[0]}`."
+            if len(media_types) == 1
+            else "Supported API versions:\n" + "\n".join(f"- `{media_type}`." for media_type in media_types)
+        )
+        if not description:
+            return version_documentation
+        if version_documentation in description:
+            return description
+        return f"{description}\n\n{version_documentation}"
+
+    @staticmethod
+    def _validate_security_scheme_conflicts(
+        existing_schemes: typing.Mapping[str, object],
+        expected_schemes: typing.Mapping[str, object],
+    ) -> None:
+        for scheme_name, expected_scheme in expected_schemes.items():
+            if scheme_name in existing_schemes and existing_schemes[scheme_name] != expected_scheme:
+                message = f"OpenAPI security scheme '{scheme_name}' conflicts with the configured security scheme."
+                raise ValueError(message)
+
+    @classmethod
+    def get_config_type(cls) -> type[SwaggerConfig]:
+        return SwaggerConfig

{microbootstrap-1.5.5 → microbootstrap-1.6.1}/pyproject.toml

@@ -58,26 +58,26 @@ dependencies = [
     "opentelemetry-instrumentation-asgi>=0.46b0",
     "orjson>=3.10.18",
 ]
-version = "1.5.5"
+version = "1.6.1"
 
 [[project.authors]]
 name = "community-of-python"
 
 [project.optional-dependencies]
 fastapi = [
-    "fastapi>=0.100",
+    "fastapi>=0.110.1",
     "fastapi-offline-docs>=1",
     "opentelemetry-instrumentation-fastapi>=0.46b0",
-    "prometheus-fastapi-instrumentator>=6.1",
+    "prometheus-fastapi-instrumentator>=7.1",
 ]
 litestar = [
-    "litestar>=2.9",
+    "litestar>=2.21.1",
     "litestar-offline-docs>=1",
     "prometheus-client>=0.20",
 ]
 granian = ["granian[reload]>=1"]
 faststream = [
-    "faststream~=0.6.2",
+    "faststream>=0.6.7,<0.8",
     "prometheus-client>=0.20",
 ]
 fastmcp = [

{microbootstrap-1.5.5 → microbootstrap-1.6.1}/pyproject.toml.orig

@@ -58,23 +58,23 @@ dependencies = [
     "opentelemetry-instrumentation-asgi>=0.46b0",
     "orjson>=3.10.18",
 ]
-version = "1.5.5"
+version = "1.6.1"
 authors = [{ name = "community-of-python" }]
 
 [project.optional-dependencies]
 fastapi = [
-    "fastapi>=0.100",
+    "fastapi>=0.110.1",
     "fastapi-offline-docs>=1",
     "opentelemetry-instrumentation-fastapi>=0.46b0",
-    "prometheus-fastapi-instrumentator>=6.1",
+    "prometheus-fastapi-instrumentator>=7.1",
 ]
 litestar = [
-    "litestar>=2.9",
+    "litestar>=2.21.1",
     "litestar-offline-docs>=1",
     "prometheus-client>=0.20",
 ]
 granian = ["granian[reload]>=1"]
-faststream = ["faststream~=0.6.2", "prometheus-client>=0.20"]
+faststream = ["faststream>=0.6.7,<0.8", "prometheus-client>=0.20"]
 fastmcp = ["fastmcp>=2,<4", "prometheus-client>=0.20"]
 
 [dependency-groups]

microbootstrap-1.5.5/microbootstrap/instruments/swagger_instrument.py

@@ -1,30 +0,0 @@
-from __future__ import annotations
-import typing
-
-import pydantic
-
-from microbootstrap.helpers import is_valid_path
-from microbootstrap.instruments.base import BaseInstrumentConfig, Instrument
-
-
-class SwaggerConfig(BaseInstrumentConfig):
-    service_name: str = "micro-service"
-    service_description: str = "Micro service description"
-    service_version: str = "1.0.0"
-
-    service_static_path: str = "/static"
-    swagger_path: str = "/docs"
-    swagger_offline_docs: bool = False
-    swagger_extra_params: dict[str, typing.Any] = pydantic.Field(default_factory=dict)
-
-
-class SwaggerInstrument(Instrument[SwaggerConfig]):
-    instrument_name = "Swagger"
-    ready_condition = "Provide valid swagger_path"
-
-    def is_ready(self) -> bool:
-        return bool(self.instrument_config.swagger_path) and is_valid_path(self.instrument_config.swagger_path)
-
-    @classmethod
-    def get_config_type(cls) -> type[SwaggerConfig]:
-        return SwaggerConfig