omnibase_infra 0.2.1__py3-none-any.whl

omnibase_infra/__init__.py

@@ -0,0 +1,101 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""ONEX Infrastructure Layer - Service integration and policy runtime.
+
+This package provides infrastructure adapters, error handling, and the RegistryPolicy
+for ONEX services. The infrastructure layer is responsible for external service
+integration, transport-aware error handling, and pure decision policy management.
+
+Core Components
+---------------
+
+**RegistryPolicy** - SINGLE SOURCE OF TRUTH for policy plugin registration:
+    - Thread-safe registration of policy plugins by (policy_id, policy_type, version)
+    - Enforces synchronous-by-default execution (async must be explicitly flagged)
+    - Supports orchestrator and reducer policy types
+    - Provides version resolution with semantic versioning
+    - See: omnibase_infra.runtime.registry_policy
+
+**Service Adapters** - External service integration:
+    - PostgreSQL: Database operations
+    - Kafka: Event streaming
+    - Consul: Service discovery
+    - Vault: Secret management
+    - Valkey/Redis: Caching
+    - HTTP/gRPC: API communication
+
+**Error Handling** - Transport-aware error context:
+    - ModelInfraErrorContext: Structured error metadata
+    - InfraConnectionError, InfraTimeoutError, InfraAuthenticationError
+    - PolicyRegistryError: Policy registration and resolution failures
+    - Automatic error code selection based on transport type
+
+**Runtime Infrastructure**:
+    - RuntimeHostProcess: ONEX node execution host
+    - Kernel: Contract-driven bootstrap entrypoint
+    - RegistryProtocolBinding: Handler registration
+    - RegistryEventBusBinding: Event bus registration
+
+Architecture Principles
+----------------------
+- **Contract-Driven**: All services follow ONEX contract patterns
+- **Protocol-Based**: Duck typing through protocols, no isinstance checks
+- **Strong Typing**: No Any types, Pydantic models for all data structures
+- **Thread-Safe**: Registry operations protected by locks
+- **Pure Policies**: Policy plugins are pure decision logic (no I/O, no side effects)
+
+Example Usage
+-------------
+    >>> from omnibase_core.container import ModelONEXContainer
+    >>> from omnibase_infra.runtime import RegistryPolicy
+    >>> from omnibase_infra.runtime.util_container_wiring import wire_infrastructure_services
+    >>> from omnibase_infra.enums import EnumPolicyType
+    >>>
+    >>> # Container-based DI (preferred)
+    >>> container = ModelONEXContainer()
+    >>> await wire_infrastructure_services(container)
+    >>> registry = await container.service_registry.resolve_service(RegistryPolicy)
+    >>>
+    >>> # Register a policy
+    >>> registry.register_policy(
+    ...     policy_id="exponential_backoff",
+    ...     policy_class=ExponentialBackoffPolicy,
+    ...     policy_type=EnumPolicyType.ORCHESTRATOR,
+    ...     version="1.0.0",
+    ... )
+    >>>
+    >>> # Retrieve and use policy
+    >>> policy_cls = registry.get("exponential_backoff")
+    >>> policy = policy_cls()
+    >>> result = policy.evaluate(context)
+
+See Also
+--------
+- RegistryPolicy: omnibase_infra.runtime.registry_policy
+- Error classes: omnibase_infra.errors
+- Runtime kernel: omnibase_infra.runtime.service_kernel
+"""
+
+__version__ = "0.2.1"
+
+from . import (
+    enums,
+    models,
+    nodes,
+    utils,
+)
+
+# Public API exports - only stable, documented modules are exposed at package level.
+# Internal modules (dlq, errors, event_bus, handlers, idempotency, mixins, plugins,
+# projectors, protocols, runtime, services, shared, testing, validation) are
+# intentionally excluded from the public API. These modules should be imported
+# directly from their specific subpackage paths when needed, e.g.:
+#   from omnibase_infra.errors import InfraConnectionError
+#   from omnibase_infra.runtime import RegistryPolicy
+__all__: list[str] = [
+    "__version__",
+    "enums",
+    "models",
+    "nodes",
+    "utils",
+]

omnibase_infra/cli/__init__.py

@@ -0,0 +1 @@
+"""ONEX Infrastructure CLI."""

omnibase_infra/cli/commands.py

@@ -0,0 +1,216 @@
+"""
+ONEX Infrastructure CLI Commands.
+
+Provides CLI interface for infrastructure management and validation.
+"""
+
+import click
+from rich.console import Console
+from rich.table import Table
+
+console = Console()
+
+
+@click.group()
+def cli() -> None:
+    """ONEX Infrastructure CLI."""
+
+
+@cli.group()
+def validate() -> None:
+    """Validation commands for infrastructure code."""
+
+
+@validate.command("architecture")
+@click.argument("directory", default="src/omnibase_infra/")
+@click.option(
+    "--max-violations",
+    default=None,
+    help="Maximum allowed violations (default: INFRA_MAX_VIOLATIONS)",
+)
+def validate_architecture_cmd(directory: str, max_violations: int | None) -> None:
+    """Validate architecture (one-model-per-file)."""
+    from omnibase_infra.validation.infra_validators import (
+        INFRA_MAX_VIOLATIONS,
+        validate_infra_architecture,
+    )
+
+    console.print(f"[bold blue]Validating architecture in {directory}...[/bold blue]")
+    # Use INFRA_MAX_VIOLATIONS constant if no override provided
+    effective_max_violations = (
+        max_violations if max_violations is not None else INFRA_MAX_VIOLATIONS
+    )
+    result = validate_infra_architecture(directory, effective_max_violations)
+    _print_result("Architecture", result)
+    raise SystemExit(0 if result.is_valid else 1)
+
+
+@validate.command("contracts")
+@click.argument("directory", default="src/omnibase_infra/nodes/")
+def validate_contracts_cmd(directory: str) -> None:
+    """Validate YAML contracts."""
+    from omnibase_infra.validation.infra_validators import validate_infra_contracts
+
+    console.print(f"[bold blue]Validating contracts in {directory}...[/bold blue]")
+    result = validate_infra_contracts(directory)
+    _print_result("Contracts", result)
+    raise SystemExit(0 if result.is_valid else 1)
+
+
+@validate.command("patterns")
+@click.argument("directory", default="src/omnibase_infra/")
+@click.option(
+    "--strict/--no-strict",
+    default=None,
+    help="Enable strict mode (default: INFRA_PATTERNS_STRICT)",
+)
+def validate_patterns_cmd(directory: str, strict: bool | None) -> None:
+    """Validate code patterns and naming conventions."""
+    from omnibase_infra.validation.infra_validators import (
+        INFRA_PATTERNS_STRICT,
+        validate_infra_patterns,
+    )
+
+    console.print(f"[bold blue]Validating patterns in {directory}...[/bold blue]")
+    # Use INFRA_PATTERNS_STRICT constant if no override provided
+    effective_strict = strict if strict is not None else INFRA_PATTERNS_STRICT
+    result = validate_infra_patterns(directory, effective_strict)
+    _print_result("Patterns", result)
+    raise SystemExit(0 if result.is_valid else 1)
+
+
+@validate.command("unions")
+@click.argument("directory", default="src/omnibase_infra/")
+@click.option(
+    "--max-unions",
+    default=None,
+    help="Maximum allowed union count (default: INFRA_MAX_UNIONS)",
+)
+@click.option(
+    "--strict/--no-strict",
+    default=None,
+    help="Enable strict mode (default: INFRA_UNIONS_STRICT)",
+)
+def validate_unions_cmd(
+    directory: str, max_unions: int | None, strict: bool | None
+) -> None:
+    """Validate Union type usage.
+
+    Counts total unions in the codebase.
+    Valid `X | None` patterns are counted but not flagged as violations.
+    """
+    from omnibase_infra.validation.infra_validators import (
+        INFRA_MAX_UNIONS,
+        INFRA_UNIONS_STRICT,
+        validate_infra_union_usage,
+    )
+
+    console.print(f"[bold blue]Validating union usage in {directory}...[/bold blue]")
+    # Use constants if no override provided
+    effective_max_unions = max_unions if max_unions is not None else INFRA_MAX_UNIONS
+    effective_strict = strict if strict is not None else INFRA_UNIONS_STRICT
+    result = validate_infra_union_usage(
+        directory, effective_max_unions, effective_strict
+    )
+    _print_result("Union Usage", result)
+    raise SystemExit(0 if result.is_valid else 1)
+
+
+@validate.command("imports")
+@click.argument("directory", default="src/omnibase_infra/")
+def validate_imports_cmd(directory: str) -> None:
+    """Check for circular imports."""
+    from omnibase_infra.validation.infra_validators import (
+        validate_infra_circular_imports,
+    )
+
+    console.print(f"[bold blue]Checking circular imports in {directory}...[/bold blue]")
+    result = validate_infra_circular_imports(directory)
+
+    # ModelModuleImportResult uses has_circular_imports property
+    if not result.has_circular_imports:
+        console.print("[bold green]Circular Imports: PASS[/bold green]")
+        raise SystemExit(0)
+    console.print("[bold red]Circular Imports: FAIL[/bold red]")
+    if hasattr(result, "cycles") and result.cycles:
+        for cycle in result.cycles:
+            console.print(f"  [red]Cycle: {cycle}[/red]")
+    if hasattr(result, "errors") and result.errors:
+        for error in result.errors:
+            console.print(f"  [red]{error}[/red]")
+    raise SystemExit(1)
+
+
+@validate.command("all")
+@click.argument("directory", default="src/omnibase_infra/")
+@click.option(
+    "--nodes-dir", default="src/omnibase_infra/nodes/", help="Nodes directory"
+)
+def validate_all_cmd(directory: str, nodes_dir: str) -> None:
+    """Run all validations."""
+    from omnibase_infra.validation.infra_validators import (
+        get_validation_summary,
+        validate_infra_all,
+    )
+
+    console.print(f"[bold blue]Running all validations on {directory}...[/bold blue]\n")
+    results = validate_infra_all(directory, nodes_dir)
+    summary = get_validation_summary(results)
+
+    # Create summary table
+    table = Table(title="Validation Results")
+    table.add_column("Validator", style="cyan")
+    table.add_column("Status", style="bold")
+    table.add_column("Errors", style="red")
+
+    for name, result in results.items():
+        is_valid = _is_result_valid(result)
+        error_count = _get_error_count(result)
+        status = "[green]PASS[/green]" if is_valid else "[red]FAIL[/red]"
+        table.add_row(name.replace("_", " ").title(), status, str(error_count))
+
+    console.print(table)
+
+    # Print summary
+    passed = summary.get("passed", 0)
+    total = summary.get("total_validators", 0)
+    console.print(f"\n[bold]Summary: {passed}/{total} passed[/bold]")
+
+    all_valid = summary.get("failed", 0) == 0
+    raise SystemExit(0 if all_valid else 1)
+
+
+def _is_result_valid(result: object) -> bool:
+    """Check if a validation result is valid."""
+    if hasattr(result, "has_circular_imports"):
+        return not bool(result.has_circular_imports)
+    if hasattr(result, "is_valid"):
+        return bool(result.is_valid)
+    return False
+
+
+def _get_error_count(result: object) -> int:
+    """Get the error count from a validation result."""
+    if hasattr(result, "has_circular_imports"):
+        if hasattr(result, "cycles"):
+            return len(result.cycles)
+        return 1 if result.has_circular_imports else 0
+    if hasattr(result, "errors"):
+        return len(result.errors)
+    return 0
+
+
+def _print_result(name: str, result: object) -> None:
+    """Print validation result with rich formatting."""
+    if hasattr(result, "is_valid"):
+        if result.is_valid:
+            console.print(f"[bold green]{name}: PASS[/bold green]")
+        else:
+            console.print(f"[bold red]{name}: FAIL[/bold red]")
+            if hasattr(result, "errors") and result.errors:
+                for error in result.errors:
+                    console.print(f"  [red]{error}[/red]")
+
+
+if __name__ == "__main__":
+    cli()

omnibase_infra/contracts/handlers/filesystem/handler_contract.yaml

@@ -0,0 +1,261 @@
+# Handler ID follows convention: {node_type}.{domain}.handler
+handler_id: effect.filesystem.handler
+name: FileSystem Handler
+version: "1.0.0"
+description: >
+  Effect handler for filesystem operations including read, write, list, delete, and directory management.
+
+descriptor:
+  handler_kind: effect
+  purity: side_effecting
+  # Idempotent: false because write operations may append (non-idempotent).
+  # Individual operations (write w/ overwrite, mkdir w/ exist_ok) can be
+  # idempotent, but the handler as a whole supports non-idempotent semantics.
+  idempotent: false
+  # TIMEOUT CONFIGURATION (30 seconds)
+  # ---------------------------------
+  # While typical local filesystem I/O completes in milliseconds, 30 seconds
+  # accommodates these legitimate scenarios:
+  #
+  # 1. Network-mounted filesystems (NFS, CIFS, SSHFS) with latency up to seconds
+  # 2. Large file operations: max_file_size_bytes (10MB) on slow storage
+  # 3. Container volume mounts with additional abstraction overhead
+  # 4. High disk I/O contention in shared infrastructure environments
+  # 5. Spinning disk storage (HDDs) vs SSDs in mixed deployments
+  #
+  # OVERRIDE GUIDANCE:
+  # - Reduce to 5000ms for latency-sensitive, local-only deployments
+  # - Increase to 60000ms for known slow NAS/SAN storage
+  # - Consider per-operation timeouts in handler implementation for fine-grained control
+  #
+  # CIRCUIT BREAKER RELATIONSHIP:
+  # Circuit breaker timeout (60000ms) is intentionally 2x handler timeout to ensure:
+  # - Individual operations timeout before circuit evaluation
+  # - Circuit tracks failure patterns, not just slow operations
+  # - Proper failure sequence: timeout → retry exhaustion → circuit threshold
+  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 (30s). This ensures the circuit
+    # stays open long enough for transient issues to resolve while allowing
+    # recovery attempts. See timeout_ms comment above for relationship details.
+    timeout_ms: 60000
+  # Serialized: Prevents race conditions for write operations to same file.
+  # Read-only operations could use concurrent policy, but handler scope
+  # includes writes so we use serialized for safety.
+  concurrency_policy: serialized
+  isolation_policy: none
+  observability_level: standard
+capability_outputs:
+  - filesystem.read
+  - filesystem.write
+  - filesystem.list
+  - filesystem.delete
+  - filesystem.mkdir
+# NOTE: Models defined in OMN-1160 (FileSystemHandler Contract)
+input_model: omnibase_infra.handlers.filesystem.ModelFileSystemRequest
+output_model: omnibase_infra.handlers.filesystem.ModelFileSystemResult
+supports_lifecycle: true
+supports_health_check: true
+supports_provisioning: false
+tags:
+  - filesystem
+  - effect
+  - infrastructure
+metadata:
+  author: OmniNode Team
+  ticket: OMN-1160
+  security:
+    # =========================================================================
+    # SECURITY CONFIGURATION
+    # =========================================================================
+    # This section defines comprehensive security constraints for filesystem
+    # operations. Implementers MUST enforce all constraints documented here.
+    # =========================================================================
+
+    # -------------------------------------------------------------------------
+    # PATH RESTRICTIONS
+    # -------------------------------------------------------------------------
+    # SECURITY: Handler implementation MUST enforce these constraints:
+    # - Validate all paths are within allowed_paths before operations
+    # - Use Path.resolve() to canonicalize paths and prevent ../ attacks
+    # - Check symlinks don't point outside allowed paths (TOCTOU mitigation)
+    # - Reject absolute paths that escape the workspace
+    allowed_paths:
+      - "${WORKSPACE_ROOT}"
+    # -------------------------------------------------------------------------
+    # FILE SIZE LIMITS
+    # -------------------------------------------------------------------------
+    # Maximum file size for read/write operations (10 MB default).
+    # Prevents memory exhaustion attacks and limits blast radius.
+    max_file_size_bytes: 10485760
+    # -------------------------------------------------------------------------
+    # CONFIGURATION REQUIREMENTS
+    # -------------------------------------------------------------------------
+    # Documents required environment variables and initialization behavior.
+    configuration_requirements:
+      environment_variables:
+        WORKSPACE_ROOT:
+          required: true
+          description: >
+            Base directory for all filesystem operations. All paths are validated to be within this directory tree.
+
+          # CRITICAL: Handler MUST fail initialization if not set.
+          # This prevents accidental access to system files when misconfigured.
+          # Do NOT fall back to "/" or "." as this would expose the entire
+          # filesystem or current working directory.
+          missing_behavior: fail_initialization
+          validation:
+            - must_be_absolute_path
+            - must_exist
+            - must_be_directory
+      # Handler initialization MUST verify all required env vars before
+      # accepting any requests. Fail-fast prevents security misconfigurations.
+      initialization_policy: fail_fast_on_missing_config
+    # -------------------------------------------------------------------------
+    # FILE PERMISSION HANDLING
+    # -------------------------------------------------------------------------
+    # Strategy for handling file permissions during create/write operations.
+    file_permissions:
+      # Default permissions for newly created files (octal notation).
+      # 0o644 = owner read/write, group/other read-only.
+      default_file_mode: "0644"
+      # Default permissions for newly created directories.
+      # 0o755 = owner full access, group/other read/execute.
+      default_directory_mode: "0755"
+      # Whether to preserve existing permissions on overwrite.
+      # true = keep existing permissions, false = apply defaults.
+      preserve_on_overwrite: true
+      # SECURITY: Handler runs with process permissions. It cannot grant
+      # permissions beyond what the process user has. Operations that would
+      # require elevated privileges MUST fail with PermissionError.
+      # Do NOT attempt to use sudo or privilege escalation.
+      privilege_escalation: forbidden
+    # -------------------------------------------------------------------------
+    # RATE LIMITING
+    # -------------------------------------------------------------------------
+    # Rate limiting strategy for filesystem operations.
+    rate_limiting:
+      # NOTE: Rate limiting is DEFERRED to the orchestration layer.
+      # Rationale: The handler is a low-level effect that processes one
+      # request at a time (serialized concurrency). Rate limiting is more
+      # effectively implemented at:
+      # - API gateway level (request rate per client)
+      # - Orchestrator level (workflow-aware throttling)
+      # - Resource manager level (system-wide I/O limits)
+      #
+      # If handler-level rate limiting becomes necessary, implement using:
+      # - Token bucket algorithm for burst tolerance
+      # - Separate limits for read vs write operations
+      # - Correlation ID tracking to prevent single-client abuse
+      enabled: false
+      deferred_to: orchestration_layer
+      # Future implementation considerations:
+      future_considerations:
+        - per_operation_limits: "Different limits for read (high) vs write (low)"
+        - burst_allowance: "Token bucket with 10-request burst"
+        - backpressure_signal: "Return 429 with Retry-After header"
+    # -------------------------------------------------------------------------
+    # TOCTOU (Time-of-Check-Time-of-Use) MITIGATION
+    # -------------------------------------------------------------------------
+    # Strategies to mitigate race conditions between path validation and use.
+    toctou_mitigation:
+      # SECURITY: TOCTOU vulnerabilities occur when an attacker modifies the
+      # filesystem between our security check and the actual operation.
+      # Example attack: symlink is validated as safe, then replaced with a
+      # symlink to /etc/passwd before the read operation.
+      strategies:
+        # 1. Open file handles immediately after validation
+        # Use os.open() with O_NOFOLLOW to prevent symlink races, then
+        # perform operations on the file descriptor, not the path.
+        - strategy: use_file_descriptors
+          description: >
+            Open files immediately after path validation and operate on file descriptors rather than paths. This binds the operation to the specific inode, not the path.
+
+          implementation_note: >
+            Use os.open(path, os.O_RDONLY | os.O_NOFOLLOW) for reads. For writes, use O_CREAT | O_EXCL for new files to prevent symlink-based attacks.
+
+        # 2. Atomic operations where possible
+        # Use rename() for atomic file replacement, mkdir() with exist_ok=False
+        # to detect races.
+        - strategy: atomic_operations
+          description: >
+            Use atomic filesystem operations. Write to temp file then rename() for atomic replacement. Use O_EXCL flag to fail if file already exists (detects races).
+
+          implementation_note: >
+            tempfile.NamedTemporaryFile with delete=False, write content, then os.rename() to target. Rename is atomic on POSIX.
+
+        # 3. Re-validate after open
+        # After opening, verify the file descriptor points to expected location.
+        - strategy: post_open_validation
+          description: >
+            After opening a file handle, verify it still points to the expected location using os.fstat() and comparing device/inode.
+
+          implementation_note: >
+            Store (st_dev, st_ino) from os.stat() before open, compare with os.fstat(fd) after open. Mismatch indicates race.
+
+        # 4. Serialized concurrency (already configured)
+        # The serialized concurrency_policy in descriptor prevents parallel
+        # operations that could race with each other.
+        - strategy: serialized_operations
+          description: >
+            Handler uses serialized concurrency policy, preventing parallel handler invocations that could race.
+
+          note: Already configured in descriptor.concurrency_policy
+      # SECURITY: Symlink handling is critical for TOCTOU mitigation.
+      # Symlinks can be weaponized to escape allowed_paths.
+      symlink_policy:
+        # Whether to follow symlinks during path resolution.
+        # false = safer, prevents symlink-based escapes
+        # true = more flexible, but requires careful validation
+        follow_symlinks: false
+        # When follow_symlinks is true, validate that the resolved path
+        # is still within allowed_paths AFTER following all symlinks.
+        validate_resolved_path: true
+        # Maximum symlink depth to follow (prevents infinite loops).
+        max_symlink_depth: 10
+        # Reject symlinks that point outside allowed_paths.
+        reject_external_targets: true
+    # -------------------------------------------------------------------------
+    # INPUT VALIDATION
+    # -------------------------------------------------------------------------
+    # All inputs MUST be validated before use.
+    input_validation:
+      # Path validation requirements
+      path_validation:
+        - reject_null_bytes: true # Prevents null byte injection
+        - reject_control_chars: true # Prevents terminal injection
+        - max_path_length: 4096 # Prevents buffer overflow attacks
+        - max_filename_length: 255 # Filesystem limit
+        - reject_reserved_names: true # CON, PRN, etc. on Windows
+      # Content validation for write operations
+      content_validation:
+        - enforce_max_file_size: true # See max_file_size_bytes
+        - encoding_validation: optional # UTF-8 validation when applicable
+    # -------------------------------------------------------------------------
+    # AUDIT AND LOGGING
+    # -------------------------------------------------------------------------
+    # Security-relevant events that MUST be logged.
+    audit_logging:
+      # Events that MUST be logged for security audit trail
+      required_events:
+        - path_validation_failure # Attempted access outside allowed_paths
+        - symlink_escape_attempt # Symlink pointed outside allowed_paths
+        - permission_denied # OS-level permission failure
+        - file_size_exceeded # Attempted to read/write oversized file
+        - initialization_failure # Handler failed to initialize (missing env)
+      # Log level for security events
+      security_event_level: warning
+      # Include correlation_id in all logs for request tracing
+      include_correlation_id: true
+      # SECURITY: Never log file contents - only metadata
+      never_log:
+        - file_contents
+        - binary_data