omnibase_infra 0.2.1__py3-none-any.whl

omnibase_infra/runtime/models/model_config_ref_parse_result.py

@@ -0,0 +1,125 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Configuration reference parse result model.
+
+.. versionadded:: 0.8.0
+    Initial implementation for OMN-765.
+
+This module provides the ModelConfigRefParseResult for representing
+the result of parsing a configuration reference string.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from pydantic import BaseModel, ConfigDict, Field
+
+if TYPE_CHECKING:
+    from omnibase_infra.runtime.models.model_config_ref import ModelConfigRef
+
+
+class ModelConfigRefParseResult(BaseModel):
+    """Result of parsing a configuration reference.
+
+    This model follows the result pattern where parsing never throws exceptions
+    for invalid input. Instead, check `success` or use the model in a boolean
+    context to determine if parsing succeeded.
+
+    Attributes:
+        success: True if parsing succeeded, False otherwise.
+        config_ref: The parsed ModelConfigRef if successful, None otherwise.
+        error_message: Error description if parsing failed, None otherwise.
+
+    Examples:
+        >>> result = ModelConfigRef.parse("file:config.yaml")
+        >>> if result:
+        ...     print(f"Path: {result.config_ref.path}")
+        Path: config.yaml
+        >>>
+        >>> result = ModelConfigRef.parse("invalid")
+        >>> if not result:
+        ...     print(f"Error: {result.error_message}")
+        Error: Invalid config reference format: missing scheme separator ':' in 'invalid'
+    """
+
+    model_config = ConfigDict(
+        strict=True,
+        frozen=True,
+        extra="forbid",
+        from_attributes=True,
+    )
+
+    success: bool = Field(
+        ...,
+        description="True if parsing succeeded, False otherwise.",
+    )
+    # NOTE: Using string annotation to avoid circular import
+    config_ref: ModelConfigRef | None = Field(
+        default=None,
+        description="The parsed configuration reference if successful, None otherwise.",
+    )
+    error_message: str | None = Field(
+        default=None,
+        description="Error description if parsing failed, None otherwise.",
+    )
+
+    def __bool__(self) -> bool:
+        """Allow using result in boolean context.
+
+        Warning:
+            **Non-standard __bool__ behavior**: This model overrides ``__bool__`` to
+            return ``True`` only when ``success`` is True. This differs from typical
+            Pydantic model behavior where ``bool(model)`` always returns ``True`` for
+            any valid model instance.
+
+            This design enables idiomatic parse result checks::
+
+                result = ModelConfigRef.parse("file:config.yaml")
+                if result:
+                    # Parsing succeeded - use the config_ref
+                    use_config(result.config_ref)
+                else:
+                    # Parsing failed - handle the error
+                    log_error(result.error_message)
+
+            If you need to check model validity instead, use explicit attribute access::
+
+                # Check for success (uses __bool__)
+                if result:
+                    ...
+
+                # Check model is valid (always True for constructed instance)
+                if result is not None:
+                    ...
+
+                # Explicit success check (preferred for clarity)
+                if result.success:
+                    ...
+
+        Returns:
+            True if parsing succeeded, False otherwise.
+
+        Examples:
+            >>> result = ModelConfigRef.parse("file:config.yaml")
+            >>> bool(result)
+            True
+            >>>
+            >>> result = ModelConfigRef.parse("")
+            >>> bool(result)
+            False
+        """
+        return self.success
+
+    def __str__(self) -> str:
+        """Return a human-readable string representation.
+
+        Returns:
+            String format showing success status and config_ref or error.
+        """
+        if self.success:
+            return f"ModelConfigRefParseResult(success=True, uri='{self.config_ref.to_uri() if self.config_ref else ''}')"
+        return f"ModelConfigRefParseResult(success=False, error='{self.error_message}')"
+
+
+__all__: list[str] = ["ModelConfigRefParseResult"]

omnibase_infra/runtime/models/model_domain_plugin_config.py

@@ -0,0 +1,92 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Domain plugin configuration model.
+
+This module provides the ModelDomainPluginConfig dataclass for passing
+configuration to domain plugins during lifecycle hooks.
+
+Design Pattern:
+    The kernel creates this config and passes it to each domain plugin
+    during bootstrap, providing all context needed for initialization
+    and handler wiring.
+
+Thread Safety:
+    This is a mutable dataclass. The dispatch_engine field may be set
+    after initial construction when the MessageDispatchEngine is created.
+
+Example:
+    >>> from omnibase_infra.runtime.models import ModelDomainPluginConfig
+    >>> from uuid import uuid4
+    >>>
+    >>> config = ModelDomainPluginConfig(
+    ...     container=container,
+    ...     event_bus=event_bus,
+    ...     correlation_id=uuid4(),
+    ...     input_topic="requests",
+    ...     output_topic="responses",
+    ...     consumer_group="onex-runtime",
+    ... )
+    >>> result = await plugin.initialize(config)
+
+Related:
+    - OMN-1346: Registration Code Extraction
+    - OMN-888: Registration Orchestrator
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+from uuid import UUID
+
+if TYPE_CHECKING:
+    from omnibase_core.container import ModelONEXContainer
+    from omnibase_infra.event_bus.inmemory_event_bus import InMemoryEventBus
+    from omnibase_infra.event_bus.kafka_event_bus import KafkaEventBus
+    from omnibase_infra.runtime import MessageDispatchEngine
+
+
+@dataclass
+class ModelDomainPluginConfig:
+    """Configuration passed to domain plugins during lifecycle hooks.
+
+    This model provides all the context a domain plugin needs to initialize
+    its resources and wire its handlers. The kernel creates this config
+    and passes it to each plugin during bootstrap.
+
+    Attributes:
+        container: The ONEX container for dependency injection.
+        event_bus: The event bus instance (InMemoryEventBus or KafkaEventBus).
+        correlation_id: Correlation ID for distributed tracing.
+        input_topic: The input topic for event consumers.
+        output_topic: The output topic for event publishers.
+        consumer_group: The consumer group for Kafka consumers.
+        dispatch_engine: The MessageDispatchEngine for dispatcher wiring
+            (set after engine creation, may be None).
+
+    Example:
+        ```python
+        config = ModelDomainPluginConfig(
+            container=container,
+            event_bus=event_bus,
+            correlation_id=uuid4(),
+            input_topic="requests",
+            output_topic="responses",
+            consumer_group="onex-runtime",
+        )
+        result = await plugin.initialize(config)
+        ```
+    """
+
+    container: ModelONEXContainer
+    event_bus: InMemoryEventBus | KafkaEventBus
+    correlation_id: UUID
+    input_topic: str
+    output_topic: str
+    consumer_group: str
+
+    # Optional: MessageDispatchEngine for dispatcher wiring (set after engine creation)
+    dispatch_engine: MessageDispatchEngine | None = None
+
+
+__all__ = ["ModelDomainPluginConfig"]

omnibase_infra/runtime/models/model_domain_plugin_result.py

@@ -0,0 +1,270 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Domain plugin result model.
+
+This module provides the ModelDomainPluginResult dataclass for representing
+the outcome of domain plugin lifecycle operations.
+
+Design Pattern:
+    Result models provide structured information about operation outcomes,
+    including success/failure status, timing, and resources created. This
+    model supports the custom __bool__ pattern where truthiness reflects
+    operation success.
+
+Thread Safety:
+    ModelDomainPluginResult is NOT frozen - it may contain mutable lists
+    of resources and callbacks.
+
+Example:
+    >>> from omnibase_infra.runtime.models import ModelDomainPluginResult
+    >>>
+    >>> # Create success result using factory method
+    >>> result = ModelDomainPluginResult.succeeded(
+    ...     plugin_id="registration",
+    ...     message="Plugin initialized",
+    ...     resources_created=["postgres_pool"],
+    ... )
+    >>> if result:  # Uses __bool__ - True if success
+    ...     print("Initialization complete!")
+    >>>
+    >>> # Create failure result
+    >>> failure = ModelDomainPluginResult.failed(
+    ...     plugin_id="registration",
+    ...     error_message="Connection refused",
+    ... )
+    >>> if not failure:
+    ...     print(f"Failed: {failure.error_message}")
+
+Related:
+    - OMN-1346: Registration Code Extraction
+    - OMN-888: Registration Orchestrator
+"""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass, field
+
+
+@dataclass
+class ModelDomainPluginResult:
+    """Result model returned by domain plugin lifecycle hooks.
+
+    Provides structured information about the outcome of a plugin operation,
+    including success/failure status, timing, and resources created or cleaned up.
+
+    Attributes:
+        plugin_id: Identifier of the plugin that produced this result.
+        success: Whether the operation succeeded.
+        message: Human-readable message describing the outcome.
+        resources_created: List of resource identifiers created during this operation.
+        services_registered: List of service class names registered in container.
+        duration_seconds: Time taken for the operation.
+        error_message: Error message if operation failed.
+        unsubscribe_callbacks: Callbacks to invoke during shutdown for cleanup.
+
+    Example:
+        ```python
+        result = ModelDomainPluginResult(
+            plugin_id="registration",
+            success=True,
+            message="Registration plugin initialized",
+            resources_created=["postgres_pool"],
+            services_registered=["HandlerNodeIntrospected", "HandlerRuntimeTick"],
+            duration_seconds=0.5,
+        )
+        if not result:
+            logger.error("Plugin failed: %s", result.error_message)
+        ```
+    """
+
+    plugin_id: str
+    success: bool
+    message: str = ""
+    resources_created: list[str] = field(default_factory=list)
+    services_registered: list[str] = field(default_factory=list)
+    duration_seconds: float = 0.0
+    error_message: str | None = None
+
+    # Store unsubscribe callbacks for cleanup
+    unsubscribe_callbacks: list[Callable[[], Awaitable[None]]] = field(
+        default_factory=list
+    )
+
+    def get_error_message_or_default(self, default: str = "unknown") -> str:
+        """Return error_message if set, otherwise the default value.
+
+        This helper simplifies error handling in plugin activation code,
+        avoiding verbose None checks when accessing error_message.
+
+        Args:
+            default: Value to return if error_message is None or empty.
+
+        Returns:
+            The error_message if it's a non-empty string, otherwise default.
+
+        Example:
+            >>> result = ModelDomainPluginResult.failed(
+            ...     plugin_id="test",
+            ...     error_message="Connection refused",
+            ... )
+            >>> result.get_error_message_or_default()
+            'Connection refused'
+            >>>
+            >>> success = ModelDomainPluginResult.succeeded(plugin_id="test")
+            >>> success.get_error_message_or_default("no error")
+            'no error'
+        """
+        return self.error_message if self.error_message else default
+
+    def __bool__(self) -> bool:
+        """Return True if the operation succeeded.
+
+        Warning:
+            **Non-standard __bool__ behavior**: This model overrides ``__bool__`` to
+            return ``True`` only when ``success`` is True. This differs from typical
+            Pydantic/dataclass behavior where ``bool(model)`` always returns ``True``
+            for any valid instance.
+
+            This design enables idiomatic plugin lifecycle checks::
+
+                result = await plugin.initialize(config)
+                if result:
+                    # Operation succeeded - continue
+                    await plugin.wire_handlers(config)
+                else:
+                    # Operation failed - handle error
+                    logger.error("Plugin failed: %s", result.error_message)
+
+            If you need to check instance validity instead, use explicit checks::
+
+                # Check for success (uses __bool__)
+                if result:
+                    ...
+
+                # Check instance is valid (always True for constructed instance)
+                if result is not None:
+                    ...
+
+                # Explicit success check (preferred for clarity)
+                if result.success:
+                    ...
+
+        Returns:
+            True if success is True, False otherwise.
+        """
+        return self.success
+
+    @classmethod
+    def succeeded(
+        cls,
+        plugin_id: str,
+        message: str = "",
+        duration_seconds: float = 0.0,
+    ) -> ModelDomainPluginResult:
+        """Create a simple success result.
+
+        For results that require additional fields (resources_created, services_registered,
+        unsubscribe_callbacks), use the constructor directly.
+
+        Args:
+            plugin_id: Identifier of the plugin.
+            message: Human-readable success message.
+            duration_seconds: Time taken for the operation.
+
+        Returns:
+            ModelDomainPluginResult with success=True.
+
+        Example:
+            >>> result = ModelDomainPluginResult.succeeded(
+            ...     plugin_id="registration",
+            ...     message="Initialized",
+            ... )
+            >>> result.success
+            True
+
+            >>> # For results with resources, use constructor:
+            >>> result = ModelDomainPluginResult(
+            ...     plugin_id="registration",
+            ...     success=True,
+            ...     message="Initialized",
+            ...     resources_created=["pool"],
+            ... )
+        """
+        return cls(
+            plugin_id=plugin_id,
+            success=True,
+            message=message,
+            duration_seconds=duration_seconds,
+        )
+
+    @classmethod
+    def failed(
+        cls,
+        plugin_id: str,
+        error_message: str,
+        message: str = "",
+        duration_seconds: float = 0.0,
+    ) -> ModelDomainPluginResult:
+        """Create a failure result.
+
+        Args:
+            plugin_id: Identifier of the plugin.
+            error_message: Description of the error that occurred.
+            message: Optional human-readable message (defaults to "Plugin {id} failed").
+            duration_seconds: Time taken before failure.
+
+        Returns:
+            ModelDomainPluginResult with success=False.
+
+        Example:
+            >>> result = ModelDomainPluginResult.failed(
+            ...     plugin_id="registration",
+            ...     error_message="Connection refused",
+            ... )
+            >>> result.success
+            False
+            >>> result.error_message
+            'Connection refused'
+        """
+        return cls(
+            plugin_id=plugin_id,
+            success=False,
+            message=message or f"Plugin {plugin_id} failed",
+            error_message=error_message,
+            duration_seconds=duration_seconds,
+        )
+
+    @classmethod
+    def skipped(
+        cls,
+        plugin_id: str,
+        reason: str,
+    ) -> ModelDomainPluginResult:
+        """Create a skipped result (plugin did not activate).
+
+        Args:
+            plugin_id: Identifier of the plugin.
+            reason: Explanation of why the plugin was skipped.
+
+        Returns:
+            ModelDomainPluginResult with success=True and skip message.
+
+        Example:
+            >>> result = ModelDomainPluginResult.skipped(
+            ...     plugin_id="registration",
+            ...     reason="POSTGRES_HOST not configured",
+            ... )
+            >>> result.success
+            True
+            >>> "skipped" in result.message
+            True
+        """
+        return cls(
+            plugin_id=plugin_id,
+            success=True,
+            message=f"Plugin {plugin_id} skipped: {reason}",
+        )
+
+
+__all__ = ["ModelDomainPluginResult"]

omnibase_infra/runtime/models/model_duplicate_response.py

@@ -0,0 +1,54 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Duplicate Response Model.
+
+This module provides the Pydantic model for duplicate message detection responses.
+"""
+
+from __future__ import annotations
+
+from typing import Literal
+from uuid import UUID
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class ModelDuplicateResponse(BaseModel):
+    """Response indicating a duplicate message was detected.
+
+    This is NOT an error - duplicates are expected under at-least-once delivery.
+    The response indicates successful deduplication, informing the caller that
+    the message was already processed and no further action is needed.
+
+    Attributes:
+        success: Always True - deduplication is successful behavior.
+        status: Always "duplicate" to indicate the response type.
+        message: Human-readable description of the deduplication.
+        message_id: UUID of the duplicate message that was detected.
+        correlation_id: Correlation ID for distributed tracing.
+    """
+
+    model_config = ConfigDict(
+        strict=True,
+        frozen=True,
+        extra="forbid",
+        from_attributes=True,  # Support pytest-xdist compatibility
+    )
+
+    success: Literal[True] = Field(
+        default=True,
+        description="Deduplication is successful behavior",
+    )
+    status: Literal["duplicate"] = Field(
+        default="duplicate",
+        description="Response type indicator",
+    )
+    message: str = Field(
+        default="Message already processed",
+        description="Human-readable deduplication message",
+    )
+    message_id: UUID = Field(description="UUID of the duplicate message")
+    correlation_id: UUID = Field(description="Correlation ID for tracing")
+
+
+__all__: list[str] = ["ModelDuplicateResponse"]

omnibase_infra/runtime/models/model_enabled_protocols_config.py

@@ -0,0 +1,61 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Enabled Protocols Configuration Model.
+
+This module provides the Pydantic model for enabled protocol configuration.
+"""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+# Literal type for valid protocol names
+# These correspond to handler_registry constants:
+# HANDLER_TYPE_HTTP, HANDLER_TYPE_DATABASE, HANDLER_TYPE_KAFKA, etc.
+# NOTE: Values must match the operation prefixes used in handler implementations
+# (e.g., "db" matches "db.query", "valkey" matches "valkey.get")
+ProtocolName = Literal[
+    "http",
+    "db",
+    "kafka",
+    "vault",
+    "consul",
+    "valkey",
+    "grpc",
+]
+
+
+def _default_enabled_protocols() -> list[ProtocolName]:
+    """Create default list of enabled protocols.
+
+    Returns a properly typed list of default protocol names.
+    Using a factory function avoids cast() in default_factory for type safety.
+    """
+    return ["http", "db"]
+
+
+class ModelEnabledProtocolsConfig(BaseModel):
+    """Enabled protocols configuration model.
+
+    Defines which protocol types are enabled for the runtime.
+
+    Attributes:
+        enabled: List of enabled protocol type names (e.g., ['http', 'db'])
+    """
+
+    model_config = ConfigDict(
+        strict=True,
+        frozen=True,
+        extra="forbid",
+        from_attributes=True,  # Support pytest-xdist compatibility
+    )
+
+    enabled: list[ProtocolName] = Field(
+        default_factory=_default_enabled_protocols,
+        description="List of enabled protocol type names",
+    )
+
+
+__all__: list[str] = ["ModelEnabledProtocolsConfig", "ProtocolName"]

omnibase_infra/runtime/models/model_event_bus_config.py

@@ -0,0 +1,54 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Event Bus Configuration Model.
+
+This module provides the Pydantic model for event bus configuration.
+"""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class ModelEventBusConfig(BaseModel):
+    """Event bus configuration model.
+
+    Defines the event bus type and operational parameters.
+
+    Attributes:
+        type: Event bus implementation type ('inmemory' or 'kafka')
+        environment: Deployment environment name
+        max_history: Maximum event history to retain
+        circuit_breaker_threshold: Failure count before circuit breaker trips
+    """
+
+    model_config = ConfigDict(
+        strict=True,
+        frozen=True,
+        extra="forbid",
+        from_attributes=True,  # Support pytest-xdist compatibility
+    )
+
+    type: Literal["inmemory", "kafka"] = Field(
+        default="inmemory",
+        description="Event bus implementation type",
+    )
+    environment: str = Field(
+        default="local",
+        description="Deployment environment name",
+    )
+    max_history: int = Field(
+        default=1000,
+        ge=0,
+        description="Maximum event history to retain",
+    )
+    circuit_breaker_threshold: int = Field(
+        default=5,
+        ge=1,
+        description="Failure count before circuit breaker trips",
+    )
+
+
+__all__: list[str] = ["ModelEventBusConfig"]