python-config-client 0.1.2__py3-none-any.whl

config_client/crypto.py

@@ -0,0 +1,75 @@
+"""AES-256-GCM decryption helpers for Config Service responses."""
+
+from __future__ import annotations
+
+import binascii
+
+from cryptography.hazmat.primitives.ciphers.aead import AESGCM
+
+from config_client.errors import ConfigClientError, DecryptionError
+
+NONCE_SIZE: int = 12  # bytes
+GCM_TAG_SIZE: int = 16  # bytes
+_MIN_CIPHERTEXT_SIZE: int = NONCE_SIZE + GCM_TAG_SIZE
+
+
+def decrypt(ciphertext: bytes, key: bytes) -> bytes:
+    """Decrypt an AES-256-GCM ciphertext produced by Config Service.
+
+    The expected wire format is::
+
+        nonce (12 bytes) || encrypted_data || GCM tag (16 bytes)
+
+    This format is compatible with the Go SDK's ``gcm.Seal(nonce, nonce,
+    plaintext, nil)`` call.
+
+    Args:
+        ciphertext: Raw bytes received from the Config Service endpoint.
+        key: 32-byte AES-256 key derived from :func:`parse_encryption_key`.
+
+    Returns:
+        Decrypted plaintext bytes (JSON-encoded configuration).
+
+    Raises:
+        DecryptionError: If *ciphertext* is too short or AESGCM authentication
+            fails (wrong key, corrupted data, etc.).
+
+    """
+    if len(ciphertext) < _MIN_CIPHERTEXT_SIZE:
+        raise DecryptionError(
+            f"ciphertext too short: expected at least {_MIN_CIPHERTEXT_SIZE} bytes, "
+            f"got {len(ciphertext)}"
+        )
+
+    nonce = ciphertext[:NONCE_SIZE]
+    encrypted = ciphertext[NONCE_SIZE:]
+
+    try:
+        aesgcm = AESGCM(key)
+        return aesgcm.decrypt(nonce, encrypted, None)
+    except Exception as exc:
+        raise DecryptionError("AES-256-GCM decryption failed") from exc
+
+
+def parse_encryption_key(hex_key: str) -> bytes:
+    """Parse and validate a hex-encoded AES-256 encryption key.
+
+    Args:
+        hex_key: 64-character hexadecimal string representing a 32-byte key.
+
+    Returns:
+        Raw 32-byte key suitable for passing to :func:`decrypt`.
+
+    Raises:
+        ConfigClientError: If *hex_key* is not exactly 64 characters or contains
+            non-hexadecimal characters.
+
+    """
+    if len(hex_key) != 64:
+        raise ConfigClientError(
+            f"encryption_key must be exactly 64 hex characters (32 bytes), got {len(hex_key)}"
+        )
+    try:
+        return binascii.unhexlify(hex_key)
+    except binascii.Error as exc:
+        raise ConfigClientError("encryption_key is not valid hexadecimal") from exc

config_client/errors.py

@@ -0,0 +1,68 @@
+"""Exception hierarchy for python-config-client."""
+
+from __future__ import annotations
+
+
+class ConfigClientError(Exception):
+    """Base class for all ``config_client`` exceptions.
+
+    Catch this to handle any error raised by the SDK.
+    """
+
+
+class UnauthorizedError(ConfigClientError):
+    """HTTP 401 — invalid or expired service token.
+
+    Raised when the Config Service rejects the ``X-Service-Token`` header.
+    This error is **not** retried automatically.
+    """
+
+
+class ForbiddenError(ConfigClientError):
+    """HTTP 403 — insufficient permissions.
+
+    Raised when the service token does not have access to the requested
+    configuration. This error is **not** retried automatically.
+    """
+
+
+class NotFoundError(ConfigClientError):
+    """HTTP 404 — configuration not found.
+
+    Raised when the requested configuration name does not exist or is not
+    accessible with the current service token.
+    """
+
+
+class DecryptionError(ConfigClientError):
+    """AES-256-GCM decryption failed.
+
+    Raised when the ciphertext received from Config Service cannot be
+    decrypted with the provided ``encryption_key``. This typically means
+    the wrong key was supplied.
+    """
+
+
+class InvalidResponseError(ConfigClientError):
+    """Unexpected server response.
+
+    Raised on non-retriable 4xx HTTP responses other than 401, 403, 404,
+    or when the response body cannot be parsed as expected.
+    """
+
+
+class ConnectionError(ConfigClientError):
+    """Network error or 5xx response after all retries are exhausted.
+
+    Raised when the HTTP transport fails due to a network-level error
+    (``httpx.TransportError``) or the server returns a 5xx status code
+    and the configured ``retry_count`` has been exceeded.
+    """
+
+
+class UnmarshalError(ConfigClientError):
+    """Failed to deserialize decrypted JSON into the target type.
+
+    Raised when the decrypted JSON payload cannot be mapped onto the
+    ``target_type`` passed to :meth:`~config_client.ConfigClient.get`.
+    """

config_client/options.py

@@ -0,0 +1,96 @@
+"""Options and GetOptions dataclasses for ConfigClient configuration."""
+
+from __future__ import annotations
+
+import binascii
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    import httpx
+
+from config_client.errors import ConfigClientError
+
+
+def _validate_host(host: str) -> None:
+    """Raise ``ConfigClientError`` if *host* is empty."""
+    if not host:
+        raise ConfigClientError("Options.host must not be empty")
+
+
+def _validate_service_token(token: str) -> None:
+    """Raise ``ConfigClientError`` if *token* is empty."""
+    if not token:
+        raise ConfigClientError("Options.service_token must not be empty")
+
+
+def _validate_encryption_key(hex_key: str) -> None:
+    """Raise ``ConfigClientError`` if *hex_key* is not a valid 64-char hex string."""
+    if len(hex_key) != 64:
+        raise ConfigClientError(
+            f"Options.encryption_key must be exactly 64 hex characters (32 bytes), "
+            f"got {len(hex_key)}"
+        )
+    try:
+        binascii.unhexlify(hex_key)
+    except binascii.Error as exc:
+        raise ConfigClientError("Options.encryption_key is not valid hexadecimal") from exc
+
+
+@dataclass
+class Options:
+    """Configuration options for :class:`~config_client.ConfigClient`.
+
+    All fields are validated on construction via ``__post_init__``.
+
+    Attributes:
+        host: Base URL of the Config Service (e.g. ``https://config.example.com``).
+        service_token: Plain-text service token used in ``X-Service-Token`` header.
+        encryption_key: AES-256 key as a 64-character hex string (32 bytes).
+        http_client: Optional pre-configured ``httpx.Client``. When provided,
+            the caller is responsible for closing it.
+        request_timeout: HTTP request timeout in seconds. Defaults to ``10.0``.
+        retry_count: Number of retry attempts for retriable errors. Defaults to ``3``.
+        retry_delay: Base delay between retries in seconds (exponential backoff).
+            Defaults to ``1.0``.
+        on_error: Optional callback invoked with the exception when a watch error
+            occurs. Does not stop the watch loop.
+        on_change: Optional callback invoked with the config name when a change
+            event is received from the SSE stream.
+
+    """
+
+    # --- required ---
+    host: str
+    service_token: str
+    encryption_key: str
+
+    # --- optional ---
+    http_client: httpx.Client | None = field(default=None)
+    request_timeout: float = 10.0
+    retry_count: int = 3
+    retry_delay: float = 1.0
+    on_error: Callable[[Exception], None] | None = field(default=None)
+    on_change: Callable[[str], None] | None = field(default=None)
+
+    def __post_init__(self) -> None:
+        """Validate all required fields."""
+        _validate_host(self.host)
+        _validate_service_token(self.service_token)
+        _validate_encryption_key(self.encryption_key)
+
+
+@dataclass
+class GetOptions:
+    """Per-request options for config retrieval methods.
+
+    Attributes:
+        environment: Filter configurations by environment label (e.g.
+            ``"production"``, ``"staging"``). Empty string means no filter.
+        version: Specific version to retrieve. ``0`` means the latest version.
+
+    """
+
+    environment: str = ""
+    version: int = 0

config_client/snapshot.py

@@ -0,0 +1,50 @@
+"""Thread-safe Snapshot container for hot-reload support."""
+
+from __future__ import annotations
+
+import threading
+from typing import Generic, TypeVar
+
+T = TypeVar("T")
+
+
+class Snapshot(Generic[T]):
+    """Thread-safe container for a configuration value with hot-reload support.
+
+    Designed to be written by a background watch thread and read concurrently
+    by any number of application threads without explicit locking on the
+    caller side.
+
+    Example::
+
+        snapshot: Snapshot[AppConfig] = Snapshot()
+        snapshot.store(client.get("my-service", AppConfig))
+
+        # In application code (any thread):
+        cfg = snapshot.load()
+        if cfg is not None:
+            print(cfg.log_level)
+    """
+
+    def __init__(self) -> None:
+        """Initialise an empty snapshot."""
+        self._lock: threading.RLock = threading.RLock()
+        self._value: T | None = None
+
+    def load(self) -> T | None:
+        """Return the current configuration value.
+
+        Returns ``None`` if :meth:`store` has never been called.
+        Safe for concurrent reads from multiple threads.
+        """
+        with self._lock:
+            return self._value
+
+    def store(self, value: T) -> None:
+        """Replace the current configuration value with *value*.
+
+        Safe for concurrent writes; subsequent :meth:`load` calls will
+        immediately observe the new value.
+        """
+        with self._lock:
+            self._value = value

config_client/transport.py

@@ -0,0 +1,207 @@
+"""HTTP transport layer with retry and exponential backoff."""
+
+from __future__ import annotations
+
+import logging
+import random
+import time
+
+import httpx
+
+from config_client.errors import (
+    ConnectionError,
+    ForbiddenError,
+    InvalidResponseError,
+    NotFoundError,
+    UnauthorizedError,
+)
+
+logger = logging.getLogger("config_client")
+
+_MAX_BACKOFF: float = 30.0
+
+
+def _mask_token(token: str) -> str:
+    """Return a masked representation of *token* safe for logging."""
+    if len(token) <= 4:
+        return "****"
+    return "****" + token[-4:]
+
+
+def backoff_delay(attempt: int, base_delay: float) -> float:
+    """Compute exponential backoff delay with full jitter.
+
+    The delay is sampled uniformly from ``[0, min(base * 2^attempt, 30.0)]``,
+    which is the "full jitter" strategy recommended to avoid thundering herd.
+
+    Args:
+        attempt: Zero-based attempt index (first retry = 1, second = 2, …).
+        base_delay: Base delay in seconds.
+
+    Returns:
+        A random float in ``[0.0, cap]`` where ``cap = min(base * 2^attempt, 30.0)``.
+
+    """
+    cap = min(base_delay * (2**attempt), _MAX_BACKOFF)
+    return random.uniform(0.0, cap)  # noqa: S311 — jitter, not cryptographic
+
+
+def _raise_for_status(response: httpx.Response) -> None:
+    """Map an HTTP error response to the appropriate SDK exception.
+
+    Args:
+        response: A completed ``httpx.Response`` with a non-2xx status code.
+
+    Raises:
+        UnauthorizedError: HTTP 401.
+        ForbiddenError: HTTP 403.
+        NotFoundError: HTTP 404.
+        InvalidResponseError: Any other 4xx.
+
+    """
+    status = response.status_code
+    if status == 401:
+        raise UnauthorizedError(f"HTTP 401 Unauthorized: {response.text}")
+    if status == 403:
+        raise ForbiddenError(f"HTTP 403 Forbidden: {response.text}")
+    if status == 404:
+        raise NotFoundError(f"HTTP 404 Not Found: {response.text}")
+    if 400 <= status < 500:
+        raise InvalidResponseError(f"HTTP {status} client error: {response.text}")
+
+
+class Transport:
+    """HTTP transport with retry logic and structured logging.
+
+    Wraps ``httpx.Client`` with:
+    - Automatic ``X-Service-Token`` header injection.
+    - Exponential backoff with full jitter for 5xx / network errors.
+    - Deterministic mapping of HTTP status codes to SDK exceptions.
+    - Token masking in all log messages.
+
+    Args:
+        host: Base URL of the Config Service.
+        service_token: Plain-text service token.
+        request_timeout: Per-request timeout in seconds.
+        retry_count: Number of retry attempts for retriable errors.
+        retry_delay: Base delay for exponential backoff.
+        http_client: Optional pre-configured ``httpx.Client``. When
+            provided the caller owns its lifecycle; ``close()`` will not
+            close it.
+
+    """
+
+    def __init__(
+        self,
+        host: str,
+        service_token: str,
+        request_timeout: float,
+        retry_count: int,
+        retry_delay: float,
+        http_client: httpx.Client | None = None,
+    ) -> None:
+        """Initialise the transport."""
+        self._host = host.rstrip("/")
+        self._token = service_token
+        self._retry_count = retry_count
+        self._retry_delay = retry_delay
+        self._owns_client = http_client is None
+
+        self._client = http_client or httpx.Client(
+            timeout=httpx.Timeout(request_timeout),
+            verify=True,  # SSL verification enabled by default
+        )
+
+    # ------------------------------------------------------------------
+    # Public interface
+    # ------------------------------------------------------------------
+
+    def get(self, path: str, **params: str | int) -> httpx.Response:
+        """Perform a GET request with retry logic.
+
+        Retries on 5xx responses and ``httpx.TransportError``. 4xx errors
+        are raised immediately without retrying.
+
+        Args:
+            path: URL path relative to the host (e.g. ``/api/v1/service/configs``).
+            **params: Query string parameters to include in the request.
+
+        Returns:
+            The successful ``httpx.Response``.
+
+        Raises:
+            UnauthorizedError: HTTP 401.
+            ForbiddenError: HTTP 403.
+            NotFoundError: HTTP 404.
+            InvalidResponseError: Any other non-retriable 4xx.
+            ConnectionError: Network error or 5xx after all retries exhausted.
+
+        """
+        url = f"{self._host}{path}"
+        masked = _mask_token(self._token)
+        # Filter out params with falsy default values (empty str / 0) to keep
+        # URLs clean, but still allow explicit non-default values.
+        query: dict[str, str] = {k: str(v) for k, v in params.items() if v not in ("", 0)}
+
+        last_exc: Exception | None = None
+
+        for attempt in range(self._retry_count + 1):
+            if attempt > 0:
+                delay = backoff_delay(attempt, self._retry_delay)
+                logger.warning(
+                    "Retrying request attempt=%d/%d url=%s token=%s delay=%.2fs",
+                    attempt,
+                    self._retry_count,
+                    url,
+                    masked,
+                    delay,
+                )
+                time.sleep(delay)
+
+            logger.debug("GET %s attempt=%d token=%s", url, attempt + 1, masked)
+
+            try:
+                response = self._client.get(
+                    url,
+                    params=query or None,
+                    headers={"X-Service-Token": self._token},
+                )
+            except httpx.TransportError as exc:
+                logger.warning("Transport error url=%s: %s", url, exc)
+                last_exc = exc
+                continue  # retriable
+
+            if 400 <= response.status_code < 500:
+                # 4xx — raise immediately, do not retry
+                _raise_for_status(response)
+                # unreachable, but satisfies mypy
+                raise InvalidResponseError(f"HTTP {response.status_code}")
+
+            if response.status_code >= 500:
+                logger.warning(
+                    "Server error status=%d url=%s attempt=%d",
+                    response.status_code,
+                    url,
+                    attempt + 1,
+                )
+                last_exc = ConnectionError(f"HTTP {response.status_code} server error")
+                continue  # retriable
+
+            return response  # 2xx — success
+
+        raise ConnectionError(
+            f"Request failed after {self._retry_count + 1} attempt(s): {url}"
+        ) from last_exc
+
+    def close(self) -> None:
+        """Close the underlying ``httpx.Client`` if owned by this instance."""
+        if self._owns_client:
+            self._client.close()
+
+    def __enter__(self) -> Transport:
+        """Support use as a context manager."""
+        return self
+
+    def __exit__(self, *args: object) -> None:
+        """Close on context manager exit."""
+        self.close()

config_client/types.py

@@ -0,0 +1,62 @@
+"""Public types: ConfigInfo, ConfigChangeEvent, Format."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime
+from enum import Enum
+
+
+@dataclass(frozen=True)
+class ConfigInfo:
+    """Metadata about a configuration available to the service token.
+
+    Returned by :meth:`~config_client.ConfigClient.list`.
+
+    Attributes:
+        name: The configuration name (slug).
+        is_valid: Whether the configuration is currently valid/active.
+        valid_from: UTC datetime from which the configuration is effective.
+        updated_at: UTC datetime of the last update.
+
+    """
+
+    name: str
+    is_valid: bool
+    valid_from: datetime
+    updated_at: datetime
+
+
+@dataclass(frozen=True)
+class ConfigChangeEvent:
+    """Payload of a Server-Sent Event from the ``/watch`` endpoint.
+
+    Passed to callbacks registered via :meth:`~config_client.ConfigClient.watch`.
+
+    Attributes:
+        config_name: Name of the changed configuration.
+        version: New version number after the change.
+        changed_by: ID of the user or process that made the change.
+        timestamp: UTC datetime when the change was applied.
+
+    """
+
+    config_name: str
+    version: int
+    changed_by: int
+    timestamp: datetime
+
+
+class Format(str, Enum):
+    """Output format for :meth:`~config_client.ConfigClient.get_formatted`.
+
+    Attributes:
+        JSON: JSON format (``application/json``).
+        YAML: YAML format.
+        ENV: Key=value ``.env`` format.
+
+    """
+
+    JSON = "json"
+    YAML = "yaml"
+    ENV = "env"