omnibase_infra 0.2.6__py3-none-any.whl

omnibase_infra/nodes/node_service_discovery_effect/protocols/protocol_discovery_operations.py

@@ -0,0 +1,279 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Protocol for Service Discovery Operations.
+
+This module defines ProtocolDiscoveryOperations, the protocol for
+pluggable service discovery backends in the NodeServiceDiscoveryEffect node.
+
+Architecture:
+    ProtocolDiscoveryOperations defines the interface for service
+    discovery backends. Implementations include:
+    - Consul: HashiCorp Consul service discovery
+    - Kubernetes: K8s native service discovery
+    - Etcd: CoreOS etcd service discovery
+
+    This protocol enables the capability-oriented design principle:
+    "I'm interested in what you do, not what you are"
+
+Protocol Duplication Note:
+    This protocol is intentionally separate from the handler-level protocol
+    at ``handlers/service_discovery/protocol_discovery_operations.py``:
+
+    - **This protocol (nodes/*/protocols/)**: Node-level contract used for
+      container-based dependency injection and registry binding. Uses
+      ``ModelServiceRegistration`` with required ``correlation_id``.
+
+    - **Handler protocol (handlers/*/protocol_*.py)**: Handler implementation
+      contract used by tests for compliance verification. Uses
+      ``ModelServiceInfo`` with optional ``correlation_id``.
+
+    The separation allows:
+    1. Node-level protocols to evolve independently of handler contracts
+    2. Different parameter models appropriate for each layer
+    3. Clear ownership boundaries (nodes own their protocols)
+
+    Both protocols share the same name for discoverability, but serve
+    different architectural layers.
+
+Protocol Verification:
+    Per ONEX conventions, protocol compliance is verified via duck typing
+    rather than isinstance checks. The @runtime_checkable decorator enables
+    structural subtyping checks.
+
+    However, registries use isinstance() for fail-fast validation at
+    registration time. See registry_infra_service_discovery.py for rationale.
+
+Thread Safety:
+    Handler implementations may be invoked concurrently.
+    Implementations should be designed for thread-safe operation.
+
+Related:
+    - NodeServiceDiscoveryEffect: Effect node that uses this protocol
+    - ModelServiceRegistration: Input model for registration
+    - ModelDiscoveryQuery: Input model for discovery queries
+    - ModelDiscoveryResult: Output model for discovery results
+    - ModelRegistrationResult: Output model for registration
+    - handlers/service_discovery/protocol_discovery_operations.py: Handler protocol
+    - OMN-1131: Capability-oriented node architecture
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Protocol, runtime_checkable
+from uuid import UUID
+
+if TYPE_CHECKING:
+    from omnibase_infra.nodes.node_service_discovery_effect.models import (
+        ModelDiscoveryQuery,
+        ModelDiscoveryResult,
+        ModelRegistrationResult,
+        ModelServiceDiscoveryHealthCheckResult,
+        ModelServiceRegistration,
+    )
+
+
+@runtime_checkable
+class ProtocolDiscoveryOperations(Protocol):
+    """Protocol for service discovery backends.
+
+    Defines the interface that all service discovery backend handlers
+    must implement. This enables pluggable backends (Consul, Kubernetes,
+    Etcd) while maintaining a unified capability-oriented interface.
+
+    Protocol Verification:
+        Per ONEX conventions, protocol compliance is verified via duck typing:
+
+        .. code-block:: python
+
+            # Verify required properties and methods exist
+            if (hasattr(handler, 'handler_type') and
+                hasattr(handler, 'register_service') and callable(handler.register_service)):
+                registry.register_handler(handler)
+
+    Attributes:
+        handler_type: Type identifier for this handler (consul, kubernetes, etcd).
+
+    Methods:
+        register_service: Register a service with the backend.
+        deregister_service: Remove a service registration.
+        discover_services: Query for service instances.
+        health_check: Verify backend connectivity.
+
+    Example:
+        .. code-block:: python
+
+            class ConsulServiceDiscoveryHandler:
+                '''Consul implementation of service discovery.'''
+
+                @property
+                def handler_type(self) -> str:
+                    return "consul"
+
+                async def register_service(
+                    self,
+                    registration: ModelServiceRegistration,
+                    correlation_id: UUID,
+                ) -> ModelRegistrationResult:
+                    # Consul-specific registration logic
+                    ...
+
+                async def deregister_service(
+                    self,
+                    service_id: UUID,
+                    correlation_id: UUID,
+                ) -> None:
+                    # Consul-specific deregistration logic
+                    ...
+
+                async def discover_services(
+                    self,
+                    query: ModelDiscoveryQuery,
+                    correlation_id: UUID,
+                ) -> ModelDiscoveryResult:
+                    # Consul-specific discovery logic
+                    ...
+
+                async def health_check(
+                    self,
+                    correlation_id: UUID | None = None,
+                ) -> ModelServiceDiscoveryHealthCheckResult:
+                    # Check Consul agent connectivity
+                    ...
+
+    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.6.0
+    """
+
+    @property
+    def handler_type(self) -> str:
+        """Return the type identifier for this handler.
+
+        The handler type identifies the backend implementation:
+        - "consul": HashiCorp Consul
+        - "kubernetes": Kubernetes native
+        - "etcd": CoreOS etcd
+
+        Returns:
+            str: Handler type identifier.
+        """
+        ...
+
+    async def register_service(
+        self,
+        registration: ModelServiceRegistration,
+        correlation_id: UUID,
+    ) -> ModelRegistrationResult:
+        """Register a service with the backend.
+
+        Creates or updates a service registration in the service
+        discovery backend. The operation should be idempotent.
+
+        Args:
+            registration: Service registration details including
+                service_id, service_name, address, port, tags, etc.
+            correlation_id: Correlation ID for distributed tracing.
+
+        Returns:
+            ModelRegistrationResult with success status and any errors.
+
+        Raises:
+            InfraConnectionError: If connection to backend fails.
+            InfraTimeoutError: If operation times out.
+            InfraUnavailableError: If circuit breaker is open.
+        """
+        ...
+
+    async def deregister_service(
+        self,
+        service_id: UUID,
+        correlation_id: UUID,
+    ) -> None:
+        """Deregister a service from the backend.
+
+        Removes a service registration from the service discovery
+        backend. The operation should be idempotent (no error if
+        service does not exist).
+
+        Args:
+            service_id: ID of the service to deregister.
+            correlation_id: Correlation ID for distributed tracing.
+
+        Raises:
+            InfraConnectionError: If connection to backend fails.
+            InfraTimeoutError: If operation times out.
+            InfraUnavailableError: If circuit breaker is open.
+        """
+        ...
+
+    async def discover_services(
+        self,
+        query: ModelDiscoveryQuery,
+        correlation_id: UUID,
+    ) -> ModelDiscoveryResult:
+        """Discover services matching query criteria.
+
+        Queries the service discovery backend for services matching
+        the specified criteria (service_name, tags, health_filter).
+
+        Args:
+            query: Query parameters for filtering services.
+            correlation_id: Correlation ID for distributed tracing.
+
+        Returns:
+            ModelDiscoveryResult with matching services and query metadata.
+
+        Raises:
+            InfraConnectionError: If connection to backend fails.
+            InfraTimeoutError: If operation times out.
+            InfraUnavailableError: If circuit breaker is open.
+        """
+        ...
+
+    async def health_check(
+        self,
+        correlation_id: UUID | None = None,
+    ) -> ModelServiceDiscoveryHealthCheckResult:
+        """Check health of the service discovery backend.
+
+        Verifies connectivity and availability of the service
+        discovery backend.
+
+        Args:
+            correlation_id: Optional correlation ID for distributed tracing.
+                If not provided, implementations should generate one.
+
+        Returns:
+            ModelServiceDiscoveryHealthCheckResult: Health status including:
+                - healthy: bool indicating overall health
+                - backend_type: str identifying the backend
+                - latency_ms: float connection latency
+                - reason: str explaining the health status
+                - error_type: str | None exception type if failed
+                - details: ModelServiceDiscoveryHealthCheckDetails with typed diagnostics
+                - correlation_id: UUID | None for tracing
+
+        Example:
+            >>> from omnibase_infra.nodes.node_service_discovery_effect.models import (
+            ...     ModelServiceDiscoveryHealthCheckDetails,
+            ... )
+            >>> health = await handler.health_check()
+            >>> health
+            ModelServiceDiscoveryHealthCheckResult(
+                healthy=True,
+                backend_type="consul",
+                latency_ms=5.2,
+                reason="ok",
+                details=ModelServiceDiscoveryHealthCheckDetails(
+                    agent_address="localhost:8500",
+                    service_count=15,
+                ),
+            )
+        """
+        ...
+
+
+__all__ = ["ProtocolDiscoveryOperations"]

omnibase_infra/nodes/node_service_discovery_effect/registry/__init__.py

@@ -0,0 +1,13 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Registry for Service Discovery Effect Node.
+
+This module exports the registry for service discovery node dependencies:
+
+Classes:
+    RegistryInfraServiceDiscovery: Registry for service discovery dependencies.
+"""
+
+from .registry_infra_service_discovery import RegistryInfraServiceDiscovery
+
+__all__ = ["RegistryInfraServiceDiscovery"]

omnibase_infra/nodes/node_service_discovery_effect/registry/registry_infra_service_discovery.py

@@ -0,0 +1,222 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Registry for Service Discovery Node Dependencies.
+
+This module provides RegistryInfraServiceDiscovery for registering
+service discovery node dependencies with the ONEX container.
+
+Architecture:
+    RegistryInfraServiceDiscovery handles dependency injection setup
+    for the NodeServiceDiscoveryEffect node:
+    - Registers protocol implementations (Consul, K8s, Etcd handlers)
+    - Configures handler resolution based on environment/configuration
+    - Provides factory methods for handler instantiation
+
+Usage:
+    The registry is typically called during application bootstrap:
+
+    .. code-block:: python
+
+        from omnibase_core.models.container import ModelONEXContainer
+        from omnibase_infra.nodes.node_service_discovery_effect.registry import (
+            RegistryInfraServiceDiscovery,
+        )
+
+        container = ModelONEXContainer()
+        RegistryInfraServiceDiscovery.register(container)
+
+        # Or with specific handler configuration
+        RegistryInfraServiceDiscovery.register_with_handler(
+            container,
+            handler=consul_handler_instance,
+        )
+
+Related:
+    - NodeServiceDiscoveryEffect: Node that consumes registered dependencies
+    - ProtocolDiscoveryOperations: Protocol for handlers
+    - ModelONEXContainer: DI container for dependency resolution
+    - OMN-1131: Capability-oriented node architecture
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING
+
+from omnibase_infra.errors import ProtocolConfigurationError
+
+if TYPE_CHECKING:
+    from omnibase_core.models.container.model_onex_container import ModelONEXContainer
+    from omnibase_infra.nodes.node_service_discovery_effect.protocols import (
+        ProtocolDiscoveryOperations,
+    )
+
+logger = logging.getLogger(__name__)
+
+
+class RegistryInfraServiceDiscovery:
+    """Registry for service discovery node dependencies.
+
+    Provides static methods for registering service discovery
+    dependencies with the ONEX container. Supports both default
+    registration and explicit handler configuration.
+
+    API Pattern Note:
+        This registry uses ``container.service_registry.register_instance()``
+        for protocol-based type-safe DI resolution. This differs from
+        RegistryInfraRegistrationStorage which uses a module-level dict for
+        multi-handler routing by type string (e.g., "postgresql", "mock"),
+        as ServiceRegistry does not support dict-style indexed access.
+
+        The different patterns serve different purposes:
+        - Protocol-based registration: Single handler per protocol type
+        - Dict-based registration: Multiple handlers with type routing
+
+    Class Methods:
+        register: Register with default/environment-based configuration.
+        register_with_handler: Register with explicit handler instance.
+
+    Example:
+        .. code-block:: python
+
+            from omnibase_core.models.container import ModelONEXContainer
+
+            # Default registration (uses environment configuration)
+            container = ModelONEXContainer()
+            RegistryInfraServiceDiscovery.register(container)
+
+            # Explicit handler registration
+            consul_handler = HandlerServiceDiscoveryConsul(
+                container=container,
+                consul_host="localhost",
+            )
+            RegistryInfraServiceDiscovery.register_with_handler(
+                container,
+                handler=consul_handler,
+            )
+    """
+
+    @staticmethod
+    def register(container: ModelONEXContainer) -> None:
+        """Register service discovery dependencies with default configuration.
+
+        Registers service discovery dependencies using environment-based
+        or default configuration. The specific handler implementation
+        is determined by configuration at runtime.
+
+        Args:
+            container: ONEX dependency injection container.
+
+        Note:
+            This method registers a factory function that creates the
+            appropriate handler based on configuration. The actual
+            handler is not instantiated until resolution time.
+
+        Example:
+            >>> container = ModelONEXContainer()
+            >>> RegistryInfraServiceDiscovery.register(container)
+        """
+        if container.service_registry is None:
+            return
+
+        # NOTE: Factory registration (register_factory) is not implemented in
+        # omnibase_core v1.0. This method provides no-op registration for forward
+        # compatibility. Use register_with_handler() to explicitly provide a
+        # pre-configured handler instance.
+        logger.debug(
+            "Service discovery factory registration skipped - "
+            "factory registration not implemented in v1.0. "
+            "Use register_with_handler() to register an explicit handler instance."
+        )
+
+    @staticmethod
+    async def register_with_handler(
+        container: ModelONEXContainer,
+        handler: ProtocolDiscoveryOperations,
+    ) -> None:
+        """Register service discovery dependencies with explicit handler.
+
+        Registers the provided handler implementation directly.
+        Use this method when you have a pre-configured handler instance.
+
+        Args:
+            container: ONEX dependency injection container.
+            handler: Pre-configured handler implementation.
+
+        Raises:
+            TypeError: If handler does not implement ProtocolDiscoveryOperations.
+
+        Example:
+            >>> container = ModelONEXContainer()
+            >>> handler = HandlerServiceDiscoveryConsul(config)
+            >>> await RegistryInfraServiceDiscovery.register_with_handler(
+            ...     container,
+            ...     handler=handler,
+            ... )
+        """
+        # Import at runtime for isinstance check (protocol is @runtime_checkable)
+        from omnibase_core.enums import EnumInjectionScope
+        from omnibase_infra.nodes.node_service_discovery_effect.protocols import (
+            ProtocolDiscoveryOperations,
+        )
+
+        # NOTE: isinstance() is intentionally used here instead of duck typing for:
+        # 1. Fail-fast validation: Immediately reject invalid handlers at registration
+        #    time rather than discovering missing methods at runtime during operations
+        # 2. Type safety: The @runtime_checkable decorator enables structural subtyping
+        #    checks that verify all required Protocol methods exist
+        # 3. Clear error messages: TypeError with specific protocol name aids debugging
+        # Duck typing (hasattr checks) would defer validation to method call time,
+        # making it harder to diagnose misconfigured handlers.
+        # See: conftest.py "Protocol Compliance Strategy" for when to use each approach.
+        if not isinstance(handler, ProtocolDiscoveryOperations):
+            raise TypeError(
+                f"Handler must implement ProtocolDiscoveryOperations, "
+                f"got {type(handler).__name__}"
+            )
+
+        if container.service_registry is None:
+            return
+
+        await container.service_registry.register_instance(
+            interface=ProtocolDiscoveryOperations,  # type: ignore[type-abstract]
+            instance=handler,
+            scope=EnumInjectionScope.GLOBAL,
+        )
+
+    @staticmethod
+    def _create_handler_from_config(
+        _container: ModelONEXContainer,
+    ) -> ProtocolDiscoveryOperations:
+        """Create handler based on configuration.
+
+        Factory function that creates the appropriate handler
+        implementation based on environment/configuration.
+
+        Args:
+            container: ONEX container (for accessing configuration).
+
+        Returns:
+            Configured handler implementation.
+
+        Raises:
+            ProtocolConfigurationError: If no handler can be configured.
+
+        Note:
+            This is a placeholder implementation. Actual handler
+            creation depends on available backend implementations
+            (Consul, Kubernetes, Etcd adapters).
+        """
+        # Placeholder implementation
+        # In production, this would:
+        # 1. Read configuration (CONSUL_AGENT_URL, K8S_NAMESPACE, etc.)
+        # 2. Instantiate appropriate handler (ConsulHandler, K8sHandler, etc.)
+        # 3. Return the configured handler
+        raise ProtocolConfigurationError(
+            "No service discovery handler configured. "
+            "Use register_with_handler() to provide a handler, "
+            "or implement handler auto-configuration."
+        )
+
+
+__all__ = ["RegistryInfraServiceDiscovery"]

omnibase_infra/nodes/reducers/__init__.py

@@ -0,0 +1,30 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""ONEX Infrastructure Reducers Module.
+
+This module provides reducer nodes for aggregating and consolidating state
+from multiple sources in the ONEX 4-node architecture.
+
+Reducers are responsible for:
+- State aggregation from multiple sources
+- Event sourcing and state reconstruction
+- Multi-source data consolidation
+- Dual registration coordination (Consul + PostgreSQL)
+
+Available Reducers:
+- NodeRegistrationReducer: Declarative FSM-driven reducer (ONEX pattern).
+  Located at: nodes/node_registration_reducer/node.py
+  Uses contract.yaml for FSM state transitions.
+
+- RegistrationReducer: Pure function reducer implementation.
+  Uses ModelReducerOutput from omnibase_core.
+
+Related:
+    - OMN-1104: Refactor RegistrationReducer to be fully declarative
+"""
+
+from omnibase_infra.nodes.reducers.registration_reducer import RegistrationReducer
+
+__all__ = [
+    "RegistrationReducer",
+]

omnibase_infra/nodes/reducers/models/__init__.py

@@ -0,0 +1,37 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Models for Reducers.
+
+This module exports models used by infrastructure reducers (pure function pattern).
+
+Available Models:
+    - ModelRegistrationState: Immutable state for pure reducer pattern
+    - ModelRegistrationConfirmation: Confirmation event from Effect layer (Phase 2)
+    - ModelPayloadConsulRegister: Payload for Consul registration intents
+    - ModelPayloadLedgerAppend: Payload for audit ledger append intents
+    - ModelPayloadPostgresUpsertRegistration: Payload for PostgreSQL upsert intents
+"""
+
+from omnibase_infra.nodes.reducers.models.model_payload_consul_register import (
+    ModelPayloadConsulRegister,
+)
+from omnibase_infra.nodes.reducers.models.model_payload_ledger_append import (
+    ModelPayloadLedgerAppend,
+)
+from omnibase_infra.nodes.reducers.models.model_payload_postgres_upsert_registration import (
+    ModelPayloadPostgresUpsertRegistration,
+)
+from omnibase_infra.nodes.reducers.models.model_registration_confirmation import (
+    ModelRegistrationConfirmation,
+)
+from omnibase_infra.nodes.reducers.models.model_registration_state import (
+    ModelRegistrationState,
+)
+
+__all__ = [
+    "ModelPayloadConsulRegister",
+    "ModelPayloadLedgerAppend",
+    "ModelPayloadPostgresUpsertRegistration",
+    "ModelRegistrationConfirmation",
+    "ModelRegistrationState",
+]

omnibase_infra/nodes/reducers/models/model_payload_consul_register.py

@@ -0,0 +1,87 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Consul register payload model for registration reducer.
+
+This payload implements ProtocolIntentPayload for use with ModelIntent.
+It contains the same data as ModelConsulRegisterIntent but with an
+`intent_type` field instead of `kind` to satisfy the protocol.
+
+Related:
+    - ModelConsulRegisterIntent: Core intent model (uses `kind` discriminator)
+    - ProtocolIntentPayload: Protocol requiring `intent_type` property
+"""
+
+from __future__ import annotations
+
+from typing import Literal
+from uuid import UUID
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from omnibase_infra.models.registration.model_node_event_bus_config import (
+    ModelNodeEventBusConfig,
+)
+
+# NOTE: ModelIntentPayloadBase was removed in omnibase_core 0.6.2
+# Using pydantic.BaseModel directly as the base class
+
+
+class ModelPayloadConsulRegister(BaseModel):
+    """Payload for Consul service registration intents.
+
+    This payload follows the ONEX intent payload pattern for use with ModelIntent.
+
+    Attributes:
+        intent_type: Discriminator literal for intent routing. Always "consul.register".
+        correlation_id: Correlation ID for distributed tracing.
+        service_id: Unique service identifier for Consul registration.
+        service_name: Service name for Consul service catalog.
+        tags: Service tags for filtering and categorization.
+        health_check: Optional health check configuration.
+        event_bus_config: Resolved event bus topics for registry storage.
+            If None, node is not included in dynamic topic routing lookups.
+    """
+
+    model_config = ConfigDict(frozen=True, extra="forbid", from_attributes=True)
+
+    intent_type: Literal["consul.register"] = Field(
+        default="consul.register",
+        description="Discriminator literal for intent routing.",
+    )
+
+    correlation_id: UUID = Field(
+        ...,
+        description="Correlation ID for distributed tracing.",
+    )
+
+    service_id: str = Field(
+        ...,
+        min_length=1,
+        description="Unique service identifier for Consul registration.",
+    )
+
+    service_name: str = Field(
+        ...,
+        min_length=1,
+        description="Service name for Consul service catalog.",
+    )
+
+    tags: list[str] = Field(
+        ...,
+        description="Service tags for filtering and categorization.",
+    )
+
+    health_check: dict[str, str] | None = Field(
+        default=None,
+        description="Optional health check configuration (HTTP, Interval, Timeout).",
+    )
+
+    event_bus_config: ModelNodeEventBusConfig | None = Field(
+        default=None,
+        description="Resolved event bus topics for registry storage.",
+    )
+
+
+__all__ = [
+    "ModelPayloadConsulRegister",
+]