toggletest 0.1.0__py3-none-any.whl

toggletest/wasm_engine.py

@@ -0,0 +1,673 @@
+"""
+wasm_engine.py - WASM evaluation engine for ToggleTest (wasmtime-py)
+
+Architecture overview:
+  1. The WASM binary (evaluator.wasm) is fetched once from the server on start.
+  2. The engine exposes an ``evaluate()`` method that writes the rules JSON and
+     evaluation context into WASM linear memory, calls the evaluator, and
+     reads the result back out.
+  3. Memory management uses the WASM module's own allocator (``tt_alloc`` /
+     ``tt_dealloc``) so there is no need for wasm-bindgen or any glue code.
+
+Two evaluation paths are supported for **all flags**:
+  - **One-shot** (``tt_evaluate``): Parses rules + context, evaluates. Always available.
+  - **Fast path** (``tt_set_rules`` + ``tt_evaluate_ctx``): Pre-sorts targeting rules
+    and pre-computes topological order once per instance, then evaluates with
+    context-only parsing. Used automatically when the WASM binary includes the
+    newer exports. Even though Python creates a fresh instance per call, the
+    fast path avoids per-flag clone+sort overhead within each evaluation.
+
+Two evaluation paths are supported for **single flag** evaluation:
+  - **One-shot** (``tt_evaluate_single``): Parses rules + flag key + context in one call.
+  - **Fast path** (``tt_set_rules`` + ``tt_evaluate_single_ctx``): Cache rules first,
+    then evaluate a single flag with flag key + context only.
+
+WASM interface (raw exports, no wasm-bindgen):
+  - ``tt_alloc(size: i32) -> i32``   -- allocate *size* bytes, return pointer
+  - ``tt_dealloc(ptr: i32, size: i32)`` -- free *size* bytes at *ptr*
+  - ``tt_evaluate(rules_ptr, rules_len, ctx_ptr, ctx_len) -> i32``
+        Returns a pointer to: [u32 LE length][JSON payload bytes]
+  - ``tt_set_rules(rules_ptr, rules_len) -> i32`` (optional)
+        Cache parsed rules. Returns 0=ok, 1=error.
+  - ``tt_evaluate_ctx(ctx_ptr, ctx_len) -> i32`` (optional)
+        Evaluate using cached rules. Same result format as tt_evaluate.
+  - ``tt_evaluate_single(rules_ptr, rules_len, flag_key_ptr, flag_key_len, ctx_ptr, ctx_len) -> i32`` (optional)
+        Evaluate a single flag. Returns [u32 LE length][FlagResult JSON].
+  - ``tt_evaluate_single_ctx(flag_key_ptr, flag_key_len, ctx_ptr, ctx_len) -> i32`` (optional)
+        Evaluate a single flag using cached rules. Same result format.
+
+This module uses **wasmtime-py** as the WASM runtime.  wasmtime compiles
+the WASM ahead-of-time to native code, giving near-native evaluation speed.
+"""
+
+from __future__ import annotations
+
+import json
+import struct
+from typing import Optional
+
+import wasmtime
+
+from .types import EvalContext, EvalResults, FlagResult, TestResult
+
+
+class WasmEngine:
+    """Loads and runs the ToggleTest WASM evaluator binary via wasmtime.
+
+    Thread-safety: a single WasmEngine instance can be called from multiple
+    threads because wasmtime Stores are cheap to create and each ``evaluate``
+    call creates its own Store + Instance.  However, the ``load`` method must
+    be called exactly once before any ``evaluate`` calls.
+    """
+
+    def __init__(self) -> None:
+        # The compiled WASM module. Set by load(), None until then.
+        self._module: Optional[wasmtime.Module] = None
+
+        # The wasmtime Engine is reusable and thread-safe. It holds compiled
+        # code caches and configuration shared across all instantiations.
+        self._engine: wasmtime.Engine = wasmtime.Engine()
+
+        # Whether the WASM binary supports the fast-path exports.
+        self._has_fast_path: bool = False
+
+        # Whether the WASM binary supports single-flag evaluation exports.
+        self._has_single_flag: bool = False
+
+    # TODO: Add WASM binary integrity verification (Content-Digest header or SHA-256 checksum)
+    def load(self, wasm_bytes: bytes) -> None:
+        """Compile and validate the WASM evaluator binary.
+
+        This compiles the WASM bytecode into native machine code via wasmtime.
+        The compilation result is cached in ``self._module`` and reused for
+        every subsequent ``evaluate`` call (instantiation is cheap).
+
+        Args:
+            wasm_bytes: The raw .wasm binary fetched from GET /sdk/evaluator.wasm.
+
+        Raises:
+            wasmtime.WasmtimeError: If the binary is invalid or missing
+                required exports (tt_alloc, tt_dealloc, tt_evaluate, memory).
+        """
+        # Compile the WASM bytes into a reusable Module.
+        self._module = wasmtime.Module(self._engine, wasm_bytes)
+
+        # Sanity-check: verify the module exports the functions we need.
+        # wasmtime.Module.exports is a list of ExportType objects.
+        export_names = {exp.name for exp in self._module.exports}
+        required = {"tt_alloc", "tt_dealloc", "tt_evaluate", "memory"}
+        missing = required - export_names
+        if missing:
+            raise RuntimeError(
+                f"WASM module is missing required exports: {missing}"
+            )
+
+        # Detect optional fast-path exports (backward-compatible with older WASM binaries).
+        self._has_fast_path = (
+            "tt_set_rules" in export_names and "tt_evaluate_ctx" in export_names
+        )
+
+        # Detect optional single-flag evaluation exports.
+        self._has_single_flag = (
+            "tt_evaluate_single" in export_names and "tt_evaluate_single_ctx" in export_names
+        )
+
+    @property
+    def loaded(self) -> bool:
+        """Return True if the WASM module has been loaded and is ready."""
+        return self._module is not None
+
+    def evaluate(self, rules_json: str, context: EvalContext) -> EvalResults:
+        """Evaluate all rules against the given context via WASM.
+
+        If the WASM binary supports the fast-path exports (tt_set_rules /
+        tt_evaluate_ctx), rules are pre-parsed and cached in the instance
+        before evaluation. This avoids per-flag clone+sort overhead.
+
+        Args:
+            rules_json: The full rules JSON string (cached by RulesStore).
+            context:    The evaluation context for the current user/request.
+
+        Returns:
+            The full evaluation results (all flags + all tests).
+
+        Raises:
+            RuntimeError: If the WASM module is not loaded or evaluation fails.
+        """
+        if self._module is None:
+            raise RuntimeError("WASM engine not loaded. Call load() first.")
+
+        # -- Step 1: Encode inputs as UTF-8 bytes --
+        rules_bytes = rules_json.encode("utf-8")
+        context_bytes = json.dumps(
+            {"user_id": context.user_id, "attributes": context.attributes or {}}
+        ).encode("utf-8")
+
+        # -- Step 2: Create a fresh Store + Instance --
+        # Each evaluation gets its own Store so there is no shared mutable
+        # state between concurrent calls.  wasmtime Instances are lightweight.
+        store = wasmtime.Store(self._engine)
+        instance = wasmtime.Instance(store, self._module, [])
+
+        # Extract the exports we need.
+        exports = instance.exports(store)
+        tt_alloc = exports["tt_alloc"]
+        tt_dealloc = exports["tt_dealloc"]
+        memory = exports["memory"]
+
+        # Type-narrow: wasmtime exports can be Func, Memory, Global, or Table.
+        if not isinstance(tt_alloc, wasmtime.Func):
+            raise TypeError(f"Expected wasmtime.Func for tt_alloc, got {type(tt_alloc)}")
+        if not isinstance(tt_dealloc, wasmtime.Func):
+            raise TypeError(f"Expected wasmtime.Func for tt_dealloc, got {type(tt_dealloc)}")
+        if not isinstance(memory, wasmtime.Memory):
+            raise TypeError(f"Expected wasmtime.Memory for memory, got {type(memory)}")
+
+        # Try the fast path if available.
+        if self._has_fast_path:
+            tt_set_rules = exports.get("tt_set_rules")
+            tt_evaluate_ctx = exports.get("tt_evaluate_ctx")
+            if isinstance(tt_set_rules, wasmtime.Func) and isinstance(tt_evaluate_ctx, wasmtime.Func):
+                return self._evaluate_fast_path(
+                    store, tt_alloc, tt_dealloc, tt_set_rules, tt_evaluate_ctx,
+                    memory, rules_bytes, context_bytes,
+                )
+
+        # Fall back to one-shot path.
+        tt_evaluate = exports["tt_evaluate"]
+        if not isinstance(tt_evaluate, wasmtime.Func):
+            raise TypeError(f"Expected wasmtime.Func for tt_evaluate, got {type(tt_evaluate)}")
+
+        return self._evaluate_one_shot(
+            store, tt_alloc, tt_dealloc, tt_evaluate,
+            memory, rules_bytes, context_bytes,
+        )
+
+    def _evaluate_fast_path(
+        self,
+        store: wasmtime.Store,
+        tt_alloc: wasmtime.Func,
+        tt_dealloc: wasmtime.Func,
+        tt_set_rules: wasmtime.Func,
+        tt_evaluate_ctx: wasmtime.Func,
+        memory: wasmtime.Memory,
+        rules_bytes: bytes,
+        context_bytes: bytes,
+    ) -> EvalResults:
+        """Fast path: cache rules in WASM, then evaluate with context only."""
+        rules_ptr = 0
+        ctx_ptr = 0
+        result_ptr = 0
+        result_total_size = 0
+
+        try:
+            # -- Cache rules in the WASM instance --
+            rules_ptr = tt_alloc(store, len(rules_bytes))
+            mem_data = memory.data_ptr(store)
+            mem_len = memory.data_len(store)
+            _write_to_memory(mem_data, mem_len, rules_ptr, rules_bytes)
+
+            set_result = tt_set_rules(store, rules_ptr, len(rules_bytes))
+
+            # Free the rules buffer (WASM has its own internal copy now).
+            tt_dealloc(store, rules_ptr, len(rules_bytes))
+            rules_ptr = 0  # Prevent double-free in finally.
+
+            if set_result != 0:
+                raise RuntimeError("tt_set_rules failed (parse error)")
+
+            # -- Evaluate with context only --
+            ctx_ptr = tt_alloc(store, len(context_bytes))
+            mem_data = memory.data_ptr(store)
+            mem_len = memory.data_len(store)
+            _write_to_memory(mem_data, mem_len, ctx_ptr, context_bytes)
+
+            result_ptr = tt_evaluate_ctx(store, ctx_ptr, len(context_bytes))
+
+            # -- Read the result --
+            mem_data = memory.data_ptr(store)
+            mem_len = memory.data_len(store)
+
+            length_bytes = _read_from_memory(mem_data, mem_len, result_ptr, 4)
+            result_len = struct.unpack("<I", length_bytes)[0]
+
+            MAX_RESULT_SIZE = 10 * 1024 * 1024  # 10MB
+            if result_len > MAX_RESULT_SIZE:
+                raise ValueError(f"WASM result size {result_len} exceeds maximum {MAX_RESULT_SIZE}")
+
+            result_total_size = 4 + result_len
+            result_bytes = _read_from_memory(
+                mem_data, mem_len, result_ptr + 4, result_len
+            )
+            result_json_str = result_bytes.decode("utf-8")
+
+            return _parse_eval_results(json.loads(result_json_str))
+
+        finally:
+            if rules_ptr:
+                tt_dealloc(store, rules_ptr, len(rules_bytes))
+            if ctx_ptr:
+                tt_dealloc(store, ctx_ptr, len(context_bytes))
+            if result_ptr and result_total_size > 0:
+                tt_dealloc(store, result_ptr, result_total_size)
+
+    def _evaluate_one_shot(
+        self,
+        store: wasmtime.Store,
+        tt_alloc: wasmtime.Func,
+        tt_dealloc: wasmtime.Func,
+        tt_evaluate: wasmtime.Func,
+        memory: wasmtime.Memory,
+        rules_bytes: bytes,
+        context_bytes: bytes,
+    ) -> EvalResults:
+        """One-shot path: send both rules and context to tt_evaluate."""
+        rules_ptr = 0
+        ctx_ptr = 0
+        result_ptr = 0
+        result_total_size = 0
+
+        try:
+            # -- Allocate and write input buffers --
+            rules_ptr = tt_alloc(store, len(rules_bytes))
+            ctx_ptr = tt_alloc(store, len(context_bytes))
+
+            mem_data = memory.data_ptr(store)
+            mem_len = memory.data_len(store)
+            _write_to_memory(mem_data, mem_len, rules_ptr, rules_bytes)
+            _write_to_memory(mem_data, mem_len, ctx_ptr, context_bytes)
+
+            # -- Call the WASM evaluator --
+            result_ptr = tt_evaluate(
+                store,
+                rules_ptr,
+                len(rules_bytes),
+                ctx_ptr,
+                len(context_bytes),
+            )
+
+            # -- Read the result --
+            mem_data = memory.data_ptr(store)
+            mem_len = memory.data_len(store)
+
+            length_bytes = _read_from_memory(mem_data, mem_len, result_ptr, 4)
+            result_len = struct.unpack("<I", length_bytes)[0]
+
+            MAX_RESULT_SIZE = 10 * 1024 * 1024  # 10MB
+            if result_len > MAX_RESULT_SIZE:
+                raise ValueError(f"WASM result size {result_len} exceeds maximum {MAX_RESULT_SIZE}")
+
+            result_total_size = 4 + result_len
+            result_bytes = _read_from_memory(
+                mem_data, mem_len, result_ptr + 4, result_len
+            )
+            result_json_str = result_bytes.decode("utf-8")
+
+            return _parse_eval_results(json.loads(result_json_str))
+
+        finally:
+            if rules_ptr:
+                tt_dealloc(store, rules_ptr, len(rules_bytes))
+            if ctx_ptr:
+                tt_dealloc(store, ctx_ptr, len(context_bytes))
+            if result_ptr and result_total_size > 0:
+                tt_dealloc(store, result_ptr, result_total_size)
+
+    def evaluate_single(
+        self, rules_json: str, flag_key: str, context: EvalContext
+    ) -> FlagResult:
+        """Evaluate a single flag against the given context via WASM.
+
+        When the WASM binary supports single-flag exports, this avoids
+        evaluating *all* flags and parsing the full result set.  Falls back
+        to the full ``evaluate()`` method on older WASM binaries.
+
+        Args:
+            rules_json: The full rules JSON string (cached by RulesStore).
+            flag_key:   The flag key to evaluate (e.g. "dark-mode").
+            context:    The evaluation context for the current user/request.
+
+        Returns:
+            A FlagResult with value, reason, and optional rule_id.
+
+        Raises:
+            RuntimeError: If the WASM module is not loaded or evaluation fails.
+        """
+        if self._module is None:
+            raise RuntimeError("WASM engine not loaded. Call load() first.")
+
+        # -- Step 1: Encode inputs as UTF-8 bytes --
+        rules_bytes = rules_json.encode("utf-8")
+        flag_key_bytes = flag_key.encode("utf-8")
+        context_bytes = json.dumps(
+            {"user_id": context.user_id, "attributes": context.attributes or {}}
+        ).encode("utf-8")
+
+        # -- Step 2: Create a fresh Store + Instance --
+        store = wasmtime.Store(self._engine)
+        instance = wasmtime.Instance(store, self._module, [])
+
+        # Extract the exports we need.
+        exports = instance.exports(store)
+        tt_alloc = exports["tt_alloc"]
+        tt_dealloc = exports["tt_dealloc"]
+        memory = exports["memory"]
+
+        # Type-narrow: wasmtime exports can be Func, Memory, Global, or Table.
+        if not isinstance(tt_alloc, wasmtime.Func):
+            raise TypeError(f"Expected wasmtime.Func for tt_alloc, got {type(tt_alloc)}")
+        if not isinstance(tt_dealloc, wasmtime.Func):
+            raise TypeError(f"Expected wasmtime.Func for tt_dealloc, got {type(tt_dealloc)}")
+        if not isinstance(memory, wasmtime.Memory):
+            raise TypeError(f"Expected wasmtime.Memory for memory, got {type(memory)}")
+
+        # -- Step 3: Choose the best evaluation path --
+
+        # Prefer the fast path (cached rules + single flag eval) when available.
+        if self._has_fast_path and self._has_single_flag:
+            tt_set_rules = exports.get("tt_set_rules")
+            tt_evaluate_single_ctx = exports.get("tt_evaluate_single_ctx")
+            if isinstance(tt_set_rules, wasmtime.Func) and isinstance(tt_evaluate_single_ctx, wasmtime.Func):
+                return self._evaluate_single_fast_path(
+                    store, tt_alloc, tt_dealloc, tt_set_rules,
+                    tt_evaluate_single_ctx, memory,
+                    rules_bytes, flag_key_bytes, context_bytes,
+                )
+
+        # One-shot single-flag eval (no cached rules).
+        if self._has_single_flag:
+            tt_evaluate_single = exports.get("tt_evaluate_single")
+            if isinstance(tt_evaluate_single, wasmtime.Func):
+                return self._evaluate_single_one_shot(
+                    store, tt_alloc, tt_dealloc, tt_evaluate_single,
+                    memory, rules_bytes, flag_key_bytes, context_bytes,
+                )
+
+        # Fall back to full evaluation and extract the single flag.
+        results = self.evaluate(rules_json, context)
+        flag_result = results.flags.get(flag_key)
+        if flag_result is None:
+            return FlagResult(value=False, reason="not_found")
+        return flag_result
+
+    def _evaluate_single_fast_path(
+        self,
+        store: wasmtime.Store,
+        tt_alloc: wasmtime.Func,
+        tt_dealloc: wasmtime.Func,
+        tt_set_rules: wasmtime.Func,
+        tt_evaluate_single_ctx: wasmtime.Func,
+        memory: wasmtime.Memory,
+        rules_bytes: bytes,
+        flag_key_bytes: bytes,
+        context_bytes: bytes,
+    ) -> FlagResult:
+        """Fast path: cache rules, then evaluate a single flag with context."""
+        rules_ptr = 0
+        flag_key_ptr = 0
+        ctx_ptr = 0
+        result_ptr = 0
+        result_total_size = 0
+
+        try:
+            # -- Cache rules in the WASM instance --
+            rules_ptr = tt_alloc(store, len(rules_bytes))
+            mem_data = memory.data_ptr(store)
+            mem_len = memory.data_len(store)
+            _write_to_memory(mem_data, mem_len, rules_ptr, rules_bytes)
+
+            set_result = tt_set_rules(store, rules_ptr, len(rules_bytes))
+
+            # Free the rules buffer (WASM has its own internal copy now).
+            tt_dealloc(store, rules_ptr, len(rules_bytes))
+            rules_ptr = 0  # Prevent double-free in finally.
+
+            if set_result != 0:
+                raise RuntimeError("tt_set_rules failed (parse error)")
+
+            # -- Allocate and write flag key + context --
+            flag_key_ptr = tt_alloc(store, len(flag_key_bytes))
+            ctx_ptr = tt_alloc(store, len(context_bytes))
+
+            mem_data = memory.data_ptr(store)
+            mem_len = memory.data_len(store)
+            _write_to_memory(mem_data, mem_len, flag_key_ptr, flag_key_bytes)
+            _write_to_memory(mem_data, mem_len, ctx_ptr, context_bytes)
+
+            # -- Call single-flag evaluation --
+            result_ptr = tt_evaluate_single_ctx(
+                store,
+                flag_key_ptr, len(flag_key_bytes),
+                ctx_ptr, len(context_bytes),
+            )
+
+            # -- Read the result --
+            mem_data = memory.data_ptr(store)
+            mem_len = memory.data_len(store)
+
+            length_bytes = _read_from_memory(mem_data, mem_len, result_ptr, 4)
+            result_len = struct.unpack("<I", length_bytes)[0]
+
+            MAX_RESULT_SIZE = 10 * 1024 * 1024  # 10MB
+            if result_len > MAX_RESULT_SIZE:
+                raise ValueError(f"WASM result size {result_len} exceeds maximum {MAX_RESULT_SIZE}")
+
+            result_total_size = 4 + result_len
+            result_bytes = _read_from_memory(
+                mem_data, mem_len, result_ptr + 4, result_len
+            )
+            result_json_str = result_bytes.decode("utf-8")
+
+            return _parse_flag_result(json.loads(result_json_str))
+
+        finally:
+            if rules_ptr:
+                tt_dealloc(store, rules_ptr, len(rules_bytes))
+            if flag_key_ptr:
+                tt_dealloc(store, flag_key_ptr, len(flag_key_bytes))
+            if ctx_ptr:
+                tt_dealloc(store, ctx_ptr, len(context_bytes))
+            if result_ptr and result_total_size > 0:
+                tt_dealloc(store, result_ptr, result_total_size)
+
+    def _evaluate_single_one_shot(
+        self,
+        store: wasmtime.Store,
+        tt_alloc: wasmtime.Func,
+        tt_dealloc: wasmtime.Func,
+        tt_evaluate_single: wasmtime.Func,
+        memory: wasmtime.Memory,
+        rules_bytes: bytes,
+        flag_key_bytes: bytes,
+        context_bytes: bytes,
+    ) -> FlagResult:
+        """One-shot path: send rules + flag key + context to tt_evaluate_single."""
+        rules_ptr = 0
+        flag_key_ptr = 0
+        ctx_ptr = 0
+        result_ptr = 0
+        result_total_size = 0
+
+        try:
+            # -- Allocate and write input buffers --
+            rules_ptr = tt_alloc(store, len(rules_bytes))
+            flag_key_ptr = tt_alloc(store, len(flag_key_bytes))
+            ctx_ptr = tt_alloc(store, len(context_bytes))
+
+            mem_data = memory.data_ptr(store)
+            mem_len = memory.data_len(store)
+            _write_to_memory(mem_data, mem_len, rules_ptr, rules_bytes)
+            _write_to_memory(mem_data, mem_len, flag_key_ptr, flag_key_bytes)
+            _write_to_memory(mem_data, mem_len, ctx_ptr, context_bytes)
+
+            # -- Call the WASM single-flag evaluator --
+            result_ptr = tt_evaluate_single(
+                store,
+                rules_ptr, len(rules_bytes),
+                flag_key_ptr, len(flag_key_bytes),
+                ctx_ptr, len(context_bytes),
+            )
+
+            # -- Read the result --
+            mem_data = memory.data_ptr(store)
+            mem_len = memory.data_len(store)
+
+            length_bytes = _read_from_memory(mem_data, mem_len, result_ptr, 4)
+            result_len = struct.unpack("<I", length_bytes)[0]
+
+            MAX_RESULT_SIZE = 10 * 1024 * 1024  # 10MB
+            if result_len > MAX_RESULT_SIZE:
+                raise ValueError(f"WASM result size {result_len} exceeds maximum {MAX_RESULT_SIZE}")
+
+            result_total_size = 4 + result_len
+            result_bytes = _read_from_memory(
+                mem_data, mem_len, result_ptr + 4, result_len
+            )
+            result_json_str = result_bytes.decode("utf-8")
+
+            return _parse_flag_result(json.loads(result_json_str))
+
+        finally:
+            if rules_ptr:
+                tt_dealloc(store, rules_ptr, len(rules_bytes))
+            if flag_key_ptr:
+                tt_dealloc(store, flag_key_ptr, len(flag_key_bytes))
+            if ctx_ptr:
+                tt_dealloc(store, ctx_ptr, len(context_bytes))
+            if result_ptr and result_total_size > 0:
+                tt_dealloc(store, result_ptr, result_total_size)
+
+
+# ---------------------------------------------------------------------------
+# Memory helpers (ctypes-based access to WASM linear memory)
+# ---------------------------------------------------------------------------
+
+
+def _write_to_memory(
+    mem_data: "ctypes pointer",
+    mem_len: int,
+    offset: int,
+    data: bytes,
+) -> None:
+    """Write ``data`` bytes into WASM linear memory at ``offset``.
+
+    Uses ctypes to directly copy bytes into the raw memory pointer exposed
+    by wasmtime.  This avoids Python-level byte-by-byte copies.
+
+    Args:
+        mem_data: The raw ctypes pointer from memory.data_ptr(store).
+        mem_len:  Total length of the WASM linear memory in bytes.
+        offset:   Byte offset within the memory to start writing.
+        data:     The bytes to write.
+
+    Raises:
+        RuntimeError: If the write would exceed the memory bounds.
+    """
+    import ctypes
+
+    if offset + len(data) > mem_len:
+        raise RuntimeError(
+            f"WASM memory write out of bounds: offset={offset}, "
+            f"len={len(data)}, mem_len={mem_len}"
+        )
+
+    # Create a ctypes array type for the data length, then copy bytes in.
+    src = (ctypes.c_ubyte * len(data)).from_buffer_copy(data)
+    ctypes.memmove(
+        ctypes.cast(mem_data, ctypes.POINTER(ctypes.c_ubyte * mem_len))[0][offset:],  # noqa: E501
+        src,
+        len(data),
+    )
+
+
+def _read_from_memory(
+    mem_data: "ctypes pointer",
+    mem_len: int,
+    offset: int,
+    length: int,
+) -> bytes:
+    """Read ``length`` bytes from WASM linear memory at ``offset``.
+
+    Args:
+        mem_data: The raw ctypes pointer from memory.data_ptr(store).
+        mem_len:  Total length of the WASM linear memory in bytes.
+        offset:   Byte offset within the memory to start reading.
+        length:   Number of bytes to read.
+
+    Returns:
+        A ``bytes`` object containing the requested data.
+
+    Raises:
+        RuntimeError: If the read would exceed the memory bounds.
+    """
+    import ctypes
+
+    if offset + length > mem_len:
+        raise RuntimeError(
+            f"WASM memory read out of bounds: offset={offset}, "
+            f"len={length}, mem_len={mem_len}"
+        )
+
+    # Cast the raw pointer to a byte array and slice out the region we need.
+    array_type = ctypes.c_ubyte * mem_len
+    full_array = ctypes.cast(mem_data, ctypes.POINTER(array_type)).contents
+    return bytes(full_array[offset : offset + length])
+
+
+# ---------------------------------------------------------------------------
+# Result parsing
+# ---------------------------------------------------------------------------
+
+
+def _parse_eval_results(raw: dict) -> EvalResults:
+    """Parse the raw JSON dict from the WASM engine into typed EvalResults.
+
+    The WASM engine returns JSON in this shape:
+    {
+        "flags": { "key": { "value": ..., "reason": "...", "rule_id": "..." } },
+        "tests": { "key": { "variant": "...", "bucket": 1234 } }
+    }
+
+    Args:
+        raw: The parsed JSON dict from the WASM evaluator.
+
+    Returns:
+        A fully typed EvalResults instance.
+    """
+    # Parse flag results.
+    flags = {}
+    for key, flag_data in raw.get("flags", {}).items():
+        flags[key] = FlagResult(
+            value=flag_data.get("value", False),
+            reason=flag_data.get("reason", "unknown"),
+            rule_id=flag_data.get("rule_id"),
+        )
+
+    # Parse test results.
+    tests = {}
+    for key, test_data in raw.get("tests", {}).items():
+        tests[key] = TestResult(
+            variant=test_data.get("variant", "control"),
+            bucket=test_data.get("bucket", 0),
+        )
+
+    return EvalResults(flags=flags, tests=tests)
+
+
+def _parse_flag_result(raw: dict) -> FlagResult:
+    """Parse the raw JSON dict from a single-flag WASM evaluation into a FlagResult.
+
+    The single-flag WASM exports return JSON in this shape:
+    {"value": ..., "reason": "...", "rule_id": "..."}
+
+    Args:
+        raw: The parsed JSON dict from the WASM single-flag evaluator.
+
+    Returns:
+        A typed FlagResult instance.
+    """
+    return FlagResult(
+        value=raw.get("value", False),
+        reason=raw.get("reason", "unknown"),
+        rule_id=raw.get("rule_id"),
+    )

toggletest-0.1.0.dist-info/METADATA

@@ -0,0 +1,12 @@
+Metadata-Version: 2.4
+Name: toggletest
+Version: 0.1.0
+Summary: ToggleTest SDK for feature flags and A/B testing
+License-Expression: MIT
+Requires-Python: >=3.9
+Requires-Dist: httpx-sse>=0.4
+Requires-Dist: httpx>=0.25
+Requires-Dist: wasmtime>=27.0
+Provides-Extra: dev
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: pytest-asyncio; extra == 'dev'

toggletest-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+toggletest/__init__.py,sha256=BRnoVmyZ8UvoFhU1d_bMw1KrmMaOoUCLkfLuJF0ShZ4,1291
+toggletest/client.py,sha256=NynnAj-9JjB0ioiVLeEe17gx6sx0qb2cN8EQCWmusf4,18262
+toggletest/event_buffer.py,sha256=3ZrE8h37TmhxkV9HB8C2xjqaNyYN7UFltCn7o2Y3a_s,8490
+toggletest/rules_store.py,sha256=IwyQ2MyGdIkwzDIvQyYRaaaSvqgVWmZqZg9_lXtSVD0,8927
+toggletest/sse.py,sha256=WpBm7F5ARUWxg_IO_V_ECpx806h_h1soVr_THwIpuY0,7994
+toggletest/types.py,sha256=nychoAZhyCtFKyDiNT-M6nj_teWwr-EF58X3WRJK_C4,5342
+toggletest/wasm_engine.py,sha256=KnUlH5g095i2qf0MvqTovFci8bpsuVqq5t9ofcOtMS8,26626
+toggletest-0.1.0.dist-info/METADATA,sha256=zo61A9_IYgRf-kmY7MLVTkxz1LcN03FzYBTYKgmUUUc,350
+toggletest-0.1.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+toggletest-0.1.0.dist-info/RECORD,,