omnibase_infra 0.2.1__py3-none-any.whl

omnibase_infra/handlers/models/http/__init__.py

@@ -0,0 +1,50 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""HTTP Handler Models Module.
+
+This module exports Pydantic models for HTTP handler request/response structures.
+All models are strongly typed to eliminate Any usage.
+
+Exports:
+    EnumHttpOperationType: Discriminator enum for HTTP operation types
+    ModelPayloadHttp: Base model for registry-managed HTTP payloads
+    RegistryPayloadHttp: Decorator-based registry for HTTP payload types
+    ModelHttpGetPayload: Payload for http.get result
+    ModelHttpPostPayload: Payload for http.post result
+    HttpPayload: Discriminated union of all HTTP payload types
+    ModelHttpHandlerPayload: Wrapper containing discriminated union payload
+"""
+
+from omnibase_infra.handlers.models.http.enum_http_operation_type import (
+    EnumHttpOperationType,
+)
+from omnibase_infra.handlers.models.http.model_http_body_content import (
+    ModelHttpBodyContent,
+)
+from omnibase_infra.handlers.models.http.model_http_get_payload import (
+    ModelHttpGetPayload,
+)
+from omnibase_infra.handlers.models.http.model_http_handler_payload import (
+    HttpPayload,
+    ModelHttpHandlerPayload,
+)
+from omnibase_infra.handlers.models.http.model_http_post_payload import (
+    ModelHttpPostPayload,
+)
+from omnibase_infra.handlers.models.http.model_payload_http import (
+    ModelPayloadHttp,
+)
+from omnibase_infra.handlers.models.http.registry_payload_http import (
+    RegistryPayloadHttp,
+)
+
+__all__: list[str] = [
+    "EnumHttpOperationType",
+    "HttpPayload",
+    "ModelHttpBodyContent",
+    "ModelHttpGetPayload",
+    "ModelHttpHandlerPayload",
+    "ModelHttpPostPayload",
+    "ModelPayloadHttp",
+    "RegistryPayloadHttp",
+]

omnibase_infra/handlers/models/http/enum_http_operation_type.py

@@ -0,0 +1,29 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""HTTP Operation Type Enum.
+
+Defines the discriminator enum for HTTP operation types, used in the
+discriminated union for HTTP handler responses.
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+
+
+class EnumHttpOperationType(str, Enum):
+    """HTTP operation type discriminator.
+
+    Each value corresponds to a specific HTTP operation type and its
+    associated payload model in the HttpPayload discriminated union.
+
+    Attributes:
+        GET: GET request operation (ModelHttpGetPayload)
+        POST: POST request operation (ModelHttpPostPayload)
+    """
+
+    GET = "get"
+    POST = "post"
+
+
+__all__: list[str] = ["EnumHttpOperationType"]

omnibase_infra/handlers/models/http/model_http_body_content.py

@@ -0,0 +1,45 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""HTTP Body Content Model.
+
+This module provides a model to encapsulate HTTP request body content,
+grouping the raw body and optional pre-serialized bytes together.
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class ModelHttpBodyContent(BaseModel):
+    """Encapsulates HTTP request body content for request preparation.
+
+    Groups the raw body and optional pre-serialized bytes together to reduce
+    function parameter count while maintaining semantic clarity.
+
+    Attributes:
+        body: The request body content (str, dict, bytes, or None).
+            For POST requests, this is the payload to send.
+        pre_serialized: Pre-serialized JSON bytes for dict bodies.
+            When provided, avoids double serialization by reusing cached bytes
+            from size validation.
+    """
+
+    model_config = ConfigDict(
+        strict=False,  # Allow object type for body
+        frozen=True,
+        extra="forbid",
+        arbitrary_types_allowed=True,  # Allow bytes type
+    )
+
+    body: object = Field(
+        default=None,
+        description="Request body content (str, dict, bytes, or None)",
+    )
+    pre_serialized: bytes | None = Field(
+        default=None,
+        description="Pre-serialized JSON bytes for dict bodies",
+    )
+
+
+__all__: list[str] = ["ModelHttpBodyContent"]

omnibase_infra/handlers/models/http/model_http_get_payload.py

@@ -0,0 +1,88 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""HTTP GET Payload Model.
+
+This module provides the Pydantic model for http.get operation results.
+Uses the registry pattern for dynamic type resolution.
+
+Related:
+    - RegistryPayloadHttp: Payload type registration and lookup
+    - OMN-1007: Union reduction refactoring
+"""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import ConfigDict, Field
+
+from omnibase_core.types import JsonType
+from omnibase_infra.handlers.models.http.enum_http_operation_type import (
+    EnumHttpOperationType,
+)
+from omnibase_infra.handlers.models.http.model_payload_http import (
+    ModelPayloadHttp,
+)
+from omnibase_infra.handlers.models.http.registry_payload_http import (
+    RegistryPayloadHttp,
+)
+
+
+@RegistryPayloadHttp.register("get")
+class ModelHttpGetPayload(ModelPayloadHttp):
+    """Payload for http.get operation result.
+
+    This model is registered with RegistryPayloadHttp for dynamic type resolution.
+    Use @RegistryPayloadHttp.register("get") decorator pattern.
+
+    Contains the HTTP response from a GET request including status code,
+    headers, and response body.
+
+    Attributes:
+        operation_type: Discriminator set to "get"
+        status_code: HTTP response status code
+        headers: Response headers as key-value dictionary
+        body: Response body (parsed as JSON if content-type is application/json)
+
+    Example:
+        >>> payload = ModelHttpGetPayload(
+        ...     status_code=200,
+        ...     headers={"content-type": "application/json"},
+        ...     body={"message": "success"},
+        ... )
+        >>> print(payload.status_code)
+        200
+
+        # Dynamic type lookup:
+        >>> from omnibase_infra.handlers.models.http import RegistryPayloadHttp
+        >>> payload_cls = RegistryPayloadHttp.get_type("get")
+        >>> payload_cls.__name__
+        'ModelHttpGetPayload'
+    """
+
+    model_config = ConfigDict(
+        strict=True,
+        frozen=True,
+        extra="forbid",
+        from_attributes=True,
+    )
+
+    operation_type: Literal[EnumHttpOperationType.GET] = Field(
+        default=EnumHttpOperationType.GET,
+        description="Operation type discriminator",
+    )
+    status_code: int = Field(
+        ge=100,
+        le=599,
+        description="HTTP response status code",
+    )
+    headers: dict[str, str] = Field(
+        default_factory=dict,
+        description="Response headers as key-value dictionary",
+    )
+    body: JsonType = Field(
+        description="Response body",
+    )
+
+
+__all__: list[str] = ["ModelHttpGetPayload"]

omnibase_infra/handlers/models/http/model_http_handler_payload.py

@@ -0,0 +1,90 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""HTTP Handler Payload Model.
+
+This module provides the discriminated union type for HTTP operation payloads
+and the wrapper model that contains them.
+"""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+from pydantic import BaseModel, ConfigDict, Discriminator, Field, Tag
+
+from omnibase_infra.handlers.models.http.model_http_get_payload import (
+    ModelHttpGetPayload,
+)
+from omnibase_infra.handlers.models.http.model_http_post_payload import (
+    ModelHttpPostPayload,
+)
+
+
+def _http_payload_discriminator(value: object) -> str:
+    """Discriminator function for HttpPayload union.
+
+    Determines which payload type to use based on the operation_type field.
+
+    Args:
+        value: The raw value being validated (dict or model instance)
+
+    Returns:
+        The discriminator tag value matching the operation_type
+    """
+    if isinstance(value, dict):
+        operation_type = value.get("operation_type", "get")
+    else:
+        operation_type = getattr(value, "operation_type", "get")
+
+    # Handle both enum values and string values
+    if hasattr(operation_type, "value"):
+        return str(operation_type.value)
+    return str(operation_type)
+
+
+# Discriminated union of all HTTP payload types
+HttpPayload = Annotated[
+    Annotated[ModelHttpGetPayload, Tag("get")]
+    | Annotated[ModelHttpPostPayload, Tag("post")],
+    Discriminator(_http_payload_discriminator),
+]
+
+
+class ModelHttpHandlerPayload(BaseModel):
+    """Wrapper model for HTTP handler payloads.
+
+    Contains the discriminated union of all possible HTTP operation payloads.
+    This allows the HttpRestHandler to return a consistent payload wrapper while
+    the actual payload type varies based on the operation.
+
+    Attributes:
+        data: The operation-specific payload (discriminated union)
+
+    Example:
+        >>> from omnibase_infra.handlers.models.http import ModelHttpGetPayload
+        >>> get_payload = ModelHttpGetPayload(
+        ...     status_code=200,
+        ...     headers={"content-type": "application/json"},
+        ...     body={"message": "success"},
+        ... )
+        >>> wrapper = ModelHttpHandlerPayload(data=get_payload)
+        >>> print(wrapper.data.operation_type)
+        <EnumHttpOperationType.GET: 'get'>
+    """
+
+    model_config = ConfigDict(
+        strict=True,
+        frozen=True,
+        extra="forbid",
+        from_attributes=True,
+    )
+
+    data: HttpPayload = Field(
+        description="Operation-specific payload",
+    )
+
+
+__all__: list[str] = [
+    "HttpPayload",
+    "ModelHttpHandlerPayload",
+]

omnibase_infra/handlers/models/http/model_http_post_payload.py

@@ -0,0 +1,88 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""HTTP POST Payload Model.
+
+This module provides the Pydantic model for http.post operation results.
+Uses the registry pattern for dynamic type resolution.
+
+Related:
+    - RegistryPayloadHttp: Payload type registration and lookup
+    - OMN-1007: Union reduction refactoring
+"""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import ConfigDict, Field
+
+from omnibase_core.types import JsonType
+from omnibase_infra.handlers.models.http.enum_http_operation_type import (
+    EnumHttpOperationType,
+)
+from omnibase_infra.handlers.models.http.model_payload_http import (
+    ModelPayloadHttp,
+)
+from omnibase_infra.handlers.models.http.registry_payload_http import (
+    RegistryPayloadHttp,
+)
+
+
+@RegistryPayloadHttp.register("post")
+class ModelHttpPostPayload(ModelPayloadHttp):
+    """Payload for http.post operation result.
+
+    This model is registered with RegistryPayloadHttp for dynamic type resolution.
+    Use @RegistryPayloadHttp.register("post") decorator pattern.
+
+    Contains the HTTP response from a POST request including status code,
+    headers, and response body.
+
+    Attributes:
+        operation_type: Discriminator set to "post"
+        status_code: HTTP response status code
+        headers: Response headers as key-value dictionary
+        body: Response body (parsed as JSON if content-type is application/json)
+
+    Example:
+        >>> payload = ModelHttpPostPayload(
+        ...     status_code=201,
+        ...     headers={"content-type": "application/json", "location": "/items/1"},
+        ...     body={"id": 1, "created": True},
+        ... )
+        >>> print(payload.status_code)
+        201
+
+        # Dynamic type lookup:
+        >>> from omnibase_infra.handlers.models.http import RegistryPayloadHttp
+        >>> payload_cls = RegistryPayloadHttp.get_type("post")
+        >>> payload_cls.__name__
+        'ModelHttpPostPayload'
+    """
+
+    model_config = ConfigDict(
+        strict=True,
+        frozen=True,
+        extra="forbid",
+        from_attributes=True,
+    )
+
+    operation_type: Literal[EnumHttpOperationType.POST] = Field(
+        default=EnumHttpOperationType.POST,
+        description="Operation type discriminator",
+    )
+    status_code: int = Field(
+        ge=100,
+        le=599,
+        description="HTTP response status code",
+    )
+    headers: dict[str, str] = Field(
+        default_factory=dict,
+        description="Response headers as key-value dictionary",
+    )
+    body: JsonType = Field(
+        description="Response body",
+    )
+
+
+__all__: list[str] = ["ModelHttpPostPayload"]

omnibase_infra/handlers/models/http/model_payload_http.py

@@ -0,0 +1,66 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Base HTTP payload model for registry-based type resolution.
+
+This module provides:
+- ModelPayloadHttp: Base model for all HTTP handler payloads
+
+Design Pattern:
+    Instead of maintaining explicit union types like:
+        HttpPayload = ModelHttpGetPayload | ModelHttpPostPayload | ...
+
+    Payload models self-register via decorator:
+        @RegistryPayloadHttp.register("get")
+        class ModelHttpGetPayload(ModelPayloadHttp): ...
+
+    The registry resolves types dynamically during Pydantic validation,
+    enabling new payload types to be added without modifying existing code.
+
+Related:
+    - RegistryPayloadHttp: Decorator-based registry for payload type discovery
+    - EnumHttpOperationType: Operation type enum for discriminator
+    - OMN-1007: Union reduction refactoring
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict
+
+
+class ModelPayloadHttp(BaseModel):
+    """Base model for all registry-managed HTTP payloads.
+
+    All concrete HTTP payload models MUST:
+    1. Inherit from this base class
+    2. Use @RegistryPayloadHttp.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 HTTP payloads share,
+    enabling type-safe access to common fields without type narrowing.
+
+    Example:
+        @RegistryPayloadHttp.register("get")
+        class ModelHttpGetPayload(ModelPayloadHttp):
+            operation_type: Literal["get"] = "get"
+            url: str
+            status_code: int
+            ...
+
+    Attributes:
+        operation_type: Operation type identifier used for type discrimination.
+
+    Related:
+        - RegistryPayloadHttp: Registration decorator and type lookup
+        - EnumHttpOperationType: Enum for operation type values
+    """
+
+    model_config = ConfigDict(frozen=True, extra="forbid", from_attributes=True)
+
+    operation_type: str
+    """Operation type identifier used for type discrimination."""
+
+
+__all__ = [
+    "ModelPayloadHttp",
+]

omnibase_infra/handlers/models/http/registry_payload_http.py

@@ -0,0 +1,212 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Registry for HTTP payload types with decorator-based registration.
+
+This module provides:
+- RegistryPayloadHttp: Decorator-based registry for payload type discovery
+
+Design Pattern:
+    Instead of maintaining explicit union types like:
+        HttpPayload = ModelHttpGetPayload | ModelHttpPostPayload | ...
+
+    Payload models self-register via decorator:
+        @RegistryPayloadHttp.register("get")
+        class ModelHttpGetPayload(ModelPayloadHttp): ...
+
+    The registry resolves types dynamically during Pydantic validation,
+    enabling new payload types to be added without modifying existing code.
+
+Related:
+    - ModelPayloadHttp: Base model for HTTP payloads
+    - EnumHttpOperationType: 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.http.model_payload_http import (
+        ModelPayloadHttp,
+    )
+
+# TypeVar bound to ModelPayloadHttp to preserve subclass type through decorator
+_HttpPayloadT = TypeVar("_HttpPayloadT", bound="ModelPayloadHttp")
+
+
+class RegistryPayloadHttp:
+    """Registry for HTTP payload model types with decorator-based registration.
+
+    This registry enables dynamic type resolution for Pydantic validation
+    without requiring explicit union type definitions.
+
+    Example:
+        @RegistryPayloadHttp.register("get")
+        class ModelHttpGetPayload(ModelPayloadHttp):
+            operation_type: Literal["get"] = "get"
+            ...
+
+        # Later, resolve type from operation_type
+        payload_cls = RegistryPayloadHttp.get_type("get")
+        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[ModelPayloadHttp]]] = {}
+    _lock: ClassVar[threading.Lock] = threading.Lock()
+
+    @classmethod
+    def register(
+        cls, operation_type: str
+    ) -> Callable[[type[_HttpPayloadT]], type[_HttpPayloadT]]:
+        """Decorator to register an HTTP payload model type.
+
+        Args:
+            operation_type: The operation type identifier (e.g., "get", "post").
+                           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:
+            @RegistryPayloadHttp.register("get")
+            class ModelHttpGetPayload(ModelPayloadHttp):
+                operation_type: Literal["get"] = "get"
+                url: str
+                ...
+        """
+
+        def decorator(
+            payload_cls: type[_HttpPayloadT],
+        ) -> type[_HttpPayloadT]:
+            # Runtime type validation (outside lock - class inspection is read-only)
+            from omnibase_infra.handlers.models.http.model_payload_http import (
+                ModelPayloadHttp,
+            )
+
+            if not issubclass(payload_cls, ModelPayloadHttp):
+                context = ModelInfraErrorContext(
+                    transport_type=EnumInfraTransportType.HTTP,
+                    operation="register_payload_type",
+                )
+                raise ProtocolConfigurationError(
+                    f"Registered class {payload_cls.__name__!r} must be a subclass "
+                    f"of ModelPayloadHttp, 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.HTTP,
+                        operation="register_payload_type",
+                    )
+                    raise ProtocolConfigurationError(
+                        f"HTTP 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[ModelPayloadHttp]:
+        """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 = RegistryPayloadHttp.get_type("get")
+            payload = payload_cls.model_validate({"operation_type": "get", ...})
+        """
+        if operation_type not in cls._types:
+            registered = ", ".join(sorted(cls._types.keys())) or "(none)"
+            raise KeyError(
+                f"Unknown HTTP operation_type '{operation_type}'. "
+                f"Registered types: {registered}"
+            )
+        return cls._types[operation_type]
+
+    @classmethod
+    def get_all_types(cls) -> dict[str, type[ModelPayloadHttp]]:
+        """Get all registered HTTP payload types.
+
+        Returns:
+            Dict mapping operation_type strings to payload model classes.
+
+        Example:
+            all_types = RegistryPayloadHttp.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 RegistryPayloadHttp.is_registered("get"):
+                payload_cls = RegistryPayloadHttp.get_type("get")
+        """
+        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(
+            "RegistryPayloadHttp.clear() is intended for testing only. "
+            "Do not use in production code.",
+            UserWarning,
+            stacklevel=2,
+        )
+        with cls._lock:
+            cls._types.clear()
+
+
+__all__ = [
+    "RegistryPayloadHttp",  # HTTP payload registry
+]

omnibase_infra/handlers/models/mcp/__init__.py

@@ -0,0 +1,23 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""MCP handler models for Model Context Protocol integration."""
+
+from omnibase_infra.handlers.models.mcp.enum_mcp_operation_type import (
+    EnumMcpOperationType,
+)
+from omnibase_infra.handlers.models.mcp.model_mcp_handler_config import (
+    ModelMcpHandlerConfig,
+)
+from omnibase_infra.handlers.models.mcp.model_mcp_tool_call import (
+    ModelMcpToolCall,
+)
+from omnibase_infra.handlers.models.mcp.model_mcp_tool_result import (
+    ModelMcpToolResult,
+)
+
+__all__ = [
+    "EnumMcpOperationType",
+    "ModelMcpHandlerConfig",
+    "ModelMcpToolCall",
+    "ModelMcpToolResult",
+]