omnibase_infra 0.2.1__py3-none-any.whl

omnibase_infra/event_bus/models/model_dlq_event.py

@@ -0,0 +1,206 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Dead Letter Queue event model for callback payloads.
+
+Provides a strongly-typed model for DLQ events that captures all relevant
+context for alerting, monitoring, and debugging failed message processing.
+
+This model is passed to DLQ callback hooks when messages are published to
+the dead letter queue, enabling custom alerting integration (PagerDuty,
+Slack, email, etc.) without coupling the EventBusKafka to specific
+alerting implementations.
+
+Example:
+    ```python
+    from omnibase_infra.event_bus.models import ModelDlqEvent
+
+    async def alert_on_dlq(event: ModelDlqEvent) -> None:
+        '''Custom alerting callback for DLQ events.'''
+        if event.success:
+            logger.warning(
+                "Message sent to DLQ",
+                extra=event.to_log_context(),
+            )
+        else:
+            # DLQ publish itself failed - critical alert
+            pagerduty.trigger(
+                summary=f"DLQ publish failed: {event.dlq_error_type}",
+                severity="critical",
+                details=event.to_log_context(),
+            )
+    ```
+
+See Also:
+    ModelDlqMetrics: Aggregate metrics for DLQ operations
+    EventBusKafka._publish_to_dlq: DLQ publishing implementation
+"""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime
+from uuid import UUID
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class ModelDlqEvent(BaseModel):
+    """Event model for dead letter queue publish operations.
+
+    Captures comprehensive context for a DLQ publish event, including:
+    - Original message context (topic, offset, partition)
+    - Failure information (error type, error message)
+    - DLQ publish result (success/failure, DLQ error if failed)
+    - Tracing information (correlation_id, timestamps)
+
+    This model follows the ONEX immutable model pattern with frozen=True
+    to ensure thread-safe sharing across callback invocations.
+
+    Attributes:
+        original_topic: The Kafka topic where the message was originally consumed
+        dlq_topic: The dead letter queue topic where the message was published
+        correlation_id: Correlation ID for distributed tracing
+        error_type: The type name of the exception that caused the original failure
+        error_message: The error message from the original failure
+        retry_count: Number of retry attempts before DLQ
+        message_offset: Original message offset (if available)
+        message_partition: Original message partition (if available)
+        success: Whether the DLQ publish succeeded
+        dlq_error_type: Type of error if DLQ publish failed (None if success)
+        dlq_error_message: Error message if DLQ publish failed (None if success)
+        timestamp: When the DLQ event occurred
+        environment: Environment identifier (e.g., "prod", "staging")
+        consumer_group: Consumer group that processed the message
+
+    Example:
+        >>> event = ModelDlqEvent(
+        ...     original_topic="orders.created",
+        ...     dlq_topic="dlq.orders",
+        ...     correlation_id=uuid4(),
+        ...     error_type="ValidationError",
+        ...     error_message="Invalid order format",
+        ...     success=True,
+        ... )
+        >>> print(event.to_log_context())
+    """
+
+    model_config = ConfigDict(frozen=True, extra="forbid", from_attributes=True)
+
+    # Original message context
+    original_topic: str = Field(
+        description="The Kafka topic where the message was originally consumed",
+    )
+    dlq_topic: str = Field(
+        description="The dead letter queue topic where the message was published",
+    )
+    correlation_id: UUID = Field(
+        description="Correlation ID for distributed tracing",
+    )
+
+    # Failure information
+    error_type: str = Field(
+        description="The type name of the exception that caused the original failure",
+    )
+    error_message: str = Field(
+        description="The error message from the original failure (sanitized)",
+    )
+    retry_count: int = Field(
+        default=0,
+        description="Number of retry attempts before DLQ",
+        ge=0,
+    )
+
+    # Original message metadata (optional, may not be available)
+    message_offset: str | None = Field(
+        default=None,
+        description="Original message offset (if available)",
+    )
+    message_partition: int | None = Field(
+        default=None,
+        description="Original message partition (if available)",
+    )
+
+    # DLQ publish result
+    success: bool = Field(
+        description="Whether the DLQ publish succeeded",
+    )
+    dlq_error_type: str | None = Field(
+        default=None,
+        description="Type of error if DLQ publish failed (None if success)",
+    )
+    dlq_error_message: str | None = Field(
+        default=None,
+        description="Error message if DLQ publish failed (None if success)",
+    )
+
+    # Tracing and environment
+    timestamp: datetime = Field(
+        default_factory=lambda: datetime.now(UTC),
+        description="When the DLQ event occurred",
+    )
+    environment: str = Field(
+        default="unknown",
+        description="Environment identifier (e.g., 'prod', 'staging')",
+    )
+    consumer_group: str = Field(
+        default="unknown",
+        description="Consumer group that processed the message",
+    )
+
+    def to_log_context(self) -> dict[str, object]:
+        """Convert to a dictionary suitable for structured logging.
+
+        Returns a dictionary with all fields formatted for logging,
+        with correlation_id converted to string and timestamp to ISO format.
+
+        Returns:
+            Dictionary with all event fields for structured logging
+        """
+        return {
+            "original_topic": self.original_topic,
+            "dlq_topic": self.dlq_topic,
+            "correlation_id": str(self.correlation_id),
+            "error_type": self.error_type,
+            "error_message": self.error_message,
+            "retry_count": self.retry_count,
+            "message_offset": self.message_offset,
+            "message_partition": self.message_partition,
+            "success": self.success,
+            "dlq_error_type": self.dlq_error_type,
+            "dlq_error_message": self.dlq_error_message,
+            "timestamp": self.timestamp.isoformat(),
+            "environment": self.environment,
+            "consumer_group": self.consumer_group,
+        }
+
+    @property
+    def is_critical(self) -> bool:
+        """Determine if this event represents a critical failure.
+
+        A critical failure is when the DLQ publish itself failed,
+        meaning the failed message was lost and cannot be recovered
+        from the DLQ for later analysis or retry.
+
+        Returns:
+            True if DLQ publish failed (message potentially lost)
+        """
+        return not self.success
+
+    @property
+    def metric_labels(self) -> dict[str, str]:
+        """Return labels suitable for metrics emission.
+
+        Provides a consistent set of labels for metrics counters,
+        following Prometheus/OpenTelemetry labeling conventions.
+
+        Returns:
+            Dictionary of label names to values for metrics
+        """
+        return {
+            "original_topic": self.original_topic,
+            "error_type": self.error_type,
+            "environment": self.environment,
+            "success": str(self.success).lower(),
+        }
+
+
+__all__: list[str] = ["ModelDlqEvent"]

omnibase_infra/event_bus/models/model_dlq_metrics.py

@@ -0,0 +1,304 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Dead Letter Queue metrics model for operational visibility.
+
+Provides a Pydantic model for tracking operational metrics of the dead letter
+queue, enabling monitoring of:
+- DLQ publish success/failure rates
+- Per-topic breakdown of DLQ messages
+- Per-error-type breakdown for debugging
+- Latency statistics for DLQ operations
+
+Design Pattern:
+    Like ModelDispatchMetrics, this model uses the copy-on-write pattern.
+    Update methods return NEW instances rather than mutating in place:
+
+    ```python
+    # Copy-on-write: returns new instance, does not mutate
+    metrics = metrics.record_dlq_publish(
+        original_topic="orders.created",
+        error_type="ValidationError",
+        success=True,
+        duration_ms=15.5,
+    )
+    ```
+
+Thread Safety:
+    Individual ModelDlqMetrics instances are safe to share across threads
+    since update operations return new instances. The EventBusKafka uses
+    a lock to ensure atomic read-modify-write cycles when updating the
+    shared metrics reference.
+
+Example:
+    >>> from omnibase_infra.event_bus.models import ModelDlqMetrics
+    >>>
+    >>> metrics = ModelDlqMetrics()
+    >>> metrics = metrics.record_dlq_publish(
+    ...     original_topic="orders.created",
+    ...     error_type="ValidationError",
+    ...     success=True,
+    ...     duration_ms=15.5,
+    ... )
+    >>> print(f"DLQ success rate: {metrics.success_rate:.1%}")
+    DLQ success rate: 100.0%
+
+See Also:
+    ModelDlqEvent: Individual DLQ event for callbacks
+    ModelDispatchMetrics: Similar pattern for dispatch metrics
+"""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class ModelDlqMetrics(BaseModel):
+    """Aggregate metrics for dead letter queue operations.
+
+    Provides comprehensive observability for DLQ health including:
+    - Total publish counts and success/failure rates
+    - Per-topic metrics breakdown
+    - Per-error-type metrics breakdown
+    - Latency statistics for DLQ publish operations
+    - Last operation timestamps for staleness detection
+
+    Attributes:
+        total_publishes: Total number of DLQ publish attempts
+        successful_publishes: Number of successful DLQ publishes
+        failed_publishes: Number of failed DLQ publishes
+        topic_counts: Per-original-topic DLQ message counts
+        error_type_counts: Per-error-type DLQ message counts
+        total_latency_ms: Cumulative DLQ publish latency in milliseconds
+        min_latency_ms: Minimum observed DLQ publish latency
+        max_latency_ms: Maximum observed DLQ publish latency
+        last_publish_at: Timestamp of the last DLQ publish attempt
+        last_failure_at: Timestamp of the last failed DLQ publish (if any)
+
+    Example:
+        >>> metrics = ModelDlqMetrics()
+        >>> print(f"Total DLQ publishes: {metrics.total_publishes}")
+        >>> print(f"Success rate: {metrics.success_rate:.1%}")
+    """
+
+    model_config = ConfigDict(
+        extra="forbid",
+        from_attributes=True,
+        validate_assignment=True,
+    )
+
+    # ---- Publish Counts ----
+    total_publishes: int = Field(
+        default=0,
+        description="Total number of DLQ publish attempts",
+        ge=0,
+    )
+    successful_publishes: int = Field(
+        default=0,
+        description="Number of successful DLQ publishes",
+        ge=0,
+    )
+    failed_publishes: int = Field(
+        default=0,
+        description="Number of failed DLQ publishes",
+        ge=0,
+    )
+
+    # ---- Per-Topic Metrics ----
+    topic_counts: dict[str, int] = Field(
+        default_factory=dict,
+        description=(
+            "Per-original-topic DLQ message counts. Keys are topic names, "
+            "values are the number of messages from that topic sent to DLQ."
+        ),
+    )
+
+    # ---- Per-Error-Type Metrics ----
+    error_type_counts: dict[str, int] = Field(
+        default_factory=dict,
+        description=(
+            "Per-error-type DLQ message counts. Keys are error type names "
+            "(e.g., 'ValidationError'), values are occurrence counts."
+        ),
+    )
+
+    # ---- Latency Statistics ----
+    total_latency_ms: float = Field(
+        default=0.0,
+        description="Cumulative DLQ publish latency in milliseconds",
+        ge=0,
+    )
+    min_latency_ms: float | None = Field(
+        default=None,
+        description="Minimum observed DLQ publish latency in milliseconds",
+    )
+    max_latency_ms: float | None = Field(
+        default=None,
+        description="Maximum observed DLQ publish latency in milliseconds",
+    )
+
+    # ---- Timestamps ----
+    last_publish_at: datetime | None = Field(
+        default=None,
+        description="Timestamp of the last DLQ publish attempt",
+    )
+    last_failure_at: datetime | None = Field(
+        default=None,
+        description="Timestamp of the last failed DLQ publish (if any)",
+    )
+
+    @property
+    def avg_latency_ms(self) -> float:
+        """Calculate average DLQ publish latency.
+
+        Returns:
+            Average latency in milliseconds, or 0.0 if no publishes.
+        """
+        if self.total_publishes == 0:
+            return 0.0
+        return self.total_latency_ms / self.total_publishes
+
+    @property
+    def success_rate(self) -> float:
+        """Calculate DLQ publish success rate.
+
+        Returns:
+            Success rate as a decimal (0.0 to 1.0), or 1.0 if no publishes.
+        """
+        if self.total_publishes == 0:
+            return 1.0
+        return self.successful_publishes / self.total_publishes
+
+    @property
+    def failure_rate(self) -> float:
+        """Calculate DLQ publish failure rate.
+
+        Returns:
+            Failure rate as a decimal (0.0 to 1.0), or 0.0 if no publishes.
+        """
+        if self.total_publishes == 0:
+            return 0.0
+        return self.failed_publishes / self.total_publishes
+
+    def record_dlq_publish(
+        self,
+        original_topic: str,
+        error_type: str,
+        success: bool,
+        duration_ms: float,
+    ) -> ModelDlqMetrics:
+        """Record a DLQ publish operation and return updated metrics.
+
+        Creates a new ModelDlqMetrics instance with updated statistics.
+
+        Args:
+            original_topic: The topic where the original message was consumed
+            error_type: The type name of the exception that caused DLQ
+            success: Whether the DLQ publish succeeded
+            duration_ms: Duration of the DLQ publish operation in milliseconds
+
+        Returns:
+            New ModelDlqMetrics with updated statistics
+        """
+        now = datetime.now(UTC)
+
+        # Update latency statistics
+        new_min = (
+            duration_ms
+            if self.min_latency_ms is None
+            else min(self.min_latency_ms, duration_ms)
+        )
+        new_max = (
+            duration_ms
+            if self.max_latency_ms is None
+            else max(self.max_latency_ms, duration_ms)
+        )
+
+        # Update topic counts
+        new_topic_counts = dict(self.topic_counts)
+        new_topic_counts[original_topic] = new_topic_counts.get(original_topic, 0) + 1
+
+        # Update error type counts
+        new_error_type_counts = dict(self.error_type_counts)
+        new_error_type_counts[error_type] = new_error_type_counts.get(error_type, 0) + 1
+
+        # Determine timestamps
+        new_last_failure_at = self.last_failure_at
+        if not success:
+            new_last_failure_at = now
+
+        return self.model_copy(
+            update={
+                "total_publishes": self.total_publishes + 1,
+                "successful_publishes": self.successful_publishes
+                + (1 if success else 0),
+                "failed_publishes": self.failed_publishes + (0 if success else 1),
+                "topic_counts": new_topic_counts,
+                "error_type_counts": new_error_type_counts,
+                "total_latency_ms": self.total_latency_ms + duration_ms,
+                "min_latency_ms": new_min,
+                "max_latency_ms": new_max,
+                "last_publish_at": now,
+                "last_failure_at": new_last_failure_at,
+            }
+        )
+
+    def get_topic_count(self, topic: str) -> int:
+        """Get DLQ message count for a specific original topic.
+
+        Args:
+            topic: The original topic name
+
+        Returns:
+            Number of messages from this topic sent to DLQ
+        """
+        return self.topic_counts.get(topic, 0)
+
+    def get_error_type_count(self, error_type: str) -> int:
+        """Get DLQ message count for a specific error type.
+
+        Args:
+            error_type: The error type name (e.g., 'ValidationError')
+
+        Returns:
+            Number of messages sent to DLQ due to this error type
+        """
+        return self.error_type_counts.get(error_type, 0)
+
+    def to_dict(self) -> dict[str, object]:
+        """Convert to dictionary with computed properties included.
+
+        Returns:
+            Dictionary with all metrics including computed properties
+        """
+        return {
+            "total_publishes": self.total_publishes,
+            "successful_publishes": self.successful_publishes,
+            "failed_publishes": self.failed_publishes,
+            "success_rate": self.success_rate,
+            "failure_rate": self.failure_rate,
+            "avg_latency_ms": self.avg_latency_ms,
+            "min_latency_ms": self.min_latency_ms,
+            "max_latency_ms": self.max_latency_ms,
+            "topic_counts": self.topic_counts,
+            "error_type_counts": self.error_type_counts,
+            "last_publish_at": (
+                self.last_publish_at.isoformat() if self.last_publish_at else None
+            ),
+            "last_failure_at": (
+                self.last_failure_at.isoformat() if self.last_failure_at else None
+            ),
+        }
+
+    @classmethod
+    def create_empty(cls) -> ModelDlqMetrics:
+        """Create a new empty metrics instance.
+
+        Returns:
+            New ModelDlqMetrics with all counters at zero
+        """
+        return cls()
+
+
+__all__: list[str] = ["ModelDlqMetrics"]

omnibase_infra/event_bus/models/model_event_headers.py

@@ -0,0 +1,115 @@
+"""Event headers model for ONEX event bus messages.
+
+This module provides ModelEventHeaders, a Pydantic model implementing
+ProtocolEventHeaders from omnibase_spi for use with event bus implementations.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Literal
+from uuid import UUID, uuid4
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+from omnibase_infra.utils import validate_timezone_aware_datetime
+
+
+class ModelEventHeaders(BaseModel):
+    """Headers for ONEX event bus messages implementing ProtocolEventHeaders.
+
+    Standardized headers for ONEX event bus messages ensuring strict
+    interoperability across all agents and preventing integration failures.
+    Includes tracing, routing, and retry configuration.
+
+    Attributes:
+        content_type: MIME type of the message body.
+        correlation_id: UUID for correlating related messages.
+        message_id: Unique identifier for this message.
+        timestamp: Message creation timestamp.
+        source: Service that produced the message.
+        event_type: Type identifier for the event.
+        schema_version: Version of the message schema (simplified from ProtocolSemVer).
+        destination: Optional target destination.
+        trace_id: Distributed tracing trace ID.
+        span_id: Distributed tracing span ID.
+        parent_span_id: Parent span for trace hierarchy.
+        operation_name: Name of the operation being traced.
+        priority: Message priority level.
+        routing_key: Key for message routing.
+        partition_key: Key for partition assignment.
+        retry_count: Current MESSAGE-LEVEL retry attempt number (application-level).
+            This tracks end-to-end message delivery attempts across services,
+            incremented when a handler fails and the message is republished.
+            Distinct from bus-level retry in EventBusKafka (max_retry_attempts)
+            which handles transient Kafka connection failures.
+        max_retries: Maximum MESSAGE-LEVEL retry attempts allowed (application-level).
+            When retry_count >= max_retries, message should be sent to DLQ.
+        ttl_seconds: Message time-to-live in seconds.
+
+    Example:
+        ```python
+        from datetime import UTC, datetime
+        headers = ModelEventHeaders(
+            source="order-service",
+            event_type="order.created",
+            routing_key="orders.us-east",
+            timestamp=datetime(2025, 1, 15, 12, 0, 0, tzinfo=UTC),
+        )
+        is_valid = await headers.validate_headers()
+        ```
+    """
+
+    content_type: str = Field(default="application/json")
+    correlation_id: UUID = Field(default_factory=uuid4)
+    message_id: UUID = Field(default_factory=uuid4)
+    # Timestamps - MUST be explicitly injected (no default_factory for testability)
+    timestamp: datetime = Field(
+        ..., description="Message creation timestamp (must be explicitly provided)"
+    )
+
+    @field_validator("timestamp")
+    @classmethod
+    def validate_timestamp_timezone_aware(cls, v: datetime) -> datetime:
+        """Validate that timestamp is timezone-aware.
+
+        Delegates to shared utility for consistent validation across all models.
+        """
+        return validate_timezone_aware_datetime(v)
+
+    source: str
+    event_type: str
+    schema_version: str = Field(default="1.0.0")
+    destination: str | None = Field(default=None)
+    trace_id: str | None = Field(default=None)
+    span_id: str | None = Field(default=None)
+    parent_span_id: str | None = Field(default=None)
+    operation_name: str | None = Field(default=None)
+    priority: Literal["low", "normal", "high", "critical"] = Field(default="normal")
+    routing_key: str | None = Field(default=None)
+    partition_key: str | None = Field(default=None)
+    retry_count: int = Field(
+        default=0,
+        description=(
+            "Current MESSAGE-LEVEL retry attempt (application-level). "
+            "Distinct from EventBusKafka.max_retry_attempts (bus-level)."
+        ),
+    )
+    max_retries: int = Field(
+        default=3,
+        description=(
+            "Maximum MESSAGE-LEVEL retry attempts (application-level). "
+            "When retry_count >= max_retries, message should go to DLQ."
+        ),
+    )
+    ttl_seconds: int | None = Field(default=None)
+
+    model_config = ConfigDict(frozen=True, extra="forbid", from_attributes=True)
+
+    async def validate_headers(self) -> bool:
+        """Validate that required headers are present and valid.
+
+        Returns:
+            True if correlation_id and event_type are valid, False otherwise.
+        """
+        return bool(self.correlation_id and self.event_type)

omnibase_infra/event_bus/models/model_event_message.py

@@ -0,0 +1,60 @@
+"""Event message model for ONEX event bus.
+
+This module provides ModelEventMessage, a Pydantic model implementing
+ProtocolEventMessage from omnibase_spi for use with event bus implementations.
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from omnibase_infra.event_bus.models.model_event_headers import ModelEventHeaders
+
+
+class ModelEventMessage(BaseModel):
+    """Event bus message implementing ProtocolEventMessage.
+
+    Defines the contract that all event message implementations must satisfy
+    for Kafka/RedPanda compatibility following ONEX Messaging Design.
+    Supports partitioning, offset tracking, and acknowledgment.
+
+    Attributes:
+        topic: Kafka topic the message belongs to.
+        key: Optional message key for partitioning (bytes).
+        value: Serialized message body as bytes.
+        headers: Structured message headers.
+        offset: Kafka offset (for consumed messages).
+        partition: Kafka partition number.
+
+    Example:
+        ```python
+        message = ModelEventMessage(
+            topic="onex.orders.created",
+            key=b"customer-123",
+            value=b'{"order_id": "ORD-123", "amount": 99.99}',
+            headers=ModelEventHeaders(
+                source="order-service",
+                event_type="order.created",
+            ),
+        )
+        await message.ack()  # Acknowledge after processing
+        ```
+    """
+
+    topic: str
+    key: bytes | None = Field(default=None)
+    value: bytes
+    headers: ModelEventHeaders
+    offset: str | None = Field(default=None)
+    partition: int | None = Field(default=None)
+
+    model_config = ConfigDict(
+        frozen=True, extra="forbid", arbitrary_types_allowed=True, from_attributes=True
+    )
+
+    async def ack(self) -> None:
+        """Acknowledge message processing.
+
+        For in-memory event bus, this is a no-op.
+        For real Kafka/RedPanda implementations, this would commit the offset.
+        """