omnibase_infra 0.2.6__py3-none-any.whl

omnibase_infra/contracts/handlers/mcp/handler_contract.yaml

@@ -0,0 +1,141 @@
+# Handler ID follows convention: {node_type}.{domain}.handler
+handler_id: effect.mcp.handler
+name: MCP Handler
+contract_version:
+  major: 1
+  minor: 0
+  patch: 0
+description: >
+  Effect handler for Model Context Protocol (MCP) integration. Exposes ONEX nodes as MCP tools for AI agent integration via streamable HTTP transport.
+
+descriptor:
+  node_archetype: effect
+  purity: side_effecting
+  # Idempotent: true for list_tools/describe, false for call_tool (depends on target)
+  # Overall handler is marked non-idempotent since tool execution may have side effects.
+  idempotent: false
+  # TIMEOUT CONFIGURATION (30 seconds)
+  # ---------------------------------
+  # MCP tool execution timeout. This is the default timeout for tool calls.
+  # Individual tools may have their own timeout configurations.
+  #
+  # OVERRIDE GUIDANCE:
+  # - Reduce for latency-sensitive deployments
+  # - Increase for tools with known long execution times
+  # - Consider per-tool timeout configuration for fine-grained control
+  timeout_ms: 30000
+  retry_policy:
+    enabled: true
+    max_retries: 3
+    backoff_strategy: exponential
+    base_delay_ms: 500
+    max_delay_ms: 10000
+  circuit_breaker:
+    enabled: true
+    failure_threshold: 5
+    # Reset timeout: 60s = 2x handler timeout_ms
+    timeout_ms: 60000
+  # Concurrent: MCP supports multiple simultaneous tool calls
+  concurrency_policy: parallel_ok
+  isolation_policy: none
+  observability_level: standard
+capability_outputs:
+  - mcp.list_tools
+  - mcp.call_tool
+  - mcp.describe
+# NOTE: Models defined in OMN-1288 (MCP Handler)
+input_model: omnibase_infra.handlers.models.mcp.ModelMcpToolCall
+output_model: omnibase_infra.handlers.models.mcp.ModelMcpToolResult
+supports_lifecycle: true
+supports_health_check: true
+supports_provisioning: false
+tags:
+  - mcp
+  - effect
+  - infrastructure
+  - ai-agent
+  - tool-interface
+metadata:
+  author: OmniNode Team
+  ticket: OMN-1288
+  transport:
+    # =========================================================================
+    # TRANSPORT CONFIGURATION
+    # =========================================================================
+    # MCP transport layer configuration for streamable HTTP.
+    # =========================================================================
+    type: streamable_http
+    default_host: "0.0.0.0"
+    default_port: 8090
+    default_path: "/mcp"
+    # Stateless mode for horizontal scaling (recommended for production)
+    stateless: true
+    # JSON response mode for compatibility (recommended)
+    json_response: true
+  security:
+    # =========================================================================
+    # SECURITY CONFIGURATION
+    # =========================================================================
+    # Security constraints for MCP operations.
+    # =========================================================================
+
+    # -------------------------------------------------------------------------
+    # AUTHENTICATION
+    # -------------------------------------------------------------------------
+    # MCP protocol supports API key authentication.
+    authentication:
+      # Whether authentication is required for tool access
+      required: false
+      # Authentication methods supported
+      methods:
+        - api_key_header
+      # Header name for API key authentication
+      api_key_header: "X-MCP-API-Key"
+    # -------------------------------------------------------------------------
+    # TOOL ACCESS CONTROL
+    # -------------------------------------------------------------------------
+    # Controls which tools can be exposed via MCP.
+    tool_access:
+      # Maximum number of tools that can be exposed
+      max_tools: 100
+      # Tags required for a node to be exposed as MCP tool
+      required_tags: []
+      # Tags that exclude a node from MCP exposure
+      excluded_tags:
+        - internal
+        - deprecated
+        - unsafe
+    # -------------------------------------------------------------------------
+    # RATE LIMITING
+    # -------------------------------------------------------------------------
+    rate_limiting:
+      enabled: false
+      deferred_to: orchestration_layer
+      future_considerations:
+        - per_tool_limits: "Different limits per tool based on complexity"
+        - burst_allowance: "Token bucket with configurable burst"
+        - client_tracking: "Rate limit by API key or client ID"
+    # -------------------------------------------------------------------------
+    # INPUT VALIDATION
+    # -------------------------------------------------------------------------
+    input_validation:
+      # Maximum size of tool arguments (in bytes)
+      max_arguments_size: 1048576 # 1 MB
+      # Maximum depth of nested objects in arguments
+      max_nesting_depth: 10
+      # Validate arguments against tool schema
+      validate_schema: true
+    # -------------------------------------------------------------------------
+    # AUDIT AND LOGGING
+    # -------------------------------------------------------------------------
+    audit_logging:
+      required_events:
+        - tool_invocation
+        - authentication_failure
+        - rate_limit_exceeded
+        - tool_execution_error
+      security_event_level: warning
+      include_correlation_id: true
+      never_log:
+        - api_keys
+        - sensitive_arguments

omnibase_infra/decorators/__init__.py

@@ -0,0 +1,29 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""ONEX Infrastructure Decorators.
+
+This module provides decorators for ONEX infrastructure patterns.
+
+Decorators
+----------
+allow_any
+    Exempt functions/classes from Any type validation. Used as a marker
+    for the AST-based validator in ``omnibase_infra.validation.any_type_validator``.
+
+Example Usage
+-------------
+    >>> from omnibase_infra.decorators import allow_any
+    >>>
+    >>> @allow_any("Required for legacy API - see OMN-1234")
+    ... def legacy_handler(data: Any) -> Any:
+    ...     return process_legacy(data)
+
+See Also
+--------
+- ``omnibase_infra.validation.any_type_validator``: Recognizes ``@allow_any``
+- CLAUDE.md: Any type policy documentation
+"""
+
+from omnibase_infra.decorators.allow_any import allow_any
+
+__all__: list[str] = ["allow_any"]

omnibase_infra/decorators/allow_any.py

@@ -0,0 +1,109 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Decorator to exempt functions/classes from Any type validation.
+
+This decorator is recognized by the ``any_type_validator.py`` AST-based validator.
+It marks functions or classes as intentionally using Any types with a documented
+reason, allowing the validator to skip checking those definitions.
+
+The decorator is a **no-op at runtime** - it simply returns the original function
+or class unchanged. Its sole purpose is to serve as a marker that the AST validator
+can detect and use to exempt the decorated entity from Any type violations.
+
+Usage
+-----
+Apply the decorator to functions or classes that intentionally use Any types:
+
+    @allow_any("Required for legacy API compatibility - see OMN-1234")
+    def legacy_handler(data: Any) -> Any:
+        return process_legacy(data)
+
+    @allow_any("Dynamic plugin dispatch requires Any for flexibility")
+    class PluginDispatcher:
+        def dispatch(self, payload: Any) -> Any:
+            return self._route(payload)
+
+The reason argument is optional but strongly recommended for code review
+and maintainability:
+
+    @allow_any()
+    def another_handler(data: Any) -> None:
+        ...
+
+See Also
+--------
+- ``omnibase_infra.validation.any_type_validator``: The AST validator that
+  recognizes this decorator
+- CLAUDE.md: Documentation of Any type policy and enforcement levels
+- ``docs/decisions/adr-any-type-pydantic-workaround.md``: ADR for Pydantic Any usage
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import TypeVar
+
+# Type variable for functions and classes
+# Using 'object' as the bound per ONEX strong typing policy (no 'Any')
+F = TypeVar("F", bound=Callable[..., object])
+
+
+def allow_any(reason: str = "") -> Callable[[F], F]:
+    """Mark a function or class as exempt from Any type validation.
+
+    This decorator is recognized by the AST-based Any type validator and
+    causes it to skip checking the decorated function or class for Any
+    type violations.
+
+    The decorator is a no-op at runtime - it returns the original function
+    or class unchanged.
+
+    Args:
+        reason: Documentation of why Any type usage is necessary. While
+            optional, providing a reason is strongly recommended for code
+            review and future maintainability. The reason is not used at
+            runtime but serves as documentation for reviewers.
+
+    Returns:
+        A decorator function that returns its input unchanged.
+
+    Examples:
+        Basic usage with reason (recommended):
+
+        >>> @allow_any("Required for JSON API responses - see OMN-1234")
+        ... def process_json(data: Any) -> Any:
+        ...     return transform(data)
+
+        Usage without reason (discouraged but valid):
+
+        >>> @allow_any()
+        ... def legacy_function(data: Any) -> None:
+        ...     handle(data)
+
+        Class-level exemption:
+
+        >>> @allow_any("Plugin system requires dynamic typing")
+        ... class DynamicPlugin:
+        ...     def execute(self, payload: Any) -> Any:
+        ...         return self._run(payload)
+
+    Note:
+        The ``reason`` parameter is purely for documentation. It is not
+        stored, logged, or validated at runtime. The validator extracts
+        the decorator presence from the AST without evaluating the
+        decorator's arguments.
+    """
+    # The reason parameter is intentionally unused at runtime.
+    # It exists solely for documentation purposes in the source code.
+    # The AST validator only checks for the decorator's presence,
+    # not its arguments.
+    _ = reason  # Explicitly mark as intentionally unused
+
+    def decorator(func: F) -> F:
+        """Return the function unchanged (no-op decorator)."""
+        return func
+
+    return decorator
+
+
+__all__: list[str] = ["allow_any"]

omnibase_infra/dlq/__init__.py

@@ -0,0 +1,90 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""ONEX Infrastructure DLQ (Dead Letter Queue) System.
+
+This module provides DLQ replay tracking capabilities for message
+processing in distributed systems. It enables persistent tracking
+of replay attempts through PostgreSQL.
+
+Components:
+    - Constants: Shared validation patterns (constants_dlq.py)
+    - Models: Pydantic models for DLQ tracking configuration and records
+    - Tracker: PostgreSQL-based tracker for replay history persistence
+
+Constants:
+    - PATTERN_TABLE_NAME: Regex pattern string for PostgreSQL table name validation
+    - REGEX_TABLE_NAME: Pre-compiled regex for runtime validation
+
+Models:
+    - ModelDlqTrackingConfig: Configuration for PostgreSQL-based tracking
+    - ModelDlqReplayRecord: Record of a DLQ message replay attempt
+    - EnumReplayStatus: Status enum for replay operations
+
+Tracker:
+    - ServiceDlqTracking: PostgreSQL tracker for replay history
+
+Example - Recording Replay Attempts:
+    >>> from omnibase_infra.dlq import (
+    ...     ServiceDlqTracking,
+    ...     ModelDlqTrackingConfig,
+    ...     ModelDlqReplayRecord,
+    ...     EnumReplayStatus,
+    ... )
+    >>> from uuid import uuid4
+    >>> from datetime import datetime, timezone
+    >>>
+    >>> # Configure the tracker
+    >>> config = ModelDlqTrackingConfig(
+    ...     dsn="postgresql://user:pass@localhost:5432/mydb",
+    ...     storage_table="dlq_replay_history",
+    ... )
+    >>>
+    >>> # Initialize and use
+    >>> tracker = ServiceDlqTracking(config)
+    >>> await tracker.initialize()
+    >>> try:
+    ...     record = ModelDlqReplayRecord(
+    ...         id=uuid4(),
+    ...         original_message_id=uuid4(),
+    ...         replay_correlation_id=uuid4(),
+    ...         original_topic="dev.orders.command.v1",
+    ...         target_topic="dev.orders.command.v1",
+    ...         replay_status=EnumReplayStatus.COMPLETED,
+    ...         replay_timestamp=datetime.now(timezone.utc),
+    ...         success=True,
+    ...         dlq_offset=12345,
+    ...         dlq_partition=0,
+    ...         retry_count=1,
+    ...     )
+    ...     await tracker.record_replay_attempt(record)
+    ...
+    ...     # Query replay history
+    ...     history = await tracker.get_replay_history(record.original_message_id)
+    ... finally:
+    ...     await tracker.shutdown()
+
+Related:
+    - scripts/dlq_replay.py - CLI tool for DLQ replay operations
+    - OMN-1032 - PostgreSQL tracking integration ticket
+    - OMN-949 - DLQ configuration ticket
+"""
+
+from omnibase_infra.dlq.constants_dlq import PATTERN_TABLE_NAME, REGEX_TABLE_NAME
+from omnibase_infra.dlq.models import (
+    EnumReplayStatus,
+    ModelDlqReplayRecord,
+    ModelDlqTrackingConfig,
+)
+from omnibase_infra.dlq.service_dlq_tracking import ServiceDlqTracking
+
+__all__: list[str] = [
+    # Constants
+    "PATTERN_TABLE_NAME",  # Regex pattern string for table name validation
+    "REGEX_TABLE_NAME",  # Pre-compiled regex for runtime validation
+    # Tracker
+    "ServiceDlqTracking",
+    # Models
+    "EnumReplayStatus",
+    "ModelDlqReplayRecord",
+    "ModelDlqTrackingConfig",
+]

omnibase_infra/dlq/constants_dlq.py

@@ -0,0 +1,57 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""DLQ Constants and Shared Validation Patterns.
+
+This module provides shared constants for the DLQ subsystem, ensuring
+consistent validation patterns across models and services.
+
+Defense-in-Depth Note:
+    The PATTERN_TABLE_NAME constant is intentionally used in BOTH:
+    1. Pydantic model validation (ModelDlqTrackingConfig.storage_table field)
+    2. Runtime validation (ServiceDlqTracking._validate_storage_table method)
+
+    This defense-in-depth approach ensures SQL injection prevention even if:
+    - Direct attribute assignment bypasses Pydantic validation
+    - Deserialization from untrusted sources bypasses model validation
+    - Future code changes inadvertently bypass config validation
+
+    DO NOT remove either validation layer. Both are intentional and required.
+
+Related:
+    - model_dlq_tracking_config.py - Pydantic field pattern validation
+    - service_dlq_tracking.py - ServiceDlqTracking runtime defense-in-depth validation
+    - OMN-1032 - PostgreSQL tracking integration ticket
+"""
+
+from __future__ import annotations
+
+import re
+
+# =============================================================================
+# TABLE NAME VALIDATION
+# =============================================================================
+
+# Regex pattern string for valid PostgreSQL table names
+# Must start with letter or underscore, followed by letters, digits, or underscores
+# This matches PostgreSQL's identifier naming rules for unquoted identifiers
+#
+# Used in:
+#   - ModelDlqTrackingConfig: Pydantic field pattern constraint
+#   - ServiceDlqTracking: Runtime defense-in-depth validation
+#
+# Pattern explanation:
+#   ^           - Start of string
+#   [a-zA-Z_]   - First character must be letter (a-z, A-Z) or underscore
+#   [a-zA-Z0-9_]* - Subsequent characters can be letters, digits, or underscores
+#   $           - End of string
+PATTERN_TABLE_NAME = r"^[a-zA-Z_][a-zA-Z0-9_]*$"
+
+# Pre-compiled regex for runtime validation (avoids recompilation overhead)
+# This is the compiled version of PATTERN_TABLE_NAME for use in service code
+REGEX_TABLE_NAME = re.compile(PATTERN_TABLE_NAME)
+
+
+__all__: list[str] = [
+    "PATTERN_TABLE_NAME",
+    "REGEX_TABLE_NAME",
+]

omnibase_infra/dlq/models/__init__.py

@@ -0,0 +1,26 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""ONEX Infrastructure DLQ Models.
+
+This module provides Pydantic models for the DLQ replay tracking system,
+including configuration and replay record models.
+
+Exports:
+    ModelDlqTrackingConfig: Configuration for PostgreSQL-based DLQ tracking service
+    ModelDlqReplayRecord: Record of a DLQ message replay attempt
+    EnumReplayStatus: Status enum for replay operations
+
+Related:
+    - scripts/dlq_replay.py - CLI tool for DLQ replay operations
+    - OMN-1032 - PostgreSQL tracking integration ticket
+"""
+
+from omnibase_infra.dlq.models.enum_replay_status import EnumReplayStatus
+from omnibase_infra.dlq.models.model_dlq_replay_record import ModelDlqReplayRecord
+from omnibase_infra.dlq.models.model_dlq_tracking_config import ModelDlqTrackingConfig
+
+__all__: list[str] = [
+    "EnumReplayStatus",
+    "ModelDlqReplayRecord",
+    "ModelDlqTrackingConfig",
+]

omnibase_infra/dlq/models/enum_replay_status.py

@@ -0,0 +1,37 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""DLQ Replay Status Enum.
+
+This module provides the status enum for DLQ replay operations.
+
+Related:
+    - scripts/dlq_replay.py - CLI tool that uses this enum
+    - OMN-1032 - PostgreSQL tracking integration ticket
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+
+
+class EnumReplayStatus(str, Enum):
+    """Status of a DLQ replay operation.
+
+    This enum tracks the lifecycle of a replay attempt:
+    - PENDING: Replay has been initiated but not yet completed
+    - COMPLETED: Message was successfully replayed to target topic
+    - FAILED: Replay attempt failed (will be recorded with error_message)
+    - SKIPPED: Message was intentionally not replayed (e.g., non-retryable error)
+
+    Usage:
+        This enum is the canonical definition for replay status tracking.
+        It is imported by scripts/dlq_replay.py for CLI usage.
+    """
+
+    PENDING = "pending"
+    COMPLETED = "completed"
+    FAILED = "failed"
+    SKIPPED = "skipped"
+
+
+__all__: list[str] = ["EnumReplayStatus"]

omnibase_infra/dlq/models/model_dlq_replay_record.py

@@ -0,0 +1,135 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""DLQ Replay Record Model.
+
+This module provides the Pydantic model for DLQ replay records,
+representing the state of a message replay operation stored in PostgreSQL.
+
+Related:
+    - scripts/dlq_replay.py - CLI tool that uses this model
+    - OMN-1032 - PostgreSQL tracking integration ticket
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from uuid import UUID
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from omnibase_infra.dlq.models.enum_replay_status import EnumReplayStatus
+
+
+class ModelDlqReplayRecord(BaseModel):
+    """Record of a DLQ message replay attempt.
+
+    This model represents a single replay attempt stored in PostgreSQL,
+    tracking both the original message context and the replay outcome.
+
+    Table Schema:
+        CREATE TABLE IF NOT EXISTS dlq_replay_history (
+            id UUID PRIMARY KEY,
+            original_message_id UUID NOT NULL,
+            replay_correlation_id UUID NOT NULL,
+            original_topic VARCHAR(255) NOT NULL,
+            target_topic VARCHAR(255) NOT NULL,
+            replay_status VARCHAR(50) NOT NULL,
+            replay_timestamp TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT now(),
+            success BOOLEAN NOT NULL,
+            error_message TEXT,
+            dlq_offset BIGINT NOT NULL,
+            dlq_partition INTEGER NOT NULL,
+            retry_count INTEGER NOT NULL DEFAULT 0
+        );
+
+    Attributes:
+        id: Unique identifier for this replay record (primary key).
+        original_message_id: Correlation ID from the original DLQ message.
+            This links the replay to the original failed message.
+        replay_correlation_id: New correlation ID assigned during replay.
+            Used for tracing the replayed message through the system.
+        original_topic: The Kafka topic where the message originally failed.
+        target_topic: The topic where the message was replayed to.
+            Usually same as original_topic, but may differ for rerouting.
+        replay_status: Current status of the replay operation.
+        replay_timestamp: When the replay was attempted (UTC).
+        success: Whether the replay was successful.
+            True for COMPLETED status, False for FAILED/SKIPPED.
+        error_message: Error details if replay failed. None for success.
+        dlq_offset: Kafka offset of the message in the DLQ topic.
+        dlq_partition: Kafka partition of the message in the DLQ topic.
+        retry_count: Number of times this message has been retried.
+            Includes previous attempts before this replay.
+
+    Example:
+        >>> from uuid import uuid4
+        >>> from datetime import datetime, timezone
+        >>> record = ModelDlqReplayRecord(
+        ...     id=uuid4(),
+        ...     original_message_id=uuid4(),
+        ...     replay_correlation_id=uuid4(),
+        ...     original_topic="dev.orders.command.v1",
+        ...     target_topic="dev.orders.command.v1",
+        ...     replay_status=EnumReplayStatus.COMPLETED,
+        ...     replay_timestamp=datetime.now(timezone.utc),
+        ...     success=True,
+        ...     dlq_offset=12345,
+        ...     dlq_partition=0,
+        ...     retry_count=1,
+        ... )
+    """
+
+    model_config = ConfigDict(
+        frozen=True,
+        extra="forbid",
+        from_attributes=True,
+    )
+
+    id: UUID = Field(
+        description="Unique identifier for this replay record (primary key)",
+    )
+    original_message_id: UUID = Field(
+        description="Correlation ID from the original DLQ message",
+    )
+    replay_correlation_id: UUID = Field(
+        description="New correlation ID assigned during replay",
+    )
+    original_topic: str = Field(
+        description="The Kafka topic where the message originally failed",
+        min_length=1,
+        max_length=255,
+    )
+    target_topic: str = Field(
+        description="The topic where the message was replayed to",
+        min_length=1,
+        max_length=255,
+    )
+    replay_status: EnumReplayStatus = Field(
+        description="Current status of the replay operation",
+    )
+    replay_timestamp: datetime = Field(
+        description="When the replay was attempted (UTC)",
+    )
+    success: bool = Field(
+        description="Whether the replay was successful",
+    )
+    error_message: str | None = Field(
+        default=None,
+        description="Error details if replay failed, None for success",
+    )
+    dlq_offset: int = Field(
+        description="Kafka offset of the message in the DLQ topic",
+        ge=0,
+    )
+    dlq_partition: int = Field(
+        description="Kafka partition of the message in the DLQ topic",
+        ge=0,
+    )
+    retry_count: int = Field(
+        default=0,
+        description="Number of times this message has been retried",
+        ge=0,
+    )
+
+
+__all__: list[str] = ["ModelDlqReplayRecord"]