@lovrozagar/honey 0.6.8 → 0.7.0

package/dist/client-python/_invalidation.py

@@ -0,0 +1,494 @@
+from __future__ import annotations
+
+import asyncio
+import re
+import threading
+import time
+from collections import OrderedDict
+from dataclasses import dataclass, field
+from typing import Any
+from urllib.parse import quote
+
+
+def _now() -> float:
+    return time.monotonic()
+
+
+# `{name}` (any name without braces or slashes) or a `:name` segment; a colon
+# inside a segment (`/ops/{id}:cancel`) is literal.
+_PATH_PARAM_RE = re.compile(r"\{([^{}/]+)\}|(?:(?<=/)|^):([a-zA-Z_][a-zA-Z0-9_]*)")
+
+
+@dataclass
+class _StaleEntry:
+    by: list[str] = field(default_factory=list)
+    seq: int = 0
+    until: float = 0.0
+
+
+@dataclass
+class _RequestMeta:
+    selector: str
+    is_stale: bool
+    invalidated_by: list[str]
+    seq_snapshot: int
+
+
+def path_matches_pattern(
+    path: str,
+    pattern: str,
+    _cache: dict[str, re.Pattern[str]] = {},
+) -> bool:
+    """Match *path* against *pattern* containing ``{name}`` / ``:name`` placeholders."""
+    if pattern not in _cache:
+        escaped_parts: list[str] = []
+        last_end = 0
+        for match in _PATH_PARAM_RE.finditer(pattern):
+            escaped_parts.append(re.escape(pattern[last_end : match.start()]))
+            escaped_parts.append("[^/]+")
+            last_end = match.end()
+        escaped_parts.append(re.escape(pattern[last_end:]))
+        _cache[pattern] = re.compile(f"^{''.join(escaped_parts)}$")
+    return bool(_cache[pattern].match(path))
+
+
+def interpolate_path(template: str, params: dict[str, str] | None) -> str:
+    """Substitute ``{name}`` / ``:name`` placeholders in *template* using *params*.
+
+    Raises ValueError if any placeholder has no matching key in *params*.
+    """
+    if not params:
+        if _PATH_PARAM_RE.search(template) is not None:
+            raise ValueError(f"Missing path params for template {template!r}")
+        return template
+
+    def _sub(match: re.Match[str]) -> str:
+        key = match.group(1) or match.group(2)
+        if key not in params or params[key] is None:
+            raise ValueError(f"Missing path param: {key}")
+        return quote(str(params[key]), safe="")
+
+    return _PATH_PARAM_RE.sub(_sub, template)
+
+
+def _has_unresolved(value: str) -> bool:
+    return _PATH_PARAM_RE.search(value) is not None
+
+
+def resolve_invalidation_targets_for_mutation(
+    targets: list[str],
+    params: dict[str, str] | None,
+) -> list[str]:
+    """Expand ``METHOD /path/{id}`` template invalidation targets to concrete selectors.
+
+    Targets without placeholders are passed through. A target whose placeholders cannot
+    all be resolved stays a pattern, so it marks every instance stale (TS parity).
+    """
+    resolved: list[str] = []
+    for entry in targets:
+        space_idx = entry.find(" ")
+        if space_idx == -1:
+            resolved.append(entry)
+            continue
+        method = entry[:space_idx]
+        template = entry[space_idx + 1 :]
+        if not _has_unresolved(template):
+            resolved.append(entry)
+            continue
+        try:
+            concrete = interpolate_path(template, params)
+        except ValueError:
+            resolved.append(entry)
+            continue
+        resolved.append(f"{method} {concrete}")
+    return resolved
+
+
+def resolve_invalidation_targets(
+    invalidate: list[str],
+    stale_map: "OrderedDict[str, _StaleEntry] | OrderedDict[str, Any]",
+) -> list[str]:
+    """Return *stale_map* keys matching any 'METHOD /pattern' invalidation entry.
+
+    Kept for back-compat with existing call sites that pass an already-built map.
+    """
+    matched: list[str] = []
+    for entry in invalidate:
+        for key in list(stale_map.keys()):
+            parts = key.split(" ", 1)
+            if len(parts) != 2:
+                continue
+            key_method, key_path = parts
+            entry_parts = entry.split(" ", 1)
+            if len(entry_parts) != 2:
+                continue
+            entry_method, entry_pattern = entry_parts
+            if key_method != entry_method:
+                continue
+            if path_matches_pattern(key_path, entry_pattern):
+                matched.append(key)
+    return matched
+
+
+def lookup_stale(key: str, stale_map: "OrderedDict[str, Any]") -> bool:
+    """Return True if *key* exists in *stale_map* and has not yet expired."""
+    entry = stale_map.get(key)
+    if entry is None:
+        return False
+    until = entry.until if isinstance(entry, _StaleEntry) else entry["until"]
+    return _now() < until
+
+
+class _StaleStore:
+    """Stale state shared by the async and sync trackers; callers hold their own lock.
+
+    Concrete keys are looked up directly; keys that still hold ``{name}``
+    placeholders are also indexed per method, so a lookup scans only the patterns
+    of its method, not every entry. Expired concrete entries go on access, expired
+    patterns when scanned, and the rest when the map is over capacity.
+    """
+
+    def __init__(
+        self, stale_time: float, stale_max_entries: int, max_sources_per_target: int
+    ) -> None:
+        self.enabled = stale_time > 0
+        self.stale_time = max(stale_time, 0.0)
+        self.max_entries = max(stale_max_entries, 1)
+        self.max_sources = max(max_sources_per_target, 1)
+        self.map: OrderedDict[str, _StaleEntry] = OrderedDict()
+        self.patterns: dict[str, dict[str, None]] = {}
+        self.seq = 0
+
+    def delete(self, key: str) -> None:
+        if self.map.pop(key, None) is None:
+            return
+        method, path = _split_key(key)
+        bucket = self.patterns.get(method)
+        if bucket is not None and _has_unresolved(path):
+            bucket.pop(key, None)
+            if not bucket:
+                del self.patterns[method]
+
+    def upsert(
+        self, key: str, until: float, seq: int, mutation_selector: str | None
+    ) -> None:
+        existing = self.map.get(key)
+        if existing is not None:
+            existing.until = until
+            existing.seq = seq
+            if mutation_selector and mutation_selector not in existing.by:
+                if len(existing.by) < self.max_sources:
+                    existing.by.append(mutation_selector)
+            self.map.move_to_end(key)
+            return
+        by = [mutation_selector] if mutation_selector else []
+        self.map[key] = _StaleEntry(by=by, seq=seq, until=until)
+        method, path = _split_key(key)
+        if _has_unresolved(path):
+            self.patterns.setdefault(method, {})[key] = None
+
+    def invalidate(self, patterns: list[str]) -> None:
+        self.evict_expired()
+        targets = resolve_invalidation_targets(patterns, self.map)
+        self.seq += 1
+        until = _now() + self.stale_time
+        for t in targets:
+            self.upsert(t, until, self.seq, None)
+        self.enforce_capacity()
+
+    def mark_stale(
+        self,
+        invalidate: list[str],
+        params: dict[str, str] | None,
+        mutation_selector: str,
+    ) -> None:
+        self.seq += 1
+        until = _now() + self.stale_time
+        for target in resolve_invalidation_targets_for_mutation(invalidate, params):
+            self.upsert(target, until, self.seq, mutation_selector)
+        self.enforce_capacity()
+
+    def mark(self, key: str) -> None:
+        self.seq += 1
+        self.upsert(key, _now() + self.stale_time, self.seq, None)
+        self.enforce_capacity()
+
+    def lookup(
+        self, concrete_selector: str, concrete_path: str, method: str, now: float
+    ) -> tuple[list[str], bool]:
+        all_by: list[str] = []
+        exact = self.map.get(concrete_selector)
+        if exact is not None:
+            if exact.until > now:
+                all_by.extend(exact.by)
+            else:
+                self.delete(concrete_selector)
+        expired: list[str] = []
+        for key in self.patterns.get(method, {}):
+            entry = self.map[key]
+            if entry.until <= now:
+                expired.append(key)
+                continue
+            if key != concrete_selector and path_matches_pattern(
+                concrete_path, _split_key(key)[1]
+            ):
+                all_by.extend(entry.by)
+        for key in expired:
+            self.delete(key)
+        deduped = list(dict.fromkeys(all_by))
+        return deduped, len(deduped) > 0
+
+    def clear(
+        self, concrete_selector: str, concrete_path: str, method: str, seq_snapshot: int
+    ) -> None:
+        exact = self.map.get(concrete_selector)
+        if exact and exact.seq <= seq_snapshot:
+            self.delete(concrete_selector)
+        to_delete = [
+            key
+            for key in self.patterns.get(method, {})
+            if self.map[key].seq <= seq_snapshot
+            and path_matches_pattern(concrete_path, _split_key(key)[1])
+        ]
+        for key in to_delete:
+            self.delete(key)
+
+    def request_meta(
+        self, concrete_selector: str, concrete_path: str, method: str
+    ) -> _RequestMeta:
+        by, is_stale = self.lookup(concrete_selector, concrete_path, method, _now())
+        return _RequestMeta(
+            selector=concrete_selector,
+            is_stale=is_stale,
+            invalidated_by=by,
+            seq_snapshot=self.seq,
+        )
+
+    def evict_expired(self) -> None:
+        now = _now()
+        for key in [k for k, v in self.map.items() if now >= v.until]:
+            self.delete(key)
+
+    def enforce_capacity(self) -> None:
+        if len(self.map) <= self.max_entries:
+            return
+        self.evict_expired()
+        target = max(self.max_entries // 2, 1)
+        while len(self.map) > target:
+            self.delete(next(iter(self.map)))
+
+
+def _split_key(key: str) -> tuple[str, str]:
+    space_idx = key.find(" ")
+    if space_idx == -1:
+        return key, ""
+    return key[:space_idx], key[space_idx + 1 :]
+
+
+def _split_method_path(method_or_key: str, path: str | None) -> tuple[str, str]:
+    if path is None:
+        return _split_key(method_or_key)
+    return method_or_key, path
+
+
+class _StaleTracker:
+    """Async-aware stale tracker backed by ``asyncio.Lock``."""
+
+    def __init__(
+        self,
+        stale_time: float,
+        stale_max_entries: int = 1000,
+        max_sources_per_target: int = 16,
+    ) -> None:
+        """stale_time == 0 disables the tracker (no stale window applied)."""
+        self._store = _StaleStore(stale_time, stale_max_entries, max_sources_per_target)
+        self._lock = asyncio.Lock()
+
+    @property
+    def enabled(self) -> bool:
+        return self._store.enabled
+
+    @property
+    def _map(self) -> "OrderedDict[str, _StaleEntry]":
+        return self._store.map
+
+    async def invalidate(self, patterns: list[str]) -> None:
+        """Mark every existing key matching *patterns* as freshly stale."""
+        if not self.enabled:
+            return
+        async with self._lock:
+            self._store.invalidate(patterns)
+
+    async def mark_stale(
+        self,
+        invalidate: list[str],
+        params: dict[str, str] | None,
+        mutation_selector: str,
+    ) -> None:
+        """Bump seq, expand templated invalidation entries, store stale keys."""
+        if not self.enabled or not invalidate:
+            return
+        async with self._lock:
+            self._store.mark_stale(invalidate, params, mutation_selector)
+
+    async def mark(self, key: str) -> None:
+        """Force *key* into the stale map. Used by SSE/WS open hooks and tests."""
+        if not self.enabled:
+            return
+        async with self._lock:
+            self._store.mark(key)
+
+    async def is_stale(self, method_or_key: str, path: str | None = None) -> bool:
+        """Return True if (method, path) is currently stale.
+
+        Accepts either ``is_stale("GET /users")`` or ``is_stale("GET", "/users")``.
+        Walks pattern entries too.
+        """
+        if not self.enabled:
+            return False
+        method, concrete_path = _split_method_path(method_or_key, path)
+        async with self._lock:
+            return self._store.lookup(
+                f"{method} {concrete_path}", concrete_path, method, _now()
+            )[1]
+
+    async def lookup_stale(
+        self,
+        concrete_selector: str,
+        concrete_path: str,
+        method: str,
+    ) -> tuple[list[str], bool]:
+        """Return (invalidated_by_list, is_stale): exact + pattern lookup with sweep."""
+        if not self.enabled:
+            return [], False
+        async with self._lock:
+            return self._store.lookup(concrete_selector, concrete_path, method, _now())
+
+    async def clear_stale(
+        self,
+        concrete_selector: str,
+        concrete_path: str,
+        method: str,
+        seq_snapshot: int,
+    ) -> None:
+        """Drop seq-older entries matching *concrete_path* (exact + pattern keys)."""
+        if not self.enabled:
+            return
+        async with self._lock:
+            self._store.clear(concrete_selector, concrete_path, method, seq_snapshot)
+
+    async def build_request_meta(
+        self,
+        concrete_selector: str,
+        concrete_path: str,
+        method: str,
+    ) -> _RequestMeta | None:
+        if not self.enabled:
+            return None
+        async with self._lock:
+            return self._store.request_meta(concrete_selector, concrete_path, method)
+
+    @staticmethod
+    def _split_key(key: str) -> tuple[str, str]:
+        return _split_key(key)
+
+
+class _StaleTrackerSync:
+    """Sync variant backed by ``threading.Lock``; mirrors :class:`_StaleTracker`."""
+
+    def __init__(
+        self,
+        stale_time: float,
+        stale_max_entries: int = 1000,
+        max_sources_per_target: int = 16,
+    ) -> None:
+        """stale_time == 0 disables the tracker (no stale window applied)."""
+        self._store = _StaleStore(stale_time, stale_max_entries, max_sources_per_target)
+        self._lock = threading.Lock()
+
+    @property
+    def enabled(self) -> bool:
+        return self._store.enabled
+
+    @property
+    def _map(self) -> "OrderedDict[str, _StaleEntry]":
+        return self._store.map
+
+    def invalidate(self, patterns: list[str]) -> None:
+        if not self.enabled:
+            return
+        with self._lock:
+            self._store.invalidate(patterns)
+
+    def mark_stale(
+        self,
+        invalidate: list[str],
+        params: dict[str, str] | None,
+        mutation_selector: str,
+    ) -> None:
+        if not self.enabled or not invalidate:
+            return
+        with self._lock:
+            self._store.mark_stale(invalidate, params, mutation_selector)
+
+    def mark(self, key: str) -> None:
+        if not self.enabled:
+            return
+        with self._lock:
+            self._store.mark(key)
+
+    def is_stale(self, method_or_key: str, path: str | None = None) -> bool:
+        if not self.enabled:
+            return False
+        method, concrete_path = _split_method_path(method_or_key, path)
+        with self._lock:
+            return self._store.lookup(
+                f"{method} {concrete_path}", concrete_path, method, _now()
+            )[1]
+
+    def lookup_stale(
+        self,
+        concrete_selector: str,
+        concrete_path: str,
+        method: str,
+    ) -> tuple[list[str], bool]:
+        if not self.enabled:
+            return [], False
+        with self._lock:
+            return self._store.lookup(concrete_selector, concrete_path, method, _now())
+
+    def clear_stale(
+        self,
+        concrete_selector: str,
+        concrete_path: str,
+        method: str,
+        seq_snapshot: int,
+    ) -> None:
+        if not self.enabled:
+            return
+        with self._lock:
+            self._store.clear(concrete_selector, concrete_path, method, seq_snapshot)
+
+    def build_request_meta(
+        self,
+        concrete_selector: str,
+        concrete_path: str,
+        method: str,
+    ) -> _RequestMeta | None:
+        if not self.enabled:
+            return None
+        with self._lock:
+            return self._store.request_meta(concrete_selector, concrete_path, method)
+
+
+__all__ = [
+    "_RequestMeta",
+    "_StaleEntry",
+    "_StaleTracker",
+    "_StaleTrackerSync",
+    "interpolate_path",
+    "lookup_stale",
+    "path_matches_pattern",
+    "resolve_invalidation_targets",
+    "resolve_invalidation_targets_for_mutation",
+]

package/dist/client-python/_realtime.py

@@ -0,0 +1,179 @@
+from __future__ import annotations
+
+import asyncio
+import random
+from enum import Enum
+from typing import Any, AsyncIterator
+
+from ._transport import (
+    TransportAdapter,
+    TransportConn,
+    TransportKind,
+    TransportOpts,
+)
+
+MAX_RECONNECT_DELAY = 30.0
+
+
+class ConnectionState(str, Enum):
+    CONNECTING = "connecting"
+    CONNECTED = "connected"
+    RECONNECTING = "reconnecting"
+    DISCONNECTED = "disconnected"
+
+
+class ResumableConnection:
+    """Orchestrates a pluggable TransportAdapter chain.
+
+    Mirrors TS `createResumableConnection` + Rust `ResumableConnection::connect`:
+    - Ordered `transports` chain tried in order on first connect.
+    - First successful adapter index memoized in `_proven_index`.
+    - On reconnect, proven adapter tried first; full chain on failure.
+    - State transitions drive `.state` property.
+
+    A dropped connection (including a clean end of an SSE stream) reconnects
+    with exponential backoff and jitter. The attempt counter resets after every
+    delivered message, so `max_reconnect_attempts` limits consecutive failures,
+    not lifetime drops. When the attempts run out the iterator raises the last
+    error instead of ending silently. Cancellation is never swallowed.
+    """
+
+    def __init__(
+        self,
+        base_url: str,
+        transports: list[TransportAdapter],
+        opts: TransportOpts | None = None,
+    ) -> None:
+        if not transports:
+            raise ValueError(
+                "ResumableConnection requires at least one transport adapter",
+            )
+        self._url = base_url
+        self._transports = transports
+        self._opts = opts or TransportOpts()
+        self._state: ConnectionState = ConnectionState.DISCONNECTED
+        self._conn: TransportConn | None = None
+        self._proven_index: int | None = None
+        self._reconnect_attempts: int = 0
+        self._closed: bool = False
+
+    @property
+    def state(self) -> ConnectionState:
+        return self._state
+
+    @property
+    def proven_transport(self) -> TransportKind | None:
+        if self._proven_index is None:
+            return None
+        if self._proven_index >= len(self._transports):
+            return None
+        return self._transports[self._proven_index].kind()
+
+    async def connect(self) -> None:
+        if self._closed:
+            raise RuntimeError("ResumableConnection is closed")
+        if self._state == ConnectionState.CONNECTED:
+            return
+        has_prior = self._conn is not None or self._proven_index is not None
+        self._state = (
+            ConnectionState.RECONNECTING if has_prior else ConnectionState.CONNECTING
+        )
+        await self._open_chain()
+
+    async def _open_chain(self) -> None:
+        last_err: Exception | None = None
+        order: list[int] = []
+        if self._proven_index is not None and self._proven_index < len(
+            self._transports
+        ):
+            order.append(self._proven_index)
+        order.extend(i for i in range(len(self._transports)) if i not in order)
+        for idx in order:
+            adapter = self._transports[idx]
+            try:
+                conn = await adapter.connect(self._url, self._opts)
+            except Exception as exc:  # CancelledError is a BaseException: it propagates
+                last_err = exc
+                continue
+            if self._closed:
+                await _close_quietly(conn)
+                raise RuntimeError("ResumableConnection is closed")
+            self._conn = conn
+            self._proven_index = idx
+            self._state = ConnectionState.CONNECTED
+            return
+        self._state = ConnectionState.DISCONNECTED
+        if last_err is not None:
+            raise last_err
+        raise RuntimeError("no transports configured")
+
+    async def send(self, data: Any) -> None:
+        if self._conn is None:
+            raise RuntimeError("not connected")
+        await self._conn.send(data)
+
+    async def close(self) -> None:
+        self._closed = True
+        self._state = ConnectionState.DISCONNECTED
+        if self._conn is not None:
+            conn = self._conn
+            self._conn = None
+            await _close_quietly(conn)
+
+    def _delay(self, attempt: int) -> float:
+        base = max(self._opts.reconnect_delay_ms, 0) / 1000.0
+        delay = min(base * (2 ** (attempt - 1)), MAX_RECONNECT_DELAY)
+        return delay / 2 + random.uniform(0, delay / 2)
+
+    def __aiter__(self) -> AsyncIterator[Any]:
+        return self._iter()
+
+    async def _iter(self) -> AsyncIterator[Any]:
+        if self._conn is None and not self._closed:
+            await self.connect()
+        while not self._closed:
+            conn = self._conn
+            if conn is None:
+                return
+            try:
+                value = await conn.recv()
+            except asyncio.CancelledError:
+                raise
+            except Exception as exc:
+                # transport died or the stream ended: drop it and reconnect with backoff
+                last_err: Exception = exc
+                self._conn = None
+                self._proven_index = None
+                self._state = ConnectionState.RECONNECTING
+                await _close_quietly(conn)
+                while True:
+                    if self._closed:
+                        return
+                    self._reconnect_attempts += 1
+                    max_attempts = self._opts.max_reconnect_attempts
+                    if max_attempts > 0 and self._reconnect_attempts > max_attempts:
+                        self._state = ConnectionState.DISCONNECTED
+                        if isinstance(last_err, StopAsyncIteration):
+                            return
+                        raise last_err
+                    await asyncio.sleep(self._delay(self._reconnect_attempts))
+                    try:
+                        await self._open_chain()
+                        break
+                    except asyncio.CancelledError:
+                        raise
+                    except Exception as reopen_exc:
+                        last_err = reopen_exc
+                continue
+            self._reconnect_attempts = 0
+            yield value
+
+
+async def _close_quietly(conn: TransportConn) -> None:
+    try:
+        await conn.close()
+    except Exception:
+        pass
+
+
+__all__ = ["ConnectionState", "ResumableConnection"]