omnibase_infra 0.2.1__py3-none-any.whl → 0.2.3__py3-none-any.whl

omnibase_infra/utils/util_retry_optimistic.py

@@ -0,0 +1,281 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Optimistic locking retry helper for concurrent data operations.
+
+This module provides utilities for retrying operations that may fail due to
+optimistic locking conflicts. Optimistic locking is a concurrency control
+strategy where conflicts are detected at write time rather than using locks.
+
+Use Cases:
+    - Database UPDATE with version checks (row_count=0 indicates conflict)
+    - CAS (Compare-And-Swap) operations in distributed systems
+    - Consul KV ModifyIndex-based updates
+    - Any operation where conflict detection is based on return value
+
+Design Decisions:
+    - No circuit breaker integration: Optimistic conflicts are application logic,
+      not infrastructure failures. They indicate contention, not service degradation.
+    - Lower initial backoff: 0.1s vs 1.0s for transient errors because conflicts
+      typically resolve faster as other transactions complete.
+    - Jitter by default: Critical for preventing thundering herd on high-contention
+      resources where multiple retries might synchronize.
+    - Caller-provided conflict check: Flexible for different conflict indicators
+      (row_count=0, version mismatch, boolean flags, etc.)
+
+Example:
+    >>> import asyncio
+    >>> from omnibase_infra.utils.util_retry_optimistic import (
+    ...     retry_on_optimistic_conflict,
+    ...     OptimisticConflictError,
+    ... )
+    >>>
+    >>> attempt_count = 0
+    >>> async def update_with_version_check():
+    ...     global attempt_count
+    ...     attempt_count += 1
+    ...     # Simulate success after 2 conflicts
+    ...     if attempt_count < 3:
+    ...         return {"row_count": 0}  # Conflict
+    ...     return {"row_count": 1}  # Success
+    >>>
+    >>> async def main():
+    ...     result = await retry_on_optimistic_conflict(
+    ...         update_with_version_check,
+    ...         check_conflict=lambda r: r["row_count"] == 0,
+    ...         max_retries=5,
+    ...     )
+    ...     print(f"Success after {attempt_count} attempts")
+    >>>
+    >>> asyncio.run(main())  # doctest: +SKIP
+    Success after 3 attempts
+
+See Also:
+    - ONEX infrastructure patterns documentation
+    - PostgreSQL advisory locks vs optimistic locking
+    - Consul KV ModifyIndex documentation
+
+.. versionadded:: 0.10.0
+    Created for database operations requiring optimistic concurrency control.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import random
+from collections.abc import Awaitable, Callable
+from typing import TYPE_CHECKING, TypeVar
+
+if TYPE_CHECKING:
+    from uuid import UUID
+
+logger = logging.getLogger(__name__)
+
+# Generic type for the return value of the retried function
+T = TypeVar("T")
+
+
+class OptimisticConflictError(Exception):
+    """Exception raised when optimistic locking retries are exhausted.
+
+    This exception indicates that an operation failed due to repeated optimistic
+    locking conflicts after all retry attempts. The caller should handle this
+    by either:
+    - Reporting the conflict to the user
+    - Using a different conflict resolution strategy
+    - Applying exponential backoff at a higher level
+
+    Note:
+        This is a standard Python exception, not an ONEX error. Optimistic
+        conflicts are expected application behavior, not infrastructure failures.
+
+    Attributes:
+        attempts: The total number of attempts made (including initial attempt).
+        last_result: The result from the final failed attempt, useful for
+            debugging or logging the conflict state.
+
+    Example:
+        >>> from omnibase_infra.utils.util_retry_optimistic import OptimisticConflictError
+        >>>
+        >>> try:
+        ...     # ... retry logic that exhausted retries
+        ...     raise OptimisticConflictError(
+        ...         attempts=4,
+        ...         last_result={"row_count": 0, "current_version": 5}
+        ...     )
+        ... except OptimisticConflictError as e:
+        ...     print(f"Failed after {e.attempts} attempts")
+        ...     print(f"Last conflict state: {e.last_result}")
+        Failed after 4 attempts
+        Last conflict state: {'row_count': 0, 'current_version': 5}
+    """
+
+    def __init__(self, *, attempts: int, last_result: object) -> None:
+        """Initialize OptimisticConflictError.
+
+        Args:
+            attempts: Total number of attempts made.
+            last_result: Result from the final attempt.
+        """
+        self.attempts = attempts
+        self.last_result = last_result
+        super().__init__(
+            f"Optimistic locking conflict persisted after {attempts} attempts. "
+            f"Last result: {last_result}"
+        )
+
+
+async def retry_on_optimistic_conflict(
+    fn: Callable[[], Awaitable[T]],
+    *,
+    check_conflict: Callable[[T], bool],
+    max_retries: int = 3,
+    initial_backoff: float = 0.1,
+    max_backoff: float = 5.0,
+    backoff_multiplier: float = 2.0,
+    jitter: bool = True,
+    correlation_id: UUID | None = None,
+) -> T:
+    """Execute async function with retry on optimistic locking conflict.
+
+    This function implements exponential backoff retry logic for operations
+    that may fail due to optimistic locking conflicts. Unlike transient error
+    retries, this does NOT integrate with circuit breakers since conflicts
+    indicate contention, not service degradation.
+
+    Args:
+        fn: Async function to execute. Should take no arguments; use closures
+            or functools.partial to bind arguments. Example:
+            ``lambda: update_record(id=123, data=data)``
+        check_conflict: Callable that inspects the result and returns True if
+            the result indicates a conflict. Examples:
+            - ``lambda r: r.row_count == 0`` (database update)
+            - ``lambda r: r.success is False`` (boolean result)
+            - ``lambda r: r.version != expected_version`` (version mismatch)
+        max_retries: Maximum number of retry attempts after the initial attempt.
+            Total attempts = max_retries + 1. Defaults to 3.
+        initial_backoff: Initial backoff delay in seconds before first retry.
+            Lower than transient error defaults (0.1s vs 1.0s) because conflicts
+            typically resolve quickly. Defaults to 0.1.
+        max_backoff: Maximum backoff delay cap in seconds. Prevents excessive
+            wait times. Defaults to 5.0.
+        backoff_multiplier: Multiplier for exponential backoff between retries.
+            Delay doubles by default: 0.1s -> 0.2s -> 0.4s -> 0.8s. Defaults to 2.0.
+        jitter: If True, adds random jitter (50-150% of delay) to prevent
+            thundering herd when multiple clients retry simultaneously.
+            Strongly recommended for high-contention scenarios. Defaults to True.
+        correlation_id: Optional correlation ID for structured logging. When
+            provided, retry attempts are logged with this ID for distributed
+            tracing. Defaults to None.
+
+    Returns:
+        The result of ``fn()`` when ``check_conflict(result)`` returns False.
+
+    Raises:
+        OptimisticConflictError: If all retry attempts are exhausted and the
+            operation still indicates a conflict. Contains ``attempts`` count
+            and ``last_result`` for debugging.
+
+    Example:
+        Basic usage with row count check::
+
+            from functools import partial
+            from omnibase_infra.utils.util_retry_optimistic import (
+                retry_on_optimistic_conflict,
+                OptimisticConflictError,
+            )
+
+            async def update_with_version(id: str, data: dict, version: int):
+                return await db.execute(
+                    "UPDATE t SET data=$1, version=version+1 "
+                    "WHERE id=$2 AND version=$3",
+                    data, id, version
+                )
+
+            try:
+                result = await retry_on_optimistic_conflict(
+                    partial(update_with_version, "abc", {"name": "new"}, 5),
+                    check_conflict=lambda r: r.row_count == 0,
+                    max_retries=5,
+                    correlation_id=correlation_id,
+                )
+            except OptimisticConflictError as e:
+                logger.error(f"Update failed after {e.attempts} attempts")
+                raise
+
+    Warning:
+        The ``fn`` callable should be idempotent or at least safe to retry.
+        This function will call ``fn`` multiple times on conflicts.
+
+    Note:
+        Backoff timing with default parameters (jitter disabled for clarity):
+        - Attempt 1: immediate
+        - Attempt 2: wait 0.1s
+        - Attempt 3: wait 0.2s
+        - Attempt 4: wait 0.4s
+        - Total max wait: ~0.7s (with max_retries=3)
+
+    .. versionadded:: 0.10.0
+    """
+    backoff = initial_backoff
+    last_result: T | None = None
+
+    for attempt in range(max_retries + 1):  # +1 for initial attempt
+        result = await fn()
+
+        if not check_conflict(result):
+            # Success - no conflict detected
+            if attempt > 0 and correlation_id is not None:
+                logger.info(
+                    "Optimistic conflict resolved after %d retries",
+                    attempt,
+                    extra={
+                        "correlation_id": str(correlation_id),
+                        "total_attempts": attempt + 1,
+                        "action": "optimistic_conflict_resolved",
+                    },
+                )
+            return result
+
+        # Conflict detected - store result for potential error reporting
+        last_result = result
+
+        if attempt == max_retries:
+            # All retries exhausted
+            break
+
+        # Log retry attempt if correlation_id provided
+        if correlation_id is not None:
+            logger.debug(
+                "Optimistic conflict detected, retrying (attempt %d/%d)",
+                attempt + 1,
+                max_retries + 1,
+                extra={
+                    "correlation_id": str(correlation_id),
+                    "attempt": attempt + 1,
+                    "max_attempts": max_retries + 1,
+                    "backoff_seconds": backoff,
+                    "action": "optimistic_conflict_retry",
+                },
+            )
+
+        # Calculate delay with optional jitter
+        delay = min(backoff, max_backoff)
+        if jitter:
+            # Apply 50-150% jitter to prevent thundering herd
+            delay *= 0.5 + random.random()
+
+        await asyncio.sleep(delay)
+        backoff *= backoff_multiplier
+
+    # All retries exhausted - raise conflict error
+    # Defensive check - last_result is guaranteed to be set after at least one attempt
+    if last_result is None:
+        raise AssertionError("Unreachable: last_result must be set after retries")
+    raise OptimisticConflictError(attempts=max_retries + 1, last_result=last_result)
+
+
+__all__: list[str] = [
+    "OptimisticConflictError",
+    "retry_on_optimistic_conflict",
+]

omnibase_infra/validation/__init__.py

@@ -200,17 +200,8 @@ from omnibase_infra.validation.validator_runtime_shape import (
     enforce_execution_shape,
 )
 
-# Security validation for handler introspection and security constraints
-from omnibase_infra.validation.validator_security import (
-    SENSITIVE_METHOD_PATTERNS,
-    SENSITIVE_PARAMETER_NAMES,
-    SecurityRuleId,
-    convert_to_validation_error,
-    has_sensitive_parameters,
-    is_sensitive_method_name,
-    validate_handler_security,
-    validate_method_exposure,
-)
+# Security validation (OMN-1277) - contract-driven validator
+from omnibase_infra.validation.validator_security import ValidatorSecurity
 
 # Topic category validation for execution shape enforcement
 from omnibase_infra.validation.validator_topic_category import (
@@ -229,8 +220,6 @@ __all__: list[str] = [
     "EXECUTION_SHAPE_RULES",  # Runtime shape validation rules
     "INFRA_MAX_UNIONS",  # Infrastructure max union threshold
     "NODE_ARCHETYPE_EXPECTED_CATEGORIES",  # Node archetype categories
-    "SENSITIVE_METHOD_PATTERNS",  # Security validation patterns
-    "SENSITIVE_PARAMETER_NAMES",  # Security validation names
     "TOPIC_CATEGORY_PATTERNS",  # Topic category patterns
     "TOPIC_SUFFIXES",  # Topic suffix constants
     # Errors
@@ -239,7 +228,6 @@ __all__: list[str] = [
     "RoutingCoverageError",  # Routing coverage error (OMN-958)
     # Enums
     "EnumContractViolationSeverity",  # Contract violation severity
-    "SecurityRuleId",  # Security rule identifiers
     # Models
     "ModelAnyTypeValidationResult",  # Any type validation result (OMN-1276)
     "ModelContractLintResult",  # Contract lint result
@@ -261,9 +249,9 @@ __all__: list[str] = [
     "TopicCategoryASTVisitor",  # Topic category AST visitor
     "TopicCategoryValidator",  # Topic category validator
     "ValidationAggregator",  # Validation error aggregation (OMN-1091)
+    "ValidatorSecurity",  # Contract-driven security validator (OMN-1277)
     # Functions
     "check_routing_coverage_ci",  # CI routing coverage check
-    "convert_to_validation_error",  # Error conversion utility
     "detect_message_category",  # Message category detection
     "discover_message_types",  # Message type discovery
     "discover_registered_routes",  # Route discovery
@@ -271,9 +259,7 @@ __all__: list[str] = [
     "enforce_execution_shape",  # Execution shape enforcement
     "get_execution_shape_rules",  # Get shape rules
     "get_validation_summary",  # Get validation summary
-    "has_sensitive_parameters",  # Sensitive parameter check
     "is_isinstance_union",  # Check if union is in isinstance() call
-    "is_sensitive_method_name",  # Sensitive method check
     "lint_contract_file",  # Lint single contract file
     "lint_contracts_ci",  # CI contract linting
     "lint_contracts_in_directory",  # Directory contract linting
@@ -286,7 +272,6 @@ __all__: list[str] = [
     "validate_execution_shapes",  # Execution shape validation
     "validate_execution_shapes_ci",  # CI shape validation
     "validate_handler_registration",  # Handler registration validation (OMN-1098)
-    "validate_handler_security",  # Handler security validation
     "validate_infra_all",  # Infrastructure validation
     "validate_infra_architecture",  # Infrastructure architecture
     "validate_infra_circular_imports",  # Circular import check
@@ -298,7 +283,6 @@ __all__: list[str] = [
     "validate_localhandler_in_file",  # LocalHandler file validation (OMN-743)
     "validate_message_chain",  # Message chain validation
     "validate_message_on_topic",  # Topic message validation
-    "validate_method_exposure",  # Method exposure validation
     "validate_patterns",  # Re-export from omnibase_core
     "validate_routing_coverage_on_startup",  # Startup routing check
     "validate_topic_categories_in_directory",  # Directory topic validation

omnibase_infra/validation/contracts/security.validation.yaml

@@ -0,0 +1,114 @@
+contract_kind: validation_subcontract
+validation:
+  version:
+    major: 1
+    minor: 0
+    patch: 0
+  validator_id: security
+  validator_name: ONEX Security Validator
+  validator_description: |
+    Validates Python source files for security concerns in handler implementations.
+    Detects sensitive method names that should be private, credential exposure in
+    method signatures, and admin/internal operations exposed publicly.
+
+    This validator performs static AST analysis to identify:
+    - Public methods with sensitive names (get_password, get_secret, etc.)
+    - Method signatures containing sensitive parameter names
+    - Admin/internal methods exposed without underscore prefix
+    - Decrypt operations exposed publicly
+
+    Part of OMN-1277: Refactor validators to be Handler and contract-driven.
+  target_patterns:
+    - "**/*.py"
+  exclude_patterns:
+    - "**/node_modules/**"
+    - "**/.git/**"
+    - "**/venv/**"
+    - "**/.venv/**"
+    - "**/__pycache__/**"
+    - "**/archived/**"
+    - "**/tests/**"
+    - "**/*_test.py"
+    - "**/test_*.py"
+    - "**/conftest.py"
+  rules:
+    - rule_id: sensitive_method_exposed
+      description: |
+        Detects public methods with sensitive names that should be private.
+        Matches patterns: get_password, get_secret, get_token, get_api_key,
+        get_credential*, fetch_password, fetch_secret, fetch_token,
+        validate_password, check_password, verify_password.
+      severity: error
+      enabled: true
+      parameters:
+        patterns:
+          - "^get_password$"
+          - "^get_secret$"
+          - "^get_token$"
+          - "^get_api_key$"
+          - "^get_credential"
+          - "^fetch_password$"
+          - "^fetch_secret$"
+          - "^fetch_token$"
+          - "^validate_password$"
+          - "^check_password$"
+          - "^verify_password$"
+    - rule_id: credential_in_signature
+      description: |
+        Detects method signatures containing sensitive parameter names.
+        Matches parameters: password, secret, token, api_key, apikey,
+        access_key, private_key, credential, auth_token, bearer_token,
+        decrypt_key, encryption_key.
+      severity: error
+      enabled: true
+      parameters:
+        sensitive_params:
+          - "password"
+          - "secret"
+          - "token"
+          - "api_key"
+          - "apikey"
+          - "access_key"
+          - "private_key"
+          - "credential"
+          - "auth_token"
+          - "bearer_token"
+          - "decrypt_key"
+          - "encryption_key"
+    - rule_id: admin_method_public
+      description: |
+        Detects admin or internal methods exposed without underscore prefix.
+        Matches patterns: admin_*, internal_*.
+      severity: warning
+      enabled: true
+      parameters:
+        patterns:
+          - "^admin_"
+          - "^internal_"
+    - rule_id: decrypt_method_public
+      description: |
+        Detects decrypt operations exposed publicly.
+        Matches patterns: decrypt_*.
+      severity: warning
+      enabled: true
+      parameters:
+        patterns:
+          - "^decrypt_"
+  # ============================================================================
+  # LINE-BASED SUPPRESSION
+  # ============================================================================
+  # If ANY pattern below appears on a source line, ALL security violations
+  # on that line are suppressed.
+  #
+  # Usage example:
+  #   def get_password(self) -> str:  # ONEX_EXCLUDE: security - required for legacy API
+  #   def admin_reset(self) -> None:  # security-ok: admin endpoint with auth guard
+  # ============================================================================
+  suppression_comments:
+    - "# ONEX_EXCLUDE: security"
+    - "# security-ok:"
+  severity_default: error
+  fail_on_error: true
+  fail_on_warning: false
+  max_violations: 0
+  parallel_execution: true

omnibase_infra/validation/infra_validators.py

@@ -37,10 +37,12 @@ from typing import TypedDict
 import yaml
 
 from omnibase_core.models.common import ModelValidationMetadata
+from omnibase_core.models.primitives import ModelSemVer
 from omnibase_core.models.validation.model_union_pattern import ModelUnionPattern
 from omnibase_core.validation import (
     CircularImportValidator,
     ModelContractValidationResult,
+    ModelImportValidationResult,
     ModelModuleImportResult,
     ModelValidationResult,
     validate_architecture,
@@ -423,7 +425,11 @@ INFRA_NODES_PATH = "src/omnibase_infra/nodes/"
 #                    (+2 unions for EnumPolicyType | str in validate_policy_type_value)
 #                    (-1 union: fix PolicyTypeInput validator coercion, changed return
 #                    type from str | EnumPolicyType to EnumPolicyType)
-INFRA_MAX_UNIONS = 96
+# - 98 (2026-01-20): OMN-1277 security validator contract refactoring (+2 unions)
+#                    ast.FunctionDef | ast.AsyncFunctionDef for AST method type checking
+# - 105 (2026-01-21): Contract-driven handler config loading (+4 unions)
+#                     ModelHandlerContract transport config fields and lifecycle types
+INFRA_MAX_UNIONS = 105
 
 # Maximum allowed architecture violations in infrastructure code.
 # Set to 0 (strict enforcement) to ensure one-model-per-file principle is always followed.
@@ -747,13 +753,14 @@ def validate_infra_contract_deep(
         return result
 
     # If result is a different type, wrap it in ModelContractValidationResult
-    # Default to passed=False for unknown result types to avoid silently masking failures
-    # Check 'passed' first, then 'is_valid' as fallback (some validators use is_valid)
+    # Default to is_valid=False for unknown result types to avoid silently masking failures
+    # Check 'is_valid' first, then 'passed' as fallback (some validators use passed)
     return ModelContractValidationResult(
-        passed=getattr(result, "passed", getattr(result, "is_valid", False)),
+        is_valid=getattr(result, "is_valid", getattr(result, "passed", False)),
         score=getattr(result, "score", 0.0),
-        errors=getattr(result, "errors", []),
+        violations=getattr(result, "violations", getattr(result, "errors", [])),
         warnings=getattr(result, "warnings", []),
+        interface_version=ModelSemVer(major=1, minor=0, patch=0),
     )
 
 
@@ -1318,29 +1325,33 @@ def validate_infra_union_usage(
     # Note: ModelValidationMetadata uses extra="allow", so extension fields
     # are accepted as int values.
     # See docstring "Metadata Extension Fields" section for field documentation.
+    #
+    # Extension fields are passed via model_construct() to satisfy type checker
+    # while preserving runtime behavior with extra="allow".
+    metadata_fields: dict[str, object] = {
+        # Standard ModelValidationMetadata fields (formally defined)
+        "validation_type": "union_usage",
+        "files_processed": files_processed,
+        "violations_found": len(filtered_issues),
+        "total_unions": total_count,  # Base field: all unions found
+        "max_unions": max_unions,  # Base field: configured threshold
+        "strict_mode": strict,  # Base field: whether strict mode enabled
+        # Extension fields (via extra="allow", typed as int)
+        # These provide transparency into the exclusion logic:
+        "non_optional_unions": threshold_count,  # What threshold actually checks
+        "optional_unions_excluded": optional_count,  # X | None patterns
+        "isinstance_unions_excluded": isinstance_count,  # isinstance(x, A | B) patterns
+    }
     return ModelValidationResult(
         is_valid=is_valid,
         errors=filtered_issues,
-        metadata=ModelValidationMetadata(
-            # Standard ModelValidationMetadata fields (formally defined)
-            validation_type="union_usage",
-            files_processed=files_processed,
-            violations_found=len(filtered_issues),
-            total_unions=total_count,  # Base field: all unions found
-            max_unions=max_unions,  # Base field: configured threshold
-            strict_mode=strict,  # Base field: whether strict mode enabled
-            # Extension fields (via extra="allow", typed as int)
-            # These provide transparency into the exclusion logic:
-            non_optional_unions=threshold_count,  # What threshold actually checks
-            optional_unions_excluded=optional_count,  # X | None patterns
-            isinstance_unions_excluded=isinstance_count,  # isinstance(x, A | B) patterns
-        ),
+        metadata=ModelValidationMetadata.model_construct(**metadata_fields),  # type: ignore[arg-type]
     )
 
 
 def validate_infra_circular_imports(
     directory: PathInput = INFRA_SRC_PATH,
-) -> ModelModuleImportResult:
+) -> ModelImportValidationResult:
     """
     Check for circular imports in infrastructure code.
 
@@ -1351,7 +1362,7 @@ def validate_infra_circular_imports(
         directory: Directory to check. Defaults to infrastructure source.
 
     Returns:
-        ModelModuleImportResult with detailed import validation results.
+        ModelImportValidationResult with detailed import validation results.
         Use result.has_circular_imports to check for issues.
     """
     validator = CircularImportValidator(source_path=Path(directory))
@@ -1361,7 +1372,7 @@ def validate_infra_circular_imports(
 def validate_infra_all(
     directory: PathInput = INFRA_SRC_PATH,
     nodes_directory: PathInput = INFRA_NODES_PATH,
-) -> dict[str, ValidationResult | ModelModuleImportResult]:
+) -> dict[str, ValidationResult | ModelImportValidationResult]:
     """
     Run all validations on infrastructure code.
 
@@ -1379,7 +1390,7 @@ def validate_infra_all(
     Returns:
         Dictionary mapping validator name to result.
     """
-    results: dict[str, ValidationResult | ModelModuleImportResult] = {}
+    results: dict[str, ValidationResult | ModelImportValidationResult] = {}
 
     # HIGH priority validators
     results["architecture"] = validate_infra_architecture(directory)
@@ -1394,7 +1405,7 @@ def validate_infra_all(
 
 
 def get_validation_summary(
-    results: dict[str, ValidationResult | ModelModuleImportResult],
+    results: dict[str, ValidationResult | ModelImportValidationResult],
 ) -> dict[str, int | list[str]]:
     """
     Generate a summary of validation results.