omnibase_infra 0.2.1__py3-none-any.whl

omnibase_infra/protocols/protocol_event_bus_like.py

@@ -0,0 +1,127 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Event Bus Protocol for Introspection.
+
+This module provides the minimal protocol interface for event bus compatibility
+with infrastructure components like ServiceTimeoutEmitter and MixinNodeIntrospection.
+
+Thread Safety:
+    Implementations of ProtocolEventBusLike MUST be thread-safe for concurrent
+    async calls. Multiple coroutines may invoke publish methods simultaneously.
+
+    Design Requirements:
+        - **Connection Pooling**: Use connection pools for underlying transports
+        - **Async-Safe Clients**: Ensure underlying clients (aiokafka, etc.) are async-safe
+        - **No Shared Mutable State**: Avoid instance-level caches that could race
+
+    Recommended Patterns:
+        - Use asyncio.Lock for any shared mutable state (e.g., circuit breakers)
+        - Use MixinAsyncCircuitBreaker for fault tolerance
+        - Keep publish operations stateless where possible
+
+Related:
+    - docs/architecture/CIRCUIT_BREAKER_THREAD_SAFETY.md: Circuit breaker patterns
+    - EventBusKafka: Production implementation with circuit breaker integration
+    - EventBusInmemory: Simple implementation for testing
+
+.. versionadded:: 0.4.0
+"""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+
+@runtime_checkable
+class ProtocolEventBusLike(Protocol):
+    """Protocol for event bus compatibility.
+
+    This protocol defines the minimal interface required for an event bus
+    to be used with infrastructure components. Any object implementing either
+    ``publish_envelope`` or ``publish`` method is compatible.
+
+    The mixin prefers ``publish_envelope`` when available, falling back
+    to ``publish`` for raw bytes publishing.
+
+    Thread Safety:
+        Implementations MUST be thread-safe for concurrent async calls.
+
+        **Guarantees implementers MUST provide:**
+            - Concurrent calls to publish methods are safe
+            - Internal state (if any) is protected by appropriate locks
+            - Underlying transport clients are async-safe
+
+        **Locking recommendations:**
+            - Use asyncio.Lock for shared mutable state
+            - Use MixinAsyncCircuitBreaker for fault tolerance (optional)
+            - Connection state management should use async-safe patterns
+
+        **What callers can assume:**
+            - Multiple coroutines can call publish methods concurrently
+            - Order of message delivery may not match call order (Kafka partitioning)
+            - Each publish is an independent operation
+
+    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.
+
+    See Also:
+        - docs/architecture/CIRCUIT_BREAKER_THREAD_SAFETY.md: Thread safety patterns
+        - MixinAsyncCircuitBreaker: Recommended for production implementations
+    """
+
+    async def publish_envelope(
+        self,
+        envelope: object,
+        topic: str,
+    ) -> None:
+        """Publish an event envelope to a topic.
+
+        Thread Safety:
+            This method MUST be safe for concurrent calls from multiple
+            coroutines. Implementations should not rely on call ordering.
+
+        Envelope Structure:
+            The envelope is typically a Pydantic model (ModelEventEnvelope
+            from omnibase_core) with the following fields:
+
+            - correlation_id: UUID for distributed tracing
+            - event_type: String identifying the event type
+            - payload: The event data (dict or Pydantic model)
+            - metadata: Optional metadata dict
+            - timestamp: When the event was created
+
+            Implementations should support:
+            - Pydantic v2 models (model_dump method)
+            - Pydantic v1 models (dict method)
+            - Plain dict objects
+
+        Args:
+            envelope: The event envelope/model to publish. Typically
+                ModelEventEnvelope, but any Pydantic model or dict is supported.
+            topic: The topic to publish to.
+        """
+        ...
+
+    async def publish(
+        self,
+        topic: str,
+        key: bytes | None,
+        value: bytes,
+    ) -> None:
+        """Publish raw bytes to a topic (fallback method).
+
+        Thread Safety:
+            This method MUST be safe for concurrent calls from multiple
+            coroutines. Implementations should not rely on call ordering.
+
+        Args:
+            topic: The topic to publish to.
+            key: Optional message key as bytes.
+            value: The message value as bytes.
+        """
+        ...
+
+
+__all__: list[str] = ["ProtocolEventBusLike"]

omnibase_infra/protocols/protocol_event_projector.py

@@ -0,0 +1,96 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Event projector protocol for event-to-state projection.
+
+Provides the protocol definition for event projectors that transform
+events into persistent state projections.
+
+Part of OMN-1168: ProjectorPluginLoader contract discovery loading.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Protocol, runtime_checkable
+from uuid import UUID
+
+if TYPE_CHECKING:
+    from omnibase_core.models.events import ModelEventEnvelope
+    from omnibase_core.models.projectors import ModelProjectionResult
+
+
+@runtime_checkable
+class ProtocolEventProjector(Protocol):
+    """Protocol for event-to-state projection.
+
+    Defines the interface that event projectors must implement to transform
+    events into persistent state projections.
+
+    Note:
+        This protocol is defined locally until omnibase_spi provides an
+        official definition. Once available, this should be imported from
+        omnibase_spi instead.
+    """
+
+    @property
+    def projector_id(self) -> str:
+        """Unique identifier for this projector."""
+        ...
+
+    @property
+    def aggregate_type(self) -> str:
+        """The aggregate type this projector handles."""
+        ...
+
+    @property
+    def consumed_events(self) -> list[str]:
+        """Event types this projector consumes."""
+        ...
+
+    @property
+    def is_placeholder(self) -> bool:
+        """Whether this is a placeholder implementation.
+
+        Returns:
+            True if this is a placeholder that will raise NotImplementedError
+            on projection methods, False for full implementations.
+        """
+        ...
+
+    async def project(
+        self,
+        event: ModelEventEnvelope,
+        correlation_id: UUID,
+    ) -> ModelProjectionResult:
+        """Project event to persistence store.
+
+        Args:
+            event: The event envelope to project.
+            correlation_id: Correlation ID for distributed tracing. Required
+                to ensure proper observability across service boundaries.
+
+        Returns:
+            Result of the projection operation.
+        """
+        ...
+
+    async def get_state(
+        self,
+        aggregate_id: UUID,
+        correlation_id: UUID,
+    ) -> object | None:
+        """Get current projected state for an aggregate.
+
+        Args:
+            aggregate_id: The unique identifier of the aggregate.
+            correlation_id: Correlation ID for distributed tracing. Required
+                to ensure proper observability across service boundaries.
+
+        Returns:
+            The current projected state, or None if no state exists.
+        """
+        ...
+
+
+__all__ = [
+    "ProtocolEventProjector",
+]

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.
+        """
+        ...