omnibase_infra 0.2.1__py3-none-any.whl

omnibase_infra/models/resilience/model_circuit_breaker_config.py

@@ -0,0 +1,227 @@
+# Copyright 2025 OmniNode Team. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+"""Configuration model for circuit breaker initialization.
+
+Environment Variable Support:
+    This model supports creation from environment variables via the from_env()
+    class method. This enables runtime configuration of circuit breaker thresholds
+    without code changes.
+
+    Environment Variables:
+        {prefix}_THRESHOLD: Maximum consecutive failures before opening circuit (default: 5)
+        {prefix}_RESET_TIMEOUT: Seconds before auto-reset to half-open (default: 60.0)
+
+    Default prefix is "ONEX_CB", so variables would be:
+        ONEX_CB_THRESHOLD=5
+        ONEX_CB_RESET_TIMEOUT=60.0
+
+This module provides the configuration model used to initialize the
+MixinAsyncCircuitBreaker mixin. Grouping parameters into a configuration
+model follows ONEX patterns for reducing function parameter count and
+union patterns.
+
+Circuit Breaker Overview:
+    The circuit breaker pattern prevents cascading failures in distributed systems
+    by temporarily blocking requests to a failing service. It operates in three states:
+    - CLOSED: Normal operation, requests allowed
+    - OPEN: Circuit tripped after threshold failures, requests blocked
+    - HALF_OPEN: Testing recovery after reset timeout, limited requests allowed
+
+See Also:
+    - MixinAsyncCircuitBreaker: The mixin that uses this configuration
+    - docs/patterns/circuit_breaker_implementation.md: Implementation details
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from omnibase_infra.enums import EnumInfraTransportType
+from omnibase_infra.utils.util_env_parsing import parse_env_float, parse_env_int
+
+
+class ModelCircuitBreakerConfig(BaseModel):
+    """Configuration model for circuit breaker initialization.
+
+    This model groups all parameters required by ``_init_circuit_breaker()``
+    into a single configuration object, following ONEX conventions for functions
+    with more than 5 parameters and reducing union type patterns.
+
+    Attributes:
+        threshold: Maximum number of consecutive failures before opening the
+            circuit. Must be >= 1. Default: 5.
+        reset_timeout_seconds: Time in seconds before the circuit automatically
+            transitions from OPEN to HALF_OPEN for recovery testing.
+            Must be >= 0. Default: 60.0.
+        service_name: Identifier for the service being protected. Used in error
+            context and logging. Default: "unknown".
+        transport_type: Transport type for error context classification.
+            Determines which error code is used when the circuit opens.
+            Default: HTTP.
+
+    Example:
+        ```python
+        from omnibase_infra.models.resilience import ModelCircuitBreakerConfig
+        from omnibase_infra.mixins import MixinAsyncCircuitBreaker
+        from omnibase_infra.enums import EnumInfraTransportType
+
+        class EventBusKafka(MixinAsyncCircuitBreaker):
+            def __init__(self, environment: str):
+                config = ModelCircuitBreakerConfig(
+                    threshold=5,
+                    reset_timeout_seconds=60.0,
+                    service_name=f"kafka.{environment}",
+                    transport_type=EnumInfraTransportType.KAFKA,
+                )
+                self._init_circuit_breaker_from_config(config)
+
+        # With defaults
+        class HttpClient(MixinAsyncCircuitBreaker):
+            def __init__(self, service_name: str):
+                config = ModelCircuitBreakerConfig(service_name=service_name)
+                self._init_circuit_breaker_from_config(config)
+        ```
+
+    Configuration Guidelines:
+        - High-reliability services: Use lower threshold (3) and longer timeout (120s)
+        - Best-effort services: Use higher threshold (10) and shorter timeout (30s)
+        - Tune based on service SLAs and failure characteristics
+
+    See Also:
+        MixinAsyncCircuitBreaker: The mixin that uses this configuration.
+    """
+
+    threshold: int = Field(
+        default=5,
+        ge=1,
+        description="Maximum consecutive failures before opening the circuit",
+    )
+
+    reset_timeout_seconds: float = Field(
+        default=60.0,
+        ge=0.0,
+        description="Seconds before automatic transition from OPEN to HALF_OPEN",
+    )
+
+    service_name: str = Field(
+        default="unknown",
+        min_length=1,
+        description="Service identifier for error context and logging",
+    )
+
+    transport_type: EnumInfraTransportType = Field(
+        default=EnumInfraTransportType.HTTP,
+        description="Transport type for error context classification",
+    )
+
+    model_config = ConfigDict(
+        frozen=True,
+        extra="forbid",
+        json_schema_extra={
+            "examples": [
+                {
+                    "threshold": 5,
+                    "reset_timeout_seconds": 60.0,
+                    "service_name": "kafka.production",
+                    "transport_type": "kafka",
+                },
+                {
+                    "threshold": 3,
+                    "reset_timeout_seconds": 120.0,
+                    "service_name": "postgresql-primary",
+                    "transport_type": "db",
+                },
+            ]
+        },
+    )
+
+    @classmethod
+    def from_env(
+        cls,
+        service_name: str = "unknown",
+        transport_type: EnumInfraTransportType = EnumInfraTransportType.HTTP,
+        prefix: str = "ONEX_CB",
+    ) -> ModelCircuitBreakerConfig:
+        """Create configuration from environment variables.
+
+        Reads circuit breaker settings from environment variables, falling back
+        to defaults if not set. This enables runtime configuration without
+        code changes.
+
+        Environment Variables:
+            {prefix}_THRESHOLD: Maximum consecutive failures before opening circuit.
+                Must be >= 1 and <= 1000. Default: 5.
+            {prefix}_RESET_TIMEOUT: Seconds before auto-reset from OPEN to HALF_OPEN.
+                Must be >= 0 and <= 3600 (1 hour). Default: 60.0.
+
+        Args:
+            service_name: Service identifier for error context and logging.
+                This is NOT read from environment - must be provided by caller.
+            transport_type: Transport type for error context classification.
+                This is NOT read from environment - must be provided by caller.
+            prefix: Environment variable prefix. Default: "ONEX_CB".
+                Override to create service-specific configurations.
+
+        Returns:
+            ModelCircuitBreakerConfig with values from environment or defaults.
+
+        Raises:
+            ProtocolConfigurationError: If environment variable values cannot be
+                parsed as int (threshold) or float (reset_timeout). The error
+                includes ModelInfraErrorContext with transport_type and service_name.
+
+        Example:
+            ```python
+            # With default prefix (reads ONEX_CB_THRESHOLD, ONEX_CB_RESET_TIMEOUT)
+            config = ModelCircuitBreakerConfig.from_env(
+                service_name="kafka.production",
+                transport_type=EnumInfraTransportType.KAFKA,
+            )
+
+            # With custom prefix (reads KAFKA_CB_THRESHOLD, KAFKA_CB_RESET_TIMEOUT)
+            config = ModelCircuitBreakerConfig.from_env(
+                service_name="kafka.production",
+                transport_type=EnumInfraTransportType.KAFKA,
+                prefix="KAFKA_CB",
+            )
+
+            # Use with circuit breaker mixin
+            self._init_circuit_breaker_from_config(config)
+            ```
+
+        Note:
+            The service_name and transport_type are not read from environment
+            because they are context-specific and should be provided by the
+            calling code. Only the numeric thresholds are configurable via
+            environment to allow tuning without identifying which service
+            each variable affects.
+        """
+        threshold_var = f"{prefix}_THRESHOLD"
+        reset_timeout_var = f"{prefix}_RESET_TIMEOUT"
+
+        threshold = parse_env_int(
+            threshold_var,
+            5,
+            min_value=1,
+            max_value=1000,
+            transport_type=transport_type,
+            service_name=service_name,
+        )
+        reset_timeout = parse_env_float(
+            reset_timeout_var,
+            60.0,
+            min_value=0.0,
+            max_value=3600.0,
+            transport_type=transport_type,
+            service_name=service_name,
+        )
+
+        return cls(
+            threshold=threshold,
+            reset_timeout_seconds=reset_timeout,
+            service_name=service_name,
+            transport_type=transport_type,
+        )
+
+
+__all__ = ["ModelCircuitBreakerConfig"]

omnibase_infra/models/routing/__init__.py

@@ -0,0 +1,25 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Routing models for declarative orchestrator configuration.
+
+These models define the structure for routing configuration
+loaded from contract.yaml files. They enable declarative mapping of
+event models to handler implementations.
+
+Note:
+    These models are local to omnibase_infra as they support infrastructure-
+    specific routing patterns. They may be promoted to omnibase_core
+    in the future if they become part of the standard ONEX contract schema.
+"""
+
+from omnibase_infra.models.routing.model_routing_entry import (
+    ModelRoutingEntry,
+)
+from omnibase_infra.models.routing.model_routing_subcontract import (
+    ModelRoutingSubcontract,
+)
+
+__all__ = [
+    "ModelRoutingEntry",
+    "ModelRoutingSubcontract",
+]

omnibase_infra/models/routing/model_routing_entry.py

@@ -0,0 +1,52 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Handler routing entry model for event-to-handler mapping.
+
+This model represents a single routing entry that maps an event model
+(identified by routing_key) to a handler (identified by handler_key).
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, Field
+
+
+class ModelRoutingEntry(BaseModel):
+    """Single entry mapping an event model to a handler.
+
+    Attributes:
+        routing_key: The event model name used for routing (e.g.,
+            "ModelNodeIntrospectionEvent"). This matches against
+            incoming event payloads.
+        handler_key: The handler's adapter ID in ServiceHandlerRegistry
+            (e.g., "handler-node-introspected"). This is the kebab-case
+            identifier used to look up the handler.
+
+    Example:
+        ```python
+        entry = ModelRoutingEntry(
+            routing_key="ModelNodeIntrospectionEvent",
+            handler_key="handler-node-introspected",
+        )
+        ```
+
+    Note:
+        The handler_key is NOT the class name - it's the kebab-case
+        adapter ID. Use _convert_class_to_handler_key() to convert
+        from class names like "HandlerNodeIntrospected" to handler
+        keys like "handler-node-introspected".
+    """
+
+    routing_key: str = Field(
+        ...,
+        description="Event model name used for routing (e.g., 'ModelNodeIntrospectionEvent')",
+    )
+    handler_key: str = Field(
+        ...,
+        description="Handler adapter ID in kebab-case (e.g., 'handler-node-introspected')",
+    )
+
+    model_config = {"frozen": True}
+
+
+__all__ = ["ModelRoutingEntry"]

omnibase_infra/models/routing/model_routing_subcontract.py

@@ -0,0 +1,70 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Routing subcontract model for orchestrator configuration.
+
+This model represents the complete routing configuration
+for an orchestrator, including all routing entries and strategy.
+"""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import BaseModel, Field
+
+from omnibase_core.models.primitives.model_semver import ModelSemVer
+from omnibase_infra.models.routing.model_routing_entry import (
+    ModelRoutingEntry,
+)
+
+
+class ModelRoutingSubcontract(BaseModel):
+    """Complete routing configuration for an orchestrator.
+
+    This subcontract defines how incoming events are routed to handlers.
+    It is loaded from the handler_routing section of contract.yaml.
+
+    Attributes:
+        version: Semantic version of this routing configuration.
+        routing_strategy: Strategy for matching events to handlers.
+            Currently only "payload_type_match" is supported.
+        handlers: List of routing entries mapping event models to handlers.
+        default_handler: Optional fallback handler key for unmatched events.
+
+    Example:
+        ```python
+        subcontract = ModelRoutingSubcontract(
+            version=ModelSemVer(major=1, minor=0, patch=0),
+            routing_strategy="payload_type_match",
+            handlers=[
+                ModelRoutingEntry(
+                    routing_key="ModelNodeIntrospectionEvent",
+                    handler_key="handler-node-introspected",
+                ),
+            ],
+            default_handler=None,
+        )
+        ```
+    """
+
+    version: ModelSemVer = Field(
+        default_factory=lambda: ModelSemVer(major=1, minor=0, patch=0),
+        description="Semantic version of this routing configuration",
+    )
+    routing_strategy: Literal["payload_type_match"] = Field(
+        default="payload_type_match",
+        description="Strategy for matching events to handlers",
+    )
+    handlers: list[ModelRoutingEntry] = Field(
+        default_factory=list,
+        description="List of routing entries mapping event models to handlers",
+    )
+    default_handler: str | None = Field(
+        default=None,
+        description="Optional fallback handler key for unmatched events",
+    )
+
+    model_config = {"frozen": True}
+
+
+__all__ = ["ModelRoutingSubcontract"]

omnibase_infra/models/runtime/__init__.py

@@ -0,0 +1,40 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Runtime Models for Plugin Loading.
+
+This module exports runtime-specific models used by the Plugin Loader
+and related runtime components.
+
+.. versionadded:: 0.7.0
+    Created as part of OMN-1132 Plugin Loader implementation.
+"""
+
+from omnibase_infra.models.runtime.model_contract_security_config import (
+    ModelContractSecurityConfig,
+)
+from omnibase_infra.models.runtime.model_discovery_error import ModelDiscoveryError
+from omnibase_infra.models.runtime.model_discovery_result import ModelDiscoveryResult
+from omnibase_infra.models.runtime.model_discovery_warning import ModelDiscoveryWarning
+from omnibase_infra.models.runtime.model_failed_plugin_load import (
+    ModelFailedPluginLoad,
+)
+from omnibase_infra.models.runtime.model_handler_contract import ModelHandlerContract
+from omnibase_infra.models.runtime.model_loaded_handler import ModelLoadedHandler
+from omnibase_infra.models.runtime.model_plugin_load_context import (
+    ModelPluginLoadContext,
+)
+from omnibase_infra.models.runtime.model_plugin_load_summary import (
+    ModelPluginLoadSummary,
+)
+
+__all__ = [
+    "ModelContractSecurityConfig",
+    "ModelDiscoveryError",
+    "ModelDiscoveryResult",
+    "ModelDiscoveryWarning",
+    "ModelFailedPluginLoad",
+    "ModelHandlerContract",
+    "ModelLoadedHandler",
+    "ModelPluginLoadContext",
+    "ModelPluginLoadSummary",
+]

omnibase_infra/models/runtime/model_contract_security_config.py

@@ -0,0 +1,41 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Contract Security Configuration Model.
+
+This module provides ModelContractSecurityConfig, a Pydantic model for
+security configuration in handler contracts.
+
+.. versionadded:: 0.7.0
+    Created as part of OMN-1317 to fix one-model-per-file violation.
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class ModelContractSecurityConfig(BaseModel):
+    """Security configuration for handler contracts.
+
+    Optional security metadata that can be specified in handler contracts
+    for security-sensitive handlers.
+
+    Attributes:
+        trusted_namespace: Expected namespace prefix for handler class.
+            If set, loader should verify handler_class starts with this prefix.
+        audit_logging: Whether audit logging is enabled for this handler.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    trusted_namespace: str | None = Field(
+        default=None,
+        description="Expected namespace prefix for handler class validation",
+    )
+    audit_logging: bool = Field(
+        default=False,
+        description="Whether audit logging is enabled for this handler",
+    )
+
+
+__all__ = ["ModelContractSecurityConfig"]

omnibase_infra/models/runtime/model_discovery_error.py

@@ -0,0 +1,81 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Discovery Error Model for Handler Discovery Operations.
+
+This module provides the ModelDiscoveryError model for tracking errors
+encountered during handler discovery operations.
+
+See Also:
+    - ModelDiscoveryResult: Aggregate discovery results
+    - ModelDiscoveryWarning: Non-fatal warnings
+
+.. versionadded:: 0.7.0
+    Created as part of OMN-1133 contract-based handler discovery.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class ModelDiscoveryError(BaseModel):
+    """Represents an error encountered during handler discovery.
+
+    Captures detailed information about a discovery failure including the
+    structured error code, human-readable message, and context about which
+    contract or handler caused the error.
+
+    Attributes:
+        error_code: Structured error code (e.g., "MODULE_NOT_FOUND", "CLASS_NOT_FOUND").
+        message: Human-readable error description.
+        contract_path: Path to the contract file that caused the error, if applicable.
+        handler_name: Name of the handler that caused the error, if applicable.
+        details: Additional structured details about the error.
+
+    Example:
+        >>> from pathlib import Path
+        >>> error = ModelDiscoveryError(
+        ...     error_code="MODULE_NOT_FOUND",
+        ...     message="Could not find module 'myapp.handlers.auth'",
+        ...     contract_path=Path("/app/handlers/auth/contract.yaml"),
+        ...     handler_name="HandlerAuth",
+        ... )
+        >>> error.error_code
+        'MODULE_NOT_FOUND'
+
+    .. versionadded:: 0.7.0
+    """
+
+    model_config = ConfigDict(
+        frozen=True,
+        extra="forbid",
+        strict=True,
+    )
+
+    error_code: str = Field(
+        ...,
+        min_length=1,
+        description="Structured error code (e.g., MODULE_NOT_FOUND, CLASS_NOT_FOUND)",
+    )
+    message: str = Field(
+        ...,
+        min_length=1,
+        description="Human-readable error description",
+    )
+    contract_path: Path | None = Field(
+        default=None,
+        description="Path to the contract file that caused the error",
+    )
+    handler_name: str | None = Field(
+        default=None,
+        description="Name of the handler that caused the error",
+    )
+    details: dict[str, object] | None = Field(
+        default=None,
+        description="Additional structured details about the error",
+    )
+
+
+__all__ = ["ModelDiscoveryError"]