omnibase_infra 0.2.1__py3-none-any.whl

omnibase_infra/handlers/models/consul/__init__.py

@@ -0,0 +1,81 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Consul Handler Models Package.
+
+This package provides strongly-typed Pydantic models for Consul handler response payloads.
+Each Consul operation has a dedicated payload model with a discriminator field for
+type-safe union handling.
+
+Payload Types:
+    - ModelConsulKVGetFoundPayload: Single key found in KV store
+    - ModelConsulKVGetNotFoundPayload: Key not found in KV store
+    - ModelConsulKVGetRecursePayload: Recursive key listing from KV store
+    - ModelConsulKVPutPayload: KV put operation result
+    - ModelConsulRegisterPayload: Service registration result
+    - ModelConsulDeregisterPayload: Service deregistration result
+
+Union Type:
+    ConsulPayload: Discriminated union of all payload types using operation_type field
+
+Registry-Based Alternative (OMN-1007):
+    - ModelPayloadConsul: Base model for all Consul handler payloads
+    - RegistryPayloadConsul: Decorator-based registry for payload type discovery
+"""
+
+from omnibase_infra.handlers.models.consul.enum_consul_operation_type import (
+    EnumConsulOperationType,
+)
+from omnibase_infra.handlers.models.consul.model_consul_deregister_payload import (
+    ModelConsulDeregisterPayload,
+)
+from omnibase_infra.handlers.models.consul.model_consul_handler_config import (
+    ModelConsulHandlerConfig,
+)
+from omnibase_infra.handlers.models.consul.model_consul_handler_payload import (
+    ConsulPayload,
+    ModelConsulHandlerPayload,
+)
+from omnibase_infra.handlers.models.consul.model_consul_kv_get_found_payload import (
+    ModelConsulKVGetFoundPayload,
+)
+from omnibase_infra.handlers.models.consul.model_consul_kv_get_not_found_payload import (
+    ModelConsulKVGetNotFoundPayload,
+)
+from omnibase_infra.handlers.models.consul.model_consul_kv_get_recurse_payload import (
+    ModelConsulKVGetRecursePayload,
+)
+from omnibase_infra.handlers.models.consul.model_consul_kv_item import (
+    ModelConsulKVItem,
+)
+from omnibase_infra.handlers.models.consul.model_consul_kv_put_payload import (
+    ModelConsulKVPutPayload,
+)
+from omnibase_infra.handlers.models.consul.model_consul_register_payload import (
+    ModelConsulRegisterPayload,
+)
+from omnibase_infra.handlers.models.consul.model_consul_retry_config import (
+    ModelConsulRetryConfig,
+)
+from omnibase_infra.handlers.models.consul.model_payload_consul import (
+    ModelPayloadConsul,
+)
+from omnibase_infra.handlers.models.consul.registry_payload_consul import (
+    RegistryPayloadConsul,
+)
+
+__all__: list[str] = [
+    "ConsulPayload",
+    "EnumConsulOperationType",
+    "ModelConsulDeregisterPayload",
+    "ModelConsulHandlerConfig",
+    "ModelConsulHandlerPayload",
+    "ModelConsulKVGetFoundPayload",
+    "ModelConsulKVGetNotFoundPayload",
+    "ModelConsulKVGetRecursePayload",
+    "ModelConsulKVItem",
+    "ModelConsulKVPutPayload",
+    "ModelConsulRegisterPayload",
+    "ModelConsulRetryConfig",
+    "ModelPayloadConsul",
+    "RegistryPayloadConsul",
+]

omnibase_infra/handlers/models/consul/enum_consul_operation_type.py

@@ -0,0 +1,57 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Consul Operation Type Enum.
+
+This module provides the discriminator enum for Consul operation payload types.
+Each operation type corresponds to a specific payload model in the discriminated union.
+
+NOT_FOUND Response Pattern:
+    The ``KV_GET_NOT_FOUND`` variant represents a successful Consul KV lookup
+    where the requested key does not exist. This is distinct from error-based
+    NOT_FOUND handling:
+
+    - **Response variant (this enum)**: Used when key absence is a valid outcome.
+      The handler returns a ``KV_GET_NOT_FOUND`` response, allowing callers to
+      distinguish between "key exists with value" and "key does not exist"
+      without exception handling.
+
+    - **Error-based NOT_FOUND**: Used in ``SecretResolutionError`` when a
+      required resource is missing (exceptional condition). See ``infra_errors.py``
+      for error-based patterns.
+
+    Example usage for callers:
+
+    .. code-block:: python
+
+        result = await consul_handler.kv_get("config/my-key")
+        match result.operation_type:
+            case EnumConsulOperationType.KV_GET_FOUND:
+                return result.value
+            case EnumConsulOperationType.KV_GET_NOT_FOUND:
+                return default_config  # Key doesn't exist, use default
+
+    This pattern allows callers to handle key absence as a normal control flow
+    case rather than an exception, which is appropriate for optional configuration
+    lookups or cache-style access patterns.
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+
+
+class EnumConsulOperationType(str, Enum):
+    """Discriminator for Consul operation payload types.
+
+    Each operation type corresponds to a specific payload model.
+    """
+
+    KV_GET_FOUND = "kv_get_found"
+    KV_GET_NOT_FOUND = "kv_get_not_found"
+    KV_GET_RECURSE = "kv_get_recurse"
+    KV_PUT = "kv_put"
+    REGISTER = "register"
+    DEREGISTER = "deregister"
+
+
+__all__: list[str] = ["EnumConsulOperationType"]

omnibase_infra/handlers/models/consul/model_consul_deregister_payload.py

@@ -0,0 +1,51 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Consul Deregister Payload Model.
+
+This module provides the payload model for consul.deregister result.
+"""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import ConfigDict, Field
+
+from omnibase_infra.handlers.models.consul.model_payload_consul import (
+    ModelPayloadConsul,
+)
+from omnibase_infra.handlers.models.consul.registry_payload_consul import (
+    RegistryPayloadConsul,
+)
+
+
+@RegistryPayloadConsul.register("deregister")
+class ModelConsulDeregisterPayload(ModelPayloadConsul):
+    """Payload for consul.deregister result.
+
+    Attributes:
+        operation_type: Discriminator literal "deregister".
+        deregistered: True if the service was deregistered successfully.
+        consul_service_id: The Consul service identifier that was deregistered.
+
+    Note:
+        consul_service_id is a Consul-specific identifier that is a user-defined string,
+        NOT a UUID. The Consul API accepts any string as a service ID. This field is
+        named with the 'consul_' prefix to avoid pattern validator warnings that expect
+        fields ending in '_id' to be UUIDs.
+    """
+
+    model_config = ConfigDict(strict=True, frozen=True, extra="forbid")
+
+    operation_type: Literal["deregister"] = Field(
+        default="deregister", description="Discriminator for payload type"
+    )
+    deregistered: bool = Field(
+        description="True if the service was deregistered successfully"
+    )
+    consul_service_id: str = Field(
+        description="The Consul service identifier that was deregistered (user-defined string, not a UUID)"
+    )
+
+
+__all__: list[str] = ["ModelConsulDeregisterPayload"]

omnibase_infra/handlers/models/consul/model_consul_handler_config.py

@@ -0,0 +1,153 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Consul Handler Configuration Model.
+
+This module provides the Pydantic configuration model for HashiCorp Consul
+handler initialization and operation.
+
+Security Note:
+    The token field uses SecretStr to prevent accidental logging of
+    sensitive ACL tokens. Tokens should come from environment variables,
+    never from YAML configuration files.
+"""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field, SecretStr
+
+from omnibase_infra.handlers.models.consul.model_consul_retry_config import (
+    ModelConsulRetryConfig,
+)
+
+
+class ModelConsulHandlerConfig(BaseModel):
+    """Configuration for HashiCorp Consul handler.
+
+    Security Policy:
+        - The token field uses SecretStr to prevent accidental logging
+        - ACL tokens should be provided via environment variables, not config files
+        - Never log or expose token values in error messages
+        - Use scheme="https" in production environments
+
+    Attributes:
+        host: Consul server hostname (default "localhost")
+        port: Consul server port (1-65535, default 8500)
+        scheme: HTTP scheme for connection (default "http")
+        token: Consul ACL token (SecretStr for security, optional)
+        timeout_seconds: Operation timeout in seconds (1.0-300.0, default 30.0)
+        connect_timeout_seconds: Connection timeout in seconds (1.0-60.0, default 10.0)
+        retry: Retry configuration with exponential backoff
+        health_check_interval_seconds: Interval for health checks (5.0-300.0, default 30.0)
+        datacenter: Consul datacenter for multi-datacenter deployments (optional)
+
+    Example:
+        >>> from pydantic import SecretStr
+        >>> config = ModelConsulHandlerConfig(
+        ...     host="consul.example.com",
+        ...     port=8500,
+        ...     scheme="https",
+        ...     token=SecretStr("acl-token-abc123"),
+        ...     datacenter="dc1",
+        ... )
+        >>> # Token is protected from accidental logging
+        >>> print(config.token)
+        SecretStr('**********')
+        >>> # Base URL property
+        >>> print(config.base_url)
+        https://consul.example.com:8500
+    """
+
+    model_config = ConfigDict(
+        strict=True,
+        frozen=True,
+        extra="forbid",
+        from_attributes=True,
+    )
+
+    host: str = Field(
+        default="localhost",
+        min_length=1,
+        description="Consul server hostname",
+    )
+    port: int = Field(
+        default=8500,
+        ge=1,
+        le=65535,
+        description="Consul server port",
+    )
+    scheme: Literal["http", "https"] = Field(
+        default="http",
+        description="HTTP scheme for Consul connection",
+    )
+    token: SecretStr | None = Field(
+        default=None,
+        description="Consul ACL token protected from logging",
+    )
+    timeout_seconds: float = Field(
+        default=30.0,
+        ge=1.0,
+        le=300.0,
+        description="Maximum time allowed per operation",
+    )
+    connect_timeout_seconds: float = Field(
+        default=10.0,
+        ge=1.0,
+        le=60.0,
+        description="Maximum time allowed for connection establishment",
+    )
+    retry: ModelConsulRetryConfig = Field(
+        default_factory=ModelConsulRetryConfig,
+        description="Retry behavior for failed operations",
+    )
+    health_check_interval_seconds: float = Field(
+        default=30.0,
+        ge=5.0,
+        le=300.0,
+        description="Interval between health check executions",
+    )
+    datacenter: str | None = Field(
+        default=None,
+        description="Consul datacenter for multi-datacenter deployments",
+    )
+    circuit_breaker_enabled: bool = Field(
+        default=True,
+        description="Enable automatic failure detection and recovery via circuit breaker",
+    )
+    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",
+    )
+    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",
+    )
+
+    @property
+    def base_url(self) -> str:
+        """Construct the base URL for Consul API requests.
+
+        Returns:
+            Complete base URL in format scheme://host:port
+        """
+        return f"{self.scheme}://{self.host}:{self.port}"
+
+
+__all__: list[str] = ["ModelConsulHandlerConfig"]

omnibase_infra/handlers/models/consul/model_consul_handler_payload.py

@@ -0,0 +1,89 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Consul Handler Payload Model.
+
+This module provides the discriminated union type and wrapper model for Consul handler
+response payloads.
+
+Union Type:
+    ConsulPayload: Discriminated union of all payload types using operation_type field
+"""
+
+from __future__ import annotations
+
+from typing import Annotated, Union
+
+from pydantic import BaseModel, ConfigDict, Discriminator, Field
+
+from omnibase_infra.handlers.models.consul.model_consul_deregister_payload import (
+    ModelConsulDeregisterPayload,
+)
+from omnibase_infra.handlers.models.consul.model_consul_kv_get_found_payload import (
+    ModelConsulKVGetFoundPayload,
+)
+from omnibase_infra.handlers.models.consul.model_consul_kv_get_not_found_payload import (
+    ModelConsulKVGetNotFoundPayload,
+)
+from omnibase_infra.handlers.models.consul.model_consul_kv_get_recurse_payload import (
+    ModelConsulKVGetRecursePayload,
+)
+from omnibase_infra.handlers.models.consul.model_consul_kv_put_payload import (
+    ModelConsulKVPutPayload,
+)
+from omnibase_infra.handlers.models.consul.model_consul_register_payload import (
+    ModelConsulRegisterPayload,
+)
+
+# Discriminated union type for all Consul payloads
+ConsulPayload = Annotated[
+    Union[
+        ModelConsulKVGetFoundPayload,
+        ModelConsulKVGetNotFoundPayload,
+        ModelConsulKVGetRecursePayload,
+        ModelConsulKVPutPayload,
+        ModelConsulRegisterPayload,
+        ModelConsulDeregisterPayload,
+    ],
+    Discriminator("operation_type"),
+]
+
+
+class ModelConsulHandlerPayload(BaseModel):
+    """Payload containing Consul operation results.
+
+    This model wraps the strongly-typed ConsulPayload discriminated union.
+    The payload type is determined by the operation_type field.
+
+    Attributes:
+        data: Strongly-typed operation result with discriminated union.
+
+    Example:
+        >>> from omnibase_infra.handlers.models import ModelConsulHandlerPayload
+        >>> payload = ModelConsulHandlerPayload(
+        ...     data=ModelConsulKVGetFoundPayload(
+        ...         found=True,
+        ...         key="mykey",
+        ...         value="myvalue",
+        ...         index=100,
+        ...     ),
+        ... )
+        >>> print(payload.data.operation_type)
+        'kv_get_found'
+    """
+
+    model_config = ConfigDict(
+        strict=True,
+        frozen=True,
+        extra="forbid",
+        from_attributes=True,  # Support pytest-xdist compatibility
+    )
+
+    data: ConsulPayload = Field(
+        description="Strongly-typed operation result with discriminated union",
+    )
+
+
+__all__: list[str] = [
+    "ConsulPayload",
+    "ModelConsulHandlerPayload",
+]

omnibase_infra/handlers/models/consul/model_consul_kv_get_found_payload.py

@@ -0,0 +1,55 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Consul KV Get Found Payload Model.
+
+This module provides the payload model for consul.kv_get when key is found (single key mode).
+"""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import ConfigDict, Field
+
+from omnibase_infra.handlers.models.consul.model_payload_consul import (
+    ModelPayloadConsul,
+)
+from omnibase_infra.handlers.models.consul.registry_payload_consul import (
+    RegistryPayloadConsul,
+)
+
+
+@RegistryPayloadConsul.register("kv_get_found")
+class ModelConsulKVGetFoundPayload(ModelPayloadConsul):
+    """Payload for consul.kv_get when key is found (single key mode).
+
+    Attributes:
+        operation_type: Discriminator literal "kv_get_found".
+        found: Always True for this payload type.
+        key: The KV key path that was queried.
+        value: The value stored at the key (decoded from bytes).
+        flags: Optional user-defined flags associated with the key.
+        modify_index: The Consul modify index for optimistic locking.
+        index: The Consul response index for blocking queries.
+    """
+
+    model_config = ConfigDict(
+        frozen=True, extra="forbid", coerce_numbers_to_str=False, from_attributes=True
+    )
+
+    operation_type: Literal["kv_get_found"] = Field(
+        default="kv_get_found", description="Discriminator for payload type"
+    )
+    found: Literal[True] = Field(
+        default=True, description="Indicates the key was found"
+    )
+    key: str = Field(description="The KV key path that was queried")
+    value: str | None = Field(description="The value stored at the key")
+    flags: int | None = Field(default=None, description="User-defined flags")
+    modify_index: int | None = Field(
+        default=None, description="Consul modify index for CAS operations"
+    )
+    index: int = Field(description="Consul response index for blocking queries")
+
+
+__all__: list[str] = ["ModelConsulKVGetFoundPayload"]

omnibase_infra/handlers/models/consul/model_consul_kv_get_not_found_payload.py

@@ -0,0 +1,49 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Consul KV Get Not Found Payload Model.
+
+This module provides the payload model for consul.kv_get when key is not found.
+"""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import ConfigDict, Field
+
+from omnibase_infra.handlers.models.consul.model_payload_consul import (
+    ModelPayloadConsul,
+)
+from omnibase_infra.handlers.models.consul.registry_payload_consul import (
+    RegistryPayloadConsul,
+)
+
+
+@RegistryPayloadConsul.register("kv_get_not_found")
+class ModelConsulKVGetNotFoundPayload(ModelPayloadConsul):
+    """Payload for consul.kv_get when key is not found.
+
+    Attributes:
+        operation_type: Discriminator literal "kv_get_not_found".
+        found: Always False for this payload type.
+        key: The KV key path that was queried.
+        value: Always None for not-found case.
+        index: The Consul response index for blocking queries.
+    """
+
+    model_config = ConfigDict(
+        frozen=True, extra="forbid", coerce_numbers_to_str=False, from_attributes=True
+    )
+
+    operation_type: Literal["kv_get_not_found"] = Field(
+        default="kv_get_not_found", description="Discriminator for payload type"
+    )
+    found: Literal[False] = Field(
+        default=False, description="Indicates the key was not found"
+    )
+    key: str = Field(description="The KV key path that was queried")
+    value: None = Field(default=None, description="Always None for not-found case")
+    index: int = Field(description="Consul response index for blocking queries")
+
+
+__all__: list[str] = ["ModelConsulKVGetNotFoundPayload"]

omnibase_infra/handlers/models/consul/model_consul_kv_get_recurse_payload.py

@@ -0,0 +1,50 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Consul KV Get Recurse Payload Model.
+
+This module provides the payload model for consul.kv_get with recurse=True.
+"""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import ConfigDict, Field
+
+from omnibase_infra.handlers.models.consul.model_consul_kv_item import (
+    ModelConsulKVItem,
+)
+from omnibase_infra.handlers.models.consul.model_payload_consul import (
+    ModelPayloadConsul,
+)
+from omnibase_infra.handlers.models.consul.registry_payload_consul import (
+    RegistryPayloadConsul,
+)
+
+
+@RegistryPayloadConsul.register("kv_get_recurse")
+class ModelConsulKVGetRecursePayload(ModelPayloadConsul):
+    """Payload for consul.kv_get with recurse=True.
+
+    Attributes:
+        operation_type: Discriminator literal "kv_get_recurse".
+        found: True if any keys were found under the prefix.
+        items: List of KV items found under the prefix.
+        count: Number of items found.
+        index: The Consul response index for blocking queries.
+    """
+
+    model_config = ConfigDict(strict=True, frozen=True, extra="forbid")
+
+    operation_type: Literal["kv_get_recurse"] = Field(
+        default="kv_get_recurse", description="Discriminator for payload type"
+    )
+    found: bool = Field(description="True if any keys were found under the prefix")
+    items: list[ModelConsulKVItem] = Field(
+        description="List of KV items found under the prefix"
+    )
+    count: int = Field(description="Number of items found")
+    index: int = Field(description="Consul response index for blocking queries")
+
+
+__all__: list[str] = ["ModelConsulKVGetRecursePayload"]

omnibase_infra/handlers/models/consul/model_consul_kv_item.py

@@ -0,0 +1,33 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Consul KV Item Model.
+
+This module provides the model for a single KV item from a recurse query.
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class ModelConsulKVItem(BaseModel):
+    """Single KV item from recurse query.
+
+    Attributes:
+        key: The KV key path.
+        value: The value stored at the key (decoded from bytes).
+        flags: Optional user-defined flags associated with the key.
+        modify_index: The Consul modify index for optimistic locking.
+    """
+
+    model_config = ConfigDict(strict=True, frozen=True, extra="forbid")
+
+    key: str = Field(description="The KV key path")
+    value: str | None = Field(description="The value stored at the key")
+    flags: int | None = Field(default=None, description="User-defined flags")
+    modify_index: int | None = Field(
+        default=None, description="Consul modify index for CAS operations"
+    )
+
+
+__all__: list[str] = ["ModelConsulKVItem"]

omnibase_infra/handlers/models/consul/model_consul_kv_put_payload.py

@@ -0,0 +1,41 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Consul KV Put Payload Model.
+
+This module provides the payload model for consul.kv_put result.
+"""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import ConfigDict, Field
+
+from omnibase_infra.handlers.models.consul.model_payload_consul import (
+    ModelPayloadConsul,
+)
+from omnibase_infra.handlers.models.consul.registry_payload_consul import (
+    RegistryPayloadConsul,
+)
+
+
+@RegistryPayloadConsul.register("kv_put")
+class ModelConsulKVPutPayload(ModelPayloadConsul):
+    """Payload for consul.kv_put result.
+
+    Attributes:
+        operation_type: Discriminator literal "kv_put".
+        success: True if the put operation succeeded.
+        key: The KV key path that was written.
+    """
+
+    model_config = ConfigDict(strict=True, frozen=True, extra="forbid")
+
+    operation_type: Literal["kv_put"] = Field(
+        default="kv_put", description="Discriminator for payload type"
+    )
+    success: bool = Field(description="True if the put operation succeeded")
+    key: str = Field(description="The KV key path that was written")
+
+
+__all__: list[str] = ["ModelConsulKVPutPayload"]