spooling 0.2.9__tar.gz → 0.2.10__tar.gz

{spooling-0.2.9/spooling.egg-info → spooling-0.2.10}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: spooling
-Version: 0.2.9
+Version: 0.2.10
 Summary: Local session tracker and semantic search for AI coding assistants
 Author: Parsed Analytics, Inc.
 License: MIT

{spooling-0.2.9 → spooling-0.2.10}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "spooling"
-version = "0.2.9"
+version = "0.2.10"
 description = "Local session tracker and semantic search for AI coding assistants"
 readme = "README.md"
 authors = [{ name = "Parsed Analytics, Inc." }]

{spooling-0.2.9 → spooling-0.2.10}/spooling/cloud.py

@@ -4,13 +4,17 @@ import json
 import os
 import re
 import signal
+import socket
+import ssl
 import time
 from datetime import datetime, timedelta, timezone
 from pathlib import Path
+from urllib.parse import urlparse
 
 import click
 import httpx
 from rich.console import Console
+from rich.markup import escape
 
 from spooling.db import get_connection
 from spooling.redact import redact_messages, redact_traces
@@ -70,6 +74,143 @@ def _api_base() -> str:
     return cfg.get("api_url") or os.environ.get("SPOOLING_CLOUD_URL") or DEFAULT_API
 
 
+# --- Friendly network errors -------------------------------------------------
+#
+# Raw exceptions like "[Errno 8] nodename nor servname provided, or not known"
+# tell a user nothing. Everything that talks to the cloud funnels its errors
+# through _explain_error / _explain_http so they get a plain-English cause and
+# the next step.
+
+_SELF_HOST_HINT = (
+    "Using a self-hosted or staging server? Point the CLI at it with\n"
+    "    spooling cloud login --key sk_... --api-url https://your-host\n"
+    "  or set SPOOLING_CLOUD_URL."
+)
+
+
+def _host_port(base: str) -> tuple[str, int]:
+    try:
+        u = urlparse(base)
+        host = u.hostname or base
+        port = u.port or (80 if u.scheme == "http" else 443)
+    except ValueError:  # e.g. port out of range in a hand-typed URL
+        return base, 443
+    return host, port
+
+
+def _exc_chain(e: BaseException):
+    seen = set()
+    while e is not None and id(e) not in seen:
+        seen.add(id(e))
+        yield e
+        e = e.__cause__ or e.__context__
+
+
+_DNS_MARKERS = (
+    "nodename nor servname",          # macOS
+    "name or service not known",      # Linux (glibc)
+    "temporary failure in name resolution",
+    "no address associated with hostname",
+    "getaddrinfo failed",             # Windows
+    "no such host",
+)
+
+
+def _is_dns_error(e: BaseException) -> bool:
+    for x in _exc_chain(e):
+        if isinstance(x, socket.gaierror):
+            return True
+        if any(m in str(x).lower() for m in _DNS_MARKERS):
+            return True
+    return False
+
+
+def _explain_error(e: BaseException, base: str) -> str:
+    """Return a plain-English explanation (rich markup) for a failed request.
+
+    Never raises: it runs inside error handlers, where a second exception would
+    hide the original problem.
+    """
+    try:
+        return _explain_error_impl(e, base)
+    except Exception:  # noqa: BLE001
+        return escape(str(e) or type(e).__name__)
+
+
+def _explain_error_impl(e: BaseException, base: str) -> str:
+    host, port = _host_port(base)
+    chain = list(_exc_chain(e))
+    if _is_dns_error(e):
+        return (
+            f"Can't reach Spooling Cloud at {escape(base)}\n"
+            f"  The hostname '{escape(host)}' doesn't resolve (DNS lookup failed).\n"
+            f"  Either you're offline, or that server doesn't exist (yet).\n"
+            f"  - Offline or on a VPN? Check your connection and try again.\n"
+            f"  - {_SELF_HOST_HINT}"
+        )
+    if any(isinstance(x, ConnectionRefusedError) for x in chain):
+        return (
+            f"Connection refused by {escape(host)}:{port}\n"
+            f"  The host is reachable but nothing is listening. Is the sync server running?\n"
+            f"  - {_SELF_HOST_HINT}"
+        )
+    if isinstance(e, httpx.TimeoutException) or any(isinstance(x, (TimeoutError, socket.timeout)) for x in chain):
+        return (
+            f"Timed out talking to {escape(base)}\n"
+            f"  The server may be starting up or overloaded. Try again in a moment."
+        )
+    if any(isinstance(x, ssl.SSLError) for x in chain):
+        return (
+            f"TLS/SSL error connecting to {escape(host)}\n"
+            f"  {escape(str(e))}\n"
+            f"  Check the server's certificate, and that the URL scheme (http/https) is right."
+        )
+    if isinstance(e, httpx.ConnectError):
+        return f"Can't connect to {escape(base)}: {escape(str(e) or type(e).__name__)}"
+    return escape(str(e) or type(e).__name__)
+
+
+def _explain_http(e: "httpx.HTTPStatusError") -> str:
+    code = e.response.status_code
+    body = escape(e.response.text[:200])
+    if code == 401:
+        return (
+            f"HTTP 401: the server rejected your API key.\n"
+            f"  Create a new key in the admin app (Settings > API keys), then run\n"
+            f"    spooling cloud login --key sk_...\n"
+            f"  {body}"
+        )
+    if code == 403:
+        return f"HTTP 403: this API key isn't allowed to do that (missing scope or no workspace).\n  {body}"
+    if code == 429:
+        retry = e.response.headers.get("retry-after")
+        return f"HTTP 429: rate limited{f', retry in {retry}s' if retry else ''}. Slow down or try again shortly."
+    if code >= 500:
+        return f"HTTP {code}: the server hit an error. This is not a problem with your data; try again shortly.\n  {body}"
+    return f"HTTP {code}: {body}"
+
+
+def _fail(message: str) -> "None":
+    """Print an error and exit non-zero so scripts and cron can detect it."""
+    console.print(f"[red]{message}[/red]")
+    raise click.exceptions.Exit(1)
+
+
+def _preflight(base: str) -> None:
+    """Fail fast, before any sync/redaction work, if the server can't be resolved.
+
+    Only checks DNS (no request is sent, so it works with any server version).
+    Connection-level problems are still reported by the request itself.
+    """
+    host, port = _host_port(base)
+    try:
+        socket.getaddrinfo(host, port, type=socket.SOCK_STREAM)
+    except OSError as e:
+        console.print(f"[red]{_explain_error(e, base)}[/red]")
+        console.print("[dim]Nothing was sent. Your local sessions are untouched.[/dim]")
+        raise click.exceptions.Exit(1)
+
+
 @click.group()
 def cloud():
     """Spooling Cloud: push local sessions to api.spooling.ai."""
@@ -93,8 +234,10 @@ def cloud_login(key: str, api_url: str | None):
         stats = r.json()
         console.print(f"[green]Logged in to {base}[/green]")
         console.print(f"  sessions in cloud: [bold]{stats.get('sessions', 0)}[/bold]")
+    except httpx.HTTPStatusError as e:
+        console.print(f"[red]Saved key, but the server rejected the check:\n  {_explain_http(e)}[/red]")
     except Exception as e:
-        console.print(f"[red]Saved key, but /v1/stats check failed: {e}[/red]")
+        console.print(f"[red]Saved key, but couldn't verify it.\n  {_explain_error(e, base)}[/red]")
 
 
 @cloud.command("status")
@@ -114,8 +257,10 @@ def cloud_status():
         console.print(f"  messages: [bold]{s.get('messages', 0)}[/bold]")
         console.print(f"  providers: [bold]{s.get('providers', 0)}[/bold]")
         console.print(f"  cost: [bold]${s.get('cost', 0):.2f}[/bold]")
+    except httpx.HTTPStatusError as e:
+        _fail(f"{_explain_http(e)}")
     except Exception as e:
-        console.print(f"[red]Error: {e}[/red]")
+        _fail(f"{_explain_error(e, base)}")
 
 
 @cloud.command("logout")
@@ -395,14 +540,9 @@ def _push_trace_batches(
                 else:
                     log(f"  pushed {acc} trace(s), {spans} span(s)")
             except httpx.HTTPStatusError as e:
-                return (
-                    accepted,
-                    rejected,
-                    spans_total,
-                    f"HTTP {e.response.status_code}: {e.response.text[:200]}",
-                )
+                return accepted, rejected, spans_total, _explain_http(e)
             except Exception as e:
-                return accepted, rejected, spans_total, str(e)
+                return accepted, rejected, spans_total, _explain_error(e, base)
     return accepted, rejected, spans_total, None
 
 
@@ -448,9 +588,9 @@ def _push_batches(
                 else:
                     log(f"  pushed {accepted} sessions")
             except httpx.HTTPStatusError as e:
-                return total, rejected, f"HTTP {e.response.status_code}: {e.response.text[:200]}"
+                return total, rejected, _explain_http(e)
             except Exception as e:
-                return total, rejected, str(e)
+                return total, rejected, _explain_error(e, base)
     return total, rejected, None
 
 
@@ -559,6 +699,8 @@ def push(limit: int, batch: int, project: str | None, cwd_substr: str | None, ti
         return
     headers = _auth_headers()
     base = _api_base()
+    if not dry_run:
+        _preflight(base)  # fail fast, before syncing and redacting, if the server can't be reached
     if do_sync:
         _sync_local()
     sessions = _collect_sessions(
@@ -607,8 +749,7 @@ def push(limit: int, batch: int, project: str | None, cwd_substr: str | None, ti
         return
     total, rejected, err = _push_batches(sessions, batch, base, headers, console.print, copy=copy)
     if err:
-        console.print(f"[red]{err}[/red]")
-        return
+        _fail(err)
     if rejected:
         console.print(
             f"[green]Done.[/green] {total} sessions synced to {base} "
@@ -649,8 +790,7 @@ def push(limit: int, batch: int, project: str | None, cwd_substr: str | None, ti
             traces, trace_batch_size, base, headers, console.print,
         )
         if t_err:
-            console.print(f"[yellow]Trace push failed: {t_err}[/yellow]")
-            return
+            _fail(f"Sessions were pushed, but the trace/span upload failed:\n  {t_err}")
         msg = f"[green]Done.[/green] {t_acc} trace(s) and {t_spans} span(s) synced"
         if t_rej:
             msg += f" ([yellow]{t_rej} trace(s) rejected[/yellow])"
@@ -715,7 +855,7 @@ def cloud_watch(interval: int, limit: int, batch: int, lookback: int, no_redact:
                     console.print(f"  [dim]Redacted {redaction_count} secret(s) before push[/dim]")
             total, rejected, err = _push_batches(sessions, batch, base, headers, console.print)
             if err:
-                console.print(f"[red]{err}[/red] (will retry next cycle)")
+                console.print(f"[red]{err.splitlines()[0]}[/red] (will retry next cycle)")
             else:
                 # Advance watermark to the cycle start; the lookback window catches
                 # sessions whose started_at slid backwards or whose messages were
@@ -790,6 +930,7 @@ def cloud_delete(project: str | None, cwd_substr: str | None, session_id: str |
 
     headers = _auth_headers()
     base = _api_base()
+    _preflight(base)
     params = {"dry_run": "true" if dry_run else "false"}
     if project:
         params["project"] = project
@@ -810,10 +951,10 @@ def cloud_delete(project: str | None, cwd_substr: str | None, session_id: str |
         r.raise_for_status()
         data = r.json()
     except httpx.HTTPStatusError as e:
-        console.print(f"[red]HTTP {e.response.status_code}: {e.response.text[:200]}[/red]")
+        console.print(f"[red]{_explain_http(e)}[/red]")
         return
     except Exception as e:
-        console.print(f"[red]{e}[/red]")
+        console.print(f"[red]{_explain_error(e, base)}[/red]")
         return
 
     matched = data.get("matched", 0)
@@ -928,9 +1069,9 @@ def _pull_sessions(
             r = client.get(f"{base}/v1/sessions", headers=headers, params=params)
             r.raise_for_status()
         except httpx.HTTPStatusError as e:
-            return 0, 0, f"HTTP {e.response.status_code}: {e.response.text[:200]}"
+            return 0, 0, _explain_http(e)
         except Exception as e:
-            return 0, 0, str(e)
+            return 0, 0, _explain_error(e, base)
 
         data = r.json()
         cloud_sessions = data.get("sessions", [])
@@ -979,6 +1120,7 @@ def pull(limit: int, batch: int, dry_run: bool):
     """
     headers = _auth_headers()
     base = _api_base()
+    _preflight(base)
 
     cfg = _load_config()
     last = cfg.get("last_pull_at")
@@ -996,10 +1138,10 @@ def pull(limit: int, batch: int, dry_run: bool):
         r = httpx.get(f"{base}/v1/sessions", headers=headers, params=params, timeout=30)
         r.raise_for_status()
     except httpx.HTTPStatusError as e:
-        console.print(f"[red]HTTP {e.response.status_code}: {e.response.text[:200]}[/red]")
+        console.print(f"[red]{_explain_http(e)}[/red]")
         return
     except Exception as e:
-        console.print(f"[red]{e}[/red]")
+        console.print(f"[red]{_explain_error(e, base)}[/red]")
         return
 
     data = r.json()
@@ -1070,6 +1212,7 @@ def sync(limit: int, batch: int, project: str | None, cwd_substr: str | None, ti
     """
     headers = _auth_headers()
     base = _api_base()
+    _preflight(base)
 
     # Phase 1: Push local → cloud
     console.print("[bold]Phase 1: Push local → cloud[/bold]")
@@ -1115,10 +1258,10 @@ def sync(limit: int, batch: int, project: str | None, cwd_substr: str | None, ti
         r = httpx.get(f"{base}/v1/sessions", headers=headers, params=params, timeout=30)
         r.raise_for_status()
     except httpx.HTTPStatusError as e:
-        console.print(f"  [red]HTTP {e.response.status_code}: {e.response.text[:200]}[/red]")
+        console.print(f"  [red]{_explain_http(e)}[/red]")
         return
     except Exception as e:
-        console.print(f"  [red]{e}[/red]")
+        console.print(f"  [red]{_explain_error(e, base)}[/red]")
         return
 
     data = r.json()

{spooling-0.2.9 → spooling-0.2.10/spooling.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: spooling
-Version: 0.2.9
+Version: 0.2.10
 Summary: Local session tracker and semantic search for AI coding assistants
 Author: Parsed Analytics, Inc.
 License: MIT

{spooling-0.2.9 → spooling-0.2.10}/spooling.egg-info/SOURCES.txt

@@ -64,6 +64,7 @@ spooling/providers/opencode.py
 spooling/providers/session_file.py
 spooling/providers/windsurf.py
 tests/test_claude_code_provider.py
+tests/test_cloud_errors.py
 tests/test_mcp_auth_middleware.py
 tests/test_session_ids.py
 tests/test_storage_optimizations.py

spooling-0.2.10/tests/test_cloud_errors.py

@@ -0,0 +1,219 @@
+"""Tests for friendly cloud errors: DNS / refused / TLS / HTTP status handling,
+fail-fast preflight, and non-zero exit codes for `spooling push`."""
+
+import json
+import socket
+import ssl
+import threading
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+
+import httpx
+import pytest
+from click.testing import CliRunner
+
+from spooling import cloud
+from spooling.cli import cli
+
+
+# --- helpers -----------------------------------------------------------------
+
+class _Handler(BaseHTTPRequestHandler):
+    status = 200
+    body = {"sessions": 3, "messages": 9, "providers": 1, "cost": 1.5,
+            "accepted": 1, "rejected": 0}
+    seen: list[str] = []
+
+    def log_message(self, *a):  # silence
+        pass
+
+    def _go(self):
+        type(self).seen.append(f"{self.command} {self.path}")
+        payload = json.dumps(type(self).body if type(self).status == 200 else {"detail": "nope"}).encode()
+        self.send_response(type(self).status)
+        if type(self).status == 429:
+            self.send_header("Retry-After", "42")
+        self.send_header("Content-Type", "application/json")
+        self.send_header("Content-Length", str(len(payload)))
+        self.end_headers()
+        self.wfile.write(payload)
+
+    do_GET = do_POST = do_DELETE = _go
+
+
+@pytest.fixture
+def server():
+    """Run a throwaway HTTP server; set .status to choose the response code."""
+    handler = type("H", (_Handler,), {"status": 200, "seen": []})
+    srv = ThreadingHTTPServer(("127.0.0.1", 0), handler)
+    t = threading.Thread(target=srv.serve_forever, daemon=True)
+    t.start()
+    srv.handler = handler
+    srv.url = f"http://127.0.0.1:{srv.server_address[1]}"
+    yield srv
+    srv.shutdown()
+
+
+@pytest.fixture
+def logged_in(tmp_path, monkeypatch):
+    """Isolated config so tests never touch the real ~/.config/spooling."""
+    cfg = tmp_path / "cloud.json"
+    monkeypatch.setattr(cloud, "CONFIG_PATH", cfg)
+    monkeypatch.delenv("SPOOLING_CLOUD_URL", raising=False)
+    monkeypatch.delenv("SPOOLING_CLOUD_API_KEY", raising=False)
+
+    def point_at(url):
+        cfg.write_text(json.dumps({"api_key": "sk_test", "api_url": url}))
+
+    point_at(cloud.DEFAULT_API)
+    return point_at
+
+
+def free_port() -> int:
+    s = socket.socket()
+    s.bind(("127.0.0.1", 0))
+    port = s.getsockname()[1]
+    s.close()
+    return port
+
+
+def run(*args):
+    return CliRunner().invoke(cli, list(args))
+
+
+def one_session():
+    return [{"id": "s1", "provider_id": "claude-code", "project": "p", "title": "t",
+             "messages": [], "message_count": 0}]
+
+
+# --- DNS ---------------------------------------------------------------------
+
+def _no_dns(monkeypatch):
+    def boom(*a, **k):
+        raise socket.gaierror(8, "nodename nor servname provided, or not known")
+    monkeypatch.setattr(socket, "getaddrinfo", boom)
+
+
+def test_push_fails_fast_on_dns_before_any_work(logged_in, monkeypatch):
+    _no_dns(monkeypatch)
+    monkeypatch.setattr(cloud, "_sync_local", lambda *a, **k: pytest.fail("synced before preflight"))
+    monkeypatch.setattr(cloud, "_collect_sessions", lambda **k: pytest.fail("collected before preflight"))
+
+    r = run("push", "--with-spans")
+
+    assert r.exit_code == 1
+    assert "Can't reach Spooling Cloud at https://api.spooling.ai" in r.output
+    assert "doesn't resolve" in r.output and "api.spooling.ai" in r.output
+    assert "--api-url" in r.output and "SPOOLING_CLOUD_URL" in r.output
+    assert "Nothing was sent" in r.output
+    assert "Errno" not in r.output          # the raw error is gone
+
+
+def test_push_dry_run_needs_no_network(logged_in, monkeypatch):
+    _no_dns(monkeypatch)
+    monkeypatch.setattr(cloud, "_collect_sessions", lambda **k: one_session())
+    r = run("push", "--dry-run", "--no-sync")
+    assert r.exit_code == 0
+    assert "would land in" in r.output
+
+
+@pytest.mark.parametrize("cmd", [["cloud", "pull"], ["cloud", "sync"], ["cloud", "delete", "--all", "--yes"]])
+def test_other_network_commands_preflight_too(logged_in, monkeypatch, cmd):
+    _no_dns(monkeypatch)
+    r = run(*cmd)
+    assert r.exit_code == 1 and "doesn't resolve" in r.output
+
+
+@pytest.mark.parametrize("msg", [
+    "[Errno 8] nodename nor servname provided, or not known",      # macOS
+    "[Errno -2] Name or service not known",                         # Linux
+    "[Errno -3] Temporary failure in name resolution",
+    "[Errno 11001] getaddrinfo failed",                             # Windows
+])
+def test_dns_detected_from_message_even_when_wrapped(msg):
+    inner = OSError(msg)
+    wrapped = httpx.ConnectError("boom")
+    wrapped.__cause__ = inner
+    assert cloud._is_dns_error(wrapped)
+    assert "doesn't resolve" in cloud._explain_error(wrapped, "https://x.example")
+
+
+# --- connection-level errors -------------------------------------------------
+
+def test_connection_refused_is_explained(logged_in):
+    logged_in(f"http://127.0.0.1:{free_port()}")
+    r = run("cloud", "status")
+    assert r.exit_code == 1
+    assert "Connection refused" in r.output and "nothing is listening" in r.output
+
+
+def test_timeout_and_tls_messages():
+    t = cloud._explain_error(httpx.ReadTimeout("slow"), "https://x.example")
+    assert "Timed out" in t
+    inner = ssl.SSLError("CERTIFICATE_VERIFY_FAILED")
+    e = httpx.ConnectError("tls")
+    e.__cause__ = inner
+    assert "TLS/SSL error" in cloud._explain_error(e, "https://x.example")
+
+
+def test_explainer_never_raises_on_garbage():
+    assert cloud._explain_error(ValueError("x"), "http://host:99999999")      # bad port
+    assert cloud._explain_error(RuntimeError(""), "")                          # empty everything
+    assert cloud._explain_error(Exception("[red]markup[/red]"), "https://x")   # rich markup in message
+
+
+# --- HTTP status codes -------------------------------------------------------
+
+@pytest.mark.parametrize("status,needle", [
+    (401, "rejected your API key"),
+    (403, "isn't allowed"),
+    (429, "rate limited, retry in 42s"),
+    (500, "not a problem with your data"),
+])
+def test_http_errors_are_explained_and_exit_nonzero(logged_in, server, status, needle):
+    server.handler.status = status
+    logged_in(server.url)
+    r = run("cloud", "status")
+    assert r.exit_code == 1
+    assert needle in r.output
+
+
+def test_status_success(logged_in, server):
+    logged_in(server.url)
+    r = run("cloud", "status")
+    assert r.exit_code == 0
+    assert "sessions: 3" in r.output
+
+
+# --- push exit codes ---------------------------------------------------------
+
+def test_push_success_exits_zero(logged_in, server, monkeypatch):
+    logged_in(server.url)
+    monkeypatch.setattr(cloud, "_collect_sessions", lambda **k: one_session())
+    r = run("push", "--no-sync")
+    assert r.exit_code == 0 and "Done." in r.output
+    assert "POST /v1/sessions/batch" in server.handler.seen
+
+
+@pytest.mark.parametrize("status", [401, 500])
+def test_push_server_error_exits_nonzero(logged_in, server, monkeypatch, status):
+    server.handler.status = status
+    logged_in(server.url)
+    monkeypatch.setattr(cloud, "_collect_sessions", lambda **k: one_session())
+    r = run("push", "--no-sync")
+    assert r.exit_code == 1
+    assert "Done." not in r.output
+
+
+def test_push_connection_refused_exits_nonzero(logged_in, monkeypatch):
+    logged_in(f"http://127.0.0.1:{free_port()}")
+    monkeypatch.setattr(cloud, "_collect_sessions", lambda **k: one_session())
+    r = run("push", "--no-sync")
+    assert r.exit_code == 1 and "Connection refused" in r.output
+
+
+def test_login_check_failure_still_saves_key_and_explains(tmp_path, monkeypatch):
+    monkeypatch.setattr(cloud, "CONFIG_PATH", tmp_path / "cloud.json")
+    port = free_port()
+    r = run("cloud", "login", "--key", "sk_new", "--api-url", f"http://127.0.0.1:{port}")
+    assert "couldn't verify it" in r.output and "Connection refused" in r.output
+    assert json.loads((tmp_path / "cloud.json").read_text())["api_key"] == "sk_new"