omnibase_infra 0.2.6__py3-none-any.whl

omnibase_infra/nodes/effects/protocol_consul_client.py

@@ -0,0 +1,89 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Protocol for Consul service registration client.
+
+This module defines the protocol that Consul clients must implement
+to be used with the NodeRegistryEffect node.
+
+Concurrency Safety:
+    Implementations MUST be safe for concurrent async calls.
+    Multiple coroutines may invoke register_service() simultaneously
+    for different or identical service registrations. Implementations
+    should use asyncio.Lock for coroutine-safety when protecting shared state.
+
+Related:
+    - NodeRegistryEffect: Effect node that uses this protocol
+    - ProtocolPostgresAdapter: Protocol for PostgreSQL backend
+    - ModelBackendResult: Structured result model for backend operations
+"""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+from omnibase_infra.nodes.effects.models import ModelBackendResult
+
+
+@runtime_checkable
+class ProtocolConsulClient(Protocol):
+    """Protocol for Consul service registration client.
+
+    Implementations must provide async service registration capability.
+
+    Concurrency Safety:
+        Implementations MUST be safe for concurrent async coroutine calls.
+
+        **Guarantees implementers MUST provide:**
+            - Concurrent register_service() 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 register_service() concurrently
+            - Each registration operation is independent
+            - Failures in one registration do not affect others
+
+        Note: asyncio.Lock provides coroutine-safety, not thread-safety.
+    """
+
+    async def register_service(
+        self,
+        service_id: str,
+        service_name: str,
+        tags: list[str],
+        health_check: dict[str, str] | None = None,
+    ) -> ModelBackendResult:
+        """Register a service in Consul.
+
+        Args:
+            service_id: Unique identifier for the service instance.
+            service_name: Name of the service for discovery.
+            tags: List of tags for filtering.
+            health_check: Optional health check configuration.
+
+        Returns:
+            ModelBackendResult with success status, optional error message,
+            timing information, and correlation context.
+        """
+        ...
+
+    async def deregister_service(
+        self,
+        service_id: str,
+    ) -> ModelBackendResult:
+        """Deregister a service from Consul.
+
+        Removes the service registration, stopping health checks and
+        removing it from service discovery.
+
+        Args:
+            service_id: Unique identifier for the service instance to remove.
+
+        Returns:
+            ModelBackendResult with success status, optional error message,
+            timing information, and correlation context.
+        """
+        ...
+
+
+__all__ = ["ProtocolConsulClient"]

omnibase_infra/nodes/effects/protocol_effect_idempotency_store.py

@@ -0,0 +1,143 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Protocol for Effect layer idempotency stores.
+
+This module defines the protocol interface for pluggable idempotency backends
+used by Effect nodes to track completed backends during dual-backend operations.
+
+Design Rationale:
+    This protocol is separate from ProtocolIdempotencyStore (omnibase_spi)
+    because Effect-level idempotency has different semantics:
+
+    1. Tracks "completed backends" per correlation_id (not just message_id)
+    2. Backend granularity: "consul", "postgres", etc.
+    3. Optimized for dual-backend retry scenarios
+    4. Does not need full message metadata (domain, processed_at patterns)
+
+    The ProtocolIdempotencyStore from omnibase_spi is designed for message-level
+    deduplication with domain isolation, which is a different use case.
+
+Available Implementations:
+    - InMemoryEffectIdempotencyStore: Bounded LRU cache with TTL (default)
+    - Future: RedisEffectIdempotencyStore, PostgresEffectIdempotencyStore
+
+Production Considerations:
+    The in-memory implementation is NOT suitable for:
+    - Distributed deployments (multi-instance)
+    - Scenarios requiring persistence across restarts
+    - Long-running operations exceeding TTL
+
+    For production, implement a persistent backend using this protocol.
+
+Related:
+    - ModelEffectIdempotencyConfig: Configuration for in-memory store
+    - InMemoryEffectIdempotencyStore: Default in-memory implementation
+    - NodeRegistryEffect: Consumes this protocol for dual-backend idempotency
+    - OMN-954: Registry effect idempotency requirements
+"""
+
+from __future__ import annotations
+
+from typing import Protocol
+from uuid import UUID
+
+
+class ProtocolEffectIdempotencyStore(Protocol):
+    """Protocol for Effect layer idempotency storage backends.
+
+    Defines the interface for tracking completed backends per correlation_id.
+    Implementations must be async-safe and support bounded memory usage.
+
+    Concurrency Safety:
+        Implementations MUST be safe for concurrent coroutine access.
+        Use asyncio.Lock or equivalent async synchronization primitives.
+        Note: asyncio.Lock provides coroutine-safety, not thread-safety.
+
+    Memory Bounds:
+        Implementations SHOULD support:
+        - Maximum entry count (LRU eviction)
+        - TTL-based expiration
+
+    Example Implementation:
+        >>> class MyIdempotencyStore:
+        ...     async def mark_completed(
+        ...         self, correlation_id: UUID, backend: str
+        ...     ) -> None:
+        ...         # Persist completion
+        ...         await self._db.insert(correlation_id, backend)
+        ...
+        ...     async def is_completed(
+        ...         self, correlation_id: UUID, backend: str
+        ...     ) -> bool:
+        ...         return await self._db.exists(correlation_id, backend)
+        ...
+        ...     async def get_completed_backends(
+        ...         self, correlation_id: UUID
+        ...     ) -> set[str]:
+        ...         return await self._db.get_backends(correlation_id)
+        ...
+        ...     async def clear(self, correlation_id: UUID) -> None:
+        ...         await self._db.delete(correlation_id)
+    """
+
+    async def mark_completed(self, correlation_id: UUID, backend: str) -> None:
+        """Mark a backend as completed for a correlation ID.
+
+        Records that the specified backend has successfully completed its
+        operation for the given correlation_id. Subsequent calls with the
+        same (correlation_id, backend) pair are idempotent.
+
+        Args:
+            correlation_id: Unique identifier for the operation.
+            backend: Backend identifier (e.g., "consul", "postgres").
+
+        Raises:
+            InfraUnavailableError: If the store is unavailable.
+        """
+        ...
+
+    async def is_completed(self, correlation_id: UUID, backend: str) -> bool:
+        """Check if a backend is completed for a correlation ID.
+
+        Args:
+            correlation_id: Unique identifier for the operation.
+            backend: Backend identifier to check.
+
+        Returns:
+            True if the backend is completed, False otherwise.
+
+        Raises:
+            InfraUnavailableError: If the store is unavailable.
+        """
+        ...
+
+    async def get_completed_backends(self, correlation_id: UUID) -> set[str]:
+        """Get all completed backends for a correlation ID.
+
+        Args:
+            correlation_id: Unique identifier for the operation.
+
+        Returns:
+            Set of completed backend identifiers. Empty set if none.
+
+        Raises:
+            InfraUnavailableError: If the store is unavailable.
+        """
+        ...
+
+    async def clear(self, correlation_id: UUID) -> None:
+        """Clear completed backends for a correlation ID.
+
+        Removes all backend completion records for the given correlation_id.
+        Used for testing or to force re-registration.
+
+        Args:
+            correlation_id: The correlation ID to clear.
+
+        Raises:
+            InfraUnavailableError: If the store is unavailable.
+        """
+        ...
+
+
+__all__ = ["ProtocolEffectIdempotencyStore"]

omnibase_infra/nodes/effects/protocol_postgres_adapter.py

@@ -0,0 +1,96 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Protocol for PostgreSQL registration persistence.
+
+This module defines the protocol that PostgreSQL adapters must implement
+to be used with the NodeRegistryEffect node.
+
+Concurrency Safety:
+    Implementations MUST be safe for concurrent async calls.
+    Multiple coroutines may invoke upsert() simultaneously for
+    different or identical node registrations. Implementations
+    should use asyncio.Lock for coroutine-safety when protecting shared state.
+
+Related:
+    - NodeRegistryEffect: Effect node that uses this protocol
+    - ProtocolConsulClient: Protocol for Consul backend
+    - ModelBackendResult: Structured result model for backend operations
+"""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+from uuid import UUID
+
+from omnibase_core.enums import EnumNodeKind
+from omnibase_core.models.primitives import ModelSemVer
+from omnibase_infra.nodes.effects.models import ModelBackendResult
+
+
+@runtime_checkable
+class ProtocolPostgresAdapter(Protocol):
+    """Protocol for PostgreSQL registration persistence.
+
+    Implementations must provide async upsert capability for
+    registration records.
+
+    Concurrency Safety:
+        Implementations MUST be safe for concurrent async coroutine calls.
+
+        **Guarantees implementers MUST provide:**
+            - Concurrent upsert() calls are coroutine-safe
+            - Connection pooling (if used) is async-safe
+            - Database transactions are properly isolated
+
+        **What callers can assume:**
+            - Multiple coroutines can call upsert() concurrently
+            - Each upsert operation is independent
+            - Failures in one upsert do not affect others
+
+        Note: asyncio.Lock provides coroutine-safety, not thread-safety.
+    """
+
+    async def upsert(
+        self,
+        node_id: UUID,
+        node_type: EnumNodeKind,
+        node_version: ModelSemVer,
+        endpoints: dict[str, str],
+        metadata: dict[str, str],
+    ) -> ModelBackendResult:
+        """Upsert a node registration record.
+
+        Args:
+            node_id: Unique identifier for the node.
+            node_type: Type of ONEX node (EnumNodeKind).
+            node_version: Semantic version of the node.
+            endpoints: Dict of endpoint type to URL.
+            metadata: Additional metadata.
+
+        Returns:
+            ModelBackendResult with success status, optional error message,
+            timing information, and correlation context.
+        """
+        ...
+
+    async def deactivate(
+        self,
+        node_id: UUID,
+    ) -> ModelBackendResult:
+        """Deactivate a node registration record.
+
+        Marks the registration as inactive (soft delete) rather than
+        removing it entirely. This preserves historical data while
+        stopping the node from appearing in active registrations.
+
+        Args:
+            node_id: Unique identifier for the node to deactivate.
+
+        Returns:
+            ModelBackendResult with success status, optional error message,
+            timing information, and correlation context.
+        """
+        ...
+
+
+__all__ = ["ProtocolPostgresAdapter"]