omnibase_infra 0.2.6__py3-none-any.whl

omnibase_infra/models/dispatch/model_dispatch_route.py

@@ -0,0 +1,279 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""
+Dispatch Route Model.
+
+Represents a routing rule that maps topic patterns and message types to dispatchers
+in the runtime dispatch engine. Routes are used by the engine to determine
+which dispatcher should process incoming messages.
+
+Design Pattern:
+    ModelDispatchRoute is a pure data model that defines a routing rule. It contains:
+    - Topic pattern matching (exact or glob patterns)
+    - Message category filtering (COMMAND, EVENT, INTENT)
+    - Message type filtering (optional specific type within category)
+    - Dispatcher reference (identifier for the registered dispatcher)
+    - Priority for route ordering when multiple routes match
+
+    The dispatch engine uses these routes to determine the appropriate dispatcher
+    for each incoming message based on topic and message type.
+
+Thread Safety:
+    ModelDispatchRoute is immutable (frozen=True) after creation,
+    making it thread-safe for concurrent read access.
+
+Example:
+    >>> from omnibase_infra.models.dispatch import ModelDispatchRoute
+    >>> from omnibase_infra.enums import EnumMessageCategory
+    >>>
+    >>> # Create a route for user events
+    >>> route = ModelDispatchRoute(
+    ...     route_id="user-events-route",
+    ...     topic_pattern="*.user.events.*",
+    ...     message_category=EnumMessageCategory.EVENT,
+    ...     dispatcher_id="user-event-dispatcher",
+    ...     priority=10,
+    ... )
+    >>>
+    >>> # Check if route matches a topic
+    >>> route.matches_topic("dev.user.events.v1")
+    True
+
+See Also:
+    omnibase_infra.models.dispatch.ModelDispatcherRegistration: Dispatcher metadata
+    omnibase_infra.models.dispatch.ModelDispatchResult: Dispatch operation result
+    omnibase_infra.enums.EnumMessageCategory: Message category enum
+"""
+
+import re
+from functools import cached_property
+from uuid import UUID, uuid4
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+from omnibase_infra.enums import EnumMessageCategory
+from omnibase_infra.models.dispatch.model_dispatch_metadata import ModelDispatchMetadata
+
+
+class ModelDispatchRoute(BaseModel):
+    """
+    Routing rule for the dispatch engine.
+
+    Maps topic patterns and message types to dispatchers. Used by the engine
+    to determine which dispatcher should process incoming messages.
+
+    Attributes:
+        route_id: Unique identifier for this route (for logging/debugging).
+        topic_pattern: Topic pattern to match (exact string or glob pattern).
+            Supports wildcards: '*' matches any single segment, '**' matches
+            multiple segments.
+        message_category: The message category this route handles (EVENT,
+            COMMAND, or INTENT).
+        message_type: Optional specific message type within the category.
+            When None, matches all message types in the category.
+        dispatcher_id: Identifier of the dispatcher to invoke when this route matches.
+        priority: Route priority for ordering (higher = matched first).
+            When multiple routes match, highest priority wins.
+        enabled: Whether this route is active. Disabled routes are skipped.
+        description: Human-readable description of the route's purpose.
+        metadata: Optional additional metadata for the route.
+
+    Example:
+        >>> route = ModelDispatchRoute(
+        ...     route_id="order-commands",
+        ...     topic_pattern="*.order.commands.*",
+        ...     message_category=EnumMessageCategory.COMMAND,
+        ...     message_type="CreateOrderCommand",
+        ...     dispatcher_id="order-command-dispatcher",
+        ...     priority=100,
+        ...     description="Routes order creation commands",
+        ... )
+    """
+
+    model_config = ConfigDict(
+        frozen=True,
+        extra="forbid",
+        from_attributes=True,
+    )
+
+    # ---- Route Identity ----
+    route_id: str = Field(
+        ...,
+        description="Unique identifier for this route (for logging/debugging).",
+        min_length=1,
+        max_length=200,
+    )
+
+    # ---- Matching Criteria ----
+    topic_pattern: str = Field(
+        ...,
+        description=(
+            "Topic pattern to match. Supports exact match or glob patterns. "
+            "Use '*' for single segment wildcard, '**' for multi-segment."
+        ),
+        min_length=1,
+        max_length=500,
+    )
+    message_category: EnumMessageCategory = Field(
+        ...,
+        description="The message category this route handles (EVENT, COMMAND, INTENT).",
+    )
+    message_type: str | None = Field(
+        default=None,
+        description=(
+            "Optional specific message type within the category. "
+            "When None, matches all message types in the category."
+        ),
+        max_length=200,
+    )
+
+    # ---- Dispatcher Reference ----
+    dispatcher_id: str = Field(
+        ...,
+        description="Identifier of the dispatcher to invoke when this route matches.",
+        min_length=1,
+        max_length=200,
+    )
+
+    # ---- Route Configuration ----
+    priority: int = Field(
+        default=0,
+        description="Route priority for ordering. Higher priority routes are matched first.",
+        ge=-1000,
+        le=1000,
+    )
+    enabled: bool = Field(
+        default=True,
+        description="Whether this route is active. Disabled routes are skipped.",
+    )
+
+    # ---- Documentation ----
+    description: str | None = Field(
+        default=None,
+        description="Human-readable description of the route's purpose.",
+        max_length=1000,
+    )
+
+    # ---- Tracing Context ----
+    correlation_id: UUID = Field(
+        default_factory=uuid4,
+        description="Correlation ID for tracing route creation (auto-generated if not provided).",
+    )
+    metadata: ModelDispatchMetadata | None = Field(
+        default=None,
+        description="Optional additional metadata for the route.",
+    )
+
+    @field_validator("topic_pattern")
+    @classmethod
+    def validate_topic_pattern(cls, v: str) -> str:
+        """Validate that the topic pattern is well-formed."""
+        # Basic validation: must not be empty or only whitespace
+        if not v or not v.strip():
+            msg = "Topic pattern cannot be empty or whitespace"
+            raise ValueError(msg)
+        # Pattern should not start/end with dots (invalid topic structure)
+        if v.startswith(".") or v.endswith("."):
+            msg = "Topic pattern cannot start or end with a dot"
+            raise ValueError(msg)
+        return v
+
+    @cached_property
+    def _compiled_pattern(self) -> re.Pattern[str]:
+        """
+        Compile the topic pattern to a regex for efficient matching.
+
+        Converts glob-style patterns to regex:
+        - '*' matches any single segment (no dots)
+        - '**' matches any number of segments (including dots)
+        """
+        # Escape special regex characters except * and **
+        pattern = self.topic_pattern
+        # Handle ** first (must be done before single *)
+        pattern = pattern.replace("**", "__DOUBLE_STAR__")
+        # Escape dots and other special chars
+        pattern = re.escape(pattern)
+        # Convert back ** placeholder to multi-segment match
+        pattern = pattern.replace("__DOUBLE_STAR__", ".*")
+        # Convert single * to single-segment match (no dots)
+        pattern = pattern.replace(r"\*", "[^.]+")
+        # Anchor the pattern
+        return re.compile(f"^{pattern}$", re.IGNORECASE)
+
+    def matches_topic(self, topic: str) -> bool:
+        """
+        Check if this route matches the given topic.
+
+        Uses glob-style pattern matching where:
+        - '*' matches any single segment (between dots)
+        - '**' matches any number of segments
+
+        Args:
+            topic: The topic to check against this route's pattern
+
+        Returns:
+            True if the topic matches the pattern, False otherwise
+
+        Example:
+            >>> route = ModelDispatchRoute(
+            ...     route_id="test",
+            ...     topic_pattern="*.user.events.*",
+            ...     message_category=EnumMessageCategory.EVENT,
+            ...     dispatcher_id="dispatcher",
+            ... )
+            >>> route.matches_topic("dev.user.events.v1")
+            True
+            >>> route.matches_topic("user.commands.v1")
+            False
+        """
+        if not self.enabled:
+            return False
+        return bool(self._compiled_pattern.match(topic))
+
+    def matches(
+        self,
+        topic: str,
+        category: EnumMessageCategory,
+        message_type: str | None = None,
+    ) -> bool:
+        """
+        Check if this route matches the given topic, category, and message type.
+
+        A route matches if:
+        1. The route is enabled (checked by matches_topic)
+        2. The topic matches the pattern
+        3. The category matches
+        4. Either this route has no message_type filter, or the message types match
+
+        Args:
+            topic: The topic to check
+            category: The message category to check
+            message_type: Optional message type to check
+
+        Returns:
+            True if all criteria match, False otherwise
+
+        Example:
+            >>> route = ModelDispatchRoute(
+            ...     route_id="test",
+            ...     topic_pattern="*.user.events.*",
+            ...     message_category=EnumMessageCategory.EVENT,
+            ...     message_type="UserCreatedEvent",
+            ...     dispatcher_id="dispatcher",
+            ... )
+            >>> route.matches("dev.user.events.v1", EnumMessageCategory.EVENT, "UserCreatedEvent")
+            True
+            >>> route.matches("dev.user.events.v1", EnumMessageCategory.COMMAND, "UserCreatedEvent")
+            False
+        """
+        # matches_topic already checks self.enabled
+        if not self.matches_topic(topic):
+            return False
+        if self.message_category != category:
+            return False
+        if self.message_type is not None and self.message_type != message_type:
+            return False
+        return True
+
+
+__all__ = ["ModelDispatchRoute"]

omnibase_infra/models/dispatch/model_dispatcher_metrics.py

@@ -0,0 +1,275 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""
+Dispatcher Metrics Model.
+
+Per-dispatcher metrics for dispatch engine observability. Tracks execution counts,
+error rates, and latency statistics for individual dispatchers.
+
+Design Pattern:
+    ModelDispatcherMetrics is a mutable data model that accumulates metrics during
+    dispatch engine operation. Unlike most ONEX models, it is NOT frozen because
+    metrics need to be updated in real-time during dispatch operations.
+
+    For thread-safety in production, the dispatch engine maintains its own
+    synchronization when updating these metrics.
+
+Thread Safety:
+    This model is NOT thread-safe on its own. The MessageDispatchEngine provides
+    thread-safety guarantees during metrics collection.
+
+Example:
+    >>> from omnibase_infra.models.dispatch import ModelDispatcherMetrics
+    >>>
+    >>> metrics = ModelDispatcherMetrics(dispatcher_id="user-event-dispatcher")
+    >>> metrics = metrics.record_execution(duration_ms=45.2, success=True)
+    >>> print(f"Success rate: {metrics.success_rate:.1%}")
+
+See Also:
+    omnibase_infra.models.dispatch.ModelDispatchMetrics: Aggregate dispatch metrics
+    omnibase_core.runtime.MessageDispatchEngine: Uses these for observability
+"""
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class ModelDispatcherMetrics(BaseModel):
+    """
+    Metrics for a single dispatcher in the dispatch engine.
+
+    Tracks execution statistics including counts, error rates, and latency
+    for observability and performance monitoring.
+
+    Attributes:
+        dispatcher_id: The dispatcher's unique identifier.
+        execution_count: Total number of times this dispatcher was executed.
+        success_count: Number of successful executions.
+        error_count: Number of failed executions.
+        total_latency_ms: Cumulative latency across all executions.
+        min_latency_ms: Minimum observed latency (-1.0 if no executions).
+        max_latency_ms: Maximum observed latency (-1.0 if no executions).
+        last_error_message: Most recent error message (empty string if none).
+        last_execution_topic: Topic of the most recent execution (empty string if none).
+
+    Example:
+        >>> metrics = ModelDispatcherMetrics(dispatcher_id="my-dispatcher")
+        >>> metrics = metrics.record_execution(duration_ms=50.0, success=True)
+        >>> metrics.avg_latency_ms
+        50.0
+    """
+
+    model_config = ConfigDict(
+        extra="forbid",
+        from_attributes=True,
+        validate_assignment=True,
+    )
+
+    # ---- Dispatcher Identity ----
+    dispatcher_id: str = Field(
+        ...,
+        description="The dispatcher's unique identifier.",
+        min_length=1,
+    )
+
+    # ---- Execution Counts ----
+    execution_count: int = Field(
+        default=0,
+        description="Total number of times this dispatcher was executed.",
+        ge=0,
+    )
+    success_count: int = Field(
+        default=0,
+        description="Number of successful executions.",
+        ge=0,
+    )
+    error_count: int = Field(
+        default=0,
+        description="Number of failed executions.",
+        ge=0,
+    )
+
+    # ---- Latency Metrics ----
+    total_latency_ms: float = Field(
+        default=0.0,
+        description="Cumulative latency across all executions in milliseconds.",
+        ge=0,
+    )
+    min_latency_ms: float = Field(
+        default=-1.0,
+        description=(
+            "Minimum observed latency in milliseconds. "
+            "Value of -1.0 indicates no executions recorded yet."
+        ),
+    )
+    max_latency_ms: float = Field(
+        default=-1.0,
+        description=(
+            "Maximum observed latency in milliseconds. "
+            "Value of -1.0 indicates no executions recorded yet."
+        ),
+    )
+
+    # ---- Last Execution Info ----
+    last_error_message: str = Field(
+        default="",
+        description=(
+            "Most recent error message. Empty string indicates no errors recorded."
+        ),
+    )
+    last_execution_topic: str = Field(
+        default="",
+        description=(
+            "Topic of the most recent execution. "
+            "Empty string indicates no executions recorded yet."
+        ),
+    )
+
+    @property
+    def avg_latency_ms(self) -> float:
+        """
+        Calculate average latency across all executions.
+
+        Returns:
+            Average latency in milliseconds, or 0.0 if no executions.
+
+        Example:
+            >>> metrics = ModelDispatcherMetrics(
+            ...     dispatcher_id="test",
+            ...     execution_count=10,
+            ...     total_latency_ms=500.0,
+            ... )
+            >>> metrics.avg_latency_ms
+            50.0
+        """
+        if self.execution_count == 0:
+            return 0.0
+        return self.total_latency_ms / self.execution_count
+
+    @property
+    def success_rate(self) -> float:
+        """
+        Calculate success rate as a fraction (0.0 to 1.0).
+
+        Returns:
+            Success rate as a decimal, or 1.0 if no executions.
+
+        Example:
+            >>> metrics = ModelDispatcherMetrics(
+            ...     dispatcher_id="test",
+            ...     execution_count=100,
+            ...     success_count=95,
+            ...     error_count=5,
+            ... )
+            >>> metrics.success_rate
+            0.95
+        """
+        if self.execution_count == 0:
+            return 1.0
+        return self.success_count / self.execution_count
+
+    @property
+    def error_rate(self) -> float:
+        """
+        Calculate error rate as a fraction (0.0 to 1.0).
+
+        Returns:
+            Error rate as a decimal, or 0.0 if no executions.
+
+        Example:
+            >>> metrics = ModelDispatcherMetrics(
+            ...     dispatcher_id="test",
+            ...     execution_count=100,
+            ...     error_count=5,
+            ... )
+            >>> metrics.error_rate
+            0.05
+        """
+        if self.execution_count == 0:
+            return 0.0
+        return self.error_count / self.execution_count
+
+    def record_execution(
+        self,
+        duration_ms: float,
+        success: bool,
+        topic: str | None = None,
+        error_message: str | None = None,
+    ) -> "ModelDispatcherMetrics":
+        """
+        Record an execution and return updated metrics.
+
+        Creates a new ModelDispatcherMetrics instance with updated statistics.
+
+        Args:
+            duration_ms: Execution duration in milliseconds.
+            success: Whether the execution was successful.
+            topic: Optional topic the message was from.
+            error_message: Optional error message if execution failed.
+
+        Returns:
+            New ModelDispatcherMetrics with updated statistics.
+
+        Example:
+            >>> metrics = ModelDispatcherMetrics(dispatcher_id="test")
+            >>> metrics = metrics.record_execution(
+            ...     duration_ms=45.0,
+            ...     success=True,
+            ...     topic="user.events.v1",
+            ... )
+            >>> metrics.execution_count
+            1
+        """
+        # Sentinel value -1.0 means "not yet computed"
+        new_min = (
+            duration_ms
+            if self.min_latency_ms < 0
+            else min(self.min_latency_ms, duration_ms)
+        )
+        new_max = (
+            duration_ms
+            if self.max_latency_ms < 0
+            else max(self.max_latency_ms, duration_ms)
+        )
+
+        # Use model_copy to prevent field drift when new fields are added
+        return self.model_copy(
+            update={
+                "execution_count": self.execution_count + 1,
+                "success_count": self.success_count + (1 if success else 0),
+                "error_count": self.error_count + (0 if success else 1),
+                "total_latency_ms": self.total_latency_ms + duration_ms,
+                "min_latency_ms": new_min,
+                "max_latency_ms": new_max,
+                # On failure: use error_message (or empty string); on success: preserve previous
+                "last_error_message": (error_message or "")
+                if not success
+                else self.last_error_message,
+                "last_execution_topic": topic if topic else self.last_execution_topic,
+            }
+        )
+
+    def to_dict(self) -> dict[str, object]:
+        """
+        Convert to dictionary with computed properties included.
+
+        Returns:
+            Dictionary with all metrics including computed properties.
+            Values are float, int, or str types.
+        """
+        return {
+            "dispatcher_id": self.dispatcher_id,
+            "execution_count": self.execution_count,
+            "success_count": self.success_count,
+            "error_count": self.error_count,
+            "total_latency_ms": self.total_latency_ms,
+            "avg_latency_ms": self.avg_latency_ms,
+            "min_latency_ms": self.min_latency_ms,
+            "max_latency_ms": self.max_latency_ms,
+            "success_rate": self.success_rate,
+            "error_rate": self.error_rate,
+            "last_error_message": self.last_error_message,
+            "last_execution_topic": self.last_execution_topic,
+        }
+
+
+__all__ = ["ModelDispatcherMetrics"]