omnibase_infra 0.2.6__py3-none-any.whl

omnibase_infra/errors/error_chain_propagation.py

@@ -0,0 +1,188 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Chain Propagation Error.
+
+Defines the error class for correlation and causation chain validation failures.
+Used when message chains fail to maintain proper correlation_id or causation_id
+propagation, which breaks distributed tracing capabilities.
+"""
+
+from __future__ import annotations
+
+from uuid import uuid4
+
+from omnibase_core.enums import EnumCoreErrorCode
+from omnibase_infra.enums import EnumInfraTransportType
+from omnibase_infra.errors.error_infra import (
+    ProtocolConfigurationError,
+    RuntimeHostError,
+)
+from omnibase_infra.models.errors.model_infra_error_context import (
+    ModelInfraErrorContext,
+)
+from omnibase_infra.models.validation.model_chain_violation import ModelChainViolation
+
+
+class ChainPropagationError(RuntimeHostError):
+    """Raised when correlation or causation chain validation fails.
+
+    Used when messages fail to properly maintain their correlation and
+    causation chains during propagation. This error indicates a break
+    in the distributed tracing chain that will impact observability
+    and debugging capabilities.
+
+    Common scenarios:
+        - Child message has different correlation_id than parent
+        - Message's causation_id doesn't reference parent's message_id
+        - Causation chain skips ancestors in the message lineage
+
+    The error includes all detected violations for comprehensive reporting
+    and supports correlation_id from the error context for meta-level tracing.
+
+    Attributes:
+        violations: Immutable tuple of all chain violations detected.
+
+    Example:
+        >>> from uuid import uuid4
+        >>> from omnibase_infra.enums import EnumChainViolationType
+        >>> from omnibase_infra.models.validation import ModelChainViolation
+        >>>
+        >>> violations = [
+        ...     ModelChainViolation(
+        ...         violation_type=EnumChainViolationType.CORRELATION_MISMATCH,
+        ...         expected_value=uuid4(),
+        ...         actual_value=uuid4(),
+        ...         message_id=uuid4(),
+        ...         violation_message="correlation_id mismatch",
+        ...     ),
+        ... ]
+        >>> context = ModelInfraErrorContext(
+        ...     operation="validate_chain",
+        ...     correlation_id=uuid4(),
+        ... )
+        >>> raise ChainPropagationError(
+        ...     "Chain validation failed",
+        ...     violations=violations,
+        ...     context=context,
+        ... )
+    """
+
+    def __init__(
+        self,
+        message: str,
+        violations: list[ModelChainViolation],
+        context: ModelInfraErrorContext | None = None,
+        **extra_context: object,
+    ) -> None:
+        """Initialize ChainPropagationError with violation details.
+
+        Args:
+            message: Human-readable error message summarizing the violations.
+            violations: List of all chain violations detected. Must contain
+                at least one violation.
+            context: Bundled infrastructure context including correlation_id
+                for meta-level tracing of the validation operation itself.
+            **extra_context: Additional context information for debugging.
+
+        Raises:
+            ProtocolConfigurationError: If violations list is empty.
+        """
+        if not violations:
+            err_context = ModelInfraErrorContext(
+                transport_type=EnumInfraTransportType.RUNTIME,
+                operation="ChainPropagationError.__init__",
+                correlation_id=context.correlation_id if context else uuid4(),
+            )
+            raise ProtocolConfigurationError(
+                "ChainPropagationError requires at least one violation",
+                context=err_context,
+                parameter="violations",
+            )
+
+        # Store violations for access
+        self._violations = violations
+
+        # Build summary for error message
+        error_count = sum(1 for v in violations if v.severity == "error")
+        warning_count = sum(1 for v in violations if v.severity == "warning")
+        violation_summary = f"{error_count} error(s), {warning_count} warning(s)"
+
+        # Build detailed message
+        full_message = f"{message}: {violation_summary}"
+
+        # Add violation types summary
+        violation_types = {v.violation_type.value for v in violations}
+        full_message += f" [{', '.join(sorted(violation_types))}]"
+
+        super().__init__(
+            message=full_message,
+            error_code=EnumCoreErrorCode.VALIDATION_ERROR,
+            context=context,
+            violation_count=len(violations),
+            error_count=error_count,
+            warning_count=warning_count,
+            violation_types=list(violation_types),
+            **extra_context,
+        )
+
+    @property
+    def violations(self) -> tuple[ModelChainViolation, ...]:
+        """Get all detected chain violations.
+
+        Returns:
+            Immutable tuple of ModelChainViolation instances describing each violation.
+        """
+        return tuple(self._violations)
+
+    def get_blocking_violations(self) -> list[ModelChainViolation]:
+        """Get only violations that should block processing.
+
+        Returns:
+            List of violations with severity='error'.
+
+        Example:
+            >>> blocking = error.get_blocking_violations()
+            >>> len(blocking)
+            1
+        """
+        return [v for v in self._violations if v.is_blocking()]
+
+    def get_warnings(self) -> list[ModelChainViolation]:
+        """Get only advisory violations.
+
+        Returns:
+            List of violations with severity='warning'.
+
+        Example:
+            >>> warnings = error.get_warnings()
+            >>> len(warnings)
+            2
+        """
+        return [v for v in self._violations if not v.is_blocking()]
+
+    def format_violations_for_logging(self) -> str:
+        """Format all violations for structured logging output.
+
+        Returns:
+            Multi-line string with each violation formatted for logging.
+
+        Example:
+            >>> error.format_violations_for_logging()
+            '[error] CORRELATION_MISMATCH on message=abc...\\n[warning] ...'
+        """
+        return "\n".join(v.format_for_logging() for v in self._violations)
+
+    def has_blocking_violations(self) -> bool:
+        """Check if any violations should block processing.
+
+        Returns:
+            True if at least one violation has severity='error'.
+
+        Example:
+            >>> error.has_blocking_violations()
+            True
+        """
+        return any(v.is_blocking() for v in self._violations)
+
+
+__all__ = ["ChainPropagationError"]

omnibase_infra/errors/error_compute_registry.py

@@ -0,0 +1,95 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Compute Registry Error Class.
+
+This module defines the ComputeRegistryError for compute registry operations.
+"""
+
+from typing import Any, cast
+
+from omnibase_infra.errors.error_infra import RuntimeHostError
+from omnibase_infra.models.errors.model_infra_error_context import (
+    ModelInfraErrorContext,
+)
+
+
+class ComputeRegistryError(RuntimeHostError):
+    """Error raised when compute registry operations fail.
+
+    Used for:
+    - Attempting to get an unregistered compute plugin
+    - Registration failures (async validation without flag, protocol validation)
+    - Plugin validation failures during registration
+    - Invalid semver format
+
+    Extends RuntimeHostError as this is an infrastructure-layer runtime concern.
+
+    Example:
+        >>> from omnibase_infra.errors import ComputeRegistryError
+        >>> from omnibase_infra.errors import ModelInfraErrorContext
+        >>> from omnibase_infra.enums import EnumInfraTransportType
+        >>> from uuid import uuid4
+
+        >>> # Plugin not found
+        >>> try:
+        ...     plugin = registry.get("unknown_plugin")
+        ... except ComputeRegistryError as e:
+        ...     print(f"Plugin not found: {e}")
+
+        >>> # With context
+        >>> context = ModelInfraErrorContext(
+        ...     transport_type=EnumInfraTransportType.RUNTIME,
+        ...     operation="get_plugin",
+        ...     correlation_id=uuid4(),
+        ... )
+        >>> raise ComputeRegistryError(
+        ...     "Compute plugin not registered",
+        ...     plugin_id="json_normalizer",
+        ...     version="1.0.0",
+        ...     context=context,
+        ... )
+
+        >>> # Async validation failure
+        >>> raise ComputeRegistryError(
+        ...     "Plugin has async execute() but deterministic_async=True not specified",
+        ...     plugin_id="async_transformer",
+        ...     async_method="execute",
+        ... )
+    """
+
+    def __init__(
+        self,
+        message: str,
+        plugin_id: str | None = None,
+        version: str | None = None,
+        registered_plugins: list[str] | None = None,
+        context: ModelInfraErrorContext | None = None,
+        **extra_context: object,
+    ) -> None:
+        """Initialize ComputeRegistryError.
+
+        Args:
+            message: Human-readable error message
+            plugin_id: The plugin ID that caused the error (if applicable)
+            version: The version that caused the error (if applicable)
+            registered_plugins: List of currently registered plugin IDs (for error context)
+            context: Bundled infrastructure context for correlation_id and structured fields
+            **extra_context: Additional context information (e.g., async_method)
+        """
+        # Add plugin_id, version, registered_plugins to extra_context if provided
+        if plugin_id is not None:
+            extra_context["plugin_id"] = plugin_id
+        if version is not None:
+            extra_context["version"] = version
+        if registered_plugins is not None:
+            extra_context["registered_plugins"] = registered_plugins
+
+        # NOTE: Cast required for mypy - **dict[str, object] doesn't satisfy **context: Any
+        super().__init__(
+            message=message,
+            context=context,
+            **cast("dict[str, Any]", extra_context),
+        )
+
+
+__all__ = ["ComputeRegistryError"]

omnibase_infra/errors/error_consul.py

@@ -0,0 +1,132 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Consul-Specific Infrastructure Error Class.
+
+This module defines the InfraConsulError class for Consul-related infrastructure
+errors. It extends InfraConnectionError to provide specialized error handling
+for HashiCorp Consul operations.
+
+Security Note:
+    Consul key paths are automatically sanitized when stored in error context
+    to prevent exposure of infrastructure topology, service names, and
+    configuration structures. Full keys are only logged at DEBUG level if needed.
+"""
+
+from omnibase_infra.errors.error_infra import InfraConnectionError
+from omnibase_infra.models.errors.model_infra_error_context import (
+    ModelInfraErrorContext,
+)
+from omnibase_infra.utils.util_error_sanitization import sanitize_consul_key
+
+
+class InfraConsulError(InfraConnectionError):
+    """Error communicating with Consul.
+
+    Used for Consul client initialization failures, KV operations,
+    service registration, and retry exhaustion scenarios.
+
+    This error extends InfraConnectionError and is specifically designed
+    for HashiCorp Consul operations. The context should use
+    ``transport_type=EnumInfraTransportType.CONSUL``.
+
+    Common use cases:
+        - Consul client initialization failures
+        - KV store read/write operation failures
+        - Service registration/deregistration errors
+        - Health check registration failures
+        - Connection retry exhaustion
+        - Session/lock operation errors
+
+    Security:
+        Consul key paths passed to this error are automatically sanitized to
+        prevent exposure of infrastructure details in error messages, logs,
+        and metrics. The sanitization masks path segments after the first
+        segment, e.g., "config/database/connection" becomes "config/***/***".
+
+    Example:
+        >>> from omnibase_infra.enums import EnumInfraTransportType
+        >>> context = ModelInfraErrorContext(
+        ...     transport_type=EnumInfraTransportType.CONSUL,
+        ...     operation="kv_get",
+        ...     target_name="consul-primary",
+        ... )
+        >>> # Consul key will be sanitized to "config/***/***" in error context
+        >>> raise InfraConsulError(
+        ...     "Failed to read key from Consul KV store",
+        ...     context=context,
+        ...     consul_key="config/database/connection",
+        ... )
+
+        >>> # Service registration failure
+        >>> context = ModelInfraErrorContext(
+        ...     transport_type=EnumInfraTransportType.CONSUL,
+        ...     operation="register_service",
+        ...     target_name="consul-primary",
+        ... )
+        >>> raise InfraConsulError(
+        ...     "Failed to register service with Consul",
+        ...     context=context,
+        ...     service_name="api-gateway",
+        ...     service_id="api-gateway-1",
+        ... )
+
+        >>> # Client initialization failure
+        >>> context = ModelInfraErrorContext(
+        ...     transport_type=EnumInfraTransportType.CONSUL,
+        ...     operation="initialize_client",
+        ...     target_name="consul-primary",
+        ... )
+        >>> raise InfraConsulError(
+        ...     "Failed to initialize Consul client",
+        ...     context=context,
+        ...     host="consul.example.com",
+        ...     port=8500,
+        ...     retry_count=3,
+        ... )
+    """
+
+    def __init__(
+        self,
+        message: str,
+        context: ModelInfraErrorContext | None = None,
+        consul_key: str | None = None,
+        service_name: str | None = None,
+        **extra_context: object,
+    ) -> None:
+        """Initialize InfraConsulError with Consul-specific context.
+
+        Args:
+            message: Human-readable error message
+            context: Bundled infrastructure context (should use CONSUL transport_type)
+            consul_key: Optional KV key that caused the error.
+                This key is automatically sanitized to mask sensitive segments
+                (e.g., "config/database/creds" -> "config/***/***").
+            service_name: Optional service name for service registration errors
+            **extra_context: Additional context information (e.g., host, port, retry_count)
+
+        Security:
+            The consul_key is sanitized before being stored in extra_context
+            to prevent exposure of infrastructure topology in error messages,
+            logs, and metrics. Only the first path segment is preserved.
+        """
+        # Include sanitized consul_key in extra_context if provided
+        # This prevents exposure of full key paths in error messages/logs
+        if consul_key is not None:
+            sanitized_key = sanitize_consul_key(consul_key)
+            if sanitized_key:
+                extra_context["consul_key"] = sanitized_key
+
+        # Include service_name in extra_context if provided
+        if service_name is not None:
+            extra_context["service_name"] = service_name
+
+        super().__init__(
+            message=message,
+            context=context,
+            **extra_context,
+        )
+
+
+__all__: list[str] = [
+    "InfraConsulError",
+]

omnibase_infra/errors/error_container_wiring.py

@@ -0,0 +1,243 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Container Wiring Error Classes.
+
+This module defines error classes specific to container wiring operations,
+providing granular error handling for service registration and resolution.
+"""
+
+from omnibase_core.enums import EnumCoreErrorCode
+from omnibase_infra.errors.error_infra import RuntimeHostError
+from omnibase_infra.models.errors.model_infra_error_context import (
+    ModelInfraErrorContext,
+)
+
+
+class ContainerWiringError(RuntimeHostError):
+    """Base error for container wiring operations.
+
+    Used as base class for all container wiring-related errors.
+    Provides common structured fields for container operations.
+
+    Example:
+        >>> context = ModelInfraErrorContext(
+        ...     transport_type=EnumInfraTransportType.RUNTIME,
+        ...     operation="wire_services",
+        ... )
+        >>> raise ContainerWiringError(
+        ...     "Container wiring failed",
+        ...     context=context,
+        ... )
+    """
+
+    def __init__(
+        self,
+        message: str,
+        context: ModelInfraErrorContext | None = None,
+        **extra_context: object,
+    ) -> None:
+        """Initialize ContainerWiringError.
+
+        Args:
+            message: Human-readable error message
+            context: Bundled infrastructure context
+            **extra_context: Additional context information
+        """
+        super().__init__(
+            message=message,
+            error_code=EnumCoreErrorCode.OPERATION_FAILED,
+            context=context,
+            **extra_context,
+        )
+
+
+class ServiceRegistrationError(ContainerWiringError):
+    """Raised when service registration fails.
+
+    Used for failures during service instance registration with the container,
+    including duplicate registrations, validation failures, or container API issues.
+
+    Example:
+        >>> context = ModelInfraErrorContext(
+        ...     transport_type=EnumInfraTransportType.RUNTIME,
+        ...     operation="register_service",
+        ... )
+        >>> raise ServiceRegistrationError(
+        ...     "Failed to register RegistryPolicy",
+        ...     service_name="RegistryPolicy",
+        ...     context=context,
+        ... )
+    """
+
+    def __init__(
+        self,
+        message: str,
+        service_name: str | None = None,
+        context: ModelInfraErrorContext | None = None,
+        **extra_context: object,
+    ) -> None:
+        """Initialize ServiceRegistrationError.
+
+        Args:
+            message: Human-readable error message
+            service_name: Name of the service that failed to register
+            context: Bundled infrastructure context
+            **extra_context: Additional context information
+        """
+        if service_name is not None:
+            extra_context["service_name"] = service_name
+
+        super().__init__(
+            message=message,
+            context=context,
+            **extra_context,
+        )
+
+
+class ServiceResolutionError(ContainerWiringError):
+    """Raised when service resolution fails.
+
+    Used for failures when attempting to resolve a service from the container,
+    including unregistered services, type mismatches, or container API issues.
+
+    Example:
+        >>> context = ModelInfraErrorContext(
+        ...     transport_type=EnumInfraTransportType.RUNTIME,
+        ...     operation="resolve_service",
+        ... )
+        >>> raise ServiceResolutionError(
+        ...     "RegistryPolicy not found in container",
+        ...     service_name="RegistryPolicy",
+        ...     context=context,
+        ... )
+    """
+
+    def __init__(
+        self,
+        message: str,
+        service_name: str | None = None,
+        context: ModelInfraErrorContext | None = None,
+        **extra_context: object,
+    ) -> None:
+        """Initialize ServiceResolutionError.
+
+        Args:
+            message: Human-readable error message
+            service_name: Name of the service that failed to resolve
+            context: Bundled infrastructure context
+            **extra_context: Additional context information
+        """
+        if service_name is not None:
+            extra_context["service_name"] = service_name
+
+        super().__init__(
+            message=message,
+            context=context,
+            **extra_context,
+        )
+
+
+class ContainerValidationError(ContainerWiringError):
+    """Raised when container validation fails.
+
+    Used for pre-wiring validation failures, such as missing required
+    container attributes or invalid container state.
+
+    Example:
+        >>> context = ModelInfraErrorContext(
+        ...     transport_type=EnumInfraTransportType.RUNTIME,
+        ...     operation="validate_container",
+        ... )
+        >>> raise ContainerValidationError(
+        ...     "Container missing service_registry attribute",
+        ...     context=context,
+        ...     missing_attribute="service_registry",
+        ... )
+    """
+
+    def __init__(
+        self,
+        message: str,
+        context: ModelInfraErrorContext | None = None,
+        **extra_context: object,
+    ) -> None:
+        """Initialize ContainerValidationError.
+
+        Args:
+            message: Human-readable error message
+            context: Bundled infrastructure context
+            **extra_context: Additional context information
+        """
+        super().__init__(
+            message=message,
+            context=context,
+            **extra_context,
+        )
+
+
+class ServiceRegistryUnavailableError(ContainerValidationError):
+    """Raised when container.service_registry is None.
+
+    This error indicates that the ModelONEXContainer was initialized
+    without a service registry, either because:
+    - enable_service_registry=False was passed
+    - The ServiceRegistry module is not installed/available
+    - Container initialization failed silently
+
+    This is a distinct error from generic ContainerValidationError to provide
+    clearer diagnostics and actionable error messages for service_registry issues.
+
+    Example:
+        >>> raise ServiceRegistryUnavailableError(
+        ...     "Container service_registry is None",
+        ...     operation="register RegistryPolicy",
+        ...     hint="Check that enable_service_registry=True",
+        ... )
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        operation: str | None = None,
+        hint: str | None = None,
+        context: ModelInfraErrorContext | None = None,
+        **extra_context: object,
+    ) -> None:
+        """Initialize ServiceRegistryUnavailableError.
+
+        Args:
+            message: Primary error message.
+            operation: The operation that was attempted (e.g., 'register_instance').
+            hint: Actionable hint for fixing the issue.
+            context: Bundled infrastructure context.
+            **extra_context: Additional context information.
+        """
+        # Build full message with operation and hint
+        full_message = message
+        if operation:
+            full_message = f"{message} (operation: {operation})"
+            extra_context["operation"] = operation
+
+        default_hint = (
+            "Ensure ModelONEXContainer is created with enable_service_registry=True "
+            "and that the ServiceRegistry module is installed."
+        )
+        actual_hint = hint or default_hint
+        full_message = f"{full_message}\nHint: {actual_hint}"
+        extra_context["hint"] = actual_hint
+
+        super().__init__(
+            message=full_message,
+            context=context,
+            **extra_context,
+        )
+
+
+__all__ = [
+    "ContainerValidationError",
+    "ContainerWiringError",
+    "ServiceRegistrationError",
+    "ServiceRegistryUnavailableError",
+    "ServiceResolutionError",
+]