omnibase_infra 0.2.6__py3-none-any.whl

omnibase_infra/runtime/models/model_secret_resolver_metrics.py

@@ -0,0 +1,111 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Model for secret resolver metrics.
+
+.. versionadded:: 0.8.0
+    Initial implementation for OMN-1374.
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class ModelSecretResolverMetrics(BaseModel):
+    """Resolution metrics for SecretResolver observability.
+
+    Provides aggregated metrics for monitoring secret resolution performance
+    and health across different source types (env, file, vault, cache).
+
+    Attributes:
+        success_counts: Count of successful resolutions by source type.
+        failure_counts: Count of failed resolutions by source type.
+        latency_samples: Number of latency samples collected.
+        avg_latency_ms: Average resolution latency in milliseconds.
+        cache_hits: Total number of cache hits.
+        cache_misses: Total number of cache misses.
+
+    Example:
+        >>> metrics = ModelSecretResolverMetrics(
+        ...     success_counts={"env": 5, "vault": 3},
+        ...     failure_counts={"vault": 1},
+        ...     latency_samples=9,
+        ...     avg_latency_ms=12.5,
+        ...     cache_hits=100,
+        ...     cache_misses=10,
+        ... )
+        >>> metrics.success_counts["env"]
+        5
+    """
+
+    model_config = ConfigDict(
+        strict=True,
+        frozen=True,
+        extra="forbid",
+        from_attributes=True,
+    )
+
+    success_counts: dict[str, int] = Field(
+        default_factory=dict,
+        description="Count of successful resolutions by source type (e.g., 'env', 'vault', 'file').",
+    )
+    failure_counts: dict[str, int] = Field(
+        default_factory=dict,
+        description="Count of failed resolutions by source type.",
+    )
+    latency_samples: int = Field(
+        default=0,
+        ge=0,
+        description="Number of latency samples collected.",
+    )
+    avg_latency_ms: float = Field(
+        default=0.0,
+        ge=0.0,
+        description="Average resolution latency in milliseconds.",
+    )
+    cache_hits: int = Field(
+        default=0,
+        ge=0,
+        description="Total number of cache hits.",
+    )
+    cache_misses: int = Field(
+        default=0,
+        ge=0,
+        description="Total number of cache misses.",
+    )
+
+    @property
+    def cache_hit_rate(self) -> float:
+        """Calculate cache hit rate.
+
+        Returns:
+            Hit rate as a float between 0.0 and 1.0.
+            Returns 0.0 if no hits or misses have occurred.
+
+        Example:
+            >>> metrics = ModelSecretResolverMetrics(cache_hits=80, cache_misses=20)
+            >>> metrics.cache_hit_rate
+            0.8
+        """
+        total = self.cache_hits + self.cache_misses
+        return self.cache_hits / total if total > 0 else 0.0
+
+    @property
+    def total_resolutions(self) -> int:
+        """Calculate total number of resolutions attempted.
+
+        Returns:
+            Sum of all success and failure counts across all source types.
+
+        Example:
+            >>> metrics = ModelSecretResolverMetrics(
+            ...     success_counts={"env": 5, "vault": 3},
+            ...     failure_counts={"vault": 1},
+            ... )
+            >>> metrics.total_resolutions
+            9
+        """
+        return sum(self.success_counts.values()) + sum(self.failure_counts.values())
+
+
+__all__: list[str] = ["ModelSecretResolverMetrics"]

omnibase_infra/runtime/models/model_secret_source_info.py

@@ -0,0 +1,72 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Model for secret source information (introspection).
+
+.. versionadded:: 0.8.0
+    Initial implementation for OMN-764.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from omnibase_infra.runtime.models.model_secret_source_spec import SecretSourceType
+
+
+class ModelSecretSourceInfo(BaseModel):
+    """Non-sensitive source information for introspection.
+
+    Provides metadata about a secret's source without exposing the
+    actual secret value. Used for debugging and observability.
+
+    Attributes:
+        logical_name: The logical name of the secret.
+        source_type: The source type from which the secret is resolved.
+        source_path_masked: Masked version of the source path for logging.
+        is_cached: Whether the secret is currently cached.
+        expires_at: Cache expiration time if cached, None otherwise.
+
+    Example:
+        >>> info = ModelSecretSourceInfo(
+        ...     logical_name="database.password",
+        ...     source_type="vault",
+        ...     source_path_masked="vault:secret/data/***",
+        ...     is_cached=True,
+        ...     expires_at=datetime.utcnow(),
+        ... )
+    """
+
+    model_config = ConfigDict(
+        strict=True,
+        frozen=True,
+        extra="forbid",
+        from_attributes=True,
+    )
+
+    logical_name: str = Field(
+        ...,
+        min_length=1,
+        description="The logical name of the secret.",
+    )
+    source_type: SecretSourceType = Field(
+        ...,
+        description="The source type from which the secret is resolved.",
+    )
+    source_path_masked: str = Field(
+        ...,
+        description="Masked source path safe for logging "
+        "(e.g., 'env:POSTGRES_***' or 'vault:secret/data/***').",
+    )
+    is_cached: bool = Field(
+        ...,
+        description="Whether the secret is currently in the cache.",
+    )
+    expires_at: datetime | None = Field(
+        default=None,
+        description="Cache expiration timestamp if cached, None if not cached.",
+    )
+
+
+__all__: list[str] = ["ModelSecretSourceInfo"]

omnibase_infra/runtime/models/model_secret_source_spec.py

@@ -0,0 +1,66 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Model for secret source specification.
+
+.. versionadded:: 0.8.0
+    Initial implementation for OMN-764.
+"""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+# Canonical type alias for secret source types.
+# Reuse this type across all secret-related models for consistency.
+SecretSourceType = Literal["env", "vault", "file"]
+
+
+class ModelSecretSourceSpec(BaseModel):
+    """Source specification for a single secret.
+
+    Defines where and how to retrieve a secret value from a specific source.
+
+    Attributes:
+        source_type: The type of secret source (env, vault, or file).
+        source_path: The path or key to the secret within the source.
+
+    Examples:
+        Environment variable::
+
+            ModelSecretSourceSpec(source_type="env", source_path="POSTGRES_PASSWORD")
+
+        Vault secret::
+
+            ModelSecretSourceSpec(
+                source_type="vault",
+                source_path="secret/data/database/postgres#password"
+            )
+
+        File-based secret::
+
+            ModelSecretSourceSpec(source_type="file", source_path="/run/secrets/db_pass")
+    """
+
+    model_config = ConfigDict(
+        strict=True,
+        frozen=True,
+        extra="forbid",
+        from_attributes=True,
+    )
+
+    source_type: SecretSourceType = Field(
+        ...,
+        description="Type of secret source: 'env' for environment variables, "
+        "'vault' for HashiCorp Vault, 'file' for file-based secrets.",
+    )
+    source_path: str = Field(
+        ...,
+        min_length=1,
+        description="Path or key to the secret. Format depends on source_type: "
+        "env=VAR_NAME, vault=path/to/secret#key, file=/path/to/file.",
+    )
+
+
+__all__: list[str] = ["ModelSecretSourceSpec", "SecretSourceType"]

omnibase_infra/runtime/models/model_security_config.py

@@ -0,0 +1,109 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Security Configuration Model for Runtime Handler Loading.
+
+This module provides the Pydantic model for configuring trusted handler namespaces.
+The model allows operators to extend the trusted namespace list via configuration
+file while maintaining secure defaults.
+
+Security Model:
+    - Default: Only omnibase_core. and omnibase_infra. are trusted
+    - Third-party: Requires allow_third_party_handlers=True AND
+      explicit listing in allowed_handler_namespaces
+    - Config file is auditable/reviewable (unlike env vars)
+
+Example:
+    >>> from omnibase_infra.runtime.models import ModelSecurityConfig
+    >>> config = ModelSecurityConfig()  # Secure defaults
+    >>> config.get_effective_namespaces()
+    ('omnibase_core.', 'omnibase_infra.')
+
+    >>> # Enable third-party handlers
+    >>> config = ModelSecurityConfig(
+    ...     allow_third_party_handlers=True,
+    ...     allowed_handler_namespaces=(
+    ...         "omnibase_core.",
+    ...         "omnibase_infra.",
+    ...         "mycompany.handlers.",
+    ...     ),
+    ... )
+    >>> config.get_effective_namespaces()
+    ('omnibase_core.', 'omnibase_infra.', 'mycompany.handlers.')
+
+.. versionadded:: 0.2.8
+    Created as part of OMN-1519 security hardening.
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from omnibase_infra.runtime.constants_security import TRUSTED_HANDLER_NAMESPACE_PREFIXES
+
+
+class ModelSecurityConfig(BaseModel):
+    """Security configuration for runtime handler loading.
+
+    This model allows operators to extend the trusted namespace list
+    via configuration file. The defaults are secure - third-party
+    namespaces require explicit opt-in.
+
+    Security Model:
+        - Default: Only omnibase_core. and omnibase_infra. are trusted
+        - Third-party: Requires allow_third_party_handlers=True AND
+          explicit listing in allowed_handler_namespaces
+        - Config file is auditable/reviewable (unlike env vars)
+
+    Attributes:
+        allow_third_party_handlers: Enable loading handlers from third-party
+            namespaces. When False, only TRUSTED_HANDLER_NAMESPACE_PREFIXES
+            are allowed regardless of allowed_handler_namespaces setting.
+        allowed_handler_namespaces: Allowed namespace prefixes for handler
+            loading. Only effective when allow_third_party_handlers=True.
+    """
+
+    model_config = ConfigDict(
+        strict=True,
+        frozen=True,
+        extra="forbid",
+        from_attributes=True,
+    )
+
+    allow_third_party_handlers: bool = Field(
+        default=False,
+        description="Enable loading handlers from third-party namespaces. "
+        "When False, only TRUSTED_HANDLER_NAMESPACE_PREFIXES are allowed.",
+    )
+
+    allowed_handler_namespaces: tuple[str, ...] = Field(
+        default=TRUSTED_HANDLER_NAMESPACE_PREFIXES,
+        description="Allowed namespace prefixes for handler loading. "
+        "Only effective when allow_third_party_handlers=True.",
+    )
+
+    def get_effective_namespaces(self) -> tuple[str, ...]:
+        """Get the effective namespace allowlist based on configuration.
+
+        Returns:
+            Tuple of allowed namespace prefixes. If third-party handlers
+            are disabled, returns only the trusted defaults regardless
+            of the allowed_handler_namespaces setting.
+
+        Example:
+            >>> config = ModelSecurityConfig()
+            >>> config.get_effective_namespaces()
+            ('omnibase_core.', 'omnibase_infra.')
+
+            >>> config = ModelSecurityConfig(
+            ...     allow_third_party_handlers=True,
+            ...     allowed_handler_namespaces=("custom.namespace.",),
+            ... )
+            >>> config.get_effective_namespaces()
+            ('custom.namespace.',)
+        """
+        if not self.allow_third_party_handlers:
+            return TRUSTED_HANDLER_NAMESPACE_PREFIXES
+        return self.allowed_handler_namespaces
+
+
+__all__: list[str] = ["ModelSecurityConfig"]

omnibase_infra/runtime/models/model_shutdown_batch_result.py

@@ -0,0 +1,75 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Shutdown Batch Result Model.
+
+This module provides the Pydantic model for batch shutdown operation results.
+
+Migration Notes:
+    The failed_components field was migrated from list[tuple[str, str]] to
+    list[ModelFailedComponent] as part of OMN-1007 tuple-to-model conversion.
+    This provides better type safety and semantic clarity for failure tracking.
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from omnibase_infra.runtime.models.model_failed_component import ModelFailedComponent
+
+
+class ModelShutdownBatchResult(BaseModel):
+    """Result of a batch shutdown operation.
+
+    Encapsulates the result of shutting down components by priority,
+    tracking which components succeeded and which failed with their error messages.
+
+    Attributes:
+        succeeded_components: List of component types that shutdown successfully.
+        failed_components: List of ModelFailedComponent instances for failures.
+
+    Example:
+        >>> from omnibase_infra.runtime.models import (
+        ...     ModelShutdownBatchResult,
+        ...     ModelFailedComponent,
+        ... )
+        >>> result = ModelShutdownBatchResult(
+        ...     succeeded_components=["ConsulAdapter", "VaultAdapter"],
+        ...     failed_components=[
+        ...         ModelFailedComponent(
+        ...             component_name="EventBusKafka",
+        ...             error_message="Connection timeout"
+        ...         )
+        ...     ]
+        ... )
+    """
+
+    model_config = ConfigDict(
+        strict=True,
+        frozen=True,
+        extra="forbid",
+        from_attributes=True,
+    )
+
+    succeeded_components: list[str] = Field(
+        default_factory=list,
+        description="Component types that shutdown successfully",
+    )
+    failed_components: list[ModelFailedComponent] = Field(
+        default_factory=list,
+        description="Components that failed during shutdown with error details",
+    )
+
+    def __str__(self) -> str:
+        """Return a human-readable string representation for debugging.
+
+        Returns:
+            String format showing succeeded and failed counts.
+        """
+        return (
+            f"ModelShutdownBatchResult("
+            f"succeeded={len(self.succeeded_components)}, "
+            f"failed={len(self.failed_components)})"
+        )
+
+
+__all__: list[str] = ["ModelShutdownBatchResult"]

omnibase_infra/runtime/models/model_shutdown_config.py

@@ -0,0 +1,94 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Shutdown Configuration Model.
+
+This module provides the Pydantic model for shutdown configuration.
+"""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+from pydantic import BaseModel, BeforeValidator, ConfigDict, Field
+
+
+def _coerce_grace_period(v: object) -> int:
+    """Coerce float values to int before strict validation.
+
+    This pre-validator handles the case where a float value like 30.0
+    is passed. With strict=True, Pydantic would reject floats, but
+    this validator ensures whole-number floats are accepted.
+
+    Note:
+        Boolean values are explicitly rejected even though bool is a
+        subclass of int in Python. This maintains semantic correctness
+        and consistency with other integer configuration fields that
+        use strict=True without pre-validators.
+
+    Args:
+        v: The input value (may be int, float, or other).
+
+    Returns:
+        Integer value if input is a valid whole number.
+
+    Raises:
+        ValueError: If float has a fractional part.
+        TypeError: If input is not numeric or is a boolean.
+    """
+    # Explicitly reject booleans first - bool is a subclass of int in Python,
+    # so isinstance(True, int) returns True. We must check bool before int
+    # to maintain strict type semantics and prevent unexpected coercion.
+    if isinstance(v, bool):
+        raise TypeError("grace_period_seconds must be an integer, got bool")
+    if isinstance(v, float):
+        if v != int(v):
+            raise ValueError(f"grace_period_seconds must be a whole number, got {v}")
+        return int(v)
+    if isinstance(v, int):
+        return v
+    raise TypeError(f"grace_period_seconds must be an integer, got {type(v).__name__}")
+
+
+# Type alias for grace period with pre-validation coercion
+_GracePeriodSeconds = Annotated[int, BeforeValidator(_coerce_grace_period)]
+
+
+class ModelShutdownConfig(BaseModel):
+    """Shutdown configuration model.
+
+    Defines graceful shutdown parameters.
+
+    Attributes:
+        grace_period_seconds: Time in seconds to wait for graceful shutdown.
+            Must be >= 0. A value of 0 means immediate shutdown with no grace
+            period (use with caution as in-flight operations may be interrupted).
+
+    Edge Cases:
+        - 0: Immediate shutdown, no waiting for in-flight operations
+        - Values > 3600: Rejected by Pydantic validation (le=3600 constraint);
+          consider using reasonable timeouts (30-120 seconds recommended)
+        - Negative values: Rejected by Pydantic validation (ge=0 constraint)
+
+    Production Recommendation:
+        Set grace_period_seconds between 30-120 seconds for production deployments
+        to allow sufficient time for in-flight operations while preventing excessive
+        delays during shutdown sequences.
+    """
+
+    model_config = ConfigDict(
+        strict=True,
+        frozen=True,
+        extra="forbid",
+        from_attributes=True,  # Support pytest-xdist compatibility
+    )
+
+    grace_period_seconds: _GracePeriodSeconds = Field(
+        default=30,
+        ge=0,
+        le=3600,  # Max 1 hour to prevent accidental excessive delays
+        strict=False,  # Override model-level strict=True to allow BeforeValidator coercion
+        description="Time in seconds to wait for graceful shutdown (0-3600)",
+    )
+
+
+__all__: list[str] = ["ModelShutdownConfig"]

omnibase_infra/runtime/models/model_transition_notification_outbox_config.py

@@ -0,0 +1,112 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Configuration model for TransitionNotificationOutbox.
+
+This module provides a Pydantic model for configuring the TransitionNotificationOutbox,
+which implements the outbox pattern for guaranteed notification delivery of state
+transition events.
+
+Related:
+    - TransitionNotificationOutbox: The outbox implementation
+    - ModelTransitionNotificationOutboxMetrics: Metrics model for observability
+    - docs/patterns/retry_backoff_compensation_strategy.md: Outbox pattern docs
+
+.. versionadded:: 0.8.0
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class ModelTransitionNotificationOutboxConfig(BaseModel):
+    """Configuration for TransitionNotificationOutbox.
+
+    This model encapsulates all configuration options for the outbox pattern
+    implementation that ensures at-least-once delivery semantics for state
+    transition notifications.
+
+    The outbox stores notifications in the same database transaction as projections,
+    then processes them asynchronously via a background processor.
+
+    Attributes:
+        outbox_table: PostgreSQL table name for the outbox.
+        batch_size: Maximum notifications to process per batch.
+        poll_interval_seconds: Seconds between polls when idle.
+        query_timeout_seconds: Timeout for database queries.
+        strict_transaction_mode: If True, raises error when store() called
+            outside a transaction context.
+        shutdown_timeout_seconds: Timeout for graceful shutdown.
+        max_retries: Maximum retry attempts before moving to DLQ. None disables DLQ.
+        dlq_topic: Topic name for DLQ (for metrics/logging purposes).
+
+    Example:
+        >>> config = ModelTransitionNotificationOutboxConfig(
+        ...     outbox_table="state_transition_outbox",
+        ...     batch_size=50,
+        ...     poll_interval_seconds=0.5,
+        ...     max_retries=3,
+        ...     dlq_topic="notifications-dlq",
+        ... )
+        >>> outbox = TransitionNotificationOutbox(
+        ...     pool=pool,
+        ...     publisher=publisher,
+        ...     **config.model_dump(),  # Unpack as kwargs
+        ... )
+
+    Related:
+        - TransitionNotificationOutbox: Uses this configuration
+        - ModelTransitionNotificationOutboxMetrics: Runtime metrics
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+    outbox_table: str = Field(
+        default="transition_notification_outbox",
+        min_length=1,
+        max_length=63,  # PostgreSQL identifier limit
+        description="PostgreSQL table name for the outbox",
+    )
+    batch_size: int = Field(
+        default=100,
+        ge=1,
+        le=1000,
+        description="Maximum notifications to process per batch",
+    )
+    poll_interval_seconds: float = Field(
+        default=1.0,
+        ge=0.1,
+        le=60.0,
+        description="Seconds between background processor polls when idle",
+    )
+    query_timeout_seconds: float = Field(
+        default=30.0,
+        ge=1.0,
+        le=300.0,
+        description="Timeout in seconds for database queries",
+    )
+    strict_transaction_mode: bool = Field(
+        default=True,
+        description="If True, raises error when store() called outside transaction",
+    )
+    shutdown_timeout_seconds: float = Field(
+        default=10.0,
+        ge=1.0,
+        le=300.0,
+        description="Timeout in seconds for graceful shutdown during stop()",
+    )
+    max_retries: int | None = Field(
+        default=None,
+        ge=1,
+        le=100,
+        description="Maximum retry attempts before moving to DLQ. None disables DLQ",
+    )
+    dlq_topic: str | None = Field(
+        default=None,
+        description="Topic name for DLQ (for metrics/logging purposes)",
+    )
+
+
+__all__: list[str] = [
+    "ModelTransitionNotificationOutboxConfig",
+]