toggletest 0.1.0__py3-none-any.whl

toggletest/__init__.py

@@ -0,0 +1,54 @@
+"""
+toggletest - ToggleTest Python SDK with WASM-based local evaluation
+
+This is the package entry point. It re-exports only the types and classes
+that SDK consumers need. Internal implementation details (WasmEngine,
+RulesStore, SseConnection, EventBuffer) are NOT exported.
+
+Usage:
+    from toggletest import ToggleTestClient
+    from toggletest import EvalContext, EvalResults, FlagResult, TestResult
+
+    client = ToggleTestClient(
+        api_key="tt_...",
+        base_url="http://localhost:3001",
+        environment="production",
+    )
+    client.start()
+
+    if client.is_enabled("dark-mode", user_id="user-123"):
+        ...
+
+    client.close()
+"""
+
+# -- Main client class --
+from .client import ToggleTestClient
+
+# -- Configuration and context types --
+from .types import ToggleTestConfig, EvalContext
+
+# -- Evaluation result types --
+from .types import FlagResult, TestResult, EvalResults
+
+# -- Event tracking types --
+from .types import SdkEvent
+
+# -- Listener types --
+from .types import RulesUpdateListener
+
+__all__ = [
+    # Client
+    "ToggleTestClient",
+    # Config / context
+    "ToggleTestConfig",
+    "EvalContext",
+    # Evaluation results
+    "FlagResult",
+    "TestResult",
+    "EvalResults",
+    # Events
+    "SdkEvent",
+    # Listeners
+    "RulesUpdateListener",
+]

toggletest/client.py

@@ -0,0 +1,520 @@
+"""
+client.py - Main ToggleTest SDK client with WASM-based local evaluation
+
+Architecture overview:
+  The ToggleTestClient is the primary public interface for the SDK. It
+  orchestrates four internal components:
+
+    1. WasmEngine     - Loads the WASM evaluator binary and runs evaluations
+                        entirely in-process (no network calls per evaluation).
+    2. RulesStore     - Caches the compiled rules JSON blob from the server,
+                        uses ETag-based conditional fetching for efficiency.
+    3. SseConnection  - Listens for ``rules_updated`` SSE events and triggers
+                        the RulesStore to re-fetch when rules change.
+    4. EventBuffer    - Batches analytics events and sends them periodically.
+
+  Lifecycle:
+    client = ToggleTestClient(api_key="tt_...", base_url="http://...")
+    client.start()              # Fetches WASM + rules, connects SSE
+    client.is_enabled("flag")   # Local evaluation (synchronous!)
+    client.track("conversion")  # Buffered event tracking
+    client.close()              # Disconnect SSE, flush events
+
+  The key insight is that after start() completes, ALL evaluation is local.
+  There are zero network calls in the hot path.  The only ongoing network
+  activity is:
+    - SSE connection for change notifications (lightweight, server-push)
+    - Periodic event flushes (batched, fire-and-forget)
+    - Occasional rules re-fetch when notified of changes
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, Callable, Dict, Optional
+
+import httpx
+
+from .event_buffer import EventBuffer
+from .rules_store import RulesStore
+from .sse import SseConnection
+from .types import (
+    EvalContext,
+    EvalResults,
+    FlagResult,
+    RulesUpdateListener,
+    SdkEvent,
+    TestResult,
+)
+from .wasm_engine import WasmEngine
+
+logger = logging.getLogger("toggletest")
+
+
+class ToggleTestClient:
+    """ToggleTest SDK client with WASM-based local evaluation.
+
+    All feature flag and A/B test evaluations happen locally via a WASM
+    engine after the initial setup completes.  The server is only contacted
+    for:
+      - Fetching the WASM binary (once, at startup)
+      - Fetching the rules JSON (at startup + on change notifications)
+      - SSE stream for real-time change notifications
+      - Batched analytics event submission
+
+    Constructor args (flat style for convenience):
+        api_key:     SDK API key, typically prefixed with "tt_".
+        base_url:    Base URL of the ToggleTest API.
+        environment: Optional environment identifier (e.g. "production").
+        on_ready:    Called once the SDK is fully initialized.
+        on_error:    Called when a non-fatal error occurs.
+    """
+
+    def __init__(
+        self,
+        *,
+        api_key: str,
+        base_url: str,
+        environment: Optional[str] = None,
+        on_ready: Optional[Callable[[], None]] = None,
+        on_error: Optional[Callable[[Exception], None]] = None,
+    ) -> None:
+        """Initialize the client.
+
+        No network calls are made in the constructor.  All I/O happens
+        in ``start()``.
+
+        Args:
+            api_key:     SDK API key sent as x-api-key header.
+            base_url:    Base URL of the ToggleTest API.
+            environment: Optional environment identifier.
+            on_ready:    Callback fired once WASM + rules are loaded.
+            on_error:    Callback fired on non-fatal errors (SSE, fetch).
+        """
+        self._api_key = api_key
+        self._base_url = base_url
+        self._environment = environment
+        self._on_ready = on_ready
+        self._on_error = on_error
+
+        # Warn if using HTTP (API key transmitted in the clear).
+        if self._base_url.startswith('http://') and 'localhost' not in self._base_url and '127.0.0.1' not in self._base_url:
+            import warnings
+            warnings.warn(
+                '[ToggleTest] WARNING: Using HTTP. API key will be transmitted insecurely. Use HTTPS in production.',
+                stacklevel=2,
+            )
+
+        # Shared HTTP client for all outbound requests (connection pooling).
+        self._http_client: Optional[httpx.Client] = None
+
+        # -- Internal components (initialized here, I/O deferred to start) --
+
+        # WASM evaluation engine. Loaded once, used for all evaluations.
+        self._engine = WasmEngine()
+
+        # Cached rules JSON with ETag-based conditional fetching.
+        self._rules_store = RulesStore(
+            base_url=base_url,
+            api_key=api_key,
+            environment=environment,
+        )
+
+        # SSE connection for real-time rules change notifications.
+        self._sse: Optional[SseConnection] = None
+
+        # Batched event buffer for analytics tracking.
+        self._event_buffer = EventBuffer(
+            base_url=base_url,
+            api_key=api_key,
+            environment=environment,
+        )
+
+        # Whether the client has completed initialization
+        # (WASM loaded + rules fetched).
+        self._ready = False
+
+    # ------------------------------------------------------------------
+    # Properties
+    # ------------------------------------------------------------------
+
+    @property
+    def ready(self) -> bool:
+        """Whether the SDK has completed initialization and is ready."""
+        return self._ready
+
+    # ------------------------------------------------------------------
+    # Lifecycle
+    # ------------------------------------------------------------------
+
+    def start(self) -> None:
+        """Initialize the SDK.
+
+        This method performs four steps in sequence:
+          1. Fetches the WASM evaluator binary from GET /sdk/evaluator.wasm
+          2. Loads the WASM binary into the wasmtime engine
+          3. Fetches the initial rules JSON from GET /sdk/rules
+          4. Starts the SSE connection for change notifications
+          5. Starts the event buffer flush timer
+
+        After this method returns, the SDK is fully operational and all
+        evaluation methods can be called synchronously.
+
+        Raises:
+            RuntimeError: If WASM loading fails.
+            httpx.HTTPError: If the initial rules fetch fails.
+        """
+        # Create the shared HTTP client with sensible timeouts.
+        self._http_client = httpx.Client(
+            timeout=httpx.Timeout(connect=10.0, read=30.0, write=10.0, pool=10.0)
+        )
+
+        # Pass the shared client to sub-components.
+        self._rules_store.set_http_client(self._http_client)
+        self._event_buffer.set_http_client(self._http_client)
+
+        # -- Step 1: Fetch the WASM evaluator binary --
+        wasm_bytes = self._fetch_wasm_binary()
+
+        # -- Step 2: Load and compile the WASM module via wasmtime --
+        self._engine.load(wasm_bytes)
+
+        # -- Step 3: Fetch the initial rules --
+        self._rules_store.fetch_rules()
+
+        # Mark as ready.  From this point, all evaluation is local.
+        self._ready = True
+
+        # -- Step 4: Connect SSE for real-time change notifications --
+        # SSE is started after we're ready so evaluation works even if
+        # SSE fails to connect.
+        self._sse = SseConnection(
+            base_url=self._base_url,
+            api_key=self._api_key,
+            environment=self._environment,
+            rules_store=self._rules_store,
+            on_error=self._on_error,
+        )
+        self._sse.connect()
+
+        # -- Step 5: Start the event buffer --
+        self._event_buffer.start()
+
+        # Notify the consumer that the SDK is ready.
+        if self._on_ready:
+            self._on_ready()
+
+    def close(self) -> None:
+        """Gracefully shut down the SDK.
+
+        Disconnects the SSE stream, flushes any remaining buffered events,
+        and releases resources.  After calling close(), the client should
+        not be used for further evaluations.
+        """
+        # Disconnect SSE first to stop triggering new rule fetches.
+        if self._sse is not None:
+            self._sse.close()
+            self._sse = None
+
+        # Flush remaining events to the server (best-effort).
+        self._event_buffer.stop()
+
+        # Close the shared HTTP client to release connection pool resources.
+        if self._http_client is not None:
+            self._http_client.close()
+            self._http_client = None
+
+        self._ready = False
+
+    # ------------------------------------------------------------------
+    # Evaluation methods (local, synchronous, zero network calls)
+    # ------------------------------------------------------------------
+
+    def is_enabled(
+        self,
+        flag_key: str,
+        *,
+        user_id: str,
+        attributes: Optional[Dict[str, Any]] = None,
+    ) -> bool:
+        """Check if a feature flag is enabled for the given user.
+
+        This is the most common evaluation method.  It evaluates the flag
+        and returns a simple boolean.  If the flag is not found in the
+        rules, it returns False (safe default).
+
+        Args:
+            flag_key:   The flag key to evaluate (e.g. "dark-mode").
+            user_id:    Unique identifier for the end-user.
+            attributes: Optional user attributes for targeting rules.
+
+        Returns:
+            True if the flag is enabled, False otherwise.
+
+        Raises:
+            RuntimeError: If the SDK is not ready.
+        """
+        result = self.evaluate_flag(
+            flag_key, user_id=user_id, attributes=attributes
+        )
+        # Coerce to boolean.  The flag value could be a boolean, string,
+        # or number depending on the flag type.
+        return bool(result.value)
+
+    def evaluate_flag(
+        self,
+        flag_key: str,
+        *,
+        user_id: str,
+        attributes: Optional[Dict[str, Any]] = None,
+    ) -> FlagResult:
+        """Evaluate a single feature flag and return the full result.
+
+        Uses the optimized single-flag WASM evaluation path when available,
+        avoiding the overhead of evaluating all flags.
+
+        Returns the flag value, the reason for the result (e.g.
+        "rule_match", "default", "disabled"), and optionally the rule ID
+        that matched.
+
+        Args:
+            flag_key:   The flag key to evaluate.
+            user_id:    Unique identifier for the end-user.
+            attributes: Optional user attributes for targeting rules.
+
+        Returns:
+            A FlagResult with value, reason, and optional rule_id.
+
+        Raises:
+            RuntimeError: If the SDK is not ready or WASM evaluation fails.
+        """
+        self._ensure_ready()
+
+        context = EvalContext(user_id=user_id, attributes=attributes or {})
+        return self._run_single_evaluation(flag_key, context)
+
+    def evaluate_all(
+        self,
+        *,
+        user_id: str,
+        attributes: Optional[Dict[str, Any]] = None,
+    ) -> EvalResults:
+        """Evaluate ALL flags and tests against the given context.
+
+        Useful for bootstrapping a client-side SDK or for debugging.
+        Returns the complete evaluation results from the WASM engine.
+
+        Args:
+            user_id:    Unique identifier for the end-user.
+            attributes: Optional user attributes for targeting rules.
+
+        Returns:
+            The full EvalResults (all flags + all tests).
+
+        Raises:
+            RuntimeError: If the SDK is not ready.
+        """
+        self._ensure_ready()
+
+        context = EvalContext(user_id=user_id, attributes=attributes or {})
+        return self._run_evaluation(context)
+
+    def get_variant(
+        self,
+        test_key: str,
+        *,
+        user_id: str,
+        attributes: Optional[Dict[str, Any]] = None,
+    ) -> TestResult:
+        """Get the variant assignment for an A/B test.
+
+        The WASM engine deterministically assigns users to variants based
+        on a hash of (user_id + test_key), so the same user always gets
+        the same variant without any server-side state.
+
+        Args:
+            test_key:   The A/B test key (e.g. "pricing-test").
+            user_id:    Unique identifier for the end-user.
+            attributes: Optional user attributes for targeting rules.
+
+        Returns:
+            A TestResult with variant name and bucket number.
+
+        Raises:
+            RuntimeError: If the SDK is not ready.
+        """
+        self._ensure_ready()
+
+        context = EvalContext(user_id=user_id, attributes=attributes or {})
+        results = self._run_evaluation(context)
+        test_result = results.tests.get(test_key)
+
+        # If the test is not in the rules, return a safe default.
+        if test_result is None:
+            return TestResult(variant="control", bucket=0)
+
+        return test_result
+
+    # ------------------------------------------------------------------
+    # Event tracking
+    # ------------------------------------------------------------------
+
+    def track(
+        self,
+        event_type: str,
+        *,
+        end_user_id: str,
+        test_key: Optional[str] = None,
+        flag_key: Optional[str] = None,
+        variant_name: Optional[str] = None,
+        evaluation_reason: Optional[str] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        """Track an analytics event.
+
+        Events are buffered and sent to the server in batches.  This method
+        returns immediately (non-blocking).
+
+        Common event types:
+          - "conversion"          - User completed a goal
+          - "flag_evaluation"     - A flag was evaluated
+          - "variant_assignment"  - User was assigned to a variant
+
+        Args:
+            event_type:        The type of event to track.
+            end_user_id:       The end-user this event is about.
+            test_key:          The A/B test key, if relevant.
+            flag_key:          The flag key, if relevant.
+            variant_name:      The variant name, if relevant.
+            evaluation_reason: The reason from the WASM engine, if relevant.
+            metadata:          Arbitrary metadata attached to the event.
+        """
+        self._event_buffer.push(
+            SdkEvent(
+                event_type=event_type,  # type: ignore[arg-type]
+                end_user_id=end_user_id,
+                test_key=test_key,
+                flag_key=flag_key,
+                variant_name=variant_name,
+                evaluation_reason=evaluation_reason,
+                metadata=metadata or {},
+            )
+        )
+
+    # ------------------------------------------------------------------
+    # Listener management
+    # ------------------------------------------------------------------
+
+    def on_rules_update(
+        self, listener: RulesUpdateListener
+    ) -> Callable[[], None]:
+        """Register a listener for rules updates.
+
+        The listener is called with the new version hash whenever the
+        rules are re-fetched from the server.  Useful for logging or
+        triggering re-evaluation of cached results.
+
+        Args:
+            listener: Callback receiving the new rules version hash.
+
+        Returns:
+            An unsubscribe function.
+        """
+        return self._rules_store.on_update(listener)
+
+    # ------------------------------------------------------------------
+    # Private helpers
+    # ------------------------------------------------------------------
+
+    def _fetch_wasm_binary(self) -> bytes:
+        """Fetch the WASM evaluator binary from the server.
+
+        Uses x-api-key header for authentication.
+
+        Returns:
+            The raw WASM bytes.
+
+        Raises:
+            httpx.HTTPStatusError: On non-2xx responses.
+            httpx.HTTPError:       On network errors.
+        """
+        headers: Dict[str, str] = {
+            "x-api-key": self._api_key,
+        }
+        if self._environment:
+            headers["x-environment"] = self._environment
+
+        client = self._http_client or httpx.Client(
+            timeout=httpx.Timeout(connect=10.0, read=30.0, write=10.0, pool=10.0)
+        )
+        resp = client.get(
+            f"{self._base_url}/sdk/evaluator.wasm",
+            headers=headers,
+            timeout=30.0,  # WASM binary may be large, allow more time.
+        )
+        resp.raise_for_status()
+        return resp.content
+
+    def _run_evaluation(self, context: EvalContext) -> EvalResults:
+        """Run the WASM evaluation with the cached rules and given context.
+
+        Encapsulates the interaction between RulesStore and WasmEngine.
+
+        Args:
+            context: The user context for evaluation.
+
+        Returns:
+            The full evaluation results.
+
+        Raises:
+            RuntimeError: If rules are not available.
+        """
+        rules_json = self._rules_store.get_rules_json()
+
+        if rules_json is None:
+            raise RuntimeError(
+                "Rules not available. Has start() been called?"
+            )
+
+        return self._engine.evaluate(rules_json, context)
+
+    def _run_single_evaluation(
+        self, flag_key: str, context: EvalContext
+    ) -> FlagResult:
+        """Run a single-flag WASM evaluation with the cached rules.
+
+        Uses ``WasmEngine.evaluate_single()`` which automatically selects
+        the best available WASM path (fast-path, one-shot, or fallback to
+        full evaluation).
+
+        Args:
+            flag_key: The flag key to evaluate.
+            context:  The user context for evaluation.
+
+        Returns:
+            A FlagResult with value, reason, and optional rule_id.
+
+        Raises:
+            RuntimeError: If rules are not available.
+        """
+        rules_json = self._rules_store.get_rules_json()
+
+        if rules_json is None:
+            raise RuntimeError(
+                "Rules not available. Has start() been called?"
+            )
+
+        return self._engine.evaluate_single(rules_json, flag_key, context)
+
+    def _ensure_ready(self) -> None:
+        """Guard that throws if the SDK has not been initialized.
+
+        Called at the top of every public evaluation method.
+
+        Raises:
+            RuntimeError: If start() has not been called or has not completed.
+        """
+        if not self._ready:
+            raise RuntimeError(
+                "ToggleTestClient is not ready. Call client.start() first."
+            )