omnibase_infra 0.2.1__py3-none-any.whl

omnibase_infra/handlers/service_discovery/protocol_discovery_operations.py

@@ -0,0 +1,170 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Protocol for Service Discovery Handler.
+
+This module defines the protocol that service discovery handlers must implement
+to be used with capability-oriented nodes.
+
+Protocol Duplication Note:
+    This protocol is intentionally separate from the node-level protocol
+    at ``nodes/node_service_discovery_effect/protocols/protocol_discovery_operations.py``:
+
+    - **This protocol (handlers/*/protocol_*.py)**: Handler implementation
+      contract used by tests for compliance verification. Uses
+      ``ModelServiceInfo`` with optional ``correlation_id``.
+
+    - **Node protocol (nodes/*/protocols/)**: Node-level contract used for
+      container-based dependency injection and registry binding.
+
+    The separation allows different parameter models and independent evolution
+    of handler contracts vs node-level DI contracts.
+
+Concurrency Safety:
+    Implementations MUST be safe for concurrent async calls.
+    Multiple coroutines may invoke methods simultaneously.
+    Implementations should use asyncio.Lock for coroutine-safety
+    when protecting shared state.
+
+Related:
+    - NodeServiceDiscoveryEffect: Effect node that uses this protocol
+    - HandlerServiceDiscoveryConsul: Consul implementation
+    - HandlerServiceDiscoveryMock: In-memory mock for testing
+    - nodes/node_service_discovery_effect/protocols/: Node-level protocol
+"""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+from uuid import UUID
+
+from omnibase_infra.handlers.service_discovery.models import (
+    ModelDiscoveryResult,
+    ModelHandlerRegistrationResult,
+    ModelServiceInfo,
+)
+from omnibase_infra.nodes.node_service_discovery_effect.models import (
+    ModelDiscoveryQuery,
+    ModelServiceDiscoveryHealthCheckResult,
+)
+
+
+@runtime_checkable
+class ProtocolDiscoveryOperations(Protocol):
+    """Protocol for service discovery handler implementations.
+
+    Defines the interface that all service discovery handlers must implement.
+    Handlers are responsible for service registration, deregistration,
+    discovery, and health checking.
+
+    Concurrency Safety:
+        Implementations MUST be safe for concurrent async coroutine calls.
+
+        **Guarantees implementers MUST provide:**
+            - Concurrent method calls are coroutine-safe
+            - Connection pooling (if used) is async-safe
+            - Internal state (if any) is protected by asyncio.Lock
+
+        **What callers can assume:**
+            - Multiple coroutines can call methods concurrently
+            - Each operation is independent
+            - Failures in one operation do not affect others
+
+        Note: asyncio.Lock provides coroutine-safety, not thread-safety.
+    """
+
+    @property
+    def handler_type(self) -> str:
+        """Return the handler type identifier.
+
+        Returns:
+            Handler type string (e.g., "consul", "mock").
+        """
+        ...
+
+    async def register_service(
+        self,
+        service_info: ModelServiceInfo,
+        correlation_id: UUID | None = None,
+    ) -> ModelHandlerRegistrationResult:
+        """Register a service with the discovery backend.
+
+        Args:
+            service_info: Service information to register.
+            correlation_id: Optional correlation ID for tracing.
+
+        Returns:
+            ModelHandlerRegistrationResult with success status, service ID,
+            and operation metadata.
+
+        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 = None,
+    ) -> None:
+        """Deregister a service from the discovery backend.
+
+        Args:
+            service_id: UUID of the service to deregister.
+            correlation_id: Optional correlation ID for 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 | None = None,
+    ) -> ModelDiscoveryResult:
+        """Discover services matching the query criteria.
+
+        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
+            and operation 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:
+        """Perform a health check on the handler.
+
+        Args:
+            correlation_id: Optional correlation ID for tracing.
+
+        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
+        """
+        ...
+
+
+__all__ = ["ProtocolDiscoveryOperations"]

omnibase_infra/idempotency/__init__.py

@@ -0,0 +1,94 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""ONEX Infrastructure Idempotency System.
+
+This module provides idempotency checking and deduplication capabilities
+for message processing in distributed systems.
+
+Components:
+    - Models: Pydantic models for idempotency records, check results, configuration, and metrics
+    - Store: Persistent storage backends for idempotency records (PostgreSQL, in-memory)
+    - Guard: Decorator and middleware for automatic idempotency checking
+
+Models:
+    - ModelIdempotencyRecord: Record of a processed message for deduplication
+    - ModelIdempotencyCheckResult: Result of an idempotency check operation
+    - ModelIdempotencyStoreMetrics: Metrics for store observability
+    - ModelPostgresIdempotencyStoreConfig: Configuration for PostgreSQL store
+    - ModelIdempotencyGuardConfig: Configuration for the idempotency guard
+
+Stores:
+    - StoreIdempotencyInmemory: In-memory store for testing (OMN-945)
+    - StoreIdempotencyPostgres: Production PostgreSQL store (OMN-945)
+
+Example - InMemory (Testing):
+    >>> from omnibase_infra.idempotency import StoreIdempotencyInmemory
+    >>> from uuid import uuid4
+    >>>
+    >>> store = StoreIdempotencyInmemory()
+    >>> message_id = uuid4()
+    >>>
+    >>> # First call returns True (message is new)
+    >>> result = await store.check_and_record(message_id, domain="test")
+    >>> assert result is True
+    >>>
+    >>> # Second call returns False (duplicate)
+    >>> result = await store.check_and_record(message_id, domain="test")
+    >>> assert result is False
+
+Example - Models:
+    >>> from omnibase_infra.idempotency import (
+    ...     ModelIdempotencyRecord,
+    ...     ModelIdempotencyCheckResult,
+    ...     ModelIdempotencyStoreMetrics,
+    ...     ModelPostgresIdempotencyStoreConfig,
+    ...     ModelIdempotencyGuardConfig,
+    ... )
+    >>> from uuid import uuid4
+    >>> from datetime import datetime, timezone
+    >>>
+    >>> # Create an idempotency record
+    >>> record = ModelIdempotencyRecord(
+    ...     message_id=uuid4(),
+    ...     domain="orders",
+    ...     processed_at=datetime.now(timezone.utc),
+    ... )
+    >>>
+    >>> # Configure the guard
+    >>> guard_config = ModelIdempotencyGuardConfig(
+    ...     enabled=True,
+    ...     store_type="postgres",
+    ...     domain_from_operation=True,
+    ... )
+    >>>
+    >>> # Get store metrics
+    >>> metrics = store.get_metrics()
+    >>> print(f"Duplicate rate: {metrics.duplicate_rate:.2%}")
+"""
+
+from omnibase_infra.idempotency.models import (
+    ModelIdempotencyCheckResult,
+    ModelIdempotencyGuardConfig,
+    ModelIdempotencyRecord,
+    ModelIdempotencyStoreMetrics,
+    ModelPostgresIdempotencyStoreConfig,
+)
+from omnibase_infra.idempotency.protocol_idempotency_store import (
+    ProtocolIdempotencyStore,
+)
+from omnibase_infra.idempotency.store_inmemory import StoreIdempotencyInmemory
+from omnibase_infra.idempotency.store_postgres import StoreIdempotencyPostgres
+
+__all__: list[str] = [
+    # Stores
+    "StoreIdempotencyInmemory",
+    # Models
+    "ModelIdempotencyCheckResult",
+    "ModelIdempotencyGuardConfig",
+    "ModelIdempotencyRecord",
+    "ModelIdempotencyStoreMetrics",
+    "ModelPostgresIdempotencyStoreConfig",
+    "StoreIdempotencyPostgres",
+    # Protocol
+    "ProtocolIdempotencyStore",
+]

omnibase_infra/idempotency/models/__init__.py

@@ -0,0 +1,43 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""ONEX Infrastructure Idempotency Models.
+
+This module provides Pydantic models for the idempotency system,
+including records, check results, configuration, and metrics models.
+
+Exports:
+    ModelIdempotencyStoreHealthCheckResult: Result of an idempotency store health check
+    ModelIdempotencyRecord: Represents a stored idempotency record
+    ModelIdempotencyCheckResult: Result of an idempotency check operation
+    ModelIdempotencyGuardConfig: Configuration for idempotency guard middleware
+    ModelIdempotencyStoreMetrics: Metrics for store observability
+    ModelPostgresIdempotencyStoreConfig: Configuration for PostgreSQL store
+"""
+
+from omnibase_infra.idempotency.models.model_idempotency_check_result import (
+    ModelIdempotencyCheckResult,
+)
+from omnibase_infra.idempotency.models.model_idempotency_guard_config import (
+    ModelIdempotencyGuardConfig,
+)
+from omnibase_infra.idempotency.models.model_idempotency_record import (
+    ModelIdempotencyRecord,
+)
+from omnibase_infra.idempotency.models.model_idempotency_store_health_check_result import (
+    ModelIdempotencyStoreHealthCheckResult,
+)
+from omnibase_infra.idempotency.models.model_idempotency_store_metrics import (
+    ModelIdempotencyStoreMetrics,
+)
+from omnibase_infra.idempotency.models.model_postgres_idempotency_store_config import (
+    ModelPostgresIdempotencyStoreConfig,
+)
+
+__all__ = [
+    "ModelIdempotencyCheckResult",
+    "ModelIdempotencyGuardConfig",
+    "ModelIdempotencyRecord",
+    "ModelIdempotencyStoreHealthCheckResult",
+    "ModelIdempotencyStoreMetrics",
+    "ModelPostgresIdempotencyStoreConfig",
+]

omnibase_infra/idempotency/models/model_idempotency_check_result.py

@@ -0,0 +1,85 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Idempotency Check Result Model.
+
+This module provides the Pydantic model for the result of an idempotency
+check operation, indicating whether a message is a duplicate and providing
+details about the original processing if applicable.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from uuid import UUID
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class ModelIdempotencyCheckResult(BaseModel):
+    """Result of an idempotency check operation.
+
+    This model represents the outcome of checking whether a message has
+    already been processed. It provides all necessary information for
+    the caller to decide how to proceed.
+
+    Attributes:
+        is_duplicate: True if the message has already been processed.
+            When True, the caller should skip processing this message.
+        message_id: The unique identifier of the checked message.
+            Echoed back for verification and logging purposes.
+        domain: Optional domain/namespace that was checked.
+            Matches the domain used in the idempotency check.
+        original_processed_at: Timestamp when the message was first processed.
+            Only populated when is_duplicate is True. Useful for debugging
+            and understanding the timing of duplicate messages.
+
+    Example:
+        >>> from uuid import uuid4
+        >>> from datetime import datetime, timezone
+        >>> # Non-duplicate result
+        >>> result = ModelIdempotencyCheckResult(
+        ...     is_duplicate=False,
+        ...     message_id=uuid4(),
+        ...     domain="orders",
+        ...     original_processed_at=None,
+        ... )
+        >>> if not result.is_duplicate:
+        ...     print("Processing message...")
+        Processing message...
+
+        >>> # Duplicate result
+        >>> duplicate_result = ModelIdempotencyCheckResult(
+        ...     is_duplicate=True,
+        ...     message_id=uuid4(),
+        ...     domain="orders",
+        ...     original_processed_at=datetime.now(timezone.utc),
+        ... )
+        >>> if duplicate_result.is_duplicate:
+        ...     print(f"Skipping duplicate, first processed at {duplicate_result.original_processed_at}")
+        Skipping duplicate, first processed at ...
+    """
+
+    model_config = ConfigDict(
+        frozen=True,
+        extra="forbid",
+        from_attributes=True,
+    )
+
+    is_duplicate: bool = Field(
+        description="True if the message has already been processed",
+    )
+    message_id: UUID = Field(
+        description="Unique identifier of the checked message",
+    )
+    domain: str | None = Field(
+        default=None,
+        description="Domain/namespace that was checked",
+        max_length=255,
+    )
+    original_processed_at: datetime | None = Field(
+        default=None,
+        description="Timestamp when the message was first processed (only if duplicate)",
+    )
+
+
+__all__: list[str] = ["ModelIdempotencyCheckResult"]

omnibase_infra/idempotency/models/model_idempotency_guard_config.py

@@ -0,0 +1,130 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Idempotency Guard Configuration Model.
+
+This module provides the Pydantic configuration model for the idempotency
+guard, which controls how idempotency checking is applied to message handlers.
+"""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class ModelIdempotencyGuardConfig(BaseModel):
+    """Configuration for the idempotency guard.
+
+    The idempotency guard is a decorator or middleware that automatically
+    applies idempotency checking to message handlers. This configuration
+    controls its behavior, including which store backend to use and which
+    operations to skip.
+
+    Attributes:
+        enabled: Whether idempotency checking is enabled.
+            When False, all messages are processed without deduplication.
+            Default: True.
+        store_type: Type of idempotency store to use.
+            "postgres" uses PostgreSQL for persistent storage.
+            "memory" uses in-memory storage (for testing only).
+            Default: "postgres".
+        domain_from_operation: Whether to extract domain from operation prefix.
+            When True, operations like "db.query" will use "db" as the domain.
+            This enables per-domain idempotency partitioning.
+            Default: True.
+        skip_operations: List of operations to skip idempotency checking for.
+            Useful for health checks, metrics endpoints, or other operations
+            that should always be processed.
+            Default: [].
+
+    Example:
+        >>> config = ModelIdempotencyGuardConfig(
+        ...     enabled=True,
+        ...     store_type="postgres",
+        ...     domain_from_operation=True,
+        ...     skip_operations=["health.check", "metrics.collect"],
+        ... )
+        >>> print(config.store_type)
+        postgres
+
+        >>> # Check if an operation should be skipped
+        >>> "health.check" in config.skip_operations
+        True
+    """
+
+    model_config = ConfigDict(
+        frozen=True,
+        extra="forbid",
+        from_attributes=True,
+    )
+
+    enabled: bool = Field(
+        default=True,
+        description="Whether idempotency checking is enabled",
+    )
+    store_type: Literal["postgres", "memory"] = Field(
+        default="postgres",
+        description="Type of idempotency store to use ('postgres' for production, 'memory' for testing)",
+    )
+    domain_from_operation: bool = Field(
+        default=True,
+        description="Extract domain from operation prefix (e.g., 'db.query' -> 'db')",
+    )
+    skip_operations: list[str] = Field(
+        default_factory=list,
+        description="Operations to skip idempotency checking for (e.g., health checks)",
+    )
+
+    def should_check_idempotency(self, operation: str) -> bool:
+        """Determine if idempotency should be checked for an operation.
+
+        Args:
+            operation: The operation name to check.
+
+        Returns:
+            True if idempotency should be checked, False if skipped.
+
+        Example:
+            >>> config = ModelIdempotencyGuardConfig(
+            ...     enabled=True,
+            ...     skip_operations=["health.check"],
+            ... )
+            >>> config.should_check_idempotency("db.query")
+            True
+            >>> config.should_check_idempotency("health.check")
+            False
+        """
+        if not self.enabled:
+            return False
+        return operation not in self.skip_operations
+
+    def extract_domain(self, operation: str) -> str | None:
+        """Extract domain from operation name if configured.
+
+        Args:
+            operation: The operation name (e.g., "db.query", "orders.create").
+
+        Returns:
+            The extracted domain if domain_from_operation is True and
+            operation contains a dot separator, otherwise None.
+
+        Example:
+            >>> config = ModelIdempotencyGuardConfig(domain_from_operation=True)
+            >>> config.extract_domain("db.query")
+            'db'
+            >>> config.extract_domain("simple_operation")
+            None
+
+            >>> config_no_domain = ModelIdempotencyGuardConfig(domain_from_operation=False)
+            >>> config_no_domain.extract_domain("db.query")
+            None
+        """
+        if not self.domain_from_operation:
+            return None
+        if "." in operation:
+            return operation.split(".")[0]
+        return None
+
+
+__all__: list[str] = ["ModelIdempotencyGuardConfig"]

omnibase_infra/idempotency/models/model_idempotency_record.py

@@ -0,0 +1,86 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Idempotency Record Model.
+
+This module provides the Pydantic model for storing idempotency records
+that track processed messages to prevent duplicate processing.
+
+The record captures essential metadata about when and how a message was
+processed, enabling deduplication across distributed systems.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from uuid import UUID, uuid4
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class ModelIdempotencyRecord(BaseModel):
+    """Record of a processed message for idempotency tracking.
+
+    This model represents a single idempotency record that tracks whether
+    a specific message has been processed. It is used by idempotency stores
+    to persist deduplication state.
+
+    Attributes:
+        id: Unique identifier for this record (auto-generated UUID4).
+        domain: Optional domain/namespace for message categorization.
+            Used to partition idempotency checks (e.g., "orders", "payments").
+        message_id: The unique identifier of the processed message.
+            This is the primary key for idempotency lookups.
+        correlation_id: Optional correlation ID for distributed tracing.
+            Links this record to a broader request context.
+        processed_at: Timestamp when the message was processed.
+            Used for TTL-based cleanup of old records.
+        handler_type: Optional handler type identifier for debugging.
+            Records which handler processed this message.
+
+    Example:
+        >>> from uuid import uuid4
+        >>> from datetime import datetime, timezone
+        >>> record = ModelIdempotencyRecord(
+        ...     message_id=uuid4(),
+        ...     domain="orders",
+        ...     correlation_id=uuid4(),
+        ...     processed_at=datetime.now(timezone.utc),
+        ...     handler_type="OrderCreatedHandler",
+        ... )
+        >>> print(record.message_id)
+        UUID('...')
+    """
+
+    model_config = ConfigDict(
+        frozen=True,
+        extra="forbid",
+        from_attributes=True,
+    )
+
+    id: UUID = Field(
+        default_factory=uuid4,
+        description="Unique identifier for this idempotency record",
+    )
+    domain: str | None = Field(
+        default=None,
+        description="Domain/namespace for message categorization (e.g., 'orders', 'payments')",
+        max_length=255,
+    )
+    message_id: UUID = Field(
+        description="Unique identifier of the processed message (primary idempotency key)",
+    )
+    correlation_id: UUID | None = Field(
+        default=None,
+        description="Correlation ID for distributed tracing",
+    )
+    processed_at: datetime = Field(
+        description="Timestamp when the message was processed",
+    )
+    handler_type: str | None = Field(
+        default=None,
+        description="Handler type identifier for debugging purposes",
+        max_length=255,
+    )
+
+
+__all__: list[str] = ["ModelIdempotencyRecord"]

omnibase_infra/idempotency/models/model_idempotency_store_health_check_result.py

@@ -0,0 +1,81 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Idempotency Store Health Check Result Model.
+
+This module provides the Pydantic model for health check results from
+idempotency stores, replacing untyped dict[str, object] returns with
+strongly-typed model instances.
+
+Note:
+    This model is domain-specific to idempotency stores and uses a Literal
+    type for the `reason` field to constrain valid status values. For
+    general-purpose handler health checks, see
+    ``omnibase_infra.runtime.models.ModelHealthCheckResult``.
+"""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class ModelIdempotencyStoreHealthCheckResult(BaseModel):
+    """Result of an idempotency store health check.
+
+    This model represents the outcome of a health check operation on an
+    idempotency store, providing structured diagnostics about the store's
+    operational status.
+
+    Attributes:
+        healthy: Whether the store is healthy and operational.
+            When True, the store can accept operations normally.
+            When False, consult the reason field for diagnostics.
+        reason: Descriptive reason for the health status.
+            - "ok": Store is healthy and operational
+            - "not_initialized": Store has not been initialized
+            - "table_not_found": Required database table does not exist
+            - "check_failed": Health check encountered an exception
+        error_type: Exception type name if health check failed.
+            Only populated when reason is "check_failed".
+            Useful for debugging and categorizing failures.
+
+    Example:
+        >>> # Healthy store
+        >>> result = ModelIdempotencyStoreHealthCheckResult(healthy=True, reason="ok")
+        >>> if result.healthy:
+        ...     print("Store is operational")
+        Store is operational
+
+        >>> # Failed health check
+        >>> result = ModelIdempotencyStoreHealthCheckResult(
+        ...     healthy=False,
+        ...     reason="check_failed",
+        ...     error_type="ConnectionRefusedError",
+        ... )
+        >>> if not result.healthy:
+        ...     print(f"Store unhealthy: {result.reason} ({result.error_type})")
+        Store unhealthy: check_failed (ConnectionRefusedError)
+    """
+
+    model_config = ConfigDict(
+        frozen=True,
+        extra="forbid",
+        from_attributes=True,
+    )
+
+    healthy: bool = Field(
+        description="Whether the store is healthy and operational",
+    )
+    reason: Literal["ok", "not_initialized", "table_not_found", "check_failed"] = Field(
+        description="Reason for the health status",
+    )
+    error_type: str | None = Field(
+        default=None,
+        description="Exception type name if health check failed",
+    )
+
+
+__all__: list[str] = [
+    "ModelIdempotencyStoreHealthCheckResult",
+]