gfa-sdk 0.1.0__py3-none-any.whl

gfa/__init__.py

@@ -0,0 +1,82 @@
+"""gfa — Opinionated Python SDK for gfa (Git for Agents).
+
+Public surface re-exports. Power users can reach into submodules
+(``gfa.routing``, ``gfa.cache``) to inspect internals.
+
+See ``design/smart-client-sdk.md`` in the gfa repo for the design spec.
+"""
+
+from gfa._version import __version__
+from gfa.async_client import AsyncClient
+from gfa.cache import BlobCache, ProfileCache, RefCache
+from gfa.client import Client
+from gfa.defaults import ClientConfig
+from gfa.errors import (
+    BadRequestError,
+    ConflictError,
+    FileNotFoundError,
+    ForbiddenError,
+    GfaError,
+    GitBinaryMissingError,
+    RefNotFoundError,
+    RepoNotFoundError,
+    ServerError,
+    SuggestPartialCloneError,
+    TransportError,
+    UnauthorizedError,
+    UnavailableError,
+    UnprocessableError,
+)
+from gfa.hints import Hint, HintHandler, default_hint_handler
+from gfa.mint_token import FileKeyTokenProvider, TokenProvider
+from gfa.models import (
+    Author,
+    ClientStats,
+    CommitInfo,
+    ConflictSurface,
+    DivergeResult,
+    FileChange,
+    RepoProfile,
+    TreeEntry,
+)
+from gfa.partial_clone import PartialClone
+from gfa.workspace import Workspace
+
+__all__ = [
+    "__version__",
+    "AsyncClient",
+    "Author",
+    "BadRequestError",
+    "BlobCache",
+    "Client",
+    "ClientConfig",
+    "ClientStats",
+    "CommitInfo",
+    "ConflictError",
+    "ConflictSurface",
+    "DivergeResult",
+    "FileChange",
+    "FileKeyTokenProvider",
+    "FileNotFoundError",
+    "ForbiddenError",
+    "GfaError",
+    "GitBinaryMissingError",
+    "Hint",
+    "HintHandler",
+    "PartialClone",
+    "ProfileCache",
+    "RefCache",
+    "RefNotFoundError",
+    "RepoNotFoundError",
+    "RepoProfile",
+    "ServerError",
+    "SuggestPartialCloneError",
+    "TokenProvider",
+    "TransportError",
+    "TreeEntry",
+    "UnauthorizedError",
+    "UnavailableError",
+    "UnprocessableError",
+    "Workspace",
+    "default_hint_handler",
+]

gfa/_transport.py

@@ -0,0 +1,383 @@
+"""HTTP transport for the SDK.
+
+Wraps an ``httpx.Client`` with:
+
+- Bearer-token-via-Basic-Auth header injection (gfa uses HTTP Basic with
+  username='t', password=<JWT>)
+- Exponential backoff retry on 5xx + network errors, with jitter
+- Atomic telemetry counters (request count, byte counts, per-endpoint hits)
+- Error envelope -> typed exception mapping
+
+This module is intentionally small. The high-level routing/cache logic
+lives in :mod:`gfa.client`; we just deliver well-formed HTTP/JSON.
+"""
+
+from __future__ import annotations
+
+import base64
+import json
+import random
+import threading
+import time
+from dataclasses import dataclass
+from typing import Any, Mapping
+
+import httpx
+
+from gfa.defaults import ClientConfig
+from gfa.errors import (
+    GfaError,
+    TransportError,
+    map_status_to_error,
+)
+from gfa.mint_token import TokenProvider
+from gfa._version import __version__
+
+
+@dataclass
+class _Counters:
+    request_count: int = 0
+    byte_count_in: int = 0
+    byte_count_out: int = 0
+    cache_hit_count: int = 0
+    cache_miss_count: int = 0
+    hints_emitted: int = 0
+
+
+class Transport:
+    """HTTP transport + retry + auth + telemetry.
+
+    One ``Transport`` instance per ``Client``. Thread-safe (httpx.Client is
+    thread-safe by design; the counters use a Lock).
+    """
+
+    def __init__(
+        self,
+        *,
+        endpoint: str,
+        token: str | TokenProvider,
+        config: ClientConfig,
+        transport: httpx.BaseTransport | None = None,
+    ) -> None:
+        if not endpoint:
+            raise ValueError("endpoint must be non-empty")
+        # Normalize: strip trailing slash.
+        self.endpoint = endpoint.rstrip("/")
+        self._token: str | TokenProvider = token
+        self._config = config
+        self._counters = _Counters()
+        self._per_endpoint: dict[str, int] = {}
+        self._lock = threading.Lock()
+
+        user_agent = config.user_agent or f"gfa-sdk-python/{__version__}"
+
+        # httpx.Client kwargs. ``transport`` is for test injection
+        # (httpx.MockTransport). Don't pass http2 when a mock transport is
+        # used — MockTransport doesn't speak HTTP/2.
+        kwargs: dict[str, Any] = {
+            "base_url": self.endpoint,
+            "timeout": httpx.Timeout(
+                config.timeout_seconds,
+                connect=config.connect_timeout_seconds,
+            ),
+            "limits": httpx.Limits(max_connections=config.pool_max_connections),
+            "headers": {"User-Agent": user_agent},
+            "follow_redirects": False,
+        }
+        if transport is not None:
+            kwargs["transport"] = transport
+        else:
+            kwargs["http2"] = config.http2
+        self._http = httpx.Client(**kwargs)
+
+    # -------------------------------------------------------------------
+    # Lifecycle
+    # -------------------------------------------------------------------
+
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> "Transport":
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
+
+    # -------------------------------------------------------------------
+    # Counters / telemetry
+    # -------------------------------------------------------------------
+
+    @property
+    def counters(self) -> _Counters:
+        with self._lock:
+            return _Counters(
+                request_count=self._counters.request_count,
+                byte_count_in=self._counters.byte_count_in,
+                byte_count_out=self._counters.byte_count_out,
+                cache_hit_count=self._counters.cache_hit_count,
+                cache_miss_count=self._counters.cache_miss_count,
+                hints_emitted=self._counters.hints_emitted,
+            )
+
+    @property
+    def per_endpoint(self) -> dict[str, int]:
+        with self._lock:
+            return dict(self._per_endpoint)
+
+    def record_cache_hit(self) -> None:
+        with self._lock:
+            self._counters.cache_hit_count += 1
+
+    def record_cache_miss(self) -> None:
+        with self._lock:
+            self._counters.cache_miss_count += 1
+
+    def record_hint_emitted(self) -> None:
+        with self._lock:
+            self._counters.hints_emitted += 1
+
+    # -------------------------------------------------------------------
+    # Request entry points
+    # -------------------------------------------------------------------
+
+    def request_json(
+        self,
+        method: str,
+        path: str,
+        *,
+        op_id: str,
+        repo_for_token: str | None = None,
+        params: Mapping[str, Any] | None = None,
+        json_body: Any | None = None,
+        expected_status: tuple[int, ...] = (200, 201),
+    ) -> tuple[int, dict[str, Any], httpx.Headers]:
+        """Send a request, parse the JSON body, return (status, parsed, headers).
+
+        Raises a typed ``GfaError`` subclass on non-expected status. Errors
+        from ``ErrorEnvelope`` payloads carry the machine ``error`` code
+        through to disambiguate 404 cases. Network failures raise
+        :class:`TransportError`.
+
+        ``expected_status`` is the set of statuses that are considered
+        success for this call. 204 (no content) returns an empty dict.
+        """
+        response = self._send(
+            method, path, op_id=op_id,
+            repo_for_token=repo_for_token,
+            params=params, json_body=json_body, content=None,
+            accept="application/json",
+        )
+        status = response.status_code
+        body = response.content
+        if status == 204 or not body:
+            parsed: dict[str, Any] = {}
+        else:
+            try:
+                parsed = response.json()
+                if not isinstance(parsed, (dict, list)):
+                    # Some endpoints (listTree) return arrays — wrap.
+                    parsed = {"_array": parsed}
+            except json.JSONDecodeError as e:
+                # Non-JSON body from a JSON endpoint -> server error.
+                raise GfaError(
+                    f"invalid JSON in response from {path}: {e}",
+                    status=status,
+                    body=response.text,
+                ) from e
+        if status not in expected_status:
+            self._raise_from_response(response, op_id=op_id)
+        return status, parsed, response.headers
+
+    def request_array(
+        self,
+        method: str,
+        path: str,
+        *,
+        op_id: str,
+        repo_for_token: str | None = None,
+        params: Mapping[str, Any] | None = None,
+        json_body: Any | None = None,
+        expected_status: tuple[int, ...] = (200, 201),
+    ) -> tuple[int, list[Any], httpx.Headers]:
+        """Same as ``request_json`` but expects an array body."""
+        response = self._send(
+            method, path, op_id=op_id,
+            repo_for_token=repo_for_token,
+            params=params, json_body=json_body, content=None,
+            accept="application/json",
+        )
+        status = response.status_code
+        if status not in expected_status:
+            self._raise_from_response(response, op_id=op_id)
+        if not response.content:
+            return status, [], response.headers
+        try:
+            parsed = response.json()
+        except json.JSONDecodeError as e:
+            raise GfaError(
+                f"invalid JSON in response from {path}: {e}",
+                status=status,
+                body=response.text,
+            ) from e
+        if isinstance(parsed, list):
+            return status, parsed, response.headers
+        # Server returned an object where we expected an array; surface as error.
+        raise GfaError(
+            f"expected JSON array from {path}, got {type(parsed).__name__}",
+            status=status,
+            body=response.text,
+        )
+
+    def request_bytes(
+        self,
+        method: str,
+        path: str,
+        *,
+        op_id: str,
+        repo_for_token: str | None = None,
+        params: Mapping[str, Any] | None = None,
+        expected_status: tuple[int, ...] = (200,),
+        accept: str = "application/octet-stream",
+    ) -> tuple[bytes, httpx.Headers]:
+        """For raw blob reads (``GET /file``). Returns the raw bytes."""
+        response = self._send(
+            method, path, op_id=op_id,
+            repo_for_token=repo_for_token,
+            params=params, json_body=None, content=None,
+            accept=accept,
+        )
+        if response.status_code not in expected_status:
+            self._raise_from_response(response, op_id=op_id)
+        return response.content, response.headers
+
+    # -------------------------------------------------------------------
+    # Internal: send w/ retry, auth, telemetry
+    # -------------------------------------------------------------------
+
+    def _send(
+        self,
+        method: str,
+        path: str,
+        *,
+        op_id: str,
+        repo_for_token: str | None,
+        params: Mapping[str, Any] | None,
+        json_body: Any | None,
+        content: bytes | None,
+        accept: str,
+    ) -> httpx.Response:
+        # Prepare body
+        body_bytes: bytes | None = None
+        headers = {"Accept": accept}
+        if json_body is not None:
+            body_bytes = json.dumps(json_body).encode("utf-8")
+            headers["Content-Type"] = "application/json"
+        elif content is not None:
+            body_bytes = content
+        # Auth header
+        headers["Authorization"] = self._auth_header(repo_for_token)
+
+        retry_attempts = self._config.max_retries
+        backoff = self._config.retry_backoff_initial_seconds
+
+        last_exc: Exception | None = None
+        for attempt in range(retry_attempts + 1):
+            try:
+                self._tick_request(op_id, request_size=len(body_bytes or b""))
+                response = self._http.request(
+                    method,
+                    path,
+                    params=params,
+                    content=body_bytes,
+                    headers=headers,
+                )
+                # tick byte_count_in
+                self._tick_response(len(response.content or b""))
+                if (
+                    response.status_code in self._config.retry_on_status
+                    and attempt < retry_attempts
+                ):
+                    self._sleep_backoff(backoff)
+                    backoff = min(
+                        backoff * 2,
+                        self._config.retry_backoff_max_seconds,
+                    )
+                    continue
+                return response
+            except (httpx.ConnectError, httpx.ReadTimeout,
+                    httpx.WriteTimeout, httpx.PoolTimeout,
+                    httpx.RemoteProtocolError, httpx.NetworkError) as e:
+                last_exc = e
+                if attempt < retry_attempts:
+                    self._sleep_backoff(backoff)
+                    backoff = min(
+                        backoff * 2,
+                        self._config.retry_backoff_max_seconds,
+                    )
+                    continue
+                raise TransportError(
+                    f"network error after {attempt + 1} attempts: {e}"
+                ) from e
+        # Should be unreachable (the loop either returns or raises).
+        raise TransportError(
+            f"exhausted retries; last error: {last_exc}"
+        ) from last_exc
+
+    def _tick_request(self, op_id: str, request_size: int) -> None:
+        with self._lock:
+            self._counters.request_count += 1
+            self._counters.byte_count_out += request_size
+            self._per_endpoint[op_id] = self._per_endpoint.get(op_id, 0) + 1
+
+    def _tick_response(self, response_size: int) -> None:
+        with self._lock:
+            self._counters.byte_count_in += response_size
+
+    def _sleep_backoff(self, base: float) -> None:
+        # +/- jitter%
+        jitter = self._config.retry_backoff_jitter
+        if jitter > 0:
+            base = base * (1.0 + random.uniform(-jitter, jitter))
+        time.sleep(max(0.0, base))
+
+    def _auth_header(self, repo: str | None) -> str:
+        """HTTP Basic with username='t', password=<JWT>.
+
+        This matches the code.storage-style scheme that gfa uses on the
+        wire (see ``CLAUDE.md`` -> Auth Model). The username 't' is
+        always literal — only the password (JWT) varies.
+        """
+        token = self._token
+        if isinstance(token, str):
+            jwt_str = token
+        else:
+            jwt_str = token.token_for(repo)
+        raw = f"t:{jwt_str}".encode("utf-8")
+        return "Basic " + base64.b64encode(raw).decode("ascii")
+
+    def _raise_from_response(self, response: httpx.Response, *, op_id: str) -> None:
+        """Translate an HTTP error response into a typed exception."""
+        status = response.status_code
+        error_code = ""
+        message = ""
+        body_text = ""
+        try:
+            body_text = response.text
+        except Exception:
+            body_text = ""
+        try:
+            parsed = response.json()
+            if isinstance(parsed, dict):
+                error_code = str(parsed.get("error", "") or "")
+                message = str(parsed.get("message", "") or "")
+        except (json.JSONDecodeError, UnicodeDecodeError, ValueError):
+            pass
+        request_id = response.headers.get("X-Gfa-Request-Id", "") or ""
+        raise map_status_to_error(
+            status,
+            url=str(response.request.url) if response.request else "",
+            error_code=error_code,
+            message=message or f"{op_id} failed with status {status}",
+            request_id=request_id,
+            body=body_text,
+        )

gfa/_version.py

@@ -0,0 +1,8 @@
+"""Single source of truth for the gfa-sdk version string.
+
+Keep in sync with ``pyproject.toml``'s ``[project].version``. The package
+re-exports ``__version__`` from here so callers can do
+``gfa.__version__`` for diagnostics.
+"""
+
+__version__ = "0.1.0"

gfa/async_client.py

@@ -0,0 +1,31 @@
+"""``gfa.AsyncClient`` — stub.
+
+The async port is filed as M-055-SDK-ASYNC follow-on. v1 ships the sync
+client only. The class is importable so callers can detect availability
+via ``hasattr(gfa, "AsyncClient")``; every method raises
+``NotImplementedError`` with a pointer to the follow-on item.
+
+When the async client lands, the underlying ``_transport.py`` will gain
+an ``async_request_*`` family using ``httpx.AsyncClient``; the routing,
+cache, and hint layers reuse the same logic.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+_MSG = (
+    "AsyncClient is not implemented in gfa-sdk 0.1 — "
+    "use `gfa.Client` (sync). Async lands in M-055-SDK-ASYNC follow-on."
+)
+
+
+class AsyncClient:
+    """Stub async client. All methods raise :class:`NotImplementedError`."""
+
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        raise NotImplementedError(_MSG)
+
+    def __getattr__(self, name: str) -> Any:  # pragma: no cover - never reached
+        raise NotImplementedError(_MSG)

gfa/cache.py

@@ -0,0 +1,181 @@
+"""Session-level caches.
+
+Three independent caches with independent TTL policies:
+
+- :class:`ProfileCache` — per-repo ``RepoProfile``; default TTL is the
+  session lifetime (never expires unless ``profile_ttl_seconds`` is finite).
+- :class:`RefCache` — ``(repo, ref-name)`` -> resolved SHA; 60s TTL by default.
+- :class:`BlobCache` — blob-SHA -> bytes; LRU bounded by max-bytes; off by
+  default.
+
+All caches are thread-safe. The Client holds one instance of each.
+"""
+
+from __future__ import annotations
+
+import math
+import threading
+import time
+from collections import OrderedDict
+from typing import Generic, TypeVar
+
+from gfa.models import RepoProfile
+
+K = TypeVar("K")
+V = TypeVar("V")
+
+
+class _TTLEntry(Generic[V]):
+    __slots__ = ("value", "expires_at")
+
+    def __init__(self, value: V, expires_at: float) -> None:
+        self.value = value
+        self.expires_at = expires_at
+
+
+class ProfileCache:
+    """Per-repo ``RepoProfile`` cache.
+
+    Unbounded — profiles are ~1 KB and a session typically touches a small
+    number of repos. TTL defaults to infinity (session lifetime).
+    """
+
+    def __init__(self, ttl_seconds: float = math.inf) -> None:
+        self._ttl = ttl_seconds
+        self._entries: dict[str, _TTLEntry[RepoProfile]] = {}
+        self._lock = threading.Lock()
+
+    def get(self, repo: str) -> RepoProfile | None:
+        with self._lock:
+            entry = self._entries.get(repo)
+            if entry is None:
+                return None
+            if entry.expires_at < time.monotonic():
+                del self._entries[repo]
+                return None
+            return entry.value
+
+    def put(self, repo: str, profile: RepoProfile) -> None:
+        with self._lock:
+            expires = (
+                math.inf if math.isinf(self._ttl) else time.monotonic() + self._ttl
+            )
+            self._entries[repo] = _TTLEntry(profile, expires)
+
+    def invalidate(self, repo: str | None = None) -> None:
+        with self._lock:
+            if repo is None:
+                self._entries.clear()
+            else:
+                self._entries.pop(repo, None)
+
+
+class RefCache:
+    """Ref-name -> resolved-SHA cache.
+
+    Keyed by ``(repo, ref)``. SHA-form refs (40-hex) are not cached — they
+    don't move and lookups are pointless.
+    """
+
+    def __init__(self, ttl_seconds: float = 60.0) -> None:
+        self._ttl = ttl_seconds
+        self._entries: dict[tuple[str, str], _TTLEntry[str]] = {}
+        self._lock = threading.Lock()
+
+    @staticmethod
+    def is_sha_like(ref: str) -> bool:
+        if len(ref) != 40:
+            return False
+        return all(c in "0123456789abcdef" for c in ref.lower())
+
+    def get(self, repo: str, ref: str) -> str | None:
+        if self.is_sha_like(ref):
+            return ref
+        key = (repo, ref)
+        with self._lock:
+            entry = self._entries.get(key)
+            if entry is None:
+                return None
+            if entry.expires_at < time.monotonic():
+                del self._entries[key]
+                return None
+            return entry.value
+
+    def put(self, repo: str, ref: str, sha: str) -> None:
+        if self.is_sha_like(ref):
+            return
+        with self._lock:
+            self._entries[(repo, ref)] = _TTLEntry(
+                sha, time.monotonic() + self._ttl
+            )
+
+    def invalidate_repo(self, repo: str) -> None:
+        """Drop every cached entry for ``repo`` (called after commit/merge)."""
+        with self._lock:
+            for k in list(self._entries.keys()):
+                if k[0] == repo:
+                    del self._entries[k]
+
+    def invalidate_all(self) -> None:
+        with self._lock:
+            self._entries.clear()
+
+
+class BlobCache:
+    """LRU cache of blob bytes keyed by blob SHA.
+
+    Bounded by total byte size (not entry count). Eviction is strict-LRU:
+    on insert that would exceed capacity, oldest entries are dropped until
+    the new entry fits. Disabled (always misses) when ``max_bytes <= 0``.
+
+    Off by default — turn on for benchmarks or read-heavy agents that
+    revisit blobs.
+    """
+
+    def __init__(self, max_bytes: int, enabled: bool = False) -> None:
+        self._max_bytes = max(0, max_bytes)
+        self._enabled = enabled and self._max_bytes > 0
+        self._entries: OrderedDict[str, bytes] = OrderedDict()
+        self._size = 0
+        self._lock = threading.Lock()
+
+    @property
+    def enabled(self) -> bool:
+        return self._enabled
+
+    @property
+    def size_bytes(self) -> int:
+        with self._lock:
+            return self._size
+
+    def get(self, sha: str) -> bytes | None:
+        if not self._enabled or not sha:
+            return None
+        with self._lock:
+            value = self._entries.get(sha)
+            if value is None:
+                return None
+            self._entries.move_to_end(sha)
+            return value
+
+    def put(self, sha: str, data: bytes) -> None:
+        if not self._enabled or not sha:
+            return
+        n = len(data)
+        if n > self._max_bytes:
+            # Item is bigger than the entire cache; do not store.
+            return
+        with self._lock:
+            if sha in self._entries:
+                old = self._entries.pop(sha)
+                self._size -= len(old)
+            while self._size + n > self._max_bytes and self._entries:
+                _, evicted = self._entries.popitem(last=False)
+                self._size -= len(evicted)
+            self._entries[sha] = data
+            self._size += n
+
+    def clear(self) -> None:
+        with self._lock:
+            self._entries.clear()
+            self._size = 0