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

omnibase_infra/mixins/mixin_postgres_op_executor.py

@@ -0,0 +1,298 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Shared execution core for PostgreSQL operation handlers.
+
+This mixin centralizes the mechanical aspects of PostgreSQL handler execution:
+- Timing via time.perf_counter()
+- Error classification and sanitization
+- ModelBackendResult construction
+- Structured logging with correlation IDs
+
+By extracting this boilerplate into a reusable mixin, handlers are reduced from
+~200 lines to ~30 lines, eliminating drift risk where error handling patterns
+could diverge across handlers.
+
+Architecture:
+    Handlers inherit from MixinPostgresOpExecutor and call _execute_postgres_op()
+    with their operation-specific logic wrapped in a callable. The mixin handles
+    all timing, error classification, sanitization, and result construction.
+
+Error Classification:
+    - TimeoutError, InfraTimeoutError → POSTGRES_TIMEOUT_ERROR (retriable)
+    - InfraAuthenticationError → POSTGRES_AUTH_ERROR (non-retriable)
+    - InfraConnectionError → POSTGRES_CONNECTION_ERROR (retriable)
+    - RepositoryExecutionError → op_error_code (handler-specified)
+    - Exception → POSTGRES_UNKNOWN_ERROR (non-retriable)
+
+Usage:
+    ```python
+    class HandlerPostgresHeartbeat(MixinPostgresOpExecutor):
+        async def handle(self, payload, correlation_id) -> ModelBackendResult:
+            return await self._execute_postgres_op(
+                op_error_code=EnumPostgresErrorCode.HEARTBEAT_ERROR,
+                correlation_id=correlation_id,
+                log_context={"contract_id": payload.contract_id},
+                fn=lambda: self._do_heartbeat(payload),
+            )
+    ```
+
+Related:
+    - EnumPostgresErrorCode: Error code enumeration with retriability metadata
+    - MixinAsyncCircuitBreaker: Circuit breaker mixin (not integrated here)
+    - OMN-1857: Extraction ticket for this mixin
+
+Note on Circuit Breaker:
+    Per OMN-1857 design decision 1A, the executor should manage circuit breaker
+    internally. However, this initial implementation focuses on the core execution
+    mechanics. Circuit breaker integration will be added as a follow-up once the
+    basic pattern is validated.
+"""
+
+from __future__ import annotations
+
+import logging
+import time
+from collections.abc import Awaitable, Callable
+from typing import TYPE_CHECKING, TypeVar
+
+from omnibase_infra.enums import EnumPostgresErrorCode
+from omnibase_infra.errors import (
+    InfraAuthenticationError,
+    InfraConnectionError,
+    InfraTimeoutError,
+    RepositoryExecutionError,
+)
+from omnibase_infra.models.model_backend_result import ModelBackendResult
+from omnibase_infra.utils import sanitize_backend_error, sanitize_error_message
+
+if TYPE_CHECKING:
+    from uuid import UUID
+
+logger = logging.getLogger(__name__)
+
+T = TypeVar("T")
+
+
+class MixinPostgresOpExecutor:
+    """Shared execution core for PostgreSQL operation handlers.
+
+    Centralizes timing, error handling, sanitization, and result construction
+    for PostgreSQL operations. Handlers inherit this mixin and delegate to
+    _execute_postgres_op() for consistent mechanical behavior.
+
+    This mixin does NOT manage circuit breaker state - that responsibility
+    remains with the handler or a separate MixinAsyncCircuitBreaker composition.
+
+    Example:
+        ```python
+        class HandlerPostgresUpsert(MixinPostgresOpExecutor):
+            def __init__(self, pool: asyncpg.Pool) -> None:
+                self._pool = pool
+
+            async def handle(
+                self, payload: ModelPayloadUpsertContract, correlation_id: UUID
+            ) -> ModelBackendResult:
+                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),
+                )
+        ```
+
+    See Also:
+        - EnumPostgresErrorCode: Error codes with is_retriable property
+        - sanitize_error_message: Error sanitization utility
+        - ModelBackendResult: Structured result model
+    """
+
+    async def _execute_postgres_op(
+        self,
+        *,
+        op_error_code: EnumPostgresErrorCode,
+        correlation_id: UUID,
+        log_context: dict[str, object],
+        fn: Callable[[], Awaitable[T]],
+    ) -> ModelBackendResult:
+        """Execute a PostgreSQL operation with timing, error handling, and sanitization.
+
+        This method wraps the actual database operation (fn) with:
+        1. Timing measurement via time.perf_counter()
+        2. Exception classification into appropriate error codes
+        3. Error message sanitization to prevent credential exposure
+        4. Structured logging with correlation ID and context
+        5. ModelBackendResult construction
+
+        Args:
+            op_error_code: Operation-specific error code for non-infrastructure
+                failures (e.g., UPSERT_ERROR, HEARTBEAT_ERROR). Used when the
+                operation fails due to business logic or query issues rather
+                than connection/auth problems.
+            correlation_id: Request correlation ID for distributed tracing.
+            log_context: Additional fields for structured logging (e.g.,
+                contract_id, node_name). Included in all log messages.
+            fn: Async callable that performs the actual database operation.
+                Should return any value on success. The return value is not
+                used - only success/failure matters.
+
+        Returns:
+            ModelBackendResult with:
+                - success: True if fn() completed without exception
+                - error: Sanitized error message (empty string on success)
+                - error_code: Appropriate EnumPostgresErrorCode
+                - duration_ms: Operation duration in milliseconds
+                - backend_id: "postgres"
+                - correlation_id: Passed through for tracing
+
+        Error Classification:
+            | Exception Type              | Error Code              | Retriable |
+            |-----------------------------|-------------------------|-----------|
+            | TimeoutError                | TIMEOUT_ERROR           | Yes       |
+            | InfraTimeoutError           | TIMEOUT_ERROR           | Yes       |
+            | InfraAuthenticationError    | AUTH_ERROR              | No        |
+            | InfraConnectionError        | CONNECTION_ERROR        | Yes       |
+            | RepositoryExecutionError    | op_error_code           | No        |
+            | Exception                   | UNKNOWN_ERROR           | No        |
+
+        Note:
+            This method never raises exceptions. All errors are captured,
+            sanitized, logged, and returned in the result model.
+        """
+        start_time = time.perf_counter()
+        log_extra = {
+            "correlation_id": str(correlation_id),
+            **log_context,
+        }
+
+        try:
+            # Execute the operation
+            await fn()
+
+            duration_ms = (time.perf_counter() - start_time) * 1000
+
+            logger.debug(
+                "PostgreSQL operation completed successfully",
+                extra={**log_extra, "duration_ms": duration_ms},
+            )
+
+            return ModelBackendResult(
+                success=True,
+                duration_ms=duration_ms,
+                backend_id="postgres",
+                correlation_id=correlation_id,
+            )
+
+        except (TimeoutError, InfraTimeoutError) as e:
+            # Timeout - retriable error
+            duration_ms = (time.perf_counter() - start_time) * 1000
+            sanitized_error = sanitize_error_message(e)
+            logger.warning(
+                "PostgreSQL operation timed out",
+                extra={
+                    **log_extra,
+                    "duration_ms": duration_ms,
+                    "error": sanitized_error,
+                },
+            )
+            return ModelBackendResult(
+                success=False,
+                error=sanitized_error,
+                error_code=EnumPostgresErrorCode.TIMEOUT_ERROR,
+                duration_ms=duration_ms,
+                backend_id="postgres",
+                correlation_id=correlation_id,
+            )
+
+        except InfraAuthenticationError as e:
+            # Authentication failure - non-retriable
+            duration_ms = (time.perf_counter() - start_time) * 1000
+            sanitized_error = sanitize_error_message(e)
+            logger.exception(
+                "PostgreSQL authentication failed",
+                extra={
+                    **log_extra,
+                    "duration_ms": duration_ms,
+                    "error": sanitized_error,
+                },
+            )
+            return ModelBackendResult(
+                success=False,
+                error=sanitized_error,
+                error_code=EnumPostgresErrorCode.AUTH_ERROR,
+                duration_ms=duration_ms,
+                backend_id="postgres",
+                correlation_id=correlation_id,
+            )
+
+        except InfraConnectionError as e:
+            # Connection failure - retriable
+            duration_ms = (time.perf_counter() - start_time) * 1000
+            sanitized_error = sanitize_error_message(e)
+            logger.warning(
+                "PostgreSQL connection failed",
+                extra={
+                    **log_extra,
+                    "duration_ms": duration_ms,
+                    "error": sanitized_error,
+                },
+            )
+            return ModelBackendResult(
+                success=False,
+                error=sanitized_error,
+                error_code=EnumPostgresErrorCode.CONNECTION_ERROR,
+                duration_ms=duration_ms,
+                backend_id="postgres",
+                correlation_id=correlation_id,
+            )
+
+        except RepositoryExecutionError as e:
+            # Query/operation failure - use handler-provided error code
+            duration_ms = (time.perf_counter() - start_time) * 1000
+            sanitized_error = sanitize_error_message(e)
+            logger.warning(
+                "PostgreSQL operation failed",
+                extra={
+                    **log_extra,
+                    "duration_ms": duration_ms,
+                    "error": sanitized_error,
+                    "error_code": op_error_code.value,
+                },
+            )
+            return ModelBackendResult(
+                success=False,
+                error=sanitized_error,
+                error_code=op_error_code,
+                duration_ms=duration_ms,
+                backend_id="postgres",
+                correlation_id=correlation_id,
+            )
+
+        except (
+            Exception
+        ) as e:  # ONEX: catch-all for driver errors, encoding errors, pool errors
+            # Unknown error - non-retriable, requires investigation
+            duration_ms = (time.perf_counter() - start_time) * 1000
+            sanitized_error = sanitize_backend_error("postgres", e)
+            logger.exception(
+                "PostgreSQL operation failed with unexpected error",
+                extra={
+                    **log_extra,
+                    "duration_ms": duration_ms,
+                    "error_type": type(e).__name__,
+                    "error": sanitized_error,
+                },
+            )
+            return ModelBackendResult(
+                success=False,
+                error=sanitized_error,
+                error_code=EnumPostgresErrorCode.UNKNOWN_ERROR,
+                duration_ms=duration_ms,
+                backend_id="postgres",
+                correlation_id=correlation_id,
+            )
+
+
+__all__ = ["MixinPostgresOpExecutor"]

omnibase_infra/models/__init__.py

@@ -30,6 +30,7 @@ from omnibase_infra.models.event_bus import (
 from omnibase_infra.models.handlers import ModelHandlerIdentifier
 from omnibase_infra.models.health import ModelHealthCheckResult
 from omnibase_infra.models.logging import ModelLogContext
+from omnibase_infra.models.model_backend_result import ModelBackendResult
 from omnibase_infra.models.model_node_identity import ModelNodeIdentity
 from omnibase_infra.models.model_retry_error_classification import (
     ModelRetryErrorClassification,
@@ -93,6 +94,8 @@ __all__: list[str] = [
     "ModelConsumerRetryConfig",
     "ModelIdempotencyConfig",
     "ModelOffsetPolicyConfig",
+    # Backend result models
+    "ModelBackendResult",
     # Resilience models
     "ModelCircuitBreakerConfig",
     # Validation models

omnibase_infra/models/discovery/model_dependency_spec.py

@@ -89,6 +89,7 @@ class ModelDependencySpec(BaseModel):
     model_config = ConfigDict(
         frozen=True,
         extra="forbid",
+        from_attributes=True,  # ORM/pytest-xdist compatibility
     )
 
     # Identity

omnibase_infra/models/discovery/model_discovered_capabilities.py

@@ -27,7 +27,7 @@ class ModelDiscoveredCapabilities(BaseModel):
         ... )
     """
 
-    model_config = ConfigDict(extra="forbid", frozen=True)
+    model_config = ConfigDict(extra="forbid", frozen=True, from_attributes=True)
 
     operations: tuple[str, ...] = Field(
         default=(),

omnibase_infra/models/discovery/model_introspection_config.py

@@ -108,6 +108,7 @@ class ModelIntrospectionConfig(BaseModel):
                 config = ModelIntrospectionConfig(
                     node_id=node_id,
                     node_type=EnumNodeKind.EFFECT,  # Use enum directly (preferred)
+                    node_name="my_effect_node",
                     event_bus=event_bus,
                     version="1.2.0",
                 )
@@ -119,6 +120,7 @@ class ModelIntrospectionConfig(BaseModel):
                 config = ModelIntrospectionConfig(
                     node_id=node_id or uuid4(),
                     node_type=EnumNodeKind.EFFECT,  # Use enum directly (preferred)
+                    node_name="my_custom_effect_node",
                     event_bus=event_bus,
                     operation_keywords=frozenset({"fetch", "upload", "download"}),
                 )
@@ -141,6 +143,27 @@ class ModelIntrospectionConfig(BaseModel):
         "Accepts EnumNodeKind directly (preferred) or string (deprecated, will be coerced).",
     )
 
+    node_name: str = Field(  # pattern-ok: canonical identifier, not a foreign key reference
+        ...,
+        min_length=1,
+        description="Node name for consumer group identification (e.g., 'claude_hook_effect'). "
+        "Cannot be empty.",
+    )
+
+    env: str = Field(
+        default="dev",
+        min_length=1,
+        description="Environment identifier (e.g., 'dev', 'staging', 'prod'). "
+        "Used for node identity in event bus subscriptions. Cannot be empty.",
+    )
+
+    service: str = Field(
+        default="onex",
+        min_length=1,
+        description="Service name (e.g., 'omniintelligence', 'omnibridge'). "
+        "Used for node identity in event bus subscriptions. Cannot be empty.",
+    )
+
     # Event bus for publishing introspection events.
     # Uses _EventBusType which provides:
     # - ProtocolEventBus | None during static analysis (TYPE_CHECKING)
@@ -155,7 +178,8 @@ class ModelIntrospectionConfig(BaseModel):
 
     version: str = Field(
         default="1.0.0",
-        description="Node version string",
+        min_length=1,
+        description="Node version string. Cannot be empty.",
     )
 
     cache_ttl: float = Field(
@@ -284,6 +308,7 @@ class ModelIntrospectionConfig(BaseModel):
     model_config = ConfigDict(
         frozen=True,
         extra="forbid",
+        from_attributes=True,  # ORM/pytest-xdist compatibility
         arbitrary_types_allowed=True,  # Allow arbitrary types for event_bus
         json_schema_extra={
             "examples": [
@@ -291,6 +316,7 @@ class ModelIntrospectionConfig(BaseModel):
                 {
                     "node_id": "550e8400-e29b-41d4-a716-446655440000",
                     "node_type": "EFFECT",
+                    "node_name": "example_effect_node",
                     "event_bus": None,
                     "version": "1.0.0",
                     "cache_ttl": 300.0,
@@ -305,6 +331,7 @@ class ModelIntrospectionConfig(BaseModel):
                 {
                     "node_id": "550e8400-e29b-41d4-a716-446655440001",
                     "node_type": "COMPUTE",
+                    "node_name": "example_compute_node",
                     "event_bus": None,
                     "version": "2.1.0",
                     "cache_ttl": 120.0,

omnibase_infra/models/discovery/model_introspection_performance_metrics.py

@@ -131,6 +131,7 @@ class ModelIntrospectionPerformanceMetrics(BaseModel):
     model_config = ConfigDict(
         frozen=True,
         extra="forbid",
+        from_attributes=True,  # ORM/pytest-xdist compatibility
         json_schema_extra={
             "examples": [
                 {

omnibase_infra/models/discovery/model_introspection_task_config.py

@@ -96,6 +96,7 @@ class ModelIntrospectionTaskConfig(BaseModel):
     model_config = ConfigDict(
         frozen=True,
         extra="forbid",
+        from_attributes=True,  # ORM/pytest-xdist compatibility
         json_schema_extra={
             "examples": [
                 {

omnibase_infra/{nodes/effects/models → models}/model_backend_result.py

@@ -61,7 +61,9 @@ class ModelBackendResult(BaseModel):
     Attributes:
         success: Whether the backend operation completed successfully.
         error: Sanitized error message if success is False.
-        error_code: Optional error code for programmatic handling.
+        error_code: Error code for programmatic handling. PostgreSQL handlers
+            use EnumPostgresErrorCode enum values which serialize to strings
+            (e.g., "POSTGRES_CONNECTION_ERROR"). Other backends use string codes.
         duration_ms: Time taken for the operation in milliseconds.
         backend_id: Optional identifier for the backend instance.
 
@@ -96,18 +98,30 @@ class ModelBackendResult(BaseModel):
         >>> result.success
         True
 
-    Example (failure case):
+    Example (failure case with PostgreSQL enum):
+        >>> from omnibase_infra.enums import EnumPostgresErrorCode
         >>> result = ModelBackendResult(
         ...     success=False,
         ...     error="Connection refused to database host",
-        ...     error_code="DATABASE_CONNECTION_ERROR",
+        ...     error_code=EnumPostgresErrorCode.CONNECTION_ERROR,
         ...     duration_ms=5000.0,
         ...     backend_id="postgres",
         ... )
         >>> result.success
         False
-        >>> result.error
-        'Connection refused to database host'
+        >>> result.error_code  # Enum serializes to string
+        'POSTGRES_CONNECTION_ERROR'
+
+    Example (failure case with Consul string code):
+        >>> result = ModelBackendResult(
+        ...     success=False,
+        ...     error="Service registration failed",
+        ...     error_code="CONSUL_CONNECTION_ERROR",
+        ...     duration_ms=1500.0,
+        ...     backend_id="consul",
+        ... )
+        >>> result.error_code
+        'CONSUL_CONNECTION_ERROR'
     """
 
     model_config = ConfigDict(frozen=True, extra="forbid", from_attributes=True)
@@ -122,7 +136,9 @@ class ModelBackendResult(BaseModel):
     )
     error_code: str | None = Field(
         default=None,
-        description="Error code for programmatic handling (e.g., DATABASE_CONNECTION_ERROR)",
+        description="Error code for programmatic handling. PostgreSQL handlers use "
+        "EnumPostgresErrorCode enum values (which serialize to strings like "
+        "'POSTGRES_CONNECTION_ERROR'). Other backends use string codes directly.",
     )
     duration_ms: float = Field(
         default=0.0,

omnibase_infra/models/projection/__init__.py

@@ -8,12 +8,15 @@ by orchestrators to query current entity state.
 
 Exports:
     ModelCapabilityFields: Container for capability fields in projection persistence
+    ModelContractProjection: Contract projection for Registry API queries
     ModelRegistrationProjection: Registration projection for orchestrator state queries
     ModelRegistrationSnapshot: Compacted snapshot for read optimization
     ModelSequenceInfo: Sequence information for projection ordering and idempotency
     ModelSnapshotTopicConfig: Kafka topic configuration for snapshot publishing
+    ModelTopicProjection: Topic projection for Registry API queries
 
 Related Tickets:
+    - OMN-1845: Create ProjectionReaderContract for contract/topic queries
     - OMN-1134: Registry Projection Extensions for Capabilities
     - OMN-947 (F2): Snapshot Publishing
     - OMN-944 (F1): Implement Registration Projection Schema
@@ -23,6 +26,9 @@ Related Tickets:
 from omnibase_infra.models.projection.model_capability_fields import (
     ModelCapabilityFields,
 )
+from omnibase_infra.models.projection.model_contract_projection import (
+    ModelContractProjection,
+)
 from omnibase_infra.models.projection.model_registration_projection import (
     ModelRegistrationProjection,
 )
@@ -33,11 +39,16 @@ from omnibase_infra.models.projection.model_sequence_info import ModelSequenceIn
 from omnibase_infra.models.projection.model_snapshot_topic_config import (
     ModelSnapshotTopicConfig,
 )
+from omnibase_infra.models.projection.model_topic_projection import (
+    ModelTopicProjection,
+)
 
 __all__ = [
     "ModelCapabilityFields",
+    "ModelContractProjection",
     "ModelRegistrationProjection",
     "ModelRegistrationSnapshot",
     "ModelSequenceInfo",
     "ModelSnapshotTopicConfig",
+    "ModelTopicProjection",
 ]