omnibase_infra 0.2.1__py3-none-any.whl

omnibase_infra/runtime/models/__init__.py

@@ -0,0 +1,192 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Runtime Models Module.
+
+This module exports Pydantic models for runtime configuration and events.
+All models are strongly typed to eliminate Any usage.
+
+Exports:
+    ModelComputeKey: Strongly-typed compute registry key model
+    ModelComputeRegistration: Compute plugin registration parameters model
+    ModelConfigRef: Parsed configuration reference (file, env, vault)
+    ModelConfigRefParseResult: Result of parsing a config reference
+    EnumConfigRefScheme: Supported config reference schemes
+    ModelDomainPluginConfig: Configuration for domain plugin lifecycle hooks
+    ModelDomainPluginResult: Result of domain plugin lifecycle operations
+    ModelEventBusConfig: Event bus configuration model
+    ModelEnabledProtocolsConfig: Enabled protocols configuration model
+    ModelProtocolRegistrationConfig: Individual protocol registration config model
+    ModelLoggingConfig: Logging configuration model
+    ModelShutdownConfig: Shutdown configuration model
+    ModelRuntimeConfig: Top-level runtime configuration model
+    ModelRuntimeSchedulerConfig: Runtime tick scheduler configuration model
+    ModelRuntimeSchedulerMetrics: Runtime scheduler metrics model
+    ModelOptionalString: Wrapper for optional string values
+    ModelOptionalUUID: Wrapper for optional UUID values
+    ModelOptionalCorrelationId: Wrapper for optional correlation ID values
+    ModelPolicyTypeFilter: Wrapper for policy type filter values
+    ModelPolicyContext: Structured context model for policy evaluation
+    ModelPolicyResult: Structured result model for policy decisions
+    ModelPolicyRegistration: Policy registration parameters model
+    ModelPolicyKey: Strongly-typed policy registry key model
+    ModelRuntimeTick: Infrastructure event emitted by runtime scheduler
+    ModelDuplicateResponse: Response for duplicate message detection
+    ModelLifecycleResult: Result of individual handler lifecycle operation
+    ModelBatchLifecycleResult: Result of batch handler lifecycle operations
+    ModelFailedComponent: Represents a component that failed during shutdown
+    ModelShutdownBatchResult: Result of batch shutdown operation
+    ModelHealthCheckResult: Result of component health check operation
+    ModelHealthCheckResponse: HTTP response model for health check endpoints
+    ModelProjectorPluginLoaderConfig: Projector plugin loader configuration model
+    ModelSecretSourceSpec: Source specification for a single secret
+    SecretSourceType: Type alias for secret source types (env, vault, file)
+    ModelSecretMapping: Mapping from logical name to source specification
+    ModelSecretResolverConfig: Configuration for SecretResolver
+    ModelCachedSecret: Cached secret with TTL tracking
+    ModelSecretCacheStats: Cache statistics for observability
+    ModelSecretResolverMetrics: Resolution metrics for observability
+    ModelSecretSourceInfo: Non-sensitive source information for introspection
+    ModelRetryPolicy: Retry policy configuration for handler operations
+    ModelBindingConfig: Configuration for binding a handler to the runtime
+    ModelBindingConfigCacheStats: Cache statistics for BindingConfigResolver
+    ModelBindingConfigResolverConfig: Configuration for BindingConfigResolver
+    ModelConfigCacheEntry: Internal cache entry for BindingConfigResolver
+"""
+
+from omnibase_infra.runtime.enums.enum_config_ref_scheme import EnumConfigRefScheme
+from omnibase_infra.runtime.models.model_batch_lifecycle_result import (
+    ModelBatchLifecycleResult,
+)
+from omnibase_infra.runtime.models.model_binding_config import ModelBindingConfig
+from omnibase_infra.runtime.models.model_binding_config_cache_stats import (
+    ModelBindingConfigCacheStats,
+)
+from omnibase_infra.runtime.models.model_binding_config_resolver_config import (
+    ModelBindingConfigResolverConfig,
+)
+from omnibase_infra.runtime.models.model_cached_secret import ModelCachedSecret
+from omnibase_infra.runtime.models.model_compute_key import ModelComputeKey
+from omnibase_infra.runtime.models.model_compute_registration import (
+    ModelComputeRegistration,
+)
+from omnibase_infra.runtime.models.model_config_cache_entry import ModelConfigCacheEntry
+from omnibase_infra.runtime.models.model_config_ref import ModelConfigRef
+from omnibase_infra.runtime.models.model_config_ref_parse_result import (
+    ModelConfigRefParseResult,
+)
+from omnibase_infra.runtime.models.model_domain_plugin_config import (
+    ModelDomainPluginConfig,
+)
+from omnibase_infra.runtime.models.model_domain_plugin_result import (
+    ModelDomainPluginResult,
+)
+from omnibase_infra.runtime.models.model_duplicate_response import (
+    ModelDuplicateResponse,
+)
+from omnibase_infra.runtime.models.model_enabled_protocols_config import (
+    ModelEnabledProtocolsConfig,
+)
+from omnibase_infra.runtime.models.model_event_bus_config import ModelEventBusConfig
+from omnibase_infra.runtime.models.model_failed_component import ModelFailedComponent
+from omnibase_infra.runtime.models.model_health_check_response import (
+    ModelHealthCheckResponse,
+)
+from omnibase_infra.runtime.models.model_health_check_result import (
+    ModelHealthCheckResult,
+)
+from omnibase_infra.runtime.models.model_lifecycle_result import (
+    ModelLifecycleResult,
+)
+from omnibase_infra.runtime.models.model_logging_config import ModelLoggingConfig
+from omnibase_infra.runtime.models.model_optional_correlation_id import (
+    ModelOptionalCorrelationId,
+)
+from omnibase_infra.runtime.models.model_optional_string import ModelOptionalString
+from omnibase_infra.runtime.models.model_optional_uuid import ModelOptionalUUID
+from omnibase_infra.runtime.models.model_policy_context import ModelPolicyContext
+from omnibase_infra.runtime.models.model_policy_key import ModelPolicyKey
+from omnibase_infra.runtime.models.model_policy_registration import (
+    ModelPolicyRegistration,
+)
+from omnibase_infra.runtime.models.model_policy_result import ModelPolicyResult
+from omnibase_infra.runtime.models.model_policy_type_filter import ModelPolicyTypeFilter
+from omnibase_infra.runtime.models.model_projector_plugin_loader_config import (
+    ModelProjectorPluginLoaderConfig,
+)
+from omnibase_infra.runtime.models.model_protocol_registration_config import (
+    ModelProtocolRegistrationConfig,
+)
+from omnibase_infra.runtime.models.model_retry_policy import ModelRetryPolicy
+from omnibase_infra.runtime.models.model_runtime_config import ModelRuntimeConfig
+from omnibase_infra.runtime.models.model_runtime_scheduler_config import (
+    ModelRuntimeSchedulerConfig,
+)
+from omnibase_infra.runtime.models.model_runtime_scheduler_metrics import (
+    ModelRuntimeSchedulerMetrics,
+)
+from omnibase_infra.runtime.models.model_runtime_tick import ModelRuntimeTick
+from omnibase_infra.runtime.models.model_secret_cache_stats import ModelSecretCacheStats
+from omnibase_infra.runtime.models.model_secret_mapping import ModelSecretMapping
+from omnibase_infra.runtime.models.model_secret_resolver_config import (
+    ModelSecretResolverConfig,
+)
+from omnibase_infra.runtime.models.model_secret_resolver_metrics import (
+    ModelSecretResolverMetrics,
+)
+from omnibase_infra.runtime.models.model_secret_source_info import ModelSecretSourceInfo
+from omnibase_infra.runtime.models.model_secret_source_spec import (
+    ModelSecretSourceSpec,
+    SecretSourceType,
+)
+from omnibase_infra.runtime.models.model_shutdown_batch_result import (
+    ModelShutdownBatchResult,
+)
+from omnibase_infra.runtime.models.model_shutdown_config import ModelShutdownConfig
+
+__all__: list[str] = [
+    "EnumConfigRefScheme",
+    "ModelBatchLifecycleResult",
+    "ModelBindingConfig",
+    "ModelBindingConfigCacheStats",
+    "ModelBindingConfigResolverConfig",
+    "ModelCachedSecret",
+    "ModelComputeKey",
+    "ModelComputeRegistration",
+    "ModelConfigCacheEntry",
+    "ModelConfigRef",
+    "ModelConfigRefParseResult",
+    "ModelDomainPluginConfig",
+    "ModelDomainPluginResult",
+    "ModelDuplicateResponse",
+    "ModelEnabledProtocolsConfig",
+    "ModelEventBusConfig",
+    "ModelFailedComponent",
+    "ModelHealthCheckResponse",
+    "ModelHealthCheckResult",
+    "ModelLifecycleResult",
+    "ModelLoggingConfig",
+    "ModelOptionalCorrelationId",
+    "ModelOptionalString",
+    "ModelOptionalUUID",
+    "ModelPolicyContext",
+    "ModelPolicyKey",
+    "ModelPolicyRegistration",
+    "ModelPolicyResult",
+    "ModelPolicyTypeFilter",
+    "ModelProjectorPluginLoaderConfig",
+    "ModelProtocolRegistrationConfig",
+    "ModelRetryPolicy",
+    "ModelRuntimeConfig",
+    "ModelRuntimeSchedulerConfig",
+    "ModelRuntimeSchedulerMetrics",
+    "ModelRuntimeTick",
+    "ModelSecretCacheStats",
+    "ModelSecretMapping",
+    "ModelSecretResolverConfig",
+    "ModelSecretResolverMetrics",
+    "ModelSecretSourceInfo",
+    "ModelSecretSourceSpec",
+    "ModelShutdownBatchResult",
+    "ModelShutdownConfig",
+    "SecretSourceType",
+]

omnibase_infra/runtime/models/model_batch_lifecycle_result.py

@@ -0,0 +1,217 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Batch Lifecycle Result Model for handler batch shutdown operations.
+
+This module provides the ModelBatchLifecycleResult class for representing the
+aggregate outcome of batch handler lifecycle operations (e.g., shutdown_handlers_by_priority).
+
+Design Pattern:
+    ModelBatchLifecycleResult replaces tuple[list[str], list[tuple[str, str | None]]]
+    returns with a strongly-typed model that provides:
+    - Clear separation of succeeded and failed results
+    - Convenient helper methods for common queries
+    - Full traceability via ModelLifecycleResult for each handler
+
+Thread Safety:
+    ModelBatchLifecycleResult is immutable (frozen=True) after creation,
+    making it thread-safe for concurrent read access.
+
+Example:
+    >>> from omnibase_infra.runtime.models import (
+    ...     ModelBatchLifecycleResult,
+    ...     ModelLifecycleResult,
+    ... )
+    >>>
+    >>> # Create batch result from individual results
+    >>> results = [
+    ...     ModelLifecycleResult.succeeded("kafka"),
+    ...     ModelLifecycleResult.succeeded("consul"),
+    ...     ModelLifecycleResult.failed("db", "Timeout"),
+    ... ]
+    >>> batch = ModelBatchLifecycleResult.from_results(results)
+    >>> batch.total_count
+    3
+    >>> batch.success_count
+    2
+    >>> batch.failure_count
+    1
+    >>> batch.all_succeeded
+    False
+"""
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from omnibase_infra.runtime.models.model_lifecycle_result import ModelLifecycleResult
+
+
+class ModelBatchLifecycleResult(BaseModel):
+    """Result of a batch handler lifecycle operation (e.g., shutdown_handlers_by_priority).
+
+    Provides a strongly-typed replacement for tuple[list[str], list[tuple[str, str | None]]]
+    with clear separation of succeeded/failed handlers and helper methods.
+
+    Attributes:
+        results: List of all lifecycle results (both successes and failures).
+        succeeded_handlers: List of handler types that completed successfully.
+        failed_handlers: List of ModelLifecycleResult for handlers that failed.
+
+    Example:
+        >>> batch = ModelBatchLifecycleResult(
+        ...     results=[
+        ...         ModelLifecycleResult.succeeded("kafka"),
+        ...         ModelLifecycleResult.failed("db", "Timeout"),
+        ...     ],
+        ...     succeeded_handlers=["kafka"],
+        ...     failed_handlers=[ModelLifecycleResult.failed("db", "Timeout")],
+        ... )
+        >>> batch.has_failures
+        True
+        >>> batch.success_count
+        1
+    """
+
+    model_config = ConfigDict(
+        strict=True,
+        frozen=True,
+        extra="forbid",
+        from_attributes=True,
+    )
+
+    results: list[ModelLifecycleResult] = Field(
+        default_factory=list,
+        description="All lifecycle results in execution order.",
+    )
+    succeeded_handlers: list[str] = Field(
+        default_factory=list,
+        description="Handler types that completed successfully.",
+    )
+    failed_handlers: list[ModelLifecycleResult] = Field(
+        default_factory=list,
+        description="Lifecycle results for handlers that failed.",
+    )
+
+    @classmethod
+    def from_results(
+        cls, results: list[ModelLifecycleResult]
+    ) -> "ModelBatchLifecycleResult":
+        """Create a batch result from a list of individual lifecycle results.
+
+        Automatically separates succeeded and failed handlers.
+
+        Args:
+            results: List of individual ModelLifecycleResult instances.
+
+        Returns:
+            ModelBatchLifecycleResult with succeeded/failed handlers categorized.
+
+        Example:
+            >>> results = [
+            ...     ModelLifecycleResult.succeeded("kafka"),
+            ...     ModelLifecycleResult.failed("db", "Error"),
+            ... ]
+            >>> batch = ModelBatchLifecycleResult.from_results(results)
+            >>> batch.succeeded_handlers
+            ['kafka']
+        """
+        succeeded = [r.handler_type for r in results if r.success]
+        failed = [r for r in results if not r.success]
+        return cls(
+            results=results,
+            succeeded_handlers=succeeded,
+            failed_handlers=failed,
+        )
+
+    @classmethod
+    def empty(cls) -> "ModelBatchLifecycleResult":
+        """Create an empty batch result (no handlers processed).
+
+        Returns:
+            Empty ModelBatchLifecycleResult.
+
+        Example:
+            >>> batch = ModelBatchLifecycleResult.empty()
+            >>> batch.total_count
+            0
+        """
+        return cls(results=[], succeeded_handlers=[], failed_handlers=[])
+
+    @property
+    def total_count(self) -> int:
+        """Return total number of handlers processed.
+
+        Returns:
+            Count of all handlers (succeeded + failed).
+        """
+        return len(self.results)
+
+    @property
+    def success_count(self) -> int:
+        """Return number of handlers that succeeded.
+
+        Returns:
+            Count of successfully completed handlers.
+        """
+        return len(self.succeeded_handlers)
+
+    @property
+    def failure_count(self) -> int:
+        """Return number of handlers that failed.
+
+        Returns:
+            Count of failed handlers.
+        """
+        return len(self.failed_handlers)
+
+    @property
+    def all_succeeded(self) -> bool:
+        """Check if all handlers completed successfully.
+
+        Returns:
+            True if no failures occurred, False otherwise.
+        """
+        return len(self.failed_handlers) == 0 and len(self.results) > 0
+
+    @property
+    def has_failures(self) -> bool:
+        """Check if any handlers failed.
+
+        Returns:
+            True if at least one handler failed, False otherwise.
+        """
+        return len(self.failed_handlers) > 0
+
+    def get_failure_messages(self) -> dict[str, str]:
+        """Get a mapping of failed handler types to their error messages.
+
+        Note:
+            All failed handlers have non-empty error messages since
+            ModelLifecycleResult.failed() requires a non-empty error_message.
+
+        Returns:
+            Dict mapping handler_type to error_message for all failures.
+
+        Example:
+            >>> batch = ModelBatchLifecycleResult.from_results([
+            ...     ModelLifecycleResult.failed("db", "Timeout"),
+            ...     ModelLifecycleResult.failed("cache", "Connection refused"),
+            ... ])
+            >>> batch.get_failure_messages()
+            {'db': 'Timeout', 'cache': 'Connection refused'}
+        """
+        return {r.handler_type: r.error_message for r in self.failed_handlers}
+
+    def __str__(self) -> str:
+        """Return a human-readable string representation for debugging.
+
+        Returns:
+            String format showing succeeded and failed counts.
+        """
+        return (
+            f"ModelBatchLifecycleResult("
+            f"total={self.total_count}, "
+            f"succeeded={self.success_count}, "
+            f"failed={self.failure_count})"
+        )
+
+
+__all__ = ["ModelBatchLifecycleResult"]

omnibase_infra/runtime/models/model_binding_config.py

@@ -0,0 +1,168 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Binding configuration model for BindingConfigResolver.
+
+.. versionadded:: 0.8.0
+    Initial implementation for OMN-765.
+
+This module provides the configuration model for handler bindings used
+by BindingConfigResolver.
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+from omnibase_core.types import JsonType
+from omnibase_infra.runtime.models.model_retry_policy import ModelRetryPolicy
+
+
+class ModelBindingConfig(BaseModel):
+    """Configuration for binding a handler to the runtime.
+
+    Defines how a specific handler is configured, including its operational
+    parameters, retry behavior, and optional external configuration references.
+
+    Attributes:
+        handler_type: Handler type identifier (e.g., "vault", "db", "consul").
+            Used for handler discovery and routing.
+        name: Optional display name for the handler. Defaults to handler_type
+            if not specified.
+        enabled: Whether the handler is active. Disabled handlers are not loaded.
+        priority: Execution priority for handler ordering. Higher values execute
+            first. Use negative values to ensure late execution.
+        config_ref: Reference to external configuration. Supported schemes:
+            - "file:configs/handler.yaml" - File path (preferred format)
+            - "file:/absolute/path/config.yaml" - Absolute file path
+            - "env:CONFIG_VAR" - Load from environment variable
+            - "vault:secret/data/path" - Load from Vault secret
+            - "vault:secret/data/path#field" - Load specific field from Vault secret
+            Note: file:// prefix is also supported for backwards compatibility.
+        config: Inline configuration dictionary. If both config_ref and config
+            are provided, config takes precedence for overlapping keys.
+        retry_policy: Retry configuration for transient failures.
+        timeout_ms: Operation timeout in milliseconds. Applies to individual
+            handler operations, not total request time.
+        rate_limit_per_second: Maximum operations per second. None means no limit.
+
+    Example:
+        >>> config = ModelBindingConfig(
+        ...     handler_type="db",
+        ...     name="primary-postgres",
+        ...     priority=10,
+        ...     timeout_ms=5000,
+        ...     retry_policy=ModelRetryPolicy(max_retries=5),
+        ...     rate_limit_per_second=100.0,
+        ... )
+    """
+
+    model_config = ConfigDict(
+        strict=True,
+        frozen=True,
+        extra="forbid",
+        from_attributes=True,
+    )
+
+    handler_type: str = Field(
+        ...,
+        min_length=1,
+        max_length=64,
+        description="Handler type identifier (e.g., 'vault', 'db', 'consul'). "
+        "Must be non-empty and match a registered handler implementation.",
+    )
+
+    name: str | None = Field(
+        default=None,
+        min_length=1,
+        max_length=128,
+        description="Optional display name for the handler. "
+        "Defaults to handler_type if not specified.",
+    )
+
+    enabled: bool = Field(
+        default=True,
+        description="Whether this handler binding is active. "
+        "Disabled handlers are skipped during runtime initialization.",
+    )
+
+    priority: int = Field(
+        default=0,
+        ge=-100,
+        le=100,
+        description="Execution priority for handler ordering (-100 to 100). "
+        "Higher values execute first. Use 0 for default ordering.",
+    )
+
+    config_ref: str | None = Field(
+        default=None,
+        min_length=1,
+        max_length=512,
+        description="Reference to external configuration. "
+        "Supported schemes: file: (including file://), env:, vault:",
+    )
+
+    config: dict[str, JsonType] | None = Field(
+        default=None,
+        description="Inline configuration dictionary. "
+        "Takes precedence over config_ref for overlapping keys.",
+    )
+
+    retry_policy: ModelRetryPolicy | None = Field(
+        default=None,
+        description="Retry configuration for transient failures. "
+        "If not specified, handler uses its default retry behavior.",
+    )
+
+    timeout_ms: int = Field(
+        default=30000,
+        ge=100,
+        le=600000,
+        description="Operation timeout in milliseconds (100-600000). "
+        "Default 30s; max 10min for long-running operations.",
+    )
+
+    rate_limit_per_second: float | None = Field(
+        default=None,
+        ge=0.1,
+        le=10000.0,
+        description="Maximum operations per second (0.1-10000). "
+        "None means no rate limiting.",
+    )
+
+    @field_validator("config_ref")
+    @classmethod
+    def validate_config_ref_scheme(cls, v: str | None) -> str | None:
+        """Validate that config_ref uses a supported scheme.
+
+        Args:
+            v: The config_ref value to validate.
+
+        Returns:
+            The validated config_ref value.
+
+        Raises:
+            ValueError: If config_ref uses an unsupported scheme.
+        """
+        if v is None:
+            return v
+
+        # Use "file:" to accept both "file://path" and shorthand "file:path" formats
+        supported_schemes = ("file:", "env:", "vault:")
+        if not any(v.startswith(scheme) for scheme in supported_schemes):
+            raise ValueError(
+                f"config_ref must start with one of {supported_schemes}, got: {v!r}"
+            )
+        return v
+
+    def get_effective_name(self) -> str:
+        """Get the effective name for this handler binding.
+
+        Returns:
+            The name field if set, otherwise the handler_type.
+        """
+        return self.name if self.name is not None else self.handler_type
+
+
+__all__: list[str] = [
+    "ModelBindingConfig",
+]