omnibase_infra 0.2.6__py3-none-any.whl

omnibase_infra/nodes/node_service_discovery_effect/models/enum_service_discovery_operation.py

@@ -0,0 +1,58 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Service Discovery Operation Enum.
+
+This module provides EnumServiceDiscoveryOperation, representing the type
+of service discovery operation performed (register, deregister).
+
+Architecture:
+    EnumServiceDiscoveryOperation defines the possible operations:
+    - REGISTER: Register a new service instance
+    - DEREGISTER: Remove a service instance from discovery
+
+    This enum is backend-agnostic and represents a normalized view
+    of operations across Consul, Kubernetes, Etcd, etc.
+
+Related:
+    - ModelRegistrationResult: Uses this enum for operation field
+    - OMN-1131: Capability-oriented node architecture
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+
+
+class EnumServiceDiscoveryOperation(str, Enum):
+    """Type of service discovery operation.
+
+    Represents the possible operations that can be performed
+    through service discovery backends.
+
+    Values:
+        REGISTER: Register a new service instance.
+        DEREGISTER: Remove a service instance from discovery.
+
+    Example:
+        >>> op = EnumServiceDiscoveryOperation.REGISTER
+        >>> op.value
+        'register'
+        >>> op.is_register
+        True
+    """
+
+    REGISTER = "register"
+    DEREGISTER = "deregister"
+
+    @property
+    def is_register(self) -> bool:
+        """Return True if this is a register operation."""
+        return self == EnumServiceDiscoveryOperation.REGISTER
+
+    @property
+    def is_deregister(self) -> bool:
+        """Return True if this is a deregister operation."""
+        return self == EnumServiceDiscoveryOperation.DEREGISTER
+
+
+__all__ = ["EnumServiceDiscoveryOperation"]

omnibase_infra/nodes/node_service_discovery_effect/models/model_discovery_query.py

@@ -0,0 +1,99 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Discovery Query Model for Service Discovery Operations.
+
+This module provides ModelDiscoveryQuery, representing query parameters
+for service discovery operations in the NodeServiceDiscoveryEffect node.
+
+Architecture:
+    ModelDiscoveryQuery captures query criteria for discovering services:
+    - service_name: Filter by service name (optional)
+    - tags: Filter by tags (optional, all must match)
+    - health_filter: Filter by health status (optional)
+
+    All fields are optional to support flexible querying:
+    - No filters: Return all registered services
+    - service_name only: Return all instances of a specific service
+    - tags only: Return services with matching tags
+    - health_filter: Return only healthy/unhealthy services
+    - Combinations: Apply multiple filters (AND logic)
+
+Related:
+    - ModelDiscoveryResult: Result model for discovery queries
+    - ModelServiceInfo: Individual service information
+    - ProtocolServiceDiscoveryHandler: Handler protocol for backends
+    - OMN-1131: Capability-oriented node architecture
+"""
+
+from __future__ import annotations
+
+from uuid import UUID, uuid4
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from .enum_health_status import EnumHealthStatus
+
+
+class ModelDiscoveryQuery(BaseModel):
+    """Query parameters for service discovery operations.
+
+    Defines criteria for discovering services from the service
+    discovery backend. All fields are optional to support flexible
+    querying patterns.
+
+    Immutability:
+        This model uses frozen=True to ensure queries are immutable
+        once created, enabling safe concurrent access and caching.
+
+    Query Logic:
+        - All specified fields use AND logic
+        - Empty/None fields are ignored
+        - Tags use AND logic (all specified tags must be present)
+        - health_filter=None returns services regardless of health
+
+    Attributes:
+        service_name: Service name to search for (optional).
+            When provided, only services with this name are returned.
+        tags: Tags to filter by (optional).
+            When provided, only services with ALL specified tags are returned.
+        health_filter: Health status filter (optional).
+            When provided, only services with matching health status are returned.
+        correlation_id: Correlation ID for distributed tracing.
+
+    Example:
+        >>> # Query all instances of user-service that are healthy
+        >>> query = ModelDiscoveryQuery(
+        ...     service_name="user-service",
+        ...     health_filter=EnumHealthStatus.HEALTHY,
+        ... )
+
+        >>> # Query all services with 'production' and 'api' tags
+        >>> query = ModelDiscoveryQuery(
+        ...     tags=("production", "api"),
+        ... )
+
+        >>> # Query all registered services
+        >>> query = ModelDiscoveryQuery()
+    """
+
+    model_config = ConfigDict(frozen=True, extra="forbid", from_attributes=True)
+
+    service_name: str | None = Field(
+        default=None,
+        description="Service name to search for (optional)",
+    )
+    tags: tuple[str, ...] | None = Field(
+        default=None,
+        description="Tags to filter by - all must match (optional)",
+    )
+    health_filter: EnumHealthStatus | None = Field(
+        default=None,
+        description="Health status filter (optional)",
+    )
+    correlation_id: UUID = Field(
+        default_factory=uuid4,
+        description="Correlation ID for distributed tracing",
+    )
+
+
+__all__ = ["ModelDiscoveryQuery"]

omnibase_infra/nodes/node_service_discovery_effect/models/model_discovery_result.py

@@ -0,0 +1,98 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Discovery Result Model for Service Discovery Operations.
+
+This module provides ModelDiscoveryResult, representing the result
+of service discovery queries from the NodeServiceDiscoveryEffect node.
+
+Architecture:
+    ModelDiscoveryResult contains the results of a service discovery
+    query along with metadata about the query execution:
+    - services: List of discovered service instances
+    - query_metadata: Information about query execution (timing, backend)
+
+    The result is backend-agnostic and represents a normalized view
+    of discovered services regardless of underlying backend.
+
+Related:
+    - ModelServiceInfo: Individual service information
+    - ModelDiscoveryQuery: Query that produced 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 .model_query_metadata import ModelQueryMetadata
+from .model_service_info import ModelServiceInfo
+
+
+class ModelDiscoveryResult(BaseModel):
+    """Result of service discovery query.
+
+    Contains the list of discovered services along with metadata
+    about the query execution. This is the primary output model
+    for discovery operations.
+
+    Immutability:
+        This model uses frozen=True to ensure results are immutable
+        once created, enabling safe concurrent access and caching.
+
+    Attributes:
+        services: List of discovered service instances.
+            Empty list indicates no services matched the query.
+        query_metadata: Metadata about query execution.
+        correlation_id: Correlation ID for distributed tracing.
+
+    Example:
+        >>> from datetime import UTC, datetime
+        >>> from uuid import uuid4
+        >>> result = ModelDiscoveryResult(
+        ...     services=(
+        ...         ModelServiceInfo(
+        ...             service_id=uuid4(),
+        ...             service_name="user-service",
+        ...             health_status=EnumHealthStatus.HEALTHY,
+        ...         ),
+        ...     ),
+        ...     query_metadata=ModelQueryMetadata(
+        ...         backend_type="consul",
+        ...         query_duration_ms=5.2,
+        ...         timestamp=datetime.now(UTC),
+        ...     ),
+        ... )
+        >>> len(result.services)
+        1
+    """
+
+    model_config = ConfigDict(frozen=True, extra="forbid", from_attributes=True)
+
+    services: tuple[ModelServiceInfo, ...] = Field(
+        default_factory=tuple,
+        description="List of discovered service instances",
+    )
+    query_metadata: ModelQueryMetadata | None = Field(
+        default=None,
+        description="Metadata about query execution",
+    )
+    correlation_id: UUID | None = Field(
+        default=None,
+        description="Correlation ID for distributed tracing",
+    )
+
+    @property
+    def service_count(self) -> int:
+        """Return the number of discovered services."""
+        return len(self.services)
+
+    @property
+    def is_empty(self) -> bool:
+        """Return True if no services were discovered."""
+        return len(self.services) == 0
+
+
+__all__ = ["ModelDiscoveryResult"]

omnibase_infra/nodes/node_service_discovery_effect/models/model_health_check_config.py

@@ -0,0 +1,121 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Health Check Configuration Model for Service Discovery.
+
+This module provides ModelHealthCheckConfig, representing health check
+configuration for service registration operations.
+
+Architecture:
+    ModelHealthCheckConfig captures health check parameters:
+    - endpoint: HTTP endpoint for health checks
+    - interval: Time between checks
+    - timeout: Maximum time to wait for response
+
+    This model is backend-agnostic and can be translated to
+    Consul, Kubernetes, Etcd-specific health check formats.
+
+Related:
+    - ModelServiceRegistration: Uses this model for health_check field
+    - ProtocolServiceDiscoveryHandler: Handler protocol for backends
+    - OMN-1131: Capability-oriented node architecture
+"""
+
+from __future__ import annotations
+
+import re
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+# Duration string pattern: supports formats like "10s", "1m", "500ms", "1h", "2d"
+# Format: <positive_number><unit> where unit is one of: ms, s, m, h, d
+DURATION_PATTERN = re.compile(r"^([1-9]\d*|0)(\.\d+)?(ms|s|m|h|d)$")
+
+
+class ModelHealthCheckConfig(BaseModel):
+    """Health check configuration for service registration.
+
+    Defines how the service discovery backend should verify
+    that a service instance is healthy and responding.
+
+    Immutability:
+        This model uses frozen=True to ensure configs are immutable
+        once created, enabling safe concurrent access.
+
+    Attributes:
+        endpoint: HTTP endpoint path for health checks (e.g., "/health").
+        interval: Time between health checks (e.g., "10s", "1m").
+        timeout: Maximum time to wait for response (e.g., "5s").
+        method: HTTP method for health check (default: "GET").
+        expected_status: Expected HTTP status code (default: 200).
+
+    Example:
+        >>> config = ModelHealthCheckConfig(
+        ...     endpoint="/health",
+        ...     interval="10s",
+        ...     timeout="5s",
+        ... )
+        >>> config.endpoint
+        '/health'
+    """
+
+    model_config = ConfigDict(frozen=True, extra="forbid", from_attributes=True)
+
+    endpoint: str = Field(
+        default="/health",
+        description="HTTP endpoint path for health checks",
+    )
+    interval: str = Field(
+        default="10s",
+        description="Time between health checks (e.g., '10s', '1m')",
+    )
+    timeout: str = Field(
+        default="5s",
+        description="Maximum time to wait for response (e.g., '5s')",
+    )
+    method: str = Field(
+        default="GET",
+        description="HTTP method for health check",
+    )
+    expected_status: int = Field(
+        default=200,
+        description="Expected HTTP status code for healthy response",
+        ge=100,
+        le=599,
+    )
+
+    @field_validator("interval", "timeout")
+    @classmethod
+    def validate_duration_format(cls, v: str) -> str:
+        """Validate that duration strings follow the expected format.
+
+        Supported formats:
+            - "10s" (seconds)
+            - "1m" (minutes)
+            - "500ms" (milliseconds)
+            - "1h" (hours)
+            - "2d" (days)
+            - Decimal values like "1.5s" are supported
+
+        Args:
+            v: The duration string to validate.
+
+        Returns:
+            The validated duration string.
+
+        Raises:
+            ValueError: If the duration string format is invalid.
+
+        Example:
+            >>> ModelHealthCheckConfig(interval="10s", timeout="5s")  # Valid
+            >>> ModelHealthCheckConfig(interval="invalid")  # Raises ValueError
+        """
+        if not DURATION_PATTERN.match(v):
+            raise ValueError(
+                f"Invalid duration format: '{v}'. "
+                f"Expected format: <number><unit> where unit is one of: ms, s, m, h, d. "
+                f"Examples: '10s', '1m', '500ms', '1.5h'"
+            )
+        return v
+
+
+__all__ = ["ModelHealthCheckConfig"]

omnibase_infra/nodes/node_service_discovery_effect/models/model_query_metadata.py

@@ -0,0 +1,63 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Query Metadata Model for Service Discovery Operations.
+
+This module provides ModelQueryMetadata, representing metadata about
+query execution in service discovery operations.
+
+Architecture:
+    ModelQueryMetadata contains information about how a query was executed,
+    useful for debugging and observability:
+    - backend_type: Type of backend that processed the query
+    - query_duration_ms: Time taken to execute the query
+    - timestamp: When the query was executed
+    - cached: Whether the result was served from cache
+
+Related:
+    - ModelDiscoveryResult: Primary result model that uses this metadata
+    - ProtocolServiceDiscoveryHandler: Handler protocol for backends
+    - OMN-1131: Capability-oriented node architecture
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class ModelQueryMetadata(BaseModel):
+    """Metadata about query execution.
+
+    Contains information about how the query was executed,
+    useful for debugging and observability.
+
+    Attributes:
+        backend_type: Type of backend that processed the query.
+        query_duration_ms: Time taken to execute the query in milliseconds.
+        timestamp: When the query was executed.
+        cached: Whether the result was served from cache.
+    """
+
+    model_config = ConfigDict(frozen=True, extra="forbid", from_attributes=True)
+
+    backend_type: str = Field(
+        ...,
+        description="Type of backend that processed the query (consul, k8s, etcd)",
+    )
+    query_duration_ms: float | None = Field(
+        default=None,
+        ge=0,
+        description="Time taken to execute the query in milliseconds",
+    )
+    timestamp: datetime | None = Field(
+        default=None,
+        description="When the query was executed",
+    )
+    cached: bool = Field(
+        default=False,
+        description="Whether the result was served from cache",
+    )
+
+
+__all__ = ["ModelQueryMetadata"]

omnibase_infra/nodes/node_service_discovery_effect/models/model_registration_result.py

@@ -0,0 +1,130 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Registration Result Model for Service Discovery Operations.
+
+This module provides ModelRegistrationResult, representing the result
+of service registration operations from the NodeServiceDiscoveryEffect node.
+
+Architecture:
+    ModelRegistrationResult captures the outcome of a service registration
+    or deregistration operation:
+    - success: Whether the operation completed successfully
+    - service_id: ID of the registered/deregistered service
+    - error: Error message if operation failed
+
+    This model is backend-agnostic and represents a normalized view
+    of registration results regardless of underlying backend.
+
+Related:
+    - ModelServiceRegistration: Input model for registration
+    - ProtocolServiceDiscoveryHandler: Handler protocol for backends
+    - NodeServiceDiscoveryEffect: Effect node that produces these results
+    - OMN-1131: Capability-oriented node architecture
+"""
+
+from __future__ import annotations
+
+from uuid import UUID, uuid4
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from .enum_service_discovery_operation import EnumServiceDiscoveryOperation
+
+
+class ModelRegistrationResult(BaseModel):
+    """Result of service registration or deregistration operation.
+
+    Contains the outcome of a registration operation along with
+    any error information if the operation failed.
+
+    Immutability:
+        This model uses frozen=True to ensure results are immutable
+        once created, enabling safe concurrent access.
+
+    Attributes:
+        success: Whether the operation completed successfully.
+        service_id: ID of the registered/deregistered service.
+        operation: Type of operation performed (register or deregister).
+        error: Error message if operation failed (None on success).
+        duration_ms: Time taken for the operation in milliseconds.
+        backend_type: Type of backend that processed the operation.
+        correlation_id: Correlation ID for distributed tracing.
+
+    Example:
+        >>> from uuid import uuid4
+        >>> # Successful registration
+        >>> result = ModelRegistrationResult(
+        ...     success=True,
+        ...     service_id=uuid4(),
+        ...     operation=EnumServiceDiscoveryOperation.REGISTER,
+        ...     duration_ms=45.2,
+        ...     backend_type="consul",
+        ... )
+        >>> result.success
+        True
+
+        >>> # Failed deregistration
+        >>> result = ModelRegistrationResult(
+        ...     success=False,
+        ...     service_id=uuid4(),
+        ...     operation=EnumServiceDiscoveryOperation.DEREGISTER,
+        ...     error="Connection timeout to Consul agent",
+        ...     duration_ms=5000.0,
+        ...     backend_type="consul",
+        ... )
+        >>> result.success
+        False
+    """
+
+    model_config = ConfigDict(frozen=True, extra="forbid", from_attributes=True)
+
+    success: bool = Field(
+        ...,
+        description="Whether the operation completed successfully",
+    )
+    service_id: UUID | None = Field(
+        default=None,
+        description="ID of the registered/deregistered service",
+    )
+    operation: EnumServiceDiscoveryOperation | None = Field(
+        default=None,
+        description="Type of operation performed (register or deregister)",
+    )
+    error: str | None = Field(
+        default=None,
+        description="Error message if operation failed (None on success)",
+    )
+    duration_ms: float = Field(
+        default=0.0,
+        description="Time taken for the operation in milliseconds",
+        ge=0.0,
+    )
+    backend_type: str | None = Field(
+        default=None,
+        description="Type of backend that processed the operation",
+    )
+    correlation_id: UUID = Field(
+        default_factory=uuid4,
+        description="Correlation ID for distributed tracing",
+    )
+
+    def __bool__(self) -> bool:
+        """Return True if the operation was successful.
+
+        Warning:
+            This overrides standard Pydantic behavior where `bool(model)`
+            always returns True. This model returns True only when the
+            operation was successful.
+
+        Returns:
+            True if success is True, False otherwise.
+
+        Example:
+            >>> result = ModelRegistrationResult(success=True)
+            >>> if result:  # Works intuitively
+            ...     print("Registration succeeded")
+        """
+        return self.success
+
+
+__all__ = ["ModelRegistrationResult"]

omnibase_infra/nodes/node_service_discovery_effect/models/model_service_discovery_health_check_details.py

@@ -0,0 +1,111 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Service Discovery Health Check Details Model.
+
+This module provides the Pydantic model for backend-specific diagnostic
+information in service discovery health check results, replacing untyped
+dict[str, object] with strongly-typed fields.
+
+Architecture:
+    ModelServiceDiscoveryHealthCheckDetails captures backend-specific diagnostics:
+    - Agent/server connectivity information
+    - Registered service counts
+    - Backend version information
+    - Custom backend-specific extensions
+
+    The model uses optional fields to accommodate different backends
+    that may provide varying levels of diagnostic information.
+
+Related:
+    - ModelServiceDiscoveryHealthCheckResult: Parent model that contains details
+    - ProtocolServiceDiscoveryHandler: Protocol for service discovery backends
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class ModelServiceDiscoveryHealthCheckDetails(BaseModel):
+    """Backend-specific diagnostic information for service discovery health checks.
+
+    This model captures diagnostic details from service discovery backends.
+    All fields are optional as different backends provide varying
+    levels of information.
+
+    Immutability:
+        This model uses frozen=True to ensure details are immutable
+        once created, enabling safe sharing and logging.
+
+    Attributes:
+        agent_address: Address of the service discovery agent (e.g., "localhost:8500").
+        server_version: Service discovery server version string.
+        service_count: Number of services registered with this backend.
+        datacenter: Datacenter or cluster name (for Consul).
+        leader: Current leader node address (for clustered backends).
+        cluster_size: Number of nodes in the cluster.
+        healthy_services: Count of healthy service instances.
+        unhealthy_services: Count of unhealthy service instances.
+
+    Example (Consul backend):
+        >>> details = ModelServiceDiscoveryHealthCheckDetails(
+        ...     agent_address="localhost:8500",
+        ...     server_version="1.15.4",
+        ...     service_count=15,
+        ...     datacenter="dc1",
+        ...     healthy_services=12,
+        ...     unhealthy_services=3,
+        ... )
+        >>> details.service_count
+        15
+
+    Example (minimal details from mock backend):
+        >>> details = ModelServiceDiscoveryHealthCheckDetails(
+        ...     server_version="mock-1.0.0",
+        ...     service_count=5,
+        ... )
+        >>> details.agent_address is None
+        True
+    """
+
+    model_config = ConfigDict(frozen=True, extra="forbid", from_attributes=True)
+
+    agent_address: str | None = Field(
+        default=None,
+        description="Address of the service discovery agent",
+    )
+    server_version: str | None = Field(
+        default=None,
+        description="Service discovery server version string",
+    )
+    service_count: int | None = Field(
+        default=None,
+        description="Number of services registered with this backend",
+        ge=0,
+    )
+    datacenter: str | None = Field(
+        default=None,
+        description="Datacenter or cluster name (for Consul)",
+    )
+    leader: str | None = Field(
+        default=None,
+        description="Current leader node address (for clustered backends)",
+    )
+    cluster_size: int | None = Field(
+        default=None,
+        description="Number of nodes in the cluster",
+        ge=0,
+    )
+    healthy_services: int | None = Field(
+        default=None,
+        description="Count of healthy service instances",
+        ge=0,
+    )
+    unhealthy_services: int | None = Field(
+        default=None,
+        description="Count of unhealthy service instances",
+        ge=0,
+    )
+
+
+__all__ = ["ModelServiceDiscoveryHealthCheckDetails"]