omnibase_infra 0.2.6__py3-none-any.whl

omnibase_infra/protocols/__init__.py

@@ -0,0 +1,104 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Protocol definitions for omnibase_infra.
+
+This module provides protocol definitions (duck-typed interfaces) for infrastructure
+components in the ONEX ecosystem.
+
+Protocols:
+    - ProtocolCapabilityProjection: Interface for capability-based projection queries
+    - ProtocolCapabilityQuery: Interface for capability-based node discovery service
+    - ProtocolDispatchEngine: Interface for message dispatch engines
+    - ProtocolEventBusLike: Interface for event bus abstraction (used by introspection)
+    - ProtocolIdempotencyStore: Interface for idempotency checking and deduplication
+    - ProtocolMessageDispatcher: Interface for message dispatchers
+    - ProtocolMessageTypeRegistry: Interface for message type registries
+    - ProtocolPluginCompute: Interface for deterministic compute plugins
+    - ProtocolRegistryMetrics: Interface for registry metrics collection (optional)
+    - ProtocolSnapshotPublisher: Interface for snapshot publishing services (F2)
+    - ProtocolSnapshotStore: Interface for snapshot storage backends
+
+Note:
+    ProtocolCircuitBreakerAware is defined in omnibase_infra.mixins (tightly coupled
+    to MixinAsyncCircuitBreaker). Import it from there, not from this package.
+
+Architecture:
+    Protocols enable duck typing and dependency injection without requiring
+    inheritance. Classes implementing a protocol are automatically recognized
+    through structural typing (matching method signatures).
+
+Usage:
+    ```python
+    from omnibase_infra.protocols import (
+        ProtocolCapabilityQuery,
+        ProtocolEventBusLike,
+        ProtocolIdempotencyStore,
+        ProtocolPluginCompute,
+        ProtocolRegistryMetrics,
+        ProtocolSnapshotPublisher,
+        ProtocolSnapshotStore,
+    )
+
+    # Verify protocol compliance via duck typing (per ONEX conventions)
+    plugin = MyComputePlugin()
+    assert hasattr(plugin, 'execute') and callable(plugin.execute)
+
+    publisher = MySnapshotPublisher()
+    assert hasattr(publisher, 'publish_snapshot') and callable(publisher.publish_snapshot)
+    assert hasattr(publisher, 'delete_snapshot') and callable(publisher.delete_snapshot)
+
+    store = MyIdempotencyStore()
+    assert hasattr(store, 'check_and_record') and callable(store.check_and_record)
+    ```
+
+See Also:
+    - omnibase_infra.plugins for base class implementations
+    - omnibase_infra.models.projection for projection models
+    - omnibase_infra.mixins for ProtocolCircuitBreakerAware
+    - ONEX 4-node architecture documentation
+    - OMN-947 (F2) for snapshot publishing design
+"""
+
+from omnibase_infra.protocols.protocol_capability_projection import (
+    ProtocolCapabilityProjection,
+)
+from omnibase_infra.protocols.protocol_capability_query import ProtocolCapabilityQuery
+from omnibase_infra.protocols.protocol_container_aware import ProtocolContainerAware
+from omnibase_infra.protocols.protocol_dispatch_engine import ProtocolDispatchEngine
+from omnibase_infra.protocols.protocol_event_bus_like import ProtocolEventBusLike
+from omnibase_infra.protocols.protocol_event_projector import ProtocolEventProjector
+from omnibase_infra.protocols.protocol_idempotency_store import (
+    ProtocolIdempotencyStore,
+)
+from omnibase_infra.protocols.protocol_message_dispatcher import (
+    ProtocolMessageDispatcher,
+)
+from omnibase_infra.protocols.protocol_message_type_registry import (
+    ProtocolMessageTypeRegistry,
+)
+from omnibase_infra.protocols.protocol_plugin_compute import ProtocolPluginCompute
+from omnibase_infra.protocols.protocol_projector_schema_validator import (
+    ProtocolProjectorSchemaValidator,
+)
+from omnibase_infra.protocols.protocol_registry_metrics import ProtocolRegistryMetrics
+from omnibase_infra.protocols.protocol_snapshot_publisher import (
+    ProtocolSnapshotPublisher,
+)
+from omnibase_infra.protocols.protocol_snapshot_store import ProtocolSnapshotStore
+
+__all__: list[str] = [
+    "ProtocolCapabilityProjection",
+    "ProtocolCapabilityQuery",
+    "ProtocolEventBusLike",
+    "ProtocolEventProjector",
+    "ProtocolContainerAware",
+    "ProtocolDispatchEngine",
+    "ProtocolIdempotencyStore",
+    "ProtocolMessageDispatcher",
+    "ProtocolMessageTypeRegistry",
+    "ProtocolPluginCompute",
+    "ProtocolProjectorSchemaValidator",
+    "ProtocolRegistryMetrics",
+    "ProtocolSnapshotPublisher",
+    "ProtocolSnapshotStore",
+]

omnibase_infra/protocols/protocol_capability_projection.py

@@ -0,0 +1,253 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Protocol for Capability-Based Projection Queries.
+
+This module defines the protocol interface for querying registration projections
+by capability fields. Enables fast capability-based node discovery using
+GIN-indexed array queries.
+
+Related Tickets:
+    - OMN-1134: Registry Projection Extensions for Capabilities
+    - OMN-1135: CapabilityQueryService (consumer of this protocol)
+
+Example:
+    >>> class CapabilityQueryService:
+    ...     def __init__(self, reader: ProtocolCapabilityProjection):
+    ...         self._reader = reader
+    ...
+    ...     async def find_postgres_adapters(self) -> list[ModelRegistrationProjection]:
+    ...         return await self._reader.get_by_capability_tag("postgres.storage")
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Protocol, runtime_checkable
+from uuid import UUID
+
+if TYPE_CHECKING:
+    from omnibase_infra.enums import EnumRegistrationState
+    from omnibase_infra.models.projection.model_registration_projection import (
+        ContractType,
+        ModelRegistrationProjection,
+    )
+
+
+@runtime_checkable
+class ProtocolCapabilityProjection(Protocol):
+    """Protocol for capability-based projection queries.
+
+    Defines the interface for querying registration projections by capability
+    fields. Implementations use GIN-indexed PostgreSQL array queries for
+    efficient lookups.
+
+    Canonical Implementation:
+        The reference implementation of this protocol is
+        ``ProjectionReaderRegistration`` in:
+
+            ``omnibase_infra/projectors/projection_reader_registration.py``
+
+        This implementation provides:
+        - asyncpg-based PostgreSQL queries with connection pooling
+        - Circuit breaker resilience (MixinAsyncCircuitBreaker)
+        - Parameterized queries for SQL injection protection
+        - Consistent error handling with InfraConnectionError/InfraTimeoutError
+        - Optional state filtering on all capability query methods
+
+    Methods:
+        get_by_capability_tag: Find nodes by capability tag (e.g., "postgres.storage").
+            Uses GIN index on capability_tags column.
+        get_by_intent_type: Find nodes by intent type they handle (e.g., "postgres.query").
+            Uses GIN index on intent_types column.
+        get_by_protocol: Find nodes implementing a specific protocol
+            (e.g., "ProtocolEventPublisher"). Uses GIN index on protocols column.
+        get_by_contract_type: Find nodes by contract type (effect, compute, reducer,
+            orchestrator). Uses B-tree index on contract_type column.
+        get_by_capability_tags_all: Find nodes with ALL specified tags.
+            Uses GIN index with @> (contains all) operator.
+        get_by_capability_tags_any: Find nodes with ANY of the specified tags.
+            Uses GIN index with && (overlaps) operator.
+
+    Query Performance:
+        All methods use GIN-indexed array queries which provide:
+        - O(log n) lookup time for single-element containment
+        - Efficient multi-tag queries using array operators
+        - Automatic index selection by PostgreSQL query planner
+
+    Example:
+        >>> import asyncpg
+        >>> from omnibase_infra.projectors import ProjectionReaderRegistration
+        >>> from omnibase_infra.enums import EnumRegistrationState
+        >>>
+        >>> # Create reader with connection pool
+        >>> pool = await asyncpg.create_pool(dsn)
+        >>> reader = ProjectionReaderRegistration(pool)
+        >>>
+        >>> # Find all active Kafka consumers
+        >>> kafka_nodes = await reader.get_by_capability_tag(
+        ...     "kafka.consumer",
+        ...     state=EnumRegistrationState.ACTIVE,
+        ... )
+        >>>
+        >>> # Find nodes implementing a protocol
+        >>> publishers = await reader.get_by_protocol("ProtocolEventPublisher")
+        >>>
+        >>> # Find effect nodes
+        >>> effects = await reader.get_by_contract_type("effect")
+
+    See Also:
+        - ``ProtocolProjectionReader``: Base protocol for all projection readers
+        - ``ModelRegistrationProjection``: The projection model returned by queries
+        - ``EnumRegistrationState``: FSM states for optional state filtering
+    """
+
+    async def get_by_capability_tag(
+        self,
+        tag: str,
+        state: EnumRegistrationState | None = None,
+        correlation_id: UUID | None = None,
+    ) -> list[ModelRegistrationProjection]:
+        """Find all registrations with the specified capability tag.
+
+        Uses GIN index on capability_tags column for efficient lookup.
+
+        Args:
+            tag: The capability tag to search for (e.g., "postgres.storage")
+            state: Optional state filter (e.g., EnumRegistrationState.ACTIVE)
+            correlation_id: Optional correlation ID for distributed tracing
+
+        Returns:
+            List of matching registration projections
+
+        Example:
+            >>> adapters = await reader.get_by_capability_tag("kafka.consumer")
+            >>> for adapter in adapters:
+            ...     print(f"{adapter.entity_id}: {adapter.node_type}")
+        """
+        ...
+
+    async def get_by_intent_type(
+        self,
+        intent_type: str,
+        state: EnumRegistrationState | None = None,
+        correlation_id: UUID | None = None,
+    ) -> list[ModelRegistrationProjection]:
+        """Find all registrations that handle the specified intent type.
+
+        Uses GIN index on intent_types column for efficient lookup.
+
+        Args:
+            intent_type: The intent type to search for (e.g., "postgres.upsert")
+            state: Optional state filter (e.g., EnumRegistrationState.ACTIVE)
+            correlation_id: Optional correlation ID for distributed tracing
+
+        Returns:
+            List of matching registration projections
+
+        Example:
+            >>> handlers = await reader.get_by_intent_type("postgres.query")
+            >>> for handler in handlers:
+            ...     print(f"Can handle postgres.query: {handler.entity_id}")
+        """
+        ...
+
+    async def get_by_protocol(
+        self,
+        protocol_name: str,
+        state: EnumRegistrationState | None = None,
+        correlation_id: UUID | None = None,
+    ) -> list[ModelRegistrationProjection]:
+        """Find all registrations implementing the specified protocol.
+
+        Uses GIN index on protocols column for efficient lookup.
+
+        Args:
+            protocol_name: The protocol name (e.g., "ProtocolDatabaseAdapter")
+            state: Optional state filter (e.g., EnumRegistrationState.ACTIVE)
+            correlation_id: Optional correlation ID for distributed tracing
+
+        Returns:
+            List of matching registration projections
+
+        Example:
+            >>> adapters = await reader.get_by_protocol("ProtocolEventPublisher")
+            >>> print(f"Found {len(adapters)} event publishers")
+        """
+        ...
+
+    async def get_by_contract_type(
+        self,
+        contract_type: ContractType,
+        state: EnumRegistrationState | None = None,
+        correlation_id: UUID | None = None,
+    ) -> list[ModelRegistrationProjection]:
+        """Find all registrations of the specified contract type.
+
+        Uses B-tree index on contract_type column for efficient lookup.
+
+        Args:
+            contract_type: The contract type. Must be one of: "effect", "compute",
+                "reducer", or "orchestrator"
+            state: Optional state filter (e.g., EnumRegistrationState.ACTIVE)
+            correlation_id: Optional correlation ID for distributed tracing
+
+        Returns:
+            List of matching registration projections
+
+        Example:
+            >>> effects = await reader.get_by_contract_type("effect")
+            >>> print(f"Found {len(effects)} effect nodes")
+        """
+        ...
+
+    async def get_by_capability_tags_all(
+        self,
+        tags: list[str],
+        state: EnumRegistrationState | None = None,
+        correlation_id: UUID | None = None,
+    ) -> list[ModelRegistrationProjection]:
+        """Find registrations with ALL specified capability tags.
+
+        Uses GIN index with @> (contains all) operator.
+
+        Args:
+            tags: List of capability tags that must all be present
+            state: Optional state filter (e.g., EnumRegistrationState.ACTIVE)
+            correlation_id: Optional correlation ID for distributed tracing
+
+        Returns:
+            List of matching registration projections
+
+        Example:
+            >>> adapters = await reader.get_by_capability_tags_all(
+            ...     ["postgres.storage", "transactions"]
+            ... )
+        """
+        ...
+
+    async def get_by_capability_tags_any(
+        self,
+        tags: list[str],
+        state: EnumRegistrationState | None = None,
+        correlation_id: UUID | None = None,
+    ) -> list[ModelRegistrationProjection]:
+        """Find registrations with ANY of the specified capability tags.
+
+        Uses GIN index with && (overlaps) operator.
+
+        Args:
+            tags: List of capability tags, at least one must be present
+            state: Optional state filter (e.g., EnumRegistrationState.ACTIVE)
+            correlation_id: Optional correlation ID for distributed tracing
+
+        Returns:
+            List of matching registration projections
+
+        Example:
+            >>> adapters = await reader.get_by_capability_tags_any(
+            ...     ["postgres.storage", "mysql.storage", "sqlite.storage"]
+            ... )
+        """
+        ...
+
+
+__all__: list[str] = ["ProtocolCapabilityProjection"]

omnibase_infra/protocols/protocol_capability_query.py

@@ -0,0 +1,251 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Protocol for Capability-Based Node Query Service.
+
+Defines the protocol interface for querying nodes by capability rather than
+by name. This enables capability-based auto-configuration where consumers
+declare what they need, not who provides it.
+
+Core Principle: "I'm interested in what you do, not what you are."
+
+Related Tickets:
+    - OMN-1135: ServiceCapabilityQuery for capability-based discovery
+    - OMN-1134: Registry Projection Extensions for Capabilities
+
+Example:
+    >>> class MyCapabilityQuery:
+    ...     async def find_nodes_by_capability(
+    ...         self, capability: str, ...
+    ...     ) -> list[ModelRegistrationProjection]:
+    ...         # Query registry for nodes with this capability
+    ...         ...
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Protocol, runtime_checkable
+from uuid import UUID
+
+if TYPE_CHECKING:
+    from omnibase_infra.enums import EnumRegistrationState
+    from omnibase_infra.models.discovery.model_dependency_spec import (
+        ModelDependencySpec,
+    )
+    from omnibase_infra.models.projection.model_registration_projection import (
+        ModelRegistrationProjection,
+    )
+
+
+@runtime_checkable
+class ProtocolCapabilityQuery(Protocol):
+    """Protocol for capability-based node queries.
+
+    Defines the interface for querying registration projections by capability
+    attributes (capability tags, intent types, protocols) rather than by name.
+
+    This protocol enables loose coupling between consumers and providers:
+    consumers declare what capabilities they need, and the system discovers
+    which nodes provide them.
+
+    Canonical Implementation:
+        The reference implementation of this protocol is
+        ``ServiceCapabilityQuery`` in:
+
+            ``omnibase_infra/services/service_capability_query.py``
+
+        This implementation provides:
+        - Delegation to ProjectionReaderRegistration for database queries
+        - Contract type filtering
+        - Dependency resolution from ModelDependencySpec
+        - Node selection strategies (first, random, round-robin, least-loaded)
+
+    Methods:
+        find_nodes_by_capability: Find nodes by capability tag.
+        find_nodes_by_intent_type: Find effect nodes by intent type handled.
+        find_nodes_by_protocol: Find nodes implementing a specific protocol.
+        resolve_dependency: Resolve a ModelDependencySpec to a concrete node.
+
+    Example:
+        >>> from omnibase_infra.services import ServiceCapabilityQuery
+        >>> from omnibase_infra.projectors import ProjectionReaderRegistration
+        >>>
+        >>> reader = ProjectionReaderRegistration(pool)
+        >>> query = ServiceCapabilityQuery(reader)
+        >>>
+        >>> # Find all Kafka consumers
+        >>> kafka_nodes = await query.find_nodes_by_capability("kafka.consumer")
+        >>>
+        >>> # Find nodes that handle postgres.upsert intent
+        >>> handlers = await query.find_nodes_by_intent_type("postgres.upsert")
+        >>>
+        >>> # Resolve a dependency specification
+        >>> spec = ModelDependencySpec(
+        ...     name="storage",
+        ...     type="node",
+        ...     capability="postgres.storage",
+        ... )
+        >>> node = await query.resolve_dependency(spec)
+
+    See Also:
+        - ``ProtocolCapabilityProjection``: Lower-level projection query protocol
+        - ``ModelDependencySpec``: Dependency specification model
+        - ``ModelRegistrationProjection``: The projection model returned by queries
+        - ``EnumRegistrationState``: FSM states for optional state filtering
+    """
+
+    async def find_nodes_by_capability(
+        self,
+        capability: str,
+        contract_type: str | None = None,
+        state: EnumRegistrationState | None = None,
+        correlation_id: UUID | None = None,
+    ) -> list[ModelRegistrationProjection]:
+        """Find nodes that provide a specific capability.
+
+        Queries the registry for nodes with the specified capability tag.
+        Optionally filters by contract type and registration state.
+
+        Args:
+            capability: Capability tag to search for (e.g., "postgres.storage",
+                "kafka.consumer", "consul.registration").
+            contract_type: Optional filter by contract type ("effect", "compute",
+                "reducer", "orchestrator").
+            state: Registration state filter. When None (default), filters to
+                EnumRegistrationState.ACTIVE to return only actively registered
+                nodes. Pass an explicit EnumRegistrationState value to query
+                nodes in other states (e.g., PENDING_REGISTRATION, LIVENESS_EXPIRED).
+            correlation_id: Optional correlation ID for distributed tracing.
+                When provided, included in all log messages for request tracking.
+
+        Returns:
+            List of matching registration projections. Empty list if no matches.
+
+        Example:
+            >>> nodes = await query.find_nodes_by_capability(
+            ...     "postgres.storage",
+            ...     contract_type="effect",
+            ...     state=EnumRegistrationState.ACTIVE,
+            ...     correlation_id=uuid4(),
+            ... )
+            >>> for node in nodes:
+            ...     print(f"Found: {node.entity_id}")
+        """
+        ...
+
+    async def find_nodes_by_intent_type(
+        self,
+        intent_type: str,
+        contract_type: str = "effect",
+        state: EnumRegistrationState | None = None,
+        correlation_id: UUID | None = None,
+    ) -> list[ModelRegistrationProjection]:
+        """Find effect nodes that handle a specific intent type.
+
+        Queries the registry for nodes that can handle the specified intent type.
+        Typically used to find effect nodes that execute specific intents.
+
+        Args:
+            intent_type: Intent type to search for (e.g., "postgres.upsert",
+                "consul.register", "kafka.publish").
+            contract_type: Filter by contract type (default: "effect").
+                Intents are typically handled by effect nodes.
+            state: Registration state filter. When None (default), filters to
+                EnumRegistrationState.ACTIVE to return only actively registered
+                nodes. Pass an explicit EnumRegistrationState value to query
+                nodes in other states (e.g., PENDING_REGISTRATION, LIVENESS_EXPIRED).
+            correlation_id: Optional correlation ID for distributed tracing.
+                When provided, included in all log messages for request tracking.
+
+        Returns:
+            List of matching registration projections. Empty list if no matches.
+
+        Example:
+            >>> handlers = await query.find_nodes_by_intent_type(
+            ...     "postgres.query",
+            ...     contract_type="effect",
+            ...     state=EnumRegistrationState.ACTIVE,
+            ...     correlation_id=uuid4(),
+            ... )
+            >>> for handler in handlers:
+            ...     print(f"Can handle postgres.query: {handler.entity_id}")
+        """
+        ...
+
+    async def find_nodes_by_protocol(
+        self,
+        protocol: str,
+        contract_type: str | None = None,
+        state: EnumRegistrationState | None = None,
+        correlation_id: UUID | None = None,
+    ) -> list[ModelRegistrationProjection]:
+        """Find nodes implementing a specific protocol.
+
+        Queries the registry for nodes that implement the specified protocol.
+        Useful for finding nodes that satisfy interface requirements.
+
+        Args:
+            protocol: Protocol name to search for (e.g., "ProtocolEventPublisher",
+                "ProtocolReducer", "ProtocolDatabaseAdapter").
+            contract_type: Optional filter by contract type ("effect", "compute",
+                "reducer", "orchestrator").
+            state: Registration state filter. When None (default), filters to
+                EnumRegistrationState.ACTIVE to return only actively registered
+                nodes. Pass an explicit EnumRegistrationState value to query
+                nodes in other states (e.g., PENDING_REGISTRATION, LIVENESS_EXPIRED).
+            correlation_id: Optional correlation ID for distributed tracing.
+                When provided, included in all log messages for request tracking.
+
+        Returns:
+            List of matching registration projections. Empty list if no matches.
+
+        Example:
+            >>> adapters = await query.find_nodes_by_protocol(
+            ...     "ProtocolEventPublisher",
+            ...     state=EnumRegistrationState.ACTIVE,
+            ...     correlation_id=uuid4(),
+            ... )
+            >>> print(f"Found {len(adapters)} event publishers")
+        """
+        ...
+
+    async def resolve_dependency(
+        self,
+        dependency_spec: ModelDependencySpec,
+        correlation_id: UUID | None = None,
+    ) -> ModelRegistrationProjection | None:
+        """Resolve a dependency specification to a concrete node.
+
+        Uses the dependency specification to query the registry and select
+        a node that matches the specified capability criteria.
+
+        Resolution Strategy:
+            1. If capability specified -> find by capability
+            2. If intent_types specified -> find by intent type
+            3. If protocol specified -> find by protocol
+            4. Apply selection strategy to choose among matches
+
+        Args:
+            dependency_spec: Dependency specification from contract.
+                Contains capability filters and selection strategy.
+            correlation_id: Optional correlation ID for distributed tracing.
+                When provided, included in all log messages for request tracking.
+
+        Returns:
+            Resolved node registration, or None if not found.
+
+        Example:
+            >>> spec = ModelDependencySpec(
+            ...     name="storage",
+            ...     type="node",
+            ...     capability="postgres.storage",
+            ...     contract_type="effect",
+            ...     selection_strategy="round_robin",
+            ... )
+            >>> node = await query.resolve_dependency(spec, correlation_id=uuid4())
+            >>> if node:
+            ...     print(f"Resolved to: {node.entity_id}")
+        """
+        ...
+
+
+__all__: list[str] = ["ProtocolCapabilityQuery"]