omnibase_infra 0.2.6__py3-none-any.whl

omnibase_infra/errors/error_message_type_registry.py

@@ -0,0 +1,101 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""
+Message Type Registry Error.
+
+Provides the MessageTypeRegistryError class for message type registry operations.
+
+Related:
+    - OMN-937: Central Message Type Registry implementation
+    - RegistryMessageType: Registry that raises this error
+
+.. versionadded:: 0.5.0
+"""
+
+from __future__ import annotations
+
+__all__ = [
+    "MessageTypeRegistryError",
+]
+
+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,
+)
+from omnibase_infra.models.errors.model_message_type_registry_error_context import (
+    ModelMessageTypeRegistryErrorContext,
+)
+
+
+class MessageTypeRegistryError(RuntimeHostError):
+    """Error raised when message type registry operations fail.
+
+    Used for:
+    - Missing message type mappings
+    - Category constraint violations
+    - Domain constraint violations
+    - Registration validation failures
+
+    Extends RuntimeHostError for consistency with infrastructure error patterns.
+
+    Example:
+        >>> from omnibase_infra.errors import ModelInfraErrorContext
+        >>> from omnibase_infra.models.errors import ModelMessageTypeRegistryErrorContext
+        >>> from omnibase_infra.enums import EnumMessageCategory
+        >>> from uuid import uuid4
+        >>> try:
+        ...     handlers = registry.get_handlers("UnknownType", category, domain)
+        ... except MessageTypeRegistryError as e:
+        ...     print(f"Handler not found: {e}")
+        ...
+        >>> # With correlation context and registry context
+        >>> context = ModelInfraErrorContext.with_correlation(
+        ...     correlation_id=uuid4(),
+        ...     operation="get_handlers",
+        ... )
+        >>> registry_context = ModelMessageTypeRegistryErrorContext(
+        ...     message_type="UnknownType",
+        ...     domain="myapp.events",
+        ...     category=EnumMessageCategory.EVENT,
+        ... )
+        >>> raise MessageTypeRegistryError(
+        ...     "Message type not found",
+        ...     registry_context=registry_context,
+        ...     context=context,
+        ... )
+
+    .. versionadded:: 0.5.0
+    """
+
+    def __init__(
+        self,
+        message: str,
+        registry_context: ModelMessageTypeRegistryErrorContext | None = None,
+        context: ModelInfraErrorContext | None = None,
+        **extra_context: object,
+    ) -> None:
+        """Initialize MessageTypeRegistryError.
+
+        Args:
+            message: Human-readable error message
+            registry_context: Bundled registry-specific context (message_type, domain, category)
+            context: Bundled infrastructure context for correlation_id and structured fields
+            **extra_context: Additional context information
+        """
+        # Build extra context dict from registry context
+        extra: dict[str, object] = dict(extra_context)
+        if registry_context is not None:
+            if registry_context.message_type is not None:
+                extra["message_type"] = registry_context.message_type
+            if registry_context.domain is not None:
+                extra["domain"] = registry_context.domain
+            if registry_context.category is not None:
+                extra["category"] = registry_context.category.value
+
+        super().__init__(
+            message=message,
+            error_code=EnumCoreErrorCode.VALIDATION_FAILED,
+            context=context,
+            **extra,
+        )

omnibase_infra/errors/error_policy_registry.py

@@ -0,0 +1,115 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Policy Registry Error Class.
+
+This module defines the PolicyRegistryError for policy registry operations.
+"""
+
+from typing import Any, cast
+
+from omnibase_infra.enums import EnumPolicyType
+from omnibase_infra.errors.error_infra import RuntimeHostError
+from omnibase_infra.models.errors.model_infra_error_context import (
+    ModelInfraErrorContext,
+)
+from omnibase_infra.types import PolicyTypeInput
+
+
+class PolicyRegistryError(RuntimeHostError):
+    """Error raised when policy registry operations fail.
+
+    Used for:
+    - Attempting to get an unregistered policy
+    - Registration failures (async validation, duplicate registration)
+    - Invalid policy type identifiers
+    - Policy validation failures during registration
+
+    Extends RuntimeHostError as this is an infrastructure-layer runtime concern.
+
+    Type Safety:
+        The `policy_type` parameter accepts both `EnumPolicyType` enum values
+        and string literals for backward compatibility. Using `EnumPolicyType`
+        is strongly recommended for type safety and IDE autocomplete support.
+
+    Example:
+        >>> from omnibase_infra.errors import PolicyRegistryError
+        >>> from omnibase_infra.enums import EnumPolicyType
+        >>> from omnibase_infra.errors import ModelInfraErrorContext
+        >>> from omnibase_infra.enums import EnumInfraTransportType
+        >>> from uuid import uuid4
+
+        >>> # RECOMMENDED: Using EnumPolicyType for type safety
+        >>> try:
+        ...     policy = registry.get("unknown_policy_id")
+        ... except PolicyRegistryError as e:
+        ...     print(f"Policy not found: {e}")
+
+        >>> # With context and EnumPolicyType (preferred approach)
+        >>> context = ModelInfraErrorContext(
+        ...     transport_type=EnumInfraTransportType.RUNTIME,
+        ...     operation="get_policy",
+        ...     correlation_id=uuid4(),
+        ... )
+        >>> raise PolicyRegistryError(
+        ...     "Policy not registered",
+        ...     policy_id="rate_limit_default",
+        ...     policy_type=EnumPolicyType.ORCHESTRATOR,  # Type-safe enum
+        ...     context=context,
+        ... )
+
+        >>> # Reducer policy example
+        >>> raise PolicyRegistryError(
+        ...     "Reducer policy validation failed",
+        ...     policy_id="state_merger",
+        ...     policy_type=EnumPolicyType.REDUCER,  # Type-safe enum
+        ... )
+
+        >>> # Backward compatible with string (legacy)
+        >>> raise PolicyRegistryError(
+        ...     "Policy not registered",
+        ...     policy_id="rate_limit_default",
+        ...     policy_type="orchestrator",  # String (legacy support)
+        ... )
+    """
+
+    def __init__(
+        self,
+        message: str,
+        policy_id: str | None = None,
+        policy_type: PolicyTypeInput | None = None,
+        context: ModelInfraErrorContext | None = None,
+        **extra_context: object,
+    ) -> None:
+        """Initialize PolicyRegistryError.
+
+        Args:
+            message: Human-readable error message
+            policy_id: The policy ID that caused the error (if applicable)
+            policy_type: The policy type that caused the error. Accepts:
+                - EnumPolicyType.ORCHESTRATOR or EnumPolicyType.REDUCER (recommended)
+                - "orchestrator" or "reducer" string (legacy support)
+                The enum value will be automatically converted to its string
+                representation for serialization.
+            context: Bundled infrastructure context for correlation_id and structured fields
+            **extra_context: Additional context information
+        """
+        # Add policy_id and policy_type to extra_context if provided
+        if policy_id is not None:
+            extra_context["policy_id"] = policy_id
+        if policy_type is not None:
+            # Convert EnumPolicyType to string for serialization
+            extra_context["policy_type"] = (
+                policy_type.value
+                if isinstance(policy_type, EnumPolicyType)
+                else policy_type
+            )
+
+        # 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__ = ["PolicyRegistryError"]

omnibase_infra/errors/error_vault.py

@@ -0,0 +1,123 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Vault-Specific Infrastructure Error Class.
+
+This module defines the InfraVaultError class for Vault-related infrastructure
+errors. It extends InfraConnectionError to provide specialized error handling
+for HashiCorp Vault operations.
+
+Security Note:
+    Secret paths are automatically sanitized when stored in error context
+    to prevent exposure of infrastructure topology and credential organization.
+    Full paths are only logged at DEBUG level if needed for debugging.
+"""
+
+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_secret_path
+
+
+class InfraVaultError(InfraConnectionError):
+    """Error communicating with Vault.
+
+    Used for Vault client initialization failures, secret operations,
+    token management, and retry exhaustion scenarios.
+
+    This error extends InfraConnectionError and is specifically designed
+    for HashiCorp Vault operations. The context should use
+    ``transport_type=EnumInfraTransportType.VAULT``.
+
+    Common use cases:
+        - Vault client initialization failures
+        - Secret read/write operation failures
+        - Token renewal or management errors
+        - Connection retry exhaustion
+        - Vault seal/unseal operation errors
+
+    Security:
+        Secret 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 mount point, e.g.,
+        "secret/data/myapp/db/creds" becomes "secret/***/***".
+
+    Example:
+        >>> from omnibase_infra.enums import EnumInfraTransportType
+        >>> context = ModelInfraErrorContext(
+        ...     transport_type=EnumInfraTransportType.VAULT,
+        ...     operation="read_secret",
+        ...     target_name="vault-primary",
+        ... )
+        >>> # Secret path will be sanitized to "secret/***/***" in error context
+        >>> raise InfraVaultError(
+        ...     "Failed to read secret from Vault",
+        ...     context=context,
+        ...     secret_path="secret/data/myapp/credentials",
+        ... )
+
+        >>> # Token renewal failure
+        >>> context = ModelInfraErrorContext(
+        ...     transport_type=EnumInfraTransportType.VAULT,
+        ...     operation="renew_token",
+        ...     target_name="vault-primary",
+        ... )
+        >>> raise InfraVaultError(
+        ...     "Vault token renewal failed",
+        ...     context=context,
+        ...     retry_count=3,
+        ... )
+
+        >>> # Client initialization failure
+        >>> context = ModelInfraErrorContext(
+        ...     transport_type=EnumInfraTransportType.VAULT,
+        ...     operation="initialize_client",
+        ...     target_name="vault-primary",
+        ... )
+        >>> raise InfraVaultError(
+        ...     "Failed to initialize Vault client",
+        ...     context=context,
+        ...     host="vault.example.com",
+        ...     port=8200,
+        ... )
+    """
+
+    def __init__(
+        self,
+        message: str,
+        context: ModelInfraErrorContext | None = None,
+        secret_path: str | None = None,
+        **extra_context: object,
+    ) -> None:
+        """Initialize InfraVaultError with Vault-specific context.
+
+        Args:
+            message: Human-readable error message
+            context: Bundled infrastructure context (should use VAULT transport_type)
+            secret_path: Optional path to the secret that caused the error.
+                This path is automatically sanitized to mask sensitive segments
+                (e.g., "secret/data/myapp/creds" -> "secret/***/***").
+            **extra_context: Additional context information (e.g., host, port, retry_count)
+
+        Security:
+            The secret_path is sanitized before being stored in extra_context
+            to prevent exposure of infrastructure topology in error messages,
+            logs, and metrics. Only the mount point is preserved.
+        """
+        # Include sanitized secret_path in extra_context if provided
+        # This prevents exposure of full secret paths in error messages/logs
+        if secret_path is not None:
+            sanitized_path = sanitize_secret_path(secret_path)
+            if sanitized_path:
+                extra_context["secret_path"] = sanitized_path
+
+        super().__init__(
+            message=message,
+            context=context,
+            **extra_context,
+        )
+
+
+__all__: list[str] = [
+    "InfraVaultError",
+]

omnibase_infra/event_bus/__init__.py

@@ -0,0 +1,72 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Event bus implementations for omnibase_infra.
+
+This module provides event bus implementations for the ONEX infrastructure.
+Two implementations are supported:
+- EventBusInmemory: For unit testing and local development without external dependencies
+- EventBusKafka: For production use with Kafka/Redpanda (see event_bus_kafka.py)
+
+Event bus selection is handled by kernel.py at bootstrap time based on:
+- KAFKA_BOOTSTRAP_SERVERS environment variable (if set, uses EventBusKafka)
+- config.event_bus.type field in runtime_config.yaml
+
+Exports:
+    EventBusInmemory: In-memory event bus for local testing and development
+    ModelEventHeaders: Event headers model for message metadata
+    ModelEventMessage: Event message model wrapping topic, key, value, and headers
+
+Topic Constants:
+    DLQ_TOPIC_VERSION: Current DLQ topic version
+    DLQ_DOMAIN: DLQ domain identifier
+    DLQ_INTENT_TOPIC_SUFFIX: Suffix for intent DLQ topics
+    DLQ_EVENT_TOPIC_SUFFIX: Suffix for event DLQ topics
+    DLQ_COMMAND_TOPIC_SUFFIX: Suffix for command DLQ topics
+    DLQ_CATEGORY_SUFFIXES: Mapping of categories to DLQ suffixes
+    DLQ_TOPIC_PATTERN: Regex pattern for DLQ topic validation
+    build_dlq_topic: Build a DLQ topic from components
+    parse_dlq_topic: Parse a DLQ topic into components
+    is_dlq_topic: Check if a topic is a DLQ topic
+    get_dlq_topic_for_original: Get DLQ topic for an original topic
+"""
+
+from __future__ import annotations
+
+from omnibase_infra.event_bus.event_bus_inmemory import (
+    EventBusInmemory,
+    ModelEventHeaders,
+    ModelEventMessage,
+)
+from omnibase_infra.event_bus.topic_constants import (
+    DLQ_CATEGORY_SUFFIXES,
+    DLQ_COMMAND_TOPIC_SUFFIX,
+    DLQ_DOMAIN,
+    DLQ_EVENT_TOPIC_SUFFIX,
+    DLQ_INTENT_TOPIC_SUFFIX,
+    DLQ_TOPIC_PATTERN,
+    DLQ_TOPIC_VERSION,
+    build_dlq_topic,
+    get_dlq_topic_for_original,
+    is_dlq_topic,
+    parse_dlq_topic,
+)
+
+__all__: list[str] = [
+    "DLQ_CATEGORY_SUFFIXES",
+    "DLQ_COMMAND_TOPIC_SUFFIX",
+    "DLQ_DOMAIN",
+    "DLQ_EVENT_TOPIC_SUFFIX",
+    "DLQ_INTENT_TOPIC_SUFFIX",
+    "DLQ_TOPIC_PATTERN",
+    # Topic Constants
+    "DLQ_TOPIC_VERSION",
+    # Event Bus
+    "EventBusInmemory",
+    "ModelEventHeaders",
+    "ModelEventMessage",
+    # Topic Functions
+    "build_dlq_topic",
+    "get_dlq_topic_for_original",
+    "is_dlq_topic",
+    "parse_dlq_topic",
+]

omnibase_infra/event_bus/configs/kafka_event_bus_config.yaml

@@ -0,0 +1,84 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+#
+# KafkaEventBus Configuration
+# ===========================
+# This file provides default configuration for the KafkaEventBus implementation.
+#
+# IMPORTANT: Environment Variable Substitution Mechanism
+# -------------------------------------------------------
+# The ${VAR_NAME:-default} syntax in this file is NOT processed by yaml.safe_load().
+# YAML reads these as literal strings (e.g., "${KAFKA_BOOTSTRAP_SERVERS:-localhost:9092}").
+#
+# Environment variable substitution happens AFTER YAML parsing in
+# ModelKafkaEventBusConfig.apply_environment_overrides(), which:
+# 1. Loads this file with yaml.safe_load() (treats ${...} as literal strings)
+# 2. Checks os.environ for matching environment variables (KAFKA_BOOTSTRAP_SERVERS, etc.)
+# 3. Overrides config values if environment variables are set
+# 4. Falls back to the literal defaults from this file if environment variables are not set
+#
+# Example: If KAFKA_BOOTSTRAP_SERVERS="kafka:9092" is set in environment:
+#   - YAML loads: bootstrap_servers: "${KAFKA_BOOTSTRAP_SERVERS:-localhost:9092}"
+#   - apply_environment_overrides() detects KAFKA_BOOTSTRAP_SERVERS env var
+#   - Final value: "kafka:9092" (from environment, not from ${...} syntax)
+#
+# The ${...} syntax is used for documentation purposes to indicate which
+# environment variables can override each configuration value.
+#
+# The KafkaEventBus implements ProtocolEventBus using Apache Kafka (via aiokafka)
+# for production-grade message delivery with resilience patterns including circuit
+# breaker, retry with exponential backoff, and graceful degradation.
+# =============================================================================
+# Connection Settings
+# =============================================================================
+# Kafka broker connection configuration
+# Comma-separated list of Kafka broker addresses
+bootstrap_servers: "${KAFKA_BOOTSTRAP_SERVERS:-localhost:9092}"
+# Environment identifier for message routing (e.g., "local", "dev", "staging", "prod")
+environment: "${KAFKA_ENVIRONMENT:-local}"
+# =============================================================================
+# Timeout and Retry Settings
+# =============================================================================
+# Controls operation timeouts and retry behavior for resilience
+
+# Timeout in seconds for Kafka operations (connect, publish, etc.)
+timeout_seconds: ${KAFKA_TIMEOUT_SECONDS:-30}
+# Maximum number of retry attempts for publish operations before failing
+max_retry_attempts: ${KAFKA_MAX_RETRY_ATTEMPTS:-3}
+# Base delay in seconds for exponential backoff between retries
+# Actual delay = retry_backoff_base * (2 ^ attempt) * random_jitter(0.5, 1.5)
+retry_backoff_base: ${KAFKA_RETRY_BACKOFF_BASE:-1.0}
+# =============================================================================
+# Circuit Breaker Settings
+# =============================================================================
+# Protects against cascading failures when Kafka is unavailable
+
+# Number of consecutive failures before circuit opens (blocks requests)
+circuit_breaker_threshold: ${KAFKA_CIRCUIT_BREAKER_THRESHOLD:-5}
+# Seconds before circuit breaker resets from open to half-open state
+# In half-open state, a single successful operation resets the circuit
+circuit_breaker_reset_timeout: ${KAFKA_CIRCUIT_BREAKER_RESET_TIMEOUT:-30.0}
+# =============================================================================
+# Consumer Settings
+# =============================================================================
+# Configuration for Kafka consumer behavior
+
+# Sleep interval in seconds between consumer poll iterations
+consumer_sleep_interval: ${KAFKA_CONSUMER_SLEEP_INTERVAL:-0.1}
+# Where to start reading messages when no committed offset exists
+# Options: "earliest" (beginning), "latest" (end of topic)
+auto_offset_reset: "${KAFKA_AUTO_OFFSET_RESET:-latest}"
+# Whether to automatically commit consumer offsets
+# Set to false for manual offset management
+enable_auto_commit: ${KAFKA_ENABLE_AUTO_COMMIT:-true}
+# =============================================================================
+# Producer Settings
+# =============================================================================
+# Configuration for Kafka producer behavior
+
+# Acknowledgment mode for message delivery confirmation
+# Options: "0" (no ack), "1" (leader ack), "all" (all replicas ack)
+acks: "${KAFKA_ACKS:-all}"
+# Enable idempotent producer to prevent duplicate messages
+# Recommended for exactly-once semantics
+enable_idempotence: ${KAFKA_ENABLE_IDEMPOTENCE:-true}