toggletest 0.1.0__py3-none-any.whl

toggletest/event_buffer.py

@@ -0,0 +1,244 @@
+"""
+event_buffer.py - Batched event tracking with evaluation_reason support
+
+Architecture overview:
+  The event buffer collects analytics events (flag evaluations, variant
+  assignments, conversions) and sends them to the server in batches.
+
+  Key changes from the old SDK:
+    - Events now include an ``evaluation_reason`` field that comes from the
+      WASM evaluation result.  This lets the backend know *why* a flag was
+      enabled or which rule matched, enabling richer analytics.
+    - Auth uses x-api-key header instead of Bearer token.
+    - Optional x-environment header for multi-environment support.
+
+  Batching strategy:
+    - Events are flushed every N seconds (default: 10s).
+    - If the buffer reaches a max size (default: 100), it flushes immediately.
+    - On flush failure (network error or non-2xx), events are re-queued for
+      retry on the next flush cycle.
+    - On close(), a final flush is attempted to avoid data loss.
+
+Thread-safety:
+  The event list is guarded by a ``threading.Lock``.  The periodic flush
+  runs on a background daemon timer thread.
+"""
+
+from __future__ import annotations
+
+import logging
+import threading
+from dataclasses import asdict
+from typing import Dict, List, Optional
+
+import httpx
+
+from .types import SdkEvent
+
+logger = logging.getLogger("toggletest")
+
+# Default interval between automatic flushes (seconds).
+DEFAULT_FLUSH_INTERVAL = 10.0
+
+# Default maximum number of events before an immediate flush is triggered.
+DEFAULT_MAX_BATCH_SIZE = 100
+
+
+class EventBuffer:
+    """Batched event buffer that periodically flushes to the server.
+
+    Events are accumulated in-memory and sent via POST /sdk/events.
+    The buffer handles retries by re-queuing failed batches.
+    """
+
+    MAX_BUFFER_SIZE = 10000
+
+    def __init__(
+        self,
+        *,
+        base_url: str,
+        api_key: str,
+        environment: Optional[str] = None,
+        flush_interval: float = DEFAULT_FLUSH_INTERVAL,
+        max_batch_size: int = DEFAULT_MAX_BATCH_SIZE,
+    ) -> None:
+        """Initialize the event buffer.
+
+        No network calls are made in the constructor. The flush timer is
+        started by ``start()``.
+
+        Args:
+            base_url:       Base URL of the ToggleTest API.
+            api_key:        SDK API key sent as x-api-key header.
+            environment:    Optional environment identifier.
+            flush_interval: Seconds between automatic flushes.
+            max_batch_size: Max events before triggering an immediate flush.
+        """
+        self._base_url = base_url
+        self._api_key = api_key
+        self._environment = environment
+        self._flush_interval = flush_interval
+        self._max_batch_size = max_batch_size
+
+        # -- Mutable state (guarded by _lock) --
+        self._lock = threading.Lock()
+        self._events: List[SdkEvent] = []
+        self._drop_warned = False
+
+        # -- Shared HTTP client (set via set_http_client) --
+        self._http_client: Optional[httpx.Client] = None
+
+        # -- Timer state --
+        self._timer: Optional[threading.Timer] = None
+        self._running = False
+
+    def set_http_client(self, client: httpx.Client) -> None:
+        """Assign a shared httpx.Client for connection reuse."""
+        self._http_client = client
+
+    # ------------------------------------------------------------------
+    # Header helpers
+    # ------------------------------------------------------------------
+
+    def _build_headers(self) -> Dict[str, str]:
+        """Build the common headers used for event submission.
+
+        Uses x-api-key for auth (not Bearer token) to match the new SDK
+        protocol.
+        """
+        headers: Dict[str, str] = {
+            "Content-Type": "application/json",
+            "x-api-key": self._api_key,
+        }
+        if self._environment:
+            headers["x-environment"] = self._environment
+        return headers
+
+    # ------------------------------------------------------------------
+    # Lifecycle
+    # ------------------------------------------------------------------
+
+    def start(self) -> None:
+        """Start the periodic flush timer.
+
+        Safe to call multiple times (no-op if already running).
+        """
+        self._running = True
+        self._schedule_flush()
+
+    def stop(self) -> None:
+        """Stop the periodic flush timer and perform a final flush.
+
+        Called during ``client.close()`` to avoid losing buffered events.
+        The final flush is best-effort: if it fails, events are lost
+        (acceptable on shutdown).
+        """
+        self._running = False
+        if self._timer is not None:
+            self._timer.cancel()
+            self._timer = None
+
+        # Final flush attempt.
+        self.flush()
+
+    # ------------------------------------------------------------------
+    # Event ingestion
+    # ------------------------------------------------------------------
+
+    def push(self, event: SdkEvent) -> None:
+        """Add an event to the buffer.
+
+        If the buffer reaches ``max_batch_size``, an immediate flush is
+        triggered.  If the buffer exceeds ``MAX_BUFFER_SIZE``, the oldest
+        events are dropped.
+
+        Args:
+            event: The analytics event to buffer.
+        """
+        with self._lock:
+            while len(self._events) >= self.MAX_BUFFER_SIZE:
+                self._events.pop(0)  # drop oldest
+                if not self._drop_warned:
+                    logger.warning('[ToggleTest] Event buffer full. Dropping oldest events.')
+                    self._drop_warned = True
+
+            self._events.append(event)
+            if len(self._events) >= self._max_batch_size:
+                self._do_flush()
+
+    # ------------------------------------------------------------------
+    # Flushing
+    # ------------------------------------------------------------------
+
+    def flush(self) -> None:
+        """Flush all buffered events to the server.
+
+        Thread-safe.  Acquires the lock, drains the buffer, and sends
+        events in a single POST request.  On failure, events are re-queued
+        at the front of the buffer for retry on the next flush cycle.
+        """
+        with self._lock:
+            self._do_flush()
+
+    def _do_flush(self) -> None:
+        """Internal flush implementation.  Caller must hold ``_lock``.
+
+        Atomically drains the current buffer, sends the batch to the
+        server, and re-queues on failure.
+        """
+        if not self._events:
+            return
+
+        # Drain the buffer.
+        batch = list(self._events)
+        self._events.clear()
+
+        # Build the payload, stripping None values for cleaner JSON.
+        payload = {
+            "events": [
+                {k: v for k, v in asdict(e).items() if v is not None}
+                for e in batch
+            ]
+        }
+
+        try:
+            client = self._http_client or httpx.Client(timeout=10.0)
+            resp = client.post(
+                f"{self._base_url}/sdk/events",
+                json=payload,
+                headers=self._build_headers(),
+                timeout=10.0,
+            )
+            if resp.status_code == 429:
+                # Evaluation limit reached — drop events, don't retry.
+                # The WASM engine still evaluates flags locally; only tracking is affected.
+                logger.warning("Evaluation limit reached. Events dropped.")
+            elif resp.status_code != 200:
+                # Other server error — re-queue for retry.
+                self._events = batch + self._events
+        except Exception:
+            # Network error (e.g. offline).  Re-queue for retry.
+            logger.debug("Failed to flush events, re-queueing")
+            self._events = batch + self._events
+
+    # ------------------------------------------------------------------
+    # Timer management
+    # ------------------------------------------------------------------
+
+    def _schedule_flush(self) -> None:
+        """Schedule the next periodic flush.
+
+        Uses ``threading.Timer`` so the flush runs on a separate daemon
+        thread after the configured interval.
+        """
+        if not self._running:
+            return
+
+        self._timer = threading.Timer(self._flush_interval, self._timer_flush)
+        self._timer.daemon = True
+        self._timer.start()
+
+    def _timer_flush(self) -> None:
+        """Called by the timer thread. Flushes and reschedules."""
+        self.flush()
+        self._schedule_flush()

toggletest/rules_store.py

@@ -0,0 +1,257 @@
+"""
+rules_store.py - Thread-safe rules cache with ETag-based conditional fetching
+
+Architecture overview:
+  The ToggleTest server compiles all flag/test configuration into a single
+  JSON document (the "rules blob") served at GET /sdk/rules.  This blob is
+  the sole input to the WASM evaluator along with the user context.
+
+  The rules store:
+    1. Fetches the rules blob on startup.
+    2. Caches the raw JSON string and its ETag (version hash).
+    3. Re-fetches when notified by the SSE stream that a new version is
+       available, using If-None-Match to avoid downloading unchanged data.
+    4. Notifies registered listeners whenever the rules actually change.
+
+  This design means the SDK always has a local copy of the rules for
+  zero-latency evaluation, and only re-downloads when something changed.
+
+Thread-safety:
+  All mutable state is guarded by a ``threading.RLock``.  An RLock (rather
+  than a plain Lock) is used because listener callbacks may call back into
+  the store (e.g. ``get_rules_json``) from the same thread.
+"""
+
+from __future__ import annotations
+
+import logging
+import threading
+from typing import Callable, Dict, List, Optional
+
+import httpx
+
+from .types import RulesUpdateListener
+
+logger = logging.getLogger("toggletest")
+
+
+class RulesStore:
+    """Cached rules JSON with ETag-based conditional fetching.
+
+    Public API:
+      - ``fetch_rules()``              -- fetch (or re-fetch) rules from server
+      - ``on_version_notification(v)`` -- called by SSE when rules change
+      - ``get_rules_json()``           -- get the cached rules JSON string
+      - ``get_version()``              -- get the cached ETag / version hash
+      - ``has_rules``                  -- whether rules have been fetched once
+      - ``on_update(listener)``        -- register a listener, returns unsub fn
+    """
+
+    def __init__(
+        self,
+        *,
+        base_url: str,
+        api_key: str,
+        environment: Optional[str] = None,
+    ) -> None:
+        """Initialize the rules store.
+
+        No network calls are made in the constructor. All I/O happens in
+        ``fetch_rules()``.
+
+        Args:
+            base_url:    Base URL of the ToggleTest API.
+            api_key:     SDK API key sent as x-api-key header.
+            environment: Optional environment identifier sent as x-environment.
+        """
+        self._base_url = base_url
+        self._api_key = api_key
+        self._environment = environment
+
+        # -- Mutable state (guarded by _lock) --
+        self._lock = threading.RLock()
+        self._rules_json: Optional[str] = None
+        self._etag: Optional[str] = None
+        self._listeners: List[RulesUpdateListener] = []
+
+        # -- Shared HTTP client (set via set_http_client) --
+        self._http_client: Optional[httpx.Client] = None
+
+    def set_http_client(self, client: httpx.Client) -> None:
+        """Assign a shared httpx.Client for connection reuse."""
+        self._http_client = client
+
+    # ------------------------------------------------------------------
+    # Header helpers
+    # ------------------------------------------------------------------
+
+    def _build_headers(
+        self, extra: Optional[Dict[str, str]] = None
+    ) -> Dict[str, str]:
+        """Build the common headers used for all API requests.
+
+        Uses x-api-key for auth (not Bearer token) to match the new SDK
+        protocol.
+
+        Args:
+            extra: Additional headers to merge in (e.g. If-None-Match).
+
+        Returns:
+            A dict of HTTP headers.
+        """
+        headers: Dict[str, str] = {
+            "x-api-key": self._api_key,
+        }
+        if self._environment:
+            headers["x-environment"] = self._environment
+        if extra:
+            headers.update(extra)
+        return headers
+
+    # ------------------------------------------------------------------
+    # Fetching
+    # ------------------------------------------------------------------
+
+    def fetch_rules(self) -> bool:
+        """Fetch the latest rules from the server.
+
+        On first call, performs an unconditional GET.
+        On subsequent calls, sends If-None-Match with the cached ETag.
+        If the server responds with 304 Not Modified, the cached rules
+        are kept and this method returns False.
+
+        Returns:
+            True if rules were updated, False if they were already current.
+
+        Raises:
+            httpx.HTTPStatusError: On non-2xx/304 responses.
+            httpx.HTTPError:       On network errors.
+        """
+        with self._lock:
+            current_etag = self._etag
+
+        # Build headers, adding If-None-Match for conditional fetch.
+        extra_headers: Optional[Dict[str, str]] = None
+        if current_etag:
+            extra_headers = {"If-None-Match": current_etag}
+
+        headers = self._build_headers(extra_headers)
+
+        client = self._http_client or httpx.Client(timeout=10.0)
+        resp = client.get(
+            f"{self._base_url}/sdk/rules",
+            headers=headers,
+            timeout=10.0,
+        )
+
+        # 304 Not Modified -- our cached copy is still current.
+        if resp.status_code == 304:
+            return False
+
+        # Raise on unexpected status codes (4xx, 5xx).
+        resp.raise_for_status()
+
+        # Store the new rules and ETag under the lock.
+        new_rules_json = resp.text
+        new_etag = resp.headers.get("ETag") or resp.headers.get("etag")
+
+        with self._lock:
+            # Only notify listeners if the rules content actually changed.
+            changed = new_rules_json != self._rules_json
+            self._rules_json = new_rules_json
+            self._etag = new_etag
+
+        if changed and new_etag:
+            self._notify_listeners(new_etag)
+
+        return changed
+
+    def on_version_notification(self, version: str) -> None:
+        """Called when the SSE stream receives a ``rules_updated`` event.
+
+        Compares the incoming version hash against the cached ETag.
+        If they differ, re-fetches the rules.
+
+        Args:
+            version: The version hash from the SSE event payload.
+        """
+        with self._lock:
+            current_etag = self._etag
+
+        # If the version matches what we have, skip the fetch entirely.
+        if current_etag == version:
+            return
+
+        # Re-fetch rules. Errors propagate to the caller (SSE handler).
+        self.fetch_rules()
+
+    # ------------------------------------------------------------------
+    # Accessors (thread-safe reads)
+    # ------------------------------------------------------------------
+
+    def get_rules_json(self) -> Optional[str]:
+        """Get the cached rules JSON string, or None if not yet fetched."""
+        with self._lock:
+            return self._rules_json
+
+    def get_version(self) -> Optional[str]:
+        """Get the current version hash (ETag) of the cached rules."""
+        with self._lock:
+            return self._etag
+
+    @property
+    def has_rules(self) -> bool:
+        """Whether rules have been fetched at least once."""
+        with self._lock:
+            return self._rules_json is not None
+
+    # ------------------------------------------------------------------
+    # Listener management
+    # ------------------------------------------------------------------
+
+    def on_update(self, listener: RulesUpdateListener) -> Callable[[], None]:
+        """Register a listener that is called whenever rules are updated.
+
+        The listener receives the new version hash (ETag string) as its
+        sole argument.
+
+        Args:
+            listener: Callback function accepting a version string.
+
+        Returns:
+            An unsubscribe function. Call it to remove the listener.
+        """
+        with self._lock:
+            self._listeners.append(listener)
+
+        def unsubscribe() -> None:
+            with self._lock:
+                try:
+                    self._listeners.remove(listener)
+                except ValueError:
+                    pass  # Already removed, nothing to do.
+
+        return unsubscribe
+
+    def _notify_listeners(self, version: str) -> None:
+        """Notify all registered listeners of a rules update.
+
+        Swallows individual listener errors to prevent one bad listener
+        from breaking the notification chain.
+
+        Args:
+            version: The new rules version hash (ETag).
+        """
+        with self._lock:
+            # Copy the list so listeners can unsubscribe during notification
+            # without causing a ConcurrentModificationError.
+            listeners_snapshot = list(self._listeners)
+
+        for listener in listeners_snapshot:
+            try:
+                listener(version)
+            except Exception:
+                # Swallow the error. Log for debugging but don't propagate.
+                logger.debug(
+                    "Rules update listener raised an exception", exc_info=True
+                )