recapi 0.4.1__py3-none-any.whl

recapi/client.py

@@ -0,0 +1,1018 @@
+"""The recapi client for Python servers: history, batching, retries and fallback.
+
+It behaves like the JS SDK (``sdk/js``); ``spec/client_vectors.json`` pins what
+both must agree on. Standard library only: it adds no dependency to an app.
+"""
+
+from __future__ import annotations
+
+import atexit
+import base64
+import contextlib
+import datetime
+import hashlib
+import http.client
+import json
+import logging
+import os
+import random
+import threading
+import time
+import urllib.parse
+import urllib.request
+import uuid
+import weakref
+from collections import OrderedDict
+from collections.abc import Iterable, Mapping, Sequence
+from dataclasses import dataclass, field
+from typing import Any, Protocol
+
+from .history import History, is_id
+
+__version__ = "0.4.1"
+
+log = logging.getLogger("recapi")
+Tags = Sequence[str] | None
+
+# API limits (docs/api.md).
+MAX_EVENTS_PER_REQUEST = 1000
+MAX_ITEMS_PER_REQUEST = 1000
+MAX_EXCLUDE = 500
+DEFAULT_COUNT = 10
+MAX_COUNT = 100
+# A widget still empty after 1.5 s has lost the user: recommend() gives up
+# then and falls back, whatever the general timeout (which suits events).
+RECOMMEND_TIMEOUT = 1.5
+# The recommended level scale (docs/api.md "Interaction levels"), by name.
+LEVEL_NAMES = {"view": 3, "cart": 5, "purchase": 10, "reject": -10}
+# Events waiting for a send. A server tracks for every user at once, so this
+# is ten times the JS SDK's queue: a minute-long outage at 150 events/s fits.
+MAX_QUEUE = 10_000
+MAX_FLUSH_BACKOFF = 60.0
+RETRIES = 3
+RETRY_BASE = 0.5
+RETRY_MAX = 8.0
+# Attribution windows, as in the JS SDK: an event on a shown item within 30
+# minutes of the display is the click; after a click, that item's events are
+# attributed for 24 hours.
+DISPLAY_WINDOW_MS = 30 * 60 * 1000
+CLICK_WINDOW_MS = 24 * 60 * 60 * 1000
+# Shown items remembered per user (the JS SDK keeps 500 for one browser; a
+# server store holds every user's).
+MAX_SHOWN_ITEMS = 100
+PUBLIC_KEY_PREFIX = "rk_pub_"
+# Open connections kept between calls: one per call in flight at the busiest
+# moment (AsyncClient runs 8 at once), so a burst of threads can't leave
+# hundreds of sockets open.
+MAX_IDLE_CONNECTIONS = 16
+
+_CODE_BY_STATUS = {
+    400: "invalid_request",
+    401: "unauthorized",
+    403: "forbidden",
+    404: "not_found",
+    413: "too_large",
+    429: "rate_limited",
+}
+
+# Indirections the tests replace (clock, backoff sleep, jitter).
+_now_ms = lambda: int(time.time() * 1000)  # noqa: E731
+_random = random.random
+
+
+def _sleep(seconds: float, stop: threading.Event | None = None) -> bool:
+    """Wait ``seconds``; return True, at once, when ``stop`` is or becomes set."""
+    if stop is None:
+        time.sleep(seconds)
+        return False
+    return stop.wait(seconds)
+
+
+class RecapiError(Exception):
+    """A failed call. ``status`` is 0 when no HTTP response was received.
+
+    ``code`` is the API's error code (``invalid_request``, ``rate_limited``,
+    ``quota_exceeded``...) or a client one: ``network``, ``timeout``,
+    ``invalid_response``.
+    """
+
+    def __init__(
+        self, code: str, message: str, *, status: int = 0, retry_after: float | None = None
+    ) -> None:
+        super().__init__(message)
+        self.code = code
+        self.status = status
+        self.retry_after = retry_after
+
+    @property
+    def retryable(self) -> bool:
+        """Whether trying again later can succeed (``quota_exceeded`` can't until it resets)."""
+        if self.code in ("network", "timeout"):
+            return True
+        if self.status == 429:
+            return self.code != "quota_exceeded"
+        return self.status >= 500
+
+    @property
+    def outage(self) -> bool:
+        """Whether recapi couldn't answer in time or failed on its side.
+
+        A 429 is the tenant's own limit and a 4xx an integration bug: a
+        fallback would hide both.
+        """
+        return self.code in ("network", "timeout") or self.status >= 500
+
+
+@dataclass(frozen=True)
+class Item:
+    """One recommended or popular item."""
+
+    item_id: str
+    score: float
+    slot: str
+    #: The object stored with the item (``metadata`` of ``PUT /v1/items``:
+    #: name, picture, link, price...), None when the item has none. Left
+    #: out of the hash, a dict having none, so items still go in sets.
+    metadata: dict[str, Any] | None = field(default=None, hash=False)
+    #: Why the item is listed, a reason code to turn into a label for
+    #: visitors: "for_you", "similar", "next", "bought_together",
+    #: "trending", "popular", "new", "explore" or "more" (docs/api.md
+    #: "Reason codes"), None when the API sent none. New codes may be
+    #: added: show nothing for an unknown one.
+    why: str | None = None
+
+
+@dataclass(frozen=True)
+class Recommendations:
+    """A recommendation list. ``fallback`` lists are popular items with no id."""
+
+    recommendation_id: str | None
+    fallback: bool
+    items: list[Item]
+
+
+class Store(Protocol):
+    """Where per-user state lives: a Redis client, Django's cache, memcached...
+
+    Values are strings; ``get`` returns None (or ``b""``) for a missing key.
+    """
+
+    def get(self, key: str) -> str | bytes | None: ...  # noqa: D102
+
+    def set(self, key: str, value: str) -> object: ...  # noqa: D102
+
+    def delete(self, key: str) -> object: ...  # noqa: D102
+
+
+class MemoryStore:
+    """In-process store keeping the most recently used ``max_users`` users."""
+
+    def __init__(self, max_users: int = 10_000) -> None:
+        self._max = max(1, max_users)
+        self._data: OrderedDict[str, str] = OrderedDict()
+        self._lock = threading.Lock()
+
+    def get(self, key: str) -> str | None:  # noqa: D102
+        with self._lock:
+            value = self._data.get(key)
+            if value is not None:
+                self._data.move_to_end(key)
+            return value
+
+    def set(self, key: str, value: str) -> None:  # noqa: D102
+        with self._lock:
+            self._data[key] = value
+            self._data.move_to_end(key)
+            while len(self._data) > self._max:
+                self._data.popitem(last=False)
+
+    def delete(self, key: str) -> None:  # noqa: D102
+        with self._lock:
+            self._data.pop(key, None)
+
+
+class _UserState:
+    """What the store keeps per user: the history and the shown items.
+
+    ``shown`` maps item -> [recommendation id, shown at, clicked at?], oldest
+    first. ``restored`` is set once the history holds recapi's stored one.
+    """
+
+    __slots__ = ("history", "restored", "shown")
+
+    def __init__(
+        self, history: History | None = None, shown: dict | None = None, restored: bool = False
+    ) -> None:
+        self.history = history or History()
+        self.shown: dict[str, list[Any]] = shown or {}
+        self.restored = restored
+
+    def dumps(self, now: int) -> str:
+        shown = [[item, *entry] for item, entry in self.shown.items() if _attributable(entry, now)]
+        state = {"history": self.history.encode(), "shown": shown[-MAX_SHOWN_ITEMS:]}
+        if self.restored:
+            state["restored"] = True
+        return json.dumps(state, separators=(",", ":"))
+
+    @classmethod
+    def loads(cls, raw: str | bytes | None) -> _UserState:
+        if not raw:
+            return cls()
+        try:
+            data = json.loads(raw)
+            history = History.decode(data["history"])
+            shown = {
+                e[0]: list(e[1:])
+                for e in data["shown"]
+                if isinstance(e, list) and 3 <= len(e) <= 4 and is_id(e[0])
+            }
+        except (ValueError, KeyError, TypeError):
+            history = None
+        if history is None:
+            log.warning("recapi: discarding a malformed stored user state")
+            return cls()
+        return cls(history, shown, data.get("restored") is True)
+
+
+def _attributable(entry: Sequence[Any], t: int) -> bool:
+    if len(entry) < 3:
+        return t - entry[1] <= DISPLAY_WINDOW_MS
+    return t - entry[2] <= CLICK_WINDOW_MS
+
+
+class Client:
+    """A recapi client, safe to share between threads; create one per process.
+
+    Args:
+        api_key: Secret key (``rk_sec_...``): a server can then restore a
+            user's history from recapi when the store lacks it.
+        base_url: Your recapi API origin, e.g. ``https://api.example.com``.
+        store: Per-user history and attribution state; defaults to an
+            in-memory :class:`MemoryStore`. Pass a shared store (Redis...) when
+            several processes serve the same users.
+        timeout: Per-request timeout in seconds (recommend() uses at most 1.5).
+        flush_interval: Seconds between background event sends.
+        max_batch: Events per request, at most the API's 1,000.
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str,
+        *,
+        store: Store | None = None,
+        timeout: float = 5.0,
+        flush_interval: float = 2.0,
+        max_batch: int = MAX_EVENTS_PER_REQUEST,
+    ) -> None:
+        if not isinstance(api_key, str) or not api_key:
+            raise ValueError("api_key is required")
+        if not isinstance(base_url, str) or not base_url:
+            raise ValueError("base_url is required")
+        self._api_key = api_key
+        self._base = base_url.rstrip("/")
+        url = urllib.parse.urlsplit(self._base)
+        if url.scheme not in ("http", "https") or not url.hostname:
+            raise ValueError("base_url must be an http(s) URL")
+        self._url = url
+        # HTTPS_PROXY, HTTP_PROXY and NO_PROXY, as urllib honours them.
+        proxy = None
+        if not urllib.request.proxy_bypass(url.hostname):
+            proxy = urllib.request.getproxies().get(url.scheme)
+        self._proxy = (
+            urllib.parse.urlsplit(proxy if "://" in proxy else "http://" + proxy) if proxy else None
+        )
+        self._proxy_auth = _basic_auth(self._proxy)
+        # Through a plain HTTP proxy, a request names the whole URL.
+        self._target_base = self._base if self._proxy and url.scheme == "http" else url.path
+        self._store: Store = store if store is not None else MemoryStore()
+        self._timeout = timeout
+        self._interval = flush_interval
+        self._max_batch = min(max(1, max_batch), MAX_EVENTS_PER_REQUEST)
+        # Two environments' keys may share one Redis: their users must not mix.
+        self._prefix = "recapi:" + hashlib.sha256(api_key.encode()).hexdigest()[:12] + ":"
+        self._init_threading()
+        ref = weakref.ref(self)
+        if hasattr(os, "register_at_fork"):
+            os.register_at_fork(after_in_child=lambda: _call(ref, "_init_threading"))
+        atexit.register(lambda: _call(ref, "close"))
+
+    def _init_threading(self) -> None:
+        # Also runs in a forked child (gunicorn, multiprocessing): the
+        # parent's queue is the parent's to send, its sender thread did not
+        # survive the fork, and a lock held then would stay held for ever.
+        self._user_locks = [threading.Lock() for _ in range(64)]
+        self._queue: list[dict[str, Any]] = []
+        self._cond = threading.Condition()
+        self._send_lock = threading.Lock()
+        self._thread: threading.Thread | None = None
+        self._failures = 0
+        self._closed = threading.Event()
+        # Keep-alive connections between calls, so the TLS handshake is paid
+        # once, not on every call. Shared by every thread, so a thread that
+        # ends (a thread per request) leaves its connection to the next call;
+        # a forked child must not share the parent's.
+        self._idle: list[http.client.HTTPConnection] = []
+        self._idle_lock = threading.Lock()
+
+    # --- events -------------------------------------------------------------
+
+    def track(
+        self,
+        item_id: str,
+        level: int | str,
+        *,
+        user_id: str | None = None,
+        anon_id: str | None = None,
+        recommendation_id: str | None = None,
+    ) -> None:
+        """Record an interaction: the user's history changes at once, the event is queued.
+
+        ``level`` is an integer -10 to 10 or ``view`` (3), ``cart`` (5),
+        ``purchase`` (10), ``reject`` (-10: never recommend the item to this
+        user again until a positive event on it). ``recommendation_id``
+        overrides the automatic attribution.
+        """
+        level = _level(level)
+        if not is_id(item_id):
+            raise ValueError("item_id must be 1-256 bytes of UTF-8 without control characters")
+        _check_ids(user_id=user_id, anon_id=anon_id, recommendation_id=recommendation_id)
+        t = _now_ms()
+        attributed = recommendation_id
+        key = self._key(user_id, anon_id)
+        if key is not None:
+            with self._lock_for(key):
+                state = self._load(key)
+                state.history.apply(item_id, level, t)
+                entry = state.shown.get(item_id)
+                # An explicit id of the recommendation that showed the item
+                # is still the click on it; another id leaves the entry alone.
+                if recommendation_id is None or (entry and entry[0] == recommendation_id):
+                    attributed = _attribute(entry, level, t) or recommendation_id
+                self._save(key, state, t)
+        self._enqueue(
+            _compact(
+                {
+                    "item_id": item_id,
+                    "level": level,
+                    "user_id": user_id,
+                    "anon_id": anon_id,
+                    "recommendation_id": attributed,
+                    "timestamp": _iso(t),
+                    "event_id": str(uuid.uuid4()),
+                }
+            )
+        )
+
+    def flush(self) -> None:
+        """Send every queued event now, with retries (end of a job or serverless handler).
+
+        Never raises: failures are logged, and retryable batches stay queued.
+        """
+        self._drain(retry=True)
+
+    def close(self) -> None:
+        """Stop the sender and send what is queued, one try per batch (runs at exit).
+
+        No retries, so a deploy never waits on a recapi outage.
+        """
+        with self._cond:
+            closing = not self._closed.is_set()
+            # Also ends a send's retry sleep, so close() waits for at most one try.
+            self._closed.set()
+            self._cond.notify_all()
+        if closing:
+            self._drain(retry=False)
+        # Also on a later close() (the one at exit): calls made after the
+        # first one may have opened connections again.
+        with self._idle_lock:
+            idle, self._idle = self._idle, []
+        for conn in idle:
+            conn.close()
+
+    def _enqueue(self, event: dict[str, Any]) -> None:
+        with self._cond:
+            if self._thread is None and not self._closed.is_set():
+                self._thread = threading.Thread(target=self._run, name="recapi-sender", daemon=True)
+                self._thread.start()
+            self._queue.append(event)
+            if len(self._queue) > MAX_QUEUE:
+                self._drop_overflow()
+            if len(self._queue) >= self._max_batch:
+                self._cond.notify_all()
+        if self._closed.is_set():
+            self._drain(retry=False)
+
+    def _drop_overflow(self) -> None:
+        dropped = len(self._queue) - MAX_QUEUE
+        del self._queue[:dropped]
+        log.warning("recapi: event queue full, dropped the %d oldest events", dropped)
+
+    def _run(self) -> None:
+        while True:
+            with self._cond:
+                delay = min(self._interval * 2**self._failures, MAX_FLUSH_BACKOFF)
+                # A full batch goes at once, except after a failure: then
+                # the backoff holds, or a down API would be hammered.
+                self._cond.wait_for(
+                    lambda: (
+                        self._closed.is_set()
+                        or (self._failures == 0 and len(self._queue) >= self._max_batch)
+                    ),
+                    timeout=delay,
+                )
+                if self._closed.is_set():
+                    return
+            self._drain(retry=True)
+
+    def _drain(self, *, retry: bool) -> None:
+        with self._send_lock:
+            while True:
+                with self._cond:
+                    batch = self._queue[: self._max_batch]
+                    del self._queue[: len(batch)]
+                if not batch:
+                    return
+                try:
+                    self._send_events(batch, retry=retry)
+                except Exception as error:
+                    if isinstance(error, RecapiError) and not error.retryable:
+                        log.error("recapi: dropped %d events: %s", len(batch), error)
+                        continue
+                    # Anything else keeps the batch, a bug of ours included: event ids
+                    # make a resend harmless, and a dead sender would lose every event.
+                    if not isinstance(error, RecapiError):
+                        log.exception("recapi: unexpected error sending events")
+                    with self._cond:
+                        self._queue[:0] = batch
+                        if len(self._queue) > MAX_QUEUE:
+                            self._drop_overflow()
+                        self._failures += 1
+                    log.warning("recapi: sending %d events failed, kept: %s", len(batch), error)
+                    return
+                self._failures = 0
+
+    def _send_events(self, events: list[dict[str, Any]], *, retry: bool) -> None:
+        def send() -> Any:
+            return self._request("POST", "/v1/events", body={"events": events})
+
+        try:
+            response = _with_retry(send, self._closed) if retry else send()
+        except RecapiError as error:
+            # Over the API's body limit (ids mostly quotes or backslashes, which
+            # JSON escapes): halves fit where the whole didn't. If the second
+            # half fails, the batch is kept whole; event ids make the resend harmless.
+            if error.status != 413 or len(events) < 2:
+                raise
+            half = len(events) // 2
+            self._send_events(events[:half], retry=retry)
+            self._send_events(events[half:], retry=retry)
+            return
+        rejected = response.get("rejected") if isinstance(response, dict) else None
+        if isinstance(rejected, list) and rejected:
+            # Invalid events are reported, never retried: they would fail again.
+            try:
+                detail = [{**r, "event": events[r["index"]]} for r in rejected[:5]]
+            except (TypeError, KeyError, IndexError):
+                detail = rejected[:5]
+            log.error("recapi: %d event(s) rejected: %s", len(rejected), detail)
+
+    # --- recommendations ----------------------------------------------------
+
+    def recommend(
+        self,
+        *,
+        user_id: str | None = None,
+        anon_id: str | None = None,
+        count: int = 0,
+        placement: str | None = None,
+        tags_any: Tags = None,
+        tags_all: Tags = None,
+        exclude: Tags = None,
+        context_item_id: str | None = None,
+        discovery: float | None = None,
+    ) -> Recommendations:
+        """Personalised recommendations for a user (or a visitor's ``anon_id``).
+
+        Sends the history from the store; without one, recapi uses its stored
+        history for ``user_id`` and returns it for the store. A history the
+        store started without it (a ``track()`` or ``identify()`` came first)
+        gets recapi's fetched once, within the same deadline, and merged in.
+        No retry, at most 1.5 s: on a network error, timeout or 5xx it returns
+        popular items (``fallback=True``, no id) and logs the error. If those
+        fail too (recapi is down), the list is empty: hide the slot. A 4xx or
+        429 raises: a fallback would hide an integration bug or a plan limit.
+        """
+        return self._recommend(
+            time.monotonic() + self._recommend_timeout,
+            user_id=user_id,
+            anon_id=anon_id,
+            count=count,
+            placement=placement,
+            tags_any=tags_any,
+            tags_all=tags_all,
+            exclude=exclude,
+            context_item_id=context_item_id,
+            discovery=discovery,
+        )
+
+    @property
+    def _recommend_timeout(self) -> float:
+        return min(self._timeout, RECOMMEND_TIMEOUT)
+
+    def _recommend(
+        self,
+        deadline: float,
+        *,
+        user_id: str | None = None,
+        anon_id: str | None = None,
+        count: int = 0,
+        placement: str | None = None,
+        tags_any: Tags = None,
+        tags_all: Tags = None,
+        exclude: Tags = None,
+        context_item_id: str | None = None,
+        discovery: float | None = None,
+    ) -> Recommendations:
+        """recommend() with its deadline as a ``time.monotonic()`` instant.
+
+        AsyncClient sets it at the ``await``: a call that waited for a thread
+        past it goes straight to the fallback.
+        """
+        key = self._key(user_id, anon_id)
+        t = _now_ms()
+        state = self._load(key) if key is not None else _UserState()
+        if (
+            user_id
+            and not state.restored
+            and not state.history.is_empty()
+            and not self._api_key.startswith(PUBLIC_KEY_PREFIX)
+        ):
+            state = self._restore(key, user_id, state, deadline, t)
+        history, recent, rejected = state.history.wire(t)
+        try:
+            response = self._request(
+                "POST",
+                "/v1/recommendations",
+                timeout=deadline - time.monotonic(),
+                body=_compact(
+                    {
+                        "user_id": user_id,
+                        "anon_id": anon_id,
+                        "placement": placement,
+                        "count": count or None,
+                        "tags_any": _list(tags_any),
+                        "tags_all": _list(tags_all),
+                        "exclude": _with_rejected(exclude, rejected),
+                        "context_item_id": context_item_id,
+                        "history": history,
+                        "recent": recent,
+                        "discovery": discovery,
+                    }
+                ),
+            )
+            rec_id, items = _parse_recommendations(response)
+        except RecapiError as error:
+            if not error.outage:
+                raise
+            # The requested length without the excluded items, so a few more
+            # are asked for. 0 is the recommendations default; popular refuses it.
+            n = count or DEFAULT_COUNT
+            skip = set(_with_rejected(exclude, rejected) or ())
+            if context_item_id is not None:
+                skip.add(context_item_id)
+            try:
+                popular = self._popular(
+                    min(n + len(skip), MAX_COUNT), tags_any, tags_all, self._recommend_timeout
+                )
+            except RecapiError as fallback_error:
+                # recapi is down altogether. The README promises no
+                # try/except, so an empty list the page can hide beats an
+                # exception that fails the whole page.
+                log.warning(
+                    "recapi: recommendations failed (%s), popular too, served no items: %s",
+                    error,
+                    fallback_error,
+                )
+                return Recommendations(None, True, [])
+            log.warning("recapi: recommendations failed, served popular items: %s", error)
+            items = [item for item in popular if item.item_id not in skip][:n]
+            return Recommendations(None, True, items)
+
+        if key is not None:
+            with self._lock_for(key):
+                state = self._load(key)
+                for item in items:
+                    state.shown.pop(item.item_id, None)
+                    state.shown[item.item_id] = [rec_id, t]
+                while len(state.shown) > MAX_SHOWN_ITEMS:
+                    del state.shown[next(iter(state.shown))]
+                # Only trusted when we sent nothing; merged, never replacing
+                # what was tracked while the request was in flight, and only
+                # once: a concurrent first call may have merged it already.
+                snapshot = response.get("history")
+                done = state.restored and not state.history.is_empty()
+                if not history and not recent and isinstance(snapshot, dict) and not done:
+                    state.history = state.history.merge_snapshot(History.from_snapshot(snapshot), t)
+                    state.restored = True
+                self._save(key, state, t)
+        return Recommendations(rec_id, False, items)
+
+    def _restore(
+        self, key: str, user_id: str, state: _UserState, deadline: float, t: int
+    ) -> _UserState:
+        """Merge recapi's stored history into a local one that lacks it (a fresh store).
+
+        The recommendation's reply carries it only when the request sends no
+        history, which would drop this one. So it is asked for apart, once:
+        a failure leaves the state as it was, to be tried on the next call.
+        """
+        path = "/v1/users/" + urllib.parse.quote(user_id, safe="") + "/history"
+        try:
+            # Half the time left, so the recommendation itself still fits.
+            snapshot = self._request("GET", path, timeout=(deadline - time.monotonic()) / 2)
+            if not isinstance(snapshot, dict):
+                raise RecapiError("invalid_response", "malformed history response")
+        except RecapiError as error:
+            log.warning("recapi: could not restore the user's stored history: %s", error)
+            return state
+        with self._lock_for(key):
+            state = self._load(key)
+            # A concurrent first call may have merged it already.
+            if not state.restored:
+                state.history = state.history.merge_snapshot(History.from_snapshot(snapshot), t)
+                state.restored = True
+                self._save(key, state, t)
+        return state
+
+    def identify(self, anon_id: str, user_id: str) -> None:
+        """Call at login: the visitor's history and shown items become the user's.
+
+        Merged into what the store has for ``user_id`` (scores add up, as in
+        the history spec), then the visitor's entry is deleted. Without it, a
+        visitor's clicks stop counting once they log in.
+        """
+        _check_ids(anon_id=anon_id, user_id=user_id)
+        if not anon_id or not user_id:
+            raise ValueError("anon_id and user_id are required")
+        visitor, user = self._key(None, anon_id), self._key(user_id, None)
+        assert visitor is not None and user is not None
+        t = _now_ms()
+        with self._locks_for(visitor, user):
+            guest = self._load(visitor)
+            if guest.history.is_empty() and not guest.history.rejected and not guest.shown:
+                return
+            state = self._load(user)
+            state.history = state.history.merge(guest.history, t)
+            # Oldest display first, as recommend() keeps them; an item's later display wins.
+            shown = sorted([*state.shown.items(), *guest.shown.items()], key=lambda e: e[1][1])
+            state.shown = {}
+            for item, entry in shown:
+                state.shown.pop(item, None)
+                state.shown[item] = entry
+            self._save(user, state, t)
+            try:
+                self._store.delete(visitor)
+            except Exception:
+                log.exception("recapi: could not delete the visitor's stored state")
+
+    def popular(
+        self,
+        *,
+        count: int = DEFAULT_COUNT,
+        tags_any: Tags = None,
+        tags_all: Tags = None,
+    ) -> list[Item]:
+        """Non-personalised popular items, for pages without a user (no retry)."""
+        return self._popular(count, tags_any, tags_all, None)
+
+    def _popular(self, count: int, tags_any: Tags, tags_all: Tags, timeout: float | None) -> list:
+        query = {k: ",".join(v) for k, v in (("tags_any", tags_any), ("tags_all", tags_all)) if v}
+        query["count"] = str(count)
+        response = self._request("GET", "/v1/popular", timeout=timeout, query=query)
+        raw = response.get("items") if isinstance(response, dict) else None
+        if not isinstance(raw, list):
+            raise RecapiError("invalid_response", "malformed popular response")
+        return [_item(entry, "backfill") for entry in raw]
+
+    # --- catalog and users --------------------------------------------------
+
+    def upsert_items(self, items: Iterable[Mapping[str, Any]]) -> int:
+        """Create or replace items (dicts of the API's item fields), 1,000 per request.
+
+        Retried like events. Returns how many were stored; an invalid item
+        raises, and nothing of its batch of 1,000 is stored.
+        """
+        batch: list[dict[str, Any]] = []
+        upserted = 0
+
+        def send() -> int:
+            response = _with_retry(
+                lambda: self._request("POST", "/v1/items:batch", body={"items": batch})
+            )
+            return int(response.get("upserted", 0)) if isinstance(response, dict) else 0
+
+        for item in items:
+            batch.append(dict(item))
+            if len(batch) == MAX_ITEMS_PER_REQUEST:
+                upserted += send()
+                batch = []
+        if batch:
+            upserted += send()
+        return upserted
+
+    def delete_user(self, user_id: str) -> None:
+        """Erase a user's events in recapi (GDPR) and their state in the store."""
+        if not is_id(user_id):
+            raise ValueError("user_id must be 1-256 bytes of UTF-8 without control characters")
+        path = "/v1/users/" + urllib.parse.quote(user_id, safe="")
+        _with_retry(lambda: self._request("DELETE", path))
+        try:
+            self._store.delete(self._key(user_id, None))
+        except Exception:
+            log.exception("recapi: could not delete the user's stored state")
+
+    # --- plumbing -----------------------------------------------------------
+
+    def _key(self, user_id: str | None, anon_id: str | None) -> str | None:
+        if user_id:
+            return self._prefix + "u:" + user_id
+        if anon_id:
+            return self._prefix + "a:" + anon_id
+        return None
+
+    def _lock_for(self, key: str) -> threading.Lock:
+        return self._user_locks[hash(key) % len(self._user_locks)]
+
+    @contextlib.contextmanager
+    def _locks_for(self, *keys: str) -> Any:
+        # Always in the same order, or two logins could each hold the other's lock.
+        indexes = sorted({hash(key) % len(self._user_locks) for key in keys})
+        with contextlib.ExitStack() as stack:
+            for i in indexes:
+                stack.enter_context(self._user_locks[i])
+            yield
+
+    def _load(self, key: str) -> _UserState:
+        # The store is a cache: when it fails, recapi's stored history is
+        # still there, so the call goes on without it.
+        try:
+            raw = self._store.get(key)
+        except Exception:
+            log.exception("recapi: store read failed")
+            return _UserState()
+        return _UserState.loads(raw)
+
+    def _save(self, key: str, state: _UserState, now: int) -> None:
+        try:
+            self._store.set(key, state.dumps(now))
+        except Exception:
+            log.exception("recapi: store write failed")
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        body: object = None,
+        query: Mapping[str, object] | None = None,
+        timeout: float | None = None,
+    ) -> Any:
+        params = {k: str(v) for k, v in (query or {}).items() if v is not None}
+        headers = {"Accept": "application/json", "User-Agent": f"recapi-python/{__version__}"}
+        # A public key travels in the URL only on GET /v1/popular (CDN
+        # caching); the API refuses a secret key there.
+        if method == "GET" and self._api_key.startswith(PUBLIC_KEY_PREFIX):
+            params["key"] = self._api_key
+        else:
+            headers["Authorization"] = f"Bearer {self._api_key}"
+        if self._target_base == self._base:
+            headers.update(self._proxy_auth)
+        target = self._target_base + path
+        if params:
+            target += "?" + urllib.parse.urlencode(params)
+        data = None
+        if body is not None:
+            # Raw UTF-8: escaped, non-Latin ids would take up to 3 times the
+            # bytes, and a batch of 1,000 could pass the API's 2 MiB limit.
+            data = json.dumps(body, separators=(",", ":"), ensure_ascii=False).encode()
+            headers["Content-Type"] = "application/json"
+        limit = self._timeout if timeout is None else timeout
+        if limit <= 0:
+            raise RecapiError("timeout", "the deadline passed before the request was sent")
+        try:
+            status, reply_headers, text = self._exchange(method, target, data, headers, limit)
+        except TimeoutError as error:
+            raise RecapiError("timeout", f"request timed out after {limit:.3g} s") from error
+        except (OSError, http.client.HTTPException) as error:
+            # HTTPException: a reply cut mid-body (IncompleteRead) or garbled
+            # by a proxy, which the JS SDK gets as a failed response.text().
+            raise RecapiError("network", str(error) or type(error).__name__) from error
+        # http.client follows no redirect: a 3xx (an http:// base_url sent on
+        # to https) fails like a 4xx, or a DELETE would look done.
+        if not 200 <= status < 300:
+            raise _http_error(status, reply_headers, text)
+        return _parse_json(text)
+
+    def _exchange(
+        self, method: str, target: str, data: bytes | None, headers: dict[str, str], limit: float
+    ) -> tuple[int, Any, bytes]:
+        """Send one request on an idle connection, or a new one; return status, headers and body.
+
+        A connection the server closed while idle fails before any reply
+        comes: it is replaced once. A failure once the reply has started is
+        never resent: the API has the request (a recommendation would count twice).
+        """
+        start = time.monotonic()
+        with self._idle_lock:
+            # The most recently used: the least likely to have timed out.
+            conn = self._idle.pop() if self._idle else None
+        for attempt in range(2):
+            if conn is None:
+                conn = self._connect()
+            reused = conn.sock is not None
+            remaining = limit - (time.monotonic() - start)
+            if remaining <= 0:  # settimeout() takes 0 as "never block"
+                self._keep(conn)
+                raise TimeoutError
+            conn.timeout = remaining
+            if conn.sock is not None:
+                conn.sock.settimeout(remaining)
+            try:
+                conn.request(method, target, body=data, headers=headers)
+                response = conn.getresponse()
+            except ConnectionError:
+                conn.close()
+                if not reused or attempt:
+                    raise
+                conn = None
+                continue
+            except BaseException:
+                conn.close()
+                raise
+            try:
+                body = response.read()
+            except BaseException:
+                # Half a reply may be left on the socket: never reuse it.
+                conn.close()
+                raise
+            self._keep(conn)
+            return response.status, response.headers, body
+        raise AssertionError("unreachable")
+
+    def _keep(self, conn: http.client.HTTPConnection) -> None:
+        """Return a connection whose last reply was read whole to the idle ones."""
+        if conn.sock is None:  # the server said "Connection: close"
+            return
+        with self._idle_lock:
+            if len(self._idle) < MAX_IDLE_CONNECTIONS:
+                self._idle.append(conn)
+                return
+        conn.close()
+
+    def _connect(self) -> http.client.HTTPConnection:
+        https = self._url.scheme == "https"
+        kind = http.client.HTTPSConnection if https else http.client.HTTPConnection
+        if self._proxy is None:
+            return kind(self._url.hostname, self._url.port, timeout=self._timeout)
+        conn = kind(self._proxy.hostname, self._proxy.port or 80, timeout=self._timeout)
+        if https:
+            conn.set_tunnel(self._url.hostname, self._url.port or 443, headers=self._proxy_auth)
+        return conn
+
+
+def _call(ref: weakref.ref, method: str) -> None:
+    client = ref()
+    if client is not None:
+        getattr(client, method)()
+
+
+def _basic_auth(proxy: urllib.parse.SplitResult | None) -> dict[str, str]:
+    if proxy is None or proxy.username is None:
+        return {}
+    user = urllib.parse.unquote(proxy.username) + ":" + urllib.parse.unquote(proxy.password or "")
+    return {"Proxy-Authorization": "Basic " + base64.b64encode(user.encode()).decode()}
+
+
+def _http_error(status: int, headers: Any, text: bytes) -> RecapiError:
+    payload = _parse_json(text)
+    body = payload.get("error") if isinstance(payload, dict) else None
+    body = body if isinstance(body, dict) else {}
+    code = (
+        body.get("code")
+        or _CODE_BY_STATUS.get(status)
+        or ("internal" if status >= 500 else "http_error")
+    )
+    return RecapiError(
+        str(code),
+        str(body.get("message") or f"HTTP {status}"),
+        status=status,
+        retry_after=_retry_after(headers.get("Retry-After")),
+    )
+
+
+def _retry_after(header: str | None) -> float | None:
+    try:
+        seconds = float(header or "")
+    except ValueError:
+        return None
+    return seconds if 0 <= seconds < float("inf") else None
+
+
+def _parse_json(raw: bytes) -> Any:
+    if not raw:
+        return None
+    try:
+        return json.loads(raw)
+    except ValueError:
+        return None
+
+
+def _with_retry(fn: Any, stop: threading.Event | None = None) -> Any:
+    """Call ``fn``, retrying retryable errors with jittered exponential backoff.
+
+    ``Retry-After`` wins over the backoff, and both are capped at 8 s. Once
+    ``stop`` is set (the client closing), the last error is raised instead.
+    """
+    for attempt in range(RETRIES + 1):
+        try:
+            return fn()
+        except RecapiError as error:
+            if attempt >= RETRIES or not error.retryable:
+                raise
+            backoff = RETRY_BASE * 2**attempt * (0.5 + _random() / 2)
+            wait = error.retry_after if error.retry_after is not None else backoff
+            if _sleep(min(RETRY_MAX, wait), stop):
+                raise
+    raise AssertionError("unreachable")
+
+
+def _parse_recommendations(response: Any) -> tuple[str, list[Item]]:
+    if (
+        not isinstance(response, dict)
+        or not isinstance(response.get("recommendation_id"), str)
+        or not isinstance(response.get("items"), list)
+    ):
+        raise RecapiError("invalid_response", "malformed recommendations response")
+    return response["recommendation_id"], [_item(e, "exploit") for e in response["items"]]
+
+
+def _item(entry: Any, slot: str) -> Item:
+    if not isinstance(entry, dict) or not isinstance(entry.get("item_id"), str):
+        raise RecapiError("invalid_response", "malformed item in response")
+    metadata = entry.get("metadata")
+    return Item(
+        entry["item_id"],
+        float(entry.get("score") or 0),
+        str(entry.get("slot") or slot),
+        metadata if isinstance(metadata, dict) and metadata else None,
+        why if isinstance(why := entry.get("why"), str) and why else None,
+    )
+
+
+def _attribute(entry: list[Any] | None, level: int, t: int) -> str | None:
+    """Return the recommendation an event at ``t`` belongs to; a first click is recorded."""
+    if entry is None or not _attributable(entry, t):
+        return None
+    if level > 0 and len(entry) < 3:
+        entry.append(t)
+    return entry[0]
+
+
+def _with_rejected(exclude: Sequence[str] | None, rejected: list[str]) -> list[str] | None:
+    """Return the caller's exclude plus the rejected items, newest first, up to the API limit."""
+    if not rejected:
+        return list(exclude) if exclude is not None else None
+    out = dict.fromkeys(exclude or ())
+    for item in reversed(rejected):
+        if len(out) >= MAX_EXCLUDE:
+            break
+        out.setdefault(item)
+    return list(out)
+
+
+def _level(level: object) -> int:
+    if isinstance(level, str) and level in LEVEL_NAMES:
+        return LEVEL_NAMES[level]
+    if isinstance(level, int) and not isinstance(level, bool) and -10 <= level <= 10:
+        return level
+    raise ValueError(f"level must be an integer from -10 to 10 or one of {list(LEVEL_NAMES)}")
+
+
+def _check_ids(**ids: str | None) -> None:
+    for name, value in ids.items():
+        if value is not None and not is_id(value):
+            raise ValueError(f"{name} must be 1-256 bytes of UTF-8 without control characters")
+
+
+def _list(values: Sequence[str] | None) -> list[str] | None:
+    return list(values) if values else None
+
+
+def _compact(fields: dict[str, Any]) -> dict[str, Any]:
+    return {k: v for k, v in fields.items() if v is not None}
+
+
+def _iso(t_ms: int) -> str:
+    moment = datetime.datetime.fromtimestamp(t_ms / 1000, tz=datetime.UTC)
+    return moment.isoformat(timespec="milliseconds").replace("+00:00", "Z")