omnibase_infra 0.2.1__py3-none-any.whl

omnibase_infra/models/errors/model_message_type_registry_error_context.py

@@ -0,0 +1,71 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Message Type Registry Error Context Model.
+
+This module defines the configuration model for message type registry error context,
+encapsulating registry-specific fields to reduce __init__ parameter count
+while maintaining strong typing per ONEX standards.
+
+Related:
+    - OMN-937: Central Message Type Registry implementation
+    - MessageTypeRegistryError: Error class that uses this model
+
+.. versionadded:: 0.5.0
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from omnibase_infra.enums import EnumMessageCategory
+
+
+class ModelMessageTypeRegistryErrorContext(BaseModel):
+    """Configuration model for message type registry error context.
+
+    Encapsulates registry-specific fields for message type registry errors
+    to reduce __init__ parameter count while maintaining strong typing.
+    This follows the ONEX pattern of using configuration models to
+    bundle related parameters.
+
+    Attributes:
+        message_type: The message type that caused the error (if applicable)
+        domain: The domain involved in the error (if applicable)
+        category: The category involved in the error (if applicable)
+
+    Example:
+        >>> from omnibase_infra.enums import EnumMessageCategory
+        >>> registry_context = ModelMessageTypeRegistryErrorContext(
+        ...     message_type="UnknownType",
+        ...     domain="myapp.events",
+        ...     category=EnumMessageCategory.EVENT,
+        ... )
+        >>> raise MessageTypeRegistryError(
+        ...     "Message type not found",
+        ...     registry_context=registry_context,
+        ... )
+
+    .. versionadded:: 0.5.0
+    """
+
+    model_config = ConfigDict(
+        frozen=True,  # Immutable for thread safety
+        extra="forbid",  # Strict validation - no extra fields
+        from_attributes=True,  # Support pytest-xdist compatibility
+    )
+
+    message_type: str | None = Field(
+        default=None,
+        description="The message type that caused the error (if applicable)",
+    )
+    domain: str | None = Field(
+        default=None,
+        description="The domain involved in the error (if applicable)",
+    )
+    category: EnumMessageCategory | None = Field(
+        default=None,
+        description="The category involved in the error (if applicable)",
+    )
+
+
+__all__ = ["ModelMessageTypeRegistryErrorContext"]

omnibase_infra/models/errors/model_timeout_error_context.py

@@ -0,0 +1,110 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Timeout Error Context Model - Stricter Typing for Timeout Errors.
+
+This module defines a specialized context model for timeout errors that enforces
+correlation_id is always present. This is stricter than ModelInfraErrorContext
+which allows optional correlation_id.
+
+Design Decision:
+    Timeout errors require correlation_id for several reasons:
+    1. Timeout events are often critical for debugging distributed systems
+    2. Timeout chains need to be traceable across services
+    3. Operators need to correlate timeout events with upstream requests
+    4. Replay and debugging require deterministic correlation tracking
+
+    By using a stricter model, we ensure at compile-time (via type checking)
+    that all timeout error contexts include correlation_id.
+
+Related:
+    - CLAUDE.md: Error Context section requires correlation_id for timeout errors
+    - ModelInfraErrorContext: Base model with optional fields
+    - InfraTimeoutError: Uses this model for stricter typing
+"""
+
+from uuid import UUID, uuid4
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from omnibase_infra.enums import EnumInfraTransportType
+
+
+class ModelTimeoutErrorContext(BaseModel):
+    """Specialized error context for timeout errors with required correlation_id.
+
+    This model enforces stricter typing than ModelInfraErrorContext by requiring
+    correlation_id to always be present. If not provided during construction,
+    a UUID is auto-generated to ensure all timeout errors are traceable.
+
+    The auto-generation behavior allows existing code patterns like:
+        context = ModelTimeoutErrorContext(
+            transport_type=EnumInfraTransportType.DATABASE,
+            operation="execute_query",
+        )
+
+    While still guaranteeing correlation_id is present:
+        assert context.correlation_id is not None  # Always passes
+
+    Attributes:
+        transport_type: Type of infrastructure transport (HTTP, DATABASE, KAFKA, etc.)
+            Required for timeout context to identify the transport layer.
+        operation: Operation being performed (required for timeout context).
+        target_name: Target resource or endpoint name (optional).
+        correlation_id: Request correlation ID for distributed tracing (required,
+            auto-generated if not provided).
+        timeout_seconds: The timeout value that was exceeded (optional).
+
+    Example:
+        >>> # With explicit correlation_id
+        >>> context = ModelTimeoutErrorContext(
+        ...     transport_type=EnumInfraTransportType.DATABASE,
+        ...     operation="execute_query",
+        ...     target_name="postgresql-primary",
+        ...     correlation_id=request.correlation_id,
+        ...     timeout_seconds=30.0,
+        ... )
+        >>> raise InfraTimeoutError("Query exceeded timeout", context=context)
+
+        >>> # Auto-generated correlation_id
+        >>> context = ModelTimeoutErrorContext(
+        ...     transport_type=EnumInfraTransportType.HTTP,
+        ...     operation="fetch_resource",
+        ... )
+        >>> assert context.correlation_id is not None  # Guaranteed
+    """
+
+    model_config = ConfigDict(
+        frozen=True,  # Immutable for thread safety
+        extra="forbid",  # Strict validation - no extra fields
+        from_attributes=True,  # Support pytest-xdist compatibility
+    )
+
+    transport_type: EnumInfraTransportType = Field(
+        ...,
+        description="Type of infrastructure transport - required for timeout context",
+    )
+    operation: str = Field(
+        ...,
+        min_length=1,
+        description="Operation being performed - required for timeout context",
+    )
+    target_name: str | None = Field(
+        default=None,
+        description="Target resource or endpoint name",
+    )
+    correlation_id: UUID = Field(
+        default_factory=uuid4,
+        description="Request correlation ID - required, auto-generated if not provided",
+    )
+    timeout_seconds: float | None = Field(
+        default=None,
+        ge=0.0,
+        description="The timeout value that was exceeded",
+    )
+
+    # NOTE: No model_validator needed - default_factory=uuid4 on correlation_id
+    # guarantees the field is always populated in Pydantic v2. The type annotation
+    # `UUID` (not `UUID | None`) documents the invariant at compile-time.
+
+
+__all__ = ["ModelTimeoutErrorContext"]

omnibase_infra/models/handlers/__init__.py

@@ -0,0 +1,37 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Handler Models for Validation and Error Reporting.
+
+This module exports handler-related models for structured validation
+and error reporting in ONEX handlers.
+
+.. versionadded:: 0.6.1
+    Created as part of OMN-1091 structured validation and error reporting.
+
+.. versionchanged:: 0.6.2
+    Added ModelHandlerDescriptor and ModelContractDiscoveryResult for
+    OMN-1097 filesystem handler discovery.
+
+Note:
+    ModelContractDiscoveryResult uses a forward reference to
+    ModelHandlerValidationError to avoid circular imports. The forward
+    reference is resolved via model_rebuild() in handler_contract_source.py
+    after both classes are defined. This pattern is tested in
+    tests/unit/runtime/test_handler_contract_source.py.
+"""
+
+from omnibase_infra.models.handlers.model_contract_discovery_result import (
+    ModelContractDiscoveryResult,
+)
+from omnibase_infra.models.handlers.model_handler_descriptor import (
+    ModelHandlerDescriptor,
+)
+from omnibase_infra.models.handlers.model_handler_identifier import (
+    ModelHandlerIdentifier,
+)
+
+__all__ = [
+    "ModelContractDiscoveryResult",
+    "ModelHandlerDescriptor",
+    "ModelHandlerIdentifier",
+]

omnibase_infra/models/handlers/model_contract_discovery_result.py

@@ -0,0 +1,80 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Contract Discovery Result Model for Graceful Error Handling.
+
+This module provides ModelContractDiscoveryResult, which holds the results of
+contract discovery with graceful error handling. Part of OMN-1097
+HandlerContractSource filesystem discovery.
+
+When graceful_mode is enabled on HandlerContractSource, this model holds both
+successfully discovered descriptors and any validation errors encountered.
+
+See Also:
+    - HandlerContractSource: Source that produces these results
+    - ModelHandlerDescriptor: Individual descriptor for discovered handlers
+    - ModelHandlerValidationError: Structured error model for validation failures
+
+.. versionadded:: 0.6.2
+    Created as part of OMN-1097 filesystem handler discovery.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from omnibase_infra.models.handlers.model_handler_descriptor import (
+    ModelHandlerDescriptor,
+)
+
+if TYPE_CHECKING:
+    from omnibase_infra.models.errors import ModelHandlerValidationError
+
+
+class ModelContractDiscoveryResult(BaseModel):
+    """Result of contract discovery with graceful error handling.
+
+    When graceful_mode is enabled, this model holds both successfully
+    discovered descriptors and any validation errors encountered.
+
+    Attributes:
+        descriptors: List of successfully discovered handler descriptors.
+        validation_errors: List of validation errors for failed contracts.
+
+    Example:
+        >>> result = ModelContractDiscoveryResult(
+        ...     descriptors=[descriptor1, descriptor2],
+        ...     validation_errors=[error1],
+        ... )
+        >>> len(result.descriptors)
+        2
+        >>> len(result.validation_errors)
+        1
+
+    .. versionadded:: 0.6.2
+        Created as part of OMN-1097 filesystem handler discovery.
+    """
+
+    model_config = ConfigDict(
+        frozen=True,
+        extra="forbid",
+        strict=True,
+    )
+
+    descriptors: list[ModelHandlerDescriptor] = Field(
+        default_factory=list,
+        description="Successfully discovered handler descriptors",
+    )
+    validation_errors: list[ModelHandlerValidationError] = Field(
+        default_factory=list,
+        description="Validation errors for failed contracts",
+    )
+
+
+# Rebuild model to resolve forward reference after all imports are available.
+# model_rebuild() is called in omnibase_infra.runtime.handler_contract_source
+# after ModelHandlerValidationError is imported. See the comment block preceding
+# model_rebuild() in handler_contract_source.py (lines 52-71) for detailed explanation.
+
+__all__ = ["ModelContractDiscoveryResult"]

omnibase_infra/models/handlers/model_handler_descriptor.py

@@ -0,0 +1,185 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Handler Descriptor Model for Filesystem Discovery.
+
+This module provides ModelHandlerDescriptor, which represents a discovered handler
+from a contract file. Part of OMN-1097 HandlerContractSource filesystem discovery.
+
+The descriptor captures essential metadata about a handler discovered from a
+handler_contract.yaml file, suitable for registration and validation.
+
+See Also:
+    - HandlerContractSource: Source that discovers these descriptors
+    - ModelHandlerContract: Contract model from omnibase_core
+    - ModelContractDiscoveryResult: Result model with graceful error handling
+
+.. versionadded:: 0.6.2
+    Created as part of OMN-1097 filesystem handler discovery.
+
+.. versionchanged:: 0.6.3
+    Changed version field from str to ModelSemVer for better type safety
+    and consistency with rest of codebase.
+"""
+
+from __future__ import annotations
+
+from typing import Annotated, Literal
+
+from pydantic import BaseModel, BeforeValidator, ConfigDict, Field
+
+from omnibase_core.models.primitives.model_semver import ModelSemVer
+from omnibase_core.types import JsonType
+
+
+def _parse_version(v: ModelSemVer | str | dict[str, JsonType]) -> ModelSemVer:
+    """Parse version input to ModelSemVer.
+
+    Accepts ModelSemVer instance, string (e.g., "1.0.0"), or dict
+    (e.g., {"major": 1, "minor": 0, "patch": 0}).
+
+    This validator enables flexible input while maintaining ModelSemVer
+    as the canonical type, supporting:
+    - Direct ModelSemVer instances (programmatic use)
+    - String versions (from YAML contract files)
+    - Dict representations (from JSON/dict sources)
+
+    Dict Validation:
+        When a dict is provided, the validator explicitly checks for:
+        1. Required keys ("major", "minor", "patch") are present
+        2. Required key values are integers (not strings or other types)
+
+        This provides clearer error messages before delegating to model_validate(),
+        rather than relying on Pydantic's generic validation errors.
+
+    Raises:
+        ValueError: If dict input is missing required keys (major, minor, patch),
+            or if required key values are not integers.
+    """
+    if isinstance(v, ModelSemVer):
+        return v
+    if isinstance(v, str):
+        return ModelSemVer.parse(v)
+    if isinstance(v, dict):
+        required_keys = {"major", "minor", "patch"}
+        if not required_keys.issubset(v.keys()):
+            missing = required_keys - v.keys()
+            raise ValueError(f"Version dict missing required keys: {missing}")
+        # Validate value types before delegating to model_validate()
+        for key in required_keys:
+            value = v[key]
+            if not isinstance(value, int):
+                raise ValueError(
+                    f"Version '{key}' must be an integer, "
+                    f"got {type(value).__name__}: {value!r}"
+                )
+        return ModelSemVer.model_validate(v)
+    # NOTE: Return as-is for unhandled types and let Pydantic's own
+    # validation raise an appropriate error with type information.
+    return v  # type: ignore[return-value]  # NOTE: Pydantic validation handles unknown types
+
+
+# Annotated type for version field that accepts string, dict, or ModelSemVer
+_VersionField = Annotated[ModelSemVer, BeforeValidator(_parse_version)]
+
+# Type alias for valid ONEX handler kinds
+LiteralHandlerKind = Literal["compute", "effect", "reducer", "orchestrator"]
+
+
+class ModelHandlerDescriptor(BaseModel):
+    """Handler descriptor model representing a discovered handler.
+
+    This model captures the essential metadata about a handler discovered
+    from a contract file, suitable for registration and validation.
+
+    Attributes:
+        handler_id: Unique identifier for the handler.
+        name: Human-readable name for the handler.
+        version: Semantic version (ModelSemVer). Accepts string, dict, or ModelSemVer.
+        handler_kind: Handler kind (compute, effect, reducer, orchestrator).
+        input_model: Fully qualified input model class path.
+        output_model: Fully qualified output model class path.
+        description: Optional description of the handler.
+        contract_path: Path to the source contract file.
+
+    Example:
+        Create with string version (common when loading from YAML):
+
+        >>> descriptor = ModelHandlerDescriptor(
+        ...     handler_id="auth.handler",
+        ...     name="Auth Handler",
+        ...     version="1.0.0",
+        ...     handler_kind="compute",
+        ...     input_model="auth.models.AuthInput",
+        ...     output_model="auth.models.AuthOutput",
+        ... )
+        >>> descriptor.version.major
+        1
+
+        Create with ModelSemVer instance:
+
+        >>> from omnibase_core.models.primitives.model_semver import ModelSemVer
+        >>> descriptor = ModelHandlerDescriptor(
+        ...     handler_id="auth.handler",
+        ...     name="Auth Handler",
+        ...     version=ModelSemVer(major=2, minor=1, patch=0, prerelease=("beta", 1)),
+        ...     handler_kind="compute",
+        ...     input_model="auth.models.AuthInput",
+        ...     output_model="auth.models.AuthOutput",
+        ... )
+        >>> str(descriptor.version)
+        '2.1.0-beta.1'
+
+    .. versionadded:: 0.6.2
+        Created as part of OMN-1097 filesystem handler discovery.
+
+    .. versionchanged:: 0.6.3
+        Changed version field from str to ModelSemVer for better type safety.
+    """
+
+    model_config = ConfigDict(
+        frozen=True,
+        extra="forbid",
+        strict=True,
+    )
+
+    handler_id: str = Field(
+        ...,
+        min_length=1,
+        description="Unique identifier for the handler",
+    )
+    name: str = Field(
+        ...,
+        min_length=1,
+        description="Human-readable name for the handler",
+    )
+    version: _VersionField = Field(
+        ...,
+        description="Semantic version (accepts string, dict, or ModelSemVer instance)",
+    )
+    handler_kind: LiteralHandlerKind = Field(
+        ...,
+        description="Handler architectural kind (compute, effect, reducer, orchestrator)",
+    )
+    input_model: str = Field(
+        ...,
+        min_length=3,
+        pattern=r"^[a-zA-Z_][a-zA-Z0-9_]*(\.[a-zA-Z_][a-zA-Z0-9_]*)+$",
+        description="Fully qualified input model class path (e.g., 'myapp.models.User')",
+    )
+    output_model: str = Field(
+        ...,
+        min_length=3,
+        pattern=r"^[a-zA-Z_][a-zA-Z0-9_]*(\.[a-zA-Z_][a-zA-Z0-9_]*)+$",
+        description="Fully qualified output model class path (e.g., 'myapp.models.Result')",
+    )
+    description: str | None = Field(
+        default=None,
+        description="Optional description of the handler",
+    )
+    contract_path: str | None = Field(
+        default=None,
+        description="Path to the source contract file",
+    )
+
+
+__all__ = ["LiteralHandlerKind", "ModelHandlerDescriptor"]