omnibase_infra 0.2.6__py3-none-any.whl

omnibase_infra/nodes/node_service_discovery_effect/models/model_service_discovery_health_check_result.py

@@ -0,0 +1,119 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Service Discovery Health Check Result Model.
+
+This module provides the Pydantic model for health check results from
+service discovery backends, using strongly-typed model instances
+for all fields including backend-specific details.
+
+Note:
+    This model is domain-specific to service discovery. For
+    general-purpose health checks, see
+    ``omnibase_infra.models.health.ModelHealthCheckResult``.
+
+Related:
+    - ModelServiceDiscoveryHealthCheckDetails: Backend-specific diagnostic details
+    - ProtocolServiceDiscoveryHandler: Protocol for service discovery backends
+"""
+
+from __future__ import annotations
+
+from uuid import UUID
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from .model_service_discovery_health_check_details import (
+    ModelServiceDiscoveryHealthCheckDetails,
+)
+
+
+class ModelServiceDiscoveryHealthCheckResult(BaseModel):
+    """Result of a service discovery backend health check.
+
+    This model represents the outcome of a health check operation on a
+    service discovery backend, providing structured diagnostics about
+    the backend's operational status.
+
+    Attributes:
+        healthy: Whether the service discovery backend is healthy and operational.
+            When True, the backend can accept operations normally.
+            When False, consult the reason field for diagnostics.
+        backend_type: Identifier for the service discovery backend (e.g., "consul", "mock").
+        latency_ms: Connection latency in milliseconds.
+        reason: Human-readable explanation of the health status.
+        error_type: Exception type name if health check failed.
+            Only populated when healthy is False.
+        details: Backend-specific diagnostic information as a typed model.
+            Contains agent_address, service_count, datacenter, etc.
+        correlation_id: Correlation ID for distributed tracing.
+
+    Example:
+        >>> from omnibase_infra.nodes.node_service_discovery_effect.models import (
+        ...     ModelServiceDiscoveryHealthCheckDetails,
+        ... )
+        >>> # Healthy service discovery backend
+        >>> result = ModelServiceDiscoveryHealthCheckResult(
+        ...     healthy=True,
+        ...     backend_type="consul",
+        ...     latency_ms=5.2,
+        ...     reason="ok",
+        ...     details=ModelServiceDiscoveryHealthCheckDetails(
+        ...         agent_address="localhost:8500",
+        ...         service_count=15,
+        ...     ),
+        ... )
+        >>> if result.healthy:
+        ...     print(f"{result.backend_type} is operational")
+        consul is operational
+
+        >>> # Failed health check
+        >>> result = ModelServiceDiscoveryHealthCheckResult(
+        ...     healthy=False,
+        ...     backend_type="consul",
+        ...     latency_ms=0.0,
+        ...     reason="Connection refused to agent",
+        ...     error_type="ConnectionRefusedError",
+        ... )
+        >>> if not result.healthy:
+        ...     print(f"Backend unhealthy: {result.reason}")
+        Backend unhealthy: Connection refused to agent
+    """
+
+    model_config = ConfigDict(
+        frozen=True,
+        extra="forbid",
+        from_attributes=True,
+    )
+
+    healthy: bool = Field(
+        description="Whether the service discovery backend is healthy and operational",
+    )
+    backend_type: str = Field(
+        description="Identifier for the service discovery backend (e.g., 'consul', 'mock')",
+    )
+    latency_ms: float = Field(
+        default=0.0,
+        ge=0.0,
+        description="Connection latency in milliseconds",
+    )
+    reason: str = Field(
+        default="ok",
+        description="Human-readable explanation of the health status",
+    )
+    error_type: str | None = Field(
+        default=None,
+        description="Exception type name if health check failed",
+    )
+    details: ModelServiceDiscoveryHealthCheckDetails = Field(
+        default_factory=ModelServiceDiscoveryHealthCheckDetails,
+        description="Backend-specific diagnostic information as a typed model",
+    )
+    correlation_id: UUID | None = Field(
+        default=None,
+        description="Correlation ID for distributed tracing",
+    )
+
+
+__all__: list[str] = [
+    "ModelServiceDiscoveryHealthCheckResult",
+]

omnibase_infra/nodes/node_service_discovery_effect/models/model_service_info.py

@@ -0,0 +1,106 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Service Info Model for Service Discovery Results.
+
+This module provides ModelServiceInfo, representing information about
+a discovered service instance from service discovery queries.
+
+Architecture:
+    ModelServiceInfo contains all relevant information about a service
+    instance returned from a discovery query:
+    - Service identity (service_id, service_name)
+    - Network location (address, port)
+    - Categorization (tags)
+    - Health status (health_status)
+    - Additional context (metadata)
+
+    This model is backend-agnostic and represents the normalized view
+    of service information across Consul, Kubernetes, Etcd, etc.
+
+Related:
+    - ModelDiscoveryResult: Contains list of ModelServiceInfo
+    - ModelDiscoveryQuery: Query that returns these results
+    - ProtocolServiceDiscoveryHandler: Handler protocol for backends
+    - OMN-1131: Capability-oriented node architecture
+"""
+
+from __future__ import annotations
+
+from uuid import UUID
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from .enum_health_status import EnumHealthStatus
+
+
+class ModelServiceInfo(BaseModel):
+    """Information about a discovered service instance.
+
+    Represents a single service instance returned from a service
+    discovery query. Contains normalized information regardless
+    of the underlying backend (Consul, K8s, Etcd).
+
+    Immutability:
+        This model uses frozen=True to ensure service info is immutable
+        once created, enabling safe concurrent access and caching.
+
+    Attributes:
+        service_id: Unique identifier for this service instance.
+        service_name: Logical name of the service.
+        address: Network address where the service is accessible.
+        port: Port number where the service listens.
+        tags: Tags associated with the service.
+        health_status: Current health status of the service.
+        metadata: Additional metadata associated with the service.
+
+    Example:
+        >>> from uuid import uuid4
+        >>> info = ModelServiceInfo(
+        ...     service_id=uuid4(),
+        ...     service_name="user-service",
+        ...     address="localhost",
+        ...     port=8080,
+        ...     tags=("api", "v2"),
+        ...     health_status=EnumHealthStatus.HEALTHY,
+        ...     metadata={"version": "2.1.0"},
+        ... )
+        >>> info.health_status
+        <EnumHealthStatus.HEALTHY: 'healthy'>
+    """
+
+    model_config = ConfigDict(frozen=True, extra="forbid", from_attributes=True)
+
+    service_id: UUID = Field(
+        ...,
+        description="Unique identifier for this service instance",
+    )
+    service_name: str = Field(
+        ...,
+        min_length=1,
+        description="Logical name of the service",
+    )
+    address: str | None = Field(
+        default=None,
+        description="Network address where the service is accessible",
+    )
+    port: int | None = Field(
+        default=None,
+        ge=1,
+        le=65535,
+        description="Port number where the service listens",
+    )
+    tags: tuple[str, ...] = Field(
+        default_factory=tuple,
+        description="Tags associated with the service",
+    )
+    health_status: EnumHealthStatus = Field(
+        default=EnumHealthStatus.UNKNOWN,
+        description="Current health status of the service",
+    )
+    metadata: dict[str, str] = Field(
+        default_factory=dict,
+        description="Additional metadata associated with the service",
+    )
+
+
+__all__ = ["ModelServiceInfo"]

omnibase_infra/nodes/node_service_discovery_effect/models/model_service_registration.py

@@ -0,0 +1,121 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Service Registration Model for Service Discovery Operations.
+
+This module provides ModelServiceRegistration, representing input for
+service registration operations in the NodeServiceDiscoveryEffect node.
+
+Architecture:
+    ModelServiceRegistration captures all information needed to register
+    a service with a service discovery backend:
+    - Service identity (service_id, service_name)
+    - Network location (address, port)
+    - Categorization (tags)
+    - Additional context (metadata)
+    - Liveness verification (health_check)
+
+    This model is backend-agnostic and can be used with Consul,
+    Kubernetes, Etcd, or other service discovery implementations.
+
+Related:
+    - NodeServiceDiscoveryEffect: Effect node that consumes this model
+    - ProtocolServiceDiscoveryHandler: Handler protocol for backends
+    - ModelRegistrationResult: Result model for registration operations
+    - OMN-1131: Capability-oriented node architecture
+"""
+
+from __future__ import annotations
+
+from uuid import UUID, uuid4
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from .model_health_check_config import ModelHealthCheckConfig
+
+
+class ModelServiceRegistration(BaseModel):
+    """Input model for service registration operations.
+
+    Contains all information needed to register a service with a
+    service discovery backend. The node delegates actual registration
+    to the configured ProtocolServiceDiscoveryHandler implementation.
+
+    Immutability:
+        This model uses frozen=True to ensure registrations are immutable
+        once created, enabling safe concurrent access.
+
+    Attributes:
+        service_id: Unique identifier for this service instance.
+            Auto-generated if not provided.
+        service_name: Logical name of the service (e.g., 'user-service').
+            Used for service discovery queries.
+        address: Network address where the service is accessible.
+            Can be hostname or IP address.
+        port: Port number where the service listens.
+        tags: Tags for service categorization and filtering.
+            Used in discovery queries to find specific service subsets.
+        metadata: Additional key-value metadata for the service.
+            Backend-specific attributes can be passed here.
+        health_check: Optional health check configuration model.
+            Defines how the backend should verify service health.
+        correlation_id: Correlation ID for distributed tracing.
+
+    Example:
+        >>> from uuid import uuid4
+        >>> registration = ModelServiceRegistration(
+        ...     service_id=uuid4(),
+        ...     service_name="user-service",
+        ...     address="localhost",
+        ...     port=8080,
+        ...     tags=("api", "v2", "production"),
+        ...     metadata={"version": "2.1.0", "region": "us-east-1"},
+        ...     health_check=ModelHealthCheckConfig(
+        ...         endpoint="/health",
+        ...         interval="10s",
+        ...         timeout="5s",
+        ...     ),
+        ... )
+        >>> registration.service_name
+        'user-service'
+    """
+
+    model_config = ConfigDict(frozen=True, extra="forbid", from_attributes=True)
+
+    service_id: UUID = Field(
+        default_factory=uuid4,
+        description="Unique identifier for this service instance",
+    )
+    service_name: str = Field(
+        ...,
+        min_length=1,
+        description="Logical name of the service (e.g., 'user-service')",
+    )
+    address: str | None = Field(
+        default=None,
+        description="Network address where the service is accessible",
+    )
+    port: int | None = Field(
+        default=None,
+        ge=1,
+        le=65535,
+        description="Port number where the service listens",
+    )
+    tags: tuple[str, ...] = Field(
+        default_factory=tuple,
+        description="Tags for service categorization and filtering",
+    )
+    metadata: dict[str, str] = Field(
+        default_factory=dict,
+        description="Additional key-value metadata for the service",
+    )
+    health_check: ModelHealthCheckConfig | None = Field(
+        default=None,
+        description="Health check configuration (interval, timeout, endpoint)",
+    )
+    correlation_id: UUID = Field(
+        default_factory=uuid4,
+        description="Correlation ID for distributed tracing",
+    )
+
+
+__all__ = ["ModelServiceRegistration"]

omnibase_infra/nodes/node_service_discovery_effect/node.py

@@ -0,0 +1,111 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Service Discovery Effect Node - Capability-Oriented Effect Node.
+
+This node provides capability-oriented service discovery operations following
+the ONEX principle: "I'm interested in what you do, not what you are".
+
+Capability-Oriented Design:
+    Named by capability (service.discovery) not vendor (consul/k8s/etcd).
+    The node provides unified operations for:
+    - register_service: Register a service instance
+    - deregister_service: Remove a service registration
+    - discover_services: Query for service instances
+    - health_check: Verify backend connectivity
+
+Pluggable Backend Support:
+    This node delegates actual service discovery operations to implementations
+    of ProtocolDiscoveryOperations. Supported backends include:
+    - Consul: HashiCorp Consul service discovery
+    - Kubernetes: K8s native service discovery
+    - Etcd: CoreOS etcd service discovery
+
+Declarative Pattern:
+    This node follows ONEX declarative conventions:
+    - Extends NodeEffect from omnibase_core
+    - All behavior defined in contract.yaml
+    - No custom routing logic in Python code
+    - Handler wired externally via container injection
+
+Usage:
+    .. code-block:: python
+
+        from omnibase_core.models.container import ModelONEXContainer
+        from omnibase_infra.nodes.node_service_discovery_effect import (
+            NodeServiceDiscoveryEffect,
+        )
+
+        # Create container with handler dependency
+        container = ModelONEXContainer()
+        container.register(
+            ProtocolDiscoveryOperations,
+            consul_handler_instance,
+        )
+
+        # Create node
+        node = NodeServiceDiscoveryEffect(container)
+
+Related:
+    - contract.yaml: ONEX contract with capabilities and I/O definitions
+    - ProtocolDiscoveryOperations: Backend handler protocol
+    - ModelServiceRegistration: Input model for registration
+    - ModelDiscoveryResult: Output model for discovery queries
+    - OMN-1131: Capability-oriented node architecture
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from omnibase_core.nodes.node_effect import NodeEffect
+
+if TYPE_CHECKING:
+    from omnibase_core.models.container.model_onex_container import ModelONEXContainer
+
+
+class NodeServiceDiscoveryEffect(NodeEffect):
+    """Effect node for service discovery operations.
+
+    Capability: service.discovery
+    Supports pluggable handlers: Consul, Kubernetes, Etcd
+
+    This node provides capability-oriented service discovery following
+    the ONEX principle of naming by capability rather than vendor.
+
+    All behavior is declarative and defined in contract.yaml:
+    - io_operations: register_service, deregister_service, discover_services
+    - capabilities: service.discovery, service.registration, etc.
+    - dependencies: ProtocolDiscoveryOperations
+
+    Attributes:
+        container: ONEX dependency injection container providing access
+            to the configured ProtocolDiscoveryOperations implementation.
+
+    Example:
+        .. code-block:: python
+
+            from omnibase_core.models.container import ModelONEXContainer
+
+            container = ModelONEXContainer()
+            # Register handler implementation (e.g., Consul, K8s, Etcd)
+            container.register(handler_protocol, handler_impl)
+
+            node = NodeServiceDiscoveryEffect(container)
+
+    Note:
+        This is a declarative node - all behavior is driven by contract.yaml.
+        The handler implementation is resolved from the container at runtime.
+    """
+
+    def __init__(self, container: ModelONEXContainer) -> None:
+        """Initialize the service discovery effect node.
+
+        Args:
+            container: ONEX dependency injection container providing
+                access to infrastructure dependencies including the
+                configured ProtocolDiscoveryOperations implementation.
+        """
+        super().__init__(container)
+
+
+__all__ = ["NodeServiceDiscoveryEffect"]

omnibase_infra/nodes/node_service_discovery_effect/protocols/__init__.py

@@ -0,0 +1,14 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Protocols for Service Discovery Effect Node.
+
+This module exports protocols for the service discovery effect node:
+
+Protocols:
+    ProtocolDiscoveryOperations: Protocol for pluggable service discovery
+        backends (Consul, Kubernetes, Etcd).
+"""
+
+from .protocol_discovery_operations import ProtocolDiscoveryOperations
+
+__all__ = ["ProtocolDiscoveryOperations"]