omnibase_infra 0.2.1__py3-none-any.whl

omnibase_infra/enums/enum_validation_severity.py

@@ -0,0 +1,78 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Validation severity levels for security and other validation errors.
+
+This module defines the severity levels used in validation error models.
+Severity indicates the impact and urgency of addressing a validation failure.
+
+Severity Levels:
+    - ERROR: Standard validation failure that must be addressed
+    - CRITICAL: Severe failure that poses security or stability risk
+    - WARNING: Advisory issue that should be reviewed but may not block
+    - INFO: Informational only, does not block operations
+
+Usage:
+    Used in ModelSecurityError and other validation error models to
+    provide structured severity classification.
+
+See Also:
+    - ModelSecurityError: Security validation error model
+    - ModelSecurityValidationResult: Complete validation result container
+"""
+
+from enum import StrEnum
+
+
+class EnumValidationSeverity(StrEnum):
+    """Validation error severity levels.
+
+    Classifies the severity of validation errors to indicate their
+    impact and urgency. Used in security validation, architecture
+    validation, and other validation contexts.
+
+    Attributes:
+        ERROR: Standard validation failure. The validation constraint
+            was violated and must be addressed before proceeding.
+            This is the default severity level. Blocks startup.
+        CRITICAL: Severe validation failure. Indicates a security risk,
+            data integrity issue, or system stability concern that
+            requires immediate attention. Blocks startup.
+        WARNING: Advisory issue. The validation identified a potential
+            problem that should be reviewed but may not necessarily
+            block the operation. Does not block startup.
+        INFO: Informational only. Provides context or suggestions
+            without indicating any problem. Does not block startup.
+
+    Example:
+        >>> from omnibase_infra.enums import EnumValidationSeverity
+        >>> severity = EnumValidationSeverity.ERROR
+        >>> severity.value
+        'error'
+        >>> severity == "error"
+        True
+        >>> severity.blocks_startup()
+        True
+        >>> EnumValidationSeverity.INFO.blocks_startup()
+        False
+
+    See Also:
+        - ModelSecurityError: Uses this enum for severity classification
+        - EnumSecurityRuleId: Security validation rule identifiers
+    """
+
+    ERROR = "error"
+    CRITICAL = "critical"
+    WARNING = "warning"
+    INFO = "info"
+
+    def blocks_startup(self) -> bool:
+        """Whether this severity level should block runtime startup.
+
+        Returns:
+            True if this severity level should prevent the runtime from
+            starting when a violation is detected.
+        """
+        return self in (EnumValidationSeverity.ERROR, EnumValidationSeverity.CRITICAL)
+
+
+__all__ = ["EnumValidationSeverity"]

omnibase_infra/errors/__init__.py

@@ -0,0 +1,156 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""ONEX Infrastructure Errors Module.
+
+This module provides infrastructure-specific error classes and error handling
+utilities for the omnibase_infra package. All errors extend from OnexError
+to maintain consistency with the ONEX error handling patterns.
+
+Exports:
+    ModelInfraErrorContext: Configuration model for bundled error context
+    RuntimeHostError: Base infrastructure error class
+    ProtocolConfigurationError: Protocol configuration validation errors
+    SecretResolutionError: Secret/credential resolution errors
+    InfraConnectionError: Infrastructure connection errors
+    InfraTimeoutError: Infrastructure timeout errors
+    InfraAuthenticationError: Infrastructure authentication errors
+    InfraUnavailableError: Infrastructure resource unavailable errors
+    EnvelopeValidationError: Envelope validation errors (pre-dispatch)
+    UnknownHandlerTypeError: Unknown handler type prefix errors
+    PolicyRegistryError: Policy registry operation errors
+    ComputeRegistryError: Compute registry operation errors
+    EventBusRegistryError: Event bus registry operation errors
+    ChainPropagationError: Correlation/causation chain validation errors
+    ArchitectureViolationError: Architecture validation errors (blocks startup)
+
+Correlation ID Assignment:
+    All infrastructure errors support correlation_id for distributed tracing.
+    Follow these rules when assigning correlation IDs:
+
+    - Always propagate correlation_id from incoming requests to error context
+    - If no correlation_id exists in the request, generate one using uuid4()
+    - Use UUID4 format for all new correlation IDs (from uuid import uuid4)
+    - Include correlation_id in all error context for distributed tracing
+    - Preserve correlation_id as UUID objects throughout the system (strong typing)
+
+    Example::
+
+        from uuid import UUID, uuid4
+        from omnibase_infra.errors import InfraConnectionError, ModelInfraErrorContext
+        from omnibase_infra.enums import EnumInfraTransportType
+
+        # Propagate from request or generate new
+        correlation_id = request.correlation_id or uuid4()
+
+        context = ModelInfraErrorContext(
+            transport_type=EnumInfraTransportType.DATABASE,
+            operation="execute_query",
+            target_name="postgresql-primary",
+            correlation_id=correlation_id,
+        )
+        raise InfraConnectionError("Failed to connect", context=context) from e
+
+Error Sanitization Guidelines:
+    NEVER include in error messages or context:
+        - Passwords, API keys, tokens, or secrets
+        - Full connection strings with credentials
+        - PII (names, emails, SSNs, phone numbers)
+        - Internal IP addresses (in production logs)
+        - Private keys or certificates
+        - Session tokens or cookies
+
+    SAFE to include:
+        - Service names (e.g., "postgresql", "kafka")
+        - Operation names (e.g., "connect", "query", "authenticate")
+        - Correlation IDs (always include for tracing)
+        - Error codes (e.g., EnumCoreErrorCode.DATABASE_CONNECTION_ERROR)
+        - Sanitized hostnames (e.g., "db.example.com")
+        - Port numbers
+        - Retry counts and timeout values
+        - Resource identifiers (non-sensitive)
+
+    Example - BAD (exposes credentials)::
+
+        raise InfraConnectionError(
+            f"Failed to connect with password={password}",  # NEVER DO THIS
+            context=context,
+        )
+
+    Example - GOOD (sanitized)::
+
+        raise InfraConnectionError(
+            "Failed to connect to database",
+            context=context,
+            host="db.example.com",
+            port=5432,
+            retry_count=3,
+        )
+"""
+
+from omnibase_infra.errors.error_architecture_violation import (
+    ArchitectureViolationError,
+)
+from omnibase_infra.errors.error_chain_propagation import ChainPropagationError
+from omnibase_infra.errors.error_compute_registry import ComputeRegistryError
+from omnibase_infra.errors.error_consul import InfraConsulError
+from omnibase_infra.errors.error_container_wiring import (
+    ContainerValidationError,
+    ContainerWiringError,
+    ServiceRegistrationError,
+    ServiceRegistryUnavailableError,
+    ServiceResolutionError,
+)
+from omnibase_infra.errors.error_event_bus_registry import EventBusRegistryError
+from omnibase_infra.errors.error_infra import (
+    EnvelopeValidationError,
+    InfraAuthenticationError,
+    InfraConnectionError,
+    InfraTimeoutError,
+    InfraUnavailableError,
+    ProtocolConfigurationError,
+    RuntimeHostError,
+    SecretResolutionError,
+    UnknownHandlerTypeError,
+)
+from omnibase_infra.errors.error_message_type_registry import MessageTypeRegistryError
+from omnibase_infra.errors.error_policy_registry import PolicyRegistryError
+from omnibase_infra.errors.error_vault import InfraVaultError
+from omnibase_infra.models.errors.model_infra_error_context import (
+    ModelInfraErrorContext,
+)
+from omnibase_infra.models.errors.model_timeout_error_context import (
+    ModelTimeoutErrorContext,
+)
+
+__all__: list[str] = [
+    # Architecture validation errors
+    "ArchitectureViolationError",
+    "ChainPropagationError",
+    "ComputeRegistryError",
+    "ContainerValidationError",
+    # Container wiring errors
+    "ContainerWiringError",
+    "EnvelopeValidationError",
+    "EventBusRegistryError",
+    "InfraAuthenticationError",
+    "InfraConnectionError",
+    # Service-specific connection errors
+    "InfraConsulError",
+    "InfraTimeoutError",
+    "InfraUnavailableError",
+    "InfraVaultError",
+    # Message type registry errors
+    "MessageTypeRegistryError",
+    # Configuration models
+    "ModelInfraErrorContext",
+    "ModelTimeoutErrorContext",
+    "PolicyRegistryError",
+    "ProtocolConfigurationError",
+    # Error classes
+    "RuntimeHostError",
+    "SecretResolutionError",
+    "ServiceRegistrationError",
+    "ServiceRegistryUnavailableError",
+    "ServiceResolutionError",
+    "UnknownHandlerTypeError",
+]

omnibase_infra/errors/error_architecture_violation.py

@@ -0,0 +1,152 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Architecture Violation Error.
+
+This module defines the error raised when architecture validation fails during
+runtime startup. The error contains detailed information about all blocking
+violations that prevented startup.
+
+Related:
+    - OMN-1138: Architecture Validator for omnibase_infra
+    - RuntimeHostProcess: Validates architecture before starting
+
+Example:
+    >>> from omnibase_infra.errors import ArchitectureViolationError
+    >>> from omnibase_infra.nodes.architecture_validator import ModelArchitectureViolation
+    >>>
+    >>> violations = (
+    ...     ModelArchitectureViolation(
+    ...         rule_id="NO_HANDLER_PUBLISHING",
+    ...         rule_name="No Handler Publishing",
+    ...         severity=EnumValidationSeverity.ERROR,
+    ...         target_type="handler",
+    ...         target_name="MyHandler",
+    ...         message="Handler must not have direct event bus access",
+    ...     ),
+    ... )
+    >>> raise ArchitectureViolationError(
+    ...     message=f"Architecture validation failed with {len(violations)} blocking violations",
+    ...     violations=violations,
+    ... )
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+from uuid import UUID, uuid4
+
+from omnibase_core.enums.enum_core_error_code import EnumCoreErrorCode
+from omnibase_infra.enums import EnumInfraTransportType
+from omnibase_infra.errors.error_infra import RuntimeHostError
+from omnibase_infra.models.errors.model_infra_error_context import (
+    ModelInfraErrorContext,
+)
+
+if TYPE_CHECKING:
+    from omnibase_infra.nodes.architecture_validator import ModelArchitectureViolation
+
+
+class ArchitectureViolationError(RuntimeHostError):
+    """Error raised when architecture validation fails during startup.
+
+    This error is raised by RuntimeHostProcess when architecture validation
+    detects blocking violations (ERROR severity) that should prevent runtime
+    startup. The error contains all blocking violations for inspection.
+
+    Use this error to:
+    - Block runtime startup when architecture rules are violated
+    - Report detailed violation information for debugging
+    - Provide context for CI/CD pipeline failures
+
+    Attributes:
+        violations: Tuple of architecture violations that caused the failure.
+            Only violations with ERROR severity should be included.
+
+    Example:
+        >>> # In RuntimeHostProcess._validate_architecture:
+        >>> blocking_violations = tuple(
+        ...     v for v in result.violations if v.blocks_startup()
+        ... )
+        >>> if blocking_violations:
+        ...     raise ArchitectureViolationError(
+        ...         message=f"Architecture validation failed with {len(blocking_violations)} blocking violations",
+        ...         violations=blocking_violations,
+        ...     )
+
+        >>> # Catching and inspecting the error:
+        >>> try:
+        ...     await runtime.start()
+        ... except ArchitectureViolationError as e:
+        ...     for v in e.violations:
+        ...         print(v.format_for_logging())
+        ...     sys.exit(1)
+    """
+
+    def __init__(
+        self,
+        message: str,
+        violations: tuple[ModelArchitectureViolation, ...],
+        context: ModelInfraErrorContext | None = None,
+        correlation_id: UUID | None = None,
+        **extra_context: object,
+    ) -> None:
+        """Initialize ArchitectureViolationError.
+
+        Args:
+            message: Human-readable error message describing the validation failure.
+            violations: Tuple of architecture violations that caused the failure.
+                Should only include violations with ERROR severity (blocking).
+            context: Optional infrastructure error context. If not provided,
+                a default context for architecture validation is created.
+            correlation_id: Optional correlation ID for distributed tracing.
+                Used when building the default context if context is None.
+                Auto-generated using uuid4() if not provided.
+            **extra_context: Additional context information for debugging.
+
+        Example:
+            >>> raise ArchitectureViolationError(
+            ...     message="Architecture validation failed with 3 blocking violations",
+            ...     violations=blocking_violations,
+            ...     correlation_id=request_correlation_id,
+            ... )
+        """
+        self.violations = violations
+
+        # Auto-generate correlation_id if not provided (per ONEX standards)
+        if correlation_id is None:
+            correlation_id = uuid4()
+
+        # Build default context if not provided
+        if context is None:
+            context = ModelInfraErrorContext(
+                transport_type=EnumInfraTransportType.RUNTIME,
+                operation="validate_architecture",
+                correlation_id=correlation_id,
+            )
+
+        # Add violation summary to extra context
+        extra_context["violation_count"] = len(violations)
+        extra_context["violation_rule_ids"] = tuple(v.rule_id for v in violations)
+
+        super().__init__(
+            message=message,
+            error_code=EnumCoreErrorCode.CONTRACT_VIOLATION,
+            context=context,
+            **extra_context,
+        )
+
+    def format_violations(self) -> str:
+        """Format all violations for display.
+
+        Returns:
+            Multi-line string with each violation formatted for logging.
+
+        Example:
+            >>> print(error.format_violations())
+            [ERROR] NO_HANDLER_PUBLISHING (No Handler Publishing) on handler/MyHandler: ...
+            [ERROR] NO_ANY_TYPES (No Any Types) on model/MyModel: ...
+        """
+        return "\n".join(v.format_for_logging() for v in self.violations)
+
+
+__all__ = ["ArchitectureViolationError"]

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,92 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Compute Registry Error Class.
+
+This module defines the ComputeRegistryError for compute registry operations.
+"""
+
+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
+
+        super().__init__(
+            message=message,
+            context=context,
+            **extra_context,
+        )
+
+
+__all__ = ["ComputeRegistryError"]