toggletest 0.1.0__py3-none-any.whl

toggletest/sse.py

@@ -0,0 +1,217 @@
+"""
+sse.py - Simplified SSE connection for version change notifications
+
+Architecture overview:
+  In the old SDK, the SSE stream carried the full flag/test data (init events,
+  individual flag_updated/flag_deleted events, etc).  The client had to maintain
+  an in-memory store that mirrored the server state.
+
+  In the new WASM-based architecture, evaluation is done locally using a
+  compiled rules JSON blob.  The SSE stream is now drastically simpler:
+    - It only sends ``rules_updated`` events containing a version hash.
+    - When the SDK receives a version hash that differs from its cached ETag,
+      it re-fetches the rules blob via the RulesStore.
+
+  This simplification means the SSE stream is just a lightweight notification
+  channel, not a data transport.  If SSE disconnects, the SDK continues to
+  evaluate using the last-fetched rules (it is never in a "no data" state
+  after initial startup).
+
+Reconnection:
+  Uses exponential backoff (1s -> 2s -> 4s -> ... -> 30s max) on connection
+  failures, consistent with the TypeScript SDK.
+
+Threading:
+  The SSE loop runs on a dedicated daemon thread so it does not block the
+  calling thread.  The ``close()`` method signals the thread to stop and
+  waits briefly for it to exit.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import threading
+import time
+from typing import Callable, Dict, Optional
+
+import httpx
+from httpx_sse import connect_sse
+
+from .rules_store import RulesStore
+
+logger = logging.getLogger("toggletest")
+
+# Maximum time between reconnection attempts.
+MAX_BACKOFF = 30.0
+
+# Starting backoff duration after first failure.
+INITIAL_BACKOFF = 1.0
+
+
+class SseConnection:
+    """SSE client that listens for ``rules_updated`` events.
+
+    When a version notification arrives, it tells the RulesStore to check
+    for new rules.  All other event types are ignored.
+    """
+
+    def __init__(
+        self,
+        *,
+        base_url: str,
+        api_key: str,
+        environment: Optional[str] = None,
+        rules_store: RulesStore,
+        on_error: Optional[Callable[[Exception], None]] = None,
+    ) -> None:
+        """Initialize the SSE connection (does not connect yet).
+
+        Args:
+            base_url:    Base URL of the ToggleTest API.
+            api_key:     SDK API key sent as x-api-key header.
+            environment: Optional environment identifier.
+            rules_store: The RulesStore to notify when rules change.
+            on_error:    Optional callback for non-fatal connection errors.
+        """
+        self._base_url = base_url
+        self._api_key = api_key
+        self._environment = environment
+        self._rules_store = rules_store
+        self._on_error = on_error
+
+        # Whether the connection loop should keep running.
+        self._running = False
+
+        # The background thread running the SSE loop.
+        self._thread: Optional[threading.Thread] = None
+
+    # ------------------------------------------------------------------
+    # Header helpers
+    # ------------------------------------------------------------------
+
+    def _build_headers(self) -> Dict[str, str]:
+        """Build headers for the SSE connection request.
+
+        Uses x-api-key (not Bearer token) to authenticate.
+        """
+        headers: Dict[str, str] = {
+            "x-api-key": self._api_key,
+            "Accept": "text/event-stream",
+        }
+        if self._environment:
+            headers["x-environment"] = self._environment
+        return headers
+
+    # ------------------------------------------------------------------
+    # Lifecycle
+    # ------------------------------------------------------------------
+
+    def connect(self) -> None:
+        """Start the SSE connection loop on a background daemon thread.
+
+        Returns immediately.  The thread automatically reconnects on failure
+        with exponential backoff.
+        """
+        self._running = True
+        self._thread = threading.Thread(target=self._run, daemon=True)
+        self._thread.start()
+
+    def close(self) -> None:
+        """Close the SSE connection and stop the reconnection loop.
+
+        Safe to call multiple times.  Blocks up to 5 seconds waiting for
+        the background thread to exit.
+        """
+        self._running = False
+        if self._thread is not None:
+            self._thread.join(timeout=5.0)
+            self._thread = None
+
+    # ------------------------------------------------------------------
+    # Internal: connection loop with reconnection
+    # ------------------------------------------------------------------
+
+    def _run(self) -> None:
+        """Main reconnection loop. Runs on the background thread.
+
+        Keeps trying to connect as long as ``_running`` is True.
+        On successful connection, reads events until the stream ends or errors.
+        On failure, waits with exponential backoff before retrying.
+        """
+        backoff = INITIAL_BACKOFF
+
+        while self._running:
+            try:
+                # httpx_sse provides a context manager that opens an SSE
+                # connection and yields an event source iterator.
+                with httpx.Client(timeout=httpx.Timeout(connect=10.0, read=120.0, write=10.0, pool=10.0)) as client:
+                    with connect_sse(
+                        client,
+                        "GET",
+                        f"{self._base_url}/sdk/stream",
+                        headers=self._build_headers(),
+                    ) as event_source:
+                        # Reset backoff on successful connection.
+                        backoff = INITIAL_BACKOFF
+
+                        for sse in event_source.iter_sse():
+                            if not self._running:
+                                return
+                            self._handle_event(sse.event, sse.data)
+            except Exception as exc:
+                # If we were intentionally closed, exit cleanly.
+                if not self._running:
+                    return
+
+                # Report the error via callback (non-fatal).
+                if self._on_error:
+                    self._on_error(exc)
+                logger.debug("SSE connection error: %s", exc)
+
+                # Wait before reconnecting with exponential backoff.
+                time.sleep(backoff)
+                backoff = min(backoff * 2, MAX_BACKOFF)
+
+    # ------------------------------------------------------------------
+    # Internal: event handling
+    # ------------------------------------------------------------------
+
+    def _handle_event(self, event_type: str, data: str) -> None:
+        """Handle a parsed SSE event.
+
+        In the new architecture, the only event type we care about is
+        ``rules_updated``, which carries a version hash.  We forward it
+        to the RulesStore, which will re-fetch if the version has changed.
+
+        All other event types (heartbeats, future event types) are silently
+        ignored.
+
+        Args:
+            event_type: The SSE event name (e.g. "rules_updated").
+            data:       The raw SSE data payload (JSON string).
+        """
+        if event_type != "rules_updated":
+            # Ignore unknown event types.
+            return
+
+        try:
+            parsed = json.loads(data)
+        except json.JSONDecodeError:
+            # Ignore malformed JSON in SSE data. This is non-fatal.
+            logger.debug("Malformed SSE data for rules_updated event: %s", data)
+            return
+
+        version = parsed.get("version")
+        if not version:
+            return
+
+        try:
+            # Tell the RulesStore to re-fetch if the version changed.
+            self._rules_store.on_version_notification(version)
+        except Exception as exc:
+            # Re-fetch failure is non-fatal.  The SDK continues evaluating
+            # with the last-known rules.
+            if self._on_error:
+                self._on_error(exc)
+            logger.debug("Failed to re-fetch rules after SSE notification: %s", exc)

toggletest/types.py

@@ -0,0 +1,156 @@
+"""
+types.py - Type definitions for the ToggleTest WASM-based SDK
+
+This SDK evaluates feature flags and A/B tests locally using a WASM engine.
+The server provides a compiled rules JSON blob and a WASM evaluator binary.
+All flag/test evaluation happens client-side with zero network latency.
+
+Mirrors the TypeScript SDK's type definitions so both SDKs share the same
+data contract with the server and WASM evaluator.
+"""
+
+from dataclasses import dataclass, field
+from typing import Any, Callable, Dict, Literal, Optional
+
+
+# ---------------------------------------------------------------------------
+# Client configuration
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class ToggleTestConfig:
+    """Configuration for the ToggleTest client.
+
+    Attributes:
+        api_key:     SDK API key, typically prefixed with "tt_".
+                     Sent as the x-api-key header on all requests.
+        base_url:    Base URL of the ToggleTest API
+                     (e.g. "http://localhost:3001").
+        environment: Optional environment identifier (e.g. "production").
+                     Sent as x-environment header so the server scopes
+                     rules to the correct environment.
+        on_ready:    Called once the WASM engine is loaded and rules are fetched.
+        on_error:    Called when a non-fatal error occurs (SSE disconnect, etc).
+    """
+
+    api_key: str
+    base_url: str
+    environment: Optional[str] = None
+    on_ready: Optional[Callable[[], None]] = None
+    on_error: Optional[Callable[[Exception], None]] = None
+
+
+# ---------------------------------------------------------------------------
+# WASM evaluation context
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class EvalContext:
+    """Context passed into every evaluation call.
+
+    The WASM engine uses this to match targeting rules and compute
+    bucket assignments.
+
+    Attributes:
+        user_id:    Unique identifier for the end-user being evaluated.
+        attributes: Arbitrary user/request attributes used in targeting rules.
+                    Example: {"plan": "pro", "country": "US", "beta": True}
+    """
+
+    user_id: str
+    attributes: Optional[Dict[str, Any]] = field(default_factory=dict)
+
+
+# ---------------------------------------------------------------------------
+# WASM evaluation results
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class FlagResult:
+    """Result of evaluating a single feature flag.
+
+    Attributes:
+        value:   The evaluated value of the flag (bool, str, number, or dict).
+        reason:  Human-readable reason for the result
+                 (e.g. "rule_match", "default", "disabled", "not_found").
+        rule_id: The ID of the rule that matched, if any.
+    """
+
+    value: Any
+    reason: str
+    rule_id: Optional[str] = None
+
+
+@dataclass
+class TestResult:
+    """Result of evaluating a single A/B test assignment.
+
+    Attributes:
+        variant: The variant the user was assigned to
+                 (e.g. "control", "variant_a").
+        bucket:  The deterministic bucket value (0-9999) computed from
+                 user_id + test key. Ensures consistent assignment
+                 without server-side state.
+    """
+
+    variant: str
+    bucket: int
+
+
+@dataclass
+class EvalResults:
+    """Full evaluation result returned by the WASM engine.
+
+    Contains every flag and every test evaluated against the provided
+    context.
+
+    Attributes:
+        flags: Map of flag key -> evaluation result.
+        tests: Map of test key -> variant assignment.
+    """
+
+    flags: Dict[str, FlagResult]
+    tests: Dict[str, TestResult]
+
+
+# ---------------------------------------------------------------------------
+# Listener type alias
+# ---------------------------------------------------------------------------
+
+# Called whenever rules are updated. Receives the new version hash (ETag).
+RulesUpdateListener = Callable[[str], None]
+
+
+# ---------------------------------------------------------------------------
+# Event tracking types
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class SdkEvent:
+    """An analytics event sent to the ToggleTest backend in batches.
+
+    Includes an evaluation_reason field so the backend knows *why* the
+    event occurred (e.g. which rule matched, or which variant was assigned).
+
+    Attributes:
+        event_type:        The kind of event being tracked.
+        end_user_id:       The end-user this event is about.
+        flag_key:          The flag key relevant to this event, if any.
+        test_key:          The A/B test key relevant to this event, if any.
+        variant_name:      The variant name for assignment/conversion events.
+        evaluation_reason: The reason the evaluation produced this result.
+                           Comes directly from the WASM engine.
+        metadata:          Arbitrary metadata attached to the event.
+    """
+
+    event_type: Literal["flag_evaluation", "variant_assignment", "conversion"]
+    end_user_id: str
+    flag_key: Optional[str] = None
+    test_key: Optional[str] = None
+    variant_name: Optional[str] = None
+    evaluation_reason: Optional[str] = None
+    metadata: Dict[str, Any] = field(default_factory=dict)