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

omnibase_infra/models/event_bus/model_dlq_config.py

@@ -0,0 +1,177 @@
+# SPDX-FileCopyrightText: 2025 OmniNode Team <info@omninode.ai>
+#
+# SPDX-License-Identifier: Apache-2.0
+"""Dead Letter Queue configuration model for event bus message handling.
+
+This module provides the configuration model for DLQ behavior in event bus
+consumers. The DLQ routes messages that fail processing to a dead letter
+topic for later analysis, retry, or manual intervention.
+
+Error Classification:
+    The DLQ configuration distinguishes between two error categories:
+
+    Content Errors (non-retryable):
+        Schema validation failures, malformed payloads, missing required fields,
+        type conversion errors. These errors will NOT fix themselves with retry.
+        Default behavior: Send to DLQ and commit offset (dlq_and_commit).
+
+    Infrastructure Errors (potentially retryable):
+        Database timeouts, network failures, service unavailability.
+        These errors MAY fix themselves after retry budget exhaustion.
+        Default behavior: Fail fast (fail_fast) to avoid hiding infrastructure
+        fires in the DLQ.
+
+Topic Naming Convention:
+    When topic is empty string, the consumer builds a DLQ topic name
+    following ONEX conventions: {env}.dlq.{original_topic}.v{schema_major}
+
+    Examples:
+        - dev.dlq.orders.created.v1
+        - prod.dlq.payments.processed.v1
+        - staging.dlq.users.registered.v1
+
+See Also:
+    - MixinKafkaDlq: DLQ publishing implementation
+    - ModelDlqEvent: Individual DLQ event model for callbacks
+    - docs/architecture/DLQ_MESSAGE_FORMAT.md: DLQ message structure
+"""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class ModelDlqConfig(BaseModel):
+    """Dead Letter Queue (DLQ) configuration.
+
+    Controls how failed messages are routed to DLQ topics. Supports
+    differentiated handling of content errors (non-retryable) versus
+    infrastructure errors (potentially retryable).
+
+    Attributes:
+        enabled: Whether DLQ publishing is enabled for failed messages.
+            When False, failed messages are dropped (logged only).
+            Default: True.
+        topic: DLQ topic name. Empty string triggers convention-based
+            topic naming: {env}.dlq.{original_topic}.v{schema_major}.
+            Non-empty value overrides the convention with explicit topic.
+            Default: "" (use convention).
+        on_content_error: Action when a content/schema error occurs.
+            Content errors (schema validation, malformed payload) are
+            non-retryable - they will never succeed with retry.
+            - "dlq_and_commit": Publish to DLQ and commit offset (default)
+            - "fail_fast": Raise immediately, do not commit
+            Default: "dlq_and_commit".
+        on_infra_exhausted: Action when retry budget exhausted for
+            infrastructure errors. Infrastructure errors (DB timeout,
+            network failure) may fix themselves, but infra owns plumbing.
+            - "dlq_and_commit": Publish to DLQ and commit offset
+            - "fail_fast": Raise immediately, do not commit (default)
+            Default: "fail_fast".
+
+    Example:
+        ```python
+        from omnibase_infra.models.event_bus import ModelDlqConfig
+
+        # Production configuration (explicit topic, fail-fast for infra)
+        config = ModelDlqConfig(
+            enabled=True,
+            topic="",  # Use convention-based naming
+            on_content_error="dlq_and_commit",
+            on_infra_exhausted="fail_fast",
+        )
+
+        # Development configuration (catch everything in DLQ)
+        dev_config = ModelDlqConfig(
+            enabled=True,
+            topic="dev.dlq.catch-all.v1",
+            on_content_error="dlq_and_commit",
+            on_infra_exhausted="dlq_and_commit",
+        )
+
+        # Disabled DLQ (for testing or specific use cases)
+        disabled = ModelDlqConfig(enabled=False)
+        ```
+
+    Configuration Guidelines:
+        - Enable DLQ for all production consumers to capture failures
+        - Use "fail_fast" for on_infra_exhausted to surface infrastructure
+          issues immediately rather than hiding them in DLQ
+        - Use "dlq_and_commit" for on_content_error since content errors
+          will never self-heal with retry
+        - Set explicit topic only when you need multiple consumers to
+          share a DLQ or when convention doesn't fit
+
+    Design Rationale:
+        Default on_content_error = "dlq_and_commit":
+            Content errors (bad schema, malformed JSON) will never fix
+            themselves. Retrying is pointless. Send to DLQ for human
+            review and continue processing other messages.
+
+        Default on_infra_exhausted = "fail_fast":
+            Infrastructure owns the plumbing. If the database is down,
+            that's an infrastructure fire that should be surfaced
+            immediately - not hidden in a DLQ. The operations team needs
+            to know about infrastructure failures, not discover them
+            later in a DLQ audit.
+
+    See Also:
+        MixinKafkaDlq: Implementation of DLQ publishing behavior.
+    """
+
+    model_config = ConfigDict(
+        frozen=True,
+        extra="forbid",
+        json_schema_extra={
+            "examples": [
+                {
+                    "enabled": True,
+                    "topic": "",
+                    "on_content_error": "dlq_and_commit",
+                    "on_infra_exhausted": "fail_fast",
+                },
+                {
+                    "enabled": True,
+                    "topic": "prod.dlq.orders.v1",
+                    "on_content_error": "dlq_and_commit",
+                    "on_infra_exhausted": "dlq_and_commit",
+                },
+            ]
+        },
+    )
+
+    enabled: bool = Field(
+        default=True,
+        description="Enable DLQ publishing for failed messages",
+    )
+
+    topic: str = Field(
+        default="",
+        description=(
+            "DLQ topic name. Empty string uses convention-based naming: "
+            "{env}.dlq.{original_topic}.v{schema_major}"
+        ),
+    )
+
+    on_content_error: Literal["dlq_and_commit", "fail_fast"] = Field(
+        default="dlq_and_commit",
+        description=(
+            "Action on content/schema errors (non-retryable). "
+            "'dlq_and_commit' publishes to DLQ and commits offset. "
+            "'fail_fast' raises immediately without committing."
+        ),
+    )
+
+    on_infra_exhausted: Literal["dlq_and_commit", "fail_fast"] = Field(
+        default="fail_fast",
+        description=(
+            "Action when retry budget exhausted for infrastructure errors. "
+            "'fail_fast' surfaces infrastructure issues immediately. "
+            "'dlq_and_commit' publishes to DLQ and commits offset."
+        ),
+    )
+
+
+__all__ = ["ModelDlqConfig"]

omnibase_infra/models/event_bus/model_idempotency_config.py

@@ -0,0 +1,131 @@
+# SPDX-FileCopyrightText: 2025 OmniNode Team <info@omninode.ai>
+#
+# SPDX-License-Identifier: Apache-2.0
+"""Idempotency configuration model for event bus message consumption.
+
+This module provides the configuration model for idempotency behavior in
+event bus consumers. When enabled, consumers deduplicate messages based on
+the `envelope_id` field from the event envelope using an INSERT ON CONFLICT
+DO NOTHING pattern.
+
+Idempotency Overview:
+    Idempotency ensures that processing the same message multiple times
+    produces the same result as processing it once. This is critical in
+    distributed systems where message delivery can be at-least-once.
+
+    The idempotency store tracks processed `envelope_id` values:
+    - On first encounter: Record envelope_id, process message
+    - On duplicate: Skip processing (already recorded)
+    - After retention period: Prune old records to limit storage
+
+Store Types:
+    - postgres: Production-grade persistent storage using INSERT ON CONFLICT
+    - memory: In-memory store for testing only (data lost on restart)
+
+See Also:
+    - EventBusSubcontractWiring: Uses this configuration for consumer setup
+    - docs/patterns/idempotency_patterns.md: Implementation details
+"""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class ModelIdempotencyConfig(BaseModel):
+    """Idempotency configuration for message consumption.
+
+    When enabled, the consumer deduplicates messages based on the `envelope_id`
+    field from the event envelope. The deduplication key is always `envelope_id`
+    (not configurable) to ensure consistent behavior across all consumers.
+
+    Attributes:
+        enabled: Whether to enable idempotency checking. When False, all
+            messages are processed regardless of prior processing.
+            Default: False.
+        store_type: Backend for storing processed envelope IDs.
+            - "postgres": Production-grade, uses INSERT ON CONFLICT DO NOTHING
+            - "memory": In-memory store for testing only
+            Default: "postgres".
+        retention_days: Number of days to retain processed envelope IDs before
+            cleanup. Longer retention uses more storage but provides stronger
+            deduplication guarantees for delayed retries.
+            Must be between 1 and 90 days. Default: 7.
+
+    Example:
+        ```python
+        from omnibase_infra.models.event_bus import ModelIdempotencyConfig
+
+        # Production configuration
+        config = ModelIdempotencyConfig(
+            enabled=True,
+            store_type="postgres",
+            retention_days=14,
+        )
+
+        # Testing configuration
+        test_config = ModelIdempotencyConfig(
+            enabled=True,
+            store_type="memory",
+            retention_days=1,
+        )
+
+        # Disabled (default behavior)
+        disabled = ModelIdempotencyConfig()  # enabled=False
+        ```
+
+    Configuration Guidelines:
+        - Enable idempotency for all consumers processing side-effecting events
+        - Use "postgres" store_type in production for durability
+        - Set retention_days based on maximum expected retry window
+        - For high-throughput topics, consider shorter retention to reduce storage
+
+    Note:
+        The deduplication key is always the `envelope_id` field from the event
+        envelope. This is intentionally not configurable to ensure consistent
+        behavior and prevent misconfiguration.
+
+    See Also:
+        EventBusSubcontractWiring: Consumer configuration that uses this model.
+    """
+
+    model_config = ConfigDict(
+        frozen=True,
+        extra="forbid",
+        json_schema_extra={
+            "examples": [
+                {
+                    "enabled": True,
+                    "store_type": "postgres",
+                    "retention_days": 7,
+                },
+                {
+                    "enabled": True,
+                    "store_type": "memory",
+                    "retention_days": 1,
+                },
+            ]
+        },
+    )
+
+    enabled: bool = Field(
+        default=False,
+        description="Enable idempotency checking for message deduplication",
+    )
+
+    store_type: Literal["postgres", "memory"] = Field(
+        default="postgres",
+        description="Idempotency store backend. 'memory' is for testing only.",
+    )
+
+    retention_days: int = Field(
+        default=7,
+        ge=1,
+        le=90,
+        description="Days to retain processed envelope IDs before cleanup",
+    )
+
+
+__all__ = ["ModelIdempotencyConfig"]

omnibase_infra/models/event_bus/model_offset_policy_config.py

@@ -0,0 +1,107 @@
+# Copyright 2025 OmniNode Team. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+"""Kafka offset commit policy configuration model.
+
+This module defines the configuration for Kafka consumer offset commit strategies,
+controlling when offsets are committed relative to handler execution.
+
+Delivery Semantics:
+    - At-least-once (default): Offsets committed AFTER successful handler execution.
+      Messages may be redelivered on failure, requiring idempotent handlers.
+    - At-most-once: Offsets committed BEFORE handler execution.
+      Messages may be lost on failure, but never processed twice.
+    - Manual: Explicit offset control for complex transaction scenarios.
+
+Design Decision:
+    The default is `commit_after_handler` (at-least-once) because:
+    1. Message loss is typically worse than duplicate processing
+    2. Idempotency can be enforced at the handler level (via idempotency keys)
+    3. This aligns with Kafka best practices for reliable message processing
+
+See Also:
+    - ModelIdempotencyConfig: Pairs with at-least-once for duplicate detection
+    - docs/patterns/kafka_delivery_semantics.md: Full delivery guarantee documentation
+"""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class ModelOffsetPolicyConfig(BaseModel):
+    """Kafka offset commit policy configuration.
+
+    Controls when consumer offsets are committed relative to handler execution.
+    Default is 'commit_after_handler' for at-least-once delivery semantics.
+
+    Attributes:
+        commit_strategy: When to commit Kafka offsets relative to handler execution.
+            - "commit_after_handler": At-least-once delivery (default, safe).
+              Offsets committed only after successful handler completion.
+              Messages may be redelivered on failure - handlers must be idempotent.
+            - "commit_before_handler": At-most-once delivery (may lose messages).
+              Offsets committed before handler execution begins.
+              Suitable only when message loss is acceptable.
+            - "manual": Explicit offset control via handler callback.
+              For complex transactional scenarios requiring precise control.
+
+    Example:
+        ```python
+        from omnibase_infra.models.event_bus import ModelOffsetPolicyConfig
+
+        # Default: at-least-once (recommended)
+        config = ModelOffsetPolicyConfig()
+        assert config.commit_strategy == "commit_after_handler"
+
+        # Explicit at-most-once (use with caution)
+        config = ModelOffsetPolicyConfig(commit_strategy="commit_before_handler")
+
+        # Manual control for transactions
+        config = ModelOffsetPolicyConfig(commit_strategy="manual")
+        ```
+
+    Warning:
+        Using "commit_before_handler" may result in message loss if the handler
+        fails after offset commit. Only use when message loss is acceptable
+        (e.g., metrics, non-critical logs).
+
+    See Also:
+        ModelIdempotencyConfig: For duplicate detection with at-least-once delivery.
+    """
+
+    commit_strategy: Literal[
+        "commit_after_handler",
+        "commit_before_handler",
+        "manual",
+    ] = Field(
+        default="commit_after_handler",
+        description=(
+            "When to commit Kafka offsets relative to handler execution. "
+            "'commit_after_handler' provides at-least-once delivery (default, safe). "
+            "'commit_before_handler' provides at-most-once delivery (may lose messages). "
+            "'manual' provides explicit control for transactional scenarios."
+        ),
+    )
+
+    model_config = ConfigDict(
+        frozen=True,
+        extra="forbid",
+        json_schema_extra={
+            "examples": [
+                {
+                    "commit_strategy": "commit_after_handler",
+                },
+                {
+                    "commit_strategy": "commit_before_handler",
+                },
+                {
+                    "commit_strategy": "manual",
+                },
+            ]
+        },
+    )
+
+
+__all__ = ["ModelOffsetPolicyConfig"]

omnibase_infra/models/resilience/model_circuit_breaker_config.py

@@ -58,6 +58,9 @@ class ModelCircuitBreakerConfig(BaseModel):
         transport_type: Transport type for error context classification.
             Determines which error code is used when the circuit opens.
             Default: HTTP.
+        half_open_successes: Number of successful requests required to close
+            the circuit from half-open state. Higher values provide more
+            confidence before closing. Must be >= 1 and <= 10. Default: 1.
 
     Example:
         ```python
@@ -114,6 +117,16 @@ class ModelCircuitBreakerConfig(BaseModel):
         description="Transport type for error context classification",
     )
 
+    half_open_successes: int = Field(
+        default=1,
+        ge=1,
+        le=10,
+        description=(
+            "Number of successful requests required to close the circuit from "
+            "half-open state. Higher values provide more confidence before closing."
+        ),
+    )
+
     model_config = ConfigDict(
         frozen=True,
         extra="forbid",
@@ -124,12 +137,14 @@ class ModelCircuitBreakerConfig(BaseModel):
                     "reset_timeout_seconds": 60.0,
                     "service_name": "kafka.production",
                     "transport_type": "kafka",
+                    "half_open_successes": 1,
                 },
                 {
                     "threshold": 3,
                     "reset_timeout_seconds": 120.0,
                     "service_name": "postgresql-primary",
                     "transport_type": "db",
+                    "half_open_successes": 2,
                 },
             ]
         },

omnibase_infra/models/validation/__init__.py

@@ -39,6 +39,12 @@ from omnibase_infra.models.validation.model_chain_violation import ModelChainVio
 from omnibase_infra.models.validation.model_coverage_metrics import (
     ModelCoverageMetrics,
 )
+from omnibase_infra.models.validation.model_declarative_node_validation_result import (
+    ModelDeclarativeNodeValidationResult,
+)
+from omnibase_infra.models.validation.model_declarative_node_violation import (
+    ModelDeclarativeNodeViolation,
+)
 from omnibase_infra.models.validation.model_execution_shape_rule import (
     ModelExecutionShapeRule,
 )
@@ -74,6 +80,8 @@ __all__ = [
     "ModelAnyTypeValidationResult",
     "ModelAnyTypeViolation",
     "ModelCategoryMatchResult",
+    "ModelDeclarativeNodeValidationResult",
+    "ModelDeclarativeNodeViolation",
     "ModelChainViolation",
     "ModelCoverageMetrics",
     "ModelExecutionShapeRule",

omnibase_infra/models/validation/model_declarative_node_validation_result.py

@@ -0,0 +1,139 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Declarative Node Validation Result Model.
+
+Defines the aggregate result structure for declarative node validation operations.
+Used by the validator to provide a structured result for CI pipeline integration
+with convenience methods for reporting.
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from omnibase_infra.models.validation.model_declarative_node_violation import (
+    ModelDeclarativeNodeViolation,
+)
+
+
+class ModelDeclarativeNodeValidationResult(BaseModel):
+    """Aggregate result of declarative node validation.
+
+    Provides a structured result for CI pipeline integration with
+    convenience methods for reporting.
+
+    Attributes:
+        passed: True if no blocking violations found.
+        violations: List of all detected violations.
+        files_checked: Number of node.py files that were validated.
+        total_violations: Total count of violations.
+        blocking_count: Count of blocking (error severity) violations.
+        imperative_nodes: List of node class names that are imperative.
+
+    Example:
+        >>> result = ModelDeclarativeNodeValidationResult.from_violations(
+        ...     violations=[violation1, violation2],
+        ...     files_checked=10,
+        ... )
+        >>> if not result.passed:
+        ...     print(result.format_summary())
+    """
+
+    passed: bool = Field(
+        ...,
+        description="True if no blocking violations found",
+    )
+    violations: list[ModelDeclarativeNodeViolation] = Field(
+        default_factory=list,
+        description="List of all detected violations",
+    )
+    files_checked: int = Field(
+        default=0,
+        ge=0,
+        description="Number of node.py files that were validated",
+    )
+    total_violations: int = Field(
+        default=0,
+        ge=0,
+        description="Total count of violations",
+    )
+    blocking_count: int = Field(
+        default=0,
+        ge=0,
+        description="Count of blocking (error severity) violations",
+    )
+    imperative_nodes: list[str] = Field(
+        default_factory=list,
+        description="List of node class names that are imperative (have violations)",
+    )
+
+    model_config = ConfigDict(
+        frozen=True,
+        extra="forbid",
+        strict=True,
+    )
+
+    def __bool__(self) -> bool:
+        """Allow boolean context: if result: ...
+
+        Warning:
+            Non-standard __bool__: Returns True only when passed is True.
+            This differs from Pydantic default where bool(model) always returns True.
+        """
+        return self.passed
+
+    @classmethod
+    def from_violations(
+        cls,
+        violations: list[ModelDeclarativeNodeViolation],
+        files_checked: int = 0,
+    ) -> ModelDeclarativeNodeValidationResult:
+        """Create a result from a list of violations.
+
+        Args:
+            violations: List of detected violations.
+            files_checked: Number of node.py files that were checked.
+
+        Returns:
+            A ModelDeclarativeNodeValidationResult instance.
+        """
+        blocking_count = sum(1 for v in violations if v.is_blocking())
+        imperative_nodes = sorted(
+            {v.node_class_name for v in violations if v.node_class_name}
+        )
+        return cls(
+            passed=blocking_count == 0,
+            violations=violations,
+            files_checked=files_checked,
+            total_violations=len(violations),
+            blocking_count=blocking_count,
+            imperative_nodes=imperative_nodes,
+        )
+
+    def format_for_ci(self) -> list[str]:
+        """Format all violations for CI output.
+
+        Returns:
+            List of formatted strings for CI annotation.
+        """
+        return [v.format_for_ci() for v in self.violations]
+
+    def format_summary(self) -> str:
+        """Format a summary for console output.
+
+        Returns:
+            Summary string with pass/fail status and counts.
+        """
+        status = "PASSED" if self.passed else "FAILED"
+        summary = (
+            f"Declarative Node Validation: {status}\n"
+            f"  Files checked: {self.files_checked}\n"
+            f"  Total violations: {self.total_violations}\n"
+            f"  Blocking violations: {self.blocking_count}"
+        )
+        if self.imperative_nodes:
+            summary += f"\n  Imperative nodes: {', '.join(self.imperative_nodes)}"
+        return summary
+
+
+__all__ = ["ModelDeclarativeNodeValidationResult"]