memwal 0.1.11.dev1__tar.gz → 0.1.11.dev2__tar.gz

{memwal-0.1.11.dev1 → memwal-0.1.11.dev2}/CHANGELOG.md

@@ -1,5 +1,12 @@
 # memwal
 
+## 0.1.12
+
+### Fixed
+
+- Grow `wait_for_remember_job` / `wait_for_remember_jobs` poll delay 1.5× from the caller interval (floor 100ms) toward a 5s cap, with an immediate first poll. Backoff is disabled above the cap. (WALM-623)
+- A 429 during a remember-job wait is reported on the timeout. Retry-After is still clamped to the caller's remaining budget, and that remainder still buys one status read. (WALM-623)
+
 ## 0.1.11
 
 ### Added

{memwal-0.1.11.dev1 → memwal-0.1.11.dev2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: memwal
-Version: 0.1.11.dev1
+Version: 0.1.11.dev2
 Summary: Python SDK for Walrus Memory — Privacy-first AI memory with Ed25519 signing
 Project-URL: Homepage, https://memory.walrus.xyz
 Project-URL: Documentation, https://memory.walrus.xyz

{memwal-0.1.11.dev1 → memwal-0.1.11.dev2}/memwal/__init__.py

@@ -126,4 +126,4 @@ __all__ = [
     "RecallManualResult",
 ]
 
-__version__ = "0.1.11.dev1"
+__version__ = "0.1.11.dev2"

{memwal-0.1.11.dev1 → memwal-0.1.11.dev2}/memwal/client.py

@@ -170,18 +170,57 @@ async def _sleep_ms(ms: int) -> None:
 
 
 def _polling_delay_ms(base_ms: int, attempt: int) -> int:
-    """Jittered exponential backoff matching TS ``pollingDelayMs``.
-
-    base * 1.5^min(attempt, 6), capped at 10s, with ±25% jitter so
-    concurrent clients don't synchronise.
-    """
+    """Same formula as TS ``pollingDelayMs``."""
 
+    if attempt == 0:
+        return 0
     base = max(100, base_ms)
-    capped = min(10_000, base * (1.5 ** min(attempt, 6)))
+    ceiling = max(5000, base)
+    capped = min(ceiling, base * (1.5 ** min(attempt - 1, 6)))
     jitter = 0.75 + random.random() * 0.5
     return int(capped * jitter)
 
 
+def _positive_retry_ms(raw: object) -> Optional[int]:
+    try:
+        seconds = float(raw)  # type: ignore[arg-type]
+    except (TypeError, ValueError):
+        return None
+    if seconds <= 0 or seconds != seconds or seconds == float("inf"):
+        return None
+    return int(seconds * 1000)
+
+
+def _retry_after_ms(err: "_HttpStatusError") -> int:
+    """Retry-After seconds, else JSON ``retry_after_seconds``, in ms."""
+
+    if err.retry_after:
+        header_ms = _positive_retry_ms(err.retry_after)
+        if header_ms is not None:
+            return header_ms
+    if not err.body:
+        return 0
+    try:
+        payload = json.loads(err.body)
+    except json.JSONDecodeError:
+        return 0
+    if not isinstance(payload, dict):
+        return 0
+    return _positive_retry_ms(payload.get("retry_after_seconds")) or 0
+
+
+def _clamped_retry_after_ms(err: "_HttpStatusError", deadline_ms: int) -> int:
+    """Clamp Retry-After to the time left. 0 means use the normal curve."""
+
+    delay = _retry_after_ms(err)
+    if delay <= 0:
+        return 0
+    remaining = deadline_ms - _now_ms()
+    if remaining <= 0:
+        return 0
+    return min(delay, remaining)
+
+
 def _is_transient_polling_status(status: int) -> bool:
     """Classify HTTP status codes for the polling retry loop.
 
@@ -423,17 +462,23 @@ class MemWal:
         - Accepts 200 + 404 from the status endpoint and dispatches on
           ``status`` field (404 / ``status == "not_found"`` raises).
         - Transient HTTP errors (429, 5xx, network drop) are retried until
-          the timeout, not surfaced as polling failures.
-        - Backoff is jittered exponential (1.5x cap 10s, ±25%) to avoid
-          thundering-herd at scale.
+          the timeout, not surfaced as polling failures. A 429 waits out
+          Retry-After within the timeout; the timeout error says so.
+        - First poll is immediate; later polls grow 1.5x toward 5s.
         """
 
         deadline_ms = _now_ms() + timeout_ms
         attempt = 0
+        saw_rate_limit = False
+        retry_after_ms = 0
 
         while _now_ms() < deadline_ms:
-            await _sleep_ms(_polling_delay_ms(poll_interval_ms, attempt))
-            attempt += 1
+            if retry_after_ms > 0:
+                await _sleep_ms(retry_after_ms)
+            else:
+                await _sleep_ms(_polling_delay_ms(poll_interval_ms, attempt))
+                attempt += 1
+            retry_after_ms = 0
 
             try:
                 data = await self._signed_request(
@@ -444,6 +489,9 @@ class MemWal:
                 )
             except _HttpStatusError as err:
                 if _is_transient_polling_status(err.status):
+                    if err.status == 429:
+                        saw_rate_limit = True
+                        retry_after_ms = _clamped_retry_after_ms(err, deadline_ms)
                     continue
                 raise
 
@@ -466,7 +514,7 @@ class MemWal:
 
             # pending / running / uploaded — keep polling.
 
-        raise MemWalRememberJobTimeout(job_id=job_id, timeout_ms=timeout_ms)
+        raise _remember_job_timeout(job_id, timeout_ms, saw_rate_limit)
 
     async def remember_and_wait(
         self,
@@ -612,15 +660,24 @@ class MemWal:
         }
         pending: List[str] = list(job_ids)
         attempt = 0
+        saw_rate_limit = False
+        retry_after_ms = 0
 
         while pending and _now_ms() < deadline_ms:
-            await _sleep_ms(_polling_delay_ms(opts.poll_interval_ms, attempt))
-            attempt += 1
+            if retry_after_ms > 0:
+                await _sleep_ms(retry_after_ms)
+            else:
+                await _sleep_ms(_polling_delay_ms(opts.poll_interval_ms, attempt))
+                attempt += 1
+            retry_after_ms = 0
 
             try:
                 batch = await self.get_remember_bulk_status(pending)
             except _HttpStatusError as err:
                 if _is_transient_polling_status(err.status):
+                    if err.status == 429:
+                        saw_rate_limit = True
+                        retry_after_ms = _clamped_retry_after_ms(err, deadline_ms)
                     continue
                 raise
 
@@ -645,6 +702,13 @@ class MemWal:
             pending = [jid for jid in pending if jid not in terminal_ids]
 
         ordered = [results[job_id] for job_id in job_ids]
+        if saw_rate_limit:
+            for item in ordered:
+                if item.status == "timeout":
+                    item.error = (
+                        f"polling timed out after {opts.timeout_ms}ms; "
+                        "wait hit a rate limit (429)"
+                    )
         succeeded = sum(1 for r in ordered if r.status == "done")
         failed = sum(1 for r in ordered if r.status == "failed")
         timed_out = sum(1 for r in ordered if r.status == "timeout")
@@ -1549,6 +1613,15 @@ class MemWalRememberJobTimeout(MemWalError):
         self.timeout_ms = timeout_ms
 
 
+def _remember_job_timeout(
+    job_id: str, timeout_ms: int, saw_rate_limit: bool
+) -> MemWalRememberJobTimeout:
+    exc = MemWalRememberJobTimeout(job_id, timeout_ms)
+    if saw_rate_limit:
+        exc.args = (f"{exc.args[0]}; wait hit a rate limit (429)",)
+    return exc
+
+
 async def _discard_http_client(memwal: MemWal) -> None:
     """Close the cached httpx client, and drop it either way.
 

{memwal-0.1.11.dev1 → memwal-0.1.11.dev2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "memwal"
-version = "0.1.11.dev1"
+version = "0.1.11.dev2"
 description = "Python SDK for Walrus Memory — Privacy-first AI memory with Ed25519 signing"
 readme = "README.md"
 license = "MIT"

memwal-0.1.11.dev2/tests/test_polling_delay.py

@@ -0,0 +1,143 @@
+"""Parity with TS pollingDelayMs, plus 429 wait behavior."""
+
+from __future__ import annotations
+
+import random
+from types import SimpleNamespace
+
+import pytest
+
+from memwal.client import (
+    MemWal,
+    MemWalRememberJobTimeout,
+    _HttpStatusError,
+    _polling_delay_ms,
+)
+
+
+def test_attempt_0_is_immediate() -> None:
+    assert _polling_delay_ms(0, 0) == 0
+    assert _polling_delay_ms(5000, 0) == 0
+
+
+def test_grows_1_5x_from_100ms_floor_toward_5s(monkeypatch: pytest.MonkeyPatch) -> None:
+    # client.py does `import random`, so patching memwal.client.random.random hits stdlib.
+    real_random = random.random
+    monkeypatch.setattr("memwal.client.random", SimpleNamespace(random=lambda: 0.5))
+    assert random.random is real_random
+    assert _polling_delay_ms(0, 1) == 100
+    assert _polling_delay_ms(50, 1) == 100
+    assert _polling_delay_ms(400, 1) == 400
+    assert _polling_delay_ms(400, 2) == 600
+    assert _polling_delay_ms(1500, 4) == 5000
+    assert _polling_delay_ms(1500, 20) == 5000
+    assert _polling_delay_ms(8000, 1) == 8000
+    assert _polling_delay_ms(8000, 15) == 8000
+
+
+def _client() -> MemWal:
+    return MemWal.create(key="11" * 32, account_id="0x1", server_url="http://localhost:8000")
+
+
+def _patch_clock(monkeypatch: pytest.MonkeyPatch) -> tuple[dict[str, int], list[int]]:
+    clock = {"now": 0}
+    slept: list[int] = []
+
+    def now_ms() -> int:
+        return clock["now"]
+
+    async def sleep_ms(ms: int) -> None:
+        slept.append(ms)
+        clock["now"] += ms
+
+    monkeypatch.setattr("memwal.client._now_ms", now_ms)
+    monkeypatch.setattr("memwal.client._sleep_ms", sleep_ms)
+    return clock, slept
+
+
+def _rate_limit(seconds: str) -> _HttpStatusError:
+    return _HttpStatusError(
+        429,
+        f'{{"retry_after_seconds": {seconds}}}',
+        retry_after=seconds,
+    )
+
+
+@pytest.mark.asyncio
+async def test_429_longer_than_budget_is_clamped_and_named(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    clock, slept = _patch_clock(monkeypatch)
+    client = _client()
+    calls = {"n": 0}
+
+    async def status(*_args: object, **_kwargs: object) -> dict:
+        calls["n"] += 1
+        raise _rate_limit("600")
+
+    monkeypatch.setattr(client, "_signed_request", status)
+
+    with pytest.raises(MemWalRememberJobTimeout, match="429"):
+        await client.wait_for_remember_job("job-1", poll_interval_ms=1500, timeout_ms=800)
+
+    assert clock["now"] <= 800
+    assert slept == [0, 800]
+    assert calls["n"] == 2
+
+
+@pytest.mark.asyncio
+async def test_429_that_fits_delays_the_next_read(monkeypatch: pytest.MonkeyPatch) -> None:
+    _patch_clock(monkeypatch)
+    client = _client()
+    calls = {"n": 0}
+
+    async def status(*_args: object, **_kwargs: object) -> dict:
+        calls["n"] += 1
+        if calls["n"] == 1:
+            raise _rate_limit("0.05")
+        return {
+            "job_id": "job-1",
+            "status": "done",
+            "blob_id": "blob-1",
+            "owner": "0x1",
+            "namespace": "default",
+        }
+
+    monkeypatch.setattr(client, "_signed_request", status)
+    done = await client.wait_for_remember_job("job-1", poll_interval_ms=1500, timeout_ms=5_000)
+
+    assert done.blob_id == "blob-1"
+    assert calls["n"] == 2
+
+
+@pytest.mark.asyncio
+async def test_bulk_timeout_names_429_and_keeps_unreturned_jobs_pending(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    _patch_clock(monkeypatch)
+    client = _client()
+    seen: list[list[str]] = []
+
+    async def status(job_ids: list[str]) -> SimpleNamespace:
+        seen.append(list(job_ids))
+        if len(seen) == 1:
+            return SimpleNamespace(
+                results=[
+                    SimpleNamespace(job_id="job-1", status="done", blob_id="b1", error=None)
+                ]
+            )
+        raise _rate_limit("600")
+
+    monkeypatch.setattr(client, "get_remember_bulk_status", status)
+    settled = await client.wait_for_remember_jobs(
+        ["job-1", "job-2"],
+        SimpleNamespace(poll_interval_ms=1500, timeout_ms=800),
+    )
+
+    assert seen[0] == ["job-1", "job-2"]
+    assert seen[1] == ["job-2"]
+    assert settled.results[0].status == "done"
+    assert settled.results[1].status == "timeout"
+    assert settled.results[1].error == (
+        "polling timed out after 800ms; wait hit a rate limit (429)"
+    )