shipeasy 0.3.0__tar.gz

shipeasy-0.3.0/.github/workflows/publish.yml

@@ -0,0 +1,65 @@
+name: Publish
+
+# HARD RULE: never publish manually. Bump the `version` field in
+# pyproject.toml, push to main, and this workflow handles PyPI.
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+concurrency:
+  group: publish
+  cancel-in-progress: false
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write  # PyPI Trusted Publishing
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - run: pip install build hatchling
+
+      - name: Run tests
+        run: |
+          pip install pytest -e .
+          pytest -q
+
+      - name: Read package version
+        id: ver
+        run: |
+          VER=$(python -c "import tomllib,sys; print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")
+          echo "version=$VER" >> "$GITHUB_OUTPUT"
+
+      - name: Check if version already on PyPI
+        id: check
+        run: |
+          STATUS=$(curl -s -o /dev/null -w "%{http_code}" https://pypi.org/pypi/shipeasy/${{ steps.ver.outputs.version }}/json)
+          if [ "$STATUS" = "200" ]; then
+            echo "Already published: shipeasy==${{ steps.ver.outputs.version }}"
+            echo "skip=1" >> "$GITHUB_OUTPUT"
+          else
+            echo "skip=0" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Build distributions
+        if: steps.check.outputs.skip != '1'
+        run: python -m build
+
+      # Requires PyPI Trusted Publishing to be configured for the
+      # `shipeasy` project on pypi.org → repo `shipeasy-ai/sdk-python`,
+      # workflow `publish.yml`. Set vars.PUBLISH_ENABLED=true once
+      # trusted publisher is configured.
+      - name: Publish to PyPI (Trusted Publishing)
+        if: steps.check.outputs.skip != '1' && vars.PUBLISH_ENABLED == 'true'
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+      - name: Publish skipped notice
+        if: steps.check.outputs.skip != '1' && vars.PUBLISH_ENABLED != 'true'
+        run: echo "::warning::vars.PUBLISH_ENABLED is not 'true' — configure PyPI Trusted Publishing on this repo, then set the variable."

shipeasy-0.3.0/.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+*.py[cod]
+.venv/
+dist/
+build/
+*.egg-info/
+.pytest_cache/

shipeasy-0.3.0/CHANGELOG.md

@@ -0,0 +1,24 @@
+# Changelog
+
+## 0.3.0
+
+- **Anonymous bucketing (`__se_anon_id`).** Added `AnonIdMiddleware` (WSGI) and
+  `AnonIdASGIMiddleware` (ASGI) — zero-dependency middleware that mints the
+  shared `__se_anon_id` first-party cookie for any request without one and
+  exposes it on the request (`environ["shipeasy.anon_id"]`). Gate/experiment
+  evaluations now default to the cookie id as `anonymous_id` (via a `ContextVar`,
+  so it works under threads and asyncio), so anonymous visitors bucket
+  consistently across server renders and the browser with no per-call wiring.
+  Implements the cross-SDK contract in `18-identity-bucketing.md`.
+- **Eval fix (no-unit gate rule).** A request with no `user_id`/`anonymous_id`
+  now resolves a fully-rolled (100%) gate as **on** instead of always off; a
+  fractional gate is still off until a stable unit exists. Matches the
+  TypeScript reference SDK. Targeting rules are still evaluated first.
+
+## 0.2.0
+
+- Per-evaluation usage telemetry (fire-and-forget, on by default).
+
+## 0.1.0
+
+- Initial release: feature flags, configs, experiments, metric tracking.

shipeasy-0.3.0/LICENSE

@@ -0,0 +1,40 @@
+Shipeasy Source-Available License (Shipeasy-SAL) 1.0
+
+Copyright (c) 2026 Shipeasy, Inc. All rights reserved.
+
+1. License Grant.
+   Subject to the terms of this License, Shipeasy, Inc. ("Shipeasy") grants
+   you a non-exclusive, non-transferable, revocable, worldwide license to:
+
+   (a) Use, copy, and modify the Software solely as a client integration for
+       interacting with Shipeasy's hosted services (the "Service");
+   (b) Distribute the Software as part of an application that calls the
+       Service, in object form, provided the recipient also agrees to this
+       License.
+
+2. Restrictions.
+   You may not:
+
+   (a) Use the Software, in whole or in part, to build, host, or operate any
+       service that competes with the Service or that provides feature-flag,
+       experimentation, configuration, internationalization, or related
+       functionality to third parties on a commercial basis;
+   (b) Sublicense, sell, rent, or lease the Software;
+   (c) Remove or alter copyright notices, license terms, or attribution.
+
+3. Contributions.
+   Any pull request you submit is licensed back to Shipeasy under this
+   License plus a perpetual, irrevocable right for Shipeasy to relicense.
+
+4. Trademarks.
+   This License does not grant rights in the names "Shipeasy", related
+   marks, or logos.
+
+5. No Warranty / Limitation of Liability.
+   THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND. IN NO
+   EVENT SHALL SHIPEASY BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER
+   LIABILITY ARISING FROM USE OF THE SOFTWARE.
+
+6. Termination.
+   This License terminates automatically if you breach it. Sections 2-5
+   survive termination.

shipeasy-0.3.0/PKG-INFO

@@ -0,0 +1,76 @@
+Metadata-Version: 2.4
+Name: shipeasy
+Version: 0.3.0
+Summary: Shipeasy server SDK for Python — feature flags, configs, experiments, metrics.
+Project-URL: Homepage, https://shipeasy.dev
+Project-URL: Source, https://github.com/shipeasy-ai/sdk-python
+Author: Shipeasy
+License: MIT
+License-File: LICENSE
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# shipeasy (Python)
+
+Server SDK for [Shipeasy](https://shipeasy.dev) — feature flags, remote configs, A/B experiments, and metric tracking. Server-key only, never embed in browsers.
+
+```bash
+pip install shipeasy
+```
+
+```python
+from shipeasy import Client
+
+client = Client(api_key="sdk_server_...")
+client.init()  # background poll; use init_once() for serverless
+
+if client.get_flag("new_checkout", {"user_id": "u_123", "country": "US"}):
+    ...
+
+config = client.get_config("billing_copy")
+
+result = client.get_experiment(
+    "checkout_button",
+    user={"user_id": "u_123"},
+    default_params={"color": "blue"},
+)
+print(result.in_experiment, result.group, result.params)
+
+client.track("u_123", "purchase", {"amount": 49})
+```
+
+## Anonymous visitors (zero-config bucketing)
+
+For logged-out traffic you need a *stable* unit so a fractional rollout buckets
+the same on the server and in the browser. The middleware mints a first-party
+`__se_anon_id` cookie (shared with every Shipeasy SDK) for any request without
+one; evaluations then **default to it** as `anonymous_id`, so `get_flag` on an
+anonymous request just works — no per-call wiring.
+
+```python
+# WSGI (Flask, Django, ...)
+from shipeasy.middleware import AnonIdMiddleware
+app.wsgi_app = AnonIdMiddleware(app.wsgi_app)
+
+# ASGI (FastAPI, Starlette)
+from shipeasy.middleware import AnonIdASGIMiddleware
+app.add_middleware(AnonIdASGIMiddleware)
+```
+
+```python
+# logged-out request → buckets on the __se_anon_id cookie automatically
+client.get_flag("new_checkout", {})
+```
+
+An explicit `user_id`/`anonymous_id` always wins. The id is also on the request
+(`environ["shipeasy.anon_id"]`). The cookie is non-`HttpOnly` by design so the
+browser SDK buckets identically; a request with **no** unit still resolves a
+fully-rolled (100%) gate as on. Cookie name + format are a cross-SDK contract —
+see `18-identity-bucketing.md`.
+
+## Evaluation
+
+Tested against the cross-language MurmurHash3 vectors in `experiment-platform/04-evaluation.md`.

shipeasy-0.3.0/README.md

@@ -0,0 +1,61 @@
+# shipeasy (Python)
+
+Server SDK for [Shipeasy](https://shipeasy.dev) — feature flags, remote configs, A/B experiments, and metric tracking. Server-key only, never embed in browsers.
+
+```bash
+pip install shipeasy
+```
+
+```python
+from shipeasy import Client
+
+client = Client(api_key="sdk_server_...")
+client.init()  # background poll; use init_once() for serverless
+
+if client.get_flag("new_checkout", {"user_id": "u_123", "country": "US"}):
+    ...
+
+config = client.get_config("billing_copy")
+
+result = client.get_experiment(
+    "checkout_button",
+    user={"user_id": "u_123"},
+    default_params={"color": "blue"},
+)
+print(result.in_experiment, result.group, result.params)
+
+client.track("u_123", "purchase", {"amount": 49})
+```
+
+## Anonymous visitors (zero-config bucketing)
+
+For logged-out traffic you need a *stable* unit so a fractional rollout buckets
+the same on the server and in the browser. The middleware mints a first-party
+`__se_anon_id` cookie (shared with every Shipeasy SDK) for any request without
+one; evaluations then **default to it** as `anonymous_id`, so `get_flag` on an
+anonymous request just works — no per-call wiring.
+
+```python
+# WSGI (Flask, Django, ...)
+from shipeasy.middleware import AnonIdMiddleware
+app.wsgi_app = AnonIdMiddleware(app.wsgi_app)
+
+# ASGI (FastAPI, Starlette)
+from shipeasy.middleware import AnonIdASGIMiddleware
+app.add_middleware(AnonIdASGIMiddleware)
+```
+
+```python
+# logged-out request → buckets on the __se_anon_id cookie automatically
+client.get_flag("new_checkout", {})
+```
+
+An explicit `user_id`/`anonymous_id` always wins. The id is also on the request
+(`environ["shipeasy.anon_id"]`). The cookie is non-`HttpOnly` by design so the
+browser SDK buckets identically; a request with **no** unit still resolves a
+fully-rolled (100%) gate as on. Cookie name + format are a cross-SDK contract —
+see `18-identity-bucketing.md`.
+
+## Evaluation
+
+Tested against the cross-language MurmurHash3 vectors in `experiment-platform/04-evaluation.md`.

shipeasy-0.3.0/pyproject.toml

@@ -0,0 +1,24 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "shipeasy"
+version = "0.3.0"
+description = "Shipeasy server SDK for Python — feature flags, configs, experiments, metrics."
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.9"
+authors = [{ name = "Shipeasy" }]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+]
+
+[project.urls]
+Homepage = "https://shipeasy.dev"
+Source = "https://github.com/shipeasy-ai/sdk-python"
+
+[tool.hatch.build.targets.wheel]
+packages = ["shipeasy"]

shipeasy-0.3.0/shipeasy/__init__.py

@@ -0,0 +1,12 @@
+from ._client import Client, ExperimentResult
+from ._hash import murmur3
+from .middleware import AnonIdMiddleware, AnonIdASGIMiddleware
+
+__all__ = [
+    "Client",
+    "ExperimentResult",
+    "murmur3",
+    "AnonIdMiddleware",
+    "AnonIdASGIMiddleware",
+]
+__version__ = "0.3.0"

shipeasy-0.3.0/shipeasy/_anon_id.py

@@ -0,0 +1,92 @@
+"""Anonymous bucketing identity — the cross-SDK ``__se_anon_id`` cookie.
+
+Gates and experiments bucket a unit with ``murmur3(salt:unit)``. For a logged-out
+visitor the unit is a stable anonymous id carried in a single first-party cookie
+that EVERY Shipeasy SDK (server + browser) reads and writes, so a server render
+and the browser bucket a fractional rollout identically. The cookie name and
+format are frozen across every language; see
+``experiment-platform/18-identity-bucketing.md``.
+"""
+
+from __future__ import annotations
+
+import re
+import uuid
+from contextvars import ContextVar
+from typing import Optional
+
+COOKIE = "__se_anon_id"
+MAX_AGE = 31_536_000  # 1 year, in seconds
+
+# The cookie value is client-controllable and feeds bucketing, so a tampered
+# value is treated as absent and a fresh id is minted. UUIDs satisfy this.
+_VALID_RX = re.compile(r"^[A-Za-z0-9_-]{1,64}$")
+
+# Per-request id resolved by the middleware. A ContextVar (not thread-local)
+# so it works under both threaded WSGI servers and asyncio/ASGI.
+_current: ContextVar[Optional[str]] = ContextVar("shipeasy_anon_id", default=None)
+
+
+def mint() -> str:
+    """A fresh opaque bucketing id (UUIDv4)."""
+    return str(uuid.uuid4())
+
+
+def is_valid(value: Optional[str]) -> bool:
+    return isinstance(value, str) and _VALID_RX.match(value) is not None
+
+
+def current() -> Optional[str]:
+    """The anon id the middleware resolved for the current request, or None.
+
+    ``Client.get_flag`` / ``get_experiment`` fall back to this as the default
+    ``anonymous_id``, so evaluations need no per-call wiring.
+    """
+    return _current.get()
+
+
+def set_current(value: Optional[str]):
+    """Bind the current-request anon id; returns the reset token."""
+    return _current.set(value)
+
+
+def reset_current(token) -> None:
+    _current.reset(token)
+
+
+def parse_cookie_header(header: Optional[str]) -> dict:
+    out: dict = {}
+    if not header:
+        return out
+    for pair in header.split(";"):
+        pair = pair.strip()
+        if "=" in pair:
+            k, v = pair.split("=", 1)
+            if k and k not in out:
+                out[k] = v
+    return out
+
+
+def read_or_mint(cookie_header: Optional[str]):
+    """Return ``(id, minted)`` for a raw Cookie header value."""
+    raw = parse_cookie_header(cookie_header).get(COOKIE)
+    if is_valid(raw):
+        return raw, False
+    return mint(), True
+
+
+def build_set_cookie(value: str, secure: bool) -> str:
+    """Format the ``Set-Cookie`` header value per the cross-SDK contract.
+
+    Non-HttpOnly by design — the browser SDK reads it via ``document.cookie`` to
+    bucket identically to the server.
+    """
+    parts = [
+        f"{COOKIE}={value}",
+        "Path=/",
+        f"Max-Age={MAX_AGE}",
+        "SameSite=Lax",
+    ]
+    if secure:
+        parts.append("Secure")
+    return "; ".join(parts)

shipeasy-0.3.0/shipeasy/_client.py

@@ -0,0 +1,214 @@
+from __future__ import annotations
+
+import json
+import logging
+import threading
+import time
+import urllib.request
+import urllib.error
+from typing import Any, Callable, Mapping, Optional, TypeVar
+
+from ._eval import ExperimentResult, eval_experiment, eval_gate
+from ._telemetry import Telemetry, DEFAULT_TELEMETRY_URL
+from . import _anon_id
+
+T = TypeVar("T")
+log = logging.getLogger("shipeasy")
+
+
+def _with_anon_id(user: Mapping[str, Any]) -> Mapping[str, Any]:
+    """Default ``anonymous_id`` to the request's ``__se_anon_id`` (set by the
+    middleware) when the caller passed no explicit unit. A caller-supplied
+    ``user_id``/``anonymous_id`` always wins; with no middleware this is a no-op.
+    """
+    if user.get("user_id") or user.get("anonymous_id"):
+        return user
+    anon = _anon_id.current()
+    if not anon:
+        return user
+    merged = dict(user)
+    merged["anonymous_id"] = anon
+    return merged
+
+_DEFAULT_BASE_URL = "https://edge.shipeasy.dev"
+_DEFAULT_POLL_INTERVAL = 30
+
+
+class Client:
+    def __init__(
+        self,
+        api_key: str,
+        base_url: Optional[str] = None,
+        *,
+        env: str = "prod",
+        disable_telemetry: bool = False,
+        telemetry_url: Optional[str] = None,
+    ) -> None:
+        self._api_key = api_key
+        self._base_url = (base_url or _DEFAULT_BASE_URL).rstrip("/")
+        # Per-evaluation usage telemetry. ON by default; pass
+        # disable_telemetry=True to opt out. See _telemetry.py.
+        self._telemetry = Telemetry(
+            endpoint=telemetry_url or DEFAULT_TELEMETRY_URL,
+            sdk_key=api_key,
+            side="server",
+            env=env,
+            disabled=disable_telemetry,
+        )
+        self._flags_blob: Optional[dict] = None
+        self._exps_blob: Optional[dict] = None
+        self._flags_etag: Optional[str] = None
+        self._exps_etag: Optional[str] = None
+        self._poll_interval = _DEFAULT_POLL_INTERVAL
+        self._lock = threading.Lock()
+        self._stop = threading.Event()
+        self._thread: Optional[threading.Thread] = None
+        self._initialized = False
+
+    def init(self) -> None:
+        self._fetch_all()
+        self._initialized = True
+        self._start_poll()
+
+    def init_once(self) -> None:
+        if self._initialized:
+            return
+        self._fetch_all()
+        self._initialized = True
+
+    def destroy(self) -> None:
+        self._stop.set()
+        if self._thread:
+            self._thread.join(timeout=1)
+            self._thread = None
+
+    def get_flag(self, name: str, user: Mapping[str, Any]) -> bool:
+        self._telemetry.emit("gate", name)
+        with self._lock:
+            gate = (self._flags_blob or {}).get("gates", {}).get(name)
+        if not gate:
+            return False
+        return eval_gate(gate, _with_anon_id(user))
+
+    def get_config(
+        self, name: str, decode: Optional[Callable[[Any], T]] = None
+    ) -> Optional[T]:
+        self._telemetry.emit("config", name)
+        with self._lock:
+            entry = (self._flags_blob or {}).get("configs", {}).get(name)
+        if not entry:
+            return None
+        value = entry.get("value")
+        if decode is None:
+            return value
+        try:
+            return decode(value)
+        except Exception as e:  # noqa: BLE001
+            log.warning("get_config(%s) decode failed: %s", name, e)
+            return None
+
+    def get_experiment(
+        self,
+        name: str,
+        user: Mapping[str, Any],
+        default_params: T,
+        decode: Optional[Callable[[Any], T]] = None,
+    ) -> ExperimentResult:
+        self._telemetry.emit("experiment", name)
+        with self._lock:
+            flags_blob = self._flags_blob
+            exps_blob = self._exps_blob
+        exp = (exps_blob or {}).get("experiments", {}).get(name)
+        result = eval_experiment(exp, flags_blob, exps_blob, _with_anon_id(user))
+        if result.params is None:
+            result.params = default_params
+        if result.in_experiment and decode is not None:
+            try:
+                result.params = decode(result.params)
+            except Exception as e:  # noqa: BLE001
+                log.warning("get_experiment(%s) decode failed: %s", name, e)
+                return ExperimentResult(False, "control", default_params)
+        return result
+
+    def track(self, user_id: str, event_name: str, properties: Optional[Mapping[str, Any]] = None) -> None:
+        body = {
+            "events": [{
+                "type": "metric",
+                "event_name": event_name,
+                "user_id": str(user_id),
+                "ts": int(time.time() * 1000),
+                **({"properties": dict(properties)} if properties else {}),
+            }]
+        }
+        data = json.dumps(body).encode("utf-8")
+        threading.Thread(
+            target=self._post_silent,
+            args=("/collect", data),
+            daemon=True,
+        ).start()
+
+    def _post_silent(self, path: str, data: bytes) -> None:
+        try:
+            req = urllib.request.Request(
+                f"{self._base_url}{path}",
+                data=data,
+                headers={"X-SDK-Key": self._api_key, "Content-Type": "text/plain"},
+                method="POST",
+            )
+            urllib.request.urlopen(req, timeout=10).read()
+        except Exception as e:  # noqa: BLE001
+            log.warning("track failed: %s", e)
+
+    def _start_poll(self) -> None:
+        def loop() -> None:
+            while not self._stop.wait(self._poll_interval):
+                try:
+                    self._fetch_all()
+                except Exception as e:  # noqa: BLE001
+                    log.warning("background poll failed: %s", e)
+        self._thread = threading.Thread(target=loop, daemon=True)
+        self._thread.start()
+
+    def _fetch_all(self) -> None:
+        interval = self._fetch_flags()
+        self._fetch_exps()
+        if interval and interval != self._poll_interval:
+            self._poll_interval = interval
+
+    def _fetch_flags(self) -> Optional[int]:
+        status, headers, body = self._http_get("/sdk/flags", self._flags_etag)
+        interval_str = headers.get("X-Poll-Interval") or headers.get("x-poll-interval")
+        interval = int(interval_str) if interval_str else None
+        if status == 304:
+            return interval
+        if status != 200:
+            raise RuntimeError(f"GET /sdk/flags returned {status}")
+        with self._lock:
+            etag = headers.get("ETag") or headers.get("etag")
+            if etag:
+                self._flags_etag = etag
+            self._flags_blob = json.loads(body)
+        return interval
+
+    def _fetch_exps(self) -> None:
+        status, headers, body = self._http_get("/sdk/experiments", self._exps_etag)
+        if status == 304:
+            return
+        if status != 200:
+            raise RuntimeError(f"GET /sdk/experiments returned {status}")
+        with self._lock:
+            etag = headers.get("ETag") or headers.get("etag")
+            if etag:
+                self._exps_etag = etag
+            self._exps_blob = json.loads(body)
+
+    def _http_get(self, path: str, etag: Optional[str]) -> tuple[int, Mapping[str, str], bytes]:
+        headers = {"X-SDK-Key": self._api_key}
+        if etag:
+            headers["If-None-Match"] = etag
+        req = urllib.request.Request(f"{self._base_url}{path}", headers=headers, method="GET")
+        try:
+            resp = urllib.request.urlopen(req, timeout=10)
+            return resp.status, dict(resp.headers), resp.read()
+        except urllib.error.HTTPError as e:
+            return e.code, dict(e.headers or {}), e.read() if e.fp else b""

shipeasy-0.3.0/shipeasy/_eval.py

@@ -0,0 +1,142 @@
+from dataclasses import dataclass
+from typing import Any, Mapping, Optional
+import re
+
+from ._hash import murmur3
+
+
+@dataclass
+class ExperimentResult:
+    in_experiment: bool
+    group: str
+    params: Optional[Any]
+
+
+def _enabled(v: Any) -> bool:
+    return v == 1 or v is True
+
+
+def _to_num(v: Any) -> Optional[float]:
+    if isinstance(v, bool):
+        return None
+    if isinstance(v, (int, float)):
+        return float(v)
+    if isinstance(v, str):
+        try:
+            return float(v)
+        except ValueError:
+            return None
+    return None
+
+
+def _user_id(user: Mapping[str, Any]) -> Optional[str]:
+    uid = user.get("user_id") or user.get("anonymous_id")
+    return str(uid) if uid else None
+
+
+def match_rule(rule: Mapping[str, Any], user: Mapping[str, Any]) -> bool:
+    attr = rule.get("attr")
+    op = rule.get("op")
+    value = rule.get("value")
+    actual = user.get(attr) if attr else None
+
+    if op == "eq":
+        return actual == value
+    if op == "neq":
+        return actual != value
+    if op == "in":
+        return actual in (value or [])
+    if op == "not_in":
+        return actual not in (value or [])
+    if op == "contains":
+        if isinstance(actual, str) and isinstance(value, str):
+            return value in actual
+        if isinstance(actual, list):
+            return value in actual
+        return False
+    if op == "regex":
+        if isinstance(actual, str) and isinstance(value, str):
+            try:
+                return re.search(value, actual) is not None
+            except re.error:
+                return False
+        return False
+    if op in ("gt", "gte", "lt", "lte"):
+        a = _to_num(actual)
+        b = _to_num(value)
+        if a is None or b is None:
+            return False
+        if op == "gt":
+            return a > b
+        if op == "gte":
+            return a >= b
+        if op == "lt":
+            return a < b
+        return a <= b
+    return False
+
+
+def eval_gate(gate: Mapping[str, Any], user: Mapping[str, Any]) -> bool:
+    if _enabled(gate.get("killswitch")):
+        return False
+    if not _enabled(gate.get("enabled")):
+        return False
+    for rule in gate.get("rules") or []:
+        if not match_rule(rule, user):
+            return False
+    uid = _user_id(user)
+    if not uid:
+        # No unit id (an unidentified request before any anon id is minted): a
+        # fully-rolled gate is on for everyone, so it can be answered without
+        # bucketing; a fractional rollout genuinely needs a stable unit, so deny
+        # until one exists. Rules above are still checked, so targeting wins.
+        # See experiment-platform/18-identity-bucketing.md.
+        return (gate.get("rolloutPct") or 0) >= 10000
+    salt = gate.get("salt") or ""
+    return murmur3(f"{salt}:{uid}") % 10000 < (gate.get("rolloutPct") or 0)
+
+
+_NOT_IN = ExperimentResult(in_experiment=False, group="control", params=None)
+
+
+def eval_experiment(
+    exp: Optional[Mapping[str, Any]],
+    flags_blob: Optional[Mapping[str, Any]],
+    exps_blob: Optional[Mapping[str, Any]],
+    user: Mapping[str, Any],
+) -> ExperimentResult:
+    if not exp or exp.get("status") != "running":
+        return _NOT_IN
+
+    targeting_gate = exp.get("targetingGate")
+    if targeting_gate:
+        gate = (flags_blob or {}).get("gates", {}).get(targeting_gate)
+        if not gate or not eval_gate(gate, user):
+            return _NOT_IN
+
+    uid = _user_id(user)
+    if not uid:
+        return _NOT_IN
+
+    universe_name = exp.get("universe")
+    universe = (exps_blob or {}).get("universes", {}).get(universe_name) if universe_name else None
+    holdout = universe.get("holdout_range") if universe else None
+    if holdout:
+        seg = murmur3(f"{universe_name}:{uid}") % 10000
+        if holdout[0] <= seg <= holdout[1]:
+            return _NOT_IN
+
+    salt = exp.get("salt") or ""
+    alloc_pct = exp.get("allocationPct") or 0
+    if murmur3(f"{salt}:alloc:{uid}") % 10000 >= alloc_pct:
+        return _NOT_IN
+
+    group_hash = murmur3(f"{salt}:group:{uid}") % 10000
+    cumulative = 0
+    groups = exp.get("groups") or []
+    for i, g in enumerate(groups):
+        cumulative += g.get("weight", 0)
+        if group_hash < cumulative or i == len(groups) - 1:
+            return ExperimentResult(in_experiment=True, group=g.get("name", "control"), params=g.get("params"))
+
+    return _NOT_IN

shipeasy-0.3.0/shipeasy/_hash.py

@@ -0,0 +1,49 @@
+_MASK32 = 0xFFFFFFFF
+_C1 = 0xCC9E2D51
+_C2 = 0x1B873593
+
+
+def _rotl(x: int, r: int) -> int:
+    return ((x << r) | (x >> (32 - r))) & _MASK32
+
+
+def _fmix32(h: int) -> int:
+    h ^= h >> 16
+    h = (h * 0x85EBCA6B) & _MASK32
+    h ^= h >> 13
+    h = (h * 0xC2B2AE35) & _MASK32
+    h ^= h >> 16
+    return h
+
+
+def murmur3(key: str, seed: int = 0) -> int:
+    data = key.encode("utf-8")
+    n = len(data)
+    h1 = seed & _MASK32
+    nblocks = n // 4
+    for i in range(nblocks):
+        off = i * 4
+        k1 = data[off] | (data[off + 1] << 8) | (data[off + 2] << 16) | (data[off + 3] << 24)
+        k1 = (k1 * _C1) & _MASK32
+        k1 = _rotl(k1, 15)
+        k1 = (k1 * _C2) & _MASK32
+        h1 ^= k1
+        h1 = _rotl(h1, 13)
+        h1 = ((h1 * 5) + 0xE6546B64) & _MASK32
+
+    tail_idx = nblocks * 4
+    k1 = 0
+    rem = n & 3
+    if rem >= 3:
+        k1 ^= data[tail_idx + 2] << 16
+    if rem >= 2:
+        k1 ^= data[tail_idx + 1] << 8
+    if rem >= 1:
+        k1 ^= data[tail_idx]
+        k1 = (k1 * _C1) & _MASK32
+        k1 = _rotl(k1, 15)
+        k1 = (k1 * _C2) & _MASK32
+        h1 ^= k1
+
+    h1 ^= n
+    return _fmix32(h1)

shipeasy-0.3.0/shipeasy/_telemetry.py

@@ -0,0 +1,67 @@
+"""Per-evaluation usage telemetry.
+
+Fires one fire-and-forget HTTP beacon per evaluation so usage is counted by
+Cloudflare's native per-path analytics (zero storage on our side). Mirrors the
+contract in the TypeScript reference SDK and experiment-platform/15-usage-metering.md.
+
+The path carries sha256(sdk_key) -- never the raw key, so a secret server key
+never lands in edge logs -- plus side/env, then feature/resource. A long-lived
+Python process can emit reliably (unlike Cloudflare Workers), so a daemon thread
+per beacon is fine; the 2s dedup window bounds volume under render/loop storms.
+"""
+from __future__ import annotations
+
+import hashlib
+import threading
+import time
+import urllib.request
+from urllib.parse import quote
+from typing import Dict
+
+DEFAULT_TELEMETRY_URL = "https://t.shipeasy.ai"
+_FEATURES = frozenset({"gate", "config", "ks", "experiment", "event"})
+
+
+class Telemetry:
+    def __init__(
+        self,
+        endpoint: str,
+        sdk_key: str,
+        side: str = "server",
+        env: str = "prod",
+        disabled: bool = False,
+        dedupe_ms: int = 2000,
+    ) -> None:
+        endpoint = (endpoint or "").rstrip("/")
+        self._disabled = disabled or not sdk_key or not endpoint
+        self._dedupe_ms = dedupe_ms
+        self._last: Dict[str, float] = {}
+        self._lock = threading.Lock()
+        if self._disabled:
+            self._prefix = ""
+        else:
+            key_hash = hashlib.sha256(sdk_key.encode("utf-8")).hexdigest()
+            self._prefix = f"{endpoint}/t/{key_hash}/{side}/{quote(env, safe='')}"
+
+    def emit(self, feature: str, resource: str) -> None:
+        """Best-effort usage beacon for one evaluation. Never blocks, never raises."""
+        if self._disabled:
+            return
+        if self._dedupe_ms > 0:
+            dedupe_key = f"{feature}/{resource}"
+            now = time.monotonic() * 1000.0
+            with self._lock:
+                last = self._last.get(dedupe_key)
+                if last is not None and now - last < self._dedupe_ms:
+                    return
+                self._last[dedupe_key] = now
+        url = f"{self._prefix}/{feature}/{quote(resource, safe='')}"
+        threading.Thread(target=_send, args=(url,), daemon=True).start()
+
+
+def _send(url: str) -> None:
+    try:
+        req = urllib.request.Request(url, method="GET")
+        urllib.request.urlopen(req, timeout=2).close()
+    except Exception:  # noqa: BLE001 -- telemetry must never affect the caller
+        pass

shipeasy-0.3.0/shipeasy/middleware.py

@@ -0,0 +1,87 @@
+"""Drop-in WSGI / ASGI middleware that mints the shared ``__se_anon_id`` cookie.
+
+For any request without a valid ``__se_anon_id`` cookie it mints a UUIDv4,
+exposes it for the duration of the request, and ``Set-Cookie``s it on the
+response. Once installed, gate/experiment evaluations with no explicit
+``user_id``/``anonymous_id`` automatically bucket on the cookie id — anonymous
+visitors get stable, SSR/browser-consistent bucketing with zero per-call wiring.
+
+WSGI (Flask, Django, any WSGI app)::
+
+    from shipeasy.middleware import AnonIdMiddleware
+    app.wsgi_app = AnonIdMiddleware(app.wsgi_app)
+
+ASGI (FastAPI, Starlette)::
+
+    from shipeasy.middleware import AnonIdASGIMiddleware
+    app.add_middleware(AnonIdASGIMiddleware)
+"""
+
+from __future__ import annotations
+
+from typing import Callable
+
+from . import _anon_id as anon_id
+
+
+class AnonIdMiddleware:
+    """WSGI middleware."""
+
+    def __init__(self, app: Callable) -> None:
+        self.app = app
+
+    def __call__(self, environ, start_response):
+        anon, minted = anon_id.read_or_mint(environ.get("HTTP_COOKIE"))
+        environ["shipeasy.anon_id"] = anon
+        token = anon_id.set_current(anon)
+
+        def _start_response(status, headers, exc_info=None):
+            if minted:
+                secure = environ.get("wsgi.url_scheme") == "https" or (
+                    environ.get("HTTP_X_FORWARDED_PROTO", "").split(",")[0].strip() == "https"
+                )
+                headers = list(headers) + [("Set-Cookie", anon_id.build_set_cookie(anon, secure))]
+            return start_response(status, headers, exc_info)
+
+        try:
+            return self.app(environ, _start_response)
+        finally:
+            anon_id.reset_current(token)
+
+
+class AnonIdASGIMiddleware:
+    """Pure-ASGI middleware (HTTP scope only; other scopes pass through)."""
+
+    def __init__(self, app) -> None:
+        self.app = app
+
+    async def __call__(self, scope, receive, send):
+        if scope.get("type") != "http":
+            await self.app(scope, receive, send)
+            return
+
+        header = b"".join(
+            v for k, v in scope.get("headers", []) if k == b"cookie"
+        ).decode("latin-1") or None
+        anon, minted = anon_id.read_or_mint(header)
+        token = anon_id.set_current(anon)
+
+        async def _send(message):
+            if minted and message["type"] == "http.response.start":
+                secure = scope.get("scheme") == "https" or _xfp_https(scope)
+                cookie = anon_id.build_set_cookie(anon, secure).encode("latin-1")
+                message = dict(message)
+                message["headers"] = list(message.get("headers", [])) + [(b"set-cookie", cookie)]
+            await send(message)
+
+        try:
+            await self.app(scope, receive, _send)
+        finally:
+            anon_id.reset_current(token)
+
+
+def _xfp_https(scope) -> bool:
+    for k, v in scope.get("headers", []):
+        if k == b"x-forwarded-proto":
+            return v.decode("latin-1").split(",")[0].strip() == "https"
+    return False

shipeasy-0.3.0/tests/test_eval.py

@@ -0,0 +1,31 @@
+from shipeasy._eval import eval_gate
+
+
+# The no-unit evaluation rule is a cross-SDK contract: a request with no unit id
+# answers a fully-rolled gate as on (no bucketing needed) but a fractional gate
+# as off. See experiment-platform/18-identity-bucketing.md.
+def test_no_unit_full_rollout_is_on():
+    assert eval_gate({"enabled": 1, "salt": "s", "rolloutPct": 10000}, {}) is True
+
+
+def test_no_unit_fractional_is_off():
+    assert eval_gate({"enabled": 1, "salt": "s", "rolloutPct": 5000}, {}) is False
+
+
+def test_no_unit_disabled_or_killed_is_off():
+    assert eval_gate({"enabled": 0, "rolloutPct": 10000}, {}) is False
+    assert eval_gate({"enabled": 1, "killswitch": 1, "rolloutPct": 10000}, {}) is False
+
+
+def test_no_unit_targeting_rule_wins():
+    gate = {
+        "enabled": 1, "salt": "s", "rolloutPct": 10000,
+        "rules": [{"attr": "plan", "op": "eq", "value": "pro"}],
+    }
+    assert eval_gate(gate, {}) is False
+    assert eval_gate(gate, {"plan": "pro"}) is True
+
+
+def test_with_unit_unchanged():
+    assert eval_gate({"enabled": 1, "salt": "s", "rolloutPct": 0}, {"user_id": "u1"}) is False
+    assert eval_gate({"enabled": 1, "salt": "s", "rolloutPct": 10000}, {"user_id": "u1"}) is True

shipeasy-0.3.0/tests/test_hash.py

@@ -0,0 +1,20 @@
+from shipeasy import murmur3
+
+
+def test_vectors():
+    # Verified against the Ruby SDK reference impl. Cross-language
+    # consistency is the contract; the table in
+    # experiment-platform/04-evaluation.md disagrees on some inputs and
+    # appears to be unverified.
+    cases = [
+        ("", 0x00000000),
+        ("a", 0x3c2569b2),
+        ("ab", 0x9bbfd75f),
+        ("abc", 0xb3dd93fa),
+        ("aaaa", 0x7eeed987),
+        ("aaaaa", 0xe9ca302b),
+        ("Hello, 世界", 0xe2a131eb),
+        ("The quick brown fox jumps over the lazy dog", 0x2e4ff723),
+    ]
+    for inp, expected in cases:
+        assert murmur3(inp) == expected, inp

shipeasy-0.3.0/tests/test_middleware.py

@@ -0,0 +1,95 @@
+import asyncio
+
+from shipeasy import _anon_id
+from shipeasy.middleware import AnonIdMiddleware, AnonIdASGIMiddleware
+from shipeasy._client import _with_anon_id
+
+
+def _run_wsgi(environ, downstream):
+    captured = {}
+
+    def start_response(status, headers, exc_info=None):
+        captured["status"] = status
+        captured["headers"] = headers
+
+    app = AnonIdMiddleware(lambda env, sr: (downstream(env), sr("200 OK", []), [b"ok"])[-1])
+    list(app(environ, start_response))
+    return captured
+
+
+def _set_cookie(headers):
+    return [v for k, v in headers if k.lower() == "set-cookie"]
+
+
+def test_wsgi_mints_and_sets_cookie():
+    seen = {}
+    cap = _run_wsgi(
+        {"wsgi.url_scheme": "https"},
+        lambda env: seen.update(id=env["shipeasy.anon_id"], cur=_anon_id.current()),
+    )
+    assert _anon_id.is_valid(seen["id"])
+    assert seen["cur"] == seen["id"]
+    cookies = _set_cookie(cap["headers"])
+    assert len(cookies) == 1
+    c = cookies[0]
+    assert f"{_anon_id.COOKIE}={seen['id']}" in c
+    assert "Path=/" in c and "Max-Age=31536000" in c and "SameSite=Lax" in c and "Secure" in c
+    assert "HttpOnly" not in c
+    # ContextVar cleared after the request.
+    assert _anon_id.current() is None
+
+
+def test_wsgi_reuses_existing_cookie():
+    seen = {}
+    cap = _run_wsgi(
+        {"HTTP_COOKIE": f"{_anon_id.COOKIE}=stable-1; other=x"},
+        lambda env: seen.update(id=env["shipeasy.anon_id"]),
+    )
+    assert seen["id"] == "stable-1"
+    assert _set_cookie(cap["headers"]) == []
+
+
+def test_wsgi_mints_on_tampered_cookie():
+    seen = {}
+    _run_wsgi(
+        {"HTTP_COOKIE": f"{_anon_id.COOKIE}=bad value!"},
+        lambda env: seen.update(id=env["shipeasy.anon_id"]),
+    )
+    assert seen["id"] != "bad value!"
+    assert _anon_id.is_valid(seen["id"])
+
+
+def test_with_anon_id_defaulting():
+    token = _anon_id.set_current("anon-xyz")
+    try:
+        assert _with_anon_id({})["anonymous_id"] == "anon-xyz"
+        assert "anonymous_id" not in _with_anon_id({"user_id": "u9"})
+        assert _with_anon_id({"anonymous_id": "caller"})["anonymous_id"] == "caller"
+    finally:
+        _anon_id.reset_current(token)
+    assert _anon_id.current() is None
+
+
+def test_asgi_mints_and_sets_cookie():
+    sent = []
+    seen = {}
+
+    async def downstream(scope, receive, send):
+        seen["cur"] = _anon_id.current()
+        await send({"type": "http.response.start", "status": 200, "headers": []})
+        await send({"type": "http.response.body", "body": b"ok"})
+
+    async def receive():
+        return {"type": "http.request"}
+
+    async def send(m):
+        sent.append(m)
+
+    app = AnonIdASGIMiddleware(downstream)
+    asyncio.run(app({"type": "http", "scheme": "https", "headers": []}, receive, send))
+
+    assert _anon_id.is_valid(seen["cur"])
+    start = next(m for m in sent if m["type"] == "http.response.start")
+    cookies = [v.decode() for k, v in start["headers"] if k == b"set-cookie"]
+    assert len(cookies) == 1 and "SameSite=Lax" in cookies[0] and "Secure" in cookies[0]
+    assert _anon_id.current() is None

shipeasy-0.3.0/tests/test_telemetry.py

@@ -0,0 +1,76 @@
+import hashlib
+
+from shipeasy import _telemetry
+from shipeasy._telemetry import Telemetry
+
+
+def _capture(monkeypatch):
+    sent = []
+    # Run synchronously and record, instead of spawning daemon threads.
+    monkeypatch.setattr(_telemetry, "_send", lambda url: sent.append(url))
+    monkeypatch.setattr(
+        _telemetry.threading,
+        "Thread",
+        lambda target, args, daemon: type("T", (), {"start": lambda self: target(*args)})(),
+    )
+    return sent
+
+
+def test_emit_path_has_hash_not_raw_key(monkeypatch):
+    sent = _capture(monkeypatch)
+    t = Telemetry("https://t.example.com/", "sk_secret", side="server", env="prod")
+    t.emit("gate", "checkout_v2")
+    h = hashlib.sha256(b"sk_secret").hexdigest()
+    assert sent == [f"https://t.example.com/t/{h}/server/prod/gate/checkout_v2"]
+    assert "sk_secret" not in sent[0]
+
+
+def test_percent_encodes_resource(monkeypatch):
+    sent = _capture(monkeypatch)
+    t = Telemetry("https://e.x", "k", side="client", env="prod")
+    t.emit("config", "billing/plan name")
+    assert sent[0].endswith("/config/billing%2Fplan%20name")
+
+
+def test_dedup_window_collapses_repeats(monkeypatch):
+    sent = _capture(monkeypatch)
+    t = Telemetry("https://e.x", "k")
+    for _ in range(50):
+        t.emit("gate", "g")
+    t.emit("gate", "other")
+    assert len(sent) == 2
+
+
+def test_disabled_and_empty_emit_nothing(monkeypatch):
+    sent = _capture(monkeypatch)
+    Telemetry("https://e.x", "k", disabled=True).emit("gate", "g")
+    Telemetry("https://e.x", "").emit("gate", "g")
+    Telemetry("", "k").emit("gate", "g")
+    assert sent == []
+
+
+# 1) basic telemetry send works for each entity call, hitting the right URL.
+def test_client_fires_a_beacon_for_each_entity(monkeypatch):
+    sent = _capture(monkeypatch)
+    from shipeasy import Client
+
+    c = Client("srv_key", base_url="https://e.x")
+    c.get_flag("g", {"user_id": "u"})
+    c.get_config("c")
+    c.get_experiment("e", {"user_id": "u"}, {})
+    assert len(sent) == 3
+    assert any(u.endswith("/gate/g") for u in sent)
+    assert any(u.endswith("/config/c") for u in sent)
+    assert any(u.endswith("/experiment/e") for u in sent)
+
+
+# 2) telemetry is not sent when disabled in settings.
+def test_client_disable_telemetry_sends_nothing(monkeypatch):
+    sent = _capture(monkeypatch)
+    from shipeasy import Client
+
+    c = Client("srv_key", base_url="https://e.x", disable_telemetry=True)
+    c.get_flag("g", {"user_id": "u"})
+    c.get_config("c")
+    c.get_experiment("e", {"user_id": "u"}, {})
+    assert sent == []