omnibase_infra 0.2.6__py3-none-any.whl

omnibase_infra/models/registration/model_node_registration.py

@@ -0,0 +1,162 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Node Registration Model.
+
+This module provides ModelNodeRegistration for persisted node registrations
+in the ONEX 2-way registration pattern.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Literal
+from uuid import UUID
+
+from pydantic import BaseModel, ConfigDict, Field, HttpUrl, field_validator
+
+from omnibase_core.models.primitives.model_semver import ModelSemVer
+from omnibase_infra.models.registration.model_node_capabilities import (
+    ModelNodeCapabilities,
+)
+from omnibase_infra.models.registration.model_node_metadata import ModelNodeMetadata
+from omnibase_infra.utils import validate_endpoint_urls_dict
+
+
+class ModelNodeRegistration(BaseModel):
+    """Model for persisted node registration in PostgreSQL.
+
+    Represents a node's complete registration state for persistence.
+    Created from introspection events and updated with heartbeat data.
+
+    Validation Design:
+        This model uses **strict Literal validation** for ``node_type``, accepting
+        only the canonical ONEX types: "effect", "compute", "reducer", "orchestrator".
+
+        This differs intentionally from ``ModelNodeHeartbeatEvent``, which uses
+        relaxed ``str`` validation to support experimental node types in transient
+        heartbeat messages. The rationale:
+
+        - **ModelNodeRegistration** (strict): Represents canonical node catalog
+          entries persisted to PostgreSQL. Must align with the source
+          ``ModelNodeIntrospectionEvent`` constraints. Invalid types would corrupt
+          the registry.
+        - **ModelNodeHeartbeatEvent** (relaxed): Transient operational messages
+          that may include experimental or custom node types not yet in the
+          canonical set.
+
+    Attributes:
+        node_id: Unique node identifier.
+        node_type: ONEX node type. Uses strict Literal["effect", "compute",
+            "reducer", "orchestrator"] validation to ensure registry integrity.
+            See field-level design note for rationale.
+        node_version: Semantic version of the node (validated against semver).
+        capabilities: Structured node capabilities.
+        endpoints: Dictionary of exposed endpoints (name -> URL).
+        metadata: Additional node metadata.
+        health_endpoint: URL for health check endpoint.
+        last_heartbeat: Timestamp of last received heartbeat.
+        registered_at: Timestamp when node was first registered.
+        updated_at: Timestamp of last update.
+
+    Example:
+        >>> from datetime import datetime, UTC
+        >>> from uuid import uuid4
+        >>> now = datetime.now(UTC)
+        >>> registration = ModelNodeRegistration(
+        ...     node_id=uuid4(),
+        ...     node_type="effect",
+        ...     capabilities={"postgres": True},
+        ...     endpoints={"health": "http://localhost:8080/health"},
+        ...     health_endpoint="http://localhost:8080/health",
+        ...     registered_at=now,
+        ...     updated_at=now,
+        ... )
+
+    See Also:
+        - :class:`ModelNodeIntrospectionEvent`: Source event for registrations.
+          Uses the same strict ``Literal`` validation for ``node_type``.
+        - :class:`ModelNodeHeartbeatEvent`: Transient health events.
+          Uses relaxed ``str`` validation to support experimental node types.
+    """
+
+    model_config = ConfigDict(
+        frozen=False,  # Mutable for updates
+        extra="forbid",
+        from_attributes=True,
+    )
+
+    # Identity
+    node_id: UUID = Field(..., description="Unique node identifier")
+    # Design Note: node_type uses strict Literal validation to match the source
+    # introspection event constraints. ModelNodeRegistration is created from
+    # ModelNodeIntrospectionEvent data, so type constraints must align. Unlike
+    # ModelNodeHeartbeatEvent (which uses relaxed str validation to support
+    # experimental node types), registrations represent canonical node catalog
+    # entries that require strict ONEX type compliance.
+    # See ModelNodeIntrospectionEvent for source validation.
+    node_type: Literal["effect", "compute", "reducer", "orchestrator"] = Field(
+        ..., description="ONEX node type"
+    )
+    node_version: ModelSemVer = Field(
+        default_factory=lambda: ModelSemVer(major=1, minor=0, patch=0),
+        description="Semantic version of the node",
+    )
+
+    @field_validator("node_version", mode="before")
+    @classmethod
+    def parse_node_version(cls, v: ModelSemVer | str) -> ModelSemVer:
+        """Parse node_version from string or ModelSemVer.
+
+        Args:
+            v: Either a ModelSemVer instance or a semver string.
+
+        Returns:
+            Validated ModelSemVer instance.
+
+        Raises:
+            ValueError: If the string is not a valid semantic version.
+        """
+        if isinstance(v, str):
+            try:
+                return ModelSemVer.parse(v)
+            except Exception as e:
+                raise ValueError(f"node_version: {e!s}") from e
+        return v
+
+    # Capabilities and endpoints
+    capabilities: ModelNodeCapabilities = Field(
+        default_factory=ModelNodeCapabilities, description="Node capabilities"
+    )
+    endpoints: dict[str, str] = Field(
+        default_factory=dict, description="Exposed endpoints (name -> URL)"
+    )
+
+    @field_validator("endpoints")
+    @classmethod
+    def validate_endpoint_urls(cls, v: dict[str, str]) -> dict[str, str]:
+        """Validate that all endpoint values are valid URLs.
+
+        Delegates to shared utility for consistent validation across all models.
+        """
+        return validate_endpoint_urls_dict(v)
+
+    metadata: ModelNodeMetadata = Field(
+        default_factory=ModelNodeMetadata, description="Additional node metadata"
+    )
+
+    # Health tracking
+    health_endpoint: HttpUrl | None = Field(
+        default=None, description="URL for health check endpoint"
+    )
+    last_heartbeat: datetime | None = Field(
+        default=None, description="Timestamp of last received heartbeat"
+    )
+
+    # Timestamps
+    registered_at: datetime = Field(
+        ..., description="Timestamp when node was first registered"
+    )
+    updated_at: datetime = Field(..., description="Timestamp of last update")
+
+
+__all__ = ["ModelNodeRegistration"]

omnibase_infra/models/registration/model_node_registration_record.py

@@ -0,0 +1,162 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Node Registration Record for PostgreSQL Intent.
+
+This module provides ModelNodeRegistrationRecord, a frozen record model
+suitable for use with ModelPostgresUpsertRegistrationIntent.
+
+Architecture:
+    This model extends ModelRegistrationRecordBase from omnibase_core to ensure
+    protocol compliance and consistent serialization behavior. It captures the
+    minimal set of fields needed for node registration persistence.
+
+    Unlike ModelNodeRegistration (which is mutable and has complex validation),
+    this record is:
+    - Immutable (frozen=True)
+    - Minimal (only essential fields)
+    - Compliant with ProtocolRegistrationRecord
+
+    Strong Typing:
+    This model uses strongly-typed models for capabilities and metadata:
+    - capabilities: ModelNodeCapabilities - typed capability flags
+    - metadata: ModelNodeMetadata - typed deployment metadata
+
+    These models replace the legacy dict[str, Any] pattern to comply with
+    the ONEX "no Any types" rule. Both models use extra="allow" to support
+    custom fields while maintaining type safety for known fields.
+
+Thread Safety:
+    ModelNodeRegistrationRecord is immutable after creation, making it
+    thread-safe for concurrent read access.
+
+Related:
+    - ModelNodeRegistration: Full mutable registration model
+    - ModelPostgresUpsertRegistrationIntent: Intent that uses this record
+    - ModelNodeCapabilities: Strongly-typed capabilities model
+    - ModelNodeMetadata: Strongly-typed metadata model
+    - OMN-889: Infrastructure MVP
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from uuid import UUID
+
+from pydantic import Field, field_validator
+
+from omnibase_core.enums.enum_node_kind import EnumNodeKind
+from omnibase_core.models.intents import ModelRegistrationRecordBase
+from omnibase_core.models.primitives.model_semver import ModelSemVer
+from omnibase_infra.models.registration.model_node_capabilities import (
+    ModelNodeCapabilities,
+)
+from omnibase_infra.models.registration.model_node_metadata import ModelNodeMetadata
+
+
+class ModelNodeRegistrationRecord(ModelRegistrationRecordBase):
+    """Frozen record for node registration in PostgreSQL.
+
+    This is a minimal, immutable record designed for use with
+    ModelPostgresUpsertRegistrationIntent. It captures the essential
+    fields needed for node registration without complex validation.
+
+    The record is serialized by the Effect layer when persisting to PostgreSQL.
+    The to_persistence_dict() method (inherited from ModelRegistrationRecordBase)
+    handles JSON-compatible serialization.
+
+    Strong Typing:
+        Uses ModelNodeCapabilities and ModelNodeMetadata instead of dict[str, Any]
+        to comply with ONEX "no Any types" rule. Both models use extra="allow"
+        to support custom fields while providing type safety for known fields.
+
+    Attributes:
+        node_id: Unique node identifier (UUID).
+        node_type: ONEX node type (effect, compute, reducer, orchestrator).
+        node_version: Semantic version of the node.
+        capabilities: Strongly-typed node capabilities (ModelNodeCapabilities).
+        endpoints: Exposed endpoints as name -> URL mapping.
+        metadata: Strongly-typed node metadata (ModelNodeMetadata).
+        health_endpoint: Optional URL for health check endpoint.
+        registered_at: Timestamp when node was first registered.
+        updated_at: Timestamp of last update.
+
+    Example:
+        >>> from datetime import datetime, UTC
+        >>> from uuid import uuid4
+        >>> from omnibase_core.enums.enum_node_kind import EnumNodeKind
+        >>> from omnibase_core.models.primitives.model_semver import ModelSemVer
+        >>> from omnibase_infra.models.registration import (
+        ...     ModelNodeCapabilities,
+        ...     ModelNodeMetadata,
+        ... )
+        >>> now = datetime.now(UTC)
+        >>> record = ModelNodeRegistrationRecord(
+        ...     node_id=uuid4(),
+        ...     node_type=EnumNodeKind.EFFECT,
+        ...     node_version=ModelSemVer(major=1, minor=0, patch=0),
+        ...     capabilities=ModelNodeCapabilities(postgres=True),
+        ...     endpoints={"health": "http://localhost:8080/health"},
+        ...     metadata=ModelNodeMetadata(environment="production"),
+        ...     health_endpoint="http://localhost:8080/health",
+        ...     registered_at=now,
+        ...     updated_at=now,
+        ... )
+        >>> db_data = record.to_persistence_dict()
+        >>> assert isinstance(db_data["node_id"], str)  # UUID serialized
+    """
+
+    # Identity
+    node_id: UUID = Field(..., description="Unique node identifier")
+    node_type: EnumNodeKind = Field(..., description="ONEX node type")
+    node_version: ModelSemVer = Field(
+        default_factory=lambda: ModelSemVer(major=1, minor=0, patch=0),
+        description="Semantic version of the node",
+    )
+
+    @field_validator("node_version", mode="before")
+    @classmethod
+    def parse_node_version(cls, v: ModelSemVer | str) -> ModelSemVer:
+        """Parse node_version from string or ModelSemVer.
+
+        Args:
+            v: Either a ModelSemVer instance or a semver string.
+
+        Returns:
+            Validated ModelSemVer instance.
+
+        Raises:
+            ValueError: If the string is not a valid semantic version.
+        """
+        if isinstance(v, str):
+            try:
+                return ModelSemVer.parse(v)
+            except Exception as e:
+                raise ValueError(f"node_version: {e!s}") from e
+        return v
+
+    # Capabilities and endpoints - strongly typed models
+    capabilities: ModelNodeCapabilities = Field(
+        default_factory=ModelNodeCapabilities,
+        description="Strongly-typed node capabilities",
+    )
+    endpoints: dict[str, str] = Field(
+        default_factory=dict, description="Exposed endpoints (name -> URL)"
+    )
+    metadata: ModelNodeMetadata = Field(
+        default_factory=ModelNodeMetadata,
+        description="Strongly-typed node metadata",
+    )
+
+    # Health tracking
+    health_endpoint: str | None = Field(
+        default=None, description="URL for health check endpoint"
+    )
+
+    # Timestamps
+    registered_at: datetime = Field(
+        ..., description="Timestamp when node was first registered"
+    )
+    updated_at: datetime = Field(..., description="Timestamp of last update")
+
+
+__all__ = ["ModelNodeRegistrationRecord"]

omnibase_infra/models/registry/__init__.py

@@ -0,0 +1,29 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Registry Models Module.
+
+This module provides Pydantic models for message type registry functionality
+in the ONEX runtime dispatch infrastructure.
+
+Models:
+    - ModelDomainConstraint: Domain ownership rules and cross-domain constraints
+    - ModelMessageTypeEntry: Registry entry for message type to handler mappings
+
+Related:
+    - OMN-937: Central Message Type Registry implementation
+    - runtime.registry: Registry implementation using these models
+
+.. versionadded:: 0.5.0
+"""
+
+from omnibase_infra.models.registry.model_domain_constraint import (
+    ModelDomainConstraint,
+)
+from omnibase_infra.models.registry.model_message_type_entry import (
+    ModelMessageTypeEntry,
+)
+
+__all__: list[str] = [
+    "ModelDomainConstraint",
+    "ModelMessageTypeEntry",
+]

omnibase_infra/models/registry/model_domain_constraint.py

@@ -0,0 +1,202 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""
+Domain Constraint Model.
+
+Defines domain ownership rules and cross-domain consumption constraints for
+message type routing in the ONEX runtime.
+
+Design Principles:
+    - Domain ownership is derived from topic name (onex.<domain>.*) AND message type
+      registry entry domain field
+    - Domain isolation by default: handlers can only process messages from their domain
+    - Cross-domain consumption requires explicit opt-in via allowed_cross_domains
+    - Clear fail-fast validation at startup time
+
+Topic Domain Extraction:
+    Domain is extracted from the first segment after the namespace prefix:
+    - "onex.registration.events" -> domain = "registration"
+    - "dev.user.events.v1" -> domain = "user"
+    - "prod.order.commands.v2" -> domain = "order"
+
+Related:
+    - OMN-937: Central Message Type Registry implementation
+    - RegistryMessageType: Uses domain constraints for validation
+
+.. versionadded:: 0.5.0
+"""
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from omnibase_infra.models.validation import ModelValidationOutcome
+
+
+class ModelDomainConstraint(BaseModel):
+    """
+    Domain constraint configuration for message type routing.
+
+    Defines which domains a handler can consume messages from and enforces
+    domain ownership rules. By default, handlers are isolated to their own
+    domain and must explicitly opt-in to cross-domain message consumption.
+
+    Attributes:
+        owning_domain: The domain that owns this handler/message type.
+            Must match the domain extracted from topic for same-domain processing.
+            Example: "registration", "user", "order"
+        allowed_cross_domains: Set of domains this handler can consume from
+            in addition to its own domain. Empty by default (domain isolation).
+            Example: {"user", "order"} allows consuming from user.* and order.* topics
+        allow_all_domains: If True, allows consumption from any domain.
+            Use sparingly - only for truly domain-agnostic handlers.
+            Overrides allowed_cross_domains if True.
+        require_explicit_opt_in: If True, cross-domain consumption raises error
+            unless explicitly allowed. Default True for security.
+
+    Example:
+        >>> # Registration handler only processes registration messages
+        >>> constraint = ModelDomainConstraint(owning_domain="registration")
+        >>> constraint.can_consume_from("registration")
+        True
+        >>> constraint.can_consume_from("user")
+        False
+
+        >>> # Handler with cross-domain access
+        >>> constraint = ModelDomainConstraint(
+        ...     owning_domain="notification",
+        ...     allowed_cross_domains={"user", "order"},
+        ... )
+        >>> constraint.can_consume_from("user")
+        True
+        >>> constraint.can_consume_from("billing")
+        False
+
+    Thread Safety:
+        This model is immutable (frozen=True) and thread-safe for concurrent access.
+
+    .. versionadded:: 0.5.0
+    """
+
+    model_config = ConfigDict(
+        frozen=True,
+        extra="forbid",
+        from_attributes=True,
+    )
+
+    owning_domain: str = Field(
+        ...,
+        description=(
+            "The domain that owns this handler/message type. "
+            "Must match topic domain for same-domain processing."
+        ),
+        min_length=1,
+        max_length=100,
+    )
+
+    allowed_cross_domains: frozenset[str] = Field(
+        default_factory=frozenset,
+        description=(
+            "Domains this handler can consume from in addition to owning_domain. "
+            "Empty by default for domain isolation."
+        ),
+    )
+
+    allow_all_domains: bool = Field(
+        default=False,
+        description=(
+            "If True, allows consumption from any domain. "
+            "Overrides allowed_cross_domains. Use sparingly."
+        ),
+    )
+
+    require_explicit_opt_in: bool = Field(
+        default=True,
+        description=(
+            "If True, cross-domain consumption raises error unless explicitly "
+            "allowed via allowed_cross_domains or allow_all_domains."
+        ),
+    )
+
+    def can_consume_from(self, topic_domain: str) -> bool:
+        """
+        Check if this constraint allows consuming messages from the given domain.
+
+        Args:
+            topic_domain: The domain extracted from the topic being consumed.
+
+        Returns:
+            True if consumption is allowed, False otherwise.
+
+        Example:
+            >>> constraint = ModelDomainConstraint(owning_domain="registration")
+            >>> constraint.can_consume_from("registration")
+            True
+            >>> constraint.can_consume_from("user")
+            False
+
+        .. versionadded:: 0.5.0
+        """
+        # Allow all domains if flag is set
+        if self.allow_all_domains:
+            return True
+
+        # Always allow own domain
+        if topic_domain == self.owning_domain:
+            return True
+
+        # Check explicit cross-domain allowlist
+        if topic_domain in self.allowed_cross_domains:
+            return True
+
+        return False
+
+    def validate_consumption(
+        self,
+        topic_domain: str,
+        message_type: str,
+    ) -> ModelValidationOutcome:
+        """
+        Validate if consumption is allowed and return detailed error if not.
+
+        This method provides detailed validation with error messages suitable
+        for fail-fast behavior at startup time.
+
+        Args:
+            topic_domain: The domain extracted from the topic.
+            message_type: The message type being consumed (for error messages).
+
+        Returns:
+            ModelValidationOutcome with is_valid=True if valid,
+            or is_valid=False with error_message if invalid.
+
+        Example:
+            >>> constraint = ModelDomainConstraint(owning_domain="registration")
+            >>> outcome = constraint.validate_consumption("user", "UserCreated")
+            >>> outcome.is_valid
+            False
+
+        .. versionadded:: 0.5.0
+        .. versionchanged:: 0.6.0
+            Return type changed from tuple[bool, str | None] to ModelValidationOutcome.
+        """
+        if self.can_consume_from(topic_domain):
+            return ModelValidationOutcome.success()
+
+        # Build detailed error message
+        if self.require_explicit_opt_in:
+            allowed = [self.owning_domain]
+            allowed.extend(sorted(self.allowed_cross_domains))
+            return ModelValidationOutcome.failure(
+                f"Domain mismatch: handler in domain '{self.owning_domain}' cannot "
+                f"consume message type '{message_type}' from domain '{topic_domain}'. "
+                f"Allowed domains: {allowed}. "
+                f"To enable cross-domain consumption, add '{topic_domain}' to "
+                f"allowed_cross_domains or set allow_all_domains=True."
+            )
+        else:
+            return ModelValidationOutcome.failure(
+                f"Domain mismatch: handler domain '{self.owning_domain}' does not "
+                f"match topic domain '{topic_domain}' for message type '{message_type}'."
+            )
+
+
+__all__ = ["ModelDomainConstraint"]