omnibase_infra 0.2.1__py3-none-any.whl

omnibase_infra/nodes/node_registration_storage_effect/models/model_storage_result.py

@@ -0,0 +1,136 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Storage Result Model for Registration Storage Operations.
+
+This module provides ModelStorageResult, representing the result of a
+query operation against registration storage.
+
+Architecture:
+    ModelStorageResult contains:
+    - records: List of matching registration records
+    - total_count: Total number of matching records (for pagination)
+    - query_metadata: Optional metadata about query execution
+
+    This model supports pagination - total_count may exceed len(records)
+    when limit/offset pagination is used.
+
+Related:
+    - ModelStorageQuery: Query model that produces these results
+    - ModelRegistrationRecord: Record type contained in results
+    - ProtocolRegistrationStorageHandler: Protocol that produces results
+"""
+
+from __future__ import annotations
+
+from uuid import UUID
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+from .model_registration_record import ModelRegistrationRecord
+
+
+class ModelStorageResult(BaseModel):
+    """Result model for registration storage query operations.
+
+    Contains the list of matching records and pagination metadata.
+    Supports efficient pagination by providing total_count separately
+    from the actual records returned.
+
+    Immutability:
+        This model uses frozen=True to ensure results are immutable
+        once created, enabling safe sharing and caching.
+
+    Attributes:
+        success: Whether the query completed successfully.
+        records: List of matching registration records.
+        total_count: Total number of records matching the query.
+        error: Error message if query failed (sanitized).
+        duration_ms: Time taken for the operation in milliseconds.
+        backend_type: The backend that handled the query.
+        correlation_id: Correlation ID for request tracing.
+
+    Example:
+        >>> # Result with pagination info
+        >>> result = ModelStorageResult(
+        ...     success=True,
+        ...     records=(record1, record2),
+        ...     total_count=150,  # More records exist
+        ...     duration_ms=45.2,
+        ...     backend_type="postgresql",
+        ...     correlation_id=correlation_id,
+        ... )
+        >>> result.has_more_records()
+        True
+    """
+
+    model_config = ConfigDict(frozen=True, extra="forbid", from_attributes=True)
+
+    success: bool = Field(
+        ...,
+        description="Whether the query completed successfully",
+    )
+    records: tuple[ModelRegistrationRecord, ...] = Field(
+        default_factory=tuple,
+        description="List of matching registration records",
+    )
+    total_count: int = Field(
+        default=0,
+        description="Total number of records matching the query (for pagination)",
+        ge=0,
+    )
+    error: str | None = Field(
+        default=None,
+        description="Sanitized error message if query failed",
+    )
+    duration_ms: float = Field(
+        default=0.0,
+        description="Time taken for the operation in milliseconds",
+        ge=0.0,
+    )
+    backend_type: str = Field(
+        default="unknown",
+        description="The backend type that handled the query",
+    )
+    correlation_id: UUID | None = Field(
+        default=None,
+        description="Correlation ID for request tracing",
+    )
+
+    @model_validator(mode="after")
+    def validate_count_consistency(self) -> ModelStorageResult:
+        """Validate that total_count is consistent with records.
+
+        total_count should be >= len(records) since pagination may
+        return a subset of matching records.
+
+        Returns:
+            The validated result model.
+
+        Raises:
+            ValueError: If total_count < len(records).
+        """
+        if self.total_count < len(self.records):
+            raise ValueError(
+                f"total_count ({self.total_count}) cannot be less than "
+                f"number of returned records ({len(self.records)})"
+            )
+        return self
+
+    def has_more_records(self) -> bool:
+        """Check if there are more records beyond the returned set.
+
+        Returns:
+            True if total_count > len(records), indicating more records exist.
+        """
+        return self.total_count > len(self.records)
+
+    def is_empty(self) -> bool:
+        """Check if the result contains no records.
+
+        Returns:
+            True if no records were returned.
+        """
+        return len(self.records) == 0
+
+
+__all__ = ["ModelStorageResult"]

omnibase_infra/nodes/node_registration_storage_effect/models/model_upsert_result.py

@@ -0,0 +1,127 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Upsert Result Model for Registration Storage Operations.
+
+This module provides ModelUpsertResult, representing the result of an
+insert or update operation against registration storage.
+
+Architecture:
+    ModelUpsertResult captures:
+    - success: Whether the operation completed successfully
+    - node_id: ID of the affected record
+    - operation: Whether it was an "insert" or "update"
+    - error: Error message if operation failed
+
+    This model supports idempotent upsert operations where the same
+    request may result in either insert or update depending on
+    existing data.
+
+Related:
+    - ModelRegistrationRecord: Record that was inserted/updated
+    - ProtocolRegistrationStorageHandler: Protocol that produces results
+"""
+
+from __future__ import annotations
+
+from typing import Literal
+from uuid import UUID
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class ModelUpsertResult(BaseModel):
+    """Result model for registration storage upsert operations.
+
+    Indicates the outcome of an insert or update operation.
+    Success indicates the record was successfully stored; operation
+    indicates whether it was a new insert or an update to existing.
+
+    Immutability:
+        This model uses frozen=True to ensure results are immutable
+        once created, enabling safe sharing and logging.
+
+    Attributes:
+        success: Whether the operation completed successfully.
+        node_id: UUID of the affected registration record.
+        operation: Type of operation performed ("insert" or "update").
+        error: Error message if success is False (sanitized).
+        duration_ms: Time taken for the operation in milliseconds.
+        backend_type: The backend that handled the upsert.
+        correlation_id: Correlation ID for request tracing.
+
+    Example (success):
+        >>> result = ModelUpsertResult(
+        ...     success=True,
+        ...     node_id=some_uuid,
+        ...     operation="insert",
+        ...     duration_ms=45.2,
+        ...     backend_type="postgresql",
+        ...     correlation_id=correlation_id,
+        ... )
+        >>> result.was_inserted()
+        True
+
+    Example (failure):
+        >>> result = ModelUpsertResult(
+        ...     success=False,
+        ...     node_id=some_uuid,
+        ...     operation="update",
+        ...     error="Connection timeout to database",
+        ...     duration_ms=5000.0,
+        ...     backend_type="postgresql",
+        ...     correlation_id=correlation_id,
+        ... )
+        >>> result.success
+        False
+    """
+
+    model_config = ConfigDict(frozen=True, extra="forbid", from_attributes=True)
+
+    success: bool = Field(
+        ...,
+        description="Whether the operation completed successfully",
+    )
+    node_id: UUID = Field(
+        ...,
+        description="UUID of the affected registration record",
+    )
+    operation: Literal["insert", "update"] = Field(
+        ...,
+        description="Type of operation performed",
+    )
+    error: str | None = Field(
+        default=None,
+        description="Error message if success is False (sanitized - no secrets)",
+    )
+    duration_ms: float = Field(
+        default=0.0,
+        description="Time taken for the operation in milliseconds",
+        ge=0.0,
+    )
+    backend_type: str = Field(
+        default="unknown",
+        description="The backend type that handled the upsert",
+    )
+    correlation_id: UUID | None = Field(
+        default=None,
+        description="Correlation ID for request tracing",
+    )
+
+    def was_inserted(self) -> bool:
+        """Check if this result represents a new record insertion.
+
+        Returns:
+            True if operation was "insert" and success is True.
+        """
+        return self.success and self.operation == "insert"
+
+    def was_updated(self) -> bool:
+        """Check if this result represents an existing record update.
+
+        Returns:
+            True if operation was "update" and success is True.
+        """
+        return self.success and self.operation == "update"
+
+
+__all__ = ["ModelUpsertResult"]

omnibase_infra/nodes/node_registration_storage_effect/node.py

@@ -0,0 +1,109 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Node Registration Storage Effect - Capability-oriented storage node.
+
+This effect node provides registration storage capabilities with pluggable backends.
+Named by capability ("registration.storage"), not by vendor (e.g., PostgreSQL).
+
+Core Principle:
+    "I'm interested in what you do, not what you are"
+
+This node follows the ONEX declarative pattern:
+    - DECLARATIVE effect driven by contract.yaml
+    - Zero custom storage logic - all behavior from handler protocol
+    - Lightweight shell that delegates to ProtocolRegistrationPersistence
+    - Pattern: "Contract-driven, handlers wired externally"
+
+Extends NodeEffect from omnibase_core for external I/O operations.
+All storage logic is 100% driven by handler implementations, not Python code.
+
+Capabilities:
+    - registration.storage: Store, query, update, delete registration records
+    - registration.storage.query: Query with filtering and pagination
+    - registration.storage.upsert: Idempotent insert/update operations
+    - registration.storage.delete: Delete by node ID
+    - registration.storage.health: Backend health checks
+
+Pluggable Backends:
+    The node supports multiple storage backends through the handler protocol:
+    - PostgreSQL (default): For relational storage requirements
+    - Mock: For testing and development
+
+    Backend configuration is done through the registry at bootstrap:
+    ```python
+    from omnibase_core.models.container import ModelONEXContainer
+    from omnibase_infra.nodes.node_registration_storage_effect import (
+        NodeRegistrationStorageEffect,
+    )
+    from omnibase_infra.nodes.node_registration_storage_effect.registry import (
+        RegistryInfraRegistrationStorage,
+    )
+    from omnibase_infra.handlers.registration_storage import (
+        HandlerRegistrationStoragePostgres,
+    )
+
+    # Create container and register handler
+    container = ModelONEXContainer()
+    handler = HandlerRegistrationStoragePostgres(dsn="postgresql://...")
+    RegistryInfraRegistrationStorage.register(container)
+    RegistryInfraRegistrationStorage.register_handler(container, handler)
+
+    # Create node with container (handler resolved via DI)
+    node = NodeRegistrationStorageEffect(container)
+    ```
+
+Design Decisions:
+    - 100% Contract-Driven: All capabilities in YAML, not Python
+    - Zero Custom Methods: Base class handles everything
+    - Declarative Execution: Handler wired externally
+    - Capability-Oriented: Named by what it does, not what it uses
+
+Related:
+    - contract.yaml: Capability definitions and IO operations
+    - ProtocolRegistrationPersistence: Handler protocol for backends
+    - models/: Input, output, and record models
+"""
+
+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 NodeRegistrationStorageEffect(NodeEffect):
+    """Effect node for registration storage operations.
+
+    Capability: registration.storage
+
+    Provides a capability-oriented interface for registration storage operations.
+    Supports pluggable handlers for different storage backends (PostgreSQL, mock).
+
+    This node is declarative - all behavior is defined in contract.yaml and
+    implemented through the handler protocol. No custom storage logic exists
+    in this class.
+
+    Attributes:
+        container: ONEX dependency injection container
+
+    Example:
+        >>> from omnibase_core.models.container import ModelONEXContainer
+        >>> container = ModelONEXContainer()
+        >>> node = NodeRegistrationStorageEffect(container)
+        >>> # Handler must be wired externally via registry
+    """
+
+    def __init__(self, container: ModelONEXContainer) -> None:
+        """Initialize the registration storage effect node.
+
+        Args:
+            container: ONEX dependency injection container for resolving
+                dependencies defined in contract.yaml.
+        """
+        super().__init__(container)
+
+
+__all__ = ["NodeRegistrationStorageEffect"]

omnibase_infra/nodes/node_registration_storage_effect/protocols/__init__.py

@@ -0,0 +1,22 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Protocols for Registration Storage Effect Node.
+
+This module exports protocols for the NodeRegistrationStorageEffect,
+defining interfaces for pluggable storage backends.
+
+Available Protocols:
+    - ProtocolRegistrationPersistence: Interface for storage backends
+
+Protocol Compliance:
+    Per ONEX conventions, protocol compliance is verified via duck typing.
+    The protocol is @runtime_checkable for isinstance() support.
+
+Implementations:
+    - HandlerRegistrationStoragePostgres: PostgreSQL backend
+    - HandlerRegistrationStorageMock: Mock backend for testing
+"""
+
+from .protocol_registration_persistence import ProtocolRegistrationPersistence
+
+__all__ = ["ProtocolRegistrationPersistence"]