omnibase_infra 0.2.6__py3-none-any.whl

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

omnibase_infra/runtime/models/model_failed_component.py

@@ -0,0 +1,55 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Failed Component Model.
+
+This module provides the Pydantic model for representing a component that
+failed during shutdown operations.
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class ModelFailedComponent(BaseModel):
+    """Represents a component that failed during shutdown.
+
+    Attributes:
+        component_name: Name or type identifier of the failed component.
+        error_message: Error message describing the failure reason.
+
+    Example:
+        >>> failed = ModelFailedComponent(
+        ...     component_name="EventBusKafka",
+        ...     error_message="Connection timeout during shutdown"
+        ... )
+        >>> print(failed.component_name)
+        EventBusKafka
+    """
+
+    model_config = ConfigDict(
+        strict=True,
+        frozen=True,
+        extra="forbid",
+        from_attributes=True,
+    )
+
+    component_name: str = Field(
+        min_length=1,
+        description="Name or type identifier of the failed component",
+    )
+    error_message: str = Field(
+        min_length=1,
+        description="Error message describing the failure reason",
+    )
+
+    def __str__(self) -> str:
+        """Return a human-readable string representation.
+
+        Returns:
+            String format showing component name and error message.
+        """
+        return f"{self.component_name}: {self.error_message}"
+
+
+__all__: list[str] = ["ModelFailedComponent"]

omnibase_infra/runtime/models/model_health_check_response.py

@@ -0,0 +1,168 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Health Check Response Model.
+
+This module provides the Pydantic model for HTTP health check endpoint responses.
+The model serializes to JSON for Docker/Kubernetes health probes.
+
+Design Pattern:
+    ModelHealthCheckResponse replaces dict[str, object] responses from the
+    health server with a strongly-typed model that provides:
+    - Typed status field with Literal values
+    - Version string for runtime identification
+    - Optional details for successful health checks
+    - Optional error fields for failure cases
+
+Thread Safety:
+    ModelHealthCheckResponse is immutable (frozen=True) after creation,
+    making it thread-safe for concurrent read access.
+
+Example:
+    >>> from omnibase_infra.runtime.models import ModelHealthCheckResponse
+    >>>
+    >>> # Create a healthy response
+    >>> response = ModelHealthCheckResponse(
+    ...     status="healthy",
+    ...     version="1.0.0",
+    ...     details={"healthy": True, "handlers": {}},
+    ... )
+    >>> response.model_dump_json()
+    '{"status":"healthy","version":"1.0.0","details":{"healthy":true,...}}'
+"""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from omnibase_core.types import JsonType
+
+
+class ModelHealthCheckResponse(BaseModel):
+    """HTTP response model for health check endpoints.
+
+    Encapsulates the JSON response returned by GET /health and GET /ready
+    endpoints, providing type-safe serialization for health probe responses.
+
+    For successful health checks:
+        - status indicates overall health state
+        - version identifies the runtime
+        - details contains full health check data
+
+    For failed health checks (exceptions during health check):
+        - status is always "unhealthy"
+        - error contains the exception message
+        - error_type contains the exception class name
+        - correlation_id enables distributed tracing
+
+    Attributes:
+        status: Overall health status of the runtime.
+        version: Runtime version string for identification.
+        details: Full health check data (present on success).
+        error: Exception message (present on failure).
+        error_type: Exception class name (present on failure).
+        correlation_id: Tracing ID for debugging (present on failure).
+    """
+
+    model_config = ConfigDict(
+        strict=True,
+        frozen=True,
+        extra="forbid",
+        from_attributes=True,
+    )
+
+    status: Literal["healthy", "degraded", "unhealthy"] = Field(
+        ...,
+        description="Overall health status of the runtime",
+    )
+    version: str = Field(
+        ...,
+        description="Runtime version string",
+    )
+    details: dict[str, JsonType] | None = Field(
+        default=None,
+        description="Full health check data from RuntimeHostProcess",
+    )
+    error: str | None = Field(
+        default=None,
+        description="Exception message if health check failed",
+    )
+    error_type: str | None = Field(
+        default=None,
+        description="Exception class name if health check failed",
+    )
+    correlation_id: str | None = Field(
+        default=None,
+        description="Correlation ID for distributed tracing on failure",
+    )
+
+    @classmethod
+    def success(
+        cls,
+        status: Literal["healthy", "degraded", "unhealthy"],
+        version: str,
+        details: dict[str, JsonType],
+    ) -> ModelHealthCheckResponse:
+        """Create a successful health check response.
+
+        Args:
+            status: The determined health status.
+            version: Runtime version string.
+            details: Full health check data from the runtime.
+
+        Returns:
+            ModelHealthCheckResponse for successful health check.
+
+        Example:
+            >>> response = ModelHealthCheckResponse.success(
+            ...     status="healthy",
+            ...     version="1.0.0",
+            ...     details={"healthy": True},
+            ... )
+        """
+        return cls(
+            status=status,
+            version=version,
+            details=details,
+        )
+
+    @classmethod
+    def failure(
+        cls,
+        version: str,
+        error: str,
+        error_type: str,
+        correlation_id: str,
+    ) -> ModelHealthCheckResponse:
+        """Create a failure health check response.
+
+        Used when health_check() itself raises an exception.
+
+        Args:
+            version: Runtime version string.
+            error: The exception message.
+            error_type: The exception class name.
+            correlation_id: Tracing ID for debugging.
+
+        Returns:
+            ModelHealthCheckResponse for failed health check.
+
+        Example:
+            >>> response = ModelHealthCheckResponse.failure(
+            ...     version="1.0.0",
+            ...     error="Connection refused",
+            ...     error_type="ConnectionError",
+            ...     correlation_id="abc-123",
+            ... )
+        """
+        return cls(
+            status="unhealthy",
+            version=version,
+            error=error,
+            error_type=error_type,
+            correlation_id=correlation_id,
+        )
+
+
+__all__: list[str] = ["ModelHealthCheckResponse"]