omnibase_infra 0.2.1__py3-none-any.whl

omnibase_infra/nodes/node_registration_storage_effect/models/model_registration_record.py

@@ -0,0 +1,199 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Registration Record Model for Storage Operations.
+
+This module provides ModelRegistrationRecord, representing a complete node
+registration record for storage in backend systems (e.g., PostgreSQL).
+
+Architecture:
+    ModelRegistrationRecord captures all information about a registered node:
+    - Identity: node_id, node_type, node_version
+    - Capabilities: Tuple of capabilities the node provides (immutable)
+    - Endpoints: Service discovery endpoints
+    - Metadata: Additional key-value metadata
+    - Timestamps: created_at, updated_at for tracking
+
+    This model is backend-agnostic and can be serialized to any storage format.
+
+Security:
+    The metadata field should NOT contain sensitive information.
+    Secrets should be stored in Vault, not in registration records.
+
+Related:
+    - NodeRegistrationStorageEffect: Effect node that stores these records
+    - ProtocolRegistrationStorageHandler: Protocol for storage backends
+    - ModelStorageQuery: Query model for retrieving records
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from datetime import datetime
+from uuid import UUID
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+from omnibase_core.enums.enum_node_kind import EnumNodeKind
+from omnibase_core.models.primitives.model_semver import ModelSemVer
+from omnibase_infra.utils import validate_timezone_aware_datetime_optional
+
+
+class ModelRegistrationRecord(BaseModel):
+    """Registration record for node storage operations.
+
+    Represents a complete node registration record that can be stored in
+    any backend (PostgreSQL, etc.). This model is capability-oriented,
+    focusing on what the node does rather than implementation details.
+
+    Immutability:
+        This model uses frozen=True to ensure records are immutable
+        once created, supporting safe concurrent access and comparison.
+
+    Note on correlation_id:
+        The correlation_id field is optional and is used for distributed
+        tracing. When not provided, handlers should auto-generate one
+        for observability. This design choice allows callers to either:
+        1. Pass an existing correlation_id for trace continuity
+        2. Omit it and let the handler generate one
+
+        The auto-generation approach ensures every operation has traceability
+        even when callers don't provide explicit IDs.
+
+    Attributes:
+        node_id: Unique identifier for the registered node.
+        node_type: Type of ONEX node (EnumNodeKind).
+        node_version: Semantic version of the node.
+        capabilities: Tuple of capability names the node provides (immutable).
+        endpoints: Dict mapping endpoint type to URL.
+        metadata: Additional key-value metadata (no secrets).
+        created_at: Timestamp when the record was created (optional, backend may set).
+        updated_at: Timestamp when the record was last updated (optional, backend may set).
+        correlation_id: Optional correlation ID for distributed tracing.
+
+    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
+        >>> record = ModelRegistrationRecord(
+        ...     node_id=uuid4(),
+        ...     node_type=EnumNodeKind.EFFECT,
+        ...     node_version=ModelSemVer(major=1, minor=0, patch=0),
+        ...     capabilities=("registration.storage", "registration.storage.query"),
+        ...     endpoints={"health": "http://localhost:8080/health"},
+        ...     metadata={"team": "platform"},
+        ...     created_at=datetime.now(UTC),
+        ...     updated_at=datetime.now(UTC),
+        ...     correlation_id=uuid4(),
+        ... )
+        >>> record.node_type
+        <EnumNodeKind.EFFECT: 'effect'>
+    """
+
+    model_config = ConfigDict(frozen=True, extra="forbid", from_attributes=True)
+
+    node_id: UUID = Field(
+        ...,
+        description="Unique identifier for the registered node",
+    )
+    node_type: EnumNodeKind = Field(
+        ...,
+        description="Type of ONEX node",
+    )
+    node_version: ModelSemVer = Field(
+        ...,
+        description="Semantic version of the node",
+    )
+    capabilities: tuple[str, ...] = Field(
+        default_factory=tuple,
+        description="Tuple of capability names the node provides (immutable)",
+    )
+    endpoints: dict[str, str] = Field(
+        default_factory=dict,
+        description="Dict mapping endpoint type to URL (e.g., {'health': 'http://...'})",
+    )
+    metadata: dict[str, str] = Field(
+        default_factory=dict,
+        description="Additional key-value metadata (no secrets)",
+    )
+    created_at: datetime | None = Field(
+        default=None,
+        description="Timestamp when the record was created (timezone-aware if provided, backend may auto-set)",
+    )
+    updated_at: datetime | None = Field(
+        default=None,
+        description="Timestamp when the record was last updated (timezone-aware if provided, backend may auto-set)",
+    )
+    correlation_id: UUID | None = Field(
+        default=None,
+        description="Correlation ID for distributed tracing (auto-generated if not provided)",
+    )
+
+    @field_validator("capabilities", mode="before")
+    @classmethod
+    def _coerce_capabilities_to_tuple(cls, v: object) -> tuple[str, ...]:
+        """Convert list/sequence to tuple for immutability.
+
+        This validator ensures explicit handling of all input types rather than
+        silent fallback, which could mask invalid input. In strict mode, all
+        items must already be strings - no silent type coercion.
+
+        Args:
+            v: The input value to coerce.
+
+        Returns:
+            tuple[str, ...]: The coerced tuple of capability strings.
+
+        Raises:
+            ValueError: If input is not a valid sequence type or contains non-strings.
+
+        Type coercion rules:
+            - tuple: Validates contents are strings, returns as-is
+            - list/set/frozenset: Validates contents are strings, converts to tuple
+            - Non-string items: Raises ValueError (strict mode)
+            - None: Raises ValueError (use default_factory=tuple instead)
+            - Other types: Raises ValueError
+        """
+        if isinstance(v, tuple):
+            # Validate tuple contents in strict mode
+            for i, item in enumerate(v):
+                if not isinstance(item, str):
+                    raise ValueError(
+                        f"capabilities[{i}] must be a string, got {type(item).__name__}"
+                    )
+            return v
+        if isinstance(v, list | set | frozenset):
+            # Convert sequence to tuple, validating contents
+            result: list[str] = []
+            for i, item in enumerate(v):
+                if not isinstance(item, str):
+                    raise ValueError(
+                        f"capabilities[{i}] must be a string, got {type(item).__name__}"
+                    )
+                result.append(item)
+            return tuple(result)
+        if isinstance(v, Sequence) and not isinstance(v, str):
+            # Handle other sequence types
+            result_seq: list[str] = []
+            for i, item in enumerate(v):
+                if not isinstance(item, str):
+                    raise ValueError(
+                        f"capabilities[{i}] must be a string, got {type(item).__name__}"
+                    )
+                result_seq.append(item)
+            return tuple(result_seq)
+        raise ValueError(
+            f"capabilities must be a tuple, list, set, or frozenset, got {type(v).__name__}"
+        )
+
+    @field_validator("created_at", "updated_at")
+    @classmethod
+    def validate_timestamp_timezone_aware(cls, v: datetime | None) -> datetime | None:
+        """Validate that timestamps are timezone-aware when provided.
+
+        Delegates to shared utility for consistent validation across all models.
+        """
+        return validate_timezone_aware_datetime_optional(v)
+
+
+__all__ = ["ModelRegistrationRecord"]

omnibase_infra/nodes/node_registration_storage_effect/models/model_registration_update.py

@@ -0,0 +1,155 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Registration Update Model for Storage Operations.
+
+This module provides ModelRegistrationUpdate, representing a partial update
+to a registration record. Only fields that are set (not None) will be updated.
+
+Architecture:
+    ModelRegistrationUpdate allows selective field updates:
+    - endpoints: Optional new endpoints dict
+    - metadata: Optional new metadata dict
+    - capabilities: Optional new capabilities list
+    - node_version: Optional new semantic version (ModelSemVer)
+
+    This model enables type-safe partial updates rather than untyped dict[str, object].
+
+Related:
+    - ModelRegistrationRecord: Full record type being updated
+    - ProtocolRegistrationStorageHandler: Protocol that uses this for updates
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator
+
+from omnibase_core.models.primitives.model_semver import ModelSemVer
+
+
+class ModelRegistrationUpdate(BaseModel):
+    """Update model for registration storage operations.
+
+    Defines the fields that can be updated in a registration record.
+    All fields are optional - only non-None fields will be applied.
+
+    Immutability:
+        This model uses frozen=True to ensure updates are immutable
+        once created, enabling safe reuse and logging.
+
+    Attributes:
+        endpoints: Optional new endpoints dict (replaces existing).
+        metadata: Optional new metadata dict (replaces existing).
+        capabilities: Optional new capabilities list (replaces existing).
+        node_version: Optional new semantic version (replaces existing).
+
+    Example:
+        >>> # Update only endpoints
+        >>> update = ModelRegistrationUpdate(
+        ...     endpoints={"health": "http://new-host:8080/health"},
+        ... )
+
+        >>> # Update multiple fields
+        >>> update = ModelRegistrationUpdate(
+        ...     endpoints={"health": "http://new-host:8080/health"},
+        ...     metadata={"team": "platform", "env": "production"},
+        ... )
+    """
+
+    model_config = ConfigDict(frozen=True, extra="forbid", from_attributes=True)
+
+    endpoints: dict[str, str] | None = Field(
+        default=None,
+        description="Optional new endpoints dict (replaces existing if set)",
+    )
+    metadata: dict[str, str] | None = Field(
+        default=None,
+        description="Optional new metadata dict (replaces existing if set)",
+    )
+    capabilities: list[str] | None = Field(
+        default=None,
+        description="Optional new capabilities list (replaces existing if set)",
+    )
+    node_version: ModelSemVer | None = Field(
+        default=None,
+        description="Optional new semantic version",
+    )
+
+    @field_validator("node_version", mode="before")
+    @classmethod
+    def parse_node_version(cls, v: ModelSemVer | str | None) -> ModelSemVer | None:
+        """Parse node_version from string or ModelSemVer.
+
+        Args:
+            v: Either a ModelSemVer instance, a semver string, or None.
+
+        Returns:
+            Validated ModelSemVer instance or None.
+
+        Raises:
+            ValueError: If the string is not a valid semantic version.
+        """
+        if v is None:
+            return None
+        if isinstance(v, str):
+            try:
+                return ModelSemVer.parse(v)
+            except Exception as e:
+                raise ValueError(f"node_version: {e!s}") from e
+        return v
+
+    @model_validator(mode="after")
+    def validate_at_least_one_field(self) -> ModelRegistrationUpdate:
+        """Validate that at least one field is set for update.
+
+        An empty update (all None fields) is a no-op and likely a bug.
+
+        Returns:
+            The validated update model.
+
+        Raises:
+            ValueError: If no fields are set.
+        """
+        if (
+            self.endpoints is None
+            and self.metadata is None
+            and self.capabilities is None
+            and self.node_version is None
+        ):
+            raise ValueError(
+                "At least one field must be set for update. "
+                "All fields are currently None."
+            )
+        return self
+
+    def has_updates(self) -> bool:
+        """Check if any fields are set for update.
+
+        Returns:
+            True if at least one field is non-None.
+        """
+        return (
+            self.endpoints is not None
+            or self.metadata is not None
+            or self.capabilities is not None
+            or self.node_version is not None
+        )
+
+    def to_dict(self) -> dict[str, object]:
+        """Convert to dict with only non-None fields.
+
+        Returns:
+            Dict of field names to values, excluding None fields.
+        """
+        result: dict[str, object] = {}
+        if self.endpoints is not None:
+            result["endpoints"] = self.endpoints
+        if self.metadata is not None:
+            result["metadata"] = self.metadata
+        if self.capabilities is not None:
+            result["capabilities"] = self.capabilities
+        if self.node_version is not None:
+            result["node_version"] = self.node_version
+        return result
+
+
+__all__ = ["ModelRegistrationUpdate"]

omnibase_infra/nodes/node_registration_storage_effect/models/model_storage_health_check_details.py

@@ -0,0 +1,123 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Storage Health Check Details Model.
+
+This module provides the Pydantic model for backend-specific diagnostic
+information in health check results, replacing untyped dict[str, object]
+with strongly-typed fields.
+
+Architecture:
+    ModelStorageHealthCheckDetails captures backend-specific diagnostics:
+    - Connection pool statistics (pool_size, active_connections)
+    - Server version information
+    - Replication status
+    - Custom backend-specific extensions
+
+    The model uses optional fields to accommodate different backends
+    that may provide varying levels of diagnostic information.
+
+Related:
+    - ModelStorageHealthCheckResult: Parent model that contains details
+    - ProtocolRegistrationStorageHandler: Protocol for storage backends
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class ModelStorageHealthCheckDetails(BaseModel):
+    """Backend-specific diagnostic information for health checks.
+
+    This model captures diagnostic details from storage backends.
+    All fields are optional as different backends provide varying
+    levels of information.
+
+    Immutability:
+        This model uses frozen=True to ensure details are immutable
+        once created, enabling safe sharing and logging.
+
+    Attributes:
+        pool_size: Maximum size of the connection pool (if applicable).
+        active_connections: Current number of active connections.
+        idle_connections: Current number of idle connections.
+        waiting_connections: Number of requests waiting for connections.
+        server_version: Database server version string.
+        is_primary: Whether this is the primary/leader node.
+        replication_lag_ms: Replication lag in milliseconds (for replicas).
+        database_name: Name of the database being used.
+        schema_name: Schema name within the database.
+        extensions: List of enabled database extensions.
+
+    Example (PostgreSQL):
+        >>> details = ModelStorageHealthCheckDetails(
+        ...     pool_size=10,
+        ...     active_connections=3,
+        ...     idle_connections=7,
+        ...     waiting_connections=0,
+        ...     server_version="PostgreSQL 16.1",
+        ...     is_primary=True,
+        ...     database_name="omninode_bridge",
+        ...     schema_name="public",
+        ... )
+        >>> details.pool_size
+        10
+
+    Example (minimal details from mock backend):
+        >>> details = ModelStorageHealthCheckDetails(
+        ...     server_version="mock-1.0.0",
+        ... )
+        >>> details.pool_size is None
+        True
+    """
+
+    model_config = ConfigDict(frozen=True, extra="forbid", from_attributes=True)
+
+    pool_size: int | None = Field(
+        default=None,
+        description="Maximum size of the connection pool (if applicable)",
+        ge=0,
+    )
+    active_connections: int | None = Field(
+        default=None,
+        description="Current number of active connections",
+        ge=0,
+    )
+    idle_connections: int | None = Field(
+        default=None,
+        description="Current number of idle connections",
+        ge=0,
+    )
+    waiting_connections: int | None = Field(
+        default=None,
+        description="Number of requests waiting for connections",
+        ge=0,
+    )
+    server_version: str | None = Field(
+        default=None,
+        description="Database server version string",
+    )
+    is_primary: bool | None = Field(
+        default=None,
+        description="Whether this is the primary/leader node",
+    )
+    replication_lag_ms: float | None = Field(
+        default=None,
+        description="Replication lag in milliseconds (for replicas)",
+        ge=0.0,
+    )
+    database_name: str | None = Field(
+        default=None,
+        description="Name of the database being used",
+    )
+    schema_name: str | None = Field(
+        default=None,
+        description="Schema name within the database",
+    )
+    extensions: list[str] | None = Field(
+        default=None,
+        description="List of enabled database extensions",
+    )
+
+
+__all__ = ["ModelStorageHealthCheckDetails"]

omnibase_infra/nodes/node_registration_storage_effect/models/model_storage_health_check_result.py

@@ -0,0 +1,117 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Storage Health Check Result Model.
+
+This module provides the Pydantic model for health check results from
+registration storage backends, using strongly-typed model instances
+for all fields including backend-specific details.
+
+Note:
+    This model is domain-specific to registration storage. For
+    general-purpose health checks, see
+    ``omnibase_infra.models.health.ModelHealthCheckResult``.
+
+Related:
+    - ModelStorageHealthCheckDetails: Backend-specific diagnostic details
+    - ProtocolRegistrationStorageHandler: Protocol for storage backends
+"""
+
+from __future__ import annotations
+
+from uuid import UUID
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from .model_storage_health_check_details import ModelStorageHealthCheckDetails
+
+
+class ModelStorageHealthCheckResult(BaseModel):
+    """Result of a storage backend health check.
+
+    This model represents the outcome of a health check operation on a
+    registration storage backend, providing structured diagnostics about
+    the storage backend's operational status.
+
+    Attributes:
+        healthy: Whether the storage backend is healthy and operational.
+            When True, the backend can accept operations normally.
+            When False, consult the reason field for diagnostics.
+        backend_type: Identifier for the storage backend (e.g., "postgresql", "mock").
+        latency_ms: Connection latency in milliseconds.
+        reason: Human-readable explanation of the health status.
+        error_type: Exception type name if health check failed.
+            Only populated when healthy is False.
+        details: Backend-specific diagnostic information as a typed model.
+            Contains pool_size, active_connections, server_version, etc.
+        correlation_id: Correlation ID for distributed tracing.
+
+    Example:
+        >>> from omnibase_infra.nodes.node_registration_storage_effect.models import (
+        ...     ModelStorageHealthCheckDetails,
+        ... )
+        >>> # Healthy storage backend
+        >>> result = ModelStorageHealthCheckResult(
+        ...     healthy=True,
+        ...     backend_type="postgresql",
+        ...     latency_ms=2.5,
+        ...     reason="ok",
+        ...     details=ModelStorageHealthCheckDetails(
+        ...         pool_size=10,
+        ...         active_connections=3,
+        ...     ),
+        ... )
+        >>> if result.healthy:
+        ...     print(f"{result.backend_type} is operational")
+        postgresql is operational
+
+        >>> # Failed health check
+        >>> result = ModelStorageHealthCheckResult(
+        ...     healthy=False,
+        ...     backend_type="postgresql",
+        ...     latency_ms=0.0,
+        ...     reason="Connection refused",
+        ...     error_type="ConnectionRefusedError",
+        ... )
+        >>> if not result.healthy:
+        ...     print(f"Backend unhealthy: {result.reason}")
+        Backend unhealthy: Connection refused
+    """
+
+    model_config = ConfigDict(
+        frozen=True,
+        extra="forbid",
+        from_attributes=True,
+    )
+
+    healthy: bool = Field(
+        description="Whether the storage backend is healthy and operational",
+    )
+    backend_type: str = Field(
+        description="Identifier for the storage backend (e.g., 'postgresql', 'mock')",
+    )
+    latency_ms: float = Field(
+        default=0.0,
+        ge=0.0,
+        description="Connection latency in milliseconds",
+    )
+    reason: str = Field(
+        default="ok",
+        description="Human-readable explanation of the health status",
+    )
+    error_type: str | None = Field(
+        default=None,
+        description="Exception type name if health check failed",
+    )
+    details: ModelStorageHealthCheckDetails = Field(
+        default_factory=ModelStorageHealthCheckDetails,
+        description="Backend-specific diagnostic information as a typed model",
+    )
+    correlation_id: UUID | None = Field(
+        default=None,
+        description="Correlation ID for distributed tracing",
+    )
+
+
+__all__: list[str] = [
+    "ModelStorageHealthCheckResult",
+]

omnibase_infra/nodes/node_registration_storage_effect/models/model_storage_query.py

@@ -0,0 +1,100 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Storage Query Model for Registration Storage Operations.
+
+This module provides ModelStorageQuery, representing a query for retrieving
+registration records from storage backends.
+
+Architecture:
+    ModelStorageQuery supports flexible querying:
+    - Filter by node_id for specific record lookup
+    - Filter by node_type for type-based queries
+    - Filter by capabilities for capability-based discovery
+    - Pagination via limit and offset
+
+    All filters are optional - an empty query returns all records.
+
+Related:
+    - NodeRegistrationStorageEffect: Effect node that executes queries
+    - ModelStorageResult: Result model containing query results
+    - ProtocolRegistrationStorageHandler: Protocol that implements queries
+"""
+
+from __future__ import annotations
+
+from uuid import UUID
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from omnibase_core.enums.enum_node_kind import EnumNodeKind
+
+
+class ModelStorageQuery(BaseModel):
+    """Query model for registration storage operations.
+
+    Defines filters and pagination for querying registration records.
+    All filter fields are optional - omitting a filter means "match all".
+
+    Immutability:
+        This model uses frozen=True to ensure queries are immutable
+        once created, enabling safe reuse and caching.
+
+    Attributes:
+        node_id: Filter by specific node ID (exact match).
+        node_type: Filter by node type (EnumNodeKind).
+        capability_filter: Filter by capability name (contains match).
+        limit: Maximum number of records to return.
+        offset: Number of records to skip for pagination.
+
+    Example:
+        >>> # Query all EFFECT nodes
+        >>> from omnibase_core.enums.enum_node_kind import EnumNodeKind
+        >>> query = ModelStorageQuery(node_type=EnumNodeKind.EFFECT, limit=100)
+
+        >>> # Query specific node
+        >>> query = ModelStorageQuery(node_id=some_uuid)
+
+        >>> # Query by capability with pagination
+        >>> query = ModelStorageQuery(
+        ...     capability_filter="registration.storage",
+        ...     limit=50,
+        ...     offset=100,
+        ... )
+    """
+
+    model_config = ConfigDict(frozen=True, extra="forbid", from_attributes=True)
+
+    node_id: UUID | None = Field(
+        default=None,
+        description="Filter by specific node ID (exact match)",
+    )
+    node_type: EnumNodeKind | None = Field(
+        default=None,
+        description="Filter by node type",
+    )
+    capability_filter: str | None = Field(
+        default=None,
+        description="Filter by capability name (nodes containing this capability)",
+    )
+    limit: int = Field(
+        default=100,
+        description="Maximum number of records to return",
+        ge=1,
+        le=1000,
+    )
+    offset: int = Field(
+        default=0,
+        description="Number of records to skip for pagination",
+        ge=0,
+    )
+
+    def is_single_record_query(self) -> bool:
+        """Check if this query targets a single record by node_id.
+
+        Returns:
+            True if node_id is specified, indicating a single-record lookup.
+        """
+        return self.node_id is not None
+
+
+__all__ = ["ModelStorageQuery"]