fairagro-middleware-shared 8.6.2__py3-none-any.whl

fairagro_middleware_shared-8.6.2.dist-info/METADATA

@@ -0,0 +1,64 @@
+Metadata-Version: 2.4
+Name: fairagro-middleware-shared
+Version: 8.6.2
+Summary: The FAIRagro advanced middleware shared components
+Requires-Python: >=3.12
+Requires-Dist: opentelemetry-api>=1.26.0
+Requires-Dist: opentelemetry-exporter-otlp>=1.26.0
+Requires-Dist: opentelemetry-instrumentation-logging>=0.47b0
+Requires-Dist: opentelemetry-sdk>=1.26.0
+Requires-Dist: pydantic>=2.12.5
+Requires-Dist: pyyaml>=6.0.3
+Description-Content-Type: text/markdown
+
+# FAIRagro Advanced Middleware - Shared Components
+
+This package contains shared utilities and components used across the FAIRagro Advanced Middleware system.
+
+## Overview
+
+The `shared` package provides:
+
+- **Configuration Management**: Base classes and utilities for configuration handling
+- **Common Models**: Pydantic models used across multiple middleware components
+- **Utilities**: Helper functions and classes for common operations
+
+## Components
+
+### Configuration (`middleware.shared.config`)
+
+Configuration utilities including:
+
+- `ConfigWrapper`: Base class for configuration management
+- Environment variable handling
+- Configuration validation with Pydantic
+
+### Models
+
+Shared Pydantic models for data validation and serialization across the middleware.
+
+## Usage
+
+This package is used as a dependency by other middleware components:
+
+- `api`: The main REST API
+- `api_client`: Client library for API interaction
+- `inspire_to_arc`: INSPIRE metadata to ARC conversion
+
+## Dependencies
+
+- `pydantic>=2.12.4`: Data validation and settings management
+
+## Development
+
+Install in development mode:
+
+```bash
+uv sync --package shared
+```
+
+Run tests:
+
+```bash
+uv run pytest middleware/shared/tests
+```

fairagro_middleware_shared-8.6.2.dist-info/RECORD

@@ -0,0 +1,20 @@
+middleware/shared/__init__.py,sha256=P1d-PbOOQXB6bJLPcR-vb66YFqze_b-VzkP-VKaRvfE,47
+middleware/shared/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+middleware/shared/tracing.py,sha256=d363v8w_6nyaxefLRVZGIKjlXHihUqM5YW_m4zf03Js,6040
+middleware/shared/api_models/__init__.py,sha256=fQLjOxBdZjagn-EtXNIqQJKxnXDLetKsAshUcKhayOQ,940
+middleware/shared/api_models/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+middleware/shared/api_models/common/__init__.py,sha256=rDdbCPIBgQWBu9dTuW5U4U5u6FjydyGJGDR1kHMPeuc,25
+middleware/shared/api_models/common/models.py,sha256=ij7lV3Xw-el7Mz4Lx8nZQlOXfHiEDJqYxjkVCcU_qAc,3115
+middleware/shared/api_models/v1/__init__.py,sha256=WDN-CbCiwGIHmMBBVauRIJpMlARkkvnw2eSqGGxx3_Q,21
+middleware/shared/api_models/v1/models.py,sha256=q08cUlZcJzKZugQ5Ncksjt_R_kjHVixMRzHgdDLCcBI,2712
+middleware/shared/api_models/v2/__init__.py,sha256=XQCD-gAp1pa-ZablK7ARIkbyK-kmQQfZnmnGkOU_7A8,21
+middleware/shared/api_models/v2/models.py,sha256=jZrshUQTk2iGO0I9pA6ZtZAoSZ1aC6M1Jad5TPtR4E0,1298
+middleware/shared/api_models/v3/__init__.py,sha256=hInpKWTKW9hKvNil789NPLbHdz4pnShoATVI0ILVKZk,21
+middleware/shared/api_models/v3/models.py,sha256=9PdV5Z5O5WI7gBY428fSodUTQ_1VGpq4FClLky7e2YE,3679
+middleware/shared/config/__init__.py,sha256=KTiiSPDPCuOxRMsqaK-7K-yVWgA2wPMYDCdQ_wv89Cs,49
+middleware/shared/config/config_base.py,sha256=DRDOUghZXfHz-gy7fhYYV20tTHBdIU0beAMoi_VR3MM,2777
+middleware/shared/config/config_wrapper.py,sha256=g7C-_S8mMttQXucD8-NYKp5_7yHz0InJ8z252WiFfYk,12412
+middleware/shared/config/logging.py,sha256=mTZdSLADsevWzT1ebhWs0dl749y4friSZUftAAZ0c6o,667
+fairagro_middleware_shared-8.6.2.dist-info/METADATA,sha256=8rWMiNrufhbkOI3NrFIE7AxOd7rcoiXADMg9XlQZTMw,1659
+fairagro_middleware_shared-8.6.2.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+fairagro_middleware_shared-8.6.2.dist-info/RECORD,,

fairagro_middleware_shared-8.6.2.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

middleware/shared/__init__.py

@@ -0,0 +1 @@
+"""Contains same generic utility functions."""

middleware/shared/api_models/__init__.py

@@ -0,0 +1,30 @@
+"""FAIRagro Middleware API Models package.
+
+Backward compatibility layer for refactored shared models.
+"""
+
+from .common import models as common
+from .v1 import models as v1
+from .v2 import models as v2
+
+# Common / Shared
+ArcStatus = common.ArcStatus
+TaskStatus = common.TaskStatus
+ApiResponse = common.ApiResponse
+ArcResponse = common.ArcResponse  # V1/V2 common
+
+# V1 Models
+LivenessResponse = v1.LivenessResponse
+HealthResponse = v1.HealthResponse
+CreateOrUpdateArcsRequest = v1.CreateOrUpdateArcsRequest
+CreateOrUpdateArcsResponse = v1.CreateOrUpdateArcsResponse
+GetTaskStatusResponse = v1.GetTaskStatusResponse
+WhoamiResponse = v1.WhoamiResponse
+ArcTaskTicket = v1.ArcTaskTicket
+
+# V2 Models
+HealthResponseV2 = v2.HealthResponse
+CreateOrUpdateArcRequest = v2.CreateOrUpdateArcRequest
+CreateOrUpdateArcResponse = v2.CreateOrUpdateArcResponse
+ArcOperationResult = v2.ArcOperationResult
+GetTaskStatusResponseV2 = v2.GetTaskStatusResponse

middleware/shared/api_models/common/__init__.py

@@ -0,0 +1 @@
+"""Common API models."""

middleware/shared/api_models/common/models.py

@@ -0,0 +1,104 @@
+"""Common models and enums shared across API versions."""
+
+from enum import StrEnum
+from typing import Annotated
+
+from pydantic import BaseModel, Field
+
+
+class ArcStatus(StrEnum):
+    """Enumeration of possible ARC status values."""
+
+    CREATED = "created"
+    UPDATED = "updated"
+    DELETED = "deleted"
+    REQUESTED = "requested"
+
+
+class TaskStatus(StrEnum):
+    """Enumeration of possible task states.
+
+    Values match Celery task states.
+    """
+
+    PENDING = "PENDING"
+    STARTED = "STARTED"
+    SUCCESS = "SUCCESS"
+    FAILURE = "FAILURE"
+    RETRY = "RETRY"
+    REVOKED = "REVOKED"
+
+
+class ArcLifecycleStatus(StrEnum):
+    """ARC lifecycle status in the system."""
+
+    ACTIVE = "ACTIVE"  # Normal active state
+    PROCESSING = "PROCESSING"  # Git workflow in progress
+    MISSING = "MISSING"  # Not seen in recent harvest
+    DELETED = "DELETED"  # Soft-deleted (not physically removed)
+    INVALID = "INVALID"  # Validation failed
+
+
+class ArcEventType(StrEnum):
+    """Types of events in the ARC event log."""
+
+    # Lifecycle events
+    ARC_CREATED = "ARC_CREATED"
+    ARC_UPDATED = "ARC_UPDATED"
+    ARC_NOT_SEEN = "ARC_NOT_SEEN"
+    ARC_MARKED_MISSING = "ARC_MARKED_MISSING"
+    ARC_MARKED_DELETED = "ARC_MARKED_DELETED"
+    ARC_RESTORED = "ARC_RESTORED"  # Reappeared after being marked missing/deleted
+    ARC_NOT_CHANGED = "ARC_NOT_CHANGED"  # Explicitly tracking no-change events (if needed)
+
+    # Git workflow events
+    GIT_QUEUED = "GIT_QUEUED"
+    GIT_PROCESSING = "GIT_PROCESSING"
+    GIT_PUSH_SUCCESS = "GIT_PUSH_SUCCESS"
+    GIT_PUSH_FAILED = "GIT_PUSH_FAILED"
+
+    # Validation events
+    VALIDATION_WARNING = "VALIDATION_WARNING"
+    VALIDATION_ERROR = "VALIDATION_ERROR"
+    VALIDATION_SUCCESS = "VALIDATION_SUCCESS"
+
+    # Operator actions
+    OPERATOR_NOTE = "OPERATOR_NOTE"
+    MANUAL_DELETION = "MANUAL_DELETION"
+
+
+class HarvestStatus(StrEnum):
+    """Harvest run status."""
+
+    RUNNING = "RUNNING"
+    COMPLETED = "COMPLETED"
+    FAILED = "FAILED"
+    CANCELLED = "CANCELLED"
+
+
+class ApiResponse(BaseModel):
+    """Base response model for business logic operations."""
+
+    client_id: Annotated[
+        str | None,
+        Field(
+            description="Client identifier which is the CN from the client certificate, "
+            "or 'unknown' if client certificates are not required",
+        ),
+    ] = None
+    message: Annotated[str, Field(description="Response message")] = ""
+
+
+class ArcResponse(BaseModel):
+    """Response model for individual ARC operations."""
+
+    id: Annotated[str, Field(description="ARC identifier, as hashed value of the original identifier and RDI")]
+    status: Annotated[ArcStatus, Field(description="Status of the ARC operation")]
+    timestamp: Annotated[str, Field(description="Timestamp of the ARC operation in ISO 8601 format")]
+
+
+class ArcOperationResult(ApiResponse):
+    """Response model for the actual result of a single ARC operation."""
+
+    rdi: Annotated[str, Field(description="Research Data Infrastructure identifier the ARC belongs to")]
+    arc: Annotated[ArcResponse, Field(description="ARC response for the operation")]

middleware/shared/api_models/v1/__init__.py

@@ -0,0 +1 @@
+"""V1 API models."""

middleware/shared/api_models/v1/models.py

@@ -0,0 +1,74 @@
+"""V1 API Models."""
+
+from typing import Annotated
+
+from pydantic import BaseModel, Field
+
+from ..common.models import ApiResponse, ArcResponse
+
+
+class LivenessResponse(BaseModel):
+    """Response model for liveness check."""
+
+    message: Annotated[str, Field(description="Liveness message")] = "ok"
+
+
+class HealthResponse(BaseModel):
+    """Response model for health check including backend status."""
+
+    status: Annotated[str, Field(description="Overall service status (ok/error)")] = "ok"
+    redis_reachable: Annotated[
+        bool,
+        Field(
+            description="[DEPRECATED] Kept for backward compatibility. Always True as Redis is no longer used.",
+            deprecated=True,
+        ),
+    ] = True
+    rabbitmq_reachable: Annotated[bool, Field(description="True if RabbitMQ is reachable")]
+
+
+class WhoamiResponse(ApiResponse):
+    """Response model for whoami operation."""
+
+    accessible_rdis: Annotated[
+        list[str], Field(description="List of Research Data Infrastructures the client is authorized for")
+    ]
+
+
+class ArcTaskTicket(ApiResponse):
+    """Response model for a newly created async task ticket."""
+
+    rdi: Annotated[str, Field(description="Research Data Infrastructure identifier the ARC belongs to")]
+    task_id: Annotated[str, Field(description="Async task ID")]
+
+
+class CreateOrUpdateArcsRequest(BaseModel):
+    """Request model for creating or updating ARCs."""
+
+    rdi: Annotated[str, Field(description="Research Data Infrastructure identifier")]
+    arcs: Annotated[list[dict], Field(description="List of ARC definitions in RO-Crate JSON format")]
+
+
+class CreateOrUpdateArcsResponse(ApiResponse):
+    """Response model for create or update ARC operations (Task Ticket or Result)."""
+
+    rdi: Annotated[str | None, Field(description="Research Data Infrastructure identifier the ARCs belong to")] = None
+    arcs: Annotated[list[ArcResponse], Field(description="List of ARC responses for the operation")] = Field(
+        default_factory=list
+    )
+
+    # Async task fields
+    task_id: Annotated[str | None, Field(description="The ID of the background task processing the ARC")] = None
+    status: Annotated[str | None, Field(description="The status of the task submission")] = None
+
+
+class GetTaskStatusResponse(BaseModel):
+    """Response model for task status."""
+
+    task_id: Annotated[str, Field(description="The ID of the background task")]
+    status: Annotated[str, Field(description="The status of the task")]
+    result: Annotated[
+        CreateOrUpdateArcsResponse | None,
+        Field(description="The result of the task if completed"),
+    ] = None
+    error: Annotated[str | None, Field(description="Error message if task failed")] = None

middleware/shared/api_models/v2/__init__.py

@@ -0,0 +1 @@
+"""V2 API models."""

middleware/shared/api_models/v2/models.py

@@ -0,0 +1,38 @@
+"""V2 API Models."""
+
+from typing import Annotated
+
+from pydantic import BaseModel, Field
+
+from ..common.models import ApiResponse, ArcOperationResult, TaskStatus
+
+
+class HealthResponse(BaseModel):
+    """Response model for health check v2."""
+
+    status: Annotated[str, Field(description="Overall service status (ok/error)")] = "ok"
+    services: Annotated[dict[str, bool], Field(description="Dictionary of service statuses")]
+
+
+class CreateOrUpdateArcRequest(BaseModel):
+    """Request model for creating or updating a single ARC."""
+
+    rdi: Annotated[str, Field(description="Research Data Infrastructure identifier")]
+    arc: Annotated[dict, Field(description="ARC definition in RO-Crate JSON format")]
+
+
+class CreateOrUpdateArcResponse(ApiResponse):
+    """Response model for create or update a single ARC operation ticket."""
+
+    task_id: Annotated[str, Field(description="The ID of the background task")]
+    status: Annotated[TaskStatus, Field(description="The status of the task")]
+
+
+class GetTaskStatusResponse(ApiResponse):
+    """Response model for task status."""
+
+    status: Annotated[TaskStatus, Field(description="The status of the task")]
+    result: Annotated[
+        ArcOperationResult | None,
+        Field(description="The result of the task if completed"),
+    ] = None

middleware/shared/api_models/v3/__init__.py

@@ -0,0 +1 @@
+"""V3 API models."""

middleware/shared/api_models/v3/models.py

@@ -0,0 +1,106 @@
+"""V3 API Models."""
+
+from enum import StrEnum
+from typing import Annotated
+
+from pydantic import BaseModel, Field
+
+from ..common.models import ApiResponse, ArcLifecycleStatus, ArcStatus, HarvestStatus
+
+
+class CreateArcRequest(BaseModel):
+    """Request model for creating or updating a single ARC."""
+
+    rdi: Annotated[str, Field(description="Research Data Infrastructure identifier")]
+    arc: Annotated[dict, Field(description="ARC definition in RO-Crate JSON format")]
+
+
+class BaseStatusResponse(BaseModel):
+    """Base response model for status-only API responses."""
+
+    status: Annotated["StatusResponse", Field(description="Overall service status")]
+    services: Annotated[dict[str, bool], Field(description="Dictionary of service checks")]
+
+
+class StatusResponse(StrEnum):
+    """Allowed status values for liveness/readiness/health responses."""
+
+    OK = "ok"
+    ERROR = "error"
+
+
+class LivenessResponse(BaseStatusResponse):
+    """Response model for liveness checks."""
+
+
+class ReadinessResponse(BaseStatusResponse):
+    """Response model for readiness checks."""
+
+
+class HealthResponse(BaseStatusResponse):
+    """Response model for global health checks."""
+
+
+class SubmitHarvestArcRequest(BaseModel):
+    """Request model for submitting an ARC within an ongoing harvest run.
+
+    The ``rdi`` is not required here — it is resolved automatically from the
+    harvest identified by the ``harvest_id`` path parameter.
+    """
+
+    arc: Annotated[
+        dict,
+        Field(
+            description=(
+                "ARC definition in RO-Crate JSON format. "
+                "The RDI is taken from the harvest run identified by the path parameter."
+            )
+        ),
+    ]
+
+
+class ArcEventSummary(BaseModel):
+    """Summary of an ARC event."""
+
+    timestamp: Annotated[str, Field(description="Timestamp of the event")]
+    type: Annotated[str, Field(description="Type of the event")]
+    message: Annotated[str, Field(description="Event message")]
+
+
+class ArcMetadata(BaseModel):
+    """Metadata summary."""
+
+    arc_hash: Annotated[str, Field(description="SHA256 hash of ARC content")]
+    status: Annotated[ArcLifecycleStatus, Field(description="Current lifecycle status")]
+    first_seen: Annotated[str, Field(description="First time ARC was seen")]
+    last_seen: Annotated[str, Field(description="Last time ARC was seen")]
+
+
+class ArcResponse(ApiResponse):
+    """Result of an ARC operation, containing full details."""
+
+    arc_id: Annotated[str, Field(description="ARC identifier")]
+    status: Annotated[ArcStatus, Field(description="Status of the ARC operation")]
+    metadata: Annotated[ArcMetadata, Field(description="Summary metadata")]
+    events: Annotated[list[ArcEventSummary], Field(description="Summary event log")] = Field(default_factory=list)
+
+
+class CreateHarvestRequest(BaseModel):
+    """Request model for starting a new harvest."""
+
+    rdi: Annotated[str, Field(description="Research Data Infrastructure identifier")]
+    expected_datasets: Annotated[
+        int | None,
+        Field(description="Optional number of datasets expected to be harvested, as reported by the client."),
+    ] = None
+
+
+class HarvestResponse(ApiResponse):
+    """Response model for harvest details."""
+
+    harvest_id: Annotated[str, Field(description="Unique harvest identifier")]
+    rdi: Annotated[str, Field(description="RDI identifier")]
+    status: Annotated[HarvestStatus, Field(description="Current status")]
+    started_at: Annotated[str, Field(description="Start timestamp")]
+    completed_at: Annotated[str | None, Field(description="Completion timestamp")] = None
+    statistics: Annotated[dict, Field(description="Harvest statistics")]

middleware/shared/config/__init__.py

@@ -0,0 +1 @@
+"""FAIRware Middleware shared config package."""

middleware/shared/config/config_base.py

@@ -0,0 +1,96 @@
+"""FAIRagro Middleware base configuration module."""
+
+import logging
+from pathlib import Path
+from typing import Annotated, Any, Literal, Self, cast
+
+from pydantic import BaseModel, Field, field_validator
+
+from .config_wrapper import ConfigWrapper
+
+LogLevel = Literal["CRITICAL", "ERROR", "WARNING", "INFO", "DEBUG", "NOTSET"]
+
+
+class OtelConfig(BaseModel):
+    """OpenTelemetry logging and tracing configuration."""
+
+    endpoint: Annotated[
+        str | None,
+        Field(
+            description="OpenTelemetry collector endpoint URL",
+            examples=["http://signoz:4318"],
+        ),
+    ] = None
+    log_console_spans: Annotated[
+        bool,
+        Field(description="Log OpenTelemetry spans to console"),
+    ] = False
+    log_level: Annotated[
+        LogLevel,
+        Field(description="Logging level for OTLP log export"),
+    ] = "INFO"
+
+
+class ConfigBase(BaseModel):
+    """Configuration base class for the FAIRagro advanced Middleware."""
+
+    log_level: Annotated[LogLevel, Field(description="Logging level for console/stdout logging")] = "INFO"
+    otel: OtelConfig = Field(default_factory=OtelConfig, description="OpenTelemetry configuration")
+
+    @field_validator("otel", mode="before")
+    @classmethod
+    def validate_otel(cls, v: Any) -> Any:
+        """Allow None for otel and convert to empty dict for default factory."""
+        if v is None:
+            return {}
+        return v
+
+    @classmethod
+    def from_config_wrapper(cls, wrapper: ConfigWrapper) -> Self:
+        """Create Config from ConfigWrapper.
+
+        Args:
+            wrapper (ConfigWrapper): Wrapped configuration data.
+
+        Returns:
+            Self: Configuration instance.
+
+        """
+        unwrapped = wrapper.unwrap()
+        # Cast to satisfy MyPy's warn_return_any=true setting
+        return cast(Self, cls.model_validate(unwrapped))
+
+    @classmethod
+    def from_data(cls, data: dict) -> Self:
+        """Create Config from raw data dictionary.
+
+        Args:
+            data (dict): Raw configuration data.
+
+        Returns:
+            Self: Configuration instance.
+
+        """
+        wrapper = ConfigWrapper.from_data(data)
+        return cls.from_config_wrapper(wrapper)
+
+    @classmethod
+    def from_yaml_file(cls, path: Path) -> Self:
+        """Create Config from a YAML file.
+
+        Args:
+            path (Path): Path to the YAML config file.
+
+        Returns:
+            Config: Configuration instance.
+
+        Raises:
+            RuntimeError: If the config file is not found.
+
+        """
+        if path.is_file():
+            wrapper = ConfigWrapper.from_yaml_file(path)
+            return cls.from_config_wrapper(wrapper)
+        msg = f"Config file {path} not found."
+        logging.error(msg)
+        raise RuntimeError(msg)

middleware/shared/config/config_wrapper.py

@@ -0,0 +1,372 @@
+"""Defines the ConfigWrapper class that wraps a yaml file and supports.
+
+Overriding single entries in the yaml tree by env vars or docker
+secret files in /run/secrets.
+"""
+
+import os
+from abc import abstractmethod
+from collections.abc import Generator
+from pathlib import Path
+from typing import cast
+
+import yaml
+
+type KeyType = str | int
+type DictType = dict[str, "ValueType"]
+type ListType = list["ValueType"]
+type PrimitiveType = str | int | float | bool | None
+type ValueType = DictType | ListType | PrimitiveType
+type WrapType = "ConfigWrapper | PrimitiveType"
+
+
+class ConfigWrapper:
+    """Wraps nested dicts and lists (aka loaded yaml).
+
+    Supports Env/Docker-Secret-Overrides.
+    """
+
+    def __init__(self, path: str = "") -> None:
+        """Initialize a ConfigWrapper with an optional path prefix.
+
+        Args:
+            path: The path prefix used for environment variable and secret lookups.
+
+        """
+        self._path = path.upper()
+
+    def _build_path(self, key: str) -> str:
+        return f"{self._path}_{key}" if self._path else key
+
+    def _wrap(self, value: "ValueType | None", key: str) -> WrapType:
+        return ConfigWrapper._from_value(value, self._build_path(key))
+
+    @staticmethod
+    def _from_value(value: "ValueType | None", path: str) -> WrapType:
+        if isinstance(value, dict):
+            return ConfigWrapperDict(value, path)
+        if isinstance(value, list):
+            return ConfigWrapperList(value, path)
+        return value
+
+    @classmethod
+    def from_data(cls, data: DictType | ListType, prefix: str = "") -> "ConfigWrapper":
+        """Create a ConfigWrapper from a dictionary or list.
+
+        Args:
+            data: The dictionary or list to wrap.
+            prefix: Optional prefix for environment variable and secret lookups.
+
+        Returns:
+            A new ConfigWrapper instance wrapping the provided data.
+
+        Raises:
+            TypeError: If data is neither a dictionary nor a list.
+
+        """
+        wrapped = cls._from_value(data, prefix)
+        if not isinstance(wrapped, ConfigWrapper):
+            raise TypeError(f"'ConfigWrapper' only wraps lists or dicts. You're trying to wrap a '{type(data)}'")
+        return wrapped
+
+    @classmethod
+    def from_yaml_file(cls, path: Path, prefix: str = "") -> "ConfigWrapper":
+        """Create a ConfigWrapper from a yaml file."""
+        with open(path, encoding="utf-8") as f:
+            data = yaml.safe_load(f) or {}
+            return cls.from_data(data, prefix)
+
+    @staticmethod
+    def _get_path_str(value: "ValueType | None", key: KeyType) -> str:
+        if isinstance(value, dict) and "id" in value:
+            return cast(str, value["id"])
+        return str(key)
+
+    @abstractmethod
+    def __getitem__(self, key: KeyType) -> WrapType:
+        """Return the value for the given key from the configuration.
+
+        Args:
+            key: The key to lookup in the configuration.
+
+        Returns:
+            The value associated with the key, wrapped if necessary.
+
+        Raises:
+            NotImplementedError: When called on the base class.
+
+        """
+        raise NotImplementedError("Please do not use class 'ConfigWrapper' directly, but a derived class")
+
+    def get(self, key: KeyType, default_value: "ValueType | None" = None) -> WrapType:
+        """Return the value of a config key.
+
+        If the value is a dict or list, it's again wrapped into to ConfigWrapper object.
+        """
+        try:
+            return self[key]
+        except KeyError:
+            key_str = ConfigWrapper._get_path_str(default_value, key)
+            return self._wrap(default_value, key_str)
+
+    @classmethod
+    def _unwrap(cls, wrapper: WrapType) -> ValueType:
+        if isinstance(wrapper, ConfigWrapperDict):
+            return {k: cls._unwrap(v) for k, v in wrapper.items()}
+        if isinstance(wrapper, ConfigWrapperList):
+            return [cls._unwrap(v) for _, v in wrapper.items()]
+        if isinstance(wrapper, (str, int, float, bool, type(None))):
+            return wrapper
+        raise TypeError(f"Cannot unwrap element of type '{type(wrapper)}'")
+
+    def unwrap(self) -> DictType | ListType:
+        """Convert the wrapped configuration back to a plain dictionary or list.
+
+        Returns:
+            The unwrapped configuration as a dictionary or list.
+
+        Raises:
+            TypeError: If the unwrapped value is not a dictionary or list.
+
+        """
+        unwrapped = ConfigWrapper._unwrap(self)
+        if isinstance(unwrapped, dict | list):
+            return unwrapped
+        raise TypeError(f"Unwrapped values must be of type list or dict, found '{type(unwrapped)}'")
+
+    @abstractmethod
+    def __iter__(self) -> Generator[KeyType, None, None]:
+        """Return an iterator over the configuration keys.
+
+        Returns:
+            A generator yielding keys of the configuration.
+
+        """
+        raise NotImplementedError("Please do not use class 'ConfigWrapper' directly, but a derived class")
+
+    @abstractmethod
+    def items(self) -> Generator[tuple[KeyType, WrapType], None, None]:
+        """Return an iterator over the configuration key-value pairs.
+
+        Returns:
+            A generator yielding tuples of (key, value) pairs from the configuration.
+
+        """
+        raise NotImplementedError("Please do not use class 'ConfigWrapper' directly, but a derived class")
+
+    @abstractmethod
+    def __len__(self) -> int:
+        """Return the number of items in the configuration.
+
+        Returns:
+            The number of items in the configuration.
+
+        """
+        raise NotImplementedError("Please do not use class 'ConfigWrapper' directly, but a derived class")
+
+    def _override_key_access(self, key: str) -> PrimitiveType:
+        """Get override value for a key from environment or Docker secrets.
+
+        Attempts to parse the override value as a primitive type (bool, int, float).
+        Supports the following formats:
+        - "true", "false" (case-insensitive) -> bool
+        - Numeric strings -> int or float
+        - Other strings -> str
+        - Empty string defaults to None
+
+        Args:
+            key: The configuration key to lookup.
+
+        Returns:
+            The override value as a primitive type, or None if not found.
+        """
+        # self._path should alwys be upper case
+        full_key = self._build_path(key.upper())
+
+        override_value = None
+
+        # 1️⃣ Check ENV
+        if full_key in os.environ:
+            override_value = os.environ[full_key]
+
+        # 2️⃣ Check Docker secret file
+        if override_value is None:
+            secret_file = Path(f"/run/secrets/{full_key.lower()}")
+            if secret_file.exists():
+                override_value = secret_file.read_text(encoding="utf-8").strip()
+
+        if override_value is None:
+            return None
+
+        # Parse the override value to appropriate primitive type
+        return self._parse_primitive_value(override_value)
+
+    @staticmethod
+    def _parse_primitive_value(value: str) -> PrimitiveType:
+        """Parse a string value into its appropriate primitive type.
+
+        Conversion rules (in order):
+        1. Empty string -> None
+        2. "true"/"false" (case-insensitive) -> bool
+        3. Integer-like strings -> int
+        4. Float-like strings -> float
+        5. Everything else -> str
+
+        Args:
+            value: The string value to parse.
+
+        Returns:
+            The parsed primitive value.
+        """
+        if not value:
+            return None
+
+        # Try bool
+        if value.lower() in {"true", "false"}:
+            return value.lower() == "true"
+
+        # Try int
+        try:
+            return int(value)
+        except ValueError:
+            pass
+
+        # Try float
+        try:
+            return float(value)
+        except ValueError:
+            pass
+
+        # Default to string
+        return value
+
+
+class ConfigWrapperDict(ConfigWrapper):
+    """A ConfigWrapper flavor that specifically wraps dicts."""
+
+    def __init__(self, data: DictType, path: str = "") -> None:
+        """Initialize a ConfigWrapperDict with dictionary data and an path prefix.
+
+        Args:
+            data: The dictionary to wrap.
+            path: The path prefix used for environment variable and secret lookups.
+
+        """
+        super().__init__(path)
+        self._data = data
+
+    def _all_keys(self) -> set[str]:
+        """All keys including discovered ENV/Secrets."""
+        keys = set(self._data.keys())
+        prefix = f"{self._path}_" if self._path else ""
+
+        # Only discover new keys from environment if we are within a sub-path
+        # Root level keys must be present in the YAML to be overridden
+        if prefix:
+            for env_key in os.environ:
+                if env_key.startswith(prefix):
+                    key_suffix = env_key[len(prefix) :]
+                    keys.add(key_suffix.lower())
+
+        secrets_dir = Path("/run/secrets")
+        path_lower = self._path.lower()
+        prefix_lower = f"{path_lower}_" if path_lower else ""
+        if secrets_dir.exists() and prefix_lower:
+            for secret_file in secrets_dir.iterdir():
+                if secret_file.name.startswith(prefix_lower):
+                    key_suffix = secret_file.name[len(prefix_lower) :]
+                    keys.add(key_suffix.lower())
+        return keys
+
+    def __getitem__(self, key: KeyType) -> WrapType:
+        """Return the value for the given key from the configuration.
+
+        Args:
+            key: The key to lookup in the configuration.
+
+        Returns:
+            WrapType: The value associated with the key, wrapped if necessary.
+
+        """
+        if not isinstance(key, str):
+            raise TypeError(f"ConfigWrapperDict only supports string keys, got {type(key)}")
+
+        override_value = self._override_key_access(key)
+        if override_value is not None:
+            return override_value
+        value = self._data[key]
+        return super()._wrap(value, key)
+
+    def __iter__(self) -> Generator[str, None, None]:
+        """Iterate over dict keys."""
+        yield from self._all_keys()
+
+    def items(self) -> Generator[tuple[str, WrapType], None, None]:
+        """Iterate over key-value pairs."""
+        for key in self._all_keys():
+            yield key, self[key]
+
+    def __len__(self) -> int:
+        """Return the number of keys in the configuration dictionary.
+
+        Returns:
+            The total count of configuration keys including environment and secret
+            overrides.
+
+        """
+        return len(self._all_keys())
+
+
+class ConfigWrapperList(ConfigWrapper):
+    """A ConfigWrapper flavour that specifically wraps lists."""
+
+    def __init__(self, data: ListType, path: str = "") -> None:
+        """Initialize a ConfigWrapperList with list data and a path prefix.
+
+        Args:
+            data: The list to wrap.
+            path: The path prefix used for environment variable and secret lookups.
+
+        """
+        super().__init__(path)
+        self._data = data
+
+    def __getitem__(self, key: KeyType) -> WrapType:
+        """Return the value at the specified index in the list.
+
+        Args:
+            key: The index to lookup in the list.
+
+        Returns:
+            The value at the specified index, wrapped if necessary.
+
+        """
+        if not isinstance(key, int):
+            raise TypeError(f"ConfigWrapperList only supports integer keys, got {type(key)}")
+
+        value = self._data[key]
+        key_str = ConfigWrapper._get_path_str(value, key)  # noqa: SLF001
+        override_value = self._override_key_access(key_str)
+        if override_value is not None:
+            return override_value
+        return super()._wrap(value, key_str)
+
+    def __iter__(self) -> Generator[int, None, None]:
+        """Iterate over list indices."""
+        for idx, _ in enumerate(self._data):
+            yield idx
+
+    def items(self) -> Generator[tuple[int, WrapType], None, None]:
+        """Iterate over index-value pairs."""
+        for idx, value in enumerate(self._data):
+            key_str = ConfigWrapper._get_path_str(value, idx)  # noqa: SLF001
+            yield idx, super()._wrap(value, key_str)
+
+    def __len__(self) -> int:
+        """Return the number of items in the list.
+
+        Returns:
+            The length of the wrapped list.
+
+        """
+        return len(self._data)

middleware/shared/config/logging.py

@@ -0,0 +1,25 @@
+"""Logging configuration module.
+
+This module provides functionality to configure logging levels for all handlers
+and the root logger across the application.
+"""
+
+import logging
+
+from middleware.shared.config.config_base import LogLevel
+
+
+def configure_logging(level: LogLevel) -> None:
+    """Configure logging level for all handlers.
+
+    Args:
+        level: Logging level to set for all handlers and root logger.
+    """
+    root = logging.getLogger()
+    if root.handlers:
+        # vorhandene Handler neu konfigurieren
+        for h in root.handlers:
+            h.setLevel(level)
+        root.setLevel(level)
+    else:
+        logging.basicConfig(level=level)

middleware/shared/tracing.py

@@ -0,0 +1,154 @@
+"""
+OpenTelemetry tracing configuration for the middleware API.
+
+This module initializes and configures OpenTelemetry for distributed tracing,
+with support for FastAPI auto-instrumentation, console logging, and OTLP export to Signoz.
+"""
+
+import logging
+from collections.abc import Sequence
+from typing import TYPE_CHECKING
+
+from opentelemetry import trace
+from opentelemetry._logs import set_logger_provider
+from opentelemetry.exporter.otlp.proto.http._log_exporter import OTLPLogExporter
+from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
+from opentelemetry.instrumentation.logging.handler import LoggingHandler
+from opentelemetry.sdk._logs import LoggerProvider
+from opentelemetry.sdk._logs.export import (
+    BatchLogRecordProcessor,
+    ConsoleLogRecordExporter,
+    SimpleLogRecordProcessor,
+)
+from opentelemetry.sdk.resources import Resource
+from opentelemetry.sdk.trace import ReadableSpan, TracerProvider
+from opentelemetry.sdk.trace.export import BatchSpanProcessor, SimpleSpanProcessor, SpanExporter, SpanExportResult
+
+if TYPE_CHECKING:
+    pass
+
+logger = logging.getLogger(__name__)
+
+
+class SimpleConsoleSpanExporter(SpanExporter):
+    """Simple span exporter that logs to console."""
+
+    def export(self, spans: Sequence[ReadableSpan]) -> SpanExportResult:  # noqa: PLR6301
+        """Export spans to console."""
+        for span in spans:
+            if span.end_time is not None and span.start_time is not None:
+                duration_ms = (span.end_time - span.start_time) / 1e6
+            else:
+                duration_ms = 0.0
+            logger.info(
+                "SPAN: %s (duration=%0.3fms)",
+                span.name,
+                duration_ms,
+            )
+            if span.attributes:
+                logger.info("  Attributes: %s", span.attributes)
+        return SpanExportResult.SUCCESS
+
+    def shutdown(self) -> None:
+        """Shutdown the exporter."""
+        pass
+
+    def force_flush(self, _timeout_millis: int = 30000) -> bool:  # noqa: PLR6301
+        """Flush any pending spans."""
+        return True
+
+
+def initialize_tracing(
+    service_name: str = "middleware-api",
+    otlp_endpoint: str | None = None,
+    log_console_spans: bool = True,
+) -> tuple[TracerProvider, trace.Tracer]:
+    """
+    Initialize OpenTelemetry tracing with console and optional OTLP exporter.
+
+    Args:
+        service_name: The service name for traces (default: "middleware-api")
+        otlp_endpoint: Optional OTLP endpoint URL (e.g. http://signoz:4318)
+        log_console_spans: Whether to log spans to console (default: True)
+
+    Returns:
+        Tuple of (TracerProvider, Tracer) for use in the application
+    """
+    # Create a resource describing this service
+    resource = Resource.create({
+        "service.name": service_name,
+        "service.version": "0.0.0",
+    })
+
+    # Create a tracer provider
+    tracer_provider = TracerProvider(resource=resource)
+
+    # Optionally add console exporter for development/debugging
+    if log_console_spans:
+        console_exporter = SimpleConsoleSpanExporter()
+        tracer_provider.add_span_processor(SimpleSpanProcessor(console_exporter))
+
+    # Optionally add OTLP exporter for Signoz/Jaeger/etc
+    if otlp_endpoint:
+        try:
+            otlp_exporter = OTLPSpanExporter(endpoint=f"{otlp_endpoint}/v1/traces")
+            tracer_provider.add_span_processor(BatchSpanProcessor(otlp_exporter))
+            logger.info("OpenTelemetry OTLP exporter configured: %s", otlp_endpoint)
+        except (ValueError, OSError) as e:
+            logger.warning("Failed to configure OTLP exporter: %s", e)
+
+    # Set the global tracer provider
+    trace.set_tracer_provider(tracer_provider)
+
+    # Get a tracer for this module
+    tracer = trace.get_tracer(__name__)
+
+    logger.info(
+        "OpenTelemetry tracing initialized (console=%s, otlp=%s)",
+        log_console_spans,
+        bool(otlp_endpoint),
+    )
+
+    return tracer_provider, tracer
+
+
+def initialize_logging(
+    service_name: str = "middleware-api",
+    otlp_endpoint: str | None = None,
+    log_console: bool = False,
+    log_level: int = logging.INFO,
+    otlp_log_level: int = logging.INFO,
+) -> LoggerProvider:
+    """
+    Initialize OpenTelemetry logging with optional OTLP exporter.
+
+    Args:
+        service_name: The service name for log records.
+        service_version: The service version for log records.
+        otlp_endpoint: Optional OTLP endpoint URL (e.g. http://signoz:4318).
+        log_console: Whether to also export logs to console via OTLP SDK exporter.
+    """
+    resource = Resource.create({"service.name": service_name, "service.version": "0.0.0"})
+    logger_provider = LoggerProvider(resource=resource)
+
+    if otlp_endpoint:
+        try:
+            otlp_log_exporter = OTLPLogExporter(endpoint=f"{otlp_endpoint}/v1/logs")
+            logger_provider.add_log_record_processor(BatchLogRecordProcessor(otlp_log_exporter))
+            if log_console:
+                logger_provider.add_log_record_processor(SimpleLogRecordProcessor(ConsoleLogRecordExporter()))
+            set_logger_provider(logger_provider)
+            root_handler = LoggingHandler(level=otlp_log_level, logger_provider=logger_provider)
+            root_logger = logging.getLogger()
+            root_logger.addHandler(root_handler)
+            root_logger.setLevel(min(root_logger.level or log_level, log_level))
+            # Prevent self-logging loops: OTEL internal logs and noisy HTTP/SSL logs at WARNING+ only
+            logging.getLogger("opentelemetry").setLevel(logging.WARNING)
+            logging.getLogger("urllib3").setLevel(logging.WARNING)
+            logging.getLogger("httpx").setLevel(logging.WARNING)
+            logging.getLogger("httpcore").setLevel(logging.WARNING)
+            logger.info("OpenTelemetry log exporter configured: %s", otlp_endpoint)
+        except (ValueError, OSError) as e:  # pragma: no cover - defensive path
+            logger.warning("Failed to configure OTLP log exporter: %s", e)
+
+    return logger_provider