omnibase_infra 0.2.6__py3-none-any.whl

omnibase_infra/protocols/protocol_container_aware.py

@@ -0,0 +1,200 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Protocol extension for Infrastructure Handlers with Container DI.
+
+This module defines the ProtocolContainerAware interface, which extends the base
+ProtocolHandler from omnibase_spi to add container-based dependency injection
+requirements. All infrastructure handlers in omnibase_infra must implement this
+extended protocol.
+
+Why This Protocol Exists:
+    The base ProtocolHandler in omnibase_spi is intentionally minimal and doesn't
+    mandate a specific constructor signature. This keeps the SPI layer decoupled
+    from implementation details.
+
+    However, omnibase_infra handlers require ModelONEXContainer for:
+    - Dependency injection of shared services (connection pools, clients)
+    - Configuration access without global state
+    - Testability through container mocking
+
+    This protocol adds the __init__ signature requirement while inheriting all
+    method requirements from the base protocol.
+
+Protocol Hierarchy:
+    omnibase_spi.ProtocolHandler (base)
+        - handler_type property
+        - initialize()
+        - shutdown()
+        - execute()
+        - describe()
+        - health_check()
+
+    omnibase_infra.ProtocolContainerAware (extension)
+        - All methods from ProtocolHandler
+        - __init__(container: ModelONEXContainer) requirement
+
+Usage:
+    Infrastructure handlers should implement this extended protocol:
+
+    ```python
+    from omnibase_core.container import ModelONEXContainer
+    from omnibase_infra.protocols import ProtocolContainerAware
+
+    class HandlerDatabase:
+        '''Database handler implementing the infra protocol.'''
+
+        def __init__(self, container: ModelONEXContainer) -> None:
+            self._container = container
+            # Access shared resources via container
+
+        @property
+        def handler_type(self) -> str:
+            return "db"
+
+        # ... implement remaining protocol methods ...
+    ```
+
+    The RuntimeHostProcess uses this protocol for type-safe handler instantiation:
+
+    ```python
+    handler_cls: type[ProtocolContainerAware] = handler_registry.get(handler_type)
+    handler_instance = handler_cls(container=container)  # Type-safe
+    ```
+
+Thread Safety:
+    Handler implementations must be thread-safe. The container provides access
+    to shared resources that may be used concurrently.
+
+See Also:
+    - omnibase_spi.protocols.handlers.protocol_handler.ProtocolHandler
+    - omnibase_core.container.ModelONEXContainer
+    - CLAUDE.md section "Container-Based Dependency Injection"
+    - PR #186: Container DI refactoring for handlers
+
+.. versionadded:: 0.7.1
+    Created as part of OMN-1434 container DI standardization.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Protocol, runtime_checkable
+
+from omnibase_spi.protocols.handlers.protocol_handler import (
+    ProtocolHandler as ProtocolHandlerBase,
+)
+
+if TYPE_CHECKING:
+    from omnibase_core.container import ModelONEXContainer
+
+__all__ = [
+    "ProtocolContainerAware",
+]
+
+
+@runtime_checkable
+class ProtocolContainerAware(ProtocolHandlerBase, Protocol):
+    """Extended protocol for infrastructure handlers with container DI.
+
+    This protocol extends the base ProtocolHandler from omnibase_spi to require
+    a constructor that accepts ModelONEXContainer for dependency injection.
+
+    All infrastructure handlers in omnibase_infra must implement this protocol.
+    The container provides access to:
+    - Database connection pools
+    - HTTP clients
+    - Service discovery clients
+    - Configuration values
+    - Logging context
+
+    Methods inherited from ProtocolHandler:
+        handler_type: Property returning the handler type identifier.
+        initialize: Initialize clients and connection pools.
+        shutdown: Release resources and close connections.
+        execute: Execute protocol-specific operations.
+        describe: Return handler metadata and capabilities.
+        health_check: Check handler health and connectivity.
+
+    Constructor Requirement (added by this protocol):
+        __init__: Must accept container: ModelONEXContainer as first positional argument.
+
+    Example:
+        ```python
+        from omnibase_core.container import ModelONEXContainer
+
+        class HandlerConsul:
+            def __init__(self, container: ModelONEXContainer) -> None:
+                self._container = container
+                self._consul_url = container.config.get("consul_url")
+
+            @property
+            def handler_type(self) -> str:
+                return "consul"
+
+            async def initialize(self, config):
+                # Use container for shared resources
+                ...
+
+            # ... implement remaining methods ...
+        ```
+
+    Protocol Verification:
+        Per ONEX conventions, verify protocol compliance via duck typing:
+
+        ```python
+        handler_cls = handler_registry.get("http")
+
+        # Verify constructor signature accepts container
+        import inspect
+        sig = inspect.signature(handler_cls.__init__)
+        params = list(sig.parameters.keys())
+        assert "container" in params or len(params) > 1  # self + container
+
+        # Verify protocol methods exist
+        assert hasattr(handler_cls, "handler_type")
+        assert hasattr(handler_cls, "initialize") and callable(getattr(handler_cls, "initialize"))
+        ```
+
+    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.
+    """
+
+    def __init__(self, container: ModelONEXContainer) -> None:
+        """Initialize the handler with a dependency injection container.
+
+        All infrastructure handlers receive their dependencies through the
+        container rather than as individual constructor arguments. This enables:
+
+        - Consistent initialization across all handlers
+        - Easy testing through container mocking
+        - Runtime configuration without code changes
+        - Shared resource management (connection pools, clients)
+
+        Args:
+            container: ONEX dependency injection container providing access to:
+                - Configuration values (container.config)
+                - Shared services (database pools, HTTP clients)
+                - Logging context
+                - Runtime metadata
+
+        Note:
+            Handlers should store the container reference and access dependencies
+            lazily when needed, rather than extracting all values in __init__.
+            This improves startup time and allows for late-bound configuration.
+
+        Example:
+            ```python
+            def __init__(self, container: ModelONEXContainer) -> None:
+                self._container = container
+                self._client: httpx.AsyncClient | None = None  # Lazy init
+
+            async def initialize(self, config):
+                # Create client during initialize(), not __init__()
+                self._client = httpx.AsyncClient(
+                    base_url=self._container.config.get("base_url"),
+                    timeout=config.get("timeout", 30.0),
+                )
+            ```
+        """
+        ...

omnibase_infra/protocols/protocol_dispatch_engine.py

@@ -0,0 +1,152 @@
+# Copyright (c) 2025 OmniNode Team
+"""Protocol definition for dispatch engine interface.
+
+This module defines the ProtocolDispatchEngine interface for dispatch engines
+that route event envelopes to appropriate handlers based on topic. The primary
+implementation is MessageDispatchEngine in the runtime module.
+
+Architecture:
+    The dispatch engine sits between event bus consumption and handler execution:
+
+    Kafka/EventBus -> EventBusSubcontractWiring -> ProtocolDispatchEngine -> Handlers
+
+    The wiring layer uses this protocol for duck-typed dispatch engine injection,
+    enabling both production MessageDispatchEngine and test mocks.
+
+Thread Safety:
+    Implementations MUST be thread-safe for concurrent async dispatch calls.
+    Multiple coroutines may invoke dispatch() simultaneously from event bus
+    callbacks.
+
+    Design Requirements:
+        - Use asyncio.Lock for shared mutable state (e.g., routing tables)
+        - Dispatch operations should be stateless where possible
+        - Handler invocations may run concurrently
+
+Related:
+    - OMN-1621: Runtime consumes event_bus subcontract for contract-driven wiring
+    - EventBusSubcontractWiring: Uses this protocol for dispatch engine injection
+    - MessageDispatchEngine: Production implementation of this protocol
+
+.. versionadded:: 0.2.5
+"""
+
+from __future__ import annotations
+
+__all__ = ["ProtocolDispatchEngine"]
+
+from typing import TYPE_CHECKING, Protocol, runtime_checkable
+
+if TYPE_CHECKING:
+    from omnibase_core.models.events.model_event_envelope import ModelEventEnvelope
+    from omnibase_infra.models.dispatch.model_dispatch_result import ModelDispatchResult
+
+
+@runtime_checkable
+class ProtocolDispatchEngine(Protocol):
+    """Protocol for dispatch engines that route event envelopes to handlers.
+
+    Dispatch engines are responsible for routing incoming event envelopes
+    to the appropriate handlers based on topic and message type. The protocol
+    enables duck-typed injection of dispatch engines into the event bus wiring
+    layer.
+
+    Protocol Verification:
+        Per ONEX conventions, protocol compliance is verified via duck typing
+        rather than isinstance checks:
+
+        .. code-block:: python
+
+            # Verify required method exists and is callable
+            if hasattr(engine, 'dispatch') and callable(engine.dispatch):
+                wiring = EventBusSubcontractWiring(
+                    event_bus=event_bus,
+                    dispatch_engine=engine,
+                    environment="dev",
+                )
+            else:
+                raise TypeError("Object does not implement ProtocolDispatchEngine")
+
+    Example:
+        .. code-block:: python
+
+            from omnibase_infra.protocols import ProtocolDispatchEngine
+            from omnibase_core.models.events.model_event_envelope import ModelEventEnvelope
+
+            class MyDispatchEngine:
+                '''Custom dispatch engine implementation.'''
+
+                async def dispatch(
+                    self,
+                    topic: str,
+                    envelope: ModelEventEnvelope[object],
+                ) -> ModelDispatchResult | None:
+                    '''Dispatch envelope to appropriate handler.'''
+                    handler = self._resolve_handler(topic, envelope)
+                    return await handler.handle(envelope)
+
+            # Verify protocol compliance via duck typing
+            engine = MyDispatchEngine()
+            assert hasattr(engine, 'dispatch') and callable(engine.dispatch)
+
+    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.2.5
+    """
+
+    async def dispatch(
+        self,
+        topic: str,
+        envelope: ModelEventEnvelope[object],
+    ) -> ModelDispatchResult | None:
+        """Dispatch an event envelope to the appropriate handler(s).
+
+        Routes the envelope to handlers registered for the given topic.
+        The dispatch engine resolves handlers based on topic patterns,
+        message types, and other routing criteria.
+
+        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
+            - The dispatch engine handles envelopes from multiple topics with
+              different payload types
+            - Handler implementations use ``isinstance()`` type guards for
+              payload-specific processing
+
+        Thread Safety:
+            This method MUST be safe for concurrent calls from multiple
+            coroutines. The event bus wiring layer may dispatch messages
+            from multiple topic subscriptions concurrently.
+
+        Args:
+            topic: The full topic name from which the envelope was consumed.
+                Used for routing and logging context.
+                Example: "dev.onex.evt.node.introspected.v1"
+            envelope: The deserialized event envelope containing the payload.
+                The payload type varies by topic/event type.
+
+        Returns:
+            ModelDispatchResult if the implementation returns dispatch metrics/results,
+            None if the implementation does not track results. Callers should not
+            depend on the return value for correctness.
+
+        Raises:
+            InfraDispatchError: If no handler is registered for the topic/message type.
+            OnexError: For handler execution failures (implementation-specific).
+
+        Example:
+            .. code-block:: python
+
+                # Event bus wiring callback
+                async def on_message(message: ProtocolEventMessage) -> None:
+                    envelope = deserialize(message)
+                    await dispatch_engine.dispatch(topic, envelope)
+        """
+        ...

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.model_event_envelope 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",
+]