shipeasy 0.3.0__py3-none-any.whl

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/_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/_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/_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/_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/_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/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.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,11 @@
+shipeasy/__init__.py,sha256=GCSaKkIvpm764bwJ2ZP39iM7IfpO8cCdZH4dnTlRWx0,278
+shipeasy/_anon_id.py,sha256=Cs1UnhZtQb2e-sXYwutEAgqIx3PhYrLkAUZD6P5imY8,2836
+shipeasy/_client.py,sha256=_8-91KqxX94G7klTsxx_avgNVlQyZlkCMdRM1NFYiHw,7666
+shipeasy/_eval.py,sha256=nR0iNBBF6_160VhBjSzZ3SJ3QV6_m5aIlSQMUmBuMfk,4363
+shipeasy/_hash.py,sha256=jdmuFswvqEhe0-rDLm5d6s8mryBZQJgPsxA70W7CyH4,1135
+shipeasy/_telemetry.py,sha256=gd5B6sXYBJV7LhpFA92_DXBEdeUheTmXVeWMzWgiLp0,2490
+shipeasy/middleware.py,sha256=wezm4JQ3YkOF4hj0dA4OrKJNsKDRGeBijTdkx56yvNw,3041
+shipeasy-0.3.0.dist-info/METADATA,sha256=_oz2JMp3Ze40exlgjtwt9C_L-d9NV9JI-yqxWSBX65I,2510
+shipeasy-0.3.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+shipeasy-0.3.0.dist-info/licenses/LICENSE,sha256=4vaJafqxp44-g9UsxZJOp19rUk9X65skmXxOYIClIY8,1651
+shipeasy-0.3.0.dist-info/RECORD,,

shipeasy-0.3.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

shipeasy-0.3.0.dist-info/licenses/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.