omnibase_infra 0.2.6__py3-none-any.whl

omnibase_infra/protocols/protocol_idempotency_store.py

@@ -0,0 +1,142 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Idempotency Store Protocol Definition.
+
+This module defines the protocol interface for idempotency stores used
+to track processed messages and prevent duplicate processing.
+
+Note: This protocol is defined locally in omnibase_infra until it is
+promoted to omnibase_spi. Once available in omnibase_spi, imports should
+be updated to use the canonical location.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Protocol, runtime_checkable
+from uuid import UUID
+
+
+@runtime_checkable
+class ProtocolIdempotencyStore(Protocol):
+    """Protocol for idempotency stores.
+
+    Idempotency stores track processed message IDs to enable exactly-once
+    or at-least-once-with-dedup semantics in distributed message processing.
+
+    Key Operations:
+        - check_and_record: Atomically check if message is new and record it
+        - is_processed: Read-only check if message was already processed
+        - mark_processed: Explicitly mark a message as processed
+        - cleanup_expired: Remove old records based on TTL
+
+    Concurrency Safety:
+        All implementations MUST be safe for concurrent coroutine access. The
+        check_and_record method MUST provide atomic check-and-set semantics to
+        prevent race conditions. Use asyncio.Lock for coroutine-safety.
+
+    Domain Isolation:
+        The optional `domain` parameter allows different message namespaces
+        to be tracked independently. The same message_id can exist in different
+        domains without conflict.
+
+    Example Usage:
+        >>> store: ProtocolIdempotencyStore = get_store()
+        >>> is_new = await store.check_and_record(
+        ...     message_id=uuid4(),
+        ...     domain="orders",
+        ...     correlation_id=uuid4(),
+        ... )
+        >>> if is_new:
+        ...     # Process the message
+        ...     await process_order(message)
+        >>> else:
+        ...     # Duplicate - skip processing
+        ...     log.info("Skipping duplicate message")
+    """
+
+    async def check_and_record(
+        self,
+        message_id: UUID,
+        domain: str | None = None,
+        correlation_id: UUID | None = None,
+    ) -> bool:
+        """Atomically check if message was processed and record if not.
+
+        This is the primary idempotency check method. It MUST be atomic:
+        when multiple concurrent calls are made with the same (domain, message_id),
+        exactly ONE caller receives True.
+
+        Args:
+            message_id: Unique identifier for the message.
+            domain: Optional domain namespace for isolated deduplication.
+            correlation_id: Optional correlation ID for distributed tracing.
+
+        Returns:
+            True if message is new (should be processed).
+            False if message is duplicate (should be skipped).
+        """
+        ...
+
+    async def is_processed(
+        self,
+        message_id: UUID,
+        domain: str | None = None,
+    ) -> bool:
+        """Check if a message was already processed.
+
+        Read-only check that does not modify the store. Use this for
+        inspection or status queries where recording is not desired.
+
+        Args:
+            message_id: Unique identifier for the message.
+            domain: Optional domain namespace.
+
+        Returns:
+            True if the message has been processed.
+            False if the message has not been processed.
+        """
+        ...
+
+    async def mark_processed(
+        self,
+        message_id: UUID,
+        domain: str | None = None,
+        correlation_id: UUID | None = None,
+        processed_at: datetime | None = None,
+    ) -> None:
+        """Mark a message as processed.
+
+        Records a message as processed without checking if it already exists.
+        Use this for explicit marking, such as when replaying events or
+        seeding the store with known processed messages.
+
+        Args:
+            message_id: Unique identifier for the message.
+            domain: Optional domain namespace for isolated deduplication.
+            correlation_id: Optional correlation ID for tracing.
+            processed_at: Optional timestamp of when processing occurred.
+                If None, implementations should use current time.
+        """
+        ...
+
+    async def cleanup_expired(
+        self,
+        ttl_seconds: int,
+    ) -> int:
+        """Remove entries older than TTL.
+
+        Cleans up old idempotency records based on their processed_at timestamp.
+        This prevents unbounded growth of the store.
+
+        Args:
+            ttl_seconds: Time-to-live in seconds. Records older than this
+                value (based on processed_at timestamp) are removed.
+
+        Returns:
+            Number of entries removed.
+        """
+        ...
+
+
+__all__: list[str] = ["ProtocolIdempotencyStore"]

omnibase_infra/protocols/protocol_message_dispatcher.py

@@ -0,0 +1,247 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""
+Protocol for Message Dispatchers in the ONEX Dispatch Engine.
+
+This module defines the ProtocolMessageDispatcher protocol for category-based
+message dispatchers. Dispatchers are the execution units that process messages
+after routing in the dispatch engine.
+
+Thread Safety:
+    Dispatcher implementations may be invoked concurrently from the dispatch engine.
+    The same dispatcher instance may be called from multiple coroutines simultaneously.
+
+    Design Requirements:
+        - Stateless Dispatchers (Recommended): Keep dispatchers stateless by
+          extracting all needed data from the envelope. This is the safest
+          approach and requires no synchronization.
+        - Stateful Dispatchers: If state is required, use appropriate
+          synchronization primitives (asyncio.Lock for async state).
+
+Related:
+    - OMN-934: Dispatcher registry for message dispatch engine
+    - RegistryDispatcher: Registry for managing dispatcher registrations
+    - ModelDispatchResult: Result model for dispatch operations
+
+.. versionadded:: 0.5.0
+"""
+
+from __future__ import annotations
+
+__all__ = ["ProtocolMessageDispatcher"]
+
+from typing import TYPE_CHECKING, Protocol, runtime_checkable
+
+from omnibase_core.enums import EnumNodeKind
+from omnibase_infra.enums import EnumMessageCategory
+from omnibase_infra.models.dispatch.model_dispatch_result import ModelDispatchResult
+
+if TYPE_CHECKING:
+    from omnibase_core.models.events.model_event_envelope import ModelEventEnvelope
+
+
+@runtime_checkable
+class ProtocolMessageDispatcher(Protocol):
+    """
+    Protocol for category-based message dispatchers in the dispatch engine.
+
+    Message dispatchers are the execution units that process messages after routing.
+    Each dispatcher is classified by:
+    - category: The message category it handles (EVENT, COMMAND, INTENT)
+    - message_types: Specific message types it accepts (empty = all)
+    - node_kind: The ONEX node kind this dispatcher represents
+
+    Protocol Verification:
+        Per ONEX conventions, protocol compliance is verified via duck typing rather
+        than isinstance checks. Verify required methods and properties exist:
+
+        **Validation Approaches**:
+
+        1. **Duck Typing Check** (recommended for quick structural validation):
+           Use when you need to verify an object implements the dispatcher interface
+           before passing it to components that expect a dispatcher.
+
+           .. code-block:: python
+
+               # Verify required properties and methods exist
+               if (hasattr(dispatcher, 'dispatcher_id') and
+                   hasattr(dispatcher, 'category') and
+                   hasattr(dispatcher, 'handle') and callable(dispatcher.handle)):
+                   registry.register_dispatcher(dispatcher)
+               else:
+                   raise TypeError("Object does not implement ProtocolMessageDispatcher")
+
+        2. **RegistryDispatcher Validation** (comprehensive validation):
+           The ``RegistryDispatcher.register_dispatcher()`` method performs thorough
+           validation including:
+           - All required properties exist and have correct types
+           - Execution shape is valid (category -> node_kind combination)
+           - ``handle()`` method is callable
+
+           This is the recommended approach for production registration as it
+           provides detailed error messages for debugging.
+
+        **Note**: For complete type safety, use static type checking (mypy)
+        in addition to duck typing verification.
+
+    Example:
+        .. code-block:: python
+
+            from omnibase_core.enums.enum_node_kind import EnumNodeKind
+            from omnibase_core.models.events.model_event_envelope import ModelEventEnvelope
+            from omnibase_infra.enums import EnumMessageCategory
+            from omnibase_infra.enums.enum_dispatch_status import EnumDispatchStatus
+            from omnibase_infra.models.dispatch.model_dispatch_result import ModelDispatchResult
+            from omnibase_infra.protocols import ProtocolMessageDispatcher
+
+            class UserEventDispatcher:
+                '''Dispatcher for user-related events.'''
+
+                @property
+                def dispatcher_id(self) -> str:
+                    return "user-event-dispatcher"
+
+                @property
+                def category(self) -> EnumMessageCategory:
+                    return EnumMessageCategory.EVENT
+
+                @property
+                def message_types(self) -> set[str]:
+                    return {"UserCreated", "UserUpdated", "UserDeleted"}
+
+                @property
+                def node_kind(self) -> EnumNodeKind:
+                    return EnumNodeKind.REDUCER
+
+                async def handle(
+                    self, envelope: ModelEventEnvelope[object]
+                ) -> ModelDispatchResult:
+                    # Process the event
+                    return ModelDispatchResult(
+                        status=EnumDispatchStatus.SUCCESS,
+                        topic="user.events",
+                        dispatcher_id=self.dispatcher_id,
+                    )
+
+            # Verify protocol compliance via duck typing (per ONEX conventions)
+            dispatcher = UserEventDispatcher()
+            assert hasattr(dispatcher, 'dispatcher_id')
+            assert hasattr(dispatcher, 'category')
+            assert hasattr(dispatcher, 'handle') and callable(dispatcher.handle)
+
+    Attributes:
+        dispatcher_id: Unique identifier for this dispatcher.
+        category: The message category this dispatcher processes.
+        message_types: Specific message types this dispatcher accepts.
+            Empty set means dispatcher accepts all message types in its category.
+        node_kind: The ONEX node kind this dispatcher represents.
+
+    Note:
+        Method bodies in this Protocol use ``...`` (Ellipsis) rather than
+        ``raise NotImplementedError()``. This is the standard Python convention
+        for ``typing.Protocol`` classes per PEP 544.
+
+    .. versionadded:: 0.5.0
+    """
+
+    @property
+    def dispatcher_id(self) -> str:
+        """
+        Return the unique identifier for this dispatcher.
+
+        The dispatcher ID is used for:
+        - Registration and lookup in the registry
+        - Tracing and observability
+        - Error reporting and debugging
+
+        Returns:
+            str: Unique dispatcher identifier (e.g., "user-event-dispatcher")
+        """
+        ...
+
+    @property
+    def category(self) -> EnumMessageCategory:
+        """
+        Return the message category this dispatcher processes.
+
+        Dispatchers are classified by the category of messages they can handle:
+        - EVENT: Past-tense immutable facts
+        - COMMAND: Imperative action requests
+        - INTENT: Goal-oriented desires
+
+        Returns:
+            EnumMessageCategory: The message category (EVENT, COMMAND, or INTENT)
+        """
+        ...
+
+    @property
+    def message_types(self) -> set[str]:
+        """
+        Return the specific message types this dispatcher accepts.
+
+        When empty, the dispatcher accepts all message types within its category.
+        When non-empty, only the listed message types are accepted.
+
+        Returns:
+            set[str]: Set of accepted message types, or empty for all types
+        """
+        ...
+
+    @property
+    def node_kind(self) -> EnumNodeKind:
+        """
+        Return the ONEX node kind this dispatcher represents.
+
+        The node kind determines valid execution shapes:
+        - REDUCER: Handles EVENT messages for state aggregation
+        - ORCHESTRATOR: Handles EVENT and COMMAND messages for coordination
+        - EFFECT: Handles INTENT and COMMAND messages for external I/O
+
+        Returns:
+            EnumNodeKind: The node kind (REDUCER, ORCHESTRATOR, EFFECT, etc.)
+        """
+        ...
+
+    async def handle(
+        self,
+        envelope: ModelEventEnvelope[object],
+    ) -> ModelDispatchResult:
+        """
+        Handle the given envelope and return a dispatch result.
+
+        This is the primary execution method. The dispatcher receives an input
+        envelope, processes it according to its category and node kind,
+        and returns a dispatch result indicating success or failure.
+
+        Typing Note (ModelEventEnvelope[object]):
+            The envelope parameter uses ``ModelEventEnvelope[object]`` instead of
+            ``Any`` per CLAUDE.md guidance: "Use ``object`` for generic payloads".
+
+            This is intentional:
+            - CLAUDE.md mandates "NEVER use ``Any``" and specifies ``object`` for
+              generic payloads that can accept multiple event types
+            - Generic dispatchers must handle multiple event types at runtime;
+              the dispatch engine routes based on topic/category/message_type,
+              not payload shape
+            - Payload extraction uses ``isinstance()`` type guards for runtime
+              safety (see dispatcher implementations)
+            - ``object`` provides better type safety than ``Any`` while allowing
+              the flexibility required for polymorphic dispatch
+
+            For type-specific processing, dispatcher implementations should use
+            type guards to narrow the payload type:
+
+            .. code-block:: python
+
+                payload = envelope.payload
+                if isinstance(payload, SpecificEventType):
+                    # Type-safe processing here
+                    process_specific_event(payload)
+
+        Args:
+            envelope: The input envelope containing the message to process.
+
+        Returns:
+            ModelDispatchResult: The result of the dispatch operation.
+        """
+        ...

omnibase_infra/protocols/protocol_message_type_registry.py

@@ -0,0 +1,306 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""
+Protocol definition for the Message Type Registry.
+
+Defines the interface contract for message type registry implementations.
+Enables duck typing and test mocking while ensuring consistent API.
+
+Design Principles:
+    - Protocol-based interface for flexibility and testability
+    - Runtime-checkable for isinstance() validation
+    - Comprehensive API covering registration, query, and validation
+    - Thread-safety documented in implementation requirements
+
+Related:
+    - OMN-937: Central Message Type Registry implementation
+    - RegistryMessageType: Primary implementation of this protocol
+
+.. versionadded:: 0.5.0
+"""
+
+from typing import Protocol, runtime_checkable
+
+from omnibase_infra.enums import EnumMessageCategory
+from omnibase_infra.models.registry.model_message_type_entry import (
+    ModelMessageTypeEntry,
+)
+
+
+@runtime_checkable
+class ProtocolMessageTypeRegistry(Protocol):
+    """
+    Protocol for message type registry implementations.
+
+    Defines the interface contract for registries that map message types
+    to handler implementations with category and domain constraints.
+
+    Implementations must follow the freeze-after-init pattern:
+    1. Registration phase: All register_* methods available
+    2. Freeze: Call freeze() to lock the registry
+    3. Query phase: Only lookup methods available
+
+    Thread Safety Requirements:
+        - Registration methods must be thread-safe during registration phase
+        - After freeze(), all query methods must be safe for concurrent access
+        - Implementations should use appropriate locking strategies
+
+    Example Implementation:
+        .. code-block:: python
+
+            class MyRegistry:
+                '''Custom registry implementation.'''
+
+                def register_message_type(
+                    self,
+                    entry: ModelMessageTypeEntry,
+                ) -> None:
+                    ...
+
+                def get_handlers(
+                    self,
+                    message_type: str,
+                    topic_category: EnumMessageCategory,
+                    topic_domain: str,
+                ) -> list[str]:
+                    ...
+
+                # ... implement all protocol methods
+
+            # Verify protocol compliance
+            registry: ProtocolMessageTypeRegistry = MyRegistry()
+
+    See Also:
+        - :class:`RegistryMessageType`: Primary implementation
+
+    .. versionadded:: 0.5.0
+    """
+
+    # =========================================================================
+    # Registration Methods (available before freeze)
+    # =========================================================================
+
+    def register_message_type(
+        self,
+        entry: ModelMessageTypeEntry,
+    ) -> None:
+        """
+        Register a message type with its handler mappings.
+
+        Associates a message type with handler(s) and defines constraints
+        for valid usage. Supports fan-out by registering multiple handlers
+        for the same message type.
+
+        Args:
+            entry: The message type entry containing handler mappings
+                and constraints.
+
+        Raises:
+            ModelOnexError: If registry is frozen (INVALID_STATE)
+            ModelOnexError: If entry validation fails (VALIDATION_ERROR)
+
+        Thread Safety:
+            Must be thread-safe during registration phase.
+
+        .. versionadded:: 0.5.0
+        """
+        ...
+
+    def freeze(self) -> None:
+        """
+        Freeze the registry to prevent further modifications.
+
+        Once frozen, registration methods will raise ModelOnexError.
+        This enables thread-safe concurrent access during query phase.
+
+        Idempotent: Calling freeze() multiple times has no additional effect.
+
+        Raises:
+            ModelOnexError: If validation fails during freeze (e.g., missing
+                handler references)
+
+        Thread Safety:
+            Must be thread-safe.
+
+        .. versionadded:: 0.5.0
+        """
+        ...
+
+    # =========================================================================
+    # Query Methods (available after freeze)
+    # =========================================================================
+
+    def get_handlers(
+        self,
+        message_type: str,
+        topic_category: EnumMessageCategory,
+        topic_domain: str,
+    ) -> list[str]:
+        """
+        Get handler IDs for a message type with validation.
+
+        Validates that the message type is allowed in the given category
+        and that the topic domain matches domain constraints.
+
+        Args:
+            message_type: The message type to look up.
+            topic_category: The category inferred from the topic.
+            topic_domain: The domain extracted from the topic.
+
+        Returns:
+            List of handler IDs that can process this message type.
+            Empty list if no handlers registered.
+
+        Raises:
+            ModelOnexError: If registry is not frozen (INVALID_STATE)
+            ModelOnexError: If category constraint violated (VALIDATION_ERROR)
+            ModelOnexError: If domain constraint violated (VALIDATION_ERROR)
+
+        Thread Safety:
+            Must be safe for concurrent access after freeze().
+
+        .. versionadded:: 0.5.0
+        """
+        ...
+
+    def get_entry(self, message_type: str) -> ModelMessageTypeEntry | None:
+        """
+        Get the registry entry for a message type.
+
+        Args:
+            message_type: The message type to look up.
+
+        Returns:
+            The registry entry if found, None otherwise.
+
+        Raises:
+            ModelOnexError: If registry is not frozen (INVALID_STATE)
+
+        Thread Safety:
+            Must be safe for concurrent access after freeze().
+
+        .. versionadded:: 0.5.0
+        """
+        ...
+
+    def has_message_type(self, message_type: str) -> bool:
+        """
+        Check if a message type is registered.
+
+        Args:
+            message_type: The message type to check.
+
+        Returns:
+            True if registered, False otherwise.
+
+        Raises:
+            ModelOnexError: If registry is not frozen (INVALID_STATE)
+
+        Thread Safety:
+            Must be safe for concurrent access after freeze().
+
+        .. versionadded:: 0.5.0
+        """
+        ...
+
+    def list_message_types(
+        self,
+        category: EnumMessageCategory | None = None,
+        domain: str | None = None,
+    ) -> list[str]:
+        """
+        List registered message types with optional filtering.
+
+        Args:
+            category: Optional filter by allowed category.
+            domain: Optional filter by owning domain.
+
+        Returns:
+            List of message type names matching the filters.
+
+        Raises:
+            ModelOnexError: If registry is not frozen (INVALID_STATE)
+
+        Thread Safety:
+            Must be safe for concurrent access after freeze().
+
+        .. versionadded:: 0.5.0
+        """
+        ...
+
+    def list_domains(self) -> list[str]:
+        """
+        List all domains that have registered message types.
+
+        Returns:
+            List of unique domain names, sorted alphabetically.
+
+        Raises:
+            ModelOnexError: If registry is not frozen (INVALID_STATE)
+
+        Thread Safety:
+            Must be safe for concurrent access after freeze().
+
+        .. versionadded:: 0.5.0
+        """
+        ...
+
+    # =========================================================================
+    # Validation Methods
+    # =========================================================================
+
+    def validate_startup(self) -> list[str]:
+        """
+        Perform startup-time validation and return any errors.
+
+        Validates registry consistency:
+        - All handler references are valid
+        - No conflicting category constraints
+        - Domain constraints are properly configured
+
+        This method should be called after freeze() to ensure fail-fast
+        behavior before consumers start processing messages.
+
+        Returns:
+            List of validation error messages. Empty list if valid.
+
+        Raises:
+            ModelOnexError: If registry is not frozen (INVALID_STATE)
+
+        Thread Safety:
+            Must be safe for concurrent access after freeze().
+
+        .. versionadded:: 0.5.0
+        """
+        ...
+
+    # =========================================================================
+    # Properties
+    # =========================================================================
+
+    @property
+    def is_frozen(self) -> bool:
+        """
+        Check if the registry is frozen.
+
+        Returns:
+            True if frozen and registration is disabled.
+
+        .. versionadded:: 0.5.0
+        """
+        ...
+
+    @property
+    def entry_count(self) -> int:
+        """
+        Get the number of registered message type entries.
+
+        Returns:
+            Number of registered message types.
+
+        .. versionadded:: 0.5.0
+        """
+        ...
+
+
+__all__ = ["ProtocolMessageTypeRegistry"]