cairnmark 0.1.0__py3-none-any.whl

cairnmark/__init__.py

@@ -0,0 +1,57 @@
+"""Official Python client for the CairnMark file service.
+
+Synchronous::
+
+    from cairnmark import CairnMark
+
+    with CairnMark("http://localhost:8080") as cm:
+        f = cm.upload(b"hello", filename="hello.txt", metadata={"env": "demo"},
+                      idempotency_key="auto")
+        cm.download_to_file(f.id, "hello-copy.txt")   # checksum-verified
+
+Asynchronous::
+
+    from cairnmark import AsyncCairnMark
+
+    async with AsyncCairnMark("http://localhost:8080") as cm:
+        f = await cm.upload(b"hello", filename="hello.txt")
+        async for file in cm.iter_files(tags={"env": "demo"}):
+            ...
+"""
+
+from ._async_client import AsyncCairnMark, AsyncDownload
+from ._client import CairnMark, Download
+from .errors import (
+    APIError,
+    CairnMarkError,
+    ChecksumMismatchError,
+    IdempotencyConflictError,
+    IdempotencyGoneError,
+    InvalidRequestError,
+    NotFoundError,
+    RangeNotSatisfiableError,
+    ServerError,
+    TooLargeError,
+)
+from .models import File, ListPage
+from .version import __version__
+
+__all__ = [
+    "APIError",
+    "AsyncCairnMark",
+    "AsyncDownload",
+    "CairnMark",
+    "CairnMarkError",
+    "ChecksumMismatchError",
+    "Download",
+    "File",
+    "IdempotencyConflictError",
+    "IdempotencyGoneError",
+    "InvalidRequestError",
+    "ListPage",
+    "NotFoundError",
+    "RangeNotSatisfiableError",
+    "ServerError",
+    "TooLargeError",
+    "__version__",
+]

cairnmark/_async_client.py

@@ -0,0 +1,375 @@
+"""The asynchronous CairnMark client — the async twin of ``_client.py``.
+
+The two are kept in lockstep by hand; the surface is small enough that a
+codegen step would cost more than it saves. Change one, change both.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import json
+import os
+from typing import Any, AsyncIterator, Callable, Iterator, cast
+from urllib.parse import quote
+
+import httpx
+
+from ._http import (
+    DEFAULT_RETRIES,
+    DEFAULT_TIMEOUT,
+    averify_bytes,
+    backoff_delay,
+    error_from_response,
+    list_params,
+    range_header,
+    resolve_idempotency_key,
+    retry_delay,
+    rewinder,
+    unexpected_status,
+    upload_params_headers,
+)
+from .errors import CairnMarkError, ServerError
+from .models import File, ListPage
+from .version import __version__
+
+
+class AsyncDownload:
+    """An open async download stream plus the file's metadata record.
+
+    Use as an async context manager (or call ``aclose()``). With verification
+    on, ChecksumMismatchError is raised as the last chunk is consumed.
+    """
+
+    def __init__(self, response: httpx.Response, file: File, verify: bool) -> None:
+        self._response = response
+        self._verify = verify
+        self.file = file
+
+    def aiter_bytes(self, chunk_size: int | None = None) -> AsyncIterator[bytes]:
+        chunks = self._response.aiter_bytes(chunk_size)
+        if self._verify and self.file.checksum_sha256:
+            return averify_bytes(chunks, self.file.checksum_sha256)
+        return chunks
+
+    async def aread(self) -> bytes:
+        """Consume the whole stream (still verified) into memory."""
+        parts = [chunk async for chunk in self.aiter_bytes()]
+        return b"".join(parts)
+
+    async def aclose(self) -> None:
+        await self._response.aclose()
+
+    async def __aenter__(self) -> AsyncDownload:
+        return self
+
+    async def __aexit__(self, *exc: object) -> None:
+        await self.aclose()
+
+
+class AsyncCairnMark:
+    """Asynchronous client for one CairnMark server. See CairnMark for the
+    full semantics — the two expose the same operations."""
+
+    def __init__(
+        self,
+        base_url: str,
+        *,
+        headers: dict[str, str] | None = None,
+        timeout: float | httpx.Timeout = DEFAULT_TIMEOUT,
+        retries: int = DEFAULT_RETRIES,
+        user_agent: str | None = None,
+        transport: httpx.AsyncBaseTransport | None = None,
+    ) -> None:
+        self._retries = retries
+        merged = dict(headers or {})
+        merged["User-Agent"] = user_agent or f"cairnmark-python/{__version__}"
+        self._http = httpx.AsyncClient(
+            base_url=base_url.rstrip("/"),
+            headers=merged,
+            timeout=timeout,
+            transport=transport,
+            follow_redirects=False,
+        )
+
+    # -- core request loop -------------------------------------------------
+
+    async def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: dict[str, str] | None = None,
+        headers: dict[str, str] | None = None,
+        content: bytes | None = None,
+        follow_redirects: bool = False,
+        expect: int = 200,
+    ) -> httpx.Response:
+        attempt = 0
+        while True:
+            try:
+                resp = await self._http.request(
+                    method,
+                    path,
+                    params=params,
+                    headers=headers,
+                    content=content,
+                    follow_redirects=follow_redirects,
+                )
+            except httpx.TransportError:
+                if attempt < self._retries:
+                    await asyncio.sleep(backoff_delay(attempt))
+                    attempt += 1
+                    continue
+                raise
+            if resp.status_code < 400:
+                if resp.status_code != expect:
+                    raise unexpected_status(resp, expect)
+                return resp
+            err = error_from_response(resp)
+            if isinstance(err, ServerError) and attempt < self._retries:
+                await asyncio.sleep(backoff_delay(attempt))
+                attempt += 1
+                continue
+            raise err
+
+    # -- uploads -------------------------------------------------------------
+
+    async def upload(
+        self,
+        content: Any,
+        *,
+        filename: str | None = None,
+        content_type: str | None = None,
+        size: int | None = None,
+        metadata: dict[str, Any] | None = None,
+        idempotency_key: str | None = None,
+    ) -> File:
+        """Stream ``content`` up; see CairnMark.upload for the semantics."""
+        key = resolve_idempotency_key(idempotency_key)
+        if isinstance(content, (bytearray, memoryview)):
+            content = bytes(content)  # httpx's typed surface takes bytes
+        if isinstance(content, bytes):
+            size = None  # httpx sets Content-Length for in-memory bodies
+        params, headers = upload_params_headers(filename, content_type, metadata, key, size)
+        rewind = rewinder(content)
+        retryable = key is not None and rewind is not None
+
+        attempt = 0
+        while True:
+            if attempt and rewind is not None:
+                rewind()
+            try:
+                # Wrapped fresh per attempt: a rewound file needs a new stream.
+                resp = await self._http.post(
+                    "/files", params=params, headers=headers, content=_as_async_content(content)
+                )
+            except httpx.TransportError:
+                if retryable and attempt < self._retries:
+                    await asyncio.sleep(backoff_delay(attempt))
+                    attempt += 1
+                    continue
+                raise
+            if resp.status_code == 201:
+                return File.from_json(resp.json())
+            err = error_from_response(resp)
+            if retryable and attempt < self._retries and err.status in (409, *range(500, 600)):
+                await asyncio.sleep(retry_delay(err if err.status == 409 else None, attempt))
+                attempt += 1
+                continue
+            raise err
+
+    async def upload_file(
+        self,
+        path: str | os.PathLike[str],
+        *,
+        filename: str | None = None,
+        content_type: str | None = None,
+        metadata: dict[str, Any] | None = None,
+        idempotency_key: str | None = None,
+    ) -> File:
+        """Upload the file at ``path``; name and size are inferred."""
+        with open(path, "rb") as f:
+            return await self.upload(
+                f,
+                filename=filename or os.path.basename(os.fspath(path)),
+                content_type=content_type,
+                size=os.fstat(f.fileno()).st_size,
+                metadata=metadata,
+                idempotency_key=idempotency_key,
+            )
+
+    # -- downloads -----------------------------------------------------------
+
+    async def download(
+        self,
+        file_id: str,
+        *,
+        verify: bool = False,
+        offset: int | None = None,
+        length: int | None = None,
+    ) -> AsyncDownload:
+        """Open the file's content; see CairnMark.download for the semantics."""
+        ranged = offset is not None or length is not None
+        if verify and ranged:
+            raise ValueError("verify is incompatible with a range download")
+
+        file = await self.get_metadata(file_id)
+        if verify and not file.checksum_sha256:
+            raise CairnMarkError(f"file {file_id} has no stored checksum to verify against")
+
+        headers = {"Range": range_header(offset or 0, length)} if ranged else None
+        expect = 206 if ranged else 200
+        attempt = 0
+        while True:
+            request = self._http.build_request("GET", _file_path(file_id), headers=headers)
+            try:
+                resp = await self._http.send(request, stream=True, follow_redirects=True)
+            except httpx.TransportError:
+                if attempt < self._retries:
+                    await asyncio.sleep(backoff_delay(attempt))
+                    attempt += 1
+                    continue
+                raise
+            if resp.status_code == expect:
+                return AsyncDownload(resp, file, verify)
+            await resp.aread()
+            await resp.aclose()
+            err = error_from_response(resp)
+            if isinstance(err, ServerError) and attempt < self._retries:
+                await asyncio.sleep(backoff_delay(attempt))
+                attempt += 1
+                continue
+            raise err
+
+    async def download_to_file(
+        self, file_id: str, path: str | os.PathLike[str], *, verify: bool = True
+    ) -> File:
+        """Download into ``path``, checksum-verified; removed on failure."""
+        async with await self.download(file_id, verify=verify) as dl:
+            try:
+                with open(path, "wb") as out:
+                    async for chunk in dl.aiter_bytes():
+                        out.write(chunk)
+            except BaseException:
+                with contextlib.suppress(OSError):
+                    os.remove(path)
+                raise
+        return dl.file
+
+    async def presign_url(self, file_id: str) -> str:
+        """The presigned object-store URL, without following it."""
+        resp = await self._request("GET", _file_path(file_id), expect=302)
+        location = resp.headers.get("location")
+        if not location:
+            raise CairnMarkError("presign response has no Location header")
+        return location
+
+    # -- metadata ------------------------------------------------------------
+
+    async def get_metadata(self, file_id: str) -> File:
+        """Fetch the metadata record for ``file_id``."""
+        resp = await self._request("GET", _file_path(file_id) + "/metadata")
+        return File.from_json(resp.json())
+
+    async def update_metadata(
+        self, file_id: str, tags: dict[str, Any], *, mode: str = "merge"
+    ) -> File:
+        """Merge (default) or replace (``mode="replace"``) the file's tags."""
+        if mode not in ("merge", "replace"):
+            raise ValueError(f'mode must be "merge" or "replace", not {mode!r}')
+        params = {"mode": "replace"} if mode == "replace" else None
+        resp = await self._request(
+            "PATCH",
+            _file_path(file_id) + "/metadata",
+            params=params,
+            headers={"Content-Type": "application/json"},
+            content=json.dumps(tags).encode(),
+        )
+        return File.from_json(resp.json())
+
+    async def delete(self, file_id: str) -> None:
+        """Soft-delete ``file_id``; the stored object is purged asynchronously."""
+        await self._request("DELETE", _file_path(file_id), expect=204)
+
+    # -- listing ---------------------------------------------------------------
+
+    async def list(
+        self,
+        *,
+        content_type: str | None = None,
+        tags: dict[str, str] | None = None,
+        limit: int | None = None,
+        cursor: str | None = None,
+    ) -> ListPage:
+        """One page of files matching the filter, newest first."""
+        resp = await self._request(
+            "GET", "/files", params=list_params(content_type, tags, limit, cursor)
+        )
+        return ListPage.from_json(resp.json())
+
+    async def iter_files(
+        self,
+        *,
+        content_type: str | None = None,
+        tags: dict[str, str] | None = None,
+        limit: int | None = None,
+    ) -> AsyncIterator[File]:
+        """Every file matching the filter, fetching pages lazily."""
+        cursor: str | None = None
+        while True:
+            page = await self.list(content_type=content_type, tags=tags, limit=limit, cursor=cursor)
+            for file in page.files:
+                yield file
+            if not page.next_cursor:
+                return
+            cursor = page.next_cursor
+
+    # -- probes / lifecycle ------------------------------------------------------
+
+    async def health(self) -> None:
+        """Raise unless the server answers 200 on /healthz (liveness)."""
+        await self._request("GET", "/healthz")
+
+    async def ready(self) -> None:
+        """Raise unless /readyz says storage and database are reachable."""
+        await self._request("GET", "/readyz")
+
+    async def aclose(self) -> None:
+        await self._http.aclose()
+
+    async def __aenter__(self) -> AsyncCairnMark:
+        return self
+
+    async def __aexit__(self, *exc: object) -> None:
+        await self.aclose()
+
+
+def _file_path(file_id: str) -> str:
+    return "/files/" + quote(file_id, safe="")
+
+
+def _as_async_content(content: Any) -> Any:
+    """Make ``content`` acceptable to httpx.AsyncClient, which refuses sync
+    streams. In-memory bytes and async iterables pass through; sync file-likes
+    and iterators are wrapped into async generators (their reads still block —
+    fine for files, use an async iterable for anything slower)."""
+    if isinstance(content, (bytes, bytearray, memoryview)) or hasattr(content, "__aiter__"):
+        return content
+    read = cast("Callable[[int], bytes] | None", getattr(content, "read", None))
+    if callable(read):
+
+        async def from_file() -> AsyncIterator[bytes]:
+            while chunk := read(65536):
+                yield chunk
+
+        return from_file()
+    if hasattr(content, "__iter__"):
+        iterator = cast("Iterator[bytes]", iter(content))
+
+        async def from_iter() -> AsyncIterator[bytes]:
+            for chunk in iterator:
+                yield chunk
+
+        return from_iter()
+    return content

cairnmark/_client.py

@@ -0,0 +1,368 @@
+"""The synchronous CairnMark client."""
+
+from __future__ import annotations
+
+import contextlib
+import json
+import os
+import time
+from typing import Any, Iterator
+from urllib.parse import quote
+
+import httpx
+
+from ._http import (
+    DEFAULT_RETRIES,
+    DEFAULT_TIMEOUT,
+    backoff_delay,
+    error_from_response,
+    list_params,
+    range_header,
+    resolve_idempotency_key,
+    retry_delay,
+    rewinder,
+    unexpected_status,
+    upload_params_headers,
+    verify_bytes,
+)
+from .errors import CairnMarkError, ServerError
+from .models import File, ListPage
+from .version import __version__
+
+
+class Download:
+    """An open download stream plus the file's metadata record.
+
+    Use as a context manager (or call ``close()``). With verification on,
+    ChecksumMismatchError is raised as the last chunk is consumed.
+    """
+
+    def __init__(self, response: httpx.Response, file: File, verify: bool) -> None:
+        self._response = response
+        self._verify = verify
+        self.file = file
+
+    def iter_bytes(self, chunk_size: int | None = None) -> Iterator[bytes]:
+        chunks = self._response.iter_bytes(chunk_size)
+        if self._verify and self.file.checksum_sha256:
+            return verify_bytes(chunks, self.file.checksum_sha256)
+        return chunks
+
+    def read(self) -> bytes:
+        """Consume the whole stream (still verified) into memory."""
+        return b"".join(self.iter_bytes())
+
+    def close(self) -> None:
+        self._response.close()
+
+    def __enter__(self) -> Download:
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
+
+
+class CairnMark:
+    """Synchronous client for one CairnMark server.
+
+    The server has no auth — put it behind your gateway and inject
+    credentials via ``headers``. ``timeout`` is httpx's per-operation timeout
+    (connect / single read), so it does not cut off large streams.
+    """
+
+    def __init__(
+        self,
+        base_url: str,
+        *,
+        headers: dict[str, str] | None = None,
+        timeout: float | httpx.Timeout = DEFAULT_TIMEOUT,
+        retries: int = DEFAULT_RETRIES,
+        user_agent: str | None = None,
+        transport: httpx.BaseTransport | None = None,
+    ) -> None:
+        self._retries = retries
+        merged = dict(headers or {})
+        merged["User-Agent"] = user_agent or f"cairnmark-python/{__version__}"
+        self._http = httpx.Client(
+            base_url=base_url.rstrip("/"),
+            headers=merged,
+            timeout=timeout,
+            transport=transport,
+            follow_redirects=False,
+        )
+
+    # -- core request loop -------------------------------------------------
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: dict[str, str] | None = None,
+        headers: dict[str, str] | None = None,
+        content: bytes | None = None,
+        follow_redirects: bool = False,
+        expect: int = 200,
+    ) -> httpx.Response:
+        """One small (non-streaming) call, retried on network errors and 5xx."""
+        attempt = 0
+        while True:
+            try:
+                resp = self._http.request(
+                    method,
+                    path,
+                    params=params,
+                    headers=headers,
+                    content=content,
+                    follow_redirects=follow_redirects,
+                )
+            except httpx.TransportError:
+                if attempt < self._retries:
+                    time.sleep(backoff_delay(attempt))
+                    attempt += 1
+                    continue
+                raise
+            if resp.status_code < 400:
+                if resp.status_code != expect:
+                    raise unexpected_status(resp, expect)
+                return resp
+            err = error_from_response(resp)
+            if isinstance(err, ServerError) and attempt < self._retries:
+                time.sleep(backoff_delay(attempt))
+                attempt += 1
+                continue
+            raise err
+
+    # -- uploads -------------------------------------------------------------
+
+    def upload(
+        self,
+        content: Any,
+        *,
+        filename: str | None = None,
+        content_type: str | None = None,
+        size: int | None = None,
+        metadata: dict[str, Any] | None = None,
+        idempotency_key: str | None = None,
+    ) -> File:
+        """Stream ``content`` (bytes or a binary file-like/iterator) up.
+
+        ``size`` sets Content-Length for file-like bodies whose length you
+        know, letting the server reject oversized uploads up front. Pass
+        ``idempotency_key="auto"`` to get a generated key, which is also what
+        makes retries safe: without a key (or with a body that can't be
+        rewound) a transient failure is raised, never retried, since a resend
+        could duplicate the file.
+        """
+        key = resolve_idempotency_key(idempotency_key)
+        if isinstance(content, (bytearray, memoryview)):
+            content = bytes(content)  # httpx's typed surface takes bytes
+        if isinstance(content, bytes):
+            size = None  # httpx sets Content-Length for in-memory bodies
+        params, headers = upload_params_headers(filename, content_type, metadata, key, size)
+        rewind = rewinder(content)
+        retryable = key is not None and rewind is not None
+
+        attempt = 0
+        while True:
+            if attempt and rewind is not None:
+                rewind()
+            try:
+                resp = self._http.post("/files", params=params, headers=headers, content=content)
+            except httpx.TransportError:
+                if retryable and attempt < self._retries:
+                    time.sleep(backoff_delay(attempt))
+                    attempt += 1
+                    continue
+                raise
+            if resp.status_code == 201:
+                return File.from_json(resp.json())
+            err = error_from_response(resp)
+            if retryable and attempt < self._retries and err.status in (409, *range(500, 600)):
+                time.sleep(retry_delay(err if err.status == 409 else None, attempt))
+                attempt += 1
+                continue
+            raise err
+
+    def upload_file(
+        self,
+        path: str | os.PathLike[str],
+        *,
+        filename: str | None = None,
+        content_type: str | None = None,
+        metadata: dict[str, Any] | None = None,
+        idempotency_key: str | None = None,
+    ) -> File:
+        """Upload the file at ``path``; name and size are inferred."""
+        with open(path, "rb") as f:
+            return self.upload(
+                f,
+                filename=filename or os.path.basename(os.fspath(path)),
+                content_type=content_type,
+                size=os.fstat(f.fileno()).st_size,
+                metadata=metadata,
+                idempotency_key=idempotency_key,
+            )
+
+    # -- downloads -----------------------------------------------------------
+
+    def download(
+        self,
+        file_id: str,
+        *,
+        verify: bool = False,
+        offset: int | None = None,
+        length: int | None = None,
+    ) -> Download:
+        """Open the file's content for reading.
+
+        Full downloads follow the server's 302 to a presigned object-store
+        URL; ``offset``/``length`` request a 206 range through the server.
+        ``verify`` hashes the stream against the stored SHA-256 (incompatible
+        with a range — partial bytes can't match a whole-file hash).
+        """
+        ranged = offset is not None or length is not None
+        if verify and ranged:
+            raise ValueError("verify is incompatible with a range download")
+
+        # The metadata record supplies the stored checksum for verification
+        # and rounds out the result either way.
+        file = self.get_metadata(file_id)
+        if verify and not file.checksum_sha256:
+            raise CairnMarkError(f"file {file_id} has no stored checksum to verify against")
+
+        headers = {"Range": range_header(offset or 0, length)} if ranged else None
+        expect = 206 if ranged else 200
+        attempt = 0
+        while True:
+            request = self._http.build_request("GET", _file_path(file_id), headers=headers)
+            try:
+                resp = self._http.send(request, stream=True, follow_redirects=True)
+            except httpx.TransportError:
+                if attempt < self._retries:
+                    time.sleep(backoff_delay(attempt))
+                    attempt += 1
+                    continue
+                raise
+            if resp.status_code == expect:
+                return Download(resp, file, verify)
+            resp.read()
+            resp.close()
+            err = error_from_response(resp)
+            if isinstance(err, ServerError) and attempt < self._retries:
+                time.sleep(backoff_delay(attempt))
+                attempt += 1
+                continue
+            raise err
+
+    def download_to_file(
+        self, file_id: str, path: str | os.PathLike[str], *, verify: bool = True
+    ) -> File:
+        """Download into ``path`` (created or truncated), checksum-verified.
+
+        On any failure — including a checksum mismatch — the partial file is
+        removed.
+        """
+        with self.download(file_id, verify=verify) as dl:
+            try:
+                with open(path, "wb") as out:
+                    for chunk in dl.iter_bytes():
+                        out.write(chunk)
+            except BaseException:
+                with contextlib.suppress(OSError):
+                    os.remove(path)
+                raise
+        return dl.file
+
+    def presign_url(self, file_id: str) -> str:
+        """The presigned object-store URL, without following it.
+
+        Hand it to a browser or another service; it expires after the
+        server's configured TTL, and its host is only as reachable as the
+        server's CAIRNMARK_S3_PUBLIC_ENDPOINT makes it.
+        """
+        resp = self._request("GET", _file_path(file_id), expect=302)
+        location = resp.headers.get("location")
+        if not location:
+            raise CairnMarkError("presign response has no Location header")
+        return location
+
+    # -- metadata ------------------------------------------------------------
+
+    def get_metadata(self, file_id: str) -> File:
+        """Fetch the metadata record for ``file_id``."""
+        resp = self._request("GET", _file_path(file_id) + "/metadata")
+        return File.from_json(resp.json())
+
+    def update_metadata(self, file_id: str, tags: dict[str, Any], *, mode: str = "merge") -> File:
+        """Merge (default) or replace (``mode="replace"``) the file's tags."""
+        if mode not in ("merge", "replace"):
+            raise ValueError(f'mode must be "merge" or "replace", not {mode!r}')
+        params = {"mode": "replace"} if mode == "replace" else None
+        resp = self._request(
+            "PATCH",
+            _file_path(file_id) + "/metadata",
+            params=params,
+            headers={"Content-Type": "application/json"},
+            content=json.dumps(tags).encode(),
+        )
+        return File.from_json(resp.json())
+
+    def delete(self, file_id: str) -> None:
+        """Soft-delete ``file_id``; the stored object is purged asynchronously."""
+        self._request("DELETE", _file_path(file_id), expect=204)
+
+    # -- listing ---------------------------------------------------------------
+
+    def list(
+        self,
+        *,
+        content_type: str | None = None,
+        tags: dict[str, str] | None = None,
+        limit: int | None = None,
+        cursor: str | None = None,
+    ) -> ListPage:
+        """One page of files matching the filter, newest first."""
+        resp = self._request("GET", "/files", params=list_params(content_type, tags, limit, cursor))
+        return ListPage.from_json(resp.json())
+
+    def iter_files(
+        self,
+        *,
+        content_type: str | None = None,
+        tags: dict[str, str] | None = None,
+        limit: int | None = None,
+    ) -> Iterator[File]:
+        """Every file matching the filter, fetching pages lazily."""
+        cursor: str | None = None
+        while True:
+            page = self.list(content_type=content_type, tags=tags, limit=limit, cursor=cursor)
+            yield from page.files
+            # A page without a cursor is the last (a final empty page is
+            # normal when the total is an exact multiple of the page size).
+            if not page.next_cursor:
+                return
+            cursor = page.next_cursor
+
+    # -- probes / lifecycle ------------------------------------------------------
+
+    def health(self) -> None:
+        """Raise unless the server answers 200 on /healthz (liveness)."""
+        self._request("GET", "/healthz")
+
+    def ready(self) -> None:
+        """Raise unless /readyz says storage and database are reachable."""
+        self._request("GET", "/readyz")
+
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> CairnMark:
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
+
+
+def _file_path(file_id: str) -> str:
+    return "/files/" + quote(file_id, safe="")

cairnmark/_http.py

@@ -0,0 +1,161 @@
+"""Shared request/response plumbing for the sync and async clients.
+
+Everything here is pure or synchronous helper logic; the two clients own the
+actual I/O and retry loops so each can sleep its own way.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import random
+import uuid
+from typing import Any, AsyncIterator, Callable, Iterator
+
+import httpx
+
+from .errors import APIError, ChecksumMismatchError, error_class_for
+
+DEFAULT_RETRIES = 2
+DEFAULT_TIMEOUT = 30.0
+#: Cap on how long a retry waits on a server-supplied Retry-After.
+MAX_RETRY_AFTER = 30.0
+
+
+def backoff_delay(attempt: int) -> float:
+    """Exponential, jittered delay in seconds before retry ``attempt`` (0-based)."""
+    d = min(0.25 * (2**attempt), 4.0)
+    return d / 2 + random.uniform(0, d / 2)
+
+
+def retry_delay(err: APIError | None, attempt: int) -> float:
+    """Backoff, except a server-supplied Retry-After (bounded) wins."""
+    if err is not None and err.retry_after:
+        return min(err.retry_after, MAX_RETRY_AFTER)
+    return backoff_delay(attempt)
+
+
+def error_from_response(response: httpx.Response) -> APIError:
+    """Map a non-2xx response (body already read) to a typed APIError."""
+    message = ""
+    try:
+        body = response.json()
+        if isinstance(body, dict):
+            message = str(body.get("error") or "")
+    except ValueError:
+        pass
+    if not message:
+        message = response.text.strip() or f"HTTP {response.status_code}"
+    retry_after = None
+    ra = response.headers.get("retry-after", "")
+    if ra.isdigit() and int(ra) > 0:
+        retry_after = float(ra)
+    return error_class_for(response.status_code)(response.status_code, message, retry_after)
+
+
+def unexpected_status(response: httpx.Response, want: int) -> APIError:
+    return APIError(response.status_code, f"unexpected status {response.status_code} (want {want})")
+
+
+def new_idempotency_key() -> str:
+    """32 hex chars, unique per call — comfortably under the server's 255 cap."""
+    return uuid.uuid4().hex
+
+
+def resolve_idempotency_key(key: str | None) -> str | None:
+    """The sentinel value "auto" becomes a freshly generated key."""
+    return new_idempotency_key() if key == "auto" else key
+
+
+def upload_params_headers(
+    filename: str | None,
+    content_type: str | None,
+    metadata: dict[str, Any] | None,
+    idempotency_key: str | None,
+    size: int | None,
+) -> tuple[dict[str, str], dict[str, str]]:
+    """Query params and headers for POST /files."""
+    params: dict[str, str] = {}
+    if filename:
+        params["filename"] = filename
+    headers: dict[str, str] = {}
+    if content_type:
+        headers["Content-Type"] = content_type
+    if metadata:
+        # The X-Metadata JSON header carries typed/nested tag values intact.
+        headers["X-Metadata"] = json.dumps(metadata, separators=(",", ":"))
+    if idempotency_key:
+        headers["Idempotency-Key"] = idempotency_key
+    if size is not None and size > 0:
+        headers["Content-Length"] = str(size)
+    return params, headers
+
+
+def list_params(
+    content_type: str | None,
+    tags: dict[str, str] | None,
+    limit: int | None,
+    cursor: str | None,
+) -> dict[str, str]:
+    """Query params for GET /files."""
+    params: dict[str, str] = {}
+    if content_type:
+        params["content_type"] = content_type
+    for key, value in (tags or {}).items():
+        params[f"tag.{key}"] = value
+    if limit:
+        params["limit"] = str(limit)
+    if cursor:
+        params["cursor"] = cursor
+    return params
+
+
+def range_header(offset: int, length: int | None) -> str:
+    """A bytes= header for offset/length (length None means "to the end")."""
+    if length is not None and length > 0:
+        return f"bytes={offset}-{offset + length - 1}"
+    return f"bytes={offset}-"
+
+
+def rewinder(content: Any) -> Callable[[], None] | None:
+    """A callable that resets ``content`` for a resend, or None if it can't be.
+
+    Retries must resend the body; bytes are trivially reusable, seekable
+    file-likes are rewound to their current position, and anything else
+    (a one-shot iterator) disables retries rather than resending garbage.
+    """
+    if isinstance(content, (bytes, bytearray, memoryview)):
+        return lambda: None
+    seek = getattr(content, "seek", None)
+    tell = getattr(content, "tell", None)
+    seekable = getattr(content, "seekable", None)
+    if callable(seek) and callable(tell) and (seekable is None or seekable()):
+        pos = content.tell()
+        return lambda: content.seek(pos)
+    return None
+
+
+def verify_bytes(chunks: Iterator[bytes], expected: str) -> Iterator[bytes]:
+    """Pass chunks through, raising ChecksumMismatchError after the last one.
+
+    The presigned object-store response carries no checksum header, so this
+    client-side hash is the only integrity signal on an offloaded download.
+    """
+    digest = hashlib.sha256()
+    for chunk in chunks:
+        digest.update(chunk)
+        yield chunk
+    got = digest.hexdigest()
+    if got != expected.lower():
+        raise ChecksumMismatchError(got, expected)
+
+
+async def averify_bytes(chunks: AsyncIterator[bytes], expected: str) -> AsyncIterator[bytes]:
+    """Async twin of verify_bytes."""
+    digest = hashlib.sha256()
+    async for chunk in chunks:
+        digest.update(chunk)
+        yield chunk
+    got = digest.hexdigest()
+    if got != expected.lower():
+        raise ChecksumMismatchError(got, expected)

cairnmark/errors.py

@@ -0,0 +1,82 @@
+"""Typed errors for the CairnMark API's client-facing failure modes."""
+
+from __future__ import annotations
+
+
+class CairnMarkError(Exception):
+    """Base class for every error this SDK raises deliberately."""
+
+
+class ChecksumMismatchError(CairnMarkError):
+    """A verified download's bytes did not hash to the stored SHA-256.
+
+    Raised from the stream once it is fully consumed — never by the server.
+    """
+
+    def __init__(self, got: str, expected: str) -> None:
+        super().__init__(f"cairnmark: downloaded sha256 {got}, stored {expected}")
+        self.got = got
+        self.expected = expected
+
+
+class APIError(CairnMarkError):
+    """A non-2xx response from the server."""
+
+    def __init__(self, status: int, message: str, retry_after: float | None = None) -> None:
+        super().__init__(f"cairnmark: server returned {status}: {message}")
+        self.status = status
+        self.message = message
+        #: Seconds the server asked to wait (409 idempotency conflicts); else None.
+        self.retry_after = retry_after
+
+
+class InvalidRequestError(APIError):
+    """400: malformed request — bad id, bad parameters, bad metadata JSON."""
+
+
+class NotFoundError(APIError):
+    """404: the file id does not exist (or was soft-deleted)."""
+
+
+class IdempotencyConflictError(APIError):
+    """409: an upload with the same Idempotency-Key is still in flight.
+
+    ``retry_after`` says when to ask again.
+    """
+
+
+class IdempotencyGoneError(APIError):
+    """410: the file created under this Idempotency-Key was deleted.
+
+    Retrying the same key can never succeed — switch to a new key.
+    """
+
+
+class TooLargeError(APIError):
+    """413: the body exceeds a server cap (upload size or metadata patch)."""
+
+
+class RangeNotSatisfiableError(APIError):
+    """416: the requested byte range lies outside the file."""
+
+
+class ServerError(APIError):
+    """5xx: the server failed; the message is generic by design."""
+
+
+_BY_STATUS: dict[int, type[APIError]] = {
+    400: InvalidRequestError,
+    404: NotFoundError,
+    409: IdempotencyConflictError,
+    410: IdempotencyGoneError,
+    413: TooLargeError,
+    416: RangeNotSatisfiableError,
+}
+
+
+def error_class_for(status: int) -> type[APIError]:
+    """The APIError subclass for an HTTP status."""
+    cls = _BY_STATUS.get(status)
+    if cls is not None:
+        return cls
+    return ServerError if status >= 500 else APIError

cairnmark/models.py

@@ -0,0 +1,68 @@
+"""Public data models returned by the CairnMark API."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime
+from typing import Any
+
+
+def _parse_time(value: str) -> datetime:
+    # The server emits RFC 3339 with a Z suffix; fromisoformat on Python 3.10
+    # only accepts a numeric offset.
+    return datetime.fromisoformat(value.replace("Z", "+00:00"))
+
+
+@dataclass(frozen=True)
+class File:
+    """A stored file's metadata record. Files are addressed by ``id`` only."""
+
+    id: str
+    filename: str
+    content_type: str
+    size_bytes: int
+    #: Hex SHA-256 computed by the server during upload; None if absent.
+    checksum_sha256: str | None
+    #: The queryable tag set (arbitrary JSON values).
+    metadata: dict[str, Any]
+    created_at: datetime
+    #: None until the file's tags are first changed — a quick way to tell an
+    #: untouched original from an edited record.
+    updated_at: datetime | None
+
+    @classmethod
+    def from_json(cls, data: dict[str, Any]) -> File:
+        updated = data.get("updated_at")
+        return cls(
+            id=data["id"],
+            filename=data["filename"],
+            content_type=data["content_type"],
+            size_bytes=data["size_bytes"],
+            checksum_sha256=data.get("checksum_sha256"),
+            metadata=data.get("metadata") or {},
+            created_at=_parse_time(data["created_at"]),
+            updated_at=_parse_time(updated) if updated else None,
+        )
+
+
+@dataclass(frozen=True)
+class ListPage:
+    """One page of list results.
+
+    A non-None ``next_cursor`` means more may follow; its absence is the
+    definitive end-of-list signal.
+    """
+
+    files: list[File]
+    limit: int
+    count: int
+    next_cursor: str | None
+
+    @classmethod
+    def from_json(cls, data: dict[str, Any]) -> ListPage:
+        return cls(
+            files=[File.from_json(f) for f in data.get("files") or []],
+            limit=data["limit"],
+            count=data["count"],
+            next_cursor=data.get("next_cursor"),
+        )

cairnmark/version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

cairnmark-0.1.0.dist-info/METADATA

@@ -0,0 +1,137 @@
+Metadata-Version: 2.4
+Name: cairnmark
+Version: 0.1.0
+Summary: Official Python client for the CairnMark file service
+Project-URL: Homepage, https://github.com/mettjs/cairnmark-python
+Author: Michael Ramirez
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Description-Content-Type: text/markdown
+
+# cairnmark-python
+
+The official Python client for [CairnMark](https://github.com/mettjs/cairnmark) —
+a self-hostable file service over S3-compatible storage with a queryable
+Postgres metadata layer.
+
+Sync **and** async clients, streaming uploads/downloads, client-side checksum
+verification, typed errors, safe retries, lazy pagination. One dependency
+(`httpx`). Python ≥ 3.10, fully typed (`py.typed`). Requires a CairnMark
+server ≥ v1.1.0 (cursor pagination and 409 `Retry-After`).
+
+```sh
+pip install cairnmark   # not yet on PyPI — until then: pip install <path to this repo>
+```
+
+## Quickstart
+
+```python
+from cairnmark import CairnMark
+
+with CairnMark("http://localhost:8080") as cm:
+    # Upload with tags; idempotency_key="auto" makes retries duplicate-safe.
+    f = cm.upload(
+        b"hello from Python",
+        filename="hello.txt",
+        content_type="text/plain",
+        metadata={"env": "demo"},
+        idempotency_key="auto",
+    )
+    print("uploaded:", f.id)
+
+    # Download — follows the presign redirect and verifies the SHA-256.
+    cm.download_to_file(f.id, "hello-copy.txt")
+
+    # Search by tag, lazily across pages.
+    for file in cm.iter_files(tags={"env": "demo"}):
+        print("found:", file.id, file.filename)
+```
+
+Async is the same surface with `await` (and `aiter_bytes`/`aread`/`aclose` on
+downloads):
+
+```python
+from cairnmark import AsyncCairnMark
+
+async with AsyncCairnMark("http://localhost:8080") as cm:
+    f = await cm.upload(b"hello", filename="hello.txt")
+    async with await cm.download(f.id, verify=True) as dl:
+        data = await dl.aread()
+    async for file in cm.iter_files(tags={"env": "demo"}):
+        ...
+```
+
+## Methods
+
+| Method | Does |
+|---|---|
+| `upload(content, *, filename, content_type, size, metadata, idempotency_key)` | Stream bytes / a file-like / an iterator up. `idempotency_key="auto"` generates a key. |
+| `upload_file(path, ...)` | Upload from disk; name and size inferred. |
+| `download(id, *, verify, offset, length)` | Open a content stream (context manager). Default follows the presign redirect; `offset`/`length` for a 206 range; `verify` for checksum checking. |
+| `download_to_file(id, path)` | Download to disk, checksum-verified; removes the file on failure. |
+| `presign_url(id)` | Mint the presigned object-store URL without following it. |
+| `get_metadata(id)` | Fetch the file record (a frozen `File` dataclass). |
+| `update_metadata(id, tags, mode="merge"\|"replace")` | Patch tags. |
+| `delete(id)` | Soft-delete. |
+| `list(...)` / `iter_files(...)` | One page / lazy iteration over every match. |
+| `health()` / `ready()` | Liveness / readiness probes (raise on failure). |
+
+## Configuration
+
+`CairnMark(base_url, ...)` / `AsyncCairnMark(base_url, ...)` keyword options:
+
+| Option | Default | Does |
+|---|---|---|
+| `headers` | `None` | Default headers on every request; the hook for gateway credentials. |
+| `timeout` | `30.0` | httpx per-operation timeout (connect / single socket read) — a `float` or an `httpx.Timeout` for fine-grained control. Doesn't cut off large streams. |
+| `retries` | `2` | Retries after a network error or 5xx (so up to `retries + 1` attempts). `0` disables. |
+| `user_agent` | `cairnmark-python/<version>` | Override the `User-Agent`. |
+| `transport` | `None` | Custom `httpx.BaseTransport` (`AsyncBaseTransport` for async) — proxies, mocking, UDS. |
+
+## Errors
+
+Every non-2xx response raises a subclass of `APIError` (which carries
+`.status`, `.message`, and `.retry_after` on 409), itself a `CairnMarkError`:
+
+`InvalidRequestError` (400) · `NotFoundError` (404) ·
+`IdempotencyConflictError` (409) · `IdempotencyGoneError` (410) ·
+`TooLargeError` (413) · `RangeNotSatisfiableError` (416) · `ServerError` (5xx)
+— plus `ChecksumMismatchError` from verified download streams.
+
+## Semantics worth knowing
+
+- **Retries.** Network errors and 5xx are retried with jittered backoff
+  (default 2 retries; `retries=` to change). Uploads retry **only** when they
+  carry an idempotency key *and* the body can be rewound (bytes or a seekable
+  file) — otherwise a retry could duplicate the file. A 409 (same key still in
+  flight) waits out the server's `Retry-After`.
+- **Checksum verification.** The presigned object-store response carries no
+  checksum header, so `verify=True` hashes the stream client-side against the
+  stored SHA-256 (fetched from metadata) and raises `ChecksumMismatchError` as
+  the last chunk is consumed. Range downloads can't be verified.
+- **Timeouts.** `timeout=` is httpx's per-operation timeout (connect, single
+  socket read), so large streams aren't cut off mid-transfer.
+- **Auth.** The server has none; put it behind your gateway and inject
+  credentials with `headers=` (or a custom `transport=`).
+
+## Development
+
+```sh
+uv sync
+uv run pytest                    # unit tests (respx-mocked, no server needed)
+uv run ruff check src tests && uv run pyright src
+
+# integration: full round-trip against a live server
+(cd ../CairnMark && docker compose up -d --build)
+uv run pytest -m integration     # honors CAIRNMARK_BASE_URL, default localhost:8080
+```
+
+## License
+
+[MIT](LICENSE) © 2026 Michael Ramirez

cairnmark-0.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+cairnmark/__init__.py,sha256=Z7RGVC8sWOvOEvTOEpNWZ9W7Ujlhmw5cTXbks5NL4Is,1429
+cairnmark/_async_client.py,sha256=Y_D35YexjjWHxIe4_UW8hsme0XP--1WRXTlHZpCtUWE,13567
+cairnmark/_client.py,sha256=UzgIcjBJCevIcPmrRkFJcMf73jmEt5xWv7OLtUIek4w,13240
+cairnmark/_http.py,sha256=2EP3y-WANaUh0ERRF-1uYI4Als2nEmVGy6Rk-YcNvbg,5426
+cairnmark/errors.py,sha256=8e1-1ZVD7Ih287CnkPKggAR1ZxGBMmuU_e1-hv7rNcQ,2396
+cairnmark/models.py,sha256=NogldgdFqMZZoi62osP8cuGnxPwx66-JJiOtXOPU3sQ,2058
+cairnmark/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+cairnmark/version.py,sha256=kUR5RAFc7HCeiqdlX36dZOHkUI5wI6V_43RpEcD8b-0,22
+cairnmark-0.1.0.dist-info/METADATA,sha256=2YDQGoyYGcNkqZUTZqN7Ga7j-PIhZI17YvQdG_UcfJM,5687
+cairnmark-0.1.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+cairnmark-0.1.0.dist-info/licenses/LICENSE,sha256=BfU8cCXBUlCgAkGfpDCRmlOCMCAnq-dKHWDbExV1U5M,1072
+cairnmark-0.1.0.dist-info/RECORD,,

cairnmark-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

cairnmark-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Michael Ramirez
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.