omnibase_infra 0.2.6__py3-none-any.whl

omnibase_infra/models/registry/model_message_type_entry.py

@@ -0,0 +1,271 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""
+Message Type Entry Model.
+
+Defines the registry entry for message type to handler mappings in the
+Central Message Type Registry.
+
+Design Principles:
+    - Each entry maps a message type to one or more handler implementations
+    - Topic category constraints define where message types can appear
+    - Domain ownership is tracked for cross-domain validation
+    - Immutable entries for thread-safe concurrent access
+
+Related:
+    - OMN-937: Central Message Type Registry implementation
+    - ModelDomainConstraint: Domain ownership rules
+    - RegistryMessageType: Uses entries for handler resolution
+
+.. versionadded:: 0.5.0
+"""
+
+from datetime import datetime
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+from omnibase_infra.enums import EnumMessageCategory
+from omnibase_infra.models.registry.model_domain_constraint import (
+    ModelDomainConstraint,
+)
+from omnibase_infra.models.validation import ModelValidationOutcome
+
+
+class ModelMessageTypeEntry(BaseModel):
+    """
+    Registry entry mapping a message type to handler(s) with constraints.
+
+    Each entry represents a message type registration in the Central Message Type
+    Registry. It defines which handlers process the message type, what categories
+    are allowed, and domain ownership constraints.
+
+    Attributes:
+        message_type: The fully-qualified message type name.
+            Example: "UserCreated", "CreateOrderCommand", "CheckoutIntent"
+        handler_ids: List of handler IDs that can process this message type.
+            Supports fan-out pattern with multiple handlers per type.
+        allowed_categories: Message categories where this type can appear.
+            Example: [EVENT] for domain events, [COMMAND] for commands.
+        domain_constraint: Domain ownership and cross-domain rules.
+        description: Human-readable description of the message type.
+        enabled: Whether this entry is active. Disabled entries are skipped.
+        registered_at: Timestamp when this entry was registered.
+
+    Fan-Out Support:
+        Multiple handler_ids can be registered for the same message type to enable
+        fan-out processing patterns. Each registered handler will receive the
+        message independently.
+
+    Example:
+        >>> entry = ModelMessageTypeEntry(
+        ...     message_type="UserCreated",
+        ...     handler_ids=["user-event-handler", "audit-logger"],
+        ...     allowed_categories=[EnumMessageCategory.EVENT],
+        ...     domain_constraint=ModelDomainConstraint(owning_domain="user"),
+        ...     description="User creation event",
+        ... )
+        >>> entry.supports_category(EnumMessageCategory.EVENT)
+        True
+        >>> entry.supports_category(EnumMessageCategory.COMMAND)
+        False
+
+    Thread Safety:
+        This model is immutable (frozen=True) and thread-safe for concurrent access.
+
+    .. versionadded:: 0.5.0
+    """
+
+    model_config = ConfigDict(
+        frozen=True,
+        extra="forbid",
+        from_attributes=True,
+    )
+
+    # ---- Message Type Identity ----
+    message_type: str = Field(
+        ...,
+        description="The fully-qualified message type name.",
+        min_length=1,
+        max_length=200,
+    )
+
+    # ---- Handler Mapping ----
+    handler_ids: tuple[str, ...] = Field(
+        ...,
+        description=(
+            "Handler IDs that can process this message type. "
+            "Tuple for immutability and fan-out support."
+        ),
+        min_length=1,
+    )
+
+    # ---- Category Constraints ----
+    allowed_categories: frozenset[EnumMessageCategory] = Field(
+        ...,
+        description=(
+            "Message categories where this type can appear. Frozenset for immutability."
+        ),
+    )
+
+    @field_validator("allowed_categories")
+    @classmethod
+    def validate_allowed_categories_not_empty(
+        cls, value: frozenset[EnumMessageCategory]
+    ) -> frozenset[EnumMessageCategory]:
+        """Validate that allowed_categories contains at least one category.
+
+        A message type with no allowed categories is invalid because it can
+        never be routed - there is no valid topic category where it could appear.
+
+        Args:
+            value: The frozenset of allowed categories.
+
+        Returns:
+            The validated frozenset.
+
+        Raises:
+            ValueError: If the frozenset is empty.
+        """
+        if not value:
+            msg = (
+                "allowed_categories cannot be empty. "
+                "A message type must be allowed in at least one category "
+                "(EVENT, COMMAND, or INTENT) to be routable."
+            )
+            raise ValueError(msg)
+        return value
+
+    # ---- Domain Constraints ----
+    domain_constraint: ModelDomainConstraint = Field(
+        ...,
+        description="Domain ownership and cross-domain consumption rules.",
+    )
+
+    # ---- Metadata ----
+    description: str | None = Field(
+        default=None,
+        description="Human-readable description of the message type.",
+        max_length=500,
+    )
+
+    enabled: bool = Field(
+        default=True,
+        description="Whether this entry is active. Disabled entries are skipped.",
+    )
+
+    # Timestamps - MUST be explicitly injected (no default_factory for testability)
+    registered_at: datetime = Field(
+        ...,
+        description="Timestamp when this entry was registered (UTC, must be explicitly provided).",
+    )
+
+    def supports_category(self, category: EnumMessageCategory) -> bool:
+        """
+        Check if this message type is allowed in the given category.
+
+        Args:
+            category: The message category to check.
+
+        Returns:
+            True if the message type can appear in this category, False otherwise.
+
+        Example:
+            >>> entry = ModelMessageTypeEntry(
+            ...     message_type="UserCreated",
+            ...     handler_ids=("handler-1",),
+            ...     allowed_categories=frozenset([EnumMessageCategory.EVENT]),
+            ...     domain_constraint=ModelDomainConstraint(owning_domain="user"),
+            ... )
+            >>> entry.supports_category(EnumMessageCategory.EVENT)
+            True
+
+        .. versionadded:: 0.5.0
+        """
+        return category in self.allowed_categories
+
+    def validate_category(
+        self,
+        topic_category: EnumMessageCategory,
+    ) -> ModelValidationOutcome:
+        """
+        Validate if the message type can appear in the given topic category.
+
+        Args:
+            topic_category: The category inferred from the topic.
+
+        Returns:
+            ModelValidationOutcome with is_valid=True if valid,
+            or is_valid=False with error_message if invalid.
+
+        Example:
+            >>> entry = ModelMessageTypeEntry(
+            ...     message_type="UserCreated",
+            ...     handler_ids=("handler-1",),
+            ...     allowed_categories=frozenset([EnumMessageCategory.EVENT]),
+            ...     domain_constraint=ModelDomainConstraint(owning_domain="user"),
+            ... )
+            >>> outcome = entry.validate_category(EnumMessageCategory.COMMAND)
+            >>> outcome.is_valid
+            False
+
+        .. versionadded:: 0.5.0
+        .. versionchanged:: 0.6.0
+            Return type changed from tuple[bool, str | None] to ModelValidationOutcome.
+        """
+        if self.supports_category(topic_category):
+            return ModelValidationOutcome.success()
+
+        allowed_str = ", ".join(sorted(c.value for c in self.allowed_categories))
+        return ModelValidationOutcome.failure(
+            f"Message type '{self.message_type}' is not allowed in category "
+            f"'{topic_category.value}'. Allowed categories: [{allowed_str}]."
+        )
+
+    def with_additional_handler(self, handler_id: str) -> "ModelMessageTypeEntry":
+        """
+        Create a new entry with an additional handler ID.
+
+        Used for fan-out registration where multiple handlers process
+        the same message type.
+
+        Args:
+            handler_id: The handler ID to add.
+
+        Returns:
+            New ModelMessageTypeEntry with the additional handler.
+
+        Example:
+            >>> entry = ModelMessageTypeEntry(
+            ...     message_type="UserCreated",
+            ...     handler_ids=("handler-1",),
+            ...     allowed_categories=frozenset([EnumMessageCategory.EVENT]),
+            ...     domain_constraint=ModelDomainConstraint(owning_domain="user"),
+            ... )
+            >>> updated = entry.with_additional_handler("handler-2")
+            >>> updated.handler_ids
+            ('handler-1', 'handler-2')
+
+        .. versionadded:: 0.5.0
+        """
+        if handler_id in self.handler_ids:
+            return self
+
+        new_handlers = tuple(list(self.handler_ids) + [handler_id])
+        return self.model_copy(update={"handler_ids": new_handlers})
+
+    def with_enabled(self, enabled: bool) -> "ModelMessageTypeEntry":
+        """
+        Create a new entry with updated enabled status.
+
+        Args:
+            enabled: The new enabled status.
+
+        Returns:
+            New ModelMessageTypeEntry with updated status.
+
+        .. versionadded:: 0.5.0
+        """
+        return self.model_copy(update={"enabled": enabled})
+
+
+__all__ = ["ModelMessageTypeEntry"]

omnibase_infra/models/resilience/__init__.py

@@ -0,0 +1,9 @@
+"""Resilience models for infrastructure fault tolerance."""
+
+from omnibase_infra.models.resilience.model_circuit_breaker_config import (
+    ModelCircuitBreakerConfig,
+)
+
+__all__ = [
+    "ModelCircuitBreakerConfig",
+]

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"]