omnibase_infra 0.2.1__py3-none-any.whl

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

omnibase_infra/runtime/models/model_health_check_result.py

@@ -0,0 +1,228 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Health Check Result Model.
+
+This module provides the Pydantic model for component health check operation results.
+
+Design Pattern:
+    ModelHealthCheckResult replaces tuple[str, Any] returns from
+    check_health() with a strongly-typed model that provides:
+    - Component type identification
+    - Typed health status with structured details
+    - Factory methods for common healthy/unhealthy patterns
+
+Thread Safety:
+    ModelHealthCheckResult is immutable (frozen=True) after creation,
+    making it thread-safe for concurrent read access.
+
+Example:
+    >>> from omnibase_infra.runtime.models import ModelHealthCheckResult
+    >>>
+    >>> # Create a healthy result
+    >>> healthy = ModelHealthCheckResult.healthy_result("kafka")
+    >>> healthy.healthy
+    True
+    >>>
+    >>> # Create an unhealthy result (timeout)
+    >>> unhealthy = ModelHealthCheckResult.timeout_result("db", 5.0)
+    >>> unhealthy.healthy
+    False
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from omnibase_core.types import JsonType
+
+
+class ModelHealthCheckResult(BaseModel):
+    """Result of a handler health check operation.
+
+    Encapsulates the result of checking a single handler's health,
+    providing the handler type, health status, and detailed health data.
+
+    Attributes:
+        handler_type: The handler type identifier (e.g., "http", "db").
+        healthy: Whether the handler is healthy and operational.
+        details: Detailed health check data returned by the handler.
+    """
+
+    model_config = ConfigDict(
+        strict=True,
+        frozen=True,
+        extra="forbid",
+        from_attributes=True,
+    )
+
+    handler_type: str = Field(
+        ...,
+        description="Handler type identifier",
+        min_length=1,
+    )
+    healthy: bool = Field(
+        ...,
+        description="Whether the handler is healthy",
+    )
+    details: dict[str, JsonType] = Field(
+        default_factory=dict,
+        description="Detailed health check data from the handler",
+    )
+
+    @classmethod
+    def healthy_result(
+        cls,
+        handler_type: str,
+        note: str = "",
+    ) -> ModelHealthCheckResult:
+        """Create a healthy result for a handler.
+
+        Args:
+            handler_type: The handler type identifier.
+            note: Optional note about the healthy status. Empty string means no note.
+
+        Returns:
+            ModelHealthCheckResult indicating healthy status.
+
+        Example:
+            >>> result = ModelHealthCheckResult.healthy_result("kafka")
+            >>> result.healthy
+            True
+        """
+        details: dict[str, JsonType] = {"healthy": True}
+        if note:
+            details["note"] = note
+        return cls(handler_type=handler_type, healthy=True, details=details)
+
+    @classmethod
+    def no_health_check_result(cls, handler_type: str) -> ModelHealthCheckResult:
+        """Create a result for a handler without health_check method.
+
+        By convention, handlers without health_check are assumed healthy.
+
+        Args:
+            handler_type: The handler type identifier.
+
+        Returns:
+            ModelHealthCheckResult indicating healthy (no health_check method).
+
+        Example:
+            >>> result = ModelHealthCheckResult.no_health_check_result("custom")
+            >>> result.healthy
+            True
+        """
+        return cls(
+            handler_type=handler_type,
+            healthy=True,
+            details={"healthy": True, "note": "no health_check method"},
+        )
+
+    @classmethod
+    def timeout_result(
+        cls,
+        handler_type: str,
+        timeout_seconds: float,
+    ) -> ModelHealthCheckResult:
+        """Create an unhealthy result for a health check timeout.
+
+        Args:
+            handler_type: The handler type identifier.
+            timeout_seconds: The timeout duration that was exceeded.
+
+        Returns:
+            ModelHealthCheckResult indicating timeout failure.
+
+        Example:
+            >>> result = ModelHealthCheckResult.timeout_result("db", 5.0)
+            >>> result.healthy
+            False
+        """
+        return cls(
+            handler_type=handler_type,
+            healthy=False,
+            details={
+                "healthy": False,
+                "error": f"health check timeout after {timeout_seconds}s",
+            },
+        )
+
+    @classmethod
+    def error_result(
+        cls,
+        handler_type: str,
+        error: str,
+    ) -> ModelHealthCheckResult:
+        """Create an unhealthy result for a health check exception.
+
+        Args:
+            handler_type: The handler type identifier.
+            error: The error message from the exception.
+
+        Returns:
+            ModelHealthCheckResult indicating error failure.
+
+        Example:
+            >>> result = ModelHealthCheckResult.error_result(
+            ...     "vault",
+            ...     "Authentication token expired",
+            ... )
+            >>> result.healthy
+            False
+        """
+        return cls(
+            handler_type=handler_type,
+            healthy=False,
+            details={"healthy": False, "error": error},
+        )
+
+    @classmethod
+    def from_handler_response(
+        cls,
+        handler_type: str,
+        health_response: object,
+    ) -> ModelHealthCheckResult:
+        """Create a result from a raw handler health check response.
+
+        Parses the handler's health check response and extracts health status.
+
+        Args:
+            handler_type: The handler type identifier.
+            health_response: The raw response from handler.health_check().
+
+        Returns:
+            ModelHealthCheckResult from the response.
+
+        Example:
+            >>> response = {"healthy": True, "lag": 100}
+            >>> result = ModelHealthCheckResult.from_handler_response(
+            ...     "kafka",
+            ...     response,
+            ... )
+            >>> result.healthy
+            True
+        """
+        if isinstance(health_response, dict):
+            healthy = bool(health_response.get("healthy", False))
+            return cls(
+                handler_type=handler_type,
+                healthy=healthy,
+                details=health_response,
+            )
+        # Non-dict response - treat as details, assume healthy
+        return cls(
+            handler_type=handler_type,
+            healthy=True,
+            details={"raw_response": health_response},
+        )
+
+    def __str__(self) -> str:
+        """Return a human-readable string representation for debugging.
+
+        Returns:
+            String format: "ModelHealthCheckResult(handler_type='...', healthy=...)"
+        """
+        status = "healthy" if self.healthy else "unhealthy"
+        return f"ModelHealthCheckResult(handler_type='{self.handler_type}', {status})"
+
+
+__all__: list[str] = ["ModelHealthCheckResult"]

omnibase_infra/runtime/models/model_lifecycle_result.py

@@ -0,0 +1,245 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Lifecycle Result Model for handler shutdown operations.
+
+This module provides the ModelLifecycleResult class for representing the outcome
+of individual handler lifecycle operations (e.g., shutdown).
+
+Design Pattern:
+    ModelLifecycleResult replaces tuple[str, bool, str | None] returns from
+    shutdown_handler() with a strongly-typed, self-documenting model that
+    provides factory methods for success/failure cases.
+
+    The model uses an empty string sentinel instead of None for error_message
+    to eliminate union types and reduce type complexity. Use the `has_error`
+    property to check if an error exists before accessing error_message.
+
+Thread Safety:
+    ModelLifecycleResult is immutable (frozen=True) after creation,
+    making it thread-safe for concurrent read access.
+
+Example:
+    >>> from omnibase_infra.runtime.models import ModelLifecycleResult
+    >>>
+    >>> # Create a successful shutdown result
+    >>> success = ModelLifecycleResult.succeeded("kafka")
+    >>> success.handler_type
+    'kafka'
+    >>> success.success
+    True
+    >>> success.has_error
+    False
+    >>>
+    >>> # Create a failed shutdown result
+    >>> failure = ModelLifecycleResult.failed("db", "Connection timeout")
+    >>> failure.success
+    False
+    >>> failure.error_message
+    'Connection timeout'
+    >>> failure.has_error
+    True
+
+.. versionchanged:: 0.7.0
+    Changed error_message from str | None to str with empty string sentinel
+    to reduce union count (OMN-1003 consolidation).
+"""
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from omnibase_infra.enums import EnumInfraTransportType
+from omnibase_infra.errors import ModelInfraErrorContext, ProtocolConfigurationError
+
+
+class ModelLifecycleResult(BaseModel):
+    """Result of a single handler lifecycle operation (e.g., shutdown).
+
+    Provides a strongly-typed replacement for tuple[str, bool, str | None]
+    with factory methods for common success/failure patterns.
+
+    Note:
+        The ``error_message`` field uses an empty string sentinel instead
+        of None to eliminate union types. Use the ``has_error`` property
+        to check if an error message exists before accessing it.
+
+    Attributes:
+        handler_type: The handler type identifier (e.g., "kafka", "db", "http").
+        success: True if the lifecycle operation completed successfully.
+        error_message: Error description if the operation failed, empty string
+            otherwise. Use ``has_error`` to check if an error exists.
+
+    Example:
+        >>> result = ModelLifecycleResult.succeeded("consul")
+        >>> result.success
+        True
+        >>> result.has_error
+        False
+
+        >>> result = ModelLifecycleResult.failed("vault", "Auth expired")
+        >>> result.success
+        False
+        >>> result.error_message
+        'Auth expired'
+        >>> result.has_error
+        True
+    """
+
+    model_config = ConfigDict(
+        strict=True,
+        frozen=True,
+        extra="forbid",
+        from_attributes=True,
+    )
+
+    handler_type: str = Field(
+        ...,
+        description="The handler type identifier (e.g., 'kafka', 'db').",
+        min_length=1,
+    )
+    success: bool = Field(
+        ...,
+        description="True if the lifecycle operation completed successfully.",
+    )
+    error_message: str = Field(
+        default="",
+        description="Error description if the operation failed, empty string otherwise. "
+        "Use has_error property to check if an error exists.",
+    )
+
+    @property
+    def has_error(self) -> bool:
+        """Check if an error message exists.
+
+        Returns:
+            True if error_message is non-empty, False otherwise.
+
+        Example:
+            >>> ModelLifecycleResult.succeeded("kafka").has_error
+            False
+            >>> ModelLifecycleResult.failed("db", "Error").has_error
+            True
+        """
+        return bool(self.error_message)
+
+    @classmethod
+    def succeeded(cls, handler_type: str) -> "ModelLifecycleResult":
+        """Create a successful lifecycle result.
+
+        Args:
+            handler_type: The handler type identifier.
+
+        Returns:
+            ModelLifecycleResult indicating success.
+
+        Example:
+            >>> result = ModelLifecycleResult.succeeded("kafka")
+            >>> result.success
+            True
+            >>> result.has_error
+            False
+        """
+        return cls(handler_type=handler_type, success=True, error_message="")
+
+    @classmethod
+    def failed(cls, handler_type: str, error_message: str) -> "ModelLifecycleResult":
+        """Create a failed lifecycle result.
+
+        Args:
+            handler_type: The handler type identifier.
+            error_message: Description of the error that occurred. Must be non-empty.
+
+        Returns:
+            ModelLifecycleResult indicating failure with error details.
+
+        Raises:
+            ValueError: If error_message is empty.
+
+        Example:
+            >>> result = ModelLifecycleResult.failed("db", "Connection refused")
+            >>> result.success
+            False
+            >>> result.error_message
+            'Connection refused'
+        """
+        if not error_message:
+            context = ModelInfraErrorContext(
+                transport_type=EnumInfraTransportType.RUNTIME,
+                operation="lifecycle_failed",
+            )
+            raise ProtocolConfigurationError(
+                "error_message must be non-empty for failed results",
+                context=context,
+            )
+        return cls(
+            handler_type=handler_type, success=False, error_message=error_message
+        )
+
+    def is_success(self) -> bool:
+        """Check if the lifecycle operation succeeded.
+
+        Returns:
+            True if success is True, False otherwise.
+        """
+        return self.success
+
+    def is_failure(self) -> bool:
+        """Check if the lifecycle operation failed.
+
+        Returns:
+            True if success is False, False otherwise.
+        """
+        return not self.success
+
+    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 lifecycle operation checks::
+
+                if result:
+                    # Operation succeeded - continue
+                    continue_shutdown_sequence()
+                else:
+                    # Operation failed - handle error
+                    log_error(result.error_message)
+                    raise LifecycleError(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 operation succeeded, False otherwise.
+
+        Example:
+            >>> if ModelLifecycleResult.succeeded("kafka"):
+            ...     print("Shutdown complete!")
+            Shutdown complete!
+        """
+        return self.success
+
+    def __str__(self) -> str:
+        """Return a human-readable string representation for debugging.
+
+        Returns:
+            String format: "ModelLifecycleResult(handler_type='...', success=...)"
+        """
+        status = "succeeded" if self.success else f"failed: {self.error_message}"
+        return f"ModelLifecycleResult(handler_type='{self.handler_type}', {status})"
+
+
+__all__ = ["ModelLifecycleResult"]