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

omnibase_infra/nodes/node_contract_persistence_effect/handlers/handler_postgres_topic_update.py

@@ -0,0 +1,298 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Handler for PostgreSQL topic routing table updates.
+
+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:
+    HandlerPostgresTopicUpdate is responsible for:
+    - Normalizing topic suffixes (stripping environment prefixes)
+    - Executing upsert operations against the PostgreSQL topics table
+    - Managing JSONB array of contract_ids for topic-to-contract mapping
+    - Returning structured ModelBackendResult
+
+    Timing, error classification, and sanitization are delegated to
+    MixinPostgresOpExecutor to eliminate boilerplate drift across handlers.
+
+Topic Normalization:
+    Topics in contracts may include environment placeholders (e.g., "{env}.topic.name")
+    or actual environment prefixes (e.g., "dev.topic.name"). Before storage, these
+    prefixes are stripped to store only the topic suffix. This enables:
+    - Environment-agnostic topic routing queries
+    - Consistent topic identity across environments
+    - Simplified topic discovery and management
+
+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
+    - ModelPayloadUpdateTopic: 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
+
+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 (
+        ModelPayloadUpdateTopic,
+    )
+
+logger = logging.getLogger(__name__)
+
+# Known environment prefixes to strip from topic suffixes before storage.
+# The placeholder prefix is checked first, then actual environment prefixes.
+_ENVIRONMENT_PREFIXES: tuple[str, ...] = (
+    "{env}.",  # Placeholder prefix (most common)
+    "dev.",
+    "prod.",
+    "staging.",
+    "local.",
+    "test.",
+)
+
+# SQL statement for topic upsert with JSONB array merge.
+# Uses ON CONFLICT to handle existing topic+direction combinations.
+# The JSONB containment operator (?) checks if contract_id already exists in array.
+# If not present, appends to array; otherwise keeps existing array unchanged.
+SQL_UPSERT_TOPIC = """
+INSERT INTO topics (topic_suffix, direction, contract_ids, first_seen_at, last_seen_at, is_active)
+VALUES ($1, $2, jsonb_build_array($3), $4, $5, TRUE)
+ON CONFLICT (topic_suffix, direction) DO UPDATE SET
+    contract_ids = CASE
+        WHEN NOT topics.contract_ids ? $3
+        THEN topics.contract_ids || to_jsonb($3::text)
+        ELSE topics.contract_ids
+    END,
+    last_seen_at = EXCLUDED.last_seen_at,
+    is_active = TRUE,
+    updated_at = NOW()
+RETURNING topic_suffix, direction, contract_ids;
+"""
+
+
+def normalize_topic_for_storage(topic: str) -> str:
+    """Strip environment placeholder/prefix from topic before storage.
+
+    Topics in contracts may include environment placeholders like "{env}." or
+    actual environment prefixes like "dev.", "prod.", etc. This function
+    normalizes topics by stripping these prefixes to store only the topic suffix.
+
+    The normalization enables environment-agnostic topic routing queries and
+    consistent topic identity across different deployment environments.
+
+    Args:
+        topic: The topic string to normalize, potentially with an environment
+            prefix (e.g., "{env}.onex.evt.platform.contract-registered.v1" or
+            "dev.onex.evt.platform.contract-registered.v1").
+
+    Returns:
+        The normalized topic suffix without environment prefix
+        (e.g., "onex.evt.platform.contract-registered.v1").
+
+    Examples:
+        >>> normalize_topic_for_storage("{env}.onex.evt.platform.contract-registered.v1")
+        'onex.evt.platform.contract-registered.v1'
+
+        >>> normalize_topic_for_storage("dev.onex.evt.platform.contract-registered.v1")
+        'onex.evt.platform.contract-registered.v1'
+
+        >>> normalize_topic_for_storage("onex.evt.platform.contract-registered.v1")
+        'onex.evt.platform.contract-registered.v1'
+    """
+    for prefix in _ENVIRONMENT_PREFIXES:
+        if topic.startswith(prefix):
+            return topic[len(prefix) :]
+    return topic
+
+
+class HandlerPostgresTopicUpdate(MixinPostgresOpExecutor):
+    """Handler for PostgreSQL topic routing table updates.
+
+    Encapsulates all PostgreSQL-specific persistence logic for topic
+    routing updates.
+
+    Timing, error classification, and sanitization are handled by the
+    MixinPostgresOpExecutor base class, reducing boilerplate and ensuring
+    consistent error handling across all PostgreSQL handlers.
+
+    Topic Contract Mapping:
+        The topics table stores a JSONB array of contract_ids that reference
+        each topic. This handler uses JSONB operations to safely add contracts
+        to the array without duplicates:
+        - If contract_id not in array: append to array
+        - If contract_id already in array: keep array unchanged
+
+    Attributes:
+        _pool: asyncpg connection pool for database operations.
+
+    Example:
+        >>> import asyncpg
+        >>> pool = await asyncpg.create_pool(dsn="...")
+        >>> handler = HandlerPostgresTopicUpdate(pool)
+        >>> result = await handler.handle(payload, correlation_id)
+        >>> result.success
+        True
+
+    See Also:
+        - NodeContractPersistenceEffect: Parent node that uses this handler
+        - ModelPayloadUpdateTopic: Input payload model
+        - normalize_topic_for_storage: Topic normalization function
+        - 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: ModelPayloadUpdateTopic,
+        correlation_id: UUID,
+    ) -> ModelBackendResult:
+        """Execute PostgreSQL topic routing table update.
+
+        Performs the upsert operation against the topics table with:
+        - Topic suffix normalization (strip environment prefix)
+        - JSONB array merge for contract_ids
+        - Parameterized SQL for injection prevention
+
+        Args:
+            payload: Update topic payload containing topic_suffix, direction,
+                contract_id, and last_seen_at timestamp.
+            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:
+            Topic suffixes are normalized before storage - environment
+            prefixes like "{env}." or "dev." are stripped.
+        """
+        # Normalize topic suffix by stripping environment prefix
+        normalized_topic = normalize_topic_for_storage(payload.topic_suffix)
+
+        return await self._execute_postgres_op(
+            op_error_code=EnumPostgresErrorCode.TOPIC_UPDATE_ERROR,
+            correlation_id=correlation_id,
+            log_context={
+                "topic_suffix": normalized_topic,
+                "original_topic": payload.topic_suffix,
+                "direction": payload.direction,
+                "contract_id": payload.contract_id,
+            },
+            fn=lambda: self._execute_topic_update(
+                payload, normalized_topic, correlation_id
+            ),
+        )
+
+    async def _execute_topic_update(
+        self,
+        payload: ModelPayloadUpdateTopic,
+        normalized_topic: str,
+        correlation_id: UUID,
+    ) -> None:
+        """Execute the topic upsert query.
+
+        Args:
+            payload: Topic update payload.
+            normalized_topic: Environment-stripped topic suffix.
+            correlation_id: Correlation ID for logging.
+
+        Raises:
+            RepositoryExecutionError: If no result returned from upsert.
+            Any exception from asyncpg (handled by MixinPostgresOpExecutor).
+        """
+        async with self._pool.acquire() as conn:
+            result = await conn.fetchrow(
+                SQL_UPSERT_TOPIC,
+                normalized_topic,
+                payload.direction,
+                payload.contract_id,
+                payload.last_seen_at,  # first_seen_at (on insert)
+                payload.last_seen_at,  # last_seen_at
+            )
+
+        if result is None:
+            # RETURNING clause should always return a row on success
+            # If None, something unexpected happened
+            logger.warning(
+                "Topic update returned no result",
+                extra={
+                    "topic_suffix": normalized_topic,
+                    "direction": payload.direction,
+                    "correlation_id": str(correlation_id),
+                },
+            )
+            context = ModelInfraErrorContext.with_correlation(
+                correlation_id=correlation_id,
+                transport_type="db",
+                operation="topic_update",
+            )
+            raise RepositoryExecutionError(
+                "postgres operation failed: no result returned",
+                context=context,
+            )
+
+        # Log for observability
+        logger.info(
+            "Topic update completed",
+            extra={
+                "topic_suffix": normalized_topic,
+                "original_topic": payload.topic_suffix,
+                "direction": payload.direction,
+                "contract_id": payload.contract_id,
+                "correlation_id": str(correlation_id),
+            },
+        )
+
+
+__all__: list[str] = ["HandlerPostgresTopicUpdate", "normalize_topic_for_storage"]

omnibase_infra/nodes/node_contract_persistence_effect/models/__init__.py

@@ -0,0 +1,15 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Models for NodeContractPersistenceEffect.
+
+Related:
+    - OMN-1845: NodeContractPersistenceEffect implementation
+"""
+
+from __future__ import annotations
+
+from omnibase_infra.nodes.node_contract_persistence_effect.models.model_persistence_result import (
+    ModelPersistenceResult,
+)
+
+__all__ = ["ModelPersistenceResult"]

omnibase_infra/nodes/node_contract_persistence_effect/models/model_persistence_result.py

@@ -0,0 +1,52 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Persistence result model for NodeContractPersistenceEffect.
+
+Related:
+    - OMN-1845: NodeContractPersistenceEffect implementation
+"""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime
+from uuid import UUID
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from omnibase_infra.enums import EnumPostgresErrorCode
+
+
+class ModelPersistenceResult(BaseModel):
+    """Result of a contract persistence operation.
+
+    Attributes:
+        success: Whether the operation succeeded.
+        error: Error message if operation failed (sanitized).
+        error_code: Typed error code for programmatic handling. Uses
+            EnumPostgresErrorCode for strong typing and validation.
+        duration_ms: Operation duration in milliseconds.
+        correlation_id: Correlation ID for distributed tracing.
+        rows_affected: Number of database rows affected.
+        timestamp: When the operation completed.
+    """
+
+    model_config = ConfigDict(frozen=True, extra="forbid", from_attributes=True)
+
+    success: bool = Field(..., description="Whether the operation succeeded.")
+    error: str | None = Field(default=None, description="Sanitized error message.")
+    error_code: EnumPostgresErrorCode | None = Field(
+        default=None,
+        description="Typed error code for programmatic handling.",
+    )
+    duration_ms: float = Field(default=0.0, description="Operation duration in ms.")
+    correlation_id: UUID | None = Field(
+        default=None, description="Correlation ID for tracing."
+    )
+    rows_affected: int = Field(default=0, description="Database rows affected.")
+    timestamp: datetime = Field(
+        default_factory=lambda: datetime.now(UTC),
+        description="Operation completion time.",
+    )
+
+
+__all__ = ["ModelPersistenceResult"]

omnibase_infra/nodes/node_contract_persistence_effect/node.py

@@ -0,0 +1,114 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Node Contract Persistence Effect - Declarative effect node for contract registry persistence.
+
+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 intent from ContractRegistryReducer (ModelIntent with typed payload)
+    2. Route to appropriate handler based on payload.intent_type (handler_routing)
+    3. Execute PostgreSQL I/O via handler
+    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
+    - Container DI: Backend adapters resolved via container, not setter methods
+
+Supported Intent Types (from ContractRegistryReducer):
+    - postgres.upsert_contract: Insert/update contract record
+    - postgres.update_topic: Update topic routing table
+    - postgres.mark_stale: Batch mark contracts as stale
+    - postgres.update_heartbeat: Update last_seen_at timestamp
+    - postgres.deactivate_contract: Mark contract as inactive (soft delete)
+    - postgres.cleanup_topic_references: Remove contract from topic arrays
+
+Node Responsibilities:
+    - Route intents to appropriate PostgreSQL handlers
+    - Delegate all execution to handlers via base class
+    - NO custom logic - pure declarative shell
+
+Related Modules:
+    - contract.yaml: Handler routing and I/O model definitions
+    - handlers/: PostgreSQL operation handlers
+    - contract_registry_reducer/: Source of intents
+    - models/model_payload_*.py: Intent payload types
+
+Related Tickets:
+    - OMN-1845: NodeContractPersistenceEffect implementation
+    - OMN-1653: ContractRegistryReducer (source of intents)
+"""
+
+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
+
+
+class NodeContractPersistenceEffect(NodeEffect):
+    """Declarative effect node for contract registry persistence.
+
+    This effect node is a lightweight shell that routes intents from
+    ContractRegistryReducer to PostgreSQL handlers. All routing and
+    execution logic is driven by contract.yaml - this class contains
+    NO custom routing code.
+
+    Supported Intent Types:
+        - postgres.upsert_contract: Upsert contract record
+        - postgres.update_topic: Update topic routing table
+        - postgres.mark_stale: Batch mark stale contracts
+        - postgres.update_heartbeat: Update heartbeat timestamp
+        - postgres.deactivate_contract: Soft delete contract
+        - postgres.cleanup_topic_references: Remove contract from topics
+
+    Args:
+        container: ONEX dependency injection container.
+
+    Dependency Injection:
+        Backend adapters (PostgreSQL) are resolved via container.
+        Handlers receive their dependencies directly via constructor injection.
+        This node contains NO instance variables for backend clients.
+
+    Example:
+        ```python
+        from omnibase_core.models.container import ModelONEXContainer
+        from omnibase_infra.nodes.node_contract_persistence_effect import (
+            NodeContractPersistenceEffect,
+        )
+
+        # Create effect node via container
+        container = ModelONEXContainer()
+        effect = NodeContractPersistenceEffect(container)
+
+        # Handlers receive dependencies directly via constructor
+        postgres_adapter = container.resolve(ProtocolPostgresAdapter)
+        upsert_handler = HandlerPostgresContractUpsert(postgres_adapter)
+
+        # Execute handler with intent payload
+        result = await upsert_handler.handle(intent_payload)
+        ```
+    """
+
+    def __init__(self, container: ModelONEXContainer) -> None:
+        """Initialize effect node with container dependency injection.
+
+        Args:
+            container: ONEX dependency injection container.
+        """
+        super().__init__(container)
+
+
+__all__ = ["NodeContractPersistenceEffect"]

omnibase_infra/nodes/node_contract_persistence_effect/registry/__init__.py

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