graphrefly 0.1.0__py3-none-any.whl

graphrefly/extra/backoff.py

@@ -0,0 +1,287 @@
+"""Backoff strategies for :func:`~graphrefly.extra.resilience.retry` and circuit tooling."""
+
+from __future__ import annotations
+
+import random
+from collections.abc import Callable
+from typing import Literal
+
+type JitterMode = Literal["none", "full", "equal"]
+type BackoffPreset = Literal[
+    "constant", "linear", "exponential", "fibonacci", "decorrelated_jitter"
+]
+type BackoffStrategy = Callable[[int, BaseException | None, int | None], int | None]
+
+NS_PER_MS = 1_000_000
+NS_PER_SEC = 1_000_000_000
+
+__all__ = [
+    "BackoffPreset",
+    "BackoffStrategy",
+    "JitterMode",
+    "NS_PER_MS",
+    "NS_PER_SEC",
+    "constant",
+    "decorrelated_jitter",
+    "exponential",
+    "fibonacci",
+    "linear",
+    "resolve_backoff_preset",
+    "with_max_attempts",
+]
+
+
+def _clamp_non_negative(value: int) -> int:
+    return 0 if value < 0 else value
+
+
+def _apply_jitter(delay: int, jitter: JitterMode) -> int:
+    if jitter == "none":
+        return delay
+    if jitter == "full":
+        return random.randint(0, delay) if delay > 0 else 0
+    # "equal" — half deterministic, half random
+    half = delay // 2
+    return half + random.randint(0, delay - half) if delay > 0 else 0
+
+
+def constant(delay_ns: int) -> BackoffStrategy:
+    """Create a backoff strategy that always returns the same delay.
+
+    Args:
+        delay_ns: Fixed delay in nanoseconds (clamped to 0 if negative).
+
+    Returns:
+        A :data:`BackoffStrategy` callable.
+
+    Example:
+        ```python
+        from graphrefly.extra.backoff import constant, NS_PER_SEC
+        s = constant(2 * NS_PER_SEC)
+        assert s(0, None, None) == 2_000_000_000
+        assert s(5, None, None) == 2_000_000_000
+        ```
+    """
+    safe = _clamp_non_negative(delay_ns)
+
+    def _strategy(
+        _attempt: int,
+        _error: BaseException | None = None,
+        _prev_delay: int | None = None,
+    ) -> int:
+        return safe
+
+    return _strategy
+
+
+def linear(base_ns: int, step_ns: int | None = None) -> BackoffStrategy:
+    """Create a backoff strategy with linearly increasing delay.
+
+    Delay is ``base_ns + step_ns * attempt`` where *step_ns* defaults to *base_ns*.
+
+    Args:
+        base_ns: Starting delay in nanoseconds.
+        step_ns: Increment per attempt in nanoseconds (defaults to *base_ns*).
+
+    Returns:
+        A :data:`BackoffStrategy` callable.
+
+    Example:
+        ```python
+        from graphrefly.extra.backoff import linear, NS_PER_SEC
+        s = linear(1 * NS_PER_SEC)
+        assert s(0, None, None) == 1_000_000_000
+        assert s(2, None, None) == 3_000_000_000
+        ```
+    """
+    safe_base = _clamp_non_negative(base_ns)
+    safe_step = safe_base if step_ns is None else _clamp_non_negative(step_ns)
+
+    def _strategy(
+        attempt: int,
+        _error: BaseException | None = None,
+        _prev_delay: int | None = None,
+    ) -> int:
+        return safe_base + safe_step * max(0, attempt)
+
+    return _strategy
+
+
+def exponential(
+    *,
+    base_ns: int = 100_000_000,
+    factor: float = 2.0,
+    max_delay_ns: int = 30_000_000_000,
+    jitter: JitterMode = "none",
+) -> BackoffStrategy:
+    """Create an exponential backoff strategy capped at ``max_delay_ns``.
+
+    Args:
+        base_ns: Initial delay in nanoseconds (default ``100_000_000`` = 100 ms).
+        factor: Multiplicative growth factor >= 1.0 (default ``2.0``).
+        max_delay_ns: Upper bound on delay in nanoseconds (default ``30_000_000_000`` = 30 s).
+        jitter: Jitter mode: ``"none"`` (default), ``"full"``, or ``"equal"``.
+
+    Returns:
+        A :data:`BackoffStrategy` callable.
+
+    Example:
+        ```python
+        from graphrefly.extra.backoff import exponential
+        s = exponential(base_ns=100_000_000, factor=2.0, max_delay_ns=30_000_000_000)
+        assert s(0, None, None) == 100_000_000
+        assert s(1, None, None) == 200_000_000
+        ```
+    """
+    safe_base = _clamp_non_negative(base_ns)
+    safe_factor = 1.0 if factor < 1.0 else factor
+    safe_max = _clamp_non_negative(max_delay_ns)
+
+    def _strategy(
+        attempt: int,
+        _error: BaseException | None = None,
+        _prev_delay: int | None = None,
+    ) -> int:
+        if safe_base == 0:
+            return _apply_jitter(0, jitter)
+        if safe_factor == 1.0:
+            return _apply_jitter(safe_base, jitter)
+
+        cap_ratio = safe_max / safe_base if safe_base > 0 else 0.0
+        raw_attempt = max(0, attempt)
+        growth = 1.0
+        for _ in range(raw_attempt):
+            if growth >= cap_ratio:
+                growth = cap_ratio
+                break
+            growth *= safe_factor
+        delay = int(safe_base * growth)
+        if delay > safe_max:
+            delay = safe_max
+        return _apply_jitter(delay, jitter)
+
+    return _strategy
+
+
+def fibonacci(base_ns: int = 100_000_000, *, max_delay_ns: int = 30_000_000_000) -> BackoffStrategy:
+    """Create a backoff strategy with Fibonacci-scaled delays.
+
+    Delays follow the sequence ``1, 2, 3, 5, 8, ... * base_ns``, capped at
+    ``max_delay_ns``.
+
+    Args:
+        base_ns: Multiplier in nanoseconds (default ``100_000_000`` = 100 ms).
+        max_delay_ns: Upper bound in nanoseconds (default ``30_000_000_000`` = 30 s).
+
+    Returns:
+        A :data:`BackoffStrategy` callable.
+
+    Example:
+        ```python
+        from graphrefly.extra.backoff import fibonacci, NS_PER_SEC
+        s = fibonacci(1 * NS_PER_SEC)
+        assert s(0, None, None) == 1_000_000_000  # 1 * 1s
+        assert s(1, None, None) == 2_000_000_000  # 2 * 1s
+        ```
+    """
+    safe_base = _clamp_non_negative(base_ns)
+    safe_max = _clamp_non_negative(max_delay_ns)
+
+    def _fib_unit(attempt: int) -> int:
+        if attempt <= 0:
+            return 1
+        prev, cur = 1, 2
+        for _ in range(1, attempt):
+            prev, cur = cur, prev + cur
+        return cur
+
+    def _strategy(
+        attempt: int,
+        _error: BaseException | None = None,
+        _prev_delay: int | None = None,
+    ) -> int:
+        raw = _fib_unit(attempt) * safe_base
+        return raw if raw <= safe_max else safe_max
+
+    return _strategy
+
+
+def decorrelated_jitter(
+    base_ns: int = 100_000_000,
+    max_delay_ns: int = 30_000_000_000,
+) -> BackoffStrategy:
+    """Decorrelated jitter (AWS-recommended): ``random(base_ns, min(max, prev * 3))``.
+
+    Stateless — uses ``prev_delay`` (passed by the consumer) instead of closure state.
+    Safe to share across concurrent retry sequences.
+
+    Args:
+        base_ns: Floor of the random range (nanoseconds, default ``100_000_000`` = 100 ms).
+        max_delay_ns: Ceiling cap (nanoseconds, default ``30_000_000_000`` = 30 s).
+    """
+    safe_base = _clamp_non_negative(base_ns)
+    safe_max = _clamp_non_negative(max_delay_ns)
+
+    def _strategy(
+        _attempt: int,
+        _error: BaseException | None = None,
+        prev_delay: int | None = None,
+    ) -> int:
+        last = prev_delay if prev_delay is not None else safe_base
+        ceiling = min(safe_max, last * 3)
+        if ceiling <= safe_base:
+            return safe_base
+        return random.randint(safe_base, ceiling)
+
+    return _strategy
+
+
+def with_max_attempts(strategy: BackoffStrategy, max_attempts: int) -> BackoffStrategy:
+    """Cap any strategy at *max_attempts*; returns ``None`` after the cap.
+
+    Args:
+        strategy: Inner strategy to wrap.
+        max_attempts: Maximum number of attempts (inclusive).
+    """
+
+    def _strategy(
+        attempt: int,
+        error: BaseException | None = None,
+        prev_delay: int | None = None,
+    ) -> int | None:
+        if attempt >= max_attempts:
+            return None
+        return strategy(attempt, error, prev_delay)
+
+    return _strategy
+
+
+def resolve_backoff_preset(name: BackoffPreset) -> BackoffStrategy:
+    """Resolve a preset name string to a :data:`BackoffStrategy` with default parameters.
+
+    Args:
+        name: One of ``"constant"``, ``"linear"``, ``"exponential"``,
+            ``"fibonacci"``, or ``"decorrelated_jitter"``.
+
+    Returns:
+        A :data:`BackoffStrategy` configured with default nanosecond parameters.
+
+    Example:
+        ```python
+        from graphrefly.extra.backoff import resolve_backoff_preset
+        s = resolve_backoff_preset("exponential")
+        assert s(0, None, None) == 100_000_000
+        ```
+    """
+    if name == "constant":
+        return constant(NS_PER_SEC)
+    if name == "linear":
+        return linear(NS_PER_SEC)
+    if name == "exponential":
+        return exponential()
+    if name == "fibonacci":
+        return fibonacci()
+    if name == "decorrelated_jitter":
+        return decorrelated_jitter()
+    msg = f"Unknown backoff preset: {name!r}"
+    raise ValueError(msg)

graphrefly/extra/backpressure.py

@@ -0,0 +1,113 @@
+"""Watermark-based backpressure controller — reactive PAUSE/RESUME flow control.
+
+Purely synchronous, event-driven. No timers, no polling, no async.
+Each controller instance uses a unique lock_id so multiple controllers
+on the same upstream node do not collide.
+"""
+
+from __future__ import annotations
+
+from typing import Any, NamedTuple, Protocol
+
+from graphrefly.core.protocol import MessageType
+
+
+class WatermarkOptions(NamedTuple):
+    """Thresholds for watermark-based backpressure."""
+
+    high_water_mark: int
+    low_water_mark: int
+
+
+class WatermarkController(Protocol):
+    """Watermark-based backpressure controller interface."""
+
+    @property
+    def pending(self) -> int: ...
+    @property
+    def paused(self) -> bool: ...
+    def on_enqueue(self) -> bool: ...
+    def on_dequeue(self) -> bool: ...
+    def dispose(self) -> None: ...
+
+
+class _WatermarkControllerImpl:
+    """Internal implementation — use :func:`create_watermark_controller`."""
+
+    __slots__ = ("_send_up", "_high", "_low", "_lock_id", "_pending", "_paused")
+
+    def __init__(
+        self,
+        send_up: Any,
+        opts: WatermarkOptions,
+    ) -> None:
+        self._send_up = send_up
+        self._high = opts.high_water_mark
+        self._low = opts.low_water_mark
+        self._lock_id: object = object()  # unforgeable identity, like TS Symbol
+        self._pending = 0
+        self._paused = False
+
+    @property
+    def pending(self) -> int:
+        """Number of un-consumed items."""
+        return self._pending
+
+    @property
+    def paused(self) -> bool:
+        """Whether upstream is currently paused by this controller."""
+        return self._paused
+
+    def on_enqueue(self) -> bool:
+        """Call when a DATA message is buffered. Returns ``True`` if PAUSE was sent."""
+        self._pending += 1
+        if not self._paused and self._pending >= self._high:
+            self._paused = True
+            self._send_up([(MessageType.PAUSE, self._lock_id)])
+            return True
+        return False
+
+    def on_dequeue(self) -> bool:
+        """Call when a buffered item is consumed. Returns ``True`` if RESUME was sent."""
+        if self._pending > 0:
+            self._pending -= 1
+        if self._paused and self._pending <= self._low:
+            self._paused = False
+            self._send_up([(MessageType.RESUME, self._lock_id)])
+            return True
+        return False
+
+    def dispose(self) -> None:
+        """If paused, send RESUME to unblock upstream."""
+        if self._paused:
+            self._paused = False
+            self._send_up([(MessageType.RESUME, self._lock_id)])
+
+
+def create_watermark_controller(
+    send_up: Any,
+    opts: WatermarkOptions,
+) -> WatermarkController:
+    """Create a watermark-based backpressure controller.
+
+    Purely synchronous, event-driven. No timers, no polling, no async.
+    Each controller instance uses a unique ``lock_id`` (``object()``) so
+    multiple controllers on the same upstream node do not collide.
+
+    Args:
+        send_up: Callback that delivers messages upstream (e.g. ``handle.up``).
+        opts: High/low watermark thresholds (item counts).
+
+    Returns:
+        A :class:`WatermarkController`.
+
+    Raises:
+        ValueError: If watermark options are invalid.
+    """
+    if opts.high_water_mark < 1:
+        raise ValueError("high_water_mark must be >= 1")
+    if opts.low_water_mark < 0:
+        raise ValueError("low_water_mark must be >= 0")
+    if opts.low_water_mark >= opts.high_water_mark:
+        raise ValueError("low_water_mark must be < high_water_mark")
+    return _WatermarkControllerImpl(send_up, opts)

graphrefly/extra/checkpoint.py

@@ -0,0 +1,307 @@
+"""Checkpoint adapters and :class:`~graphrefly.graph.Graph` save/restore helpers (roadmap §3.1)."""
+
+from __future__ import annotations
+
+import json
+import os
+import sqlite3
+import tempfile
+import warnings
+from contextlib import suppress
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, Protocol, runtime_checkable
+
+if TYPE_CHECKING:
+    from graphrefly.core.node import Node
+    from graphrefly.graph.graph import Graph
+
+__all__ = [
+    "CheckpointAdapter",
+    "DictCheckpointAdapter",
+    "FileCheckpointAdapter",
+    "MemoryCheckpointAdapter",
+    "SqliteCheckpointAdapter",
+    "checkpoint_node_value",
+    "restore_graph_checkpoint",
+    "save_graph_checkpoint",
+]
+
+
+@runtime_checkable
+class CheckpointAdapter(Protocol):
+    """JSON-friendly snapshot persistence (single blob in / out)."""
+
+    def save(self, data: dict[str, Any]) -> None: ...
+    def load(self) -> dict[str, Any] | None: ...
+
+
+class MemoryCheckpointAdapter:
+    """In-memory checkpoint adapter (process-local; useful for tests and embedding).
+
+    Stores a deep-copy of the snapshot so mutations to the saved dict do not
+    affect the stored state.
+
+    Example:
+        ```python
+        from graphrefly import Graph, state
+        from graphrefly.extra.checkpoint import MemoryCheckpointAdapter, save_graph_checkpoint
+        g = Graph("g"); g.add("x", state(1))
+        adapter = MemoryCheckpointAdapter()
+        save_graph_checkpoint(g, adapter)
+        assert adapter.load()["nodes"]["x"]["value"] == 1
+        ```
+    """
+
+    __slots__ = ("_data",)
+
+    def __init__(self) -> None:
+        self._data: dict[str, Any] | None = None
+
+    def save(self, data: dict[str, Any]) -> None:
+        self._data = json.loads(json.dumps(data, ensure_ascii=False))
+
+    def load(self) -> dict[str, Any] | None:
+        return None if self._data is None else dict(self._data)
+
+
+class DictCheckpointAdapter:
+    """Store a checkpoint under a fixed key inside a caller-owned ``dict``.
+
+    Useful for tests or environments where you already manage a shared dict.
+
+    Args:
+        storage: The dict to store the checkpoint in.
+        key: Key under which the snapshot is stored (default ``"graphrefly_checkpoint"``).
+
+    Example:
+        ```python
+        from graphrefly.extra.checkpoint import DictCheckpointAdapter
+        store = {}
+        adapter = DictCheckpointAdapter(store)
+        adapter.save({"version": 1, "nodes": {}, "edges": [], "subgraphs": [], "name": "g"})
+        assert "graphrefly_checkpoint" in store
+        ```
+    """
+
+    __slots__ = ("_key", "_storage")
+
+    def __init__(self, storage: dict[str, Any], *, key: str = "graphrefly_checkpoint") -> None:
+        self._storage = storage
+        self._key = key
+
+    def save(self, data: dict[str, Any]) -> None:
+        self._storage[self._key] = json.loads(json.dumps(data, ensure_ascii=False))
+
+    def load(self) -> dict[str, Any] | None:
+        raw = self._storage.get(self._key)
+        return dict(raw) if isinstance(raw, dict) else None
+
+
+class FileCheckpointAdapter:
+    """Persist checkpoint data as JSON to a file using atomic write-then-replace.
+
+    Writes to a temporary file in the same directory, then renames it over the
+    target path to avoid partial writes.
+
+    Args:
+        path: Destination file path (``str`` or :class:`pathlib.Path`).
+
+    Example:
+        ```python
+        import tempfile, os
+        from graphrefly.extra.checkpoint import FileCheckpointAdapter
+        with tempfile.NamedTemporaryFile(suffix=".json", delete=False) as f:
+            tmp = f.name
+        adapter = FileCheckpointAdapter(tmp)
+        adapter.save({"version": 1, "nodes": {}, "edges": [], "subgraphs": [], "name": "g"})
+        assert os.path.exists(tmp)
+        os.unlink(tmp)
+        ```
+    """
+
+    __slots__ = ("_path",)
+
+    def __init__(self, path: str | Path) -> None:
+        self._path = Path(path)
+
+    def save(self, data: dict[str, Any]) -> None:
+        self._path.parent.mkdir(parents=True, exist_ok=True)
+        payload = json.dumps(data, ensure_ascii=False, sort_keys=True, separators=(",", ":"))
+        fd, tmp = tempfile.mkstemp(
+            dir=self._path.parent,
+            prefix=f".{self._path.name}.",
+            suffix=".tmp",
+        )
+        try:
+            with os.fdopen(fd, "w", encoding="utf-8") as f:
+                f.write(payload)
+                f.write("\n")
+            os.replace(tmp, self._path)
+        except BaseException:
+            with suppress(FileNotFoundError):
+                os.unlink(tmp)
+            raise
+
+    def load(self) -> dict[str, Any] | None:
+        if not self._path.is_file():
+            return None
+        text = self._path.read_text(encoding="utf-8")
+        if not text.strip():
+            return None
+        data = json.loads(text)
+        return data if isinstance(data, dict) else None
+
+
+def _stable_snapshot_json(data: dict[str, Any]) -> str:
+    return json.dumps(data, ensure_ascii=False, sort_keys=True, separators=(",", ":"))
+
+
+class SqliteCheckpointAdapter:
+    """Persist one checkpoint blob under a fixed key using :mod:`sqlite3` (stdlib, zero deps).
+
+    Uses a single-row table. Call :meth:`close` when the adapter is no longer needed.
+
+    Args:
+        path: Path to the SQLite database file (``str`` or :class:`pathlib.Path`).
+        key: Row key for the checkpoint (default ``"graphrefly_checkpoint"``).
+
+    Example:
+        ```python
+        import tempfile, os
+        from graphrefly.extra.checkpoint import SqliteCheckpointAdapter
+        with tempfile.NamedTemporaryFile(suffix=".db", delete=False) as f:
+            tmp = f.name
+        adapter = SqliteCheckpointAdapter(tmp)
+        adapter.save({"version": 1, "nodes": {}, "edges": [], "subgraphs": [], "name": "g"})
+        assert adapter.load()["version"] == 1
+        adapter.close()
+        os.unlink(tmp)
+        ```
+    """
+
+    __slots__ = ("_conn", "_key")
+
+    def __init__(self, path: str | Path, *, key: str = "graphrefly_checkpoint") -> None:
+        self._conn = sqlite3.connect(str(path))
+        self._key = key
+        self._conn.execute(
+            "CREATE TABLE IF NOT EXISTS graphrefly_checkpoint (k TEXT PRIMARY KEY, v TEXT NOT NULL)"
+        )
+        self._conn.commit()
+
+    def save(self, data: dict[str, Any]) -> None:
+        payload = _stable_snapshot_json(data)
+        self._conn.execute(
+            "INSERT OR REPLACE INTO graphrefly_checkpoint (k, v) VALUES (?, ?)",
+            (self._key, payload),
+        )
+        self._conn.commit()
+
+    def load(self) -> dict[str, Any] | None:
+        row = self._conn.execute(
+            "SELECT v FROM graphrefly_checkpoint WHERE k = ?", (self._key,)
+        ).fetchone()
+        if row is None or not isinstance(row[0], str) or not row[0].strip():
+            return None
+        parsed = json.loads(row[0])
+        return parsed if isinstance(parsed, dict) else None
+
+    def close(self) -> None:
+        """Close the underlying SQLite connection (safe to call more than once)."""
+        with suppress(Exception):
+            self._conn.close()
+
+
+def _check_json_serializable(data: dict[str, Any]) -> None:
+    """Warn when snapshot values are not JSON-serializable."""
+    try:
+        json.dumps(data, ensure_ascii=False)
+    except (TypeError, ValueError) as exc:
+        warnings.warn(
+            f"Snapshot contains non-JSON-serializable values: {exc}. "
+            "This may cause errors when persisting to JSON-based adapters.",
+            stacklevel=3,
+        )
+
+
+def save_graph_checkpoint(graph: Graph, adapter: CheckpointAdapter) -> None:
+    """Persist a :meth:`~graphrefly.graph.Graph.snapshot` via a :class:`CheckpointAdapter`.
+
+    Args:
+        graph: The :class:`~graphrefly.graph.Graph` to snapshot.
+        adapter: Any :class:`CheckpointAdapter` (memory, file, SQLite, etc.).
+
+    Example:
+        ```python
+        from graphrefly import Graph, state
+        from graphrefly.extra.checkpoint import MemoryCheckpointAdapter, save_graph_checkpoint
+        g = Graph("g"); g.add("x", state(5))
+        adapter = MemoryCheckpointAdapter()
+        save_graph_checkpoint(g, adapter)
+        ```
+    """
+    snap = graph.snapshot()
+    _check_json_serializable(snap)
+    adapter.save(snap)
+
+
+def restore_graph_checkpoint(graph: Graph, adapter: CheckpointAdapter) -> bool:
+    """Load a snapshot from *adapter* and apply it to *graph*.
+
+    Uses :meth:`~graphrefly.graph.Graph.restore` for application.
+
+    Args:
+        graph: The target :class:`~graphrefly.graph.Graph`.
+        adapter: Any :class:`CheckpointAdapter` to load from.
+
+    Returns:
+        ``True`` if snapshot data existed and was applied; ``False`` if the adapter
+        had no saved data.
+
+    Example:
+        ```python
+        from graphrefly import Graph, state
+        from graphrefly.extra.checkpoint import (
+            MemoryCheckpointAdapter,
+            restore_graph_checkpoint,
+            save_graph_checkpoint,
+        )
+        g = Graph("g"); x = state(0); g.add("x", x)
+        adapter = MemoryCheckpointAdapter()
+        save_graph_checkpoint(g, adapter)
+        x.down([("DATA", 99)])
+        restored = restore_graph_checkpoint(g, adapter)
+        assert restored and g.get("x") == 0
+        ```
+    """
+    data = adapter.load()
+    if data is None:
+        return False
+    graph.restore(data)
+    return True
+
+
+def checkpoint_node_value(node: Node[Any]) -> dict[str, Any]:
+    """Build a minimal versioned JSON payload for a single node's last cached value.
+
+    Useful for custom adapters that persist individual nodes rather than whole
+    graph snapshots. Emits a warning when the value is not JSON-serializable.
+
+    Args:
+        node: Any :class:`~graphrefly.core.node.Node` whose ``get()`` value to capture.
+
+    Returns:
+        A ``dict`` with ``version`` (``1``) and ``value`` keys.
+
+    Example:
+        ```python
+        from graphrefly import state
+        from graphrefly.extra.checkpoint import checkpoint_node_value
+        x = state(42)
+        payload = checkpoint_node_value(x)
+        assert payload == {"version": 1, "value": 42}
+        ```
+    """
+    result: dict[str, Any] = {"version": 1, "value": node.get()}
+    _check_json_serializable(result)
+    return result