atomicmemory 1.0.0__py3-none-any.whl

atomicmemory/storage/_mapping.py

@@ -0,0 +1,305 @@
+"""Wire mappers for backend artifact-storage responses.
+
+Core emits snake_case JSON and storage HEAD headers. This module is the
+single translation seam into Python SDK models, with closed-enum
+validation before any public model is returned.
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Iterable
+from typing import Any, TypeVar
+
+import httpx
+from pydantic import BaseModel
+from pydantic import ValidationError as PydanticValidationError
+
+from atomicmemory.storage.errors import (
+    ArtifactInUseError,
+    ArtifactNotFoundError,
+    FilecoinDirectStorageNotSupportedError,
+    PointerContentNotManagedError,
+    StorageClientError,
+    UnsupportedCapabilityError,
+)
+from atomicmemory.storage.types import (
+    ArtifactHead,
+    DeleteArtifactResult,
+    StorageArtifactStatus,
+    StoredArtifact,
+    VerificationResult,
+)
+
+ModelT = TypeVar("ModelT", bound=BaseModel)
+
+STORAGE_MODES = ("pointer", "managed")
+STORAGE_STATUSES: tuple[StorageArtifactStatus, ...] = (
+    "stored",
+    "pending",
+    "available",
+    "unavailable",
+    "deleting",
+    "deleted",
+    "delete_failed",
+    "failed",
+)
+CONTENT_ENCODINGS = ("identity", "aes_gcm")
+
+
+def map_stored_artifact(raw: Any) -> StoredArtifact:
+    """Translate and validate a snake_case artifact response."""
+    body = _require_object(raw, "StoredArtifact")
+    artifact_id = _require_wire_string(body, "artifact_id")
+    provider = _require_wire_string(body, "provider")
+    mode = _require_wire_enum(body, "mode", STORAGE_MODES)
+    status = _require_wire_enum(body, "status", STORAGE_STATUSES)
+    content_encoding = _require_wire_enum(body, "content_encoding", CONTENT_ENCODINGS)
+    artifact = {
+        "artifactId": artifact_id,
+        "provider": provider,
+        "mode": mode,
+        "uri": _optional_string(body, "uri"),
+        "status": status,
+        "sizeBytes": _optional_non_negative_int(body, "size_bytes"),
+        "contentType": _optional_string(body, "content_type"),
+        "contentEncoding": content_encoding,
+        "identifiers": _string_dict(body, "identifiers"),
+        "lifecycle": _object_or_empty(body, "lifecycle"),
+        "metadata": _metadata_dict(body, "metadata"),
+        "createdAt": _require_wire_string(body, "created_at"),
+        "updatedAt": _require_wire_string(body, "updated_at"),
+    }
+    content_hash = _optional_string(body, "content_hash")
+    if content_hash is not None:
+        artifact["contentHash"] = content_hash
+    _copy_optional_object(artifact, "providerDetails", body, "provider_details")
+    _copy_optional_object(artifact, "replication", body, "replication")
+    _copy_optional_object(artifact, "verification", body, "verification")
+    _copy_optional_object(artifact, "retrieval", body, "retrieval")
+    return validate_response_model(StoredArtifact, artifact, "StoredArtifact")
+
+
+def map_head_headers(headers: httpx.Headers, fallback_id: str) -> ArtifactHead:
+    """Project storage HEAD response headers into an ``ArtifactHead``."""
+    mode = _validate_header_enum(headers, "x-atomicmemory-storage-mode", STORAGE_MODES)
+    status = _validate_header_enum(headers, "x-atomicmemory-storage-status", STORAGE_STATUSES)
+    return validate_response_model(
+        ArtifactHead,
+        {
+            "artifactId": headers.get("x-atomicmemory-artifact-id") or fallback_id,
+            "provider": headers.get("x-atomicmemory-provider") or "",
+            "mode": mode,
+            "status": status,
+            "sizeBytes": _parse_size(headers.get("content-length")),
+            "contentType": headers.get("content-type"),
+        },
+        "ArtifactHead",
+    )
+
+
+def map_delete_result(raw: Any) -> DeleteArtifactResult:
+    """Translate and validate a snake_case delete response."""
+    body = _require_object(raw, "DeleteArtifactResult")
+    out: dict[str, Any] = {
+        "artifactId": _require_wire_string(body, "artifact_id"),
+        "status": _require_wire_enum(body, "status", STORAGE_STATUSES),
+    }
+    if isinstance(body.get("cascaded_document_ids"), list):
+        out["cascadedDocumentIds"] = [str(v) for v in body["cascaded_document_ids"]]
+    return validate_response_model(DeleteArtifactResult, out, "DeleteArtifactResult")
+
+
+def map_verify_result(raw: Any) -> VerificationResult:
+    """Map verification response variants to a single Python model."""
+    body = raw if isinstance(raw, dict) else {}
+    if body.get("kind") == "verified":
+        details = body.get("details") if isinstance(body.get("details"), dict) else {}
+        return validate_response_model(
+            VerificationResult, {"kind": "verified", "details": details}, "VerificationResult"
+        )
+    if body.get("kind") == "failed":
+        failed = {"kind": "failed", "reason": str(body.get("reason", "unknown failure"))}
+        return validate_response_model(VerificationResult, failed, "VerificationResult")
+    unsupported = {"kind": "unsupported", "reason": str(body.get("reason", "unsupported"))}
+    return validate_response_model(VerificationResult, unsupported, "VerificationResult")
+
+
+def validate_response_model(model: type[ModelT], data: dict[str, Any], type_name: str) -> ModelT:
+    """Validate a response model without leaking Pydantic errors."""
+    try:
+        return model.model_validate(data)
+    except PydanticValidationError as exc:
+        raise StorageClientError(
+            f"{type_name}: server response failed validation",
+            error_code="invalid_storage_response",
+            status=200,
+            body_text="",
+            context={"type": type_name, "errors": exc.errors()},
+        ) from exc
+
+
+def raise_for_storage_response(response: httpx.Response, artifact_id: str | None = None) -> None:
+    """Raise the typed storage error for a non-success response."""
+    body_text = response.text
+    envelope = _parse_error_envelope(body_text)
+    code = envelope.get("error_code")
+    message = str(envelope.get("error") or f"request failed with status {response.status_code}")
+    known_id = artifact_id or ""
+    if code == "artifact_in_use":
+        count = envelope.get("referenced_by_document_count")
+        raise ArtifactInUseError(
+            artifact_id=known_id,
+            referenced_by_document_count=count if isinstance(count, int) else 0,
+            body_text=body_text,
+        )
+    if code == "pointer_content_not_managed":
+        uri = envelope.get("uri")
+        raise PointerContentNotManagedError(
+            artifact_id=known_id,
+            uri=uri if isinstance(uri, str) else "",
+            body_text=body_text,
+        )
+    if code == "filecoin_direct_storage_not_yet_supported":
+        raise FilecoinDirectStorageNotSupportedError(body_text=body_text)
+    if code == "artifact_not_found" or response.status_code == 404:
+        raise ArtifactNotFoundError(artifact_id=known_id, body_text=body_text)
+    if code == "unsupported_capability":
+        raise UnsupportedCapabilityError(capability="unknown", message=message, body_text=body_text)
+    raise StorageClientError(
+        message,
+        error_code=code if isinstance(code, str) else f"http_{response.status_code}",
+        status=response.status_code,
+        body_text=body_text,
+    )
+
+
+def _require_object(raw: Any, type_name: str) -> dict[str, Any]:
+    if not isinstance(raw, dict):
+        raise StorageClientError(
+            f"{type_name}: server response is not a JSON object",
+            error_code="invalid_storage_response",
+            status=200,
+            body_text="",
+        )
+    return raw
+
+
+def _require_wire_string(raw: dict[str, Any], field: str) -> str:
+    value = raw.get(field)
+    if not isinstance(value, str) or value == "":
+        raise StorageClientError(
+            f"mapStoredArtifact: server response is missing required `{field}`",
+            error_code="invalid_storage_response",
+            status=200,
+            body_text="",
+        )
+    return str(value)
+
+
+def _require_wire_enum(raw: dict[str, Any], field: str, allowed: Iterable[str]) -> str:
+    value = raw.get(field)
+    allowed_values = tuple(allowed)
+    if not isinstance(value, str) or value not in allowed_values:
+        raise StorageClientError(
+            f"mapStoredArtifact: `{field}` must be one of {', '.join(allowed_values)}",
+            error_code="invalid_storage_response",
+            status=200,
+            body_text="",
+        )
+    return value
+
+
+def _validate_header_enum(headers: httpx.Headers, name: str, allowed: Iterable[str]) -> str:
+    value = headers.get(name)
+    allowed_values = tuple(allowed)
+    if not isinstance(value, str) or value not in allowed_values:
+        raise StorageClientError(
+            f"head(): server returned an unrecognized {name} value",
+            error_code="invalid_head_response",
+            status=200,
+            body_text="",
+        )
+    return value
+
+
+def _parse_size(value: str | None) -> int | None:
+    if value is None:
+        return None
+    try:
+        parsed = int(value)
+    except ValueError:
+        return None
+    return parsed if parsed >= 0 else None
+
+
+def _optional_string(body: dict[str, Any], field: str) -> str | None:
+    if field not in body or body[field] is None:
+        return None
+    value = body[field]
+    if isinstance(value, str):
+        return value
+    raise _invalid_response(f"mapStoredArtifact: `{field}` must be a string or null")
+
+
+def _optional_non_negative_int(body: dict[str, Any], field: str) -> int | None:
+    if field not in body or body[field] is None:
+        return None
+    value = body[field]
+    if isinstance(value, int) and not isinstance(value, bool) and value >= 0:
+        return value
+    raise _invalid_response(f"mapStoredArtifact: `{field}` must be a non-negative integer or null")
+
+
+def _string_dict(body: dict[str, Any], field: str) -> dict[str, str]:
+    if field not in body or body[field] is None:
+        return {}
+    value = body[field]
+    if not isinstance(value, dict):
+        raise _invalid_response(f"mapStoredArtifact: `{field}` must be an object")
+    if not all(isinstance(v, str) for v in value.values()):
+        raise _invalid_response(f"mapStoredArtifact: `{field}` values must be strings")
+    return {str(k): v for k, v in value.items()}
+
+
+def _object_or_empty(body: dict[str, Any], field: str) -> dict[str, Any]:
+    if field not in body or body[field] is None:
+        return {}
+    value = body[field]
+    if not isinstance(value, dict):
+        raise _invalid_response(f"mapStoredArtifact: `{field}` must be an object")
+    return value
+
+
+def _metadata_dict(body: dict[str, Any], field: str) -> dict[str, str | int | float | bool]:
+    if field not in body or body[field] is None:
+        return {}
+    value = body[field]
+    if not isinstance(value, dict):
+        raise _invalid_response(f"mapStoredArtifact: `{field}` must be an object")
+    if not all(isinstance(v, str | int | float | bool) for v in value.values()):
+        raise _invalid_response(f"mapStoredArtifact: `{field}` values must be scalar")
+    return {str(k): v for k, v in value.items() if isinstance(v, str | int | float | bool)}
+
+
+def _copy_optional_object(out: dict[str, Any], out_key: str, body: dict[str, Any], wire_key: str) -> None:
+    if wire_key not in body or body[wire_key] is None:
+        return
+    value = body[wire_key]
+    if not isinstance(value, dict):
+        raise _invalid_response(f"mapStoredArtifact: `{wire_key}` must be an object")
+    out[out_key] = value
+
+
+def _invalid_response(message: str) -> StorageClientError:
+    return StorageClientError(message, error_code="invalid_storage_response", status=200, body_text="")
+
+
+def _parse_error_envelope(body_text: str) -> dict[str, Any]:
+    if body_text == "":
+        return {}
+    try:
+        parsed = json.loads(body_text)
+    except json.JSONDecodeError:
+        return {}
+    return parsed if isinstance(parsed, dict) else {}

atomicmemory/storage/async_client.py

@@ -0,0 +1,208 @@
+"""Async client for backend artifact storage.
+
+The async surface mirrors :mod:`atomicmemory.storage.client` while
+using ``httpx.AsyncClient`` for every storage API request.
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+from types import TracebackType
+from typing import Any
+
+import httpx
+
+from atomicmemory.storage._mapping import (
+    map_delete_result,
+    map_head_headers,
+    map_stored_artifact,
+    map_verify_result,
+    raise_for_storage_response,
+    validate_response_model,
+)
+from atomicmemory.storage.client import (
+    METADATA_HEADER,
+    _coerce_config,
+    _coerce_delete_options,
+    _coerce_managed_body,
+    _coerce_put_input,
+    _coerce_verify_options,
+    _encode_metadata_header,
+    _json_response,
+    _managed_path,
+    _network_error,
+    _pointer_payload,
+    _quote_id,
+    _require_artifact_id,
+)
+from atomicmemory.storage.types import (
+    ArtifactHead,
+    ArtifactRef,
+    DeleteArtifactOptions,
+    DeleteArtifactResult,
+    PutArtifactInput,
+    PutManagedInput,
+    PutPointerInput,
+    StorageCapabilities,
+    StorageClientConfig,
+    StoredArtifact,
+    VerificationResult,
+    VerifyArtifactOptions,
+)
+
+
+class AsyncStorageClient:
+    """Async entry point for the direct artifact-storage API."""
+
+    def __init__(self, config: StorageClientConfig | dict[str, Any]) -> None:
+        self._config = _coerce_config(config)
+        self._api_url = self._config.api_url.rstrip("/")
+        self._client = httpx.AsyncClient(timeout=self._config.timeout_seconds)
+
+    async def capabilities(self) -> StorageCapabilities:
+        response = await self._request("GET", "/v1/storage/capabilities")
+        return validate_response_model(StorageCapabilities, _json_response(response), "StorageCapabilities")
+
+    async def put(self, input: PutArtifactInput | dict[str, Any]) -> StoredArtifact:
+        value = _coerce_put_input(input)
+        if isinstance(value, PutPointerInput):
+            return await self._put_pointer(value)
+        return await self._put_managed(value)
+
+    async def get(self, ref: ArtifactRef | dict[str, Any]) -> StoredArtifact:
+        artifact_id = _require_artifact_id(ref)
+        response = await self._request(
+            "GET",
+            f"/v1/storage/artifacts/{_quote_id(artifact_id)}",
+            artifact_id=artifact_id,
+        )
+        return map_stored_artifact(_json_response(response))
+
+    async def get_content(self, ref: ArtifactRef | dict[str, Any]) -> httpx.Response:
+        """Return a fully buffered content response for small artifacts."""
+        artifact_id = _require_artifact_id(ref)
+        path = f"/v1/storage/artifacts/{_quote_id(artifact_id)}/content"
+        return await self._request("GET", path, artifact_id=artifact_id)
+
+    @asynccontextmanager
+    async def stream_content(self, ref: ArtifactRef | dict[str, Any]) -> AsyncIterator[httpx.Response]:
+        """Stream artifact bytes without loading the whole response into memory."""
+        artifact_id = _require_artifact_id(ref)
+        path = f"/v1/storage/artifacts/{_quote_id(artifact_id)}/content"
+        try:
+            async with self._client.stream("GET", f"{self._api_url}{path}", headers=self._headers(None)) as response:
+                if response.is_success:
+                    yield response
+                    return
+                await response.aread()
+                raise_for_storage_response(response, artifact_id)
+        except httpx.RequestError as exc:
+            raise _network_error("GET", path, exc) from exc
+        raise AssertionError("unreachable")
+
+    async def head(self, ref: ArtifactRef | dict[str, Any]) -> ArtifactHead:
+        artifact_id = _require_artifact_id(ref)
+        response = await self._request(
+            "HEAD",
+            f"/v1/storage/artifacts/{_quote_id(artifact_id)}",
+            artifact_id=artifact_id,
+        )
+        return map_head_headers(response.headers, artifact_id)
+
+    async def delete(
+        self,
+        ref: ArtifactRef | dict[str, Any],
+        options: DeleteArtifactOptions | dict[str, Any] | None = None,
+    ) -> DeleteArtifactResult:
+        artifact_id = _require_artifact_id(ref)
+        path = f"/v1/storage/artifacts/{_quote_id(artifact_id)}"
+        policy = _coerce_delete_options(options).policy
+        if policy:
+            path = f"{path}?policy={policy}"
+        response = await self._request("DELETE", path, artifact_id=artifact_id)
+        return map_delete_result(_json_response(response))
+
+    async def verify(
+        self,
+        ref: ArtifactRef | dict[str, Any],
+        options: VerifyArtifactOptions | dict[str, Any] | None = None,
+    ) -> VerificationResult:
+        _coerce_verify_options(options)
+        artifact_id = _require_artifact_id(ref)
+        path = f"/v1/storage/artifacts/{_quote_id(artifact_id)}/verify"
+        response = await self._request("POST", path, artifact_id=artifact_id)
+        return map_verify_result(_json_response(response))
+
+    async def close(self) -> None:
+        await self._client.aclose()
+
+    async def __aenter__(self) -> AsyncStorageClient:
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> None:
+        await self.close()
+
+    async def _put_pointer(self, input: PutPointerInput) -> StoredArtifact:
+        response = await self._request(
+            "POST",
+            "/v1/storage/artifacts",
+            headers={"Content-Type": "application/json"},
+            content=_json_bytes(_pointer_payload(input)),
+        )
+        return map_stored_artifact(_json_response(response))
+
+    async def _put_managed(self, input: PutManagedInput) -> StoredArtifact:
+        body = _coerce_managed_body(input.body)
+        headers = {"Content-Type": input.content_type, "Content-Length": str(len(body))}
+        if input.metadata is not None:
+            headers[METADATA_HEADER] = _encode_metadata_header(input.metadata)
+        response = await self._request(
+            "POST",
+            _managed_path(input.disclose_content_hash),
+            headers=headers,
+            content=body,
+        )
+        return map_stored_artifact(_json_response(response))
+
+    async def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        headers: dict[str, str] | None = None,
+        content: bytes | None = None,
+        artifact_id: str | None = None,
+    ) -> httpx.Response:
+        try:
+            response = await self._client.request(
+                method,
+                f"{self._api_url}{path}",
+                headers=self._headers(headers),
+                content=content,
+            )
+        except httpx.RequestError as exc:
+            raise _network_error(method, path, exc) from exc
+        if response.is_success:
+            return response
+        raise_for_storage_response(response, artifact_id)
+        raise AssertionError("unreachable")
+
+    def _headers(self, extra: dict[str, str] | None) -> dict[str, str]:
+        headers = {
+            "Authorization": f"Bearer {self._config.api_key}",
+            "X-AtomicMemory-User-Id": self._config.user_id,
+        }
+        if extra:
+            headers.update(extra)
+        return headers
+
+
+def _json_bytes(payload: dict[str, Any]) -> bytes:
+    return json.dumps(payload, separators=(",", ":")).encode()