rocketflag 0.1.0__tar.gz → 0.2.0__tar.gz

{rocketflag-0.1.0/src/rocketflag.egg-info → rocketflag-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rocketflag
-Version: 0.1.0
+Version: 0.2.0
 Summary: Python SDK of the RocketFlag Service
 Author: RocketFlag Developers
 License: MIT
@@ -29,6 +29,8 @@ Dynamic: license-file
 
 Official Python SDK for [RocketFlag](https://rocketflag.app). Same evaluation API as the [Node](https://github.com/RocketFlag/node-sdk) and [Go](https://github.com/RocketFlag/go-sdk) SDKs: create a client, fetch a flag, branch on `flag.enabled`.
 
+**Beta:** the evaluation API matches Node and Go, but packaging and docs may still change. Prefer pinning a version in production.
+
 ## Installation
 
 ```bash
@@ -81,7 +83,24 @@ flag = rocketflag.get_flag("IFldMzqP5jtv9wAL", {
 })
 ```
 
-`env` must be alphanumeric, matching the Node SDK.
+`env` selects the environment of a group flag. Environment names contain letters, numbers, hyphens and underscores.
+
+## Sticky rollouts and audiences
+
+Pass a `targetingKey` to make percentage rollouts sticky, and any other keys as audience attributes:
+
+```python
+flag = rocketflag.get_flag("IFldMzqP5jtv9wAL", {
+    "targetingKey": user.id,
+    "plan": "pro",
+    "country": "AU",
+})
+```
+
+- **`targetingKey`**: a stable identifier for the user. The same key always gets the same answer from a percentage rollout, in every environment of a group flag, and raising the percentage only ever adds users. Without a `targetingKey` the `cohort` is used, and with neither each request is a fresh random roll. Prefer an opaque id over an email address: the key is part of the request URL.
+- **Any other key** is an audience attribute, matched against the flag's audience exactly and case-sensitively. An attribute you don't send never matches. `cohort`, `env` and `targetingKey` are reserved and can't be audience attributes.
+
+Context values must be `str`, `int`, `float` or `bool`. `None` raises `ValueError`, so leave out an attribute you don't have. The `UserContext` type hint excludes `None` too, so a type checker catches it first.
 
 ## Caching
 
@@ -100,7 +119,11 @@ flag = rocketflag.get_flag("IFldMzqP5jtv9wAL", ttl_seconds=0)
 flag = rocketflag.get_flag("IFldMzqP5jtv9wAL", ttl_seconds=10)
 ```
 
-Without a client default or per-call TTL, every call hits the API. The cache has no size cap; entries expire on the next lookup after TTL.
+Without a client default or per-call TTL, every call hits the API. Each distinct context is its own cache entry, so a `targetingKey` per user means an entry per user. The cache holds at most 10,000 entries and evicts the least recently used one when it is full. Change the cap with `max_entries`:
+
+```python
+rocketflag = create_client(ttl_seconds=300, max_entries=50_000)
+```
 
 ## Errors
 

{rocketflag-0.1.0 → rocketflag-0.2.0}/README.md

@@ -2,6 +2,8 @@
 
 Official Python SDK for [RocketFlag](https://rocketflag.app). Same evaluation API as the [Node](https://github.com/RocketFlag/node-sdk) and [Go](https://github.com/RocketFlag/go-sdk) SDKs: create a client, fetch a flag, branch on `flag.enabled`.
 
+**Beta:** the evaluation API matches Node and Go, but packaging and docs may still change. Prefer pinning a version in production.
+
 ## Installation
 
 ```bash
@@ -54,7 +56,24 @@ flag = rocketflag.get_flag("IFldMzqP5jtv9wAL", {
 })
 ```
 
-`env` must be alphanumeric, matching the Node SDK.
+`env` selects the environment of a group flag. Environment names contain letters, numbers, hyphens and underscores.
+
+## Sticky rollouts and audiences
+
+Pass a `targetingKey` to make percentage rollouts sticky, and any other keys as audience attributes:
+
+```python
+flag = rocketflag.get_flag("IFldMzqP5jtv9wAL", {
+    "targetingKey": user.id,
+    "plan": "pro",
+    "country": "AU",
+})
+```
+
+- **`targetingKey`**: a stable identifier for the user. The same key always gets the same answer from a percentage rollout, in every environment of a group flag, and raising the percentage only ever adds users. Without a `targetingKey` the `cohort` is used, and with neither each request is a fresh random roll. Prefer an opaque id over an email address: the key is part of the request URL.
+- **Any other key** is an audience attribute, matched against the flag's audience exactly and case-sensitively. An attribute you don't send never matches. `cohort`, `env` and `targetingKey` are reserved and can't be audience attributes.
+
+Context values must be `str`, `int`, `float` or `bool`. `None` raises `ValueError`, so leave out an attribute you don't have. The `UserContext` type hint excludes `None` too, so a type checker catches it first.
 
 ## Caching
 
@@ -73,7 +92,11 @@ flag = rocketflag.get_flag("IFldMzqP5jtv9wAL", ttl_seconds=0)
 flag = rocketflag.get_flag("IFldMzqP5jtv9wAL", ttl_seconds=10)
 ```
 
-Without a client default or per-call TTL, every call hits the API. The cache has no size cap; entries expire on the next lookup after TTL.
+Without a client default or per-call TTL, every call hits the API. Each distinct context is its own cache entry, so a `targetingKey` per user means an entry per user. The cache holds at most 10,000 entries and evicts the least recently used one when it is full. Change the cap with `max_entries`:
+
+```python
+rocketflag = create_client(ttl_seconds=300, max_entries=50_000)
+```
 
 ## Errors
 

{rocketflag-0.1.0 → rocketflag-0.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "rocketflag"
-version = "0.1.0"
+version = "0.2.0"
 description = "Python SDK of the RocketFlag Service"
 readme = "README.md"
 license = { text = "MIT" }

{rocketflag-0.1.0 → rocketflag-0.2.0}/src/rocketflag/__init__.py

@@ -1,18 +1,30 @@
 """Official Python SDK for RocketFlag."""
 
-from .client import DEFAULT_API_URL, DEFAULT_VERSION, Client, Flag, create_client
+from .client import (
+    DEFAULT_API_URL,
+    DEFAULT_MAX_CACHE_ENTRIES,
+    DEFAULT_VERSION,
+    Client,
+    ContextValue,
+    Flag,
+    UserContext,
+    create_client,
+)
 from .errors import APIError, InvalidResponseError, NetworkError, RocketFlagError
 
 __all__ = [
     "APIError",
     "Client",
+    "ContextValue",
     "DEFAULT_API_URL",
+    "DEFAULT_MAX_CACHE_ENTRIES",
     "DEFAULT_VERSION",
     "Flag",
     "InvalidResponseError",
     "NetworkError",
     "RocketFlagError",
+    "UserContext",
     "create_client",
 ]
 
-__version__ = "0.1.0"
+__version__ = "0.2.0"

{rocketflag-0.1.0 → rocketflag-0.2.0}/src/rocketflag/client.py

@@ -1,18 +1,21 @@
 """RocketFlag evaluation client.
 
 Mirrors the Node and Go SDKs: GET {api_url}/{version}/flags/{flag_id}
-with optional query-string user context (cohort, env, …) and an opt-in
-in-memory TTL cache keyed by flag ID + context.
+with optional query-string user context (cohort, env, targetingKey and
+audience attributes) and an opt-in in-memory TTL cache keyed by flag ID +
+context, capped at a maximum number of entries.
 """
 
 from __future__ import annotations
 
 import json
 import re
+import threading
 import time
 import urllib.error
 import urllib.parse
 import urllib.request
+from collections import OrderedDict
 from dataclasses import dataclass
 from typing import Any, Mapping, Optional, Union
 
@@ -20,9 +23,13 @@ from .errors import APIError, InvalidResponseError, NetworkError
 
 DEFAULT_API_URL = "https://api.rocketflag.app"
 DEFAULT_VERSION = "v1"
-_ALPHANUMERIC = re.compile(r"^[a-zA-Z0-9]+$")
+DEFAULT_MAX_CACHE_ENTRIES = 10_000
+_ENV_NAME = re.compile(r"[A-Za-z0-9_-]+")
 
 ContextValue = Union[str, int, float, bool]
+# Every key is sent as a query parameter: cohort, env, targetingKey (a stable
+# user identifier that makes percentage rollouts sticky) and any other key as
+# an audience attribute. None is not a value; leave the key out instead.
 UserContext = Mapping[str, ContextValue]
 
 
@@ -48,12 +55,12 @@ def _validate_flag(payload: Any) -> Flag:
 
 def _validate_context(user_context: UserContext) -> None:
     for key, value in user_context.items():
-        if isinstance(value, bool):
-            continue
-        if isinstance(value, (str, int, float)):
-            if key == "env":
-                if not isinstance(value, str) or not _ALPHANUMERIC.match(value):
-                    raise ValueError(f"env values must be alphanumeric. Invalid value for env: {value!r}")
+        if isinstance(value, (str, int, float)):  # bool is an int
+            if key == "env" and (not isinstance(value, str) or not _ENV_NAME.fullmatch(value)):
+                raise ValueError(
+                    "env values may only contain letters, numbers, hyphens and underscores. "
+                    f"Invalid value for env: {value!r}"
+                )
             continue
         raise ValueError(
             f"userContext values must be of type str, int, float, or bool. Invalid value for key: {key}"
@@ -75,12 +82,18 @@ class Client:
         api_url: str = DEFAULT_API_URL,
         *,
         ttl_seconds: Optional[float] = None,
+        max_entries: int = DEFAULT_MAX_CACHE_ENTRIES,
         opener: Optional[urllib.request.OpenerDirector] = None,
     ) -> None:
+        if isinstance(max_entries, bool) or not isinstance(max_entries, int) or max_entries < 1:
+            raise ValueError("max_entries must be a positive integer")
         self.version = version
         self.api_url = api_url.rstrip("/")
         self._default_ttl_ms = 0.0 if ttl_seconds is None else float(ttl_seconds) * 1000.0
-        self._cache: dict[str, tuple[Flag, float]] = {}
+        self._max_entries = max_entries
+        # Least recently used first; a hit moves its entry to the end.
+        self._cache: OrderedDict[str, tuple[Flag, float]] = OrderedDict()
+        self._cache_lock = threading.Lock()
         self._opener = opener or urllib.request.build_opener()
 
     def get_flag(
@@ -108,12 +121,14 @@ class Client:
         cache_key = ""
         if effective_ttl_ms > 0:
             cache_key = _cache_key(flag_id, params)
-            entry = self._cache.get(cache_key)
-            if entry is not None:
-                flag, expires_at = entry
-                if expires_at > time.time() * 1000.0:
-                    return Flag(name=flag.name, enabled=flag.enabled, id=flag.id)
-                del self._cache[cache_key]
+            with self._cache_lock:
+                entry = self._cache.get(cache_key)
+                if entry is not None:
+                    flag, expires_at = entry
+                    if expires_at > time.time() * 1000.0:
+                        self._cache.move_to_end(cache_key)
+                        return Flag(name=flag.name, enabled=flag.enabled, id=flag.id)
+                    del self._cache[cache_key]
 
         request = urllib.request.Request(url, method="GET")
         try:
@@ -139,7 +154,11 @@ class Client:
 
         flag = _validate_flag(payload)
         if effective_ttl_ms > 0:
-            self._cache[cache_key] = (flag, time.time() * 1000.0 + effective_ttl_ms)
+            with self._cache_lock:
+                self._cache.pop(cache_key, None)
+                if len(self._cache) >= self._max_entries:
+                    self._cache.popitem(last=False)
+                self._cache[cache_key] = (flag, time.time() * 1000.0 + effective_ttl_ms)
         return flag
 
 
@@ -147,6 +166,7 @@ def create_client(
     version: str = DEFAULT_VERSION,
     api_url: str = DEFAULT_API_URL,
     ttl_seconds: Optional[float] = None,
+    max_entries: int = DEFAULT_MAX_CACHE_ENTRIES,
 ) -> Client:
-    """Create a client. Signature matches Node's createRocketflagClient(version, apiUrl, { ttlSeconds })."""
-    return Client(version, api_url, ttl_seconds=ttl_seconds)
+    """Create a client. Matches Node's createRocketflagClient(version, apiUrl, { ttlSeconds, maxEntries })."""
+    return Client(version, api_url, ttl_seconds=ttl_seconds, max_entries=max_entries)

{rocketflag-0.1.0 → rocketflag-0.2.0/src/rocketflag.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rocketflag
-Version: 0.1.0
+Version: 0.2.0
 Summary: Python SDK of the RocketFlag Service
 Author: RocketFlag Developers
 License: MIT
@@ -29,6 +29,8 @@ Dynamic: license-file
 
 Official Python SDK for [RocketFlag](https://rocketflag.app). Same evaluation API as the [Node](https://github.com/RocketFlag/node-sdk) and [Go](https://github.com/RocketFlag/go-sdk) SDKs: create a client, fetch a flag, branch on `flag.enabled`.
 
+**Beta:** the evaluation API matches Node and Go, but packaging and docs may still change. Prefer pinning a version in production.
+
 ## Installation
 
 ```bash
@@ -81,7 +83,24 @@ flag = rocketflag.get_flag("IFldMzqP5jtv9wAL", {
 })
 ```
 
-`env` must be alphanumeric, matching the Node SDK.
+`env` selects the environment of a group flag. Environment names contain letters, numbers, hyphens and underscores.
+
+## Sticky rollouts and audiences
+
+Pass a `targetingKey` to make percentage rollouts sticky, and any other keys as audience attributes:
+
+```python
+flag = rocketflag.get_flag("IFldMzqP5jtv9wAL", {
+    "targetingKey": user.id,
+    "plan": "pro",
+    "country": "AU",
+})
+```
+
+- **`targetingKey`**: a stable identifier for the user. The same key always gets the same answer from a percentage rollout, in every environment of a group flag, and raising the percentage only ever adds users. Without a `targetingKey` the `cohort` is used, and with neither each request is a fresh random roll. Prefer an opaque id over an email address: the key is part of the request URL.
+- **Any other key** is an audience attribute, matched against the flag's audience exactly and case-sensitively. An attribute you don't send never matches. `cohort`, `env` and `targetingKey` are reserved and can't be audience attributes.
+
+Context values must be `str`, `int`, `float` or `bool`. `None` raises `ValueError`, so leave out an attribute you don't have. The `UserContext` type hint excludes `None` too, so a type checker catches it first.
 
 ## Caching
 
@@ -100,7 +119,11 @@ flag = rocketflag.get_flag("IFldMzqP5jtv9wAL", ttl_seconds=0)
 flag = rocketflag.get_flag("IFldMzqP5jtv9wAL", ttl_seconds=10)
 ```
 
-Without a client default or per-call TTL, every call hits the API. The cache has no size cap; entries expire on the next lookup after TTL.
+Without a client default or per-call TTL, every call hits the API. Each distinct context is its own cache entry, so a `targetingKey` per user means an entry per user. The cache holds at most 10,000 entries and evicts the least recently used one when it is full. Change the cap with `max_entries`:
+
+```python
+rocketflag = create_client(ttl_seconds=300, max_entries=50_000)
+```
 
 ## Errors
 

rocketflag-0.2.0/tests/test_client.py

@@ -0,0 +1,266 @@
+import json
+import threading
+from http.server import BaseHTTPRequestHandler, HTTPServer
+from urllib.parse import parse_qs, urlparse
+
+import pytest
+
+from rocketflag import (
+    DEFAULT_MAX_CACHE_ENTRIES,
+    APIError,
+    Client,
+    Flag,
+    InvalidResponseError,
+    NetworkError,
+    create_client,
+)
+
+
+class FlagHandler(BaseHTTPRequestHandler):
+    responses = {}
+    hits = 0
+
+    def do_GET(self):
+        type(self).hits += 1
+        parsed = urlparse(self.path)
+        body, status = self.responses.get(parsed.path, (b"{}", 404))
+        if callable(body):
+            body, status = body(parsed)
+        self.send_response(status)
+        self.send_header("Content-Type", "application/json")
+        self.end_headers()
+        self.wfile.write(body)
+
+    def log_message(self, format, *args):
+        return
+
+
+@pytest.fixture
+def server():
+    FlagHandler.hits = 0
+    FlagHandler.responses = {}
+    httpd = HTTPServer(("127.0.0.1", 0), FlagHandler)
+    thread = threading.Thread(target=httpd.serve_forever, daemon=True)
+    thread.start()
+    host, port = httpd.server_address
+    yield f"http://{host}:{port}", FlagHandler
+    httpd.shutdown()
+    httpd.server_close()
+
+
+def flag_json(**overrides):
+    payload = {"name": "signup", "enabled": True, "id": "abc123"}
+    payload.update(overrides)
+    return json.dumps(payload).encode()
+
+
+def test_get_flag_success(server):
+    base, handler = server
+    handler.responses["/v1/flags/abc123"] = (flag_json(), 200)
+    client = create_client(api_url=base)
+    flag = client.get_flag("abc123")
+    assert flag == Flag(name="signup", enabled=True, id="abc123")
+    assert flag.enabled is True
+
+
+def test_passes_context_as_query_string(server):
+    base, handler = server
+    seen = {}
+
+    def body(parsed):
+        seen["query"] = parse_qs(parsed.query)
+        return flag_json(), 200
+
+    handler.responses["/v1/flags/abc123"] = (body, 200)
+    client = Client(api_url=base)
+    client.get_flag("abc123", {"cohort": "beta", "env": "prod"})
+    assert seen["query"]["cohort"] == ["beta"]
+    assert seen["query"]["env"] == ["prod"]
+
+
+def test_cache_hits_on_second_call(server):
+    base, handler = server
+    handler.responses["/v1/flags/abc123"] = (flag_json(), 200)
+    client = create_client(api_url=base, ttl_seconds=60)
+    first = client.get_flag("abc123", {"cohort": "beta"})
+    second = client.get_flag("abc123", {"cohort": "beta"})
+    assert first == second
+    assert handler.hits == 1
+
+
+def test_ttl_zero_bypasses_cache(server):
+    base, handler = server
+    handler.responses["/v1/flags/abc123"] = (flag_json(), 200)
+    client = create_client(api_url=base, ttl_seconds=60)
+    client.get_flag("abc123")
+    client.get_flag("abc123", ttl_seconds=0)
+    assert handler.hits == 2
+
+
+def test_api_error_on_404(server):
+    base, handler = server
+    handler.responses["/v1/flags/missing"] = (b"not found", 404)
+    client = create_client(api_url=base)
+    with pytest.raises(APIError) as exc:
+        client.get_flag("missing")
+    assert exc.value.status == 404
+
+
+def test_invalid_json(server):
+    base, handler = server
+    handler.responses["/v1/flags/abc123"] = (b"not-json", 200)
+    client = create_client(api_url=base)
+    with pytest.raises(InvalidResponseError):
+        client.get_flag("abc123")
+
+
+def test_invalid_shape(server):
+    base, handler = server
+    handler.responses["/v1/flags/abc123"] = (b'{"name": 1}', 200)
+    client = create_client(api_url=base)
+    with pytest.raises(InvalidResponseError):
+        client.get_flag("abc123")
+
+
+def test_requires_flag_id():
+    client = create_client()
+    with pytest.raises(ValueError):
+        client.get_flag("")
+
+
+class StubResponse:
+    status = 200
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *exc):
+        return False
+
+    def read(self):
+        return flag_json()
+
+
+class StubOpener:
+    """Answers every request with a flag, recording the URLs it was asked for."""
+
+    def __init__(self):
+        self.urls = []
+
+    def open(self, request):
+        self.urls.append(request.full_url)
+        return StubResponse()
+
+
+def test_passes_targeting_key_and_audience_attributes(server):
+    base, handler = server
+    seen = {}
+
+    def body(parsed):
+        seen["query"] = parse_qs(parsed.query, keep_blank_values=True)
+        return flag_json(), 200
+
+    handler.responses["/v1/flags/abc123"] = (body, 200)
+    client = Client(api_url=base)
+    client.get_flag("abc123", {"targetingKey": "user-42", "plan": "pro", "country": "AU", "seats": 5, "beta": True})
+    assert seen["query"] == {
+        "targetingKey": ["user-42"],
+        "plan": ["pro"],
+        "country": ["AU"],
+        "seats": ["5"],
+        "beta": ["true"],
+    }
+
+
+def test_none_value_is_rejected():
+    opener = StubOpener()
+    client = Client(opener=opener)
+    with pytest.raises(ValueError, match="Invalid value for key: plan"):
+        client.get_flag("abc", {"plan": None})
+    assert opener.urls == []
+
+
+@pytest.mark.parametrize("env", ["prod", "prod-portals", "staging_v2", "production1"])
+def test_env_accepts_letters_numbers_hyphens_and_underscores(env):
+    opener = StubOpener()
+    client = Client(opener=opener)
+    client.get_flag("abc", {"env": env})
+    assert opener.urls == [f"https://api.rocketflag.app/v1/flags/abc?env={env}"]
+
+
+@pytest.mark.parametrize("env", ["prod 1", "prod.1", "prod!", "prod\n", "", True, 5])
+def test_env_rejects_other_characters(env):
+    opener = StubOpener()
+    client = Client(opener=opener)
+    with pytest.raises(ValueError, match="env values may only contain letters, numbers, hyphens and underscores"):
+        client.get_flag("abc", {"env": env})
+    assert opener.urls == []
+
+
+def test_cache_evicts_least_recently_used_when_full():
+    opener = StubOpener()
+    client = Client(ttl_seconds=60, max_entries=2, opener=opener)
+    client.get_flag("abc", {"targetingKey": "a"})
+    client.get_flag("abc", {"targetingKey": "b"})
+    client.get_flag("abc", {"targetingKey": "a"})  # hit, so "b" is now least recently used
+    assert len(opener.urls) == 2
+
+    client.get_flag("abc", {"targetingKey": "c"})  # evicts "b"
+    client.get_flag("abc", {"targetingKey": "a"})
+    assert len(opener.urls) == 3
+
+    client.get_flag("abc", {"targetingKey": "b"})
+    assert len(opener.urls) == 4
+
+
+def test_cache_holds_10000_entries_by_default():
+    assert DEFAULT_MAX_CACHE_ENTRIES == 10_000
+    opener = StubOpener()
+    client = Client(ttl_seconds=60, opener=opener)
+    for i in range(10_001):
+        client.get_flag("abc", {"targetingKey": f"user-{i}"})
+    assert len(opener.urls) == 10_001
+
+    client.get_flag("abc", {"targetingKey": "user-10000"})
+    assert len(opener.urls) == 10_001
+    client.get_flag("abc", {"targetingKey": "user-0"})
+    assert len(opener.urls) == 10_002
+
+
+def test_cache_is_safe_under_concurrent_use():
+    opener = StubOpener()
+    client = Client(ttl_seconds=60, max_entries=8, opener=opener)
+    errors = []
+
+    def worker(n):
+        try:
+            for i in range(500):
+                client.get_flag("abc", {"targetingKey": f"user-{(n * i) % 20}"})
+        except Exception as exc:  # pragma: no cover - surfaced by the assert below
+            errors.append(exc)
+
+    threads = [threading.Thread(target=worker, args=(n,)) for n in range(8)]
+    for thread in threads:
+        thread.start()
+    for thread in threads:
+        thread.join()
+
+    assert errors == []
+    assert len(client._cache) <= 8
+
+
+@pytest.mark.parametrize("max_entries", [0, -1, 1.5, True, "10"])
+def test_max_entries_must_be_a_positive_integer(max_entries):
+    with pytest.raises(ValueError, match="max_entries must be a positive integer"):
+        Client(max_entries=max_entries)
+
+
+def test_create_client_passes_max_entries():
+    with pytest.raises(ValueError, match="max_entries must be a positive integer"):
+        create_client(max_entries=0)
+
+
+def test_network_error():
+    client = create_client(api_url="http://127.0.0.1:1")
+    with pytest.raises(NetworkError):
+        client.get_flag("abc123")

rocketflag-0.1.0/tests/test_client.py

@@ -1,139 +0,0 @@
-import json
-import threading
-from http.server import BaseHTTPRequestHandler, HTTPServer
-from urllib.parse import parse_qs, urlparse
-
-import pytest
-
-from rocketflag import (
-    APIError,
-    Client,
-    Flag,
-    InvalidResponseError,
-    NetworkError,
-    create_client,
-)
-
-
-class FlagHandler(BaseHTTPRequestHandler):
-    responses = {}
-    hits = 0
-
-    def do_GET(self):
-        type(self).hits += 1
-        parsed = urlparse(self.path)
-        body, status = self.responses.get(parsed.path, (b"{}", 404))
-        if callable(body):
-            body, status = body(parsed)
-        self.send_response(status)
-        self.send_header("Content-Type", "application/json")
-        self.end_headers()
-        self.wfile.write(body)
-
-    def log_message(self, format, *args):
-        return
-
-
-@pytest.fixture
-def server():
-    FlagHandler.hits = 0
-    FlagHandler.responses = {}
-    httpd = HTTPServer(("127.0.0.1", 0), FlagHandler)
-    thread = threading.Thread(target=httpd.serve_forever, daemon=True)
-    thread.start()
-    host, port = httpd.server_address
-    yield f"http://{host}:{port}", FlagHandler
-    httpd.shutdown()
-    httpd.server_close()
-
-
-def flag_json(**overrides):
-    payload = {"name": "signup", "enabled": True, "id": "abc123"}
-    payload.update(overrides)
-    return json.dumps(payload).encode()
-
-
-def test_get_flag_success(server):
-    base, handler = server
-    handler.responses["/v1/flags/abc123"] = (flag_json(), 200)
-    client = create_client(api_url=base)
-    flag = client.get_flag("abc123")
-    assert flag == Flag(name="signup", enabled=True, id="abc123")
-    assert flag.enabled is True
-
-
-def test_passes_context_as_query_string(server):
-    base, handler = server
-    seen = {}
-
-    def body(parsed):
-        seen["query"] = parse_qs(parsed.query)
-        return flag_json(), 200
-
-    handler.responses["/v1/flags/abc123"] = (body, 200)
-    client = Client(api_url=base)
-    client.get_flag("abc123", {"cohort": "beta", "env": "prod"})
-    assert seen["query"]["cohort"] == ["beta"]
-    assert seen["query"]["env"] == ["prod"]
-
-
-def test_cache_hits_on_second_call(server):
-    base, handler = server
-    handler.responses["/v1/flags/abc123"] = (flag_json(), 200)
-    client = create_client(api_url=base, ttl_seconds=60)
-    first = client.get_flag("abc123", {"cohort": "beta"})
-    second = client.get_flag("abc123", {"cohort": "beta"})
-    assert first == second
-    assert handler.hits == 1
-
-
-def test_ttl_zero_bypasses_cache(server):
-    base, handler = server
-    handler.responses["/v1/flags/abc123"] = (flag_json(), 200)
-    client = create_client(api_url=base, ttl_seconds=60)
-    client.get_flag("abc123")
-    client.get_flag("abc123", ttl_seconds=0)
-    assert handler.hits == 2
-
-
-def test_api_error_on_404(server):
-    base, handler = server
-    handler.responses["/v1/flags/missing"] = (b"not found", 404)
-    client = create_client(api_url=base)
-    with pytest.raises(APIError) as exc:
-        client.get_flag("missing")
-    assert exc.value.status == 404
-
-
-def test_invalid_json(server):
-    base, handler = server
-    handler.responses["/v1/flags/abc123"] = (b"not-json", 200)
-    client = create_client(api_url=base)
-    with pytest.raises(InvalidResponseError):
-        client.get_flag("abc123")
-
-
-def test_invalid_shape(server):
-    base, handler = server
-    handler.responses["/v1/flags/abc123"] = (b'{"name": 1}', 200)
-    client = create_client(api_url=base)
-    with pytest.raises(InvalidResponseError):
-        client.get_flag("abc123")
-
-
-def test_requires_flag_id():
-    client = create_client()
-    with pytest.raises(ValueError):
-        client.get_flag("")
-
-
-def test_env_must_be_alphanumeric():
-    client = create_client()
-    with pytest.raises(ValueError, match="alphanumeric"):
-        client.get_flag("abc", {"env": "prod-1"})
-
-
-def test_network_error():
-    client = create_client(api_url="http://127.0.0.1:1")
-    with pytest.raises(NetworkError):
-        client.get_flag("abc123")