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

config_client/__init__.py

@@ -0,0 +1,49 @@
+"""python-config-client — Python SDK for Config Service.
+
+This package provides a synchronous client for fetching, decrypting,
+and hot-reloading configurations from Config Service.
+
+Example usage::
+
+    from config_client import ConfigClient, Options
+
+    client = ConfigClient(Options(
+        host="https://config.example.com",
+        service_token="your-token",
+        encryption_key="your-hex-key",
+    ))
+    cfg = client.get("my-service", dict)
+"""
+
+from config_client.client import ConfigClient
+from config_client.errors import (
+    ConfigClientError,
+    ConnectionError,
+    DecryptionError,
+    ForbiddenError,
+    InvalidResponseError,
+    NotFoundError,
+    UnauthorizedError,
+    UnmarshalError,
+)
+from config_client.options import GetOptions, Options
+from config_client.snapshot import Snapshot
+from config_client.types import ConfigChangeEvent, ConfigInfo, Format
+
+__all__ = [
+    "ConfigClient",
+    "Options",
+    "GetOptions",
+    "ConfigInfo",
+    "ConfigChangeEvent",
+    "Format",
+    "Snapshot",
+    "ConfigClientError",
+    "UnauthorizedError",
+    "ForbiddenError",
+    "NotFoundError",
+    "DecryptionError",
+    "InvalidResponseError",
+    "ConnectionError",
+    "UnmarshalError",
+]

config_client/_sse.py

@@ -0,0 +1,101 @@
+"""Internal SSE reader — not part of the public API.
+
+This module is intentionally private (prefixed with ``_``).
+Do **not** import or re-export its contents from ``config_client/__init__.py``.
+"""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Generator
+from dataclasses import dataclass, field
+
+import httpx
+import httpx_sse
+
+logger = logging.getLogger("config_client")
+
+
+@dataclass
+class SSEEvent:
+    """A parsed Server-Sent Event received from the ``/watch`` endpoint.
+
+    Attributes:
+        event: The ``event:`` field value (e.g. ``"config_changed"``).
+            Defaults to ``"message"`` when absent in the stream.
+        data: The ``data:`` field value (raw string payload).
+        id: The ``id:`` field value. Empty string when absent.
+        retry: The ``retry:`` reconnection hint in milliseconds, or ``None``.
+
+    """
+
+    event: str = "message"
+    data: str = ""
+    id: str = ""
+    retry: int | None = field(default=None)
+
+
+def iter_sse_events(
+    client: httpx.Client,
+    url: str,
+    headers: dict[str, str],
+) -> Generator[SSEEvent, None, None]:
+    """Open an SSE stream and yield parsed :class:`SSEEvent` objects.
+
+    The generator is designed to be used by the watch layer, which is
+    responsible for reconnection and error handling.
+
+    The underlying ``httpx`` connection is kept open for the lifetime of
+    the generator. Callers should either exhaust the generator or call
+    ``close()`` on it (e.g. via a ``try/finally`` block or ``with``
+    statement) to release the connection.
+
+    Args:
+        client: An already-configured ``httpx.Client`` instance. The caller
+            owns its lifecycle; this function never closes it.
+        url: Fully-qualified URL of the SSE endpoint.
+        headers: Additional HTTP headers to include in the request.
+
+    Yields:
+        :class:`SSEEvent` for every valid event received from the stream.
+
+    Raises:
+        httpx.TransportError: On network-level failures (connection reset,
+            timeouts, etc.). The caller (watch layer) is responsible for
+            catching this and deciding whether to reconnect.
+        httpx.HTTPStatusError: When the server returns a non-2xx status on
+            the initial connection.
+
+    """
+    logger.debug("Opening SSE stream url=%s", url)
+
+    with httpx_sse.connect_sse(client, "GET", url, headers=headers) as event_source:
+        event_source.response.raise_for_status()
+
+        for raw in event_source.iter_sse():
+            try:
+                retry_ms: int | None = raw.retry if raw.retry is not None else None
+                event = SSEEvent(
+                    event=raw.event or "message",
+                    data=raw.data,
+                    id=raw.id or "",
+                    retry=retry_ms,
+                )
+            except Exception as exc:  # noqa: BLE001 — unexpected malformed event
+                logger.warning("Ignoring malformed SSE event: %s", exc)
+                continue
+
+            if not event.data:
+                # Keep-alive / comment lines — skip silently
+                logger.debug("SSE keep-alive received url=%s", url)
+                continue
+
+            logger.debug(
+                "SSE event received event=%s id=%s url=%s",
+                event.event,
+                event.id,
+                url,
+            )
+            yield event
+
+    logger.warning("SSE stream closed url=%s", url)

config_client/client.py

@@ -0,0 +1,520 @@
+"""ConfigClient — main entry point for the Config Service SDK."""
+
+from __future__ import annotations
+
+import dataclasses
+import json
+import logging
+import os
+import threading
+import typing
+from collections.abc import Callable
+from datetime import datetime, timezone
+from typing import TYPE_CHECKING, Any, TypeVar, cast
+
+from config_client.crypto import decrypt, parse_encryption_key
+from config_client.errors import ConfigClientError, UnmarshalError
+from config_client.options import GetOptions, Options
+from config_client.snapshot import Snapshot
+from config_client.transport import Transport, backoff_delay
+from config_client.types import ConfigChangeEvent, ConfigInfo, Format
+
+if TYPE_CHECKING:
+    pass  # nothing extra needed at runtime from type-only imports
+logger = logging.getLogger("config_client")
+
+T = TypeVar("T")
+
+_BASE_PATH = "/api/v1/service/configs"
+
+
+def _build_query(opts: GetOptions | None) -> dict[str, str | int]:
+    """Return non-default query parameters from *opts*."""
+    params: dict[str, str | int] = {}
+    if opts is None:
+        return params
+    if opts.environment:
+        params["environment"] = opts.environment
+    if opts.version != 0:
+        params["version"] = opts.version
+    return params
+
+
+def _deserialize(data: dict[str, Any], target_type: type[T]) -> T:
+    """Deserialize *data* dict into an instance of *target_type*.
+
+    Dispatch order:
+    1. ``dict`` — return as-is.
+    2. Pydantic ``BaseModel`` subclass — ``model_validate(data)``.
+    3. ``dataclass`` — recursive construction via :func:`_build_dataclass`.
+    4. Anything else — raise :exc:`~config_client.errors.UnmarshalError`.
+
+    Args:
+        data: Decoded JSON dict from the config payload.
+        target_type: The type to deserialize into.
+
+    Returns:
+        An instance of *target_type*.
+
+    Raises:
+        UnmarshalError: If deserialization fails for any reason.
+
+    """
+    # 1. dict passthrough
+    if target_type is dict:
+        return cast(T, data)
+
+    # 2. Pydantic v2
+    try:
+        import pydantic  # noqa: PLC0415
+
+        if isinstance(target_type, type) and issubclass(target_type, pydantic.BaseModel):
+            try:
+                return target_type.model_validate(data)
+            except pydantic.ValidationError as exc:
+                raise UnmarshalError(
+                    f"Pydantic validation failed for {target_type.__name__}: {exc}"
+                ) from exc
+    except ImportError:
+        pass
+
+    # 3. dataclass
+    if dataclasses.is_dataclass(target_type) and isinstance(target_type, type):
+        try:
+            return cast(T, _build_dataclass(target_type, data))
+        except (TypeError, KeyError, ValueError) as exc:
+            raise UnmarshalError(
+                f"Dataclass construction failed for {target_type.__name__}: {exc}"
+            ) from exc
+
+    raise UnmarshalError(
+        f"Unsupported target_type {target_type!r}. "
+        "Use dict, a dataclass, or a pydantic.BaseModel subclass."
+    )
+
+
+def _build_dataclass(cls: type, data: dict[str, Any]) -> Any:  # noqa: ANN401
+    """Recursively construct a dataclass from a nested dict.
+
+    Uses :func:`typing.get_type_hints` to resolve string annotations
+    (produced by ``from __future__ import annotations``) without ``eval``.
+
+    Args:
+        cls: A dataclass type.
+        data: Dict of field values (may contain nested dicts).
+
+    Returns:
+        An instance of *cls*.
+
+    """
+    try:
+        hints: dict[str, Any] = typing.get_type_hints(cls)
+    except Exception:  # noqa: BLE001  — graceful fallback for unresolvable hints
+        hints = {}
+
+    kwargs: dict[str, Any] = {}
+    for f in dataclasses.fields(cls):
+        value = data[f.name]
+        actual_type = hints.get(f.name)
+
+        if (
+            actual_type is not None
+            and isinstance(actual_type, type)
+            and dataclasses.is_dataclass(actual_type)
+            and isinstance(value, dict)
+        ):
+            kwargs[f.name] = _build_dataclass(actual_type, value)
+        else:
+            kwargs[f.name] = value
+    return cls(**kwargs)
+
+
+def _parse_config_info(raw: dict[str, Any]) -> ConfigInfo:
+    """Parse a single ConfigInfo dict from the list endpoint response.
+
+    Args:
+        raw: A dict with ``name``, ``is_valid``, ``valid_from``, ``updated_at`` keys.
+
+    Returns:
+        A :class:`~config_client.types.ConfigInfo` instance.
+
+    """
+    return ConfigInfo(
+        name=str(raw["name"]),
+        is_valid=bool(raw["is_valid"]),
+        valid_from=datetime.fromisoformat(str(raw["valid_from"])).replace(tzinfo=timezone.utc)
+        if datetime.fromisoformat(str(raw["valid_from"])).tzinfo is None
+        else datetime.fromisoformat(str(raw["valid_from"])),
+        updated_at=datetime.fromisoformat(str(raw["updated_at"])).replace(tzinfo=timezone.utc)
+        if datetime.fromisoformat(str(raw["updated_at"])).tzinfo is None
+        else datetime.fromisoformat(str(raw["updated_at"])),
+    )
+
+
+def _parse_change_event(data: str) -> ConfigChangeEvent | None:
+    """Parse a JSON SSE data payload into a :class:`ConfigChangeEvent`.
+
+    Returns ``None`` when the payload is invalid or missing required fields,
+    logging a warning so the caller can skip the event gracefully.
+
+    Args:
+        data: Raw ``data:`` field from an SSE event (JSON string).
+
+    Returns:
+        A :class:`ConfigChangeEvent` or ``None`` if parsing fails.
+
+    """
+    try:
+        raw = json.loads(data)
+        return ConfigChangeEvent(
+            config_name=str(raw["config_name"]),
+            version=int(raw["version"]),
+            changed_by=int(raw["changed_by"]),
+            timestamp=datetime.fromisoformat(str(raw["timestamp"])).replace(tzinfo=timezone.utc)
+            if datetime.fromisoformat(str(raw["timestamp"])).tzinfo is None
+            else datetime.fromisoformat(str(raw["timestamp"])),
+        )
+    except (KeyError, ValueError, TypeError) as exc:
+        logger.warning("Could not parse SSE change event data=%r: %s", data, exc)
+        return None
+
+
+class ConfigClient:
+    """Synchronous client for Config Service.
+
+    Fetches, decrypts, and deserializes service configurations. Supports
+    plain-dict, dataclass, and Pydantic v2 deserialization targets.
+
+    Example::
+
+        with ConfigClient(Options(
+            host="https://config.example.com",
+            service_token="tok",
+            encryption_key="aa" * 32,
+        )) as client:
+            cfg = client.get("my-service", AppConfig)
+
+    """
+
+    def __init__(self, opts: Options) -> None:
+        """Initialise the client with the given options.
+
+        Args:
+            opts: :class:`~config_client.options.Options` instance. Validation
+                happens inside ``Options.__post_init__``; any invalid value
+                raises :exc:`~config_client.errors.ConfigClientError` before
+                this constructor returns.
+
+        """
+        # Options validates itself; we just store what we need.
+        self._opts = opts
+        self._key: bytes = parse_encryption_key(opts.encryption_key)
+
+        self._transport = Transport(
+            host=opts.host,
+            service_token=opts.service_token,
+            request_timeout=opts.request_timeout,
+            retry_count=opts.retry_count,
+            retry_delay=opts.retry_delay,
+            http_client=opts.http_client,
+        )
+
+        # Threading event used to signal watch loops to stop.
+        self._stop_event: threading.Event = threading.Event()
+
+        logger.debug("ConfigClient initialised host=%s", opts.host)
+
+    # ------------------------------------------------------------------
+    # Constructors
+    # ------------------------------------------------------------------
+
+    @classmethod
+    def from_env(cls) -> ConfigClient:
+        """Create a :class:`ConfigClient` from environment variables.
+
+        Reads ``CONFIG_SERVICE_HOST``, ``CONFIG_SERVICE_TOKEN``, and
+        ``CONFIG_SERVICE_KEY`` from the process environment.
+
+        Returns:
+            A configured :class:`ConfigClient`.
+
+        Raises:
+            ConfigClientError: If any required environment variable is missing.
+
+        """
+        required = {
+            "host": "CONFIG_SERVICE_HOST",
+            "service_token": "CONFIG_SERVICE_TOKEN",
+            "encryption_key": "CONFIG_SERVICE_KEY",
+        }
+        values: dict[str, str] = {}
+        for field, var in required.items():
+            val = os.environ.get(var)
+            if not val:
+                raise ConfigClientError(f"Required environment variable {var!r} is not set")
+            values[field] = val
+
+        return cls(Options(**values))  # type: ignore[arg-type]
+
+    # ------------------------------------------------------------------
+    # Lifecycle
+    # ------------------------------------------------------------------
+
+    def close(self) -> None:
+        """Stop all active watch loops and close the HTTP transport."""
+        self._stop_event.set()
+        self._transport.close()
+        logger.debug("ConfigClient closed")
+
+    def __enter__(self) -> ConfigClient:
+        """Support use as a context manager."""
+        return self
+
+    def __exit__(self, *args: object) -> None:
+        """Close on context manager exit."""
+        self.close()
+
+    # ------------------------------------------------------------------
+    # Config retrieval
+    # ------------------------------------------------------------------
+
+    def get(
+        self,
+        config_name: str,
+        target_type: type[T],
+        opts: GetOptions | None = None,
+    ) -> T:
+        """Fetch, decrypt, and deserialize a configuration.
+
+        Args:
+            config_name: The configuration name (slug).
+            target_type: Deserialization target — ``dict``, a ``dataclass``
+                type, or a ``pydantic.BaseModel`` subclass.
+            opts: Optional per-request options (environment, version).
+
+        Returns:
+            An instance of *target_type*.
+
+        Raises:
+            UnauthorizedError: HTTP 401.
+            ForbiddenError: HTTP 403.
+            NotFoundError: HTTP 404.
+            ConnectionError: Network / 5xx after retries exhausted.
+            DecryptionError: AES-GCM decryption failed.
+            UnmarshalError: JSON→type deserialization failed.
+
+        """
+        path = f"{_BASE_PATH}/{config_name}"
+        params = _build_query(opts)
+        response = self._transport.get(path, **params)
+
+        plaintext = decrypt(response.content, self._key)
+        return _deserialize(json.loads(plaintext), target_type)
+
+    def get_raw(
+        self,
+        config_name: str,
+        opts: GetOptions | None = None,
+    ) -> dict[str, object]:
+        """Fetch and decrypt a configuration, returning a raw ``dict``.
+
+        Args:
+            config_name: The configuration name (slug).
+            opts: Optional per-request options.
+
+        Returns:
+            Decrypted JSON payload as a ``dict``.
+
+        """
+        return cast("dict[str, object]", self.get(config_name, dict, opts))
+
+    def get_bytes(
+        self,
+        config_name: str,
+        opts: GetOptions | None = None,
+    ) -> bytes:
+        """Fetch and decrypt a configuration, returning raw JSON bytes.
+
+        Args:
+            config_name: The configuration name (slug).
+            opts: Optional per-request options.
+
+        Returns:
+            Decrypted JSON as raw ``bytes`` (not parsed).
+
+        """
+        path = f"{_BASE_PATH}/{config_name}"
+        params = _build_query(opts)
+        response = self._transport.get(path, **params)
+        return decrypt(response.content, self._key)
+
+    def get_formatted(self, config_name: str, fmt: Format) -> bytes:
+        """Fetch a configuration in plaintext format (no decryption).
+
+        Uses the ``/formatted`` endpoint which returns plaintext JSON, YAML,
+        or env-file content directly.
+
+        Args:
+            config_name: The configuration name (slug).
+            fmt: Output format — :attr:`Format.JSON`, :attr:`Format.YAML`,
+                or :attr:`Format.ENV`.
+
+        Returns:
+            Raw bytes of the formatted configuration.
+
+        """
+        path = f"{_BASE_PATH}/{config_name}/formatted"
+        response = self._transport.get(path, format=fmt.value)
+        return response.content
+
+    def list(self) -> list[ConfigInfo]:
+        """Return metadata for all configurations accessible to this token.
+
+        Returns:
+            A list of :class:`~config_client.types.ConfigInfo` objects.
+
+        Raises:
+            UnauthorizedError: HTTP 401.
+            ForbiddenError: HTTP 403.
+            ConnectionError: Network / 5xx after retries exhausted.
+            InvalidResponseError: Unexpected response format.
+
+        """
+        response = self._transport.get(_BASE_PATH)
+        payload: list[dict[str, Any]] = response.json()
+        return [_parse_config_info(item) for item in payload]
+
+    # ------------------------------------------------------------------
+    # Watch & Hot-Reload
+    # ------------------------------------------------------------------
+
+    def watch(
+        self,
+        config_name: str,
+        callback: Callable[[ConfigChangeEvent], None],
+    ) -> None:
+        """Subscribe to SSE change events for a configuration.
+
+        Blocks the calling thread until :meth:`close` is called or
+        :exc:`KeyboardInterrupt` is raised. Automatically reconnects
+        after connection drops using exponential backoff.
+
+        Args:
+            config_name: The configuration name to watch.
+            callback: Invoked with a :class:`~config_client.types.ConfigChangeEvent`
+                on every change event received from the SSE stream.
+
+        """
+        from config_client._sse import iter_sse_events  # noqa: PLC0415
+
+        url = f"{self._opts.host.rstrip('/')}{_BASE_PATH}/{config_name}/watch"
+        headers = {"X-Service-Token": self._opts.service_token}
+        attempt = 0
+        max_reconnects = max(self._opts.retry_count, 1)
+
+        while not self._stop_event.is_set():
+            try:
+                for event in iter_sse_events(
+                    self._transport._client,  # noqa: SLF001
+                    url,
+                    headers,
+                ):
+                    if self._stop_event.is_set():
+                        return
+
+                    change_event = _parse_change_event(event.data)
+                    if change_event is None:
+                        continue
+
+                    try:
+                        callback(change_event)
+                    except Exception as cb_exc:  # noqa: BLE001
+                        logger.error(
+                            "watch callback raised an exception config=%s: %s",
+                            config_name,
+                            cb_exc,
+                        )
+
+                    if self._opts.on_change is not None:
+                        self._opts.on_change(config_name)
+
+                # Stream ended cleanly — reconnect
+                attempt = 0
+                logger.warning("SSE stream ended, reconnecting config=%s", config_name)
+
+            except KeyboardInterrupt:
+                logger.info("watch interrupted by user config=%s", config_name)
+                return
+
+            except Exception as exc:  # noqa: BLE001
+                if self._stop_event.is_set():
+                    return
+
+                logger.warning("SSE error config=%s attempt=%d: %s", config_name, attempt, exc)
+
+                if self._opts.on_error is not None:
+                    self._opts.on_error(exc)
+
+                attempt += 1
+                if attempt > max_reconnects:
+                    logger.error(
+                        "watch giving up after %d attempts config=%s",
+                        attempt,
+                        config_name,
+                    )
+                    return
+
+                delay = backoff_delay(attempt, self._opts.retry_delay)
+                logger.warning(
+                    "Reconnecting in %.2fs config=%s attempt=%d/%d",
+                    delay,
+                    config_name,
+                    attempt,
+                    max_reconnects,
+                )
+                self._stop_event.wait(timeout=delay)
+
+    def watch_and_decode(
+        self,
+        config_name: str,
+        target_type: type[T],
+        snapshot: Snapshot[T],
+        opts: GetOptions | None = None,
+    ) -> None:
+        """Watch for config changes and update *snapshot* on every change.
+
+        Internally calls :meth:`watch` with a callback that fetches the
+        latest configuration via :meth:`get` and stores it in *snapshot*.
+        Errors from :meth:`get` are forwarded to ``Options.on_error`` and
+        do **not** stop the watch loop.
+
+        Blocks the calling thread. Recommended usage is inside a daemon
+        ``threading.Thread``.
+
+        Args:
+            config_name: The configuration name to watch.
+            target_type: Deserialization target type for :meth:`get`.
+            snapshot: Thread-safe container to update on each change.
+            opts: Optional per-request options passed to :meth:`get`.
+
+        """
+
+        def _on_change(event: ConfigChangeEvent) -> None:  # noqa: ARG001
+            try:
+                new_value = self.get(config_name, target_type, opts)
+                snapshot.store(new_value)
+                logger.debug(
+                    "Snapshot updated config=%s version=%s",
+                    config_name,
+                    event.version,
+                )
+            except Exception as exc:  # noqa: BLE001
+                logger.error(
+                    "watch_and_decode get() failed config=%s: %s",
+                    config_name,
+                    exc,
+                )
+                if self._opts.on_error is not None:
+                    self._opts.on_error(exc)
+
+        self.watch(config_name, _on_change)