barricator-client 0.1.0__tar.gz

barricator_client-0.1.0/PKG-INFO

@@ -0,0 +1,86 @@
+Metadata-Version: 2.4
+Name: barricator-client
+Version: 0.1.0
+Summary: Barricator production-grade Python Server SDK (local evaluation, SSE sync, telemetry)
+Author: Jorge Spiropulo
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/barricator/barricator-python-client
+Project-URL: Source, https://github.com/barricator/barricator-python-client
+Project-URL: Changelog, https://github.com/barricator/barricator-python-client/blob/main/CHANGELOG.md
+Keywords: feature-flags,barricator,sdk,rollout,ab-testing
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: build>=1.2; extra == "dev"
+
+# barricator-python-client
+
+[![PyPI](https://img.shields.io/pypi/v/barricator-client?label=PyPI)](https://pypi.org/project/barricator-client/)
+
+Production-grade **Python Server SDK** for Barricator. Standard library only (no third-party runtime
+deps), Python 3.9+.
+
+## Install
+
+```bash
+pip install barricator-client
+```
+
+## Guarantees
+
+- **Zero-latency evaluation.** `is_enabled(...)` is a synchronous in-memory dict lookup — no I/O.
+- **Local evaluation** that mirrors the backend engine exactly (incl. MurmurHash3 bucketing —
+  verified byte-identical with the Java SDK).
+- **Real-time sync** over SSE on a daemon thread, with exponential backoff + jitter on disconnect and
+  graceful fallback to cached state.
+- **Async telemetry** flushed every 30s; never blocks the host application.
+- **Two tracks:** synchronous `BarricatorClient` and asyncio-native `AsyncBarricatorClient`.
+
+## Sync usage
+
+```python
+from barricator import BarricatorClient, UserContext
+
+with BarricatorClient("sdk-srv-...", base_url="https://app.barricator.io") as client:
+    user = UserContext("user-123", email="user@enterprise.com", custom={"plan": "pro"})
+    if client.is_enabled("premium-pricing", user):
+        ...
+    theme = client.string_variation("homepage-theme", user, "control")
+```
+
+## Async usage
+
+```python
+from barricator import AsyncBarricatorClient, UserContext
+
+async with await AsyncBarricatorClient.create("sdk-srv-...") as client:
+    user = UserContext("user-123", country="US")
+    enabled = client.is_enabled("beta-feature", user)   # evaluation is sync (in-memory)
+```
+
+## Test
+
+```bash
+python3 -m unittest discover -s tests -v
+```
+
+## Layout
+
+| Module | Responsibility |
+|--------|----------------|
+| `barricator.client` / `barricator.aio` | Sync / async clients |
+| `barricator.evaluation` | Local targeting engine |
+| `barricator.store` | Thread-safe `FlagStore` + `MetricsBuffer` |
+| `barricator.transport` | urllib bootstrap/flush + SSE parsing |
+| `barricator.murmur` | MurmurHash3 (cross-SDK consistent) |
+| `barricator.context` | `UserContext` |

barricator_client-0.1.0/README.md

@@ -0,0 +1,61 @@
+# barricator-python-client
+
+[![PyPI](https://img.shields.io/pypi/v/barricator-client?label=PyPI)](https://pypi.org/project/barricator-client/)
+
+Production-grade **Python Server SDK** for Barricator. Standard library only (no third-party runtime
+deps), Python 3.9+.
+
+## Install
+
+```bash
+pip install barricator-client
+```
+
+## Guarantees
+
+- **Zero-latency evaluation.** `is_enabled(...)` is a synchronous in-memory dict lookup — no I/O.
+- **Local evaluation** that mirrors the backend engine exactly (incl. MurmurHash3 bucketing —
+  verified byte-identical with the Java SDK).
+- **Real-time sync** over SSE on a daemon thread, with exponential backoff + jitter on disconnect and
+  graceful fallback to cached state.
+- **Async telemetry** flushed every 30s; never blocks the host application.
+- **Two tracks:** synchronous `BarricatorClient` and asyncio-native `AsyncBarricatorClient`.
+
+## Sync usage
+
+```python
+from barricator import BarricatorClient, UserContext
+
+with BarricatorClient("sdk-srv-...", base_url="https://app.barricator.io") as client:
+    user = UserContext("user-123", email="user@enterprise.com", custom={"plan": "pro"})
+    if client.is_enabled("premium-pricing", user):
+        ...
+    theme = client.string_variation("homepage-theme", user, "control")
+```
+
+## Async usage
+
+```python
+from barricator import AsyncBarricatorClient, UserContext
+
+async with await AsyncBarricatorClient.create("sdk-srv-...") as client:
+    user = UserContext("user-123", country="US")
+    enabled = client.is_enabled("beta-feature", user)   # evaluation is sync (in-memory)
+```
+
+## Test
+
+```bash
+python3 -m unittest discover -s tests -v
+```
+
+## Layout
+
+| Module | Responsibility |
+|--------|----------------|
+| `barricator.client` / `barricator.aio` | Sync / async clients |
+| `barricator.evaluation` | Local targeting engine |
+| `barricator.store` | Thread-safe `FlagStore` + `MetricsBuffer` |
+| `barricator.transport` | urllib bootstrap/flush + SSE parsing |
+| `barricator.murmur` | MurmurHash3 (cross-SDK consistent) |
+| `barricator.context` | `UserContext` |

barricator_client-0.1.0/barricator/__init__.py

@@ -0,0 +1,11 @@
+"""Barricator Python Server SDK.
+
+Local evaluation, SSE synchronization, MurmurHash3 rollout bucketing, and async telemetry, with both
+synchronous (:class:`BarricatorClient`) and asyncio (:class:`AsyncBarricatorClient`) tracks.
+"""
+from .aio import AsyncBarricatorClient
+from .client import BarricatorClient
+from .context import UserContext
+
+__all__ = ["BarricatorClient", "AsyncBarricatorClient", "UserContext"]
+__version__ = "0.1.0"

barricator_client-0.1.0/barricator/aio.py

@@ -0,0 +1,168 @@
+"""Asyncio-native Barricator server SDK client.
+
+Evaluation stays synchronous (it is a pure in-memory O(1) lookup — there is nothing to await), but
+all network I/O is non-blocking: the initial bootstrap and periodic flush run via ``asyncio.to_thread``
+and an ``asyncio`` task, while the blocking SSE iteration runs on a dedicated daemon thread that feeds
+the shared, thread-safe store.
+"""
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import random
+import threading
+from typing import Any, Optional
+
+from . import evaluation
+from .context import UserContext
+from .store import FlagStore, MetricsBuffer
+from .transport import Transport
+
+logger = logging.getLogger("barricator.aio")
+
+
+class AsyncBarricatorClient:
+    def __init__(
+        self,
+        sdk_key: str,
+        base_url: str = "https://app.barricator.io",
+        *,
+        streaming_enabled: bool = True,
+        metrics_enabled: bool = True,
+        metrics_flush_interval: float = 30.0,
+        bootstrap_timeout: float = 5.0,
+        initial_reconnect_delay: float = 1.0,
+        max_reconnect_delay: float = 60.0,
+    ) -> None:
+        if not sdk_key:
+            raise ValueError("sdk_key is required")
+        self._transport = Transport(base_url, sdk_key)
+        self._store = FlagStore()
+        self._metrics = MetricsBuffer()
+        self._streaming_enabled = streaming_enabled
+        self._metrics_enabled = metrics_enabled
+        self._metrics_flush_interval = metrics_flush_interval
+        self._bootstrap_timeout = bootstrap_timeout
+        self._initial_reconnect_delay = initial_reconnect_delay
+        self._max_reconnect_delay = max_reconnect_delay
+
+        self._closed = threading.Event()
+        self._sse_conn: Optional[Any] = None
+        self._sse_thread: Optional[threading.Thread] = None
+        self._flush_task: Optional[asyncio.Task] = None
+
+    @classmethod
+    async def create(cls, sdk_key: str, base_url: str = "https://app.barricator.io", **kwargs: Any) -> "AsyncBarricatorClient":
+        client = cls(sdk_key, base_url, **kwargs)
+        await client.start()
+        return client
+
+    async def start(self) -> None:
+        await self._safe_bootstrap()
+        if self._streaming_enabled:
+            self._sse_thread = threading.Thread(target=self._stream_loop, name="barricator-sse", daemon=True)
+            self._sse_thread.start()
+        if self._metrics_enabled:
+            self._flush_task = asyncio.create_task(self._flush_loop())
+
+    # --- synchronous, in-memory evaluation (no await needed) ---
+
+    def is_enabled(self, flag_key: str, user: UserContext, default: bool = False) -> bool:
+        value = self._evaluate(flag_key, user, default).value
+        return value if isinstance(value, bool) else default
+
+    def string_variation(self, flag_key: str, user: UserContext, default: str) -> str:
+        value = self._evaluate(flag_key, user, default).value
+        return default if value is None else str(value)
+
+    def number_variation(self, flag_key: str, user: UserContext, default: float) -> float:
+        value = self._evaluate(flag_key, user, default).value
+        try:
+            return float(value) if value is not None else default
+        except (TypeError, ValueError):
+            return default
+
+    def json_variation(self, flag_key: str, user: UserContext, default: Any) -> Any:
+        return self._evaluate(flag_key, user, default).value
+
+    @property
+    def initialized(self) -> bool:
+        return self._store.initialized
+
+    def _evaluate(self, flag_key: str, user: UserContext, fallback: Any) -> evaluation.EvaluationResult:
+        result = evaluation.evaluate(self._store.get(flag_key), user, fallback)
+        if self._metrics_enabled:
+            self._metrics.record(flag_key, result.variation_id, result.is_defaulted)
+        return result
+
+    # --- lifecycle ---
+
+    async def _safe_bootstrap(self) -> None:
+        try:
+            resp = await asyncio.to_thread(self._transport.bootstrap, self._bootstrap_timeout)
+            flags = {f["key"]: f for f in (resp.get("flags") or [])}
+            self._store.replace_all(flags, int(resp.get("rulesVersion", 0)))
+        except Exception as exc:  # noqa: BLE001
+            logger.warning("Async bootstrap failed (%s); serving cached/defaults", exc)
+
+    def _stream_loop(self) -> None:
+        delay = self._initial_reconnect_delay
+        while not self._closed.is_set():
+            try:
+                conn = self._transport.open_stream()
+                self._sse_conn = conn
+                delay = self._initial_reconnect_delay
+                for evt in conn.events():
+                    if self._closed.is_set():
+                        break
+                    self._apply_event(evt)
+            except Exception as exc:  # noqa: BLE001
+                if self._closed.is_set():
+                    break
+                logger.debug("SSE disconnected (%s); reconnecting in %.1fs", exc, delay)
+                self._closed.wait(delay + random.uniform(0, delay / 2))
+                delay = min(delay * 2, self._max_reconnect_delay)
+
+    def _apply_event(self, evt: dict) -> None:
+        if evt.get("event") != "flag-change":
+            return
+        try:
+            payload = json.loads(evt["data"])
+            if payload.get("type") == "DELETE":
+                self._store.remove(payload.get("flagKey"))
+            elif payload.get("flag"):
+                self._store.upsert(payload["flag"])
+        except Exception as exc:  # noqa: BLE001
+            logger.debug("Failed to apply SSE delta: %s", exc)
+
+    async def _flush_loop(self) -> None:
+        try:
+            while not self._closed.is_set():
+                await asyncio.sleep(self._metrics_flush_interval)
+                await self.flush()
+        except asyncio.CancelledError:
+            pass
+
+    async def flush(self) -> None:
+        events = self._metrics.drain()
+        if events:
+            try:
+                await asyncio.to_thread(self._transport.flush_metrics, events)
+            except Exception as exc:  # noqa: BLE001
+                logger.debug("Async metrics flush failed: %s", exc)
+
+    async def aclose(self) -> None:
+        self._closed.set()
+        if self._flush_task is not None:
+            self._flush_task.cancel()
+        if self._sse_conn is not None:
+            self._sse_conn.close()
+        await self.flush()
+
+    async def __aenter__(self) -> "AsyncBarricatorClient":
+        await self.start()
+        return self
+
+    async def __aexit__(self, *exc: Any) -> None:
+        await self.aclose()

barricator_client-0.1.0/barricator/client.py

@@ -0,0 +1,167 @@
+"""Synchronous Barricator server SDK client."""
+from __future__ import annotations
+
+import logging
+import random
+import threading
+import time
+from typing import Any, Optional
+
+from . import evaluation
+from .context import UserContext
+from .store import FlagStore, MetricsBuffer
+from .transport import Transport
+
+logger = logging.getLogger("barricator")
+
+
+class BarricatorClient:
+    """Server SDK client.
+
+    Evaluation methods are synchronous, in-memory, and never perform I/O or raise. A daemon thread
+    keeps the cache fresh via SSE (with exponential backoff on disconnect), and another daemon thread
+    flushes aggregated telemetry every ``metrics_flush_interval`` seconds. Use as a context manager
+    or call :meth:`close`.
+    """
+
+    def __init__(
+        self,
+        sdk_key: str,
+        base_url: str = "https://app.barricator.io",
+        *,
+        streaming_enabled: bool = True,
+        metrics_enabled: bool = True,
+        metrics_flush_interval: float = 30.0,
+        bootstrap_timeout: float = 5.0,
+        initial_reconnect_delay: float = 1.0,
+        max_reconnect_delay: float = 60.0,
+    ) -> None:
+        if not sdk_key:
+            raise ValueError("sdk_key is required")
+        self._transport = Transport(base_url, sdk_key)
+        self._store = FlagStore()
+        self._metrics = MetricsBuffer()
+        self._metrics_enabled = metrics_enabled
+        self._metrics_flush_interval = metrics_flush_interval
+        self._bootstrap_timeout = bootstrap_timeout
+        self._initial_reconnect_delay = initial_reconnect_delay
+        self._max_reconnect_delay = max_reconnect_delay
+
+        self._closed = threading.Event()
+        self._sse_conn = None  # type: Optional[Any]
+
+        self._safe_bootstrap()
+        if streaming_enabled:
+            self._sse_thread = threading.Thread(target=self._stream_loop, name="barricator-sse", daemon=True)
+            self._sse_thread.start()
+        if metrics_enabled:
+            self._flush_thread = threading.Thread(target=self._flush_loop, name="barricator-metrics", daemon=True)
+            self._flush_thread.start()
+
+    # --- public evaluation API ---
+
+    def is_enabled(self, flag_key: str, user: UserContext, default: bool = False) -> bool:
+        value = self._evaluate(flag_key, user, default).value
+        return value if isinstance(value, bool) else default
+
+    def bool_variation(self, flag_key: str, user: UserContext, default: bool) -> bool:
+        return self.is_enabled(flag_key, user, default)
+
+    def string_variation(self, flag_key: str, user: UserContext, default: str) -> str:
+        value = self._evaluate(flag_key, user, default).value
+        return default if value is None else str(value)
+
+    def number_variation(self, flag_key: str, user: UserContext, default: float) -> float:
+        value = self._evaluate(flag_key, user, default).value
+        try:
+            return float(value) if value is not None else default
+        except (TypeError, ValueError):
+            return default
+
+    def json_variation(self, flag_key: str, user: UserContext, default: Any) -> Any:
+        return self._evaluate(flag_key, user, default).value
+
+    @property
+    def initialized(self) -> bool:
+        return self._store.initialized
+
+    def _evaluate(self, flag_key: str, user: UserContext, fallback: Any) -> evaluation.EvaluationResult:
+        flag = self._store.get(flag_key)
+        result = evaluation.evaluate(flag, user, fallback)
+        if self._metrics_enabled:
+            self._metrics.record(flag_key, result.variation_id, result.is_defaulted)
+        return result
+
+    # --- lifecycle ---
+
+    def _safe_bootstrap(self) -> None:
+        try:
+            resp = self._transport.bootstrap(timeout=self._bootstrap_timeout)
+            flags = {f["key"]: f for f in (resp.get("flags") or [])}
+            self._store.replace_all(flags, int(resp.get("rulesVersion", 0)))
+            logger.debug("Barricator bootstrap: %d flags (v%s)", len(flags), resp.get("rulesVersion"))
+        except Exception as exc:  # noqa: BLE001 - never fatal
+            logger.warning("Barricator bootstrap failed (%s); serving cached/defaults", exc)
+
+    def _stream_loop(self) -> None:
+        delay = self._initial_reconnect_delay
+        while not self._closed.is_set():
+            try:
+                conn = self._transport.open_stream()
+                self._sse_conn = conn
+                # Reconnected: re-bootstrap to recover any deltas missed while offline.
+                self._safe_bootstrap()
+                delay = self._initial_reconnect_delay
+                for evt in conn.events():
+                    if self._closed.is_set():
+                        break
+                    self._apply_event(evt)
+            except Exception as exc:  # noqa: BLE001
+                if self._closed.is_set():
+                    break
+                logger.debug("SSE disconnected (%s); reconnecting in %.1fs", exc, delay)
+                self._sleep_with_jitter(delay)
+                delay = min(delay * 2, self._max_reconnect_delay)
+
+    def _apply_event(self, evt: dict) -> None:
+        if evt.get("event") != "flag-change":
+            return
+        try:
+            import json
+
+            payload = json.loads(evt["data"])
+            if payload.get("type") == "DELETE":
+                self._store.remove(payload.get("flagKey"))
+            else:
+                flag = payload.get("flag")
+                if flag:
+                    self._store.upsert(flag)
+        except Exception as exc:  # noqa: BLE001
+            logger.debug("Failed to apply SSE delta: %s", exc)
+
+    def _flush_loop(self) -> None:
+        while not self._closed.wait(self._metrics_flush_interval):
+            self.flush()
+
+    def flush(self) -> None:
+        try:
+            events = self._metrics.drain()
+            if events:
+                self._transport.flush_metrics(events)
+        except Exception as exc:  # noqa: BLE001
+            logger.debug("Metrics flush failed: %s", exc)
+
+    def _sleep_with_jitter(self, base: float) -> None:
+        self._closed.wait(base + random.uniform(0, base / 2))
+
+    def close(self) -> None:
+        self._closed.set()
+        if self._sse_conn is not None:
+            self._sse_conn.close()
+        self.flush()
+
+    def __enter__(self) -> "BarricatorClient":
+        return self
+
+    def __exit__(self, *exc: Any) -> None:
+        self.close()

barricator_client-0.1.0/barricator/context.py

@@ -0,0 +1,46 @@
+"""User context passed to evaluation."""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, Optional
+
+_BUILTINS = {"key", "name", "email", "country", "anonymous"}
+
+
+@dataclass(frozen=True)
+class UserContext:
+    """The evaluation subject.
+
+    ``key`` is the stable identity used for deterministic percentage rollouts and must be consistent
+    across calls for a given subject. Custom attributes are addressable by targeting clauses.
+    """
+
+    key: str
+    name: Optional[str] = None
+    email: Optional[str] = None
+    country: Optional[str] = None
+    anonymous: bool = False
+    custom: Dict[str, Any] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        if not self.key:
+            raise ValueError("UserContext.key must be a non-empty string")
+
+    def attribute(self, attribute: str) -> Any:
+        """Resolve an attribute by clause name (built-ins take precedence over custom)."""
+        if attribute == "key":
+            return self.key
+        if attribute == "name":
+            return self.name
+        if attribute == "email":
+            return self.email
+        if attribute == "country":
+            return self.country
+        if attribute == "anonymous":
+            return self.anonymous
+        return self.custom.get(attribute)
+
+    def has_attribute(self, attribute: str) -> bool:
+        if attribute in _BUILTINS:
+            return self.attribute(attribute) is not None
+        return attribute in self.custom

barricator_client-0.1.0/barricator/evaluation.py

@@ -0,0 +1,185 @@
+"""Pure, synchronous targeting evaluator — a faithful port of the backend engine."""
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from typing import Any, Dict, List, Optional
+
+from .context import UserContext
+from .murmur import bucket_100k
+
+REASON_OFF = "OFF"
+REASON_RULE_MATCH = "RULE_MATCH"
+REASON_FALLTHROUGH = "FALLTHROUGH"
+REASON_FLAG_NOT_FOUND = "FLAG_NOT_FOUND"
+REASON_ERROR = "ERROR"
+
+_DEFAULTED_REASONS = {REASON_FLAG_NOT_FOUND, REASON_ERROR}
+
+
+@dataclass
+class EvaluationResult:
+    value: Any
+    variation_id: Optional[str]
+    reason: str
+
+    @property
+    def is_defaulted(self) -> bool:
+        return self.reason in _DEFAULTED_REASONS
+
+
+def evaluate(flag: Optional[Dict[str, Any]], ctx: UserContext, fallback: Any) -> EvaluationResult:
+    """Evaluate a flag (raw dict from the ruleset) for a user. Never raises."""
+    if flag is None:
+        return EvaluationResult(fallback, None, REASON_FLAG_NOT_FOUND)
+    try:
+        if not flag.get("on", False):
+            return _served(flag, flag.get("offVariationId"), REASON_OFF, fallback)
+
+        for rule in flag.get("rules") or []:
+            if _rule_matches(rule, ctx):
+                if rule.get("rollout"):
+                    variation_id = _bucket(flag["key"], rule["rollout"], ctx)
+                else:
+                    variation_id = rule.get("variationId")
+                return _served(flag, variation_id, REASON_RULE_MATCH, fallback)
+
+        fallthrough_rollout = flag.get("fallthroughRollout")
+        if fallthrough_rollout:
+            variation_id = _bucket(flag["key"], fallthrough_rollout, ctx)
+            return _served(flag, variation_id, REASON_FALLTHROUGH, fallback)
+        return _served(flag, flag.get("fallthroughVariationId"), REASON_FALLTHROUGH, fallback)
+    except Exception:  # noqa: BLE001 - evaluation must never propagate
+        return EvaluationResult(fallback, None, REASON_ERROR)
+
+
+def _served(flag: Dict[str, Any], variation_id: Optional[str], reason: str, fallback: Any) -> EvaluationResult:
+    value = _variation_value(flag, variation_id)
+    if value is _MISSING:
+        value = flag.get("defaultValue", fallback)
+        if value is None:
+            value = fallback
+    return EvaluationResult(value, variation_id, reason)
+
+
+_MISSING = object()
+
+
+def _variation_value(flag: Dict[str, Any], variation_id: Optional[str]) -> Any:
+    if variation_id is None:
+        return _MISSING
+    for variation in flag.get("variations") or []:
+        if variation.get("id") == variation_id:
+            return variation.get("value")
+    return _MISSING
+
+
+def _bucket(flag_key: str, rollout: Dict[str, Any], ctx: UserContext) -> Optional[str]:
+    weighted: List[Dict[str, Any]] = rollout.get("variations") or []
+    if not weighted:
+        return None
+    bucket_by = rollout.get("bucketBy") or "key"
+    attr = ctx.attribute(bucket_by)
+    bucket_by_value = str(attr) if attr is not None else ctx.key
+    b = bucket_100k(flag_key, rollout.get("salt") or "", bucket_by_value)
+    cumulative = 0
+    for wv in weighted:
+        cumulative += int(wv.get("weight", 0))
+        if b < cumulative:
+            return wv.get("variationId")
+    return weighted[-1].get("variationId")
+
+
+def _rule_matches(rule: Dict[str, Any], ctx: UserContext) -> bool:
+    clauses = rule.get("clauses") or []
+    if not clauses:
+        return False
+    return all(_clause_matches(c, ctx) for c in clauses)
+
+
+def _clause_matches(clause: Dict[str, Any], ctx: UserContext) -> bool:
+    attr = ctx.attribute(clause.get("attribute"))
+    result = attr is not None and _apply_operator(clause.get("op"), attr, clause.get("values") or [])
+    return clause.get("negate", False) != result
+
+
+def _apply_operator(op: Optional[str], attr: Any, values: List[Any]) -> bool:
+    if not op:
+        return False
+    s = lambda x: "" if x is None else str(x)  # noqa: E731
+    if op == "IN":
+        return any(_loose_eq(attr, v) for v in values)
+    if op == "NOT_IN":
+        return all(not _loose_eq(attr, v) for v in values)
+    if op == "EQUALS":
+        return bool(values) and _loose_eq(attr, values[0])
+    if op == "NOT_EQUALS":
+        return not values or not _loose_eq(attr, values[0])
+    if op == "CONTAINS":
+        return any(s(v) in s(attr) for v in values)
+    if op == "NOT_CONTAINS":
+        return all(s(v) not in s(attr) for v in values)
+    if op == "STARTS_WITH":
+        return any(s(attr).startswith(s(v)) for v in values)
+    if op == "ENDS_WITH":
+        return any(s(attr).endswith(s(v)) for v in values)
+    if op == "MATCHES_REGEX":
+        return any(_safe_regex(s(attr), s(v)) for v in values)
+    if op in ("GREATER_THAN", "AFTER"):
+        return _cmp_num(attr, values) > 0
+    if op == "GREATER_THAN_OR_EQUAL":
+        return _cmp_num(attr, values) >= 0
+    if op in ("LESS_THAN", "BEFORE"):
+        return _cmp_num(attr, values) < 0
+    if op == "LESS_THAN_OR_EQUAL":
+        return _cmp_num(attr, values) <= 0
+    if op == "SEMVER_EQUAL":
+        return _cmp_semver(attr, values) == 0
+    if op == "SEMVER_GREATER_THAN":
+        return _cmp_semver(attr, values) > 0
+    if op == "SEMVER_LESS_THAN":
+        return _cmp_semver(attr, values) < 0
+    return False
+
+
+def _loose_eq(a: Any, b: Any) -> bool:
+    if a is None or b is None:
+        return a is b
+    if isinstance(a, (int, float)) and isinstance(b, (int, float)):
+        return float(a) == float(b)
+    return a == b or str(a) == str(b)
+
+
+def _safe_regex(value: str, pattern: str) -> bool:
+    try:
+        return re.search(pattern, value) is not None
+    except re.error:
+        return False
+
+
+def _cmp_num(attr: Any, values: List[Any]) -> int:
+    if not values:
+        return 0
+    try:
+        a, b = float(attr), float(values[0])
+        return (a > b) - (a < b)
+    except (TypeError, ValueError):
+        return 0
+
+
+def _parse_semver(v: str) -> List[int]:
+    core = re.split(r"[-+]", str(v))[0]
+    parts = [0, 0, 0]
+    for i, piece in enumerate(core.split(".")[:3]):
+        try:
+            parts[i] = int(piece.strip())
+        except ValueError:
+            parts[i] = 0
+    return parts
+
+
+def _cmp_semver(attr: Any, values: List[Any]) -> int:
+    if not values:
+        return 0
+    a, b = _parse_semver(attr), _parse_semver(values[0])
+    return (a > b) - (a < b)

barricator_client-0.1.0/barricator/murmur.py

@@ -0,0 +1,78 @@
+"""MurmurHash3 (x86 32-bit).
+
+Bit-for-bit compatible with the Java/backend implementation so a user buckets into the same
+variation across every SDK. Bucketing hashes ``"<flag_key>.<salt>.<bucket_by_value>"``.
+"""
+
+_C1 = 0xCC9E2D51
+_C2 = 0x1B873593
+_MASK = 0xFFFFFFFF
+
+
+def _rotl32(x: int, r: int) -> int:
+    x &= _MASK
+    return ((x << r) | (x >> (32 - r))) & _MASK
+
+
+def _fmix(h: int) -> int:
+    h ^= h >> 16
+    h = (h * 0x85EBCA6B) & _MASK
+    h ^= h >> 13
+    h = (h * 0xC2B2AE35) & _MASK
+    h ^= h >> 16
+    return h & _MASK
+
+
+def hash32(data: bytes, seed: int = 0) -> int:
+    """Return the signed 32-bit MurmurHash3 (matching Java's ``int`` result)."""
+    h1 = seed & _MASK
+    length = len(data)
+    rounded_end = length & 0xFFFFFFFC
+
+    for i in range(0, rounded_end, 4):
+        k1 = (data[i] & 0xFF) \
+            | ((data[i + 1] & 0xFF) << 8) \
+            | ((data[i + 2] & 0xFF) << 16) \
+            | ((data[i + 3] & 0xFF) << 24)
+        k1 = (k1 * _C1) & _MASK
+        k1 = _rotl32(k1, 15)
+        k1 = (k1 * _C2) & _MASK
+        h1 ^= k1
+        h1 = _rotl32(h1, 13)
+        h1 = (h1 * 5 + 0xE6546B64) & _MASK
+
+    k1 = 0
+    tail = length & 0x03
+    if tail == 3:
+        k1 = (data[rounded_end + 2] & 0xFF) << 16
+    if tail >= 2:
+        k1 |= (data[rounded_end + 1] & 0xFF) << 8
+    if tail >= 1:
+        k1 |= (data[rounded_end] & 0xFF)
+        k1 = (k1 * _C1) & _MASK
+        k1 = _rotl32(k1, 15)
+        k1 = (k1 * _C2) & _MASK
+        h1 ^= k1
+
+    h1 ^= length
+    h1 = _fmix(h1)
+
+    # Convert to signed 32-bit so that ``% n`` matches Java's Math.floorMod(signedInt, n).
+    if h1 >= 0x80000000:
+        h1 -= 0x100000000
+    return h1
+
+
+def _unsigned_hash(flag_key: str, salt: str, bucket_by: str) -> int:
+    composite = f"{flag_key}.{salt or ''}.{bucket_by}"
+    return hash32(composite.encode("utf-8"), 0)
+
+
+def bucket_0_to_99(flag_key: str, salt: str, bucket_by: str) -> int:
+    """Deterministic bucket in ``[0, 100)``."""
+    return _unsigned_hash(flag_key, salt, bucket_by) % 100
+
+
+def bucket_100k(flag_key: str, salt: str, bucket_by: str) -> int:
+    """Deterministic bucket in ``[0, 100000)`` for sub-percent rollouts."""
+    return _unsigned_hash(flag_key, salt, bucket_by) % 100_000

barricator_client-0.1.0/barricator/store.py

@@ -0,0 +1,78 @@
+"""Thread-safe in-memory flag store and metrics buffer."""
+from __future__ import annotations
+
+import threading
+from typing import Any, Dict, List, Optional, Tuple
+
+
+class FlagStore:
+    """Holds the environment ruleset. Reads are guarded by an ``RLock`` for consistency under
+    concurrent SSE updates; lookups are O(1) dict access."""
+
+    def __init__(self) -> None:
+        self._lock = threading.RLock()
+        self._flags: Dict[str, Dict[str, Any]] = {}
+        self._rules_version = 0
+        self._initialized = False
+
+    def get(self, key: str) -> Optional[Dict[str, Any]]:
+        with self._lock:
+            return self._flags.get(key)
+
+    @property
+    def initialized(self) -> bool:
+        with self._lock:
+            return self._initialized
+
+    @property
+    def rules_version(self) -> int:
+        with self._lock:
+            return self._rules_version
+
+    def replace_all(self, flags: Dict[str, Dict[str, Any]], version: int) -> None:
+        with self._lock:
+            self._flags = dict(flags)
+            self._rules_version = version
+            self._initialized = True
+
+    def upsert(self, flag: Dict[str, Any]) -> None:
+        if not flag or not flag.get("key"):
+            return
+        with self._lock:
+            self._flags[flag["key"]] = flag
+            self._rules_version = max(self._rules_version, int(flag.get("version", 0)))
+            self._initialized = True
+
+    def remove(self, key: Optional[str]) -> None:
+        if not key:
+            return
+        with self._lock:
+            self._flags.pop(key, None)
+
+
+class MetricsBuffer:
+    """Lock-guarded aggregation of evaluation counts keyed by (flag, variation, defaulted)."""
+
+    def __init__(self) -> None:
+        self._lock = threading.Lock()
+        self._counts: Dict[Tuple[str, Optional[str], bool], int] = {}
+
+    def record(self, flag_key: str, variation_id: Optional[str], defaulted: bool) -> None:
+        key = (flag_key, variation_id, defaulted)
+        with self._lock:
+            self._counts[key] = self._counts.get(key, 0) + 1
+
+    def drain(self) -> List[Dict[str, Any]]:
+        with self._lock:
+            snapshot = self._counts
+            self._counts = {}
+        return [
+            {
+                "flagKey": flag_key,
+                "variationId": variation_id,
+                "count": count,
+                "defaulted": defaulted,
+            }
+            for (flag_key, variation_id, defaulted), count in snapshot.items()
+            if count > 0
+        ]

barricator_client-0.1.0/barricator/transport.py

@@ -0,0 +1,83 @@
+"""HTTP transport using only the standard library (urllib)."""
+from __future__ import annotations
+
+import json
+import urllib.error
+import urllib.request
+from typing import Any, Dict, Iterator, List, Optional
+
+
+class Transport:
+    """Bootstrap + metrics flush (request/response) and SSE line streaming, over urllib."""
+
+    def __init__(self, base_url: str, sdk_key: str, connect_timeout: float = 10.0) -> None:
+        self._base_url = base_url.rstrip("/")
+        self._sdk_key = sdk_key
+        self._connect_timeout = connect_timeout
+
+    def _headers(self, accept: str) -> Dict[str, str]:
+        return {"Authorization": f"Bearer {self._sdk_key}", "Accept": accept}
+
+    def bootstrap(self, timeout: float = 5.0) -> Dict[str, Any]:
+        req = urllib.request.Request(
+            f"{self._base_url}/api/v1/flags/bootstrap",
+            headers=self._headers("application/json"),
+            method="GET",
+        )
+        with urllib.request.urlopen(req, timeout=timeout) as resp:
+            return json.loads(resp.read().decode("utf-8"))
+
+    def flush_metrics(self, events: List[Dict[str, Any]], timeout: float = 10.0) -> bool:
+        body = json.dumps({"events": events}).encode("utf-8")
+        headers = self._headers("application/json")
+        headers["Content-Type"] = "application/json"
+        req = urllib.request.Request(
+            f"{self._base_url}/api/v1/metrics/flush",
+            data=body,
+            headers=headers,
+            method="POST",
+        )
+        try:
+            with urllib.request.urlopen(req, timeout=timeout) as resp:
+                return 200 <= resp.status < 300
+        except urllib.error.HTTPError:
+            return False
+
+    def open_stream(self) -> "SseConnection":
+        """Open the SSE stream. Caller iterates events and must close the connection."""
+        req = urllib.request.Request(
+            f"{self._base_url}/api/v1/flags/stream",
+            headers=self._headers("text/event-stream"),
+            method="GET",
+        )
+        resp = urllib.request.urlopen(req, timeout=self._connect_timeout)
+        return SseConnection(resp)
+
+
+class SseConnection:
+    """Parses a Server-Sent Events byte stream into (event, data) tuples."""
+
+    def __init__(self, response: Any) -> None:
+        self._response = response
+
+    def events(self) -> Iterator[Dict[str, Optional[str]]]:
+        event: Optional[str] = None
+        data_parts: List[str] = []
+        for raw in self._response:
+            line = raw.decode("utf-8").rstrip("\n").rstrip("\r")
+            if line == "":
+                if event is not None and data_parts:
+                    yield {"event": event, "data": "".join(data_parts)}
+                event, data_parts = None, []
+            elif line.startswith(":"):
+                continue  # heartbeat/comment
+            elif line.startswith("event:"):
+                event = line[len("event:"):].strip()
+            elif line.startswith("data:"):
+                data_parts.append(line[len("data:"):].strip())
+
+    def close(self) -> None:
+        try:
+            self._response.close()
+        except Exception:  # noqa: BLE001
+            pass

barricator_client-0.1.0/barricator_client.egg-info/PKG-INFO

@@ -0,0 +1,86 @@
+Metadata-Version: 2.4
+Name: barricator-client
+Version: 0.1.0
+Summary: Barricator production-grade Python Server SDK (local evaluation, SSE sync, telemetry)
+Author: Jorge Spiropulo
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/barricator/barricator-python-client
+Project-URL: Source, https://github.com/barricator/barricator-python-client
+Project-URL: Changelog, https://github.com/barricator/barricator-python-client/blob/main/CHANGELOG.md
+Keywords: feature-flags,barricator,sdk,rollout,ab-testing
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: build>=1.2; extra == "dev"
+
+# barricator-python-client
+
+[![PyPI](https://img.shields.io/pypi/v/barricator-client?label=PyPI)](https://pypi.org/project/barricator-client/)
+
+Production-grade **Python Server SDK** for Barricator. Standard library only (no third-party runtime
+deps), Python 3.9+.
+
+## Install
+
+```bash
+pip install barricator-client
+```
+
+## Guarantees
+
+- **Zero-latency evaluation.** `is_enabled(...)` is a synchronous in-memory dict lookup — no I/O.
+- **Local evaluation** that mirrors the backend engine exactly (incl. MurmurHash3 bucketing —
+  verified byte-identical with the Java SDK).
+- **Real-time sync** over SSE on a daemon thread, with exponential backoff + jitter on disconnect and
+  graceful fallback to cached state.
+- **Async telemetry** flushed every 30s; never blocks the host application.
+- **Two tracks:** synchronous `BarricatorClient` and asyncio-native `AsyncBarricatorClient`.
+
+## Sync usage
+
+```python
+from barricator import BarricatorClient, UserContext
+
+with BarricatorClient("sdk-srv-...", base_url="https://app.barricator.io") as client:
+    user = UserContext("user-123", email="user@enterprise.com", custom={"plan": "pro"})
+    if client.is_enabled("premium-pricing", user):
+        ...
+    theme = client.string_variation("homepage-theme", user, "control")
+```
+
+## Async usage
+
+```python
+from barricator import AsyncBarricatorClient, UserContext
+
+async with await AsyncBarricatorClient.create("sdk-srv-...") as client:
+    user = UserContext("user-123", country="US")
+    enabled = client.is_enabled("beta-feature", user)   # evaluation is sync (in-memory)
+```
+
+## Test
+
+```bash
+python3 -m unittest discover -s tests -v
+```
+
+## Layout
+
+| Module | Responsibility |
+|--------|----------------|
+| `barricator.client` / `barricator.aio` | Sync / async clients |
+| `barricator.evaluation` | Local targeting engine |
+| `barricator.store` | Thread-safe `FlagStore` + `MetricsBuffer` |
+| `barricator.transport` | urllib bootstrap/flush + SSE parsing |
+| `barricator.murmur` | MurmurHash3 (cross-SDK consistent) |
+| `barricator.context` | `UserContext` |

barricator_client-0.1.0/barricator_client.egg-info/SOURCES.txt

@@ -0,0 +1,16 @@
+README.md
+pyproject.toml
+barricator/__init__.py
+barricator/aio.py
+barricator/client.py
+barricator/context.py
+barricator/evaluation.py
+barricator/murmur.py
+barricator/store.py
+barricator/transport.py
+barricator_client.egg-info/PKG-INFO
+barricator_client.egg-info/SOURCES.txt
+barricator_client.egg-info/dependency_links.txt
+barricator_client.egg-info/requires.txt
+barricator_client.egg-info/top_level.txt
+tests/test_evaluation.py

barricator_client-0.1.0/barricator_client.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

barricator_client-0.1.0/barricator_client.egg-info/requires.txt

@@ -0,0 +1,4 @@
+
+[dev]
+pytest>=7
+build>=1.2

barricator_client-0.1.0/barricator_client.egg-info/top_level.txt

@@ -0,0 +1 @@
+barricator

barricator_client-0.1.0/pyproject.toml

@@ -0,0 +1,36 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "barricator-client"
+version = "0.1.0"
+description = "Barricator production-grade Python Server SDK (local evaluation, SSE sync, telemetry)"
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "Apache-2.0" }
+authors = [{ name = "Jorge Spiropulo" }]
+keywords = ["feature-flags", "barricator", "sdk", "rollout", "ab-testing"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: Apache Software License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Software Development :: Libraries",
+]
+dependencies = []  # standard library only (urllib, threading, asyncio)
+
+[project.urls]
+Homepage = "https://github.com/barricator/barricator-python-client"
+Source = "https://github.com/barricator/barricator-python-client"
+Changelog = "https://github.com/barricator/barricator-python-client/blob/main/CHANGELOG.md"
+
+[project.optional-dependencies]
+dev = ["pytest>=7", "build>=1.2"]
+
+[tool.setuptools.packages.find]
+include = ["barricator*"]

barricator_client-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

barricator_client-0.1.0/tests/test_evaluation.py

@@ -0,0 +1,79 @@
+import unittest
+
+from barricator import UserContext
+from barricator import evaluation
+from barricator.murmur import bucket_0_to_99, bucket_100k
+
+
+def _flag(**kwargs):
+    base = {
+        "key": "f",
+        "on": True,
+        "variations": [
+            {"id": "on", "value": True},
+            {"id": "off", "value": False},
+        ],
+        "rules": [],
+        "offVariationId": "off",
+        "fallthroughVariationId": "off",
+    }
+    base.update(kwargs)
+    return base
+
+
+class EvaluationTests(unittest.TestCase):
+    def test_off_serves_off_variation(self):
+        result = evaluation.evaluate(_flag(on=False), UserContext("u1"), True)
+        self.assertFalse(result.value)
+        self.assertEqual(result.reason, evaluation.REASON_OFF)
+
+    def test_rule_ends_with_email(self):
+        flag = _flag(
+            rules=[{
+                "id": "r1",
+                "clauses": [{"attribute": "email", "op": "ENDS_WITH", "values": ["@enterprise.com"]}],
+                "variationId": "on",
+            }],
+        )
+        enterprise = UserContext("u1", email="user@enterprise.com")
+        consumer = UserContext("u2", email="user@gmail.com")
+        self.assertTrue(evaluation.evaluate(flag, enterprise, False).value)
+        self.assertFalse(evaluation.evaluate(flag, consumer, False).value)
+
+    def test_missing_flag_returns_fallback(self):
+        result = evaluation.evaluate(None, UserContext("u1"), "fallback")
+        self.assertEqual(result.value, "fallback")
+        self.assertTrue(result.is_defaulted)
+
+    def test_rollout_is_deterministic(self):
+        flag = _flag(fallthroughRollout={
+            "variations": [
+                {"variationId": "on", "weight": 50000},
+                {"variationId": "off", "weight": 50000},
+            ],
+        })
+        user = UserContext("stable-user-123")
+        first = evaluation.evaluate(flag, user, False).value
+        second = evaluation.evaluate(flag, user, False).value
+        self.assertEqual(first, second)
+
+    def test_custom_attribute_targeting(self):
+        flag = _flag(rules=[{
+            "id": "r1",
+            "clauses": [{"attribute": "plan", "op": "IN", "values": ["pro", "enterprise"]}],
+            "variationId": "on",
+        }])
+        self.assertTrue(evaluation.evaluate(flag, UserContext("u", custom={"plan": "pro"}), False).value)
+        self.assertFalse(evaluation.evaluate(flag, UserContext("u", custom={"plan": "free"}), False).value)
+
+
+class MurmurTests(unittest.TestCase):
+    def test_bucket_in_range_and_stable(self):
+        b = bucket_0_to_99("flag", "salt", "user-1")
+        self.assertTrue(0 <= b < 100)
+        self.assertEqual(b, bucket_0_to_99("flag", "salt", "user-1"))
+        self.assertTrue(0 <= bucket_100k("flag", "salt", "user-1") < 100000)
+
+
+if __name__ == "__main__":
+    unittest.main()