omnibase_infra 0.3.1__py3-none-any.whl → 0.3.2__py3-none-any.whl

omnibase_infra/nodes/node_contract_persistence_effect/handlers/__init__.py

@@ -0,0 +1,74 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Handlers for NodeContractPersistenceEffect operations.
+
+This package contains the handlers for the NodeContractPersistenceEffect node,
+following the declarative node pattern where PostgreSQL operations are
+encapsulated in dedicated handler classes.
+
+Available Handlers:
+    HandlerPostgresContractUpsert: Upsert contract record handler.
+    HandlerPostgresTopicUpdate: Update topic routing handler.
+    HandlerPostgresMarkStale: Batch mark stale contracts handler.
+    HandlerPostgresHeartbeat: Update heartbeat timestamp handler.
+    HandlerPostgresDeactivate: Deactivate contract handler.
+    HandlerPostgresCleanupTopics: Cleanup topic references handler.
+
+Architecture:
+    These handlers are used by NodeContractPersistenceEffect to execute
+    PostgreSQL operations based on intents from ContractRegistryReducer.
+    Each handler is responsible for:
+    - Operation timing and observability
+    - Error sanitization for security
+    - Structured result construction
+    - Retry logic per retry_policy configuration
+
+Shared Patterns:
+    All handlers share a common error handling pattern:
+    - TimeoutError/InfraTimeoutError: Returns *_TIMEOUT_ERROR code
+    - InfraAuthenticationError: Returns *_AUTH_ERROR code (non-retriable)
+    - InfraConnectionError: Returns *_CONNECTION_ERROR code (retriable)
+    - RepositoryExecutionError: Returns operation-specific error code
+    - Exception: Returns *_UNKNOWN_ERROR code
+
+    Each handler sanitizes errors via sanitize_error_message() to prevent
+    credential exposure in logs and error responses.
+
+Related:
+    - NodeContractPersistenceEffect: Parent effect node coordinating handlers
+    - ContractRegistryReducer: Source of intents
+    - OMN-1845: Implementation ticket
+    - OMN-1653: ContractRegistryReducer ticket
+"""
+
+from __future__ import annotations
+
+from omnibase_infra.nodes.node_contract_persistence_effect.handlers.handler_postgres_cleanup_topics import (
+    HandlerPostgresCleanupTopics,
+)
+from omnibase_infra.nodes.node_contract_persistence_effect.handlers.handler_postgres_contract_upsert import (
+    HandlerPostgresContractUpsert,
+)
+from omnibase_infra.nodes.node_contract_persistence_effect.handlers.handler_postgres_deactivate import (
+    HandlerPostgresDeactivate,
+)
+from omnibase_infra.nodes.node_contract_persistence_effect.handlers.handler_postgres_heartbeat import (
+    HandlerPostgresHeartbeat,
+)
+from omnibase_infra.nodes.node_contract_persistence_effect.handlers.handler_postgres_mark_stale import (
+    HandlerPostgresMarkStale,
+)
+from omnibase_infra.nodes.node_contract_persistence_effect.handlers.handler_postgres_topic_update import (
+    HandlerPostgresTopicUpdate,
+    normalize_topic_for_storage,
+)
+
+__all__: list[str] = [
+    "HandlerPostgresCleanupTopics",
+    "HandlerPostgresContractUpsert",
+    "HandlerPostgresDeactivate",
+    "HandlerPostgresHeartbeat",
+    "HandlerPostgresMarkStale",
+    "HandlerPostgresTopicUpdate",
+    "normalize_topic_for_storage",
+]

omnibase_infra/nodes/node_contract_persistence_effect/handlers/handler_postgres_cleanup_topics.py

@@ -0,0 +1,217 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Handler for PostgreSQL topic reference cleanup.
+
+This handler encapsulates PostgreSQL-specific topic cleanup logic for the
+NodeContractPersistenceEffect node, following the declarative node pattern where
+handlers are extracted for testability and separation of concerns.
+
+Architecture:
+    HandlerPostgresCleanupTopics is responsible for:
+    - Removing contract_id from topics.contract_ids JSONB arrays
+    - Returning structured ModelBackendResult
+
+    Timing, error classification, and sanitization are delegated to
+    MixinPostgresOpExecutor to eliminate boilerplate drift across handlers.
+
+    This handler removes a contract_id from the contract_ids JSONB array in
+    all topics that reference it. Topic rows are NOT deleted even when the
+    contract_ids array becomes empty.
+
+Topic Orphan Handling (OMN-1709):
+    When all contracts are removed from a topic, the topic row remains with
+    empty contract_ids array. This is intentional:
+    - Preserves topic routing history for auditing and debugging
+    - Allows topic reactivation if a new contract references the same topic
+    - Avoids complex cascading deletes during high-volume deregistration
+
+    To clean up orphaned topics, run:
+        DELETE FROM topics WHERE contract_ids = '[]' AND is_active = FALSE;
+
+Coroutine Safety:
+    This handler is stateless and coroutine-safe for concurrent calls
+    with different request instances. Thread-safety depends on the
+    underlying asyncpg.Pool implementation.
+
+Related:
+    - NodeContractPersistenceEffect: Parent effect node that coordinates handlers
+    - ModelPayloadCleanupTopicReferences: Input payload model
+    - ModelBackendResult: Structured result model for backend operations
+    - MixinPostgresOpExecutor: Shared execution core for timing/error handling
+    - OMN-1845: Implementation ticket
+    - OMN-1857: Executor extraction ticket
+    - OMN-1709: Topic orphan handling documentation
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING
+from uuid import UUID
+
+import asyncpg
+
+from omnibase_infra.enums import (
+    EnumHandlerType,
+    EnumHandlerTypeCategory,
+    EnumPostgresErrorCode,
+)
+from omnibase_infra.mixins.mixin_postgres_op_executor import MixinPostgresOpExecutor
+from omnibase_infra.models.model_backend_result import ModelBackendResult
+
+logger = logging.getLogger(__name__)
+
+if TYPE_CHECKING:
+    from omnibase_infra.nodes.contract_registry_reducer.models import (
+        ModelPayloadCleanupTopicReferences,
+    )
+
+# SQL for removing contract_id from all topic contract_ids arrays
+# Uses parameterized query: $1 = contract_id (as text)
+#
+# JSONB operators:
+#   - `contract_ids ? $1` checks if string exists as element in JSONB array
+#   - `contract_ids - $1` removes the string element from JSONB array
+#
+# Note: updated_at is handled by the trigger (trigger_topics_updated_at)
+# but we update it explicitly here for clarity and for cases where
+# the trigger might not be installed.
+SQL_CLEANUP_TOPIC_REFERENCES = """
+UPDATE topics
+SET contract_ids = contract_ids - $1,
+    updated_at = NOW()
+WHERE contract_ids ? $1
+"""
+
+
+class HandlerPostgresCleanupTopics(MixinPostgresOpExecutor):
+    """Handler for removing contract references from topics.
+
+    Encapsulates all PostgreSQL-specific topic cleanup logic extracted from
+    NodeContractPersistenceEffect for declarative node compliance.
+
+    Timing, error classification, and sanitization are handled by the
+    MixinPostgresOpExecutor base class, reducing boilerplate and ensuring
+    consistent error handling across all PostgreSQL handlers.
+
+    Important: Topic rows are NOT deleted even when contract_ids becomes empty.
+    This is intentional per OMN-1709 - orphaned topics are preserved for
+    auditing and can be cleaned up separately if needed.
+
+    Attributes:
+        _pool: asyncpg connection pool for database operations.
+
+    Example:
+        >>> import asyncpg
+        >>> pool = await asyncpg.create_pool(dsn="postgresql://...")
+        >>> handler = HandlerPostgresCleanupTopics(pool)
+        >>> result = await handler.handle(payload, correlation_id)
+        >>> result.success
+        True
+
+    See Also:
+        - NodeContractPersistenceEffect: Parent node that uses this handler
+        - ModelPayloadCleanupTopicReferences: Input payload model
+        - MixinPostgresOpExecutor: Shared execution mechanics
+    """
+
+    def __init__(self, pool: asyncpg.Pool) -> None:
+        """Initialize handler with asyncpg connection pool.
+
+        Args:
+            pool: asyncpg connection pool for executing database operations.
+        """
+        self._pool = pool
+
+    @property
+    def handler_type(self) -> EnumHandlerType:
+        """Architectural role of this handler."""
+        return EnumHandlerType.INFRA_HANDLER
+
+    @property
+    def handler_category(self) -> EnumHandlerTypeCategory:
+        """Behavioral classification of this handler."""
+        return EnumHandlerTypeCategory.EFFECT
+
+    async def handle(
+        self,
+        payload: ModelPayloadCleanupTopicReferences,
+        correlation_id: UUID,
+    ) -> ModelBackendResult:
+        """Remove contract_id from all topic contract_ids arrays.
+
+        The cleanup removes the contract_id from all topics.contract_ids
+        JSONB arrays. Topic rows are preserved even if contract_ids becomes
+        empty (per OMN-1709 topic orphan handling).
+
+        Args:
+            payload: Cleanup payload containing contract_id to remove and
+                cleaned_at timestamp.
+            correlation_id: Request correlation ID for distributed tracing.
+
+        Returns:
+            ModelBackendResult with:
+                - success: True if cleanup 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:
+            If no topics contain the contract_id, success=True is still
+            returned. This follows the idempotency principle - cleaning up
+            references for a contract that has no topic associations is
+            not an error.
+        """
+        return await self._execute_postgres_op(
+            op_error_code=EnumPostgresErrorCode.CLEANUP_ERROR,
+            correlation_id=correlation_id,
+            log_context={
+                "contract_id": payload.contract_id,
+            },
+            fn=lambda: self._execute_cleanup(payload, correlation_id),
+        )
+
+    async def _execute_cleanup(
+        self,
+        payload: ModelPayloadCleanupTopicReferences,
+        correlation_id: UUID,
+    ) -> None:
+        """Execute the topic cleanup UPDATE query.
+
+        Args:
+            payload: Cleanup payload with contract_id.
+            correlation_id: Correlation ID for logging.
+
+        Raises:
+            Any exception from asyncpg (handled by MixinPostgresOpExecutor).
+        """
+        async with self._pool.acquire() as conn:
+            # Execute the update and get the number of affected rows
+            result = await conn.execute(
+                SQL_CLEANUP_TOPIC_REFERENCES,
+                payload.contract_id,
+            )
+
+        # Parse the result to get affected row count
+        # asyncpg execute returns a string like "UPDATE N"
+        topics_updated = 0
+        if result and result.startswith("UPDATE "):
+            try:
+                topics_updated = int(result.split(" ")[1])
+            except (ValueError, IndexError):
+                pass  # Keep default of 0 if parsing fails
+
+        # Log for observability
+        logger.info(
+            "Topic cleanup operation completed",
+            extra={
+                "correlation_id": str(correlation_id),
+                "contract_id": payload.contract_id,
+                "topics_updated": topics_updated,
+            },
+        )
+
+
+__all__: list[str] = ["HandlerPostgresCleanupTopics"]

omnibase_infra/nodes/node_contract_persistence_effect/handlers/handler_postgres_contract_upsert.py

@@ -0,0 +1,242 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Handler for PostgreSQL contract record upsert.
+
+This handler encapsulates PostgreSQL-specific persistence logic for the
+NodeContractPersistenceEffect node, following the declarative node pattern where
+handlers are extracted for testability and separation of concerns.
+
+Architecture:
+    HandlerPostgresContractUpsert is responsible for:
+    - Executing upsert operations against the PostgreSQL contracts table
+    - Serializing contract_yaml dict to YAML string before INSERT
+    - Returning structured ModelBackendResult
+
+    Timing, error classification, and sanitization are delegated to
+    MixinPostgresOpExecutor to eliminate boilerplate drift across handlers.
+
+Coroutine Safety:
+    This handler is stateless and coroutine-safe for concurrent calls
+    with different payload instances. Thread-safety depends on the
+    underlying asyncpg connection pool implementation.
+
+SQL Security:
+    All SQL queries use parameterized queries with positional placeholders
+    ($1, $2, etc.) to prevent SQL injection attacks. The asyncpg library
+    handles proper escaping and type conversion for all parameters.
+
+Related:
+    - NodeContractPersistenceEffect: Parent effect node that coordinates handlers
+    - ModelPayloadUpsertContract: Input payload model
+    - ModelBackendResult: Structured result model for backend operations
+    - MixinPostgresOpExecutor: Shared execution core for timing/error handling
+    - OMN-1845: Implementation ticket
+    - OMN-1857: Executor extraction ticket
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING
+from uuid import UUID
+
+import yaml
+
+from omnibase_infra.enums import (
+    EnumHandlerType,
+    EnumHandlerTypeCategory,
+    EnumPostgresErrorCode,
+)
+from omnibase_infra.errors import ModelInfraErrorContext, RepositoryExecutionError
+from omnibase_infra.mixins.mixin_postgres_op_executor import MixinPostgresOpExecutor
+from omnibase_infra.models.model_backend_result import ModelBackendResult
+
+if TYPE_CHECKING:
+    import asyncpg
+
+    from omnibase_infra.nodes.contract_registry_reducer.models import (
+        ModelPayloadUpsertContract,
+    )
+
+logger = logging.getLogger(__name__)
+
+# SQL statement for contract upsert with ON CONFLICT for idempotency.
+# Uses RETURNING to confirm the operation was executed.
+SQL_UPSERT_CONTRACT = """
+INSERT INTO contracts (
+    contract_id, node_name, version_major, version_minor, version_patch,
+    contract_hash, contract_yaml, is_active, registered_at, last_seen_at
+) VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10)
+ON CONFLICT (contract_id) DO UPDATE SET
+    contract_hash = EXCLUDED.contract_hash,
+    contract_yaml = EXCLUDED.contract_yaml,
+    is_active = EXCLUDED.is_active,
+    last_seen_at = EXCLUDED.last_seen_at,
+    updated_at = NOW()
+RETURNING contract_id, (xmax = 0) AS was_insert;
+"""
+
+
+class HandlerPostgresContractUpsert(MixinPostgresOpExecutor):
+    """Handler for PostgreSQL contract record upsert.
+
+    Encapsulates all PostgreSQL-specific persistence logic for contract
+    record upserts.
+
+    Timing, error classification, and sanitization are handled by the
+    MixinPostgresOpExecutor base class, reducing boilerplate and ensuring
+    consistent error handling across all PostgreSQL handlers.
+
+    Attributes:
+        _pool: asyncpg connection pool for database operations.
+
+    Example:
+        >>> import asyncpg
+        >>> pool = await asyncpg.create_pool(dsn="...")
+        >>> handler = HandlerPostgresContractUpsert(pool)
+        >>> result = await handler.handle(payload, correlation_id)
+        >>> result.success
+        True
+
+    See Also:
+        - NodeContractPersistenceEffect: Parent node that uses this handler
+        - ModelPayloadUpsertContract: Input payload model
+        - MixinPostgresOpExecutor: Shared execution mechanics
+    """
+
+    def __init__(self, pool: asyncpg.Pool) -> None:
+        """Initialize handler with asyncpg connection pool.
+
+        Args:
+            pool: asyncpg connection pool for database operations.
+                The pool should be pre-configured and ready for use.
+        """
+        self._pool = pool
+
+    @property
+    def handler_type(self) -> EnumHandlerType:
+        """Architectural role of this handler."""
+        return EnumHandlerType.INFRA_HANDLER
+
+    @property
+    def handler_category(self) -> EnumHandlerTypeCategory:
+        """Behavioral classification of this handler."""
+        return EnumHandlerTypeCategory.EFFECT
+
+    async def handle(
+        self,
+        payload: ModelPayloadUpsertContract,
+        correlation_id: UUID,
+    ) -> ModelBackendResult:
+        """Execute PostgreSQL contract record upsert.
+
+        Performs the upsert operation against the contracts table with:
+        - Contract YAML serialization (dict to YAML string)
+        - Parameterized SQL for injection prevention
+
+        Args:
+            payload: Upsert contract payload containing all contract fields
+                including contract_id, node_name, version components,
+                contract_hash, contract_yaml, and timestamps.
+            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
+        """
+        return await self._execute_postgres_op(
+            op_error_code=EnumPostgresErrorCode.UPSERT_ERROR,
+            correlation_id=correlation_id,
+            log_context={
+                "contract_id": payload.contract_id,
+                "node_name": payload.node_name,
+            },
+            fn=lambda: self._execute_upsert(payload, correlation_id),
+        )
+
+    async def _execute_upsert(
+        self,
+        payload: ModelPayloadUpsertContract,
+        correlation_id: UUID,
+    ) -> None:
+        """Execute the contract upsert query.
+
+        Args:
+            payload: Contract upsert payload.
+            correlation_id: Correlation ID for logging.
+
+        Raises:
+            RepositoryExecutionError: If no result returned from upsert.
+            Any exception from asyncpg (handled by MixinPostgresOpExecutor).
+        """
+        # Serialize contract_yaml to YAML string if it's a dict
+        # The PostgreSQL column is TEXT type, so we need a string representation
+        contract_yaml_str: str
+        if isinstance(payload.contract_yaml, dict):
+            contract_yaml_str = yaml.safe_dump(
+                payload.contract_yaml,
+                default_flow_style=False,
+                sort_keys=True,
+                allow_unicode=True,
+            )
+        elif isinstance(payload.contract_yaml, str):
+            contract_yaml_str = payload.contract_yaml
+        else:
+            # Handle unexpected types by converting to string representation
+            contract_yaml_str = str(payload.contract_yaml)
+
+        async with self._pool.acquire() as conn:
+            result = await conn.fetchrow(
+                SQL_UPSERT_CONTRACT,
+                payload.contract_id,
+                payload.node_name,
+                payload.version_major,
+                payload.version_minor,
+                payload.version_patch,
+                payload.contract_hash,
+                contract_yaml_str,
+                payload.is_active,
+                payload.registered_at,
+                payload.last_seen_at,
+            )
+
+        if result is None:
+            # RETURNING clause should always return a row on success
+            # If None, something unexpected happened
+            logger.warning(
+                "Contract upsert returned no result",
+                extra={
+                    "contract_id": payload.contract_id,
+                    "correlation_id": str(correlation_id),
+                },
+            )
+            context = ModelInfraErrorContext.with_correlation(
+                correlation_id=correlation_id,
+                transport_type="db",
+                operation="contract_upsert",
+            )
+            raise RepositoryExecutionError(
+                "postgres operation failed: no result returned",
+                context=context,
+            )
+
+        # Log for observability
+        was_insert = result["was_insert"]
+        operation = "insert" if was_insert else "update"
+        logger.info(
+            "Contract upsert completed",
+            extra={
+                "contract_id": payload.contract_id,
+                "node_name": payload.node_name,
+                "operation": operation,
+                "correlation_id": str(correlation_id),
+            },
+        )
+
+
+__all__: list[str] = ["HandlerPostgresContractUpsert"]