omnibase_infra 0.2.1__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_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"]