omnibase_infra 0.2.1__py3-none-any.whl

omnibase_infra/nodes/node_registry_effect/handlers/handler_postgres_upsert.py

@@ -0,0 +1,208 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Handler for PostgreSQL registration record upsert.
+
+This handler encapsulates PostgreSQL-specific persistence logic for the
+NodeRegistryEffect node, following the declarative node pattern where handlers
+are extracted for testability and separation of concerns.
+
+Architecture:
+    HandlerPostgresUpsert is responsible for:
+    - Executing upsert operations against the PostgreSQL adapter
+    - Timing operation duration for observability
+    - Sanitizing error messages before inclusion in results
+    - Returning structured ModelBackendResult
+
+    This extraction supports the declarative node pattern where NodeRegistryEffect
+    delegates backend-specific operations to dedicated handlers.
+
+Coroutine Safety:
+    This handler is stateless and coroutine-safe for concurrent calls
+    with different request instances. Thread-safety depends on the
+    underlying ProtocolPostgresAdapter implementation.
+
+Related:
+    - NodeRegistryEffect: Parent effect node that coordinates handlers
+    - ProtocolPostgresAdapter: Protocol defining the upsert interface
+    - ModelBackendResult: Structured result model for backend operations
+    - ModelRegistryRequest: Input request model
+    - OMN-1103: Refactoring ticket for handler extraction
+"""
+
+from __future__ import annotations
+
+import time
+from typing import TYPE_CHECKING
+from uuid import UUID
+
+from omnibase_infra.errors import (
+    InfraAuthenticationError,
+    InfraConnectionError,
+    InfraTimeoutError,
+)
+from omnibase_infra.nodes.node_registry_effect.models import ModelBackendResult
+from omnibase_infra.utils import sanitize_backend_error, sanitize_error_message
+
+if TYPE_CHECKING:
+    from omnibase_infra.nodes.effects.protocol_postgres_adapter import (
+        ProtocolPostgresAdapter,
+    )
+    from omnibase_infra.nodes.node_registry_effect.models import ModelRegistryRequest
+
+
+class HandlerPostgresUpsert:
+    """Handler for PostgreSQL registration record upsert.
+
+    Encapsulates all PostgreSQL-specific persistence logic extracted from
+    NodeRegistryEffect for declarative node compliance. The handler provides
+    a clean interface for executing upsert operations with proper timing
+    and error sanitization.
+
+    Attributes:
+        _postgres_adapter: Protocol-compliant PostgreSQL adapter.
+
+    Example:
+        >>> from unittest.mock import AsyncMock
+        >>> adapter = AsyncMock()
+        >>> adapter.upsert.return_value = ModelBackendResult(success=True, backend_id="postgres")
+        >>> handler = HandlerPostgresUpsert(adapter)
+        >>> result = await handler.handle(request, correlation_id)
+        >>> result.success
+        True
+
+    See Also:
+        - NodeRegistryEffect: Parent node that uses this handler
+        - ProtocolPostgresAdapter: Protocol for PostgreSQL operations
+    """
+
+    def __init__(self, postgres_adapter: ProtocolPostgresAdapter) -> None:
+        """Initialize handler with PostgreSQL adapter.
+
+        Args:
+            postgres_adapter: Protocol-compliant PostgreSQL adapter for
+                executing registration record upsert operations.
+        """
+        self._postgres_adapter = postgres_adapter
+
+    async def handle(
+        self,
+        request: ModelRegistryRequest,
+        correlation_id: UUID,
+    ) -> ModelBackendResult:
+        """Execute PostgreSQL registration record upsert.
+
+        Performs the upsert operation against the PostgreSQL adapter with:
+        - Operation timing via time.perf_counter()
+        - Protocol call to adapter.upsert()
+        - Error sanitization for security
+        - Structured result construction
+
+        Args:
+            request: Registration request with node details including
+                node_id, node_type, node_version, endpoints, and metadata.
+            correlation_id: Request correlation ID for distributed tracing.
+
+        Returns:
+            ModelBackendResult with:
+                - success: True if upsert completed successfully
+                - error: Sanitized error message if failed
+                - error_code: Error code for programmatic handling
+                - duration_ms: Operation duration in milliseconds
+                - backend_id: Set to "postgres"
+                - correlation_id: Passed through for tracing
+
+        Note:
+            Error messages are sanitized using sanitize_backend_error to
+            prevent exposure of connection strings, credentials, or other
+            sensitive information in logs and responses.
+        """
+        start_time = time.perf_counter()
+
+        try:
+            result = await self._postgres_adapter.upsert(
+                node_id=request.node_id,
+                node_type=request.node_type,
+                node_version=request.node_version,
+                endpoints=request.endpoints,
+                metadata=request.metadata,
+            )
+
+            duration_ms = (time.perf_counter() - start_time) * 1000
+
+            if result.success:
+                return ModelBackendResult(
+                    success=True,
+                    duration_ms=duration_ms,
+                    backend_id="postgres",
+                    correlation_id=correlation_id,
+                )
+            else:
+                # Sanitize backend error to avoid exposing secrets
+                # (connection strings, credentials, internal hostnames)
+                sanitized_error = sanitize_backend_error("postgres", result.error)
+                return ModelBackendResult(
+                    success=False,
+                    error=sanitized_error,
+                    error_code="POSTGRES_UPSERT_ERROR",
+                    duration_ms=duration_ms,
+                    backend_id="postgres",
+                    correlation_id=correlation_id,
+                )
+
+        except (TimeoutError, InfraTimeoutError) as e:
+            # Timeout during upsert - retriable error
+            duration_ms = (time.perf_counter() - start_time) * 1000
+            sanitized_error = sanitize_error_message(e)
+            return ModelBackendResult(
+                success=False,
+                error=sanitized_error,
+                error_code="POSTGRES_TIMEOUT_ERROR",
+                duration_ms=duration_ms,
+                backend_id="postgres",
+                correlation_id=correlation_id,
+            )
+
+        except InfraAuthenticationError as e:
+            # Authentication failure - non-retriable error
+            duration_ms = (time.perf_counter() - start_time) * 1000
+            sanitized_error = sanitize_error_message(e)
+            return ModelBackendResult(
+                success=False,
+                error=sanitized_error,
+                error_code="POSTGRES_AUTH_ERROR",
+                duration_ms=duration_ms,
+                backend_id="postgres",
+                correlation_id=correlation_id,
+            )
+
+        except InfraConnectionError as e:
+            # Connection failure - retriable error
+            duration_ms = (time.perf_counter() - start_time) * 1000
+            sanitized_error = sanitize_error_message(e)
+            return ModelBackendResult(
+                success=False,
+                error=sanitized_error,
+                error_code="POSTGRES_CONNECTION_ERROR",
+                duration_ms=duration_ms,
+                backend_id="postgres",
+                correlation_id=correlation_id,
+            )
+
+        except (
+            Exception
+        ) as e:  # ONEX: catch-all - database adapter may raise unexpected exceptions
+            # beyond typed infrastructure errors (e.g., driver errors, encoding errors,
+            # connection pool errors). Required to sanitize errors and prevent credential exposure.
+            duration_ms = (time.perf_counter() - start_time) * 1000
+            sanitized_error = sanitize_error_message(e)
+            return ModelBackendResult(
+                success=False,
+                error=sanitized_error,
+                error_code="POSTGRES_UNKNOWN_ERROR",
+                duration_ms=duration_ms,
+                backend_id="postgres",
+                correlation_id=correlation_id,
+            )
+
+
+__all__: list[str] = ["HandlerPostgresUpsert"]

omnibase_infra/nodes/node_registry_effect/models/__init__.py

@@ -0,0 +1,43 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Models for NodeRegistryEffect.
+
+This package contains node-specific Pydantic models for the registry effect node.
+Models follow ONEX naming conventions: Model<Name>.
+
+Shared models are re-exported from the effects package for convenience.
+Node-specific models are defined here.
+
+Model Categories:
+    - Input Models: Request payloads for effect operations
+    - Output Models: Response structures from effect operations
+    - Result Models: Per-backend operation outcomes
+    - Config Models: Node configuration schemas
+
+Related:
+    - omnibase_infra.nodes.effects.models: Shared effect models
+    - contract.yaml: Model references in input_model/output_model
+"""
+
+from __future__ import annotations
+
+# Re-export shared effect models for convenience
+from omnibase_infra.nodes.effects.models import (
+    ModelBackendResult,
+    ModelEffectIdempotencyConfig,
+    ModelRegistryRequest,
+    ModelRegistryResponse,
+)
+
+# Node-specific models
+from omnibase_infra.nodes.node_registry_effect.models.model_partial_retry_request import (
+    ModelPartialRetryRequest,
+)
+
+__all__ = [
+    "ModelBackendResult",
+    "ModelEffectIdempotencyConfig",
+    "ModelPartialRetryRequest",
+    "ModelRegistryRequest",
+    "ModelRegistryResponse",
+]

omnibase_infra/nodes/node_registry_effect/models/model_partial_retry_request.py

@@ -0,0 +1,92 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Partial Retry Request Model for targeted backend retries.
+
+This module provides ModelPartialRetryRequest, a Pydantic model that implements
+the ProtocolPartialRetryRequest protocol for use with HandlerPartialRetry.
+
+Architecture:
+    ModelPartialRetryRequest provides a concrete implementation of the
+    ProtocolPartialRetryRequest protocol, allowing the NodeRegistryEffect to
+    create properly typed requests for partial failure retries.
+
+Related:
+    - HandlerPartialRetry: Handler that consumes this request
+    - ProtocolPartialRetryRequest: Protocol this model implements
+    - NodeRegistryEffect: Node that creates these requests
+"""
+
+from __future__ import annotations
+
+from uuid import UUID
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from omnibase_core.enums.enum_node_kind import EnumNodeKind
+from omnibase_infra.enums import EnumBackendType
+
+
+class ModelPartialRetryRequest(BaseModel):
+    """Request model for partial failure retry operations.
+
+    Provides a Pydantic model implementation of the ProtocolPartialRetryRequest
+    protocol for HandlerPartialRetry.
+
+    Attributes:
+        node_id: Unique identifier for the node being registered.
+        node_type: Type of ONEX node (effect, compute, reducer, orchestrator).
+        node_version: Semantic version of the node.
+        target_backend: Backend to retry ("consul" or "postgres").
+        idempotency_key: Optional key for idempotent retry semantics.
+        service_name: Optional service name for Consul registration.
+        tags: Tags for Consul service discovery.
+        health_check_config: Optional Consul health check configuration.
+        endpoints: Dict of endpoint type to URL for PostgreSQL.
+        metadata: Additional metadata for PostgreSQL registration.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    node_id: UUID = Field(
+        ...,
+        description="Unique identifier for the node being registered",
+    )
+    node_type: EnumNodeKind = Field(
+        ...,
+        description="Type of ONEX node (effect, compute, reducer, orchestrator)",
+    )
+    node_version: str = Field(
+        ...,
+        description="Semantic version of the node",
+    )
+    target_backend: EnumBackendType = Field(
+        ...,
+        description="Backend to retry: 'consul' or 'postgres'",
+    )
+    idempotency_key: str | None = Field(
+        default=None,
+        description="Optional key for idempotent retry semantics",
+    )
+    service_name: str | None = Field(
+        default=None,
+        description="Name for service discovery registration (Consul)",
+    )
+    tags: list[str] = Field(
+        default_factory=list,
+        description="List of tags for service discovery (Consul)",
+    )
+    health_check_config: dict[str, str] | None = Field(
+        default=None,
+        description="Optional health check configuration (Consul)",
+    )
+    endpoints: dict[str, str] = Field(
+        default_factory=dict,
+        description="Dict of endpoint type to URL (PostgreSQL)",
+    )
+    metadata: dict[str, str] = Field(
+        default_factory=dict,
+        description="Additional metadata for the registration record (PostgreSQL)",
+    )
+
+
+__all__ = ["ModelPartialRetryRequest"]

omnibase_infra/nodes/node_registry_effect/node.py

@@ -0,0 +1,165 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Node Registry Effect - Declarative effect node for dual-backend registration.
+
+This node follows the ONEX declarative pattern:
+    - DECLARATIVE effect driven by contract.yaml
+    - Zero custom routing logic - all behavior from handler_routing
+    - Lightweight shell that delegates to handlers via container resolution
+    - Used for ONEX-compliant runtime execution via RuntimeHostProcess
+    - Pattern: "Contract-driven, handlers wired externally"
+
+Extends NodeEffect from omnibase_core for infrastructure I/O operations.
+All handler routing is 100% driven by contract.yaml, not Python code.
+
+Handler Routing Pattern:
+    1. Receive registration request (input_model in contract)
+    2. Route to appropriate handler based on payload type (handler_routing)
+    3. Execute infrastructure I/O via handler (Consul, PostgreSQL)
+    4. Return structured response (output_model in contract)
+
+Design Decisions:
+    - 100% Contract-Driven: All routing logic in YAML, not Python
+    - Zero Custom Routing: Base class handles handler dispatch via contract
+    - Declarative Handlers: handler_routing section defines dispatch rules
+    - External Wiring: Handlers resolved via container dependency injection
+
+Node Responsibilities:
+    - Define I/O model contract (ModelRegistryRequest -> ModelRegistryResponse)
+    - Provide dependency injection points for backend clients
+    - Delegate all execution to handlers via base class
+
+The actual handler execution and routing is performed by:
+    - NodeOrchestrator (for workflow coordination)
+    - Or direct handler invocation by callers
+
+Coroutine Safety:
+    This node is async-safe. Handler coordination is performed by the
+    orchestrator layer, not by this effect node.
+
+Related Modules:
+    - contract.yaml: Handler routing and I/O model definitions
+    - handlers/: Backend-specific handlers (Consul, PostgreSQL)
+    - models/: Node-specific input/output models
+    - NodeRegistrationOrchestrator: Coordinates handler execution
+
+Migration Notes (OMN-1103):
+    This declarative node replaces the imperative implementation.
+    All routing logic has been moved to contract.yaml handler_routing.
+    Callers should use handlers directly or via the orchestrator.
+"""
+
+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
+    from omnibase_infra.nodes.effects.protocol_consul_client import ProtocolConsulClient
+    from omnibase_infra.nodes.effects.protocol_postgres_adapter import (
+        ProtocolPostgresAdapter,
+    )
+
+
+class NodeRegistryEffect(NodeEffect):
+    """Declarative effect node for dual-backend node registration.
+
+    This effect node is a lightweight shell that defines the I/O contract
+    for registration operations. All routing and execution logic is driven
+    by contract.yaml - this class contains no custom routing code.
+
+    Handler coordination is performed by:
+        - NodeRegistrationOrchestrator for workflow-based execution
+        - Direct handler invocation for simple use cases
+
+    Supported Operations (defined in contract.yaml handler_routing):
+        - register_node: Register to both Consul and PostgreSQL
+        - deregister_node: Deregister from both backends
+        - retry_partial_failure: Retry a specific backend after partial failure
+
+    Dependency Injection:
+        Backend clients are injected via setter methods. The orchestrator
+        or caller is responsible for wiring these dependencies.
+
+    Example:
+        ```python
+        from omnibase_core.models.container import ModelONEXContainer
+        from omnibase_infra.nodes.node_registry_effect import NodeRegistryEffect
+        from omnibase_infra.nodes.node_registry_effect.handlers import (
+            HandlerConsulRegister,
+            HandlerPostgresUpsert,
+        )
+
+        # Create effect node
+        container = ModelONEXContainer()
+        effect = NodeRegistryEffect(container)
+
+        # Wire backend clients
+        effect.set_consul_client(consul_client)
+        effect.set_postgres_adapter(postgres_adapter)
+
+        # Execute via handlers directly
+        consul_handler = HandlerConsulRegister(consul_client)
+        postgres_handler = HandlerPostgresUpsert(postgres_adapter)
+
+        # Or use orchestrator for coordinated execution
+        orchestrator = NodeRegistrationOrchestrator(container)
+        result = await orchestrator.execute_registration(request)
+        ```
+    """
+
+    def __init__(self, container: ModelONEXContainer) -> None:
+        """Initialize the effect node.
+
+        Args:
+            container: ONEX dependency injection container providing:
+                - Backend adapters (Consul client, PostgreSQL adapter)
+                - Handler instances
+                - Configuration
+        """
+        super().__init__(container)
+
+        # Backend adapters (injected via setter methods)
+        self._consul_client: ProtocolConsulClient | None = None
+        self._postgres_adapter: ProtocolPostgresAdapter | None = None
+
+    def set_consul_client(self, client: ProtocolConsulClient) -> None:
+        """Set the Consul client for service registration.
+
+        Args:
+            client: Protocol-compliant Consul client implementation.
+        """
+        self._consul_client = client
+
+    def set_postgres_adapter(self, adapter: ProtocolPostgresAdapter) -> None:
+        """Set the PostgreSQL adapter for registration persistence.
+
+        Args:
+            adapter: Protocol-compliant PostgreSQL adapter implementation.
+        """
+        self._postgres_adapter = adapter
+
+    @property
+    def consul_client(self) -> ProtocolConsulClient | None:
+        """Get the Consul client if configured."""
+        return self._consul_client
+
+    @property
+    def postgres_adapter(self) -> ProtocolPostgresAdapter | None:
+        """Get the PostgreSQL adapter if configured."""
+        return self._postgres_adapter
+
+    @property
+    def has_consul_client(self) -> bool:
+        """Check if Consul client is configured."""
+        return self._consul_client is not None
+
+    @property
+    def has_postgres_adapter(self) -> bool:
+        """Check if PostgreSQL adapter is configured."""
+        return self._postgres_adapter is not None
+
+
+__all__ = ["NodeRegistryEffect"]

omnibase_infra/nodes/node_registry_effect/registry/__init__.py

@@ -0,0 +1,27 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Registry package for NodeRegistryEffect.
+
+This package provides infrastructure registry components for the
+NodeRegistryEffect node, following ONEX naming conventions.
+
+Exports:
+    RegistryInfraRegistryEffect: Factory and metadata registry for
+        creating NodeRegistryEffect instances with dependency injection.
+
+Usage:
+    >>> from omnibase_infra.nodes.node_registry_effect.registry import (
+    ...     RegistryInfraRegistryEffect,
+    ... )
+    >>> effect = RegistryInfraRegistryEffect.create(container)
+
+.. versionadded:: 0.5.0
+"""
+
+from __future__ import annotations
+
+from omnibase_infra.nodes.node_registry_effect.registry.registry_infra_registry_effect import (
+    RegistryInfraRegistryEffect,
+)
+
+__all__ = ["RegistryInfraRegistryEffect"]