omnibase_infra 0.2.6__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,160 @@
+# 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)
+    BindingResolutionError: Binding resolution errors (declarative operation bindings)
+
+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_binding_resolution import BindingResolutionError
+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",
+    # Binding resolution errors
+    "BindingResolutionError",
+    "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_binding_resolution.py

@@ -0,0 +1,128 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Binding Resolution Error for declarative operation bindings.
+
+This module defines the error raised when binding resolution fails during
+declarative operation processing. Bindings use ${source.path} expressions
+to extract values from envelopes, payloads, or context.
+"""
+
+from uuid import UUID
+
+from omnibase_core.enums 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,
+)
+
+
+class BindingResolutionError(RuntimeHostError):
+    """Error when binding resolution fails.
+
+    Raised when a required binding cannot be resolved from the envelope,
+    payload, or context. Includes full diagnostic context for debugging.
+
+    This error is typically raised during declarative operation processing
+    when a ${source.path} expression cannot be resolved because:
+    - The source (payload, envelope, context) is missing
+    - A path segment does not exist in the source
+    - The value is required but None
+
+    Attributes:
+        operation_name: The operation being resolved (e.g., "db.query")
+        parameter_name: The parameter that failed (e.g., "sql")
+        expression: The ${source.path} expression that failed (e.g., "${payload.sql}")
+        missing_segment: Which path segment was not found (if applicable)
+        binding_correlation_id: Request correlation for tracing (stored separately from context)
+
+    Example:
+        >>> context = ModelInfraErrorContext.with_correlation(
+        ...     transport_type=EnumInfraTransportType.RUNTIME,
+        ...     operation="binding_resolution",
+        ...     target_name="db.query",
+        ... )
+        >>> raise BindingResolutionError(
+        ...     "Required parameter 'sql' could not be resolved",
+        ...     operation_name="db.query",
+        ...     parameter_name="sql",
+        ...     expression="${payload.sql}",
+        ...     missing_segment="sql",
+        ...     context=context,
+        ... )
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        operation_name: str,
+        parameter_name: str,
+        expression: str,
+        missing_segment: str | None = None,
+        correlation_id: UUID | None = None,
+        context: ModelInfraErrorContext | None = None,
+    ) -> None:
+        """Initialize binding resolution error.
+
+        Args:
+            message: Human-readable error description
+            operation_name: Operation being resolved (e.g., "db.query")
+            parameter_name: Parameter that failed (e.g., "sql")
+            expression: Original expression (e.g., "${payload.sql}")
+            missing_segment: Path segment not found (e.g., "sql")
+            correlation_id: Request correlation ID (used if context not provided)
+            context: Infrastructure error context (preferred over correlation_id)
+        """
+        self.operation_name = operation_name
+        self.parameter_name = parameter_name
+        self.expression = expression
+        self.missing_segment = missing_segment
+        # Store binding-specific correlation_id separately
+        self.binding_correlation_id = correlation_id
+
+        # Build context if not provided
+        if context is None:
+            context = ModelInfraErrorContext.with_correlation(
+                correlation_id=correlation_id,
+                transport_type=EnumInfraTransportType.RUNTIME,
+                operation="binding_resolution",
+                target_name=operation_name,
+            )
+
+        super().__init__(
+            message=message,
+            error_code=EnumCoreErrorCode.INVALID_INPUT,
+            context=context,
+            operation_name=operation_name,
+            parameter_name=parameter_name,
+            expression=expression,
+            missing_segment=missing_segment,
+        )
+
+    def __str__(self) -> str:
+        """Return detailed error message with diagnostic info.
+
+        Provides a structured diagnostic message that includes all relevant
+        context for debugging binding resolution failures.
+
+        Returns:
+            Pipe-delimited string with operation, parameter, expression,
+            and optionally missing segment and correlation ID.
+        """
+        parts = [
+            f"Binding resolution failed for operation '{self.operation_name}'",
+            f"Parameter: {self.parameter_name}",
+            f"Expression: {self.expression}",
+        ]
+        if self.missing_segment:
+            parts.append(f"Missing segment: {self.missing_segment}")
+        # Include correlation_id from context (model attribute, always present after __init__)
+        if hasattr(self, "model") and self.model.correlation_id:
+            parts.append(f"Correlation ID: {self.model.correlation_id}")
+        elif self.binding_correlation_id:
+            parts.append(f"Correlation ID: {self.binding_correlation_id}")
+        return " | ".join(parts)
+
+
+__all__ = ["BindingResolutionError"]