omnibase_infra 0.2.1__py3-none-any.whl

omnibase_infra/handlers/models/consul/model_consul_register_payload.py

@@ -0,0 +1,53 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Consul Register Payload Model.
+
+This module provides the payload model for consul.register result.
+"""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import ConfigDict, Field
+
+from omnibase_infra.handlers.models.consul.model_payload_consul import (
+    ModelPayloadConsul,
+)
+from omnibase_infra.handlers.models.consul.registry_payload_consul import (
+    RegistryPayloadConsul,
+)
+
+
+@RegistryPayloadConsul.register("register")
+class ModelConsulRegisterPayload(ModelPayloadConsul):
+    """Payload for consul.register result.
+
+    Attributes:
+        operation_type: Discriminator literal "register".
+        registered: True if the service was registered successfully.
+        name: The service name.
+        consul_service_id: The Consul service identifier (user-defined string).
+
+    Note:
+        consul_service_id is a Consul-specific identifier that is a user-defined string,
+        NOT a UUID. The Consul API accepts any string as a service ID. This field is
+        named with the 'consul_' prefix to avoid pattern validator warnings that expect
+        fields ending in '_id' to be UUIDs.
+    """
+
+    model_config = ConfigDict(strict=True, frozen=True, extra="forbid")
+
+    operation_type: Literal["register"] = Field(
+        default="register", description="Discriminator for payload type"
+    )
+    registered: bool = Field(
+        description="True if the service was registered successfully"
+    )
+    name: str = Field(description="The service name")
+    consul_service_id: str = Field(
+        description="The Consul service identifier (user-defined string, not a UUID)"
+    )
+
+
+__all__: list[str] = ["ModelConsulRegisterPayload"]

omnibase_infra/handlers/models/consul/model_consul_retry_config.py

@@ -0,0 +1,66 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Consul Retry Configuration Model.
+
+This module provides the Pydantic configuration model for Consul operation
+retry logic with exponential backoff.
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class ModelConsulRetryConfig(BaseModel):
+    """Configuration for Consul operation retry logic with exponential backoff.
+
+    Attributes:
+        max_attempts: Maximum number of retry attempts (1-10)
+        initial_delay_seconds: Initial backoff delay in seconds (0.1-60.0)
+        max_delay_seconds: Maximum backoff delay in seconds (1.0-300.0)
+        exponential_base: Exponential backoff multiplier (1.5-4.0)
+
+    Example:
+        >>> retry_config = ModelConsulRetryConfig(
+        ...     max_attempts=3,
+        ...     initial_delay_seconds=1.0,
+        ...     max_delay_seconds=30.0,
+        ...     exponential_base=2.0,
+        ... )
+        >>> # Backoff sequence: 1.0s, 2.0s, 4.0s, 8.0s, 16.0s (capped at 30.0s)
+    """
+
+    model_config = ConfigDict(
+        strict=True,
+        frozen=True,
+        extra="forbid",
+        from_attributes=True,
+    )
+
+    max_attempts: int = Field(
+        default=3,
+        ge=1,
+        le=10,
+        description="Maximum retry attempts for failed operations",
+    )
+    initial_delay_seconds: float = Field(
+        default=1.0,
+        ge=0.1,
+        le=60.0,
+        description="Initial delay before first retry",
+    )
+    max_delay_seconds: float = Field(
+        default=30.0,
+        ge=1.0,
+        le=300.0,
+        description="Maximum delay cap for exponential backoff",
+    )
+    exponential_base: float = Field(
+        default=2.0,
+        ge=1.5,
+        le=4.0,
+        description="Base multiplier for exponential backoff calculation",
+    )
+
+
+__all__: list[str] = ["ModelConsulRetryConfig"]

omnibase_infra/handlers/models/consul/model_payload_consul.py

@@ -0,0 +1,66 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Base Consul payload model for registry-based type resolution.
+
+This module provides:
+- ModelPayloadConsul: Base model for all Consul handler payloads
+
+Design Pattern:
+    Instead of maintaining explicit union types like:
+        ConsulPayload = ModelConsulKVGetFoundPayload | ModelConsulRegisterPayload | ...
+
+    Payload models self-register via decorator:
+        @RegistryPayloadConsul.register("kv_get_found")
+        class ModelConsulKVGetFoundPayload(ModelPayloadConsul): ...
+
+    The registry resolves types dynamically during Pydantic validation,
+    enabling new payload types to be added without modifying existing code.
+
+Related:
+    - RegistryPayloadConsul: Decorator-based registry for payload type discovery
+    - EnumConsulOperationType: Operation type enum for discriminator
+    - OMN-1007: Union reduction refactoring
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict
+
+
+class ModelPayloadConsul(BaseModel):
+    """Base model for all registry-managed Consul payloads.
+
+    All concrete Consul payload models MUST:
+    1. Inherit from this base class
+    2. Use @RegistryPayloadConsul.register("operation_type") decorator
+    3. Define operation_type as Literal["type"] with matching default
+    4. Be frozen (immutable) for thread safety
+
+    This base class defines the common interface that all payloads share,
+    enabling type-safe access to common fields without type narrowing.
+
+    Example:
+        @RegistryPayloadConsul.register("kv_get_found")
+        class ModelConsulKVGetFoundPayload(ModelPayloadConsul):
+            operation_type: Literal["kv_get_found"] = "kv_get_found"
+            key: str
+            value: str | None
+            ...
+
+    Attributes:
+        operation_type: Operation type identifier used for type discrimination.
+
+    Related:
+        - RegistryPayloadConsul: Registration decorator and type lookup
+        - EnumConsulOperationType: Enum of valid operation types
+    """
+
+    model_config = ConfigDict(frozen=True, extra="forbid", from_attributes=True)
+
+    operation_type: str
+    """Operation type identifier used for type discrimination."""
+
+
+__all__: list[str] = [
+    "ModelPayloadConsul",
+]

omnibase_infra/handlers/models/consul/registry_payload_consul.py

@@ -0,0 +1,214 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Registry for Consul payload types with decorator-based registration.
+
+This module provides:
+- RegistryPayloadConsul: Decorator-based registry for payload type discovery
+
+Design Pattern:
+    Instead of maintaining explicit union types like:
+        ConsulPayload = ModelConsulKVGetFoundPayload | ModelConsulRegisterPayload | ...
+
+    Payload models self-register via decorator:
+        @RegistryPayloadConsul.register("kv_get_found")
+        class ModelConsulKVGetFoundPayload(ModelPayloadConsul): ...
+
+    The registry resolves types dynamically during Pydantic validation,
+    enabling new payload types to be added without modifying existing code.
+
+Related:
+    - ModelPayloadConsul: Base model for Consul payloads
+    - EnumConsulOperationType: Operation type enum for discriminator
+    - OMN-1007: Union reduction refactoring
+"""
+
+from __future__ import annotations
+
+import threading
+import warnings
+from collections.abc import Callable
+from typing import TYPE_CHECKING, ClassVar, TypeVar
+
+from omnibase_infra.enums import EnumInfraTransportType
+from omnibase_infra.errors import ModelInfraErrorContext, ProtocolConfigurationError
+
+if TYPE_CHECKING:
+    from omnibase_infra.handlers.models.consul.model_payload_consul import (
+        ModelPayloadConsul,
+    )
+
+# TypeVar bound to ModelPayloadConsul to preserve subclass type through decorator
+_ConsulPayloadT = TypeVar("_ConsulPayloadT", bound="ModelPayloadConsul")
+
+
+class RegistryPayloadConsul:
+    """Registry for Consul payload model types with decorator-based registration.
+
+    This registry enables dynamic type resolution for Pydantic validation
+    without requiring explicit union type definitions.
+
+    Example:
+        @RegistryPayloadConsul.register("kv_get_found")
+        class ModelConsulKVGetFoundPayload(ModelPayloadConsul):
+            operation_type: Literal["kv_get_found"] = "kv_get_found"
+            ...
+
+        # Later, resolve type from operation_type
+        payload_cls = RegistryPayloadConsul.get_type("kv_get_found")
+        payload = payload_cls.model_validate(data)
+
+    Thread Safety:
+        All registration and mutation operations are protected by a class-level
+        threading.Lock to ensure thread-safe access. Read operations (get_type,
+        get_all_types, is_registered) are atomic dictionary operations and safe
+        for concurrent access. The lock ensures that check-and-set operations
+        in register() are atomic, preventing race conditions.
+    """
+
+    _types: ClassVar[dict[str, type[ModelPayloadConsul]]] = {}
+    _lock: ClassVar[threading.Lock] = threading.Lock()
+
+    @classmethod
+    def register(
+        cls, operation_type: str
+    ) -> Callable[[type[_ConsulPayloadT]], type[_ConsulPayloadT]]:
+        """Decorator to register a Consul payload model type.
+
+        Args:
+            operation_type: The operation type identifier (e.g., "kv_get_found",
+                          "register"). Must match the model's `operation_type`
+                          field value.
+
+        Returns:
+            Decorator function that registers the class and returns it unchanged.
+
+        Raises:
+            ValueError: If operation_type is already registered (prevents duplicates).
+
+        Example:
+            @RegistryPayloadConsul.register("kv_get_found")
+            class ModelConsulKVGetFoundPayload(ModelPayloadConsul):
+                operation_type: Literal["kv_get_found"] = "kv_get_found"
+                key: str
+                value: str | None
+                ...
+        """
+
+        def decorator(
+            payload_cls: type[_ConsulPayloadT],
+        ) -> type[_ConsulPayloadT]:
+            # Runtime type validation (outside lock - class inspection is read-only)
+            from omnibase_infra.handlers.models.consul.model_payload_consul import (
+                ModelPayloadConsul,
+            )
+
+            if not issubclass(payload_cls, ModelPayloadConsul):
+                context = ModelInfraErrorContext(
+                    transport_type=EnumInfraTransportType.CONSUL,
+                    operation="register_payload_type",
+                )
+                raise ProtocolConfigurationError(
+                    f"Registered class {payload_cls.__name__!r} must be a subclass "
+                    f"of ModelPayloadConsul, got {payload_cls.__mro__}",
+                    context=context,
+                )
+
+            # Thread-safe registration with atomic check-and-set
+            with cls._lock:
+                if operation_type in cls._types:
+                    context = ModelInfraErrorContext(
+                        transport_type=EnumInfraTransportType.CONSUL,
+                        operation="register_payload_type",
+                    )
+                    raise ProtocolConfigurationError(
+                        f"Consul payload operation_type '{operation_type}' already registered "
+                        f"to {cls._types[operation_type].__name__}. "
+                        f"Cannot register {payload_cls.__name__}.",
+                        context=context,
+                    )
+                cls._types[operation_type] = payload_cls
+            return payload_cls
+
+        return decorator
+
+    @classmethod
+    def get_type(cls, operation_type: str) -> type[ModelPayloadConsul]:
+        """Get the payload model class for a given operation type.
+
+        Args:
+            operation_type: The operation type identifier.
+
+        Returns:
+            The registered payload model class.
+
+        Raises:
+            KeyError: If operation_type is not registered.
+
+        Example:
+            payload_cls = RegistryPayloadConsul.get_type("kv_get_found")
+            payload = payload_cls.model_validate({"operation_type": "kv_get_found", ...})
+        """
+        if operation_type not in cls._types:
+            registered = ", ".join(sorted(cls._types.keys())) or "(none)"
+            raise KeyError(
+                f"Unknown Consul operation_type '{operation_type}'. "
+                f"Registered types: {registered}"
+            )
+        return cls._types[operation_type]
+
+    @classmethod
+    def get_all_types(cls) -> dict[str, type[ModelPayloadConsul]]:
+        """Get all registered Consul payload types.
+
+        Returns:
+            Dict mapping operation_type strings to payload model classes.
+
+        Example:
+            all_types = RegistryPayloadConsul.get_all_types()
+            for op_type, payload_cls in all_types.items():
+                print(f"{op_type}: {payload_cls.__name__}")
+        """
+        return dict(cls._types)
+
+    @classmethod
+    def is_registered(cls, operation_type: str) -> bool:
+        """Check if an operation type is registered.
+
+        Args:
+            operation_type: The operation type identifier.
+
+        Returns:
+            True if registered, False otherwise.
+
+        Example:
+            if RegistryPayloadConsul.is_registered("kv_get_found"):
+                payload_cls = RegistryPayloadConsul.get_type("kv_get_found")
+        """
+        return operation_type in cls._types
+
+    @classmethod
+    def clear(cls) -> None:
+        """Clear all registered types.
+
+        Warning:
+            This method is intended for **testing purposes only**.
+            Calling it in production code will emit a warning.
+            It breaks the immutability guarantee after startup.
+
+        Thread Safety:
+            This method is protected by the class-level lock to ensure
+            thread-safe clearing of the registry.
+        """
+        warnings.warn(
+            "RegistryPayloadConsul.clear() is intended for testing only. "
+            "Do not use in production code.",
+            UserWarning,
+            stacklevel=2,
+        )
+        with cls._lock:
+            cls._types.clear()
+
+
+__all__: list[str] = [
+    "RegistryPayloadConsul",  # Consul payload registry
+]

omnibase_infra/handlers/models/graph/__init__.py

@@ -0,0 +1,35 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Graph handler models package.
+
+Provides strongly-typed Pydantic models for graph database operations.
+Supports Memgraph and Neo4j via Bolt protocol with Cypher queries.
+"""
+
+from omnibase_infra.handlers.models.graph.enum_graph_operation_type import (
+    EnumGraphOperationType,
+)
+from omnibase_infra.handlers.models.graph.model_graph_execute_payload import (
+    ModelGraphExecutePayload,
+)
+from omnibase_infra.handlers.models.graph.model_graph_handler_config import (
+    ModelGraphHandlerConfig,
+)
+from omnibase_infra.handlers.models.graph.model_graph_handler_payload import (
+    GraphPayload,
+    ModelGraphHandlerPayload,
+)
+from omnibase_infra.handlers.models.graph.model_graph_query_payload import (
+    ModelGraphQueryPayload,
+)
+from omnibase_infra.handlers.models.graph.model_graph_record import ModelGraphRecord
+
+__all__: list[str] = [
+    "EnumGraphOperationType",
+    "GraphPayload",
+    "ModelGraphExecutePayload",
+    "ModelGraphHandlerConfig",
+    "ModelGraphHandlerPayload",
+    "ModelGraphQueryPayload",
+    "ModelGraphRecord",
+]

omnibase_infra/handlers/models/graph/enum_graph_operation_type.py

@@ -0,0 +1,20 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Graph operation type enumeration for discriminated unions."""
+
+from enum import Enum
+
+
+class EnumGraphOperationType(str, Enum):
+    """Graph operation types for handler routing.
+
+    Attributes:
+        QUERY: Execute a Cypher query that returns results
+        EXECUTE: Execute a Cypher statement (write operation)
+    """
+
+    QUERY = "graph.query"
+    EXECUTE = "graph.execute"
+
+
+__all__: list[str] = ["EnumGraphOperationType"]

omnibase_infra/handlers/models/graph/model_graph_execute_payload.py

@@ -0,0 +1,38 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Execute payload model for Graph handler."""
+
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from omnibase_infra.models.types import JsonDict
+
+
+class ModelGraphExecutePayload(BaseModel):
+    """Payload for graph.execute operation result.
+
+    Attributes:
+        operation_type: Discriminator for payload type
+        cypher: The Cypher statement that was executed
+        counters: Operation counters (nodes_created, relationships_created, etc.)
+        success: Whether the execution was successful
+    """
+
+    model_config = ConfigDict(strict=True, frozen=True, extra="forbid")
+
+    operation_type: Literal["graph.execute"] = Field(
+        default="graph.execute",
+        description="Operation type discriminator",
+    )
+    cypher: str = Field(description="The Cypher statement that was executed")
+    counters: JsonDict = Field(
+        default_factory=dict,
+        description="Operation counters (nodes_created, etc.)",
+    )
+    success: bool = Field(
+        default=True, description="Whether the execution was successful"
+    )
+
+
+__all__: list[str] = ["ModelGraphExecutePayload"]

omnibase_infra/handlers/models/graph/model_graph_handler_config.py

@@ -0,0 +1,54 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Configuration model for HandlerGraph."""
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class ModelGraphHandlerConfig(BaseModel):
+    """Configuration for Graph handler initialization.
+
+    Supports both Memgraph and Neo4j via Bolt protocol.
+
+    Attributes:
+        uri: Bolt URI (e.g., bolt://localhost:7687)
+        username: Database username
+        password: Database password
+        database: Database name (default: neo4j for Neo4j, memgraph for Memgraph)
+        timeout_seconds: Request timeout in seconds
+        max_connection_pool_size: Maximum number of connections in pool
+    """
+
+    model_config = ConfigDict(strict=True, frozen=True, extra="forbid")
+
+    uri: str = Field(
+        default="bolt://localhost:7687",
+        description="Bolt URI for graph database",
+    )
+    username: str = Field(
+        default="",
+        description="Database username",
+    )
+    password: str = Field(
+        default="",
+        description="Database password",
+    )
+    database: str = Field(
+        default="memgraph",
+        description="Database name (memgraph or neo4j)",
+    )
+    timeout_seconds: float = Field(
+        default=30.0,
+        ge=0.1,
+        le=3600.0,
+        description="Request timeout in seconds",
+    )
+    max_connection_pool_size: int = Field(
+        default=50,
+        ge=1,
+        le=1000,
+        description="Maximum number of connections in pool",
+    )
+
+
+__all__: list[str] = ["ModelGraphHandlerConfig"]

omnibase_infra/handlers/models/graph/model_graph_handler_payload.py

@@ -0,0 +1,44 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Handler payload model for Graph operations."""
+
+from typing import Annotated
+
+from pydantic import BaseModel, ConfigDict, Discriminator, Field, Tag
+
+from omnibase_infra.handlers.models.graph.model_graph_execute_payload import (
+    ModelGraphExecutePayload,
+)
+from omnibase_infra.handlers.models.graph.model_graph_query_payload import (
+    ModelGraphQueryPayload,
+)
+
+
+def _get_graph_operation_type(value: object) -> str:
+    """Extract operation_type from Graph payload for discriminated union."""
+    if isinstance(value, dict):
+        return str(value.get("operation_type", ""))
+    return getattr(value, "operation_type", "")
+
+
+GraphPayload = Annotated[
+    Annotated[ModelGraphQueryPayload, Tag("graph.query")]
+    | Annotated[ModelGraphExecutePayload, Tag("graph.execute")],
+    Discriminator(_get_graph_operation_type),
+]
+"""Discriminated union of all Graph payload types."""
+
+
+class ModelGraphHandlerPayload(BaseModel):
+    """Wrapper for Graph handler payloads using discriminated union.
+
+    Attributes:
+        data: The typed payload from the discriminated union
+    """
+
+    model_config = ConfigDict(strict=True, frozen=True, extra="forbid")
+
+    data: GraphPayload = Field(description="The typed payload")
+
+
+__all__: list[str] = ["ModelGraphHandlerPayload", "GraphPayload"]

omnibase_infra/handlers/models/graph/model_graph_query_payload.py

@@ -0,0 +1,40 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Query payload model for Graph handler."""
+
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from omnibase_infra.handlers.models.graph.model_graph_record import ModelGraphRecord
+from omnibase_infra.models.types import JsonDict
+
+
+class ModelGraphQueryPayload(BaseModel):
+    """Payload for graph.query operation result.
+
+    Attributes:
+        operation_type: Discriminator for payload type
+        cypher: The Cypher query that was executed
+        records: List of result records
+        summary: Query execution summary (counters, timing, etc.)
+    """
+
+    model_config = ConfigDict(strict=True, frozen=True, extra="forbid")
+
+    operation_type: Literal["graph.query"] = Field(
+        default="graph.query",
+        description="Operation type discriminator",
+    )
+    cypher: str = Field(description="The Cypher query that was executed")
+    records: list[ModelGraphRecord] = Field(
+        default_factory=list,
+        description="List of result records",
+    )
+    summary: JsonDict = Field(
+        default_factory=dict,
+        description="Query execution summary",
+    )
+
+
+__all__: list[str] = ["ModelGraphQueryPayload"]

omnibase_infra/handlers/models/graph/model_graph_record.py

@@ -0,0 +1,22 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Graph record model for Cypher query results."""
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from omnibase_infra.models.types import JsonDict
+
+
+class ModelGraphRecord(BaseModel):
+    """Single record from a Cypher query result.
+
+    Attributes:
+        data: Record data as key-value pairs
+    """
+
+    model_config = ConfigDict(strict=True, frozen=True, extra="forbid")
+
+    data: JsonDict = Field(description="Record data as key-value pairs")
+
+
+__all__: list[str] = ["ModelGraphRecord"]