omnibase_infra 0.2.8__py3-none-any.whl → 0.2.9__py3-none-any.whl

omnibase_infra/services/contract_publisher/errors.py

@@ -0,0 +1,243 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Contract Publisher Error Classes.
+
+This module defines error classes specific to contract publishing operations.
+All error classes extend from RuntimeHostError to maintain consistency with
+ONEX infrastructure error handling patterns.
+
+Error Hierarchy:
+    RuntimeHostError (from omnibase_infra.errors)
+    └── ContractPublisherError (base contract publishing error)
+        ├── ContractSourceNotConfiguredError
+        ├── ContractPublishingInfraError
+        └── NoContractsFoundError
+
+Related:
+    - OMN-1752: Extract ContractPublisher to omnibase_infra
+    - ARCH-002: Runtime owns all Kafka plumbing
+
+.. versionadded:: 0.3.0
+    Created as part of OMN-1752 (ContractPublisher extraction).
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from omnibase_core.enums import EnumCoreErrorCode
+from omnibase_infra.enums import EnumInfraTransportType
+from omnibase_infra.errors import RuntimeHostError
+from omnibase_infra.models.errors import ModelInfraErrorContext
+
+if TYPE_CHECKING:
+    from omnibase_infra.services.contract_publisher.models import ModelInfraError
+
+
+class ContractPublisherError(RuntimeHostError):
+    """Base error class for contract publishing errors.
+
+    All contract publishing-specific errors should inherit from this class.
+    Provides common context for contract publishing operations.
+
+    Example:
+        >>> raise ContractPublisherError("Publishing failed")
+
+    .. versionadded:: 0.3.0
+    """
+
+    def __init__(
+        self,
+        message: str,
+        error_code: EnumCoreErrorCode | None = None,
+        context: ModelInfraErrorContext | None = None,
+        **extra_context: object,
+    ) -> None:
+        """Initialize ContractPublisherError.
+
+        Args:
+            message: Human-readable error message
+            error_code: Error code (defaults to OPERATION_FAILED)
+            context: Bundled infrastructure context
+            **extra_context: Additional context information
+        """
+        # Default to KAFKA transport type for contract publishing
+        if context is None:
+            context = ModelInfraErrorContext.with_correlation(
+                transport_type=EnumInfraTransportType.KAFKA,
+                operation="contract_publish",
+            )
+
+        super().__init__(
+            message=message,
+            error_code=error_code or EnumCoreErrorCode.OPERATION_FAILED,
+            context=context,
+            **extra_context,
+        )
+
+
+class ContractSourceNotConfiguredError(ContractPublisherError):
+    """Raised when no contract source is configured.
+
+    This error indicates a configuration problem - the ContractPublisherConfig
+    does not have the required source configuration for the selected mode.
+
+    Examples:
+        - mode="filesystem" but filesystem_root is None
+        - mode="package" but package_module is None
+        - mode="composite" but neither source is configured
+
+    Example:
+        >>> raise ContractSourceNotConfiguredError(
+        ...     mode="filesystem",
+        ...     missing_field="filesystem_root",
+        ... )
+
+    .. versionadded:: 0.3.0
+    """
+
+    def __init__(
+        self,
+        mode: str,
+        missing_field: str,
+        message: str | None = None,
+    ) -> None:
+        """Initialize ContractSourceNotConfiguredError.
+
+        Args:
+            mode: The configured mode (filesystem, package, composite)
+            missing_field: The field that is missing
+            message: Optional custom message
+        """
+        self.mode = mode
+        self.missing_field = missing_field
+
+        default_message = (
+            f"Contract source not configured: mode='{mode}' requires '{missing_field}'"
+        )
+
+        super().__init__(
+            message=message or default_message,
+            error_code=EnumCoreErrorCode.CONFIGURATION_ERROR,
+            mode=mode,
+            missing_field=missing_field,
+        )
+
+
+class ContractPublishingInfraError(ContractPublisherError):
+    """Raised when infrastructure fails during contract publishing.
+
+    This error wraps one or more ModelInfraError instances that occurred
+    during the publishing process. It is raised when fail_fast=True and
+    an infrastructure error occurs.
+
+    Attributes:
+        infra_errors: List of infrastructure errors that occurred
+
+    Example:
+        >>> from omnibase_infra.services.contract_publisher.models import ModelInfraError
+        >>> error = ModelInfraError(
+        ...     error_type="publisher_unavailable",
+        ...     message="Event bus publisher not available",
+        ...     retriable=False,
+        ... )
+        >>> raise ContractPublishingInfraError([error])
+
+    .. versionadded:: 0.3.0
+    """
+
+    def __init__(
+        self,
+        infra_errors: list[ModelInfraError],
+        message: str | None = None,
+    ) -> None:
+        """Initialize ContractPublishingInfraError.
+
+        Args:
+            infra_errors: List of infrastructure errors that occurred
+            message: Optional custom message
+        """
+        self.infra_errors = infra_errors
+
+        # Build message from errors if not provided
+        if message is None:
+            error_count = len(infra_errors)
+            if error_count == 1:
+                message = f"Contract publishing failed: {infra_errors[0].message}"
+            else:
+                message = f"Contract publishing failed with {error_count} infrastructure errors"
+
+        super().__init__(
+            message=message,
+            error_code=EnumCoreErrorCode.OPERATION_FAILED,
+            error_count=len(infra_errors),
+        )
+
+
+class NoContractsFoundError(ContractPublisherError):
+    """Raised when no contracts are found and allow_zero_contracts=False.
+
+    This error indicates that:
+    - Discovery found zero contract files, OR
+    - Discovery found files but all failed validation (published_count == 0)
+
+    Both cases result in "no contracts published" which may indicate
+    a configuration or deployment problem.
+
+    Attributes:
+        source_description: Description of the source that was searched
+        discovered_count: Number of contracts discovered (may be > 0 if all failed)
+        valid_count: Number of valid contracts (always 0 when raised)
+
+    Example:
+        >>> raise NoContractsFoundError(
+        ...     source_description="filesystem: /app/contracts",
+        ...     discovered_count=0,
+        ... )
+
+    .. versionadded:: 0.3.0
+    """
+
+    def __init__(
+        self,
+        source_description: str,
+        discovered_count: int = 0,
+        valid_count: int = 0,
+        message: str | None = None,
+    ) -> None:
+        """Initialize NoContractsFoundError.
+
+        Args:
+            source_description: Description of the source searched
+            discovered_count: Number of contracts discovered
+            valid_count: Number of valid contracts (should be 0)
+            message: Optional custom message
+        """
+        self.source_description = source_description
+        self.discovered_count = discovered_count
+        self.valid_count = valid_count
+
+        if message is None:
+            if discovered_count == 0:
+                message = f"No contracts found in {source_description}"
+            else:
+                message = (
+                    f"No valid contracts: discovered {discovered_count} but "
+                    f"all failed validation in {source_description}"
+                )
+
+        super().__init__(
+            message=message,
+            error_code=EnumCoreErrorCode.RESOURCE_NOT_FOUND,
+            source_description=source_description,
+            discovered_count=discovered_count,
+            valid_count=valid_count,
+        )
+
+
+__all__ = [
+    "ContractPublisherError",
+    "ContractSourceNotConfiguredError",
+    "ContractPublishingInfraError",
+    "NoContractsFoundError",
+]

omnibase_infra/services/contract_publisher/models/__init__.py

@@ -0,0 +1,28 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Contract Publisher Models.
+
+Re-exports all models for clean imports.
+
+.. versionadded:: 0.3.0
+"""
+
+from omnibase_infra.services.contract_publisher.models.model_contract_error import (
+    ModelContractError,
+)
+from omnibase_infra.services.contract_publisher.models.model_infra_error import (
+    ModelInfraError,
+)
+from omnibase_infra.services.contract_publisher.models.model_publish_result import (
+    ModelPublishResult,
+)
+from omnibase_infra.services.contract_publisher.models.model_publish_stats import (
+    ModelPublishStats,
+)
+
+__all__ = [
+    "ModelContractError",
+    "ModelInfraError",
+    "ModelPublishResult",
+    "ModelPublishStats",
+]

omnibase_infra/services/contract_publisher/models/model_contract_error.py

@@ -0,0 +1,67 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Contract Error Model.
+
+Non-fatal error for contract parsing/validation failures.
+
+.. versionadded:: 0.3.0
+"""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class ModelContractError(BaseModel):
+    """Non-fatal contract-level error.
+
+    Represents errors that occur during contract parsing, validation, or
+    conflict detection. These errors are non-fatal - processing continues
+    and the error is collected in the result.
+
+    Error Types:
+        yaml_parse: YAML syntax error
+        schema_validation: Contract doesn't match ModelHandlerContract schema
+        missing_field: Required field missing (handler_id, etc.)
+        invalid_handler_class: handler_class not fully qualified Python path
+        duplicate_conflict: Same handler_id with different content hash
+
+    Attributes:
+        contract_path: Path or identifier of the contract that failed
+        handler_id: Handler ID if extracted, None if parsing failed early
+        error_type: Category of the error
+        message: Human-readable error description
+
+    Example:
+        >>> error = ModelContractError(
+        ...     contract_path="/app/contracts/handlers/foo/contract.yaml",
+        ...     handler_id=None,
+        ...     error_type="yaml_parse",
+        ...     message="Invalid YAML syntax at line 10",
+        ... )
+
+    .. versionadded:: 0.3.0
+    """
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    contract_path: str = Field(
+        description="Path or identifier of the contract that failed"
+    )
+    handler_id: str | None = Field(
+        default=None,
+        description="Handler ID if extracted, None if parsing failed early",
+    )
+    error_type: Literal[
+        "yaml_parse",
+        "schema_validation",
+        "missing_field",
+        "invalid_handler_class",
+        "duplicate_conflict",
+    ] = Field(description="Category of the error")
+    message: str = Field(description="Human-readable error description")
+
+
+__all__ = ["ModelContractError"]

omnibase_infra/services/contract_publisher/models/model_infra_error.py

@@ -0,0 +1,62 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Infrastructure Error Model.
+
+Fatal error for infrastructure failures (Kafka, network, etc.).
+
+.. versionadded:: 0.3.0
+"""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class ModelInfraError(BaseModel):
+    """Infrastructure error during contract publishing.
+
+    Represents errors that occur due to infrastructure failures (Kafka,
+    network, etc.). These errors are potentially fatal depending on
+    fail_fast configuration.
+
+    Error Types:
+        publisher_unavailable: Event bus publisher not available in container
+        kafka_timeout: Kafka operation timed out
+        broker_down: Kafka broker unreachable
+        publish_failed: Generic publish failure
+        serialization_failed: Failed to serialize event envelope
+
+    Attributes:
+        error_type: Category of the error
+        message: Human-readable error description
+        retriable: Whether the operation might succeed on retry
+
+    Example:
+        >>> error = ModelInfraError(
+        ...     error_type="kafka_timeout",
+        ...     message="Publish timed out after 30s",
+        ...     retriable=True,
+        ... )
+
+    .. versionadded:: 0.3.0
+    """
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    error_type: Literal[
+        "publisher_unavailable",
+        "kafka_timeout",
+        "broker_down",
+        "publish_failed",
+        "serialization_failed",
+    ] = Field(description="Category of the error")
+    message: str = Field(description="Human-readable error description")
+    retriable: bool = Field(
+        default=False,
+        description="Whether the operation might succeed on retry",
+    )
+
+
+__all__ = ["ModelInfraError"]

omnibase_infra/services/contract_publisher/models/model_publish_result.py

@@ -0,0 +1,112 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Publish Result Model.
+
+Complete result of contract publishing with errors and statistics.
+
+.. versionadded:: 0.3.0
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from omnibase_infra.services.contract_publisher.models.model_contract_error import (
+    ModelContractError,
+)
+from omnibase_infra.services.contract_publisher.models.model_infra_error import (
+    ModelInfraError,
+)
+from omnibase_infra.services.contract_publisher.models.model_publish_stats import (
+    ModelPublishStats,
+)
+
+
+class ModelPublishResult(BaseModel):
+    """Complete result of contract publishing operation.
+
+    Contains three categories of information:
+    - published: List of handler_ids successfully published
+    - contract_errors: Non-fatal contract-level errors
+    - infra_errors: Infrastructure errors
+    - stats: Publishing statistics
+
+    The __bool__ method returns True if any contracts were published
+    successfully, enabling idiomatic conditional checks:
+
+        >>> result = await publisher.publish_all()
+        >>> if result:
+        ...     print(f"Published {len(result.published)} contracts")
+        ... else:
+        ...     print("No contracts published")
+
+    Warning:
+        This model overrides __bool__ to return True only when contracts
+        are published. This differs from standard Pydantic behavior where
+        bool(model) always returns True. Use explicit checks if you need
+        to verify the model exists rather than its success state.
+
+    Attributes:
+        published: List of handler_ids successfully published
+        contract_errors: Non-fatal contract-level errors
+        infra_errors: Infrastructure errors
+        stats: Publishing statistics
+
+    Example:
+        >>> result = ModelPublishResult(
+        ...     published=["handler.foo", "handler.bar"],
+        ...     contract_errors=[],
+        ...     infra_errors=[],
+        ...     stats=stats,
+        ... )
+        >>> if result:
+        ...     print("Success!")
+
+    .. versionadded:: 0.3.0
+    """
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    published: list[str] = Field(
+        description="List of handler_ids successfully published"
+    )
+    contract_errors: list[ModelContractError] = Field(
+        default_factory=list,
+        description="Non-fatal contract-level errors",
+    )
+    infra_errors: list[ModelInfraError] = Field(
+        default_factory=list,
+        description="Infrastructure errors",
+    )
+    stats: ModelPublishStats = Field(description="Publishing statistics")
+
+    def __bool__(self) -> bool:
+        """Return True if any contracts were published successfully.
+
+        Warning:
+            This differs from standard Pydantic behavior. The model
+            evaluates to False when no contracts are published, even
+            if the model itself is valid.
+
+        Returns:
+            True if published list is non-empty, False otherwise.
+        """
+        return bool(self.published)
+
+    @property
+    def has_contract_errors(self) -> bool:
+        """Check if any contract errors occurred."""
+        return len(self.contract_errors) > 0
+
+    @property
+    def has_infra_errors(self) -> bool:
+        """Check if any infrastructure errors occurred."""
+        return len(self.infra_errors) > 0
+
+    @property
+    def has_errors(self) -> bool:
+        """Check if any errors (contract or infra) occurred."""
+        return self.has_contract_errors or self.has_infra_errors
+
+
+__all__ = ["ModelPublishResult"]

omnibase_infra/services/contract_publisher/models/model_publish_stats.py

@@ -0,0 +1,79 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Publish Statistics Model.
+
+Statistics for contract publishing operations including counts, timing, and per-origin breakdown.
+
+.. versionadded:: 0.3.0
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class ModelPublishStats(BaseModel):
+    """Publishing statistics for observability.
+
+    Tracks counts, timing, and per-origin breakdown for contract publishing.
+    Included in every ModelPublishResult for debugging and monitoring.
+
+    Attributes:
+        discovered_count: Total contracts found by discovery
+        valid_count: Contracts that passed validation
+        published_count: Contracts successfully published to Kafka
+        errored_count: Contracts that failed validation
+        dedup_count: Contracts deduplicated (same handler_id + hash)
+        duration_ms: Total duration of publish_all()
+        discover_ms: Time spent in discovery phase
+        validate_ms: Time spent in validation phase
+        publish_ms: Time spent in publishing phase
+        environment: Resolved environment (for log clarity)
+        filesystem_count: Contracts from filesystem source
+        package_count: Contracts from package source
+
+    Example:
+        >>> stats = ModelPublishStats(
+        ...     discovered_count=10,
+        ...     valid_count=8,
+        ...     published_count=8,
+        ...     errored_count=2,
+        ...     dedup_count=0,
+        ...     duration_ms=1234.5,
+        ...     discover_ms=100.0,
+        ...     validate_ms=500.0,
+        ...     publish_ms=634.5,
+        ...     environment="dev",
+        ...     filesystem_count=10,
+        ...     package_count=0,
+        ... )
+
+    .. versionadded:: 0.3.0
+    """
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    # Counts
+    discovered_count: int = Field(ge=0, description="Total contracts found")
+    valid_count: int = Field(ge=0, description="Contracts that passed validation")
+    published_count: int = Field(ge=0, description="Contracts successfully published")
+    errored_count: int = Field(ge=0, description="Contracts that failed validation")
+    dedup_count: int = Field(ge=0, description="Contracts deduplicated (same hash)")
+
+    # Timing (milliseconds)
+    duration_ms: float = Field(ge=0.0, description="Total duration")
+    discover_ms: float = Field(ge=0.0, description="Discovery phase duration")
+    validate_ms: float = Field(ge=0.0, description="Validation phase duration")
+    publish_ms: float = Field(ge=0.0, description="Publishing phase duration")
+
+    # Context
+    environment: str = Field(description="Resolved environment for topics")
+
+    # Per-origin breakdown
+    filesystem_count: int = Field(
+        default=0, ge=0, description="Contracts from filesystem"
+    )
+    package_count: int = Field(default=0, ge=0, description="Contracts from package")
+
+
+__all__ = ["ModelPublishStats"]