omnibase_infra 0.2.1__py3-none-any.whl

omnibase_infra/handlers/models/vault/model_vault_handler_config.py

@@ -0,0 +1,148 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Vault Handler Configuration Model.
+
+This module provides the Pydantic configuration model for HashiCorp Vault
+handler initialization and operation.
+
+Security Note:
+    The token field uses SecretStr to prevent accidental logging of
+    sensitive credentials. Tokens should come from environment variables,
+    never from YAML configuration files.
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field, SecretStr, field_validator
+
+from omnibase_infra.handlers.models.vault.model_vault_retry_config import (
+    ModelVaultRetryConfig,
+)
+
+
+class ModelVaultHandlerConfig(BaseModel):
+    """Configuration for HashiCorp Vault handler.
+
+    Security Policy:
+        - The token field uses SecretStr to prevent accidental logging
+        - Tokens should be provided via environment variables, not config files
+        - Never log or expose token values in error messages
+        - Use verify_ssl=True in production environments
+
+    Attributes:
+        url: Vault server URL (required, e.g., "https://vault.example.com:8200")
+        token: Vault authentication token (SecretStr for security, optional)
+        namespace: Vault namespace for Vault Enterprise (optional)
+        timeout_seconds: Operation timeout in seconds (1.0-300.0, default 30.0)
+        verify_ssl: Whether to verify SSL certificates (default True)
+        token_renewal_threshold_seconds: Token renewal threshold in seconds (default 300.0)
+        default_token_ttl: Default token TTL in seconds when not provided by Vault (default 3600)
+        retry: Retry configuration with exponential backoff
+
+    Example:
+        >>> from pydantic import SecretStr
+        >>> config = ModelVaultHandlerConfig(
+        ...     url="https://vault.example.com:8200",
+        ...     token=SecretStr("s.1234567890abcdefghijklmnopqrstuv"),
+        ...     namespace="engineering",
+        ...     timeout_seconds=30.0,
+        ...     verify_ssl=True,
+        ... )
+        >>> # Token is protected from accidental logging
+        >>> print(config.token)
+        SecretStr('**********')
+    """
+
+    model_config = ConfigDict(
+        strict=True,
+        frozen=True,
+        extra="forbid",
+        from_attributes=True,
+    )
+
+    url: str = Field(
+        description="Vault server URL (e.g., 'https://vault.example.com:8200')",
+    )
+
+    @field_validator("url")
+    @classmethod
+    def validate_url_format(cls, v: str) -> str:
+        """Validate that URL has proper format for Vault server."""
+        if not v:
+            msg = "URL cannot be empty"
+            raise ValueError(msg)
+        # Check for valid URL scheme
+        if not v.startswith(("http://", "https://")):
+            msg = "URL must start with http:// or https://"
+            raise ValueError(msg)
+        # Basic structure validation (scheme + host at minimum)
+        parts = v.split("://", 1)
+        if len(parts) != 2 or not parts[1]:
+            msg = "URL must have format: scheme://host[:port]"
+            raise ValueError(msg)
+        return v
+
+    token: SecretStr | None = Field(
+        default=None,
+        description="Authentication token protected from logging",
+    )
+    namespace: str | None = Field(
+        default=None,
+        description="Vault namespace for multi-tenant isolation",
+    )
+    timeout_seconds: float = Field(
+        default=30.0,
+        ge=1.0,
+        le=300.0,
+        description="Maximum time allowed per operation",
+    )
+    verify_ssl: bool = Field(
+        default=True,
+        description="Enable SSL certificate verification",
+    )
+    token_renewal_threshold_seconds: float = Field(
+        default=300.0,
+        ge=0.0,
+        description="Trigger renewal when remaining TTL falls below this value",
+    )
+    default_token_ttl: int = Field(
+        default=3600,
+        ge=300,
+        le=86400,
+        description="Fallback TTL when Vault response does not provide TTL",
+    )
+    retry: ModelVaultRetryConfig = Field(
+        default_factory=ModelVaultRetryConfig,
+        description="Retry behavior for failed operations",
+    )
+    max_concurrent_operations: int = Field(
+        default=10,
+        ge=1,
+        le=100,
+        description="Thread pool size for concurrent operations",
+    )
+    max_queue_size_multiplier: int = Field(
+        default=3,
+        ge=1,
+        le=10,
+        description="Multiplier to calculate queue capacity from thread pool size",
+    )
+    circuit_breaker_enabled: bool = Field(
+        default=True,
+        description="Enable automatic failure detection and recovery",
+    )
+    circuit_breaker_failure_threshold: int = Field(
+        default=5,
+        ge=1,
+        le=20,
+        description="Consecutive failures required to open circuit",
+    )
+    circuit_breaker_reset_timeout_seconds: float = Field(
+        default=30.0,
+        ge=1.0,
+        le=300.0,
+        description="Wait time before testing recovery after circuit opens",
+    )
+
+
+__all__: list[str] = ["ModelVaultHandlerConfig"]

omnibase_infra/handlers/models/vault/model_vault_handler_payload.py

@@ -0,0 +1,101 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Vault Handler Payload Model.
+
+This module provides the discriminated union type for Vault operation payloads
+and the wrapper model that contains them.
+"""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+from pydantic import BaseModel, ConfigDict, Discriminator, Field, Tag
+
+from omnibase_infra.handlers.models.vault.model_vault_delete_payload import (
+    ModelVaultDeletePayload,
+)
+from omnibase_infra.handlers.models.vault.model_vault_list_payload import (
+    ModelVaultListPayload,
+)
+from omnibase_infra.handlers.models.vault.model_vault_renew_token_payload import (
+    ModelVaultRenewTokenPayload,
+)
+from omnibase_infra.handlers.models.vault.model_vault_secret_payload import (
+    ModelVaultSecretPayload,
+)
+from omnibase_infra.handlers.models.vault.model_vault_write_payload import (
+    ModelVaultWritePayload,
+)
+
+
+def _vault_payload_discriminator(value: object) -> str:
+    """Discriminator function for VaultPayload union.
+
+    Determines which payload type to use based on the operation_type field.
+
+    Args:
+        value: The raw value being validated (dict or model instance)
+
+    Returns:
+        The discriminator tag value matching the operation_type
+    """
+    if isinstance(value, dict):
+        operation_type = value.get("operation_type", "read_secret")
+    else:
+        operation_type = getattr(value, "operation_type", "read_secret")
+
+    # Handle both enum values and string values
+    if hasattr(operation_type, "value"):
+        return str(operation_type.value)
+    return str(operation_type)
+
+
+# Discriminated union of all Vault payload types
+VaultPayload = Annotated[
+    Annotated[ModelVaultSecretPayload, Tag("read_secret")]
+    | Annotated[ModelVaultWritePayload, Tag("write_secret")]
+    | Annotated[ModelVaultDeletePayload, Tag("delete_secret")]
+    | Annotated[ModelVaultListPayload, Tag("list_secrets")]
+    | Annotated[ModelVaultRenewTokenPayload, Tag("renew_token")],
+    Discriminator(_vault_payload_discriminator),
+]
+
+
+class ModelVaultHandlerPayload(BaseModel):
+    """Wrapper model for Vault handler payloads.
+
+    Contains the discriminated union of all possible Vault operation payloads.
+    This allows the HandlerVault to return a consistent payload wrapper while
+    the actual payload type varies based on the operation.
+
+    Attributes:
+        data: The operation-specific payload (discriminated union)
+
+    Example:
+        >>> from omnibase_infra.handlers.models.vault import ModelVaultSecretPayload
+        >>> secret_payload = ModelVaultSecretPayload(
+        ...     data={"username": "admin"},
+        ...     metadata={"version": 1},
+        ... )
+        >>> wrapper = ModelVaultHandlerPayload(data=secret_payload)
+        >>> print(wrapper.data.operation_type)
+        <EnumVaultOperationType.READ_SECRET: 'read_secret'>
+    """
+
+    model_config = ConfigDict(
+        strict=True,
+        frozen=True,
+        extra="forbid",
+        from_attributes=True,
+    )
+
+    data: VaultPayload = Field(
+        description="Operation-specific payload",
+    )
+
+
+__all__: list[str] = [
+    "ModelVaultHandlerPayload",
+    "VaultPayload",
+]

omnibase_infra/handlers/models/vault/model_vault_list_payload.py

@@ -0,0 +1,58 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Vault List Payload Model.
+
+This module provides the Pydantic model for vault.list_secrets operation results.
+"""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import ConfigDict, Field
+
+from omnibase_infra.handlers.models.vault.enum_vault_operation_type import (
+    EnumVaultOperationType,
+)
+from omnibase_infra.handlers.models.vault.model_payload_vault import (
+    ModelPayloadVault,
+)
+from omnibase_infra.handlers.models.vault.registry_payload_vault import (
+    RegistryPayloadVault,
+)
+
+
+@RegistryPayloadVault.register("list_secrets")
+class ModelVaultListPayload(ModelPayloadVault):
+    """Payload for vault.list_secrets operation result.
+
+    Contains the list of secret keys at the specified path.
+
+    Attributes:
+        operation_type: Discriminator set to "list_secrets"
+        keys: List of secret key names at the path
+
+    Example:
+        >>> payload = ModelVaultListPayload(keys=["db/", "api/", "config"])
+        >>> print(payload.keys)
+        ['db/', 'api/', 'config']
+    """
+
+    model_config = ConfigDict(
+        strict=True,
+        frozen=True,
+        extra="forbid",
+        from_attributes=True,
+    )
+
+    operation_type: Literal[EnumVaultOperationType.LIST_SECRETS] = Field(
+        default=EnumVaultOperationType.LIST_SECRETS,
+        description="Operation type discriminator",
+    )
+    keys: list[str] = Field(
+        default_factory=list,
+        description="List of secret key names at the path",
+    )
+
+
+__all__: list[str] = ["ModelVaultListPayload"]

omnibase_infra/handlers/models/vault/model_vault_renew_token_payload.py

@@ -0,0 +1,67 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Vault Renew Token Payload Model.
+
+This module provides the Pydantic model for vault.renew_token operation results.
+"""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import ConfigDict, Field
+
+from omnibase_infra.handlers.models.vault.enum_vault_operation_type import (
+    EnumVaultOperationType,
+)
+from omnibase_infra.handlers.models.vault.model_payload_vault import (
+    ModelPayloadVault,
+)
+from omnibase_infra.handlers.models.vault.registry_payload_vault import (
+    RegistryPayloadVault,
+)
+
+
+@RegistryPayloadVault.register("renew_token")
+class ModelVaultRenewTokenPayload(ModelPayloadVault):
+    """Payload for vault.renew_token operation result.
+
+    Contains token renewal information including new TTL.
+
+    Attributes:
+        operation_type: Discriminator set to "renew_token"
+        renewable: Whether the token can be renewed again
+        lease_duration: New token TTL in seconds
+
+    Example:
+        >>> payload = ModelVaultRenewTokenPayload(
+        ...     renewable=True,
+        ...     lease_duration=3600,
+        ... )
+        >>> print(payload.lease_duration)
+        3600
+    """
+
+    model_config = ConfigDict(
+        strict=True,
+        frozen=True,
+        extra="forbid",
+        from_attributes=True,
+    )
+
+    operation_type: Literal[EnumVaultOperationType.RENEW_TOKEN] = Field(
+        default=EnumVaultOperationType.RENEW_TOKEN,
+        description="Operation type discriminator",
+    )
+    renewable: bool = Field(
+        default=False,
+        description="Whether the token can be renewed again",
+    )
+    lease_duration: int = Field(
+        default=0,
+        ge=0,
+        description="New token TTL in seconds",
+    )
+
+
+__all__: list[str] = ["ModelVaultRenewTokenPayload"]

omnibase_infra/handlers/models/vault/model_vault_retry_config.py

@@ -0,0 +1,66 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Vault Retry Configuration Model.
+
+This module provides the Pydantic configuration model for Vault operation
+retry logic with exponential backoff.
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class ModelVaultRetryConfig(BaseModel):
+    """Configuration for Vault operation retry logic with exponential backoff.
+
+    Attributes:
+        max_attempts: Maximum number of retry attempts (1-10)
+        initial_backoff_seconds: Initial backoff delay in seconds (0.01-10.0)
+        max_backoff_seconds: Maximum backoff delay in seconds (1.0-60.0)
+        exponential_base: Exponential backoff multiplier (1.5-4.0)
+
+    Example:
+        >>> retry_config = ModelVaultRetryConfig(
+        ...     max_attempts=3,
+        ...     initial_backoff_seconds=0.1,
+        ...     max_backoff_seconds=10.0,
+        ...     exponential_base=2.0,
+        ... )
+        >>> # Backoff sequence: 0.1s, 0.2s, 0.4s
+    """
+
+    model_config = ConfigDict(
+        strict=True,
+        frozen=True,
+        extra="forbid",
+        from_attributes=True,
+    )
+
+    max_attempts: int = Field(
+        default=3,
+        ge=1,
+        le=10,
+        description="Maximum retry attempts for failed operations",
+    )
+    initial_backoff_seconds: float = Field(
+        default=0.1,
+        ge=0.01,
+        le=10.0,
+        description="Initial delay before first retry",
+    )
+    max_backoff_seconds: float = Field(
+        default=10.0,
+        ge=1.0,
+        le=60.0,
+        description="Maximum delay cap for exponential backoff",
+    )
+    exponential_base: float = Field(
+        default=2.0,
+        ge=1.5,
+        le=4.0,
+        description="Base multiplier for exponential backoff calculation",
+    )
+
+
+__all__: list[str] = ["ModelVaultRetryConfig"]

omnibase_infra/handlers/models/vault/model_vault_secret_payload.py

@@ -0,0 +1,106 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Vault Secret Payload Model.
+
+This module provides the Pydantic model for vault.read_secret operation results.
+
+JsonType Recursion Fix (OMN-1274):
+    This module uses ``dict[str, object]`` for the ``data`` and ``metadata``
+    fields instead of the recursive ``JsonType`` type alias. Here is why:
+
+    **The Original Problem:**
+    ``JsonType`` was defined as a recursive type alias::
+
+        JsonType = dict[str, "JsonType"] | list["JsonType"] | str | int | float | bool | None
+
+    Pydantic 2.x performs eager schema generation at class definition time.
+    When encountering recursive type aliases, it attempts infinite expansion::
+
+        JsonType -> dict[str, JsonType] | list[JsonType] | ...
+                 -> dict[str, dict[str, JsonType] | ...] | ...
+                 -> ... (RecursionError)
+
+    **Why dict[str, object] is Correct Here:**
+    Vault secrets are always structured as key-value dictionaries:
+
+    - ``data``: Secret key-value pairs (e.g., {"username": "...", "password": "..."})
+    - ``metadata``: Vault metadata (version, created_time, etc.)
+
+    Neither field needs to support arrays or primitives at the root level,
+    making ``dict[str, object]`` the semantically correct choice.
+
+    Using ``dict[str, object]`` provides:
+    - Correct semantics: Vault secrets are always dictionaries
+    - Type safety: Pydantic validates the outer structure
+    - No recursion: ``object`` avoids the recursive type expansion
+
+    **Caveats:**
+    - Values are typed as ``object`` (no static type checking on values)
+    - Callers should validate expected secret structure at runtime
+    - For full JSON support (any JSON value), use ``JsonType`` from
+      ``omnibase_core.types`` (now fixed via TypeAlias pattern)
+
+See Also:
+    - ADR: ``docs/decisions/adr-any-type-pydantic-workaround.md`` (historical)
+    - Pydantic issue: https://github.com/pydantic/pydantic/issues/3278
+"""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import ConfigDict, Field
+
+from omnibase_infra.handlers.models.vault.enum_vault_operation_type import (
+    EnumVaultOperationType,
+)
+from omnibase_infra.handlers.models.vault.model_payload_vault import (
+    ModelPayloadVault,
+)
+from omnibase_infra.handlers.models.vault.registry_payload_vault import (
+    RegistryPayloadVault,
+)
+
+
+@RegistryPayloadVault.register("read_secret")
+class ModelVaultSecretPayload(ModelPayloadVault):
+    """Payload for vault.read_secret operation result.
+
+    Contains the secret data retrieved from Vault KV v2 secrets engine
+    along with metadata about the secret version.
+
+    Attributes:
+        operation_type: Discriminator set to "read_secret"
+        data: The secret data as a key-value dictionary
+        metadata: Vault metadata about the secret (version, created_time, etc.)
+
+    Example:
+        >>> payload = ModelVaultSecretPayload(
+        ...     data={"username": "admin", "password": "secret"},
+        ...     metadata={"version": 1, "created_time": "2025-01-01T00:00:00Z"},
+        ... )
+        >>> print(payload.data["username"])
+        'admin'
+    """
+
+    model_config = ConfigDict(
+        strict=True,
+        frozen=True,
+        extra="forbid",
+        from_attributes=True,
+    )
+
+    operation_type: Literal[EnumVaultOperationType.READ_SECRET] = Field(
+        default=EnumVaultOperationType.READ_SECRET,
+        description="Operation type discriminator",
+    )
+    data: dict[str, object] = Field(
+        description="Secret data as key-value dictionary",
+    )
+    metadata: dict[str, object] = Field(
+        default_factory=dict,
+        description="Vault metadata about the secret",
+    )
+
+
+__all__: list[str] = ["ModelVaultSecretPayload"]

omnibase_infra/handlers/models/vault/model_vault_write_payload.py

@@ -0,0 +1,66 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Vault Write Payload Model.
+
+This module provides the Pydantic model for vault.write_secret operation results.
+"""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import ConfigDict, Field
+
+from omnibase_infra.handlers.models.vault.enum_vault_operation_type import (
+    EnumVaultOperationType,
+)
+from omnibase_infra.handlers.models.vault.model_payload_vault import (
+    ModelPayloadVault,
+)
+from omnibase_infra.handlers.models.vault.registry_payload_vault import (
+    RegistryPayloadVault,
+)
+
+
+@RegistryPayloadVault.register("write_secret")
+class ModelVaultWritePayload(ModelPayloadVault):
+    """Payload for vault.write_secret operation result.
+
+    Contains confirmation of secret write operation with version information.
+
+    Attributes:
+        operation_type: Discriminator set to "write_secret"
+        version: The version number of the newly written secret
+        created_time: Timestamp when the secret version was created
+
+    Example:
+        >>> payload = ModelVaultWritePayload(
+        ...     version=2,
+        ...     created_time="2025-01-01T00:00:00Z",
+        ... )
+        >>> print(payload.version)
+        2
+    """
+
+    model_config = ConfigDict(
+        strict=True,
+        frozen=True,
+        extra="forbid",
+        from_attributes=True,
+    )
+
+    operation_type: Literal[EnumVaultOperationType.WRITE_SECRET] = Field(
+        default=EnumVaultOperationType.WRITE_SECRET,
+        description="Operation type discriminator",
+    )
+    version: int | None = Field(
+        default=None,
+        description="Version number of the written secret",
+    )
+    created_time: str | None = Field(
+        default=None,
+        description="Timestamp when the secret version was created",
+    )
+
+
+__all__: list[str] = ["ModelVaultWritePayload"]