omnibase_infra 0.2.1__py3-none-any.whl

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

omnibase_infra/errors/error_event_bus_registry.py

@@ -0,0 +1,102 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Event Bus Registry Error Class.
+
+This module defines the EventBusRegistryError for event bus registry operations.
+"""
+
+from omnibase_infra.errors.error_infra import RuntimeHostError
+from omnibase_infra.models.errors.model_infra_error_context import (
+    ModelInfraErrorContext,
+)
+
+
+class EventBusRegistryError(RuntimeHostError):
+    """Error raised when event bus registry operations fail.
+
+    Used for:
+    - Attempting to get an unregistered event bus kind
+    - Registration failures (duplicate registration, protocol validation)
+    - Event bus class validation failures during registration
+    - Invalid bus_kind identifiers
+
+    Extends RuntimeHostError as this is an infrastructure-layer runtime concern.
+
+    Example:
+        >>> from omnibase_infra.errors import EventBusRegistryError
+        >>> from omnibase_infra.errors import ModelInfraErrorContext
+        >>> from omnibase_infra.enums import EnumInfraTransportType
+        >>> from uuid import uuid4
+
+        >>> # Bus kind not found
+        >>> try:
+        ...     bus_cls = registry.get("unknown_bus")
+        ... except EventBusRegistryError as e:
+        ...     print(f"Event bus not found: {e}")
+
+        >>> # With context
+        >>> context = ModelInfraErrorContext(
+        ...     transport_type=EnumInfraTransportType.KAFKA,
+        ...     operation="get_bus",
+        ...     correlation_id=uuid4(),
+        ... )
+        >>> raise EventBusRegistryError(
+        ...     "Event bus kind not registered",
+        ...     bus_kind="kafka",
+        ...     context=context,
+        ... )
+
+        >>> # Protocol validation failure
+        >>> raise EventBusRegistryError(
+        ...     "Event bus class does not implement ProtocolEventBus",
+        ...     bus_kind="custom",
+        ...     bus_class="InvalidBus",
+        ... )
+
+        >>> # Duplicate registration
+        >>> raise EventBusRegistryError(
+        ...     "Event bus kind is already registered",
+        ...     bus_kind="inmemory",
+        ...     existing_class="EventBusInmemory",
+        ... )
+    """
+
+    def __init__(
+        self,
+        message: str,
+        bus_kind: str | None = None,
+        bus_class: str | None = None,
+        available_kinds: list[str] | None = None,
+        existing_class: str | None = None,
+        context: ModelInfraErrorContext | None = None,
+        **extra_context: object,
+    ) -> None:
+        """Initialize EventBusRegistryError.
+
+        Args:
+            message: Human-readable error message
+            bus_kind: The bus kind that caused the error (if applicable)
+            bus_class: The bus class name that caused the error (if applicable)
+            available_kinds: List of currently registered bus kinds (for error context)
+            existing_class: Name of already registered class (for duplicate registration)
+            context: Bundled infrastructure context for correlation_id and structured fields
+            **extra_context: Additional context information
+        """
+        # Add domain-specific fields to extra_context if provided
+        if bus_kind is not None:
+            extra_context["bus_kind"] = bus_kind
+        if bus_class is not None:
+            extra_context["bus_class"] = bus_class
+        if available_kinds is not None:
+            extra_context["available_kinds"] = available_kinds
+        if existing_class is not None:
+            extra_context["existing_class"] = existing_class
+
+        super().__init__(
+            message=message,
+            context=context,
+            **extra_context,
+        )
+
+
+__all__ = ["EventBusRegistryError"]