memwal 0.1.8.dev2__tar.gz → 0.1.9__tar.gz

{memwal-0.1.8.dev2 → memwal-0.1.9}/CHANGELOG.md

@@ -1,5 +1,14 @@
 # memwal
 
+## 0.1.9
+
+### Fixed
+
+- HTTP 503 with `x-auth-error: AUTH_UPSTREAM_UNAVAILABLE` is reported as a retryable credential-verification outage, not a sign-in failure. Other 503s keep the generic sanitized body.
+- `remember_bulk_async` rejects an empty `items` list before the request and raises when the relayer returns a `job_ids` length that does not match the batch.
+- restore `truncated` docs now match WALM-431 retryable semantics.
+- Warn when `server_url` uses plaintext `http://` against a non-localhost host, matching the TypeScript SDK `normalizeServerUrl` guard. Localhost, `127.0.0.1`, `::1`, and `*.localhost` are exempt; invalid URLs are left for the HTTP client to surface. The warning logs only scheme, host, and port so URL userinfo is not written to logs.
+
 ## 0.1.8
 
 ### Added

{memwal-0.1.8.dev2 → memwal-0.1.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: memwal
-Version: 0.1.8.dev2
+Version: 0.1.9
 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.8.dev2 → memwal-0.1.9}/memwal/__init__.py

@@ -122,4 +122,4 @@ __all__ = [
     "RecallManualResult",
 ]
 
-__version__ = "0.1.8.dev2"
+__version__ = "0.1.9"

{memwal-0.1.8.dev2 → memwal-0.1.9}/memwal/client.py

@@ -35,6 +35,7 @@ import time
 import uuid
 from datetime import datetime, timezone
 from typing import Any, Dict, List, Optional, Sequence, Tuple, TypeVar, Union
+from urllib.parse import ParseResult, urlparse
 
 import httpx
 import nacl.signing
@@ -97,11 +98,62 @@ AUTH_REJECTED_MESSAGE = (
     "and dashboard credentials. Full troubleshooting: "
     "https://docs.wal.app/walrus-memory/troubleshooting/overview#401-auth_rejected-errors"
 )
+AUTH_UPSTREAM_UNAVAILABLE = "AUTH_UPSTREAM_UNAVAILABLE"
+UPSTREAM_UNAVAILABLE_MESSAGE = (
+    "Walrus Memory temporarily cannot verify credentials (upstream unavailable). "
+    "Retry; this is not a sign-in failure."
+)
 
 
 logger = logging.getLogger("memwal")
 
 
+def _server_url_for_log(parsed: ParseResult) -> str:
+    """Scheme/host/port only — never userinfo, path, query, or fragment."""
+
+    host = parsed.hostname or ""
+    if ":" in host:
+        host = f"[{host}]"
+    if parsed.port is not None:
+        return f"{parsed.scheme}://{host}:{parsed.port}"
+    return f"{parsed.scheme}://{host}"
+
+
+def normalize_server_url(url: str) -> str:
+    """Strip a trailing slash and warn on plaintext HTTP to a remote host.
+
+    Ports the TypeScript ``normalizeServerUrl`` helper: localhost,
+    ``127.0.0.1``, ``::1``, and ``*.localhost`` are exempt. Invalid URLs
+    are returned trimmed so the HTTP client can surface the error later.
+
+    The warning logs only scheme/host/port so URL userinfo (HTTPX
+    credentials) and other sensitive components are not written to logs.
+    The returned URL is otherwise unchanged and still used for transport.
+    """
+
+    trimmed = url.rstrip("/")
+    try:
+        parsed = urlparse(trimmed)
+        host = (parsed.hostname or "").lower()
+        is_local = (
+            host == "localhost"
+            or host == "127.0.0.1"
+            or host == "::1"
+            or host.endswith(".localhost")
+        )
+        if parsed.scheme == "http" and host and not is_local:
+            logger.warning(
+                '[memwal] serverUrl "%s" uses plaintext HTTP on a non-localhost host. '
+                "Signed requests and any bearer material will be visible to the network. "
+                "Use https:// in production.",
+                _server_url_for_log(parsed),
+            )
+    except ValueError:
+        # invalid URL — let the HTTP call surface the error at request time
+        pass
+    return trimmed
+
+
 # ============================================================
 # Polling helpers (PR #121 parity with TS SDK)
 # ============================================================
@@ -229,7 +281,7 @@ class MemWal:
         self._private_key_hex = normalize_private_key(config.key)
         self._signing_key = build_signing_key(self._private_key_hex)
         self._account_id = config.account_id
-        self._server_url = config.server_url.rstrip("/")
+        self._server_url = normalize_server_url(config.server_url)
         self._namespace = config.namespace
         self._client: Optional[httpx.AsyncClient] = None
         self._server_config: Optional[Dict[str, str]] = None
@@ -463,6 +515,9 @@ class MemWal:
         capped at ``MAX_REMEMBER_TEXT_BYTES`` (= 64 KiB).
         """
 
+        if not items:
+            raise ValueError("remember_bulk_async: items must be a non-empty array")
+
         payload_items: List[Dict[str, Any]] = [
             {
                 "text": item.text,
@@ -476,8 +531,15 @@ class MemWal:
             {"items": payload_items},
             accepted_statuses=(200, 202),
         )
+        job_ids = data.get("job_ids")
+        returned = len(job_ids) if job_ids else 0
+        if not job_ids or returned != len(payload_items):
+            raise ValueError(
+                f"remember_bulk_async: server returned {returned} job_ids for "
+                f"{len(payload_items)} items"
+            )
         return RememberBulkAcceptedResult(
-            job_ids=list(data.get("job_ids", [])),
+            job_ids=list(job_ids),
             total=int(data.get("total", len(payload_items))),
             status=data.get("status", "pending"),
         )
@@ -1275,6 +1337,8 @@ class MemWal:
             raise _HttpStatusError(
                 status=response.status_code,
                 body=err_text,
+                auth_error=response.headers.get("x-auth-error"),
+                retry_after=response.headers.get("retry-after"),
             )
 
         return response.json()
@@ -1318,15 +1382,25 @@ class _HttpStatusError(MemWalError):
     explicitly accepted).
     """
 
-    def __init__(self, status: int, body: str) -> None:
+    def __init__(
+        self,
+        status: int,
+        body: str,
+        auth_error: str | None = None,
+        retry_after: str | None = None,
+    ) -> None:
         if status == 401:
             super().__init__(AUTH_REJECTED_MESSAGE)
+        elif status == 503 and auth_error == AUTH_UPSTREAM_UNAVAILABLE:
+            super().__init__(UPSTREAM_UNAVAILABLE_MESSAGE)
         else:
             super().__init__(
                 f"Walrus Memory API error ({status}): {_redact_internal_urls(body)}"
             )
         self.status = status
         self.body = body
+        self.auth_error = auth_error
+        self.retry_after = retry_after
 
 
 class MemWalRememberJobNotFound(MemWalError):

{memwal-0.1.8.dev2 → memwal-0.1.9}/memwal/types.py

@@ -206,13 +206,17 @@ class RestoreResult:
     total: int
     namespace: str
     owner: str
-    #: True when this restore is known-incomplete: either more on-chain
-    #: blobs were missing locally than ``limit`` allowed this call to
-    #: restore, or the sidecar's raw on-chain candidate fetch hit its own
-    #: cap before this namespace's blobs were even filtered out of that
-    #: set (WALM-319) -- this can be ``True`` even when ``total == 0``,
-    #: since a cap hit elsewhere can starve this namespace's fetch
-    #: entirely. Raising ``limit`` only helps with the first case.
+    #: True when this restore is known-incomplete: more on-chain blobs were
+    #: missing locally than ``limit`` allowed this call to restore, or the
+    #: sidecar's owner-wide candidate fetch hit its cap *and* raising
+    #: ``limit`` can still expand that fetch (``limit < 20``). Once the cap
+    #: is saturated, truncation follows this call's missing-blob page, not
+    #: on-chain ``total``, so a fully restored namespace does not loop
+    #: (WALM-431 / GH #762).
+    #:
+    #: ``truncated=False`` is not proof the sidecar saw every on-chain blob.
+    #: Blobs beyond the owner-wide sidecar candidate cap can still be
+    #: missing. Follow-up field: WALM-451 (``sourceCapped``).
     #:
     #: Relayers older than WALM-319 don't send this field at all; the SDK
     #: defaults it to ``False`` in that case rather than requiring it.

{memwal-0.1.8.dev2 → memwal-0.1.9}/pyproject.toml

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

memwal-0.1.9/tests/test_auth_rejected_message.py

@@ -0,0 +1,30 @@
+"""Tests for the AUTH_REJECTED_MESSAGE shown on a 401 from the relayer."""
+
+from __future__ import annotations
+
+from memwal.client import (
+    AUTH_REJECTED_MESSAGE,
+    AUTH_UPSTREAM_UNAVAILABLE,
+    UPSTREAM_UNAVAILABLE_MESSAGE,
+    _HttpStatusError,
+)
+
+
+def test_auth_rejected_message_points_to_troubleshooting_guide() -> None:
+    assert "docs.wal.app/walrus-memory/troubleshooting/overview" in AUTH_REJECTED_MESSAGE
+
+
+def test_auth_503_is_retryable_not_a_credential_failure() -> None:
+    err = _HttpStatusError(
+        503, "upstream unavailable", auth_error=AUTH_UPSTREAM_UNAVAILABLE, retry_after="5"
+    )
+    assert str(err) == UPSTREAM_UNAVAILABLE_MESSAGE
+    assert "sign-in" in str(err)
+    assert "401" not in str(err)
+    assert err.retry_after == "5"
+
+
+def test_non_auth_503_keeps_generic_body() -> None:
+    err = _HttpStatusError(503, "Rate limiter temporarily unavailable")
+    assert "Rate limiter temporarily unavailable" in str(err)
+    assert "cannot verify credentials" not in str(err)

{memwal-0.1.8.dev2 → memwal-0.1.9}/tests/test_client.py

@@ -27,6 +27,8 @@ from memwal.client import (
 from memwal.types import (
     RecallManualOptions,
     RecallParams,
+    RememberBulkAcceptedResult,
+    RememberBulkItem,
     RememberManualOptions,
     ScoringWeights,
 )
@@ -343,6 +345,90 @@ class TestRemember:
         assert result.status == "pending"
 
 
+# ============================================================
+# remember_bulk_async() tests
+# ============================================================
+
+
+class TestRememberBulkAsync:
+    @respx.mock
+    async def test_empty_items_raises_without_http(self, memwal_client: MemWal) -> None:
+        mock_seal_session_prereqs()
+        route = respx.post(f"{_TEST_SERVER}/api/remember/bulk").mock(
+            return_value=httpx.Response(
+                202,
+                json={"job_ids": [], "total": 0, "status": "pending"},
+            )
+        )
+
+        with pytest.raises(
+            ValueError,
+            match="remember_bulk_async: items must be a non-empty array",
+        ):
+            await memwal_client.remember_bulk_async([])
+
+        assert not route.called
+
+    @respx.mock
+    async def test_mismatched_job_ids_raises(self, memwal_client: MemWal) -> None:
+        mock_seal_session_prereqs()
+        respx.post(f"{_TEST_SERVER}/api/remember/bulk").mock(
+            return_value=httpx.Response(
+                202,
+                json={
+                    "job_ids": ["job-1"],
+                    "total": 1,
+                    "status": "pending",
+                },
+            )
+        )
+
+        with pytest.raises(
+            ValueError,
+            match="remember_bulk_async: server returned 1 job_ids for 2 items",
+        ):
+            await memwal_client.remember_bulk_async(
+                [
+                    RememberBulkItem(text="I love coffee"),
+                    RememberBulkItem(text="I live in Tokyo"),
+                ]
+            )
+
+    @respx.mock
+    async def test_matching_job_ids_returns_accepted(
+        self, memwal_client: MemWal
+    ) -> None:
+        mock_seal_session_prereqs()
+        route = respx.post(f"{_TEST_SERVER}/api/remember/bulk").mock(
+            return_value=httpx.Response(
+                202,
+                json={
+                    "job_ids": ["job-1", "job-2"],
+                    "total": 2,
+                    "status": "pending",
+                },
+            )
+        )
+
+        result = await memwal_client.remember_bulk_async(
+            [
+                RememberBulkItem(text="I love coffee"),
+                RememberBulkItem(text="I live in Tokyo", namespace="profile"),
+            ]
+        )
+
+        assert route.called
+        body = json.loads(route.calls[0].request.content)
+        assert body["items"] == [
+            {"text": "I love coffee", "namespace": "default"},
+            {"text": "I live in Tokyo", "namespace": "profile"},
+        ]
+        assert isinstance(result, RememberBulkAcceptedResult)
+        assert result.job_ids == ["job-1", "job-2"]
+        assert result.total == 2
+        assert result.status == "pending"
+
+
 # ============================================================
 # recall() tests
 # ============================================================

memwal-0.1.9/tests/test_normalize_server_url.py

@@ -0,0 +1,96 @@
+"""Tests for plaintext HTTP server_url guarding (WALM-452 / #748).
+
+No network: ``MemWal.create`` only stores config, and
+``normalize_server_url`` is a pure parse + log helper.
+"""
+
+from __future__ import annotations
+
+import logging
+
+import pytest
+
+from memwal.client import MemWal, normalize_server_url
+
+_KEY = "ab" * 32
+_ACCOUNT = "0xdummy"
+
+
+def test_plaintext_remote_warns_and_strips(caplog: pytest.LogCaptureFixture) -> None:
+    caplog.set_level(logging.WARNING, logger="memwal")
+    assert (
+        normalize_server_url("http://relayer.example.com/")
+        == "http://relayer.example.com"
+    )
+    assert "plaintext" in caplog.text
+
+
+def test_https_remote_does_not_warn(caplog: pytest.LogCaptureFixture) -> None:
+    caplog.set_level(logging.WARNING, logger="memwal")
+    assert (
+        normalize_server_url("https://relayer.memory.walrus.xyz")
+        == "https://relayer.memory.walrus.xyz"
+    )
+    assert caplog.text == ""
+
+
+@pytest.mark.parametrize(
+    "url",
+    [
+        "http://localhost:8000",
+        "http://127.0.0.1:8000",
+        "http://foo.localhost",
+        "http://[::1]:8000",
+    ],
+)
+def test_plaintext_local_does_not_warn(
+    url: str, caplog: pytest.LogCaptureFixture
+) -> None:
+    caplog.set_level(logging.WARNING, logger="memwal")
+    assert normalize_server_url(url) == url
+    assert caplog.text == ""
+
+
+def test_create_warns_on_plaintext_remote(caplog: pytest.LogCaptureFixture) -> None:
+    caplog.set_level(logging.WARNING, logger="memwal")
+    client = MemWal.create(
+        key=_KEY,
+        account_id=_ACCOUNT,
+        server_url="http://relayer.example.com/",
+    )
+    assert client._server_url == "http://relayer.example.com"
+    assert "plaintext" in caplog.text
+
+
+def test_plaintext_remote_warning_omits_url_credentials(
+    caplog: pytest.LogCaptureFixture,
+) -> None:
+    """HTTPX userinfo must stay on the transport URL and out of the warning."""
+
+    caplog.set_level(logging.WARNING, logger="memwal")
+    url = "http://alice:example-secret@relayer.example.com/?token=super-secret"
+    assert (
+        normalize_server_url(url)
+        == "http://alice:example-secret@relayer.example.com/?token=super-secret"
+    )
+    assert "plaintext" in caplog.text
+    assert "http://relayer.example.com" in caplog.text
+    assert "alice" not in caplog.text
+    assert "example-secret" not in caplog.text
+    assert "super-secret" not in caplog.text
+    for rec in caplog.records:
+        assert "example-secret" not in rec.getMessage()
+        assert "example-secret" not in str(rec.args)
+        assert "super-secret" not in rec.getMessage()
+        assert "super-secret" not in str(rec.args)
+
+
+def test_create_preserves_url_credentials_and_redacts_warning(
+    caplog: pytest.LogCaptureFixture,
+) -> None:
+    caplog.set_level(logging.WARNING, logger="memwal")
+    url = "http://alice:example-secret@relayer.example.com/"
+    client = MemWal.create(key=_KEY, account_id=_ACCOUNT, server_url=url)
+    assert client._server_url == "http://alice:example-secret@relayer.example.com"
+    assert "plaintext" in caplog.text
+    assert "example-secret" not in caplog.text

memwal-0.1.8.dev2/tests/test_auth_rejected_message.py

@@ -1,9 +0,0 @@
-"""Tests for the AUTH_REJECTED_MESSAGE shown on a 401 from the relayer."""
-
-from __future__ import annotations
-
-from memwal.client import AUTH_REJECTED_MESSAGE
-
-
-def test_auth_rejected_message_points_to_troubleshooting_guide() -> None:
-    assert "docs.wal.app/walrus-memory/troubleshooting/overview" in AUTH_REJECTED_MESSAGE