omnibase_infra 0.2.6__py3-none-any.whl

omnibase_infra/runtime/models/model_health_check_result.py

@@ -0,0 +1,229 @@
+# 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
+        # Convert to string representation for JsonType compatibility
+        return cls(
+            handler_type=handler_type,
+            healthy=True,
+            details={"raw_response": str(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"]

omnibase_infra/runtime/models/model_logging_config.py

@@ -0,0 +1,42 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Logging Configuration Model.
+
+This module provides the Pydantic model for logging configuration.
+"""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class ModelLoggingConfig(BaseModel):
+    """Logging configuration model.
+
+    Defines logging level and format for the runtime.
+
+    Attributes:
+        level: Logging level (DEBUG, INFO, WARNING, ERROR, CRITICAL)
+        format: Log message format string
+    """
+
+    model_config = ConfigDict(
+        strict=True,
+        frozen=True,
+        extra="forbid",
+        from_attributes=True,  # Support pytest-xdist compatibility
+    )
+
+    level: Literal["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"] = Field(
+        default="INFO",
+        description="Logging level",
+    )
+    format: str = Field(
+        default="%(asctime)s [%(levelname)s] %(name)s: %(message)s",
+        description="Log message format string",
+    )
+
+
+__all__: list[str] = ["ModelLoggingConfig"]

omnibase_infra/runtime/models/model_optional_correlation_id.py

@@ -0,0 +1,167 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Model for optional correlation ID values in runtime module.
+
+This module provides a strongly-typed Pydantic model for optional
+correlation ID values (UUIDs), replacing `UUID | None` union types
+to comply with ONEX standards.
+
+Correlation IDs are used throughout the runtime for request tracing,
+logging, and distributed system observability.
+
+Design Decision (PR #47 Review):
+    This model intentionally duplicates patterns from ModelOptionalUUID rather than
+    using inheritance or generics. This design choice provides:
+
+    1. **Self-contained model**: No dependencies on base classes or mixins
+    2. **Correlation-specific methods**: `get_or_generate()` is specific to correlation IDs
+    3. **ONEX compliance**: Follows "composition over inheritance" principle
+    4. **Future-ready**: Available for strongly-typed correlation ID handling
+       in RuntimeHostProcess and event envelope processing
+
+    While currently not actively used, this model is pre-built for consistent
+    correlation ID handling as the codebase evolves. The trade-off of code
+    duplication vs. generic abstractions was intentionally chosen for clarity
+    and type safety.
+
+    See Also:
+        - ModelOptionalUUID: Similar pattern for generic optional UUIDs
+        - docs/patterns/correlation_id_tracking.md: Correlation ID best practices
+"""
+
+from uuid import UUID, uuid4
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class ModelOptionalCorrelationId(BaseModel):
+    """Strongly-typed model for optional correlation ID values.
+
+    Replaces `UUID | None` for correlation IDs to comply with ONEX
+    standards requiring specific typed models instead of generic union types.
+
+    This specialized wrapper is designed for correlation ID use cases,
+    providing factory methods to generate new UUIDs when needed and
+    ensuring consistent handling across the runtime module.
+
+    Attributes:
+        value: The optional correlation ID (UUID), defaults to None.
+
+    Example:
+        >>> corr = ModelOptionalCorrelationId.generate()
+        >>> corr.has_value()
+        True
+        >>> empty = ModelOptionalCorrelationId()
+        >>> filled = empty.get_or_generate()
+        >>> filled.has_value()
+        True
+    """
+
+    model_config = ConfigDict(frozen=True, from_attributes=True, extra="forbid")
+
+    value: UUID | None = Field(
+        default=None, description="Optional correlation ID (UUID)"
+    )
+
+    @classmethod
+    def generate(cls) -> "ModelOptionalCorrelationId":
+        """Create a new correlation ID with a generated UUID.
+
+        Factory method that creates a ModelOptionalCorrelationId with
+        a newly generated UUID4 value.
+
+        Returns:
+            A new ModelOptionalCorrelationId with a generated UUID.
+        """
+        return cls(value=uuid4())
+
+    @classmethod
+    def from_uuid(cls, value: UUID) -> "ModelOptionalCorrelationId":
+        """Create a correlation ID from an existing UUID.
+
+        Args:
+            value: An existing UUID to wrap.
+
+        Returns:
+            A new ModelOptionalCorrelationId with the given UUID.
+        """
+        return cls(value=value)
+
+    @classmethod
+    def none(cls) -> "ModelOptionalCorrelationId":
+        """Create an empty correlation ID.
+
+        Returns:
+            A new ModelOptionalCorrelationId with no value.
+        """
+        return cls()
+
+    def get(self) -> UUID | None:
+        """Get the optional correlation ID.
+
+        Returns:
+            The UUID value if present, None otherwise.
+        """
+        return self.value
+
+    def has_value(self) -> bool:
+        """Check if correlation ID is present.
+
+        Returns:
+            True if value is not None, False otherwise.
+        """
+        return self.value is not None
+
+    def get_or_default(self, default: UUID) -> UUID:
+        """Get correlation ID or return default if None.
+
+        Args:
+            default: The default UUID to return if None.
+
+        Returns:
+            The stored value if present, otherwise the default.
+        """
+        return self.value if self.value is not None else default
+
+    def get_or_generate(self) -> "ModelOptionalCorrelationId":
+        """Get this correlation ID or generate a new one if None.
+
+        Returns a new ModelOptionalCorrelationId with either:
+        - The existing UUID if present
+        - A newly generated UUID if None
+
+        Returns:
+            A ModelOptionalCorrelationId that always has a value.
+        """
+        if self.value is not None:
+            return self
+        return ModelOptionalCorrelationId.generate()
+
+    def __bool__(self) -> bool:
+        """Boolean representation based on value presence.
+
+        Warning:
+            **Non-standard __bool__ behavior**: This model overrides ``__bool__`` to
+            return ``True`` only when a correlation ID is present. This differs from
+            typical Pydantic model behavior where ``bool(model)`` always returns
+            ``True`` for any valid model instance.
+
+            This design enables idiomatic presence checks::
+
+                if corr_id:
+                    # Correlation ID is present - propagate it
+                    context.set_correlation_id(corr_id.value)
+                else:
+                    # No correlation ID - generate new one
+                    corr_id = corr_id.get_or_generate()
+
+            Use ``corr_id.has_value()`` for explicit, self-documenting code.
+            Use ``corr_id is not None`` if you need to check model existence.
+
+        Returns:
+            True if correlation ID is present, False otherwise.
+        """
+        return self.has_value()
+
+
+__all__ = ["ModelOptionalCorrelationId"]