omnibase_infra 0.2.1__py3-none-any.whl

omnibase_infra/nodes/effects/models/model_backend_result.py

@@ -0,0 +1,190 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Backend Result Model for Registry Effect Operations.
+
+This module provides ModelBackendResult, representing the result of an individual
+backend operation (Consul or PostgreSQL) within the dual-registration workflow.
+
+Architecture:
+    ModelBackendResult captures the outcome of a single backend operation:
+    - success: Whether the operation completed successfully
+    - error: Error message if the operation failed (sanitized)
+    - duration_ms: Time taken for the operation
+
+    This model is used within ModelRegistryResponse to report per-backend status,
+    enabling partial failure detection and targeted retry strategies.
+
+Security:
+    Error messages MUST be sanitized before inclusion. Never include:
+    - Credentials, connection strings, or secrets
+    - Internal IP addresses or hostnames
+    - PII (names, emails, etc.)
+
+    See CLAUDE.md "Error Sanitization Guidelines" for complete rules.
+
+Related:
+    - ModelRegistryResponse: Uses this model for consul_result and postgres_result
+    - NodeRegistryEffect: Effect node that produces these results
+    - OMN-954: Partial failure scenario testing
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+from uuid import UUID
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+# Compiled regex for secret pattern detection (module-level for performance)
+# Used by ModelBackendResult._warn_on_potential_secrets validator
+_SECRET_PATTERNS: re.Pattern[str] = re.compile(
+    r"(password\s*=|api_key\s*=|token\s*=|secret\s*=|credentials|"
+    r"connection_string\s*=.*@)",
+    re.IGNORECASE,
+)
+
+_logger = logging.getLogger(__name__)
+
+
+class ModelBackendResult(BaseModel):
+    """Result of an individual backend operation.
+
+    Captures the outcome of a single backend operation (Consul or PostgreSQL)
+    within the dual-registration workflow. Used to enable partial failure
+    detection and targeted retry strategies.
+
+    Immutability:
+        This model uses frozen=True to ensure backend results are immutable
+        once created, supporting safe concurrent access and comparison.
+
+    Attributes:
+        success: Whether the backend operation completed successfully.
+        error: Sanitized error message if success is False.
+        error_code: Optional error code for programmatic handling.
+        duration_ms: Time taken for the operation in milliseconds.
+        backend_id: Optional identifier for the backend instance.
+
+    Design Note - No ``retries`` Field:
+        This model intentionally does NOT include a ``retries`` field because:
+
+        1. **Effect layer dispatches once**: The effect node dispatches to handlers
+           exactly once per operation. It does not implement retry loops.
+        2. **Handlers own retry logic**: Handlers implement their own retry behavior
+           using the ``retry_policy`` configuration from the contract. Retry count
+           is internal handler state, not exposed in results.
+        3. **Caller-controlled retries**: Callers can use the ``retry_partial_failure``
+           operation for explicit retries after partial failures.
+
+        **Important**: At the effect layer, a ``retries`` field would always be 0.
+        Retry counts are only meaningful when aggregated by the orchestrator layer,
+        which tracks how many times ``retry_partial_failure`` was called.
+
+        For observability of retry attempts:
+        - Handlers should emit metrics/logs during internal retry loops
+        - Use ``correlation_id`` to correlate retry attempts across logs
+        - Orchestrator layer can track ``retry_partial_failure`` operation calls
+
+        See: ``contract.yaml`` error_handling.retry_policy for handler configuration.
+
+    Example:
+        >>> result = ModelBackendResult(
+        ...     success=True,
+        ...     duration_ms=45.2,
+        ...     backend_id="consul",
+        ... )
+        >>> result.success
+        True
+
+    Example (failure case):
+        >>> result = ModelBackendResult(
+        ...     success=False,
+        ...     error="Connection refused to database host",
+        ...     error_code="DATABASE_CONNECTION_ERROR",
+        ...     duration_ms=5000.0,
+        ...     backend_id="postgres",
+        ... )
+        >>> result.success
+        False
+        >>> result.error
+        'Connection refused to database host'
+    """
+
+    model_config = ConfigDict(frozen=True, extra="forbid", from_attributes=True)
+
+    success: bool = Field(
+        ...,
+        description="Whether the backend operation completed successfully",
+    )
+    error: str | None = Field(
+        default=None,
+        description="Sanitized error message if success is False",
+    )
+    error_code: str | None = Field(
+        default=None,
+        description="Error code for programmatic handling (e.g., DATABASE_CONNECTION_ERROR)",
+    )
+    duration_ms: float = Field(
+        default=0.0,
+        description="Time taken for the operation in milliseconds",
+        ge=0.0,
+    )
+    backend_id: str | None = Field(
+        default=None,
+        description="Optional identifier for the backend instance",
+    )
+    correlation_id: UUID | None = Field(
+        default=None,
+        description="Correlation ID for tracing the operation",
+    )
+
+    @field_validator("error", mode="after")
+    @classmethod
+    def _warn_on_potential_secrets(cls, value: str | None) -> str | None:
+        """Defense-in-depth validator to detect potential secret exposure in error messages.
+
+        This validator checks if the error string contains common patterns that might
+        indicate accidental secret exposure. It logs a warning if detected but does NOT
+        block or modify the value - this is defense-in-depth, not enforcement.
+
+        The actual sanitization should happen at the error source (see CLAUDE.md
+        "Error Sanitization Guidelines"). This validator serves as a safety net
+        to detect when sanitization was missed.
+
+        Detected Patterns:
+            - password= (case insensitive)
+            - api_key= (case insensitive)
+            - token= (case insensitive)
+            - secret= (case insensitive)
+            - credentials (case insensitive)
+            - connection_string=...@ (indicates embedded credentials)
+
+        Args:
+            value: The error string to check, or None.
+
+        Returns:
+            The original value unchanged.
+
+        Security:
+            This validator intentionally does NOT raise an exception or modify
+            the value. It only logs a warning to alert operators that a potential
+            secret may have been exposed. The rationale:
+            1. Blocking could cause unexpected runtime failures
+            2. Modification could mask debugging information
+            3. Warning provides observability without breaking functionality
+        """
+        if value is None:
+            return value
+
+        if _SECRET_PATTERNS.search(value):
+            _logger.warning(
+                "Potential secret pattern detected in error message. "
+                "Error messages should be sanitized at the source. "
+                "See CLAUDE.md 'Error Sanitization Guidelines' for rules. "
+                "Pattern detected in error field of ModelBackendResult."
+            )
+
+        return value
+
+
+__all__ = ["ModelBackendResult"]

omnibase_infra/nodes/effects/models/model_effect_idempotency_config.py

@@ -0,0 +1,92 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Configuration model for Effect layer idempotency store.
+
+This module provides configuration for the in-memory idempotency store used
+by Effect nodes to track completed backends during dual-backend operations.
+
+Memory Characteristics:
+    The default configuration limits memory usage:
+    - max_cache_size=10000 entries
+    - Each entry: ~100 bytes (UUID key + set of backend strings + timestamp)
+    - Max memory at default: ~1MB
+
+    For high-volume systems, adjust based on:
+    - Expected concurrent correlation IDs
+    - Backend completion tracking duration (TTL)
+    - Available memory headroom
+
+Production Note:
+    This in-memory store does NOT persist across restarts and does NOT
+    support distributed scenarios. For production use:
+    - Use StoreIdempotencyPostgres from omnibase_infra.idempotency
+    - Or implement a Redis/Valkey-backed store
+    - Consider the existing ProtocolIdempotencyStore for full persistence
+
+Related:
+    - NodeRegistryEffect: Uses this for dual-backend idempotency
+    - InMemoryEffectIdempotencyStore: Implementation using this config
+    - OMN-954: Registry effect idempotency requirements
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class ModelEffectIdempotencyConfig(BaseModel):
+    """Configuration for Effect layer in-memory idempotency store.
+
+    This configuration controls the bounded in-memory cache used for tracking
+    completed backends during dual-backend registration operations.
+
+    Attributes:
+        max_cache_size: Maximum number of correlation IDs to track.
+            When exceeded, oldest entries are evicted (LRU).
+            Default: 10000 entries (~1MB memory).
+        cache_ttl_seconds: Time-to-live for entries in seconds.
+            Entries older than TTL are eligible for cleanup.
+            Default: 3600.0 (1 hour).
+        cleanup_interval_seconds: How often to run TTL cleanup.
+            Cleanup happens lazily on access, but this sets the minimum
+            interval between full cleanup passes.
+            Default: 300.0 (5 minutes).
+
+    Memory Estimation:
+        - Per-entry overhead: ~100 bytes
+        - max_cache_size=10000 -> ~1MB
+        - max_cache_size=100000 -> ~10MB
+
+    Example:
+        >>> config = ModelEffectIdempotencyConfig(
+        ...     max_cache_size=5000,
+        ...     cache_ttl_seconds=1800.0,  # 30 minutes
+        ... )
+        >>> store = InMemoryEffectIdempotencyStore(config)
+    """
+
+    max_cache_size: int = Field(
+        default=10000,
+        ge=1,
+        le=1000000,
+        description="Maximum entries before LRU eviction.",
+    )
+
+    cache_ttl_seconds: float = Field(
+        default=3600.0,
+        ge=1.0,
+        le=86400.0,
+        description="Entry TTL in seconds (1 hour default).",
+    )
+
+    cleanup_interval_seconds: float = Field(
+        default=300.0,
+        ge=1.0,
+        le=3600.0,
+        description="Minimum interval between TTL cleanup passes.",
+    )
+
+    model_config = ConfigDict(frozen=True, extra="forbid", from_attributes=True)
+
+
+__all__ = ["ModelEffectIdempotencyConfig"]

omnibase_infra/nodes/effects/models/model_registry_request.py

@@ -0,0 +1,132 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Registry Request Model for Registry Effect Operations.
+
+This module provides ModelRegistryRequest, representing the input to the
+NodeRegistryEffect node for dual-backend registration operations.
+
+Architecture:
+    ModelRegistryRequest captures all information needed to register a node
+    in both Consul and PostgreSQL backends:
+    - Node identity (node_id, node_type, node_version)
+    - Service discovery info (endpoints, health checks)
+    - Metadata for registration record
+
+    This model is typically created from a ModelNodeIntrospectionEvent
+    or directly constructed for programmatic registration.
+
+Related:
+    - NodeRegistryEffect: Effect node that consumes this request
+    - ModelRegistryResponse: Response model for registry operations
+    - ModelNodeIntrospectionEvent: Source of registration data
+    - OMN-954: Partial failure scenario testing
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from uuid import UUID, uuid4
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+from omnibase_core.enums import EnumNodeKind
+from omnibase_core.models.primitives import ModelSemVer
+from omnibase_infra.utils import validate_timezone_aware_datetime
+
+
+class ModelRegistryRequest(BaseModel):
+    """Request model for dual-backend registration operations.
+
+    Contains all information needed to register a node in both Consul
+    and PostgreSQL backends. The NodeRegistryEffect uses this request to
+    execute parallel or sequential registration operations.
+
+    Immutability:
+        This model uses frozen=True to ensure requests are immutable
+        once created, enabling safe concurrent access.
+
+    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.
+        correlation_id: Correlation ID for distributed tracing.
+        service_name: Name for service discovery registration.
+        endpoints: Dict of endpoint type to URL (e.g., {"health": "http://..."}).
+        tags: List of tags for service discovery.
+        metadata: Additional metadata for the registration record.
+        health_check_config: Optional health check configuration for Consul.
+        timestamp: When this request was created.
+
+    Example:
+        >>> from datetime import UTC, datetime
+        >>> from uuid import uuid4
+        >>> from omnibase_core.enums.enum_node_kind import EnumNodeKind
+        >>> from omnibase_core.models.primitives.model_semver import ModelSemVer
+        >>> request = ModelRegistryRequest(
+        ...     node_id=uuid4(),
+        ...     node_type=EnumNodeKind.EFFECT,
+        ...     node_version=ModelSemVer(major=1, minor=0, patch=0),
+        ...     correlation_id=uuid4(),
+        ...     service_name="onex-effect",
+        ...     endpoints={"health": "http://localhost:8080/health"},
+        ...     timestamp=datetime(2025, 1, 15, 12, 0, 0, tzinfo=UTC),
+        ... )
+        >>> request.node_type
+        <EnumNodeKind.EFFECT: 'effect'>
+    """
+
+    model_config = ConfigDict(frozen=True, extra="forbid", from_attributes=True)
+
+    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: ModelSemVer = Field(
+        ...,
+        description="Semantic version of the node",
+    )
+    correlation_id: UUID = Field(
+        default_factory=uuid4,
+        description="Correlation ID for distributed tracing",
+    )
+    service_name: str | None = Field(
+        default=None,
+        description="Name for service discovery registration",
+    )
+    endpoints: dict[str, str] = Field(
+        default_factory=dict,
+        description="Dict of endpoint type to URL",
+    )
+    tags: list[str] = Field(
+        default_factory=list,
+        description="List of tags for service discovery",
+    )
+    metadata: dict[str, str] = Field(
+        default_factory=dict,
+        description="Additional metadata for the registration record",
+    )
+    health_check_config: dict[str, str] | None = Field(
+        default=None,
+        description="Optional health check configuration for Consul",
+    )
+    # Timestamps - MUST be explicitly injected (no default_factory for testability)
+    timestamp: datetime = Field(
+        ...,
+        description="When this request was created (must be explicitly provided)",
+    )
+
+    @field_validator("timestamp")
+    @classmethod
+    def validate_timestamp_timezone_aware(cls, v: datetime) -> datetime:
+        """Validate that timestamp is timezone-aware.
+
+        Delegates to shared utility for consistent validation across all models.
+        """
+        return validate_timezone_aware_datetime(v)
+
+
+__all__ = ["ModelRegistryRequest"]

omnibase_infra/nodes/effects/models/model_registry_response.py

@@ -0,0 +1,263 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Registry Response Model for Dual-Backend Registration Operations.
+
+This module provides ModelRegistryResponse, representing the complete response
+from the NodeRegistryEffect node after executing dual-backend registration.
+
+Architecture:
+    ModelRegistryResponse captures the outcome of registering a node in both
+    Consul and PostgreSQL backends, with support for partial failure scenarios:
+
+    - status=EnumRegistryResponseStatus.SUCCESS: Both backends succeeded
+    - status=EnumRegistryResponseStatus.PARTIAL: One backend succeeded, one failed
+    - status=EnumRegistryResponseStatus.FAILED: Both backends failed
+
+    Each backend's individual result is captured in consul_result and
+    postgres_result fields, enabling targeted retry strategies.
+
+Partial Failure Handling:
+    When one backend fails but the other succeeds:
+    1. Status is set to EnumRegistryResponseStatus.PARTIAL
+    2. The successful backend's result shows success=True
+    3. The failed backend's result shows success=False with error details
+    4. Retry logic can target only the failed backend
+
+    This supports idempotent retry: if Consul already succeeded, only
+    PostgreSQL needs to be retried on subsequent attempts.
+
+Related:
+    - ModelBackendResult: Individual backend operation result
+    - NodeRegistryEffect: Effect node that produces this response
+    - ModelRegistryRequest: Input request model
+    - OMN-954: Partial failure scenario testing
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from uuid import UUID
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from omnibase_infra.enums import EnumBackendType, EnumRegistryResponseStatus
+from omnibase_infra.nodes.effects.models.model_backend_result import (
+    ModelBackendResult,
+)
+
+
+class ModelRegistryResponse(BaseModel):
+    """Response model for dual-backend registration operations.
+
+    Captures the complete outcome of registering a node in both Consul
+    and PostgreSQL backends, with individual results for each backend.
+
+    Status Semantics:
+        - SUCCESS: Both consul_result.success AND postgres_result.success are True
+        - PARTIAL: Exactly one of consul_result.success or postgres_result.success is True
+        - FAILED: Both consul_result.success AND postgres_result.success are False
+
+    Immutability:
+        This model uses frozen=True to ensure responses are immutable
+        once created, supporting safe concurrent access and comparison.
+
+    Attributes:
+        status: Overall status of the dual-registration operation.
+        node_id: UUID of the node that was registered.
+        correlation_id: Correlation ID for distributed tracing.
+        consul_result: Result of the Consul registration operation.
+        postgres_result: Result of the PostgreSQL upsert operation.
+        processing_time_ms: Total time for the dual-registration operation.
+        timestamp: When this response was created.
+        error_summary: Aggregated error message for failed operations.
+
+    Example (success):
+        >>> from uuid import uuid4
+        >>> from omnibase_infra.enums import EnumRegistryResponseStatus
+        >>> response = ModelRegistryResponse(
+        ...     status=EnumRegistryResponseStatus.SUCCESS,
+        ...     node_id=uuid4(),
+        ...     correlation_id=uuid4(),
+        ...     consul_result=ModelBackendResult(
+        ...         success=True, duration_ms=45.0, backend_id="consul"
+        ...     ),
+        ...     postgres_result=ModelBackendResult(
+        ...         success=True, duration_ms=30.0, backend_id="postgres"
+        ...     ),
+        ...     processing_time_ms=75.0,
+        ... )
+        >>> response.status == EnumRegistryResponseStatus.SUCCESS
+        True
+
+    Example (partial failure):
+        >>> response = ModelRegistryResponse(
+        ...     status=EnumRegistryResponseStatus.PARTIAL,
+        ...     node_id=uuid4(),
+        ...     correlation_id=uuid4(),
+        ...     consul_result=ModelBackendResult(
+        ...         success=True, duration_ms=45.0, backend_id="consul"
+        ...     ),
+        ...     postgres_result=ModelBackendResult(
+        ...         success=False,
+        ...         error="Connection refused",
+        ...         duration_ms=5000.0,
+        ...         backend_id="postgres",
+        ...     ),
+        ...     processing_time_ms=5045.0,
+        ...     error_summary="PostgreSQL: Connection refused",
+        ... )
+        >>> response.status == EnumRegistryResponseStatus.PARTIAL
+        True
+        >>> response.consul_result.success
+        True
+        >>> response.postgres_result.success
+        False
+    """
+
+    model_config = ConfigDict(frozen=True, extra="forbid", from_attributes=True)
+
+    status: EnumRegistryResponseStatus = Field(
+        ...,
+        description="Overall status: success, partial, or failed",
+    )
+    node_id: UUID = Field(
+        ...,
+        description="UUID of the node that was registered",
+    )
+    correlation_id: UUID = Field(
+        ...,
+        description="Correlation ID for distributed tracing",
+    )
+    consul_result: ModelBackendResult = Field(
+        ...,
+        description="Result of the Consul registration operation",
+    )
+    postgres_result: ModelBackendResult = Field(
+        ...,
+        description="Result of the PostgreSQL upsert operation",
+    )
+    processing_time_ms: float = Field(
+        default=0.0,
+        description="Total time for the dual-registration operation in milliseconds",
+        ge=0.0,
+    )
+    # Timestamps - MUST be explicitly injected (no default_factory for testability)
+    timestamp: datetime = Field(
+        ...,
+        description="When this response was created (must be explicitly provided)",
+    )
+    error_summary: str | None = Field(
+        default=None,
+        description="Aggregated error message for failed operations",
+    )
+
+    @classmethod
+    def from_backend_results(
+        cls,
+        node_id: UUID,
+        correlation_id: UUID,
+        consul_result: ModelBackendResult,
+        postgres_result: ModelBackendResult,
+        timestamp: datetime,
+    ) -> ModelRegistryResponse:
+        """Create a response from individual backend results.
+
+        Automatically determines the status based on backend success flags:
+        - Both success -> SUCCESS
+        - One success, one failure -> PARTIAL
+        - Both failure -> FAILED
+
+        Processing time is calculated from the sum of backend durations.
+
+        Args:
+            node_id: UUID of the registered node.
+            correlation_id: Correlation ID for tracing.
+            consul_result: Result from Consul registration.
+            postgres_result: Result from PostgreSQL upsert.
+            timestamp: When this response was created (must be explicitly provided).
+
+        Returns:
+            ModelRegistryResponse with computed status, processing_time, and error_summary.
+        """
+        # Determine status based on backend results
+        if consul_result.success and postgres_result.success:
+            status = EnumRegistryResponseStatus.SUCCESS
+        elif consul_result.success or postgres_result.success:
+            status = EnumRegistryResponseStatus.PARTIAL
+        else:
+            status = EnumRegistryResponseStatus.FAILED
+
+        # Calculate processing time from backend durations
+        processing_time_ms = consul_result.duration_ms + postgres_result.duration_ms
+
+        # Build error summary from failed backends
+        errors: list[str] = []
+        if not consul_result.success and consul_result.error:
+            errors.append(f"Consul: {consul_result.error}")
+        if not postgres_result.success and postgres_result.error:
+            errors.append(f"PostgreSQL: {postgres_result.error}")
+        error_summary = "; ".join(errors) if errors else None
+
+        return cls(
+            status=status,
+            node_id=node_id,
+            correlation_id=correlation_id,
+            consul_result=consul_result,
+            postgres_result=postgres_result,
+            processing_time_ms=processing_time_ms,
+            timestamp=timestamp,
+            error_summary=error_summary,
+        )
+
+    def is_complete_success(self) -> bool:
+        """Check if both backends succeeded.
+
+        Returns:
+            True if status is SUCCESS, False otherwise.
+        """
+        return self.status == EnumRegistryResponseStatus.SUCCESS
+
+    def is_partial_failure(self) -> bool:
+        """Check if exactly one backend failed.
+
+        Returns:
+            True if status is PARTIAL, False otherwise.
+        """
+        return self.status == EnumRegistryResponseStatus.PARTIAL
+
+    def is_complete_failure(self) -> bool:
+        """Check if both backends failed.
+
+        Returns:
+            True if status is FAILED, False otherwise.
+        """
+        return self.status == EnumRegistryResponseStatus.FAILED
+
+    def get_failed_backends(self) -> list[str]:
+        """Get list of backends that failed.
+
+        Returns:
+            List of backend names that failed ("consul", "postgres").
+        """
+        failed: list[str] = []
+        if not self.consul_result.success:
+            failed.append(EnumBackendType.CONSUL.value)
+        if not self.postgres_result.success:
+            failed.append(EnumBackendType.POSTGRES.value)
+        return failed
+
+    def get_successful_backends(self) -> list[str]:
+        """Get list of backends that succeeded.
+
+        Returns:
+            List of backend names that succeeded ("consul", "postgres").
+        """
+        succeeded: list[str] = []
+        if self.consul_result.success:
+            succeeded.append(EnumBackendType.CONSUL.value)
+        if self.postgres_result.success:
+            succeeded.append(EnumBackendType.POSTGRES.value)
+        return succeeded
+
+
+__all__ = ["ModelRegistryResponse"]