omnibase_infra 0.2.1__py3-none-any.whl

omnibase_infra/nodes/node_registry_effect/registry/registry_infra_registry_effect.py

@@ -0,0 +1,196 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Registry for NodeRegistryEffect infrastructure dependencies.
+
+This registry provides factory methods for creating NodeRegistryEffect
+instances with their required dependencies resolved from the container.
+
+Following ONEX naming conventions:
+    - File: registry_infra_<node_name>.py
+    - Class: RegistryInfra<NodeName>
+
+The registry serves as the entry point for creating properly configured
+effect node instances, documenting required protocols, and providing
+node metadata for introspection.
+
+Related:
+    - contract.yaml: Node contract defining operations and dependencies
+    - node.py: Declarative node implementation
+    - handlers/: Backend-specific operation handlers
+
+.. versionadded:: 0.5.0
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from omnibase_core.models.container.model_onex_container import ModelONEXContainer
+    from omnibase_infra.nodes.node_registry_effect.node import NodeRegistryEffect
+
+
+class RegistryInfraRegistryEffect:
+    """Infrastructure registry for NodeRegistryEffect.
+
+    Provides dependency resolution and factory methods for creating
+    properly configured NodeRegistryEffect instances.
+
+    This registry follows the ONEX infrastructure registry pattern:
+        - Factory method for node creation with container injection
+        - Protocol requirements documentation for container validation
+        - Node type classification for routing decisions
+        - Capability listing for service discovery
+
+    Example:
+        >>> from omnibase_core.models.container import ModelONEXContainer
+        >>> from omnibase_infra.nodes.node_registry_effect.registry import (
+        ...     RegistryInfraRegistryEffect,
+        ... )
+        >>>
+        >>> # Create container with required protocols registered
+        >>> container = ModelONEXContainer()
+        >>> # ... register protocols ...
+        >>>
+        >>> # Create node instance via registry
+        >>> effect = RegistryInfraRegistryEffect.create(container)
+
+    .. versionadded:: 0.5.0
+    """
+
+    @staticmethod
+    def create(container: ModelONEXContainer) -> NodeRegistryEffect:
+        """Create a NodeRegistryEffect instance with resolved dependencies.
+
+        Factory method that creates a fully configured NodeRegistryEffect
+        using the provided ONEX container for dependency injection.
+
+        Args:
+            container: ONEX dependency injection container. Must have the
+                following protocols registered:
+                - ProtocolConsulClient: Consul service discovery operations
+                - ProtocolPostgresAdapter: PostgreSQL registration persistence
+                - ProtocolEffectIdempotencyStore: Idempotency tracking
+                - ProtocolCircuitBreaker: Backend circuit breaker protection
+
+        Returns:
+            Configured NodeRegistryEffect instance ready for operation.
+
+        Raises:
+            OnexError: If required protocols are not registered in container.
+
+        Example:
+            >>> container = ModelONEXContainer()
+            >>> container.register(ProtocolConsulClient, consul_client)
+            >>> container.register(ProtocolPostgresAdapter, postgres_adapter)
+            >>> effect = RegistryInfraRegistryEffect.create(container)
+
+        .. versionadded:: 0.5.0
+        """
+        from omnibase_infra.nodes.node_registry_effect.node import NodeRegistryEffect
+
+        return NodeRegistryEffect(container)
+
+    @staticmethod
+    def get_required_protocols() -> list[str]:
+        """Get list of protocols required by this node.
+
+        Returns the protocol class names that must be registered in the
+        container before creating a NodeRegistryEffect instance.
+
+        Returns:
+            List of protocol class names required for node operation.
+
+        Example:
+            >>> protocols = RegistryInfraRegistryEffect.get_required_protocols()
+            >>> for proto in protocols:
+            ...     if not container.has(proto):
+            ...         raise ConfigurationError(f"Missing: {proto}")
+
+        .. versionadded:: 0.5.0
+        """
+        return [
+            "ProtocolConsulClient",
+            "ProtocolPostgresAdapter",
+            "ProtocolEffectIdempotencyStore",
+            "ProtocolCircuitBreaker",
+        ]
+
+    @staticmethod
+    def get_node_type() -> str:
+        """Get the node type classification.
+
+        Returns the ONEX node archetype for this node, used for
+        routing decisions and execution context selection.
+
+        Returns:
+            Node type string ("EFFECT").
+
+        Note:
+            EFFECT nodes perform external I/O operations and should
+            be treated as side-effecting by the runtime.
+
+        .. versionadded:: 0.5.0
+        """
+        return "EFFECT"
+
+    @staticmethod
+    def get_node_name() -> str:
+        """Get the canonical node name.
+
+        Returns:
+            The node name as defined in contract.yaml.
+
+        .. versionadded:: 0.5.0
+        """
+        return "node_registry_effect"
+
+    @staticmethod
+    def get_capabilities() -> list[str]:
+        """Get list of capabilities provided by this node.
+
+        Returns capability identifiers that can be used for service
+        discovery and feature detection.
+
+        Returns:
+            List of capability identifiers.
+
+        .. versionadded:: 0.5.0
+        """
+        return [
+            "dual_backend_registration",
+            "partial_failure_handling",
+            "targeted_retry",
+            "idempotent_operations",
+            "circuit_breaker_protection",
+            "parallel_execution",
+        ]
+
+    @staticmethod
+    def get_supported_operations() -> list[str]:
+        """Get list of operations supported by this node.
+
+        Returns:
+            List of operation identifiers as defined in contract.yaml.
+
+        .. versionadded:: 0.5.0
+        """
+        return [
+            "register_node",
+            "deregister_node",
+            "retry_partial_failure",
+        ]
+
+    @staticmethod
+    def get_backends() -> list[str]:
+        """Get list of backend types this node interacts with.
+
+        Returns:
+            List of backend identifiers.
+
+        .. versionadded:: 0.5.0
+        """
+        return ["consul", "postgres"]
+
+
+__all__ = ["RegistryInfraRegistryEffect"]

omnibase_infra/nodes/node_service_discovery_effect/__init__.py

@@ -0,0 +1,111 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Service Discovery Effect Node - Capability-Oriented Service Discovery.
+
+This module provides NodeServiceDiscoveryEffect, a capability-oriented effect
+node for service discovery operations with pluggable backend support.
+
+Capability-Oriented Design:
+    Named by capability (service.discovery) not vendor (consul/k8s/etcd).
+    Following the ONEX principle: "I'm interested in what you do, not what you are"
+
+Supported Operations:
+    - 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
+
+Pluggable Backends:
+    - Consul: HashiCorp Consul service discovery
+    - Kubernetes: K8s native service discovery
+    - Etcd: CoreOS etcd service discovery
+
+Node:
+    NodeServiceDiscoveryEffect: Declarative effect node for service discovery.
+
+Models:
+    ModelServiceRegistration: Input model for registration operations.
+    ModelServiceInfo: Information about a discovered service.
+    ModelDiscoveryQuery: Query parameters for discovery operations.
+    ModelDiscoveryResult: Result of discovery queries.
+    ModelRegistrationResult: Result of registration/deregistration.
+
+Enums:
+    EnumHealthStatus: Health status values (HEALTHY, UNHEALTHY, UNKNOWN).
+
+Protocol:
+    ProtocolDiscoveryOperations: Protocol for pluggable backends.
+
+Registry:
+    RegistryInfraServiceDiscovery: DI registry for node dependencies.
+
+Example:
+    .. code-block:: python
+
+        from omnibase_core.models.container import ModelONEXContainer
+        from omnibase_infra.nodes.node_service_discovery_effect import (
+            NodeServiceDiscoveryEffect,
+            ModelServiceRegistration,
+            RegistryInfraServiceDiscovery,
+        )
+
+        # Setup container with handler
+        container = ModelONEXContainer()
+        RegistryInfraServiceDiscovery.register_with_handler(
+            container,
+            handler=consul_handler,
+        )
+
+        # Create node
+        node = NodeServiceDiscoveryEffect(container)
+
+        # Register a service
+        registration = ModelServiceRegistration(
+            service_name="user-service",
+            address="localhost",
+            port=8080,
+            tags=("api", "v2"),
+        )
+
+Related:
+    - contract.yaml: ONEX contract with capabilities and I/O definitions
+    - OMN-1131: Capability-oriented node architecture
+
+.. versionadded:: 0.6.0
+"""
+
+from .models import (
+    EnumHealthStatus,
+    ModelDiscoveryQuery,
+    ModelDiscoveryResult,
+    ModelQueryMetadata,
+    ModelRegistrationResult,
+    ModelServiceInfo,
+    ModelServiceRegistration,
+)
+from .node import (
+    NodeServiceDiscoveryEffect,
+)
+from .protocols import (
+    ProtocolDiscoveryOperations,
+)
+from .registry import (
+    RegistryInfraServiceDiscovery,
+)
+
+__all__ = [
+    # Node
+    "NodeServiceDiscoveryEffect",
+    # Models
+    "EnumHealthStatus",
+    "ModelDiscoveryQuery",
+    "ModelDiscoveryResult",
+    "ModelQueryMetadata",
+    "ModelRegistrationResult",
+    "ModelServiceInfo",
+    "ModelServiceRegistration",
+    # Protocol
+    "ProtocolDiscoveryOperations",
+    # Registry
+    "RegistryInfraServiceDiscovery",
+]

omnibase_infra/nodes/node_service_discovery_effect/contract.yaml

@@ -0,0 +1,246 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+#
+# ONEX Node Contract - Service Discovery Effect Node
+#
+# Capability-Oriented Design: "I'm interested in what you do, not what you are"
+# This node is named by capability (service.discovery) not vendor (consul/k8s/etcd).
+# Supports pluggable backends through ProtocolDiscoveryOperations.
+#
+contract_version:
+  major: 1
+  minor: 0
+  patch: 0
+node_version: "1.0.0"
+name: "node_service_discovery_effect"
+node_type: "EFFECT_GENERIC"
+description: >
+  Effect node for service discovery operations. Provides capability-oriented service registration, deregistration, and discovery with pluggable backend support (Consul, Kubernetes, Etcd). Named by capability, not vendor.
+
+# Strongly typed I/O models
+input_model:
+  name: "ModelServiceRegistration"
+  module: "omnibase_infra.nodes.node_service_discovery_effect.models"
+  description: "Input model for service registration operations."
+output_model:
+  name: "ModelDiscoveryResult"
+  module: "omnibase_infra.nodes.node_service_discovery_effect.models"
+  description: "Output model for service discovery query results."
+# Capability declaration - what this node CAN DO
+capabilities:
+  - name: "service.discovery"
+    description: >
+      Discover services by name, tags, or health status. Provides a unified interface for querying service locations across different backends.
+
+  - name: "service.registration"
+    description: >
+      Register services with service discovery backends. Supports health check configuration and metadata attachment.
+
+  - name: "service.deregistration"
+    description: >
+      Deregister services from service discovery backends. Handles cleanup and graceful removal.
+
+  - name: "service.health_check"
+    description: >
+      Health check operations for service discovery backend connectivity and availability verification.
+
+# IO operations (EFFECT node specific)
+io_operations:
+  - operation: "register_service"
+    description: "Register a service with the configured backend"
+    input_fields:
+      - service_id
+      - service_name
+      - address
+      - port
+      - tags
+      - metadata
+      - health_check
+    output_fields:
+      - success
+      - service_id
+      - error
+  - operation: "deregister_service"
+    description: "Deregister a service from the configured backend"
+    input_fields:
+      - service_id
+    output_fields:
+      - success
+      - error
+  - operation: "discover_services"
+    description: "Discover services matching query criteria"
+    input_fields:
+      - service_name
+      - tags
+      - health_filter
+    output_fields:
+      - services
+      - query_metadata
+  - operation: "health_check"
+    description: "Check health of the service discovery backend"
+    input_fields: []
+    output_fields:
+      - status
+      - backend_type
+      - details
+# Dependencies (protocols this node requires)
+dependencies:
+  - name: "service_discovery_handler"
+    type: "protocol"
+    class_name: "ProtocolDiscoveryOperations"
+    module: "omnibase_infra.nodes.node_service_discovery_effect.protocols"
+    description: >
+      Protocol for pluggable service discovery backends. Implementations include Consul, Kubernetes, and Etcd handlers.
+
+# Error handling configuration
+error_handling:
+  retry_policy:
+    max_retries: 3
+    initial_delay_ms: 100
+    max_delay_ms: 5000
+    exponential_base: 2
+    retry_on:
+      - "InfraConnectionError"
+      - "InfraTimeoutError"
+  circuit_breaker:
+    enabled: true
+    failure_threshold: 5
+    reset_timeout_ms: 60000
+  error_types:
+    - name: "ServiceRegistrationError"
+      description: "Error during service registration"
+      recoverable: true
+      retry_strategy: "exponential_backoff"
+    - name: "ServiceDiscoveryError"
+      description: "Error during service discovery query"
+      recoverable: true
+      retry_strategy: "exponential_backoff"
+    - name: "BackendUnavailableError"
+      description: "Service discovery backend is unavailable"
+      recoverable: true
+      retry_strategy: "exponential_backoff"
+# Health check configuration
+health_check:
+  enabled: true
+  endpoint: "/health"
+  interval_seconds: 30
+# Model definitions for contract documentation
+definitions:
+  ModelServiceRegistration:
+    type: object
+    description: "Input model for service registration"
+    properties:
+      service_id:
+        type: string
+        description: "Unique identifier for the service instance"
+      service_name:
+        type: string
+        description: "Logical name of the service (e.g., 'user-service')"
+      address:
+        type: string
+        description: "Network address where service is accessible"
+      port:
+        type: integer
+        description: "Port number for the service"
+      tags:
+        type: array
+        items:
+          type: string
+        description: "Tags for service categorization and filtering"
+      metadata:
+        type: object
+        description: "Additional key-value metadata for the service"
+      health_check:
+        type: object
+        description: "Health check configuration"
+    required:
+      - service_id
+      - service_name
+  ModelServiceInfo:
+    type: object
+    description: "Information about a discovered service"
+    properties:
+      service_id:
+        type: string
+        description: "Unique identifier for the service instance"
+      service_name:
+        type: string
+        description: "Logical name of the service"
+      address:
+        type: string
+        description: "Network address of the service"
+      port:
+        type: integer
+        description: "Port number of the service"
+      tags:
+        type: array
+        items:
+          type: string
+        description: "Tags associated with the service"
+      health_status:
+        type: string
+        description: "Current health status (healthy, unhealthy, unknown)"
+      metadata:
+        type: object
+        description: "Service metadata"
+    required:
+      - service_id
+      - service_name
+      - health_status
+  ModelDiscoveryQuery:
+    type: object
+    description: "Query parameters for service discovery"
+    properties:
+      service_name:
+        type: string
+        description: "Service name to search for (optional)"
+      tags:
+        type: array
+        items:
+          type: string
+        description: "Tags to filter by (optional)"
+      health_filter:
+        type: string
+        description: "Health status filter (all, healthy, unhealthy)"
+  ModelDiscoveryResult:
+    type: object
+    description: "Result of service discovery query"
+    properties:
+      services:
+        type: array
+        items:
+          $ref: "#/definitions/ModelServiceInfo"
+        description: "List of discovered services"
+      query_metadata:
+        type: object
+        description: "Metadata about the query execution"
+    required:
+      - services
+  ModelRegistrationResult:
+    type: object
+    description: "Result of service registration operation"
+    properties:
+      success:
+        type: boolean
+        description: "Whether registration succeeded"
+      service_id:
+        type: string
+        description: "ID of the registered service"
+      error:
+        type: string
+        description: "Error message if registration failed"
+    required:
+      - success
+# Metadata
+metadata:
+  author: "OmniNode Team"
+  license: "MIT"
+  created: "2025-01-06"
+  tags:
+    - effect
+    - service-discovery
+    - capability-oriented
+    - consul
+    - kubernetes
+    - etcd
+    - pluggable

omnibase_infra/nodes/node_service_discovery_effect/models/__init__.py

@@ -0,0 +1,67 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Models for Service Discovery Effect Node.
+
+This module exports models for the service discovery effect node:
+
+Enums:
+    EnumHealthStatus: Health status values (HEALTHY, UNHEALTHY, UNKNOWN).
+    EnumServiceDiscoveryOperation: Operation types (REGISTER, DEREGISTER).
+
+Models:
+    ModelHealthCheckConfig: Health check configuration for registration.
+    ModelServiceRegistration: Input model for service registration.
+    ModelServiceInfo: Information about a discovered service.
+    ModelDiscoveryQuery: Query parameters for service discovery.
+    ModelDiscoveryResult: Result of service discovery query.
+    ModelQueryMetadata: Metadata about query execution.
+    ModelRegistrationResult: Result of registration/deregistration.
+"""
+
+from .enum_health_status import (
+    EnumHealthStatus,
+)
+from .enum_service_discovery_operation import (
+    EnumServiceDiscoveryOperation,
+)
+from .model_discovery_query import (
+    ModelDiscoveryQuery,
+)
+from .model_discovery_result import (
+    ModelDiscoveryResult,
+)
+from .model_health_check_config import (
+    ModelHealthCheckConfig,
+)
+from .model_query_metadata import (
+    ModelQueryMetadata,
+)
+from .model_registration_result import (
+    ModelRegistrationResult,
+)
+from .model_service_discovery_health_check_details import (
+    ModelServiceDiscoveryHealthCheckDetails,
+)
+from .model_service_discovery_health_check_result import (
+    ModelServiceDiscoveryHealthCheckResult,
+)
+from .model_service_info import (
+    ModelServiceInfo,
+)
+from .model_service_registration import (
+    ModelServiceRegistration,
+)
+
+__all__ = [
+    "EnumHealthStatus",
+    "EnumServiceDiscoveryOperation",
+    "ModelDiscoveryQuery",
+    "ModelDiscoveryResult",
+    "ModelHealthCheckConfig",
+    "ModelQueryMetadata",
+    "ModelRegistrationResult",
+    "ModelServiceDiscoveryHealthCheckDetails",
+    "ModelServiceDiscoveryHealthCheckResult",
+    "ModelServiceInfo",
+    "ModelServiceRegistration",
+]

omnibase_infra/nodes/node_service_discovery_effect/models/enum_health_status.py

@@ -0,0 +1,72 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Health Status Enum for Service Discovery.
+
+This module provides EnumHealthStatus, representing the health status
+of a service instance in service discovery operations.
+
+Architecture:
+    EnumHealthStatus defines the possible health states for services:
+    - HEALTHY: Service is responding and passing health checks
+    - UNHEALTHY: Service is failing health checks
+    - UNKNOWN: Health status cannot be determined
+
+    This enum is backend-agnostic and represents a normalized view
+    of health status across Consul, Kubernetes, Etcd, etc.
+
+Related:
+    - ModelServiceInfo: Uses this enum for health_status field
+    - ModelDiscoveryQuery: Uses this enum for health_filter field
+    - OMN-1131: Capability-oriented node architecture
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+
+
+class EnumHealthStatus(str, Enum):
+    """Health status of a service instance.
+
+    Represents the possible health states for services discovered
+    through service discovery backends.
+
+    Values:
+        HEALTHY: Service is responding and passing health checks.
+        UNHEALTHY: Service is failing health checks.
+        UNKNOWN: Health status cannot be determined.
+
+    Backend Mappings:
+        - Consul: passing -> HEALTHY, critical -> UNHEALTHY, warning -> UNHEALTHY
+        - Kubernetes: Ready=True -> HEALTHY, Ready=False -> UNHEALTHY
+        - Etcd: Based on TTL and key presence
+
+    Example:
+        >>> status = EnumHealthStatus.HEALTHY
+        >>> status.value
+        'healthy'
+        >>> status.is_healthy
+        True
+    """
+
+    HEALTHY = "healthy"
+    UNHEALTHY = "unhealthy"
+    UNKNOWN = "unknown"
+
+    @property
+    def is_healthy(self) -> bool:
+        """Return True if the status indicates a healthy service."""
+        return self == EnumHealthStatus.HEALTHY
+
+    @property
+    def is_unhealthy(self) -> bool:
+        """Return True if the status indicates an unhealthy service."""
+        return self == EnumHealthStatus.UNHEALTHY
+
+    @property
+    def is_unknown(self) -> bool:
+        """Return True if the health status is unknown."""
+        return self == EnumHealthStatus.UNKNOWN
+
+
+__all__ = ["EnumHealthStatus"]