sunstone-data-platform 1.0.0__py3-none-any.whl

sunstone_data/graph/client.py

@@ -0,0 +1,328 @@
+"""HTTP client for graph-server.
+
+graph-server speaks the SPARQL 1.1 Graph Store Protocol (GSP) over named
+graphs, plus small REST endpoints for branches, tags and concept maps. Its error
+bodies are bare ``text/plain`` with no JSON envelope, so this client maps
+``(status, route)`` to a typed exception and never reads a body for meaning
+(spec 180 §5).
+
+ETags are graph-server's optimistic-concurrency token. The wire form is the
+strong-quoted ``"txn-9"``; callers here see and pass the unquoted ``txn-9``,
+or the sentinel ``*`` for "whatever is current".
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+
+import httpx
+
+from sunstone_data.config import current_environment_name, get_settings
+
+#: graph-server rejects request bodies larger than this.
+MAX_REQUEST_BYTES = 64 * 1024 * 1024
+
+TURTLE = "text/turtle"
+N_TRIPLES = "application/n-triples"
+
+
+class AuthError(RuntimeError):
+    """Not authenticated: no token, or the token was rejected twice."""
+
+    def __init__(self, message: str = "Not authenticated; run `sunstone data login`"):
+        super().__init__(message)
+
+
+class PermissionError(RuntimeError):  # noqa: A001 - deliberate shadow, see module docstring
+    """Authenticated, but the token lacks the role the route needs.
+
+    The server's 403 body is the opaque string ``forbidden``, so the missing
+    role is worked out client-side from the method and path.
+
+    Attributes:
+        role: Role the route requires ("read" or "readwrite").
+        client_id: Client identity this client was configured with, if any.
+    """
+
+    def __init__(self, role: str, client_id: str | None):
+        self.role = role
+        self.client_id = client_id
+        super().__init__(f"missing role {role!r} for client {client_id!r}")
+
+
+class NotFound(RuntimeError):
+    """The branch, tag, graph or concept map does not exist."""
+
+
+class ConflictError(RuntimeError):
+    """An ``If-Match`` precondition failed.
+
+    Attributes:
+        etag: The branch's current ETag, unquoted. Refetch and retry with it.
+    """
+
+    def __init__(self, etag: str, message: str | None = None):
+        self.etag = etag
+        super().__init__(message or f"precondition failed; current ETag is {etag!r}")
+
+
+class TooLarge(RuntimeError):
+    """Request body exceeded the 64 MiB cap."""
+
+    def __init__(self, message: str = "request body exceeds the 64 MiB cap"):
+        super().__init__(message)
+
+
+class UnsupportedMedia(RuntimeError):
+    """Unsupported media type: Turtle or N-Triples only."""
+
+    def __init__(self, message: str = f"unsupported media type; use {TURTLE} or {N_TRIPLES}"):
+        super().__init__(message)
+
+
+class Unavailable(RuntimeError):
+    """graph SoR unavailable; safe to retry."""
+
+    def __init__(self, message: str = "graph SoR unavailable; safe to retry"):
+        super().__init__(message)
+
+
+def _required_role(method: str, path: str) -> str:
+    """Mirror graph-server's own role classifier (graph-core ``auth.rs``)."""
+    if path == "/sparql" and method in ("GET", "HEAD", "POST"):
+        return "read"
+    return "read" if method in ("GET", "HEAD") else "readwrite"
+
+
+def _unquote_etag(value: str | None) -> str:
+    """Strip the strong-quote wrapper from an ETag header value."""
+    return (value or "").strip().strip('"')
+
+
+class GraphClient:
+    """Thin HTTP client for a graph-server instance.
+
+    Args:
+        base_url: graph-server base URL (e.g. "http://localhost:8080").
+        token_provider: Returns a bearer token, or None when unauthenticated.
+            Called lazily on first use and again after a 401.
+        client_id: Client identity, reported in `PermissionError`. Informational
+            only — this client never decodes the token.
+        timeout: HTTP request timeout in seconds.
+    """
+
+    def __init__(
+        self,
+        base_url: str,
+        token_provider: Callable[[], str | None] | None = None,
+        client_id: str | None = None,
+        timeout: float = 10.0,
+    ):
+        self._base_url = base_url.rstrip("/")
+        self._token_provider = token_provider
+        self._client_id = client_id
+        self._timeout = timeout
+        self._token: str | None = None
+        self._token_loaded = False
+
+    # --- Graph Store Protocol ---
+
+    def get_graph(self, branch: str, graph_iri: str, accept: str = TURTLE) -> str:
+        """Fetch a named graph's contents as text.
+
+        Args:
+            branch: Branch name.
+            graph_iri: IRI of the named graph.
+            accept: `N_TRIPLES` for N-Triples; anything else yields Turtle.
+
+        Returns:
+            The serialized graph.
+
+        Raises:
+            NotFound: The branch or graph has no visible quads.
+        """
+        return self.get_graph_with_etag(branch, graph_iri, accept)[0]
+
+    def get_graph_with_etag(self, branch: str, graph_iri: str, accept: str = TURTLE) -> tuple[str, str]:
+        """Fetch a named graph's contents and the branch's ETag together.
+
+        A read-modify-write needs both from the *same* response: the ETag of a
+        later, separate read would not cover the bytes being modified.
+
+        Returns:
+            (serialized graph, ETag unquoted).
+
+        Raises:
+            NotFound: The branch or graph has no visible quads.
+        """
+        resp = self._request(
+            "GET",
+            f"/branches/{branch}/graphs",
+            params={"graph": graph_iri},
+            headers={"Accept": accept},
+        )
+        return resp.text, _unquote_etag(resp.headers.get("ETag"))
+
+    def put_graph(
+        self,
+        branch: str,
+        graph_iri: str,
+        data: str | bytes,
+        if_match: str,
+        content_type: str = TURTLE,
+    ) -> str:
+        """Replace a named graph. Returns the new ETag, unquoted."""
+        return self._write_graph("PUT", branch, graph_iri, if_match, data, content_type)
+
+    def post_graph(
+        self,
+        branch: str,
+        graph_iri: str,
+        data: str | bytes,
+        if_match: str,
+        content_type: str = TURTLE,
+    ) -> str:
+        """Merge triples into a named graph. Returns the new ETag, unquoted."""
+        return self._write_graph("POST", branch, graph_iri, if_match, data, content_type)
+
+    def delete_graph(self, branch: str, graph_iri: str, if_match: str) -> str:
+        """Delete a named graph. Returns the new ETag, unquoted."""
+        return self._write_graph("DELETE", branch, graph_iri, if_match)
+
+    def _write_graph(
+        self,
+        method: str,
+        branch: str,
+        graph_iri: str,
+        if_match: str,
+        data: str | bytes | None = None,
+        content_type: str | None = None,
+    ) -> str:
+        headers = {"If-Match": if_match if if_match == "*" else f'"{if_match}"'}
+        if content_type is not None:
+            headers["Content-Type"] = content_type
+        resp = self._request(
+            method,
+            f"/branches/{branch}/graphs",
+            params={"graph": graph_iri},
+            headers=headers,
+            content=data.encode() if isinstance(data, str) else data,
+        )
+        return _unquote_etag(resp.headers.get("ETag"))
+
+    # --- Branches ---
+
+    def list_branches(self) -> list[dict]:
+        """List branches. Rows carry name, parent, head_txn, created_by, timestamps."""
+        return self._request("GET", "/branches").json().get("branches", [])
+
+    def create_branch(self, name: str, parent: str | None = None) -> None:
+        """Create a branch. Server defaults the parent to "main"."""
+        self._request("PUT", f"/branches/{name}", params={"parent": parent} if parent else None)
+
+    def delete_branch(self, name: str) -> None:
+        """Delete a branch."""
+        self._request("DELETE", f"/branches/{name}")
+
+    # --- Tags ---
+
+    def list_tags(self) -> list[dict]:
+        """List tags. Rows carry name, branch, at_txn."""
+        return self._request("GET", "/tags").json().get("tags", [])
+
+    def create_tag(self, name: str, branch: str, at_txn: int | None = None) -> dict:
+        """Tag a branch at a txn (default: the branch's current head)."""
+        body: dict = {"branch": branch}
+        if at_txn is not None:
+            body["at_txn"] = at_txn
+        return self._request("PUT", f"/tags/{name}", json=body).json()
+
+    def delete_tag(self, name: str) -> None:
+        """Delete a tag."""
+        self._request("DELETE", f"/tags/{name}")
+
+    # --- Concept maps ---
+
+    def allocate_conceptmap(self) -> dict:
+        """Allocate a concept map. Returns {"conceptmap": ..., "graph_iri": ...}."""
+        return self._request("POST", "/conceptmaps/").json()
+
+    # --- SPARQL ---
+
+    def sparql(self, query: str, accept: str = "application/sparql-results+json") -> httpx.Response:
+        """Run a SPARQL query. Pass-through: the raw response is returned."""
+        return self._request(
+            "POST",
+            "/sparql",
+            headers={"Content-Type": "application/sparql-query", "Accept": accept},
+            content=query.encode(),
+        )
+
+    # --- HTTP ---
+
+    def _bearer(self, refresh: bool = False) -> str | None:
+        if refresh or not self._token_loaded:
+            self._token = self._token_provider() if self._token_provider else None
+            self._token_loaded = True
+        return self._token
+
+    def _request(self, method: str, path: str, **kwargs) -> httpx.Response:
+        resp = self._send(method, path, self._bearer(), **kwargs)
+        if resp.status_code == 401 and self._token_provider is not None:
+            # Spec 180 §5: refresh once, then give up.
+            resp = self._send(method, path, self._bearer(refresh=True), **kwargs)
+        if resp.status_code >= 400:
+            exc = self._error(resp, method, path)
+            if exc is not None:
+                raise exc
+            resp.raise_for_status()  # statuses outside the spec table (400, 409, ...)
+        return resp
+
+    def _send(self, method: str, path: str, token: str | None, **kwargs) -> httpx.Response:
+        headers = dict(kwargs.pop("headers", None) or {})
+        if token:
+            headers["Authorization"] = f"Bearer {token}"
+        return httpx.request(
+            method,
+            f"{self._base_url}{path}",
+            headers=headers,
+            timeout=self._timeout,
+            **kwargs,
+        )
+
+    def _error(self, resp: httpx.Response, method: str, path: str) -> Exception | None:
+        """Map (status, route) to a typed exception; None for statuses not in spec §5."""
+        status = resp.status_code
+        if status == 401:
+            return AuthError()
+        if status == 403:
+            return PermissionError(_required_role(method, path), self._client_id)
+        if status == 404:
+            return NotFound(f"{method} {path} not found")
+        if status == 412:
+            return ConflictError(_unquote_etag(resp.headers.get("ETag")))
+        if status == 413:
+            return TooLarge()
+        if status == 415:
+            return UnsupportedMedia()
+        if status == 503:
+            return Unavailable()
+        return None
+
+
+def get_graph_client(env_name: str | None = None) -> GraphClient:
+    """Create a GraphClient from the current settings."""
+    settings = get_settings()
+    env = env_name or current_environment_name()
+
+    def token_provider() -> str | None:
+        from sunstone_data.auth.client_creds import resolve_access_token
+
+        with httpx.Client() as client:
+            return resolve_access_token(settings, env, client)
+
+    return GraphClient(
+        settings.graph_url,
+        token_provider=token_provider,
+        client_id=settings.client_id or None,
+    )