omnibase_infra 0.2.1__py3-none-any.whl

omnibase_infra/handlers/service_discovery/handler_service_discovery_mock.py

@@ -0,0 +1,258 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Mock Service Discovery Handler.
+
+This module provides an in-memory mock implementation of the service discovery
+handler protocol for testing purposes.
+
+Thread Safety:
+    This handler uses asyncio.Lock for coroutine-safe access to the
+    in-memory service store.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import time
+from datetime import UTC, datetime
+from uuid import UUID, uuid4
+
+from omnibase_infra.handlers.service_discovery.models import (
+    ModelDiscoveryResult,
+    ModelHandlerRegistrationResult,
+    ModelServiceInfo,
+)
+from omnibase_infra.nodes.node_service_discovery_effect.models import (
+    ModelDiscoveryQuery,
+    ModelServiceDiscoveryHealthCheckDetails,
+    ModelServiceDiscoveryHealthCheckResult,
+)
+from omnibase_infra.nodes.node_service_discovery_effect.models.enum_service_discovery_operation import (
+    EnumServiceDiscoveryOperation,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class HandlerServiceDiscoveryMock:
+    """In-memory mock for testing service discovery.
+
+    Provides a simple in-memory implementation of the service discovery
+    protocol for unit and integration testing.
+
+    Thread Safety:
+        This handler is coroutine-safe. All operations on the internal
+        service store are protected by asyncio.Lock.
+
+    Attributes:
+        handler_type: Returns "mock" identifier.
+
+    Example:
+        >>> handler = HandlerServiceDiscoveryMock()
+        >>> result = await handler.register_service(service_info)
+        >>> assert result.success
+    """
+
+    def __init__(self) -> None:
+        """Initialize HandlerServiceDiscoveryMock with empty service store."""
+        self._services: dict[UUID, ModelServiceInfo] = {}
+        self._lock = asyncio.Lock()
+
+        logger.debug("HandlerServiceDiscoveryMock initialized")
+
+    @property
+    def handler_type(self) -> str:
+        """Return the handler type identifier.
+
+        Returns:
+            "mock" identifier string.
+        """
+        return "mock"
+
+    async def register_service(
+        self,
+        service_info: ModelServiceInfo,
+        correlation_id: UUID | None = None,
+    ) -> ModelHandlerRegistrationResult:
+        """Register a service in the mock store.
+
+        Args:
+            service_info: Service information to register.
+            correlation_id: Optional correlation ID for tracing.
+
+        Returns:
+            ModelHandlerRegistrationResult with registration outcome.
+        """
+        correlation_id = correlation_id or uuid4()
+        start_time = time.monotonic()
+
+        async with self._lock:
+            # Add timestamp if not present
+            if service_info.registered_at is None:
+                service_info = ModelServiceInfo(
+                    service_id=service_info.service_id,
+                    service_name=service_info.service_name,
+                    address=service_info.address,
+                    port=service_info.port,
+                    tags=service_info.tags,
+                    health_status=service_info.health_status,
+                    metadata=service_info.metadata,
+                    health_check_url=service_info.health_check_url,
+                    registered_at=datetime.now(UTC),
+                    correlation_id=correlation_id,
+                )
+
+            self._services[service_info.service_id] = service_info
+
+        duration_ms = (time.monotonic() - start_time) * 1000
+
+        logger.debug(
+            "Mock service registered",
+            extra={
+                "service_id": service_info.service_id,
+                "service_name": service_info.service_name,
+                "correlation_id": str(correlation_id),
+            },
+        )
+
+        return ModelHandlerRegistrationResult(
+            success=True,
+            service_id=service_info.service_id,
+            operation=EnumServiceDiscoveryOperation.REGISTER,
+            duration_ms=duration_ms,
+            backend_type=self.handler_type,
+            correlation_id=correlation_id,
+        )
+
+    async def deregister_service(
+        self,
+        service_id: UUID,
+        correlation_id: UUID | None = None,
+    ) -> None:
+        """Deregister a service from the mock store.
+
+        Args:
+            service_id: UUID of the service to deregister.
+            correlation_id: Optional correlation ID for tracing.
+        """
+        correlation_id = correlation_id or uuid4()
+
+        async with self._lock:
+            self._services.pop(service_id, None)
+
+        logger.debug(
+            "Mock service deregistered",
+            extra={
+                "service_id": str(service_id),
+                "correlation_id": str(correlation_id),
+            },
+        )
+
+    async def discover_services(
+        self,
+        query: ModelDiscoveryQuery,
+        correlation_id: UUID | None = None,
+    ) -> ModelDiscoveryResult:
+        """Discover services matching the query criteria in the mock store.
+
+        Args:
+            query: Query parameters including service_name, tags,
+                and health_filter for filtering services.
+            correlation_id: Optional correlation ID for tracing.
+                If not provided, uses query.correlation_id.
+
+        Returns:
+            ModelDiscoveryResult with list of matching services.
+        """
+        correlation_id = correlation_id or query.correlation_id
+        start_time = time.monotonic()
+
+        async with self._lock:
+            matching_services: list[ModelServiceInfo] = []
+
+            for service in self._services.values():
+                # Match by service name if provided
+                if query.service_name and service.service_name != query.service_name:
+                    continue
+
+                # Match by tags if provided
+                if query.tags:
+                    service_tags = set(service.tags)
+                    if not all(tag in service_tags for tag in query.tags):
+                        continue
+
+                matching_services.append(service)
+
+        duration_ms = (time.monotonic() - start_time) * 1000
+
+        logger.debug(
+            "Mock service discovery completed",
+            extra={
+                "service_name": query.service_name,
+                "found_count": len(matching_services),
+                "correlation_id": str(correlation_id),
+            },
+        )
+
+        return ModelDiscoveryResult(
+            success=True,
+            services=tuple(matching_services),
+            duration_ms=duration_ms,
+            backend_type=self.handler_type,
+            correlation_id=correlation_id,
+        )
+
+    async def health_check(
+        self,
+        correlation_id: UUID | None = None,
+    ) -> ModelServiceDiscoveryHealthCheckResult:
+        """Perform a health check on the mock handler.
+
+        Args:
+            correlation_id: Optional correlation ID for tracing.
+
+        Returns:
+            ModelServiceDiscoveryHealthCheckResult with health status information.
+        """
+        correlation_id = correlation_id or uuid4()
+        start_time = time.monotonic()
+
+        async with self._lock:
+            service_count = len(self._services)
+
+        latency_ms = (time.monotonic() - start_time) * 1000
+
+        return ModelServiceDiscoveryHealthCheckResult(
+            healthy=True,
+            backend_type=self.handler_type,
+            latency_ms=latency_ms,
+            reason="ok",
+            details=ModelServiceDiscoveryHealthCheckDetails(
+                server_version="mock-1.0.0",
+                service_count=service_count,
+            ),
+            correlation_id=correlation_id,
+        )
+
+    async def clear(self) -> None:
+        """Clear all services from the mock store.
+
+        Utility method for test cleanup.
+        """
+        async with self._lock:
+            self._services.clear()
+
+        logger.debug("Mock service store cleared")
+
+    async def get_service_count(self) -> int:
+        """Get the number of registered services.
+
+        Returns:
+            Number of services in the store.
+        """
+        async with self._lock:
+            return len(self._services)
+
+
+__all__ = ["HandlerServiceDiscoveryMock"]

omnibase_infra/handlers/service_discovery/models/__init__.py

@@ -0,0 +1,22 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Service Discovery Handler Models.
+
+Models for service discovery handler operations.
+"""
+
+from omnibase_infra.handlers.service_discovery.models.model_discovery_result import (
+    ModelDiscoveryResult,
+)
+from omnibase_infra.handlers.service_discovery.models.model_registration_result import (
+    ModelHandlerRegistrationResult,
+)
+from omnibase_infra.handlers.service_discovery.models.model_service_info import (
+    ModelServiceInfo,
+)
+
+__all__: list[str] = [
+    "ModelDiscoveryResult",
+    "ModelHandlerRegistrationResult",
+    "ModelServiceInfo",
+]

omnibase_infra/handlers/service_discovery/models/model_discovery_result.py

@@ -0,0 +1,64 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Discovery Result Model.
+
+This module provides the ModelDiscoveryResult class representing the outcome
+of a service discovery query.
+"""
+
+from __future__ import annotations
+
+from uuid import UUID
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from omnibase_infra.handlers.service_discovery.models.model_service_info import (
+    ModelServiceInfo,
+)
+
+
+class ModelDiscoveryResult(BaseModel):
+    """Result of a service discovery query.
+
+    Contains the list of services matching a discovery query along with
+    operation metadata. Immutable once created.
+
+    Attributes:
+        success: Whether the discovery query completed successfully.
+        services: List of discovered services matching the query.
+        error: Sanitized error message if discovery failed.
+        duration_ms: Time taken for the operation in milliseconds.
+        backend_type: The backend that handled the discovery.
+        correlation_id: Correlation ID for tracing.
+    """
+
+    model_config = ConfigDict(frozen=True, extra="forbid", from_attributes=True)
+
+    success: bool = Field(
+        ...,
+        description="Whether the discovery query completed successfully",
+    )
+    services: tuple[ModelServiceInfo, ...] = Field(
+        default=(),
+        description="List of discovered services matching the query",
+    )
+    error: str | None = Field(
+        default=None,
+        description="Sanitized error message if discovery failed",
+    )
+    duration_ms: float = Field(
+        default=0.0,
+        description="Time taken for the operation in milliseconds",
+        ge=0.0,
+    )
+    backend_type: str = Field(
+        default="unknown",
+        description="The backend type that handled the discovery",
+    )
+    correlation_id: UUID | None = Field(
+        default=None,
+        description="Correlation ID for tracing",
+    )
+
+
+__all__ = ["ModelDiscoveryResult"]

omnibase_infra/handlers/service_discovery/models/model_registration_result.py

@@ -0,0 +1,138 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Handler Registration Result Model for Service Discovery Operations.
+
+This module provides ModelHandlerRegistrationResult, representing the result
+of service registration operations from service discovery handlers.
+
+Architecture:
+    ModelHandlerRegistrationResult captures the outcome of a service registration
+    or deregistration operation at the handler level:
+    - success: Whether the operation completed successfully
+    - service_id: ID of the registered/deregistered service
+    - error: Error message if operation failed
+
+    This model is handler-level specific and distinct from the node-level
+    ModelRegistrationResult to avoid namespace conflicts while maintaining
+    similar semantics.
+
+Related:
+    - ModelServiceInfo: Handler-level service info model
+    - ProtocolServiceDiscoveryHandler: Handler protocol for backends
+    - ModelRegistrationResult (node-level): Node I/O model
+    - OMN-1131: Capability-oriented node architecture
+"""
+
+from __future__ import annotations
+
+from uuid import UUID, uuid4
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from omnibase_infra.nodes.node_service_discovery_effect.models.enum_service_discovery_operation import (
+    EnumServiceDiscoveryOperation,
+)
+
+
+class ModelHandlerRegistrationResult(BaseModel):
+    """Result of service registration or deregistration handler operation.
+
+    Contains the outcome of a registration operation along with
+    any error information if the operation failed.
+
+    Note:
+        This is the handler-level model distinct from the node-level
+        ModelRegistrationResult. Use this model in handler implementations
+        and protocol definitions.
+
+    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 = ModelHandlerRegistrationResult(
+        ...     success=True,
+        ...     service_id=uuid4(),
+        ...     operation=EnumServiceDiscoveryOperation.REGISTER,
+        ...     duration_ms=45.2,
+        ...     backend_type="consul",
+        ... )
+        >>> result.success
+        True
+
+        >>> # Failed deregistration
+        >>> result = ModelHandlerRegistrationResult(
+        ...     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 = ModelHandlerRegistrationResult(success=True)
+            >>> if result:  # Works intuitively
+            ...     print("Registration succeeded")
+        """
+        return self.success
+
+
+__all__ = ["ModelHandlerRegistrationResult"]

omnibase_infra/handlers/service_discovery/models/model_service_info.py

@@ -0,0 +1,99 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Service Information Model for Service Discovery Handlers.
+
+This module provides the ModelServiceInfo class representing service metadata
+for service discovery handler operations.
+
+Note:
+    This model is aligned with the node-level ModelServiceInfo at
+    nodes/node_service_discovery_effect/models/model_service_info.py
+    with additional handler-level fields (health_check_url, registered_at,
+    correlation_id) for handler context and tracing.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from uuid import UUID
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from omnibase_infra.nodes.node_service_discovery_effect.models.enum_health_status import (
+    EnumHealthStatus,
+)
+
+
+class ModelServiceInfo(BaseModel):
+    """Service information for discovery and registration handlers.
+
+    Represents a service instance with its metadata for service discovery
+    handler operations. Immutable once created.
+
+    This model is schema-compatible with the node-level ModelServiceInfo,
+    with additional handler-level fields for tracing and context:
+    - health_check_url: URL for health check verification
+    - registered_at: Timestamp for registration tracking
+    - correlation_id: Correlation ID for distributed tracing
+
+    Attributes:
+        service_id: Unique identifier for the service instance.
+        service_name: Human-readable name of the service.
+        address: Network address (hostname or IP) of the service.
+        port: Network port the service listens on.
+        tags: Tags for filtering and categorization.
+        health_status: Current health status of the service.
+        metadata: Additional key-value metadata for the service.
+        health_check_url: Optional URL for health checks (handler extension).
+        registered_at: Timestamp when the service was registered (handler extension).
+        correlation_id: Correlation ID for tracing (handler extension).
+    """
+
+    model_config = ConfigDict(frozen=True, extra="forbid", from_attributes=True)
+
+    service_id: UUID = Field(
+        ...,
+        description="Unique identifier for the service instance",
+    )
+    service_name: str = Field(
+        ...,
+        description="Human-readable name of the service",
+        min_length=1,
+    )
+    address: str | None = Field(
+        default=None,
+        description="Network address (hostname or IP) of the service",
+    )
+    port: int | None = Field(
+        default=None,
+        description="Network port the service listens on",
+        ge=1,
+        le=65535,
+    )
+    tags: tuple[str, ...] = Field(
+        default=(),
+        description="Tags for filtering and categorization",
+    )
+    health_status: EnumHealthStatus = Field(
+        default=EnumHealthStatus.UNKNOWN,
+        description="Current health status of the service",
+    )
+    metadata: dict[str, str] = Field(
+        default_factory=dict,
+        description="Additional key-value metadata",
+    )
+    health_check_url: str | None = Field(
+        default=None,
+        description="Optional URL for health checks",
+    )
+    registered_at: datetime | None = Field(
+        default=None,
+        description="Timestamp when the service was registered",
+    )
+    correlation_id: UUID | None = Field(
+        default=None,
+        description="Correlation ID for tracing",
+    )
+
+
+__all__ = ["ModelServiceInfo"]