memwal 0.1.11.dev9__tar.gz → 0.1.11.dev10__tar.gz

{memwal-0.1.11.dev9 → memwal-0.1.11.dev10}/CHANGELOG.md

@@ -2,8 +2,13 @@
 
 ## Unreleased
 
+### Added
+
+- `get_remember_status(job_id)` on `MemWal` and `MemWalSync` returns `RememberJobStatus` from `GET /api/remember/{job_id}`, accepting 200 and 404 like the TypeScript SDK. (WALM-832, #1096)
+
 ### Fixed
 
+- `get_remember_status` and `wait_for_remember_job` reject a job id outside `[A-Za-z0-9_-]+` before the request. `.`, `..`, a backslash, and encoded dot-dot used to pass a denylist and be rewritten after signing. An empty id used to call `GET /api/remember/` and raise `json.JSONDecodeError`. An unparseable 404 is `not_found` / `MemWalRememberJobNotFound`, not a JSON error. `uuid.UUID` is coerced with `str()`. Valid UUID job ids are unchanged. (WALM-833, #1100, #1216)
 - `remember`, `remember_bulk`, `analyze`, and `embed` reject whitespace-only text before the request. A blank body used to be accepted and then sit until the caller timed out. (#1129)
 - A 401 `AUTH_REJECTED` now says a wallet address is not a MemWal account ID. (#1132)
 - `wait_for_remember_jobs` / `remember_bulk_and_wait` no longer return a batch they could not read as if it were still uploading. When every status poll is rate-limited, the wait makes one confirming read and raises `MemWalRateLimited` (`status` 429, `job_ids`, `retry_after`) if that is refused too. An item still unsettled at the deadline names its last known status, or says no read got through. (WALM-671, #967)

{memwal-0.1.11.dev9 → memwal-0.1.11.dev10}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: memwal
-Version: 0.1.11.dev9
+Version: 0.1.11.dev10
 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
@@ -240,6 +240,7 @@ Create a new async client.
 | Method | Description |
 |--------|-------------|
 | `await remember(text, namespace?)` | Accept a background remember job and return `job_id` |
+| `await get_remember_status(job_id)` | Read one remember job without waiting |
 | `await wait_for_remember_job(job_id, ...)` | Poll one remember job until it is searchable |
 | `await remember_and_wait(text, namespace?, ...)` | Store a memory and wait until it is searchable |
 | `await remember_bulk(items)` | Accept several background remember jobs |

{memwal-0.1.11.dev9 → memwal-0.1.11.dev10}/README.md

@@ -201,6 +201,7 @@ Create a new async client.
 | Method | Description |
 |--------|-------------|
 | `await remember(text, namespace?)` | Accept a background remember job and return `job_id` |
+| `await get_remember_status(job_id)` | Read one remember job without waiting |
 | `await wait_for_remember_job(job_id, ...)` | Poll one remember job until it is searchable |
 | `await remember_and_wait(text, namespace?, ...)` | Store a memory and wait until it is searchable |
 | `await remember_bulk(items)` | Accept several background remember jobs |

{memwal-0.1.11.dev9 → memwal-0.1.11.dev10}/memwal/__init__.py

@@ -128,4 +128,4 @@ __all__ = [
     "RecallManualResult",
 ]
 
-__version__ = "0.1.11.dev9"
+__version__ = "0.1.11.dev10"

{memwal-0.1.11.dev9 → memwal-0.1.11.dev10}/memwal/client.py

@@ -69,6 +69,7 @@ from .types import (
     RememberBulkResult,
     RememberBulkStatusItem,
     RememberBulkStatusResult,
+    RememberJobStatus,
     RememberManualOptions,
     RememberManualResult,
     RememberResult,
@@ -156,6 +157,36 @@ def _derived_idempotency_key(request_identity: str) -> str:
     return f"r1-{hashlib.sha256(payload).hexdigest()}"
 
 
+def _require_remember_job_id(job_id: object) -> str:
+    """String form of a remember job id.
+
+    ``uuid.UUID`` used to interpolate into the path and still does. Any other
+    non-string is a type mistake: ``not_found`` would hide a job that exists.
+    """
+
+    if isinstance(job_id, uuid.UUID):
+        return str(job_id)
+    if not isinstance(job_id, str):
+        raise TypeError(
+            f"remember job id must be a string, got {type(job_id).__name__}"
+        )
+    return job_id
+
+
+def _remember_status_path(job_id: str) -> Optional[str]:
+    """``/api/remember/{job_id}`` when the id is one safe segment, else None.
+
+    httpx rewrites the path after it is signed. ``.`` requests
+    ``/api/remember``, ``..`` requests ``/api``, and a NUL raises
+    ``InvalidURL``. An allowlist keeps those from leaving the client. A
+    normal UUID is unchanged. (#1100, #1216)
+    """
+
+    if re.fullmatch(r"[A-Za-z0-9_-]+", job_id) is None:
+        return None
+    return f"/api/remember/{job_id}"
+
+
 def normalize_server_url(url: str) -> str:
     """Strip a trailing slash and warn on plaintext HTTP to a remote host.
 
@@ -524,6 +555,55 @@ class MemWal:
         remaining_s = (deadline_ms - _now_ms()) / 1000.0
         return max(0.001, min(60.0, remaining_s))
 
+    async def get_remember_status(self, job_id: str) -> RememberJobStatus:
+        """One-shot lookup of a remember job. Mirrors TS ``getRememberStatus``.
+
+        ``GET /api/remember/{job_id}``, accepting 200 and 404. A 404, or a
+        body with no ``status``, is ``not_found`` — not an exception. A job
+        id outside ``[A-Za-z0-9_-]+`` is ``not_found`` without a request.
+        """
+
+        job_id = _require_remember_job_id(job_id)
+        path = _remember_status_path(job_id)
+        if path is None:
+            return RememberJobStatus(
+                job_id=job_id,
+                status="not_found",
+                error=f"Job {job_id} not found",
+            )
+        try:
+            data = await self._signed_request(
+                "GET",
+                path,
+                {},
+                accepted_statuses=(200, 404),
+                # Status is metadata. No SEAL decrypt, so no session. Matches TS.
+                include_seal_session=False,
+            )
+        except (json.JSONDecodeError, UnicodeDecodeError):
+            data = None
+        if not isinstance(data, dict):
+            return RememberJobStatus(
+                job_id=job_id,
+                status="not_found",
+                error=f"remember job not found: {job_id}",
+            )
+        status = data.get("status")
+        if not status:
+            return RememberJobStatus(
+                job_id=data.get("job_id") or job_id,
+                status="not_found",
+                error=data.get("error") or f"remember job not found: {job_id}",
+            )
+        return RememberJobStatus(
+            job_id=data.get("job_id", job_id),
+            status=status,
+            owner=data.get("owner"),
+            namespace=data.get("namespace"),
+            blob_id=data.get("blob_id"),
+            error=data.get("error"),
+        )
+
     async def wait_for_remember_job(
         self,
         job_id: str,
@@ -542,6 +622,11 @@ class MemWal:
         - First poll is immediate; later polls grow 1.5x toward 5s.
         """
 
+        job_id = _require_remember_job_id(job_id)
+        path = _remember_status_path(job_id)
+        if path is None:
+            raise MemWalRememberJobNotFound(job_id)
+
         deadline_ms = _now_ms() + timeout_ms
         attempt = 0
         saw_rate_limit = False
@@ -563,7 +648,7 @@ class MemWal:
                 try:
                     data = await self._signed_request(
                         "GET",
-                        f"/api/remember/{job_id}",
+                        path,
                         {},
                         accepted_statuses=(200, 404),
                         timeout=poll_timeout,
@@ -572,12 +657,14 @@ class MemWal:
                     if "unexpected keyword argument" in str(err) and "timeout" in str(err):
                         data = await self._signed_request(
                             "GET",
-                            f"/api/remember/{job_id}",
+                            path,
                             {},
                             accepted_statuses=(200, 404),
                         )
                     else:
                         raise
+            except (json.JSONDecodeError, UnicodeDecodeError):
+                raise MemWalRememberJobNotFound(job_id) from None
             except _HttpStatusError as err:
                 if _is_transient_polling_status(err.status):
                     last_refusal = err.status
@@ -592,6 +679,8 @@ class MemWal:
                 last_refusal = 0
                 continue
 
+            if not isinstance(data, dict):
+                raise MemWalRememberJobNotFound(job_id)
             status_str = data.get("status")
             if status_str is None or status_str == "not_found":
                 raise MemWalRememberJobNotFound(job_id)
@@ -1964,6 +2053,10 @@ class MemWalSync:
     ) -> RememberAcceptedResult:
         return self._run(self._inner.remember_async(text, namespace, idempotency_key))
 
+    def get_remember_status(self, job_id: str) -> RememberJobStatus:
+        """Synchronous version of :meth:`MemWal.get_remember_status`."""
+        return self._run(self._inner.get_remember_status(job_id))
+
     def wait_for_remember_job(
         self,
         job_id: str,

{memwal-0.1.11.dev9 → memwal-0.1.11.dev10}/pyproject.toml

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

{memwal-0.1.11.dev9 → memwal-0.1.11.dev10}/tests/test_client.py

@@ -10,6 +10,7 @@ from __future__ import annotations
 import base64
 import json
 import time
+import uuid
 from datetime import datetime, timedelta, timezone
 from typing import Any, Sequence
 
@@ -24,6 +25,7 @@ from memwal.client import (
     MemWalCompatibilityError,
     MemWalError,
     MemWalRateLimited,
+    MemWalRememberJobNotFound,
     MemWalRememberJobTimeout,
     MemWalSync,
     _HttpStatusError,
@@ -36,6 +38,7 @@ from memwal.types import (
     RememberBulkOptions,
     RememberBulkStatusItem,
     RememberBulkStatusResult,
+    RememberJobStatus,
     RememberManualOptions,
     ScoringWeights,
 )
@@ -642,6 +645,151 @@ class TestRememberJobTimeoutDetail:
         )
 
 
+# ============================================================
+# one-job remember status
+# ============================================================
+
+
+_NORMAL_JOB_ID = "550e8400-e29b-41d4-a716-446655440000"
+
+
+class TestRememberJobStatus:
+    @respx.mock
+    async def test_unsafe_job_id_is_not_requested(self, memwal_client: MemWal) -> None:
+        route = respx.route().mock(return_value=httpx.Response(500, text="nope"))
+        for job_id in ("", "abc/def?x=1", "job 1", "a\tb", "?", "/", ".", "..", "%2e%2e", "a\\b"):
+            status = await memwal_client.get_remember_status(job_id)
+            assert status == RememberJobStatus(
+                job_id=job_id,
+                status="not_found",
+                error=f"Job {job_id} not found",
+            )
+            with pytest.raises(MemWalRememberJobNotFound) as exc:
+                await memwal_client.wait_for_remember_job(
+                    job_id, poll_interval_ms=0, timeout_ms=5_000
+                )
+            assert exc.value.status == 404
+            assert exc.value.job_id == job_id
+            assert not isinstance(exc.value, json.JSONDecodeError)
+        assert route.call_count == 0
+
+    async def test_non_string_job_id_is_a_type_error(self, memwal_client: MemWal) -> None:
+        with pytest.raises(TypeError):
+            await memwal_client.get_remember_status(1)  # type: ignore[arg-type]
+        with pytest.raises(TypeError):
+            await memwal_client.wait_for_remember_job(1, poll_interval_ms=0, timeout_ms=5_000)  # type: ignore[arg-type]
+
+    @respx.mock
+    async def test_uuid_object_reads_the_string_path(self, memwal_client: MemWal) -> None:
+        _mock_version()
+        job = uuid.UUID(_NORMAL_JOB_ID)
+        route = respx.get(f"{_TEST_SERVER}/api/remember/{job}").mock(
+            return_value=httpx.Response(200, json={"job_id": str(job), "status": "running"})
+        )
+        status = await memwal_client.get_remember_status(job)  # type: ignore[arg-type]
+        assert status.status == "running"
+        assert status.job_id == str(job)
+        assert route.call_count == 1
+
+    @respx.mock
+    async def test_non_object_404_body_is_not_found(self, memwal_client: MemWal) -> None:
+        mock_seal_session_prereqs()
+        route = respx.get(f"{_TEST_SERVER}/api/remember/job-1")
+        for body in (b"null", b"[]", b'"Not Found"', b"<html>nope</html>"):
+            route.mock(return_value=httpx.Response(404, content=body))
+            status = await memwal_client.get_remember_status("job-1")
+            assert status.status == "not_found"
+            assert status.job_id == "job-1"
+            with pytest.raises(MemWalRememberJobNotFound) as exc:
+                await memwal_client.wait_for_remember_job(
+                    "job-1", poll_interval_ms=0, timeout_ms=5_000
+                )
+            assert exc.value.status == 404
+
+    @respx.mock
+    async def test_empty_404_body_is_not_found(self, memwal_client: MemWal) -> None:
+        mock_seal_session_prereqs()
+        respx.get(f"{_TEST_SERVER}/api/remember/job-1").mock(
+            return_value=httpx.Response(404, content=b"")
+        )
+        status = await memwal_client.get_remember_status("job-1")
+        assert status.status == "not_found"
+        assert status.job_id == "job-1"
+        with pytest.raises(MemWalRememberJobNotFound) as exc:
+            await memwal_client.wait_for_remember_job(
+                "job-1", poll_interval_ms=0, timeout_ms=5_000
+            )
+        assert exc.value.status == 404
+
+    @respx.mock
+    async def test_reads_a_normal_job_id(self, memwal_client: MemWal) -> None:
+        mock_seal_session_prereqs()
+        route = respx.get(f"{_TEST_SERVER}/api/remember/{_NORMAL_JOB_ID}").mock(
+            return_value=httpx.Response(
+                200,
+                json={
+                    "job_id": _NORMAL_JOB_ID,
+                    "status": "done",
+                    "blob_id": "blob-1",
+                    "owner": "0xowner",
+                    "namespace": "profile",
+                },
+            )
+        )
+
+        status = await memwal_client.get_remember_status(_NORMAL_JOB_ID)
+        assert status == RememberJobStatus(
+            job_id=_NORMAL_JOB_ID,
+            status="done",
+            owner="0xowner",
+            namespace="profile",
+            blob_id="blob-1",
+        )
+        assert "x-seal-session" not in route.calls[0].request.headers
+
+        result = await memwal_client.wait_for_remember_job(
+            _NORMAL_JOB_ID, poll_interval_ms=0, timeout_ms=5_000
+        )
+        assert result.blob_id == "blob-1"
+        assert result.namespace == "profile"
+        assert [str(call.request.url) for call in route.calls] == [
+            f"{_TEST_SERVER}/api/remember/{_NORMAL_JOB_ID}",
+            f"{_TEST_SERVER}/api/remember/{_NORMAL_JOB_ID}",
+        ]
+
+    @respx.mock
+    def test_sync_reads_a_normal_job_id(self) -> None:
+        _mock_version()
+        route = respx.get(f"{_TEST_SERVER}/api/remember/{_NORMAL_JOB_ID}").mock(
+            return_value=httpx.Response(
+                200,
+                json={
+                    "job_id": _NORMAL_JOB_ID,
+                    "status": "running",
+                    "namespace": "profile",
+                },
+            )
+        )
+        client = MemWalSync.create(
+            key=_TEST_KEY_HEX,
+            account_id=_TEST_ACCOUNT_ID,
+            server_url=_TEST_SERVER,
+        )
+        try:
+            missing = client.get_remember_status("")
+            assert missing.status == "not_found"
+            with pytest.raises(MemWalRememberJobNotFound):
+                client.wait_for_remember_job("abc/def?x=1", poll_interval_ms=0, timeout_ms=5_000)
+            status = client.get_remember_status(_NORMAL_JOB_ID)
+            assert status.status == "running"
+            assert status.namespace == "profile"
+            assert str(route.calls[0].request.url) == (
+                f"{_TEST_SERVER}/api/remember/{_NORMAL_JOB_ID}"
+            )
+        finally:
+            client.close()
+
+
 # ============================================================
 # recall() tests
 # ============================================================