objectstore-client 0.2.8__tar.gz → 0.2.10__tar.gz

{objectstore_client-0.2.8 → objectstore_client-0.2.10}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: objectstore-client
-Version: 0.2.8
+Version: 0.2.10
 Summary: Client SDK for Objectstore, the Sentry object storage platform
 Author: Sentry
 Author-email: Sentry <oss@sentry.io>
@@ -147,6 +147,8 @@ session.delete(key)
 ### Usecases and Scopes
 
 A `Usecase` represents a server-side namespace with its own configuration defaults.
+Its name must follow the naming rules documented on [`Usecase`]; invalid names
+raise `ValueError` during construction.
 Within a Usecase, Scopes provide further isolation — typically keyed by organization
 and project IDs. A Session ties a Client to a specific Usecase + Scope for operations.
 
@@ -219,6 +221,12 @@ session.put(video_data, compress="none")
 session.put(zstd_data, precompressed="zstd")
 ```
 
+### Resumable Uploads
+
+The client automatically uses resumable uploads when eligible and may create
+temporary files for spooling. See [`Session.put()`](src/objectstore_client/client.py)
+for eligibility, configuration, and upload behavior.
+
 ### Custom Metadata
 
 Arbitrary key-value pairs can be attached to objects and retrieved on download.

{objectstore_client-0.2.8 → objectstore_client-0.2.10}/README.md

@@ -28,6 +28,8 @@ session.delete(key)
 ### Usecases and Scopes
 
 A `Usecase` represents a server-side namespace with its own configuration defaults.
+Its name must follow the naming rules documented on [`Usecase`]; invalid names
+raise `ValueError` during construction.
 Within a Usecase, Scopes provide further isolation — typically keyed by organization
 and project IDs. A Session ties a Client to a specific Usecase + Scope for operations.
 
@@ -100,6 +102,12 @@ session.put(video_data, compress="none")
 session.put(zstd_data, precompressed="zstd")
 ```
 
+### Resumable Uploads
+
+The client automatically uses resumable uploads when eligible and may create
+temporary files for spooling. See [`Session.put()`](src/objectstore_client/client.py)
+for eligibility, configuration, and upload behavior.
+
 ### Custom Metadata
 
 Arbitrary key-value pairs can be attached to objects and retrieved on download.

{objectstore_client-0.2.8 → objectstore_client-0.2.10}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "objectstore-client"
-version = "0.2.8"
+version = "0.2.10"
 description = "Client SDK for Objectstore, the Sentry object storage platform"
 readme = "README.md"
 authors = [{ name = "Sentry", email = "oss@sentry.io" }]

objectstore_client-0.2.10/src/objectstore_client/_resumable.py

@@ -0,0 +1,385 @@
+from __future__ import annotations
+
+import random
+import time
+from collections.abc import Iterator
+from contextlib import contextmanager, nullcontext
+from dataclasses import dataclass
+from io import SEEK_END, BytesIO
+from os import PathLike
+from tempfile import TemporaryFile
+from typing import IO, TYPE_CHECKING
+from urllib.parse import urlencode
+
+import urllib3
+import zstandard
+
+from objectstore_client.errors import RequestError, raise_for_status
+from objectstore_client.metadata import Compression, ExpirationPolicy
+from objectstore_client.metrics import measure_storage_operation
+from objectstore_client.tracing import storage_span
+
+if TYPE_CHECKING:
+    from objectstore_client.client import Session
+
+
+class ResumableUploadUnavailable(RequestError):
+    """The upload session expired, was canceled, or could not be found."""
+
+
+class UploadOffsetMismatch(RequestError):
+    """The server rejected a chunk and reported its offset."""
+
+    def __init__(self, offset: int, response: urllib3.BaseHTTPResponse):
+        super().__init__(
+            f"Upload offset mismatch (server holds {offset} bytes)",
+            response.status,
+            response.data.decode("utf-8", "replace"),
+        )
+        self.offset = offset
+
+
+class ChunkTooSmall(ValueError):
+    """A non-final chunk is shorter than the upload granularity."""
+
+
+class NoUploadProgress(Exception):
+    """A write completed without advancing the server's upload offset."""
+
+    def __init__(self) -> None:
+        super().__init__("Upload made no progress")
+
+
+@dataclass(frozen=True)
+class UploadIncomplete:
+    """The upload expects more bytes, starting at the given offset."""
+
+    offset: int
+
+
+@dataclass(frozen=True)
+class UploadComplete:
+    """The upload is complete."""
+
+
+UploadProgress = UploadIncomplete | UploadComplete
+
+
+def parse_progress_response(response: urllib3.BaseHTTPResponse) -> UploadProgress:
+    if response.status == 409:
+        raise UploadOffsetMismatch(int(response.headers["Upload-Offset"]), response)
+    if response.status in (404, 410):
+        raise_for_status(response, error_type=ResumableUploadUnavailable)
+    raise_for_status(response)
+    if response.status == 201:
+        return UploadComplete()
+    return UploadIncomplete(int(response.headers["Upload-Offset"]))
+
+
+class ResumableUpload:
+    """A handle bound to one resumable upload session."""
+
+    def __init__(
+        self,
+        session: Session,
+        key: str,
+        token: str,
+        total_length: int | None = None,
+        granularity: int | None = None,
+    ):
+        self._session = session
+        self._key = key
+        self._token = token
+        self._total_length = total_length
+        self._granularity = granularity
+
+    @property
+    def key(self) -> str:
+        return self._key
+
+    @property
+    def token(self) -> str:
+        return self._token
+
+    @property
+    def granularity(self) -> int | None:
+        """The persistence unit for non-final chunks, if known."""
+        return self._granularity
+
+    def progress(self) -> UploadProgress:
+        """Query the server's authoritative offset.
+
+        Raises `ResumableUploadUnavailable` for an unavailable session.
+        """
+        session = self._session
+        query = urlencode({"session": self.token})
+        headers = session._make_headers()
+        headers["Upload-Offset"] = "*"
+        with (
+            storage_span(
+                "resumable.progress", session._usecase, session._scope, key=self.key
+            ),
+            measure_storage_operation(
+                session._metrics_backend, "resumable.progress", session._usecase.name
+            ),
+        ):
+            response = session._pool.request(
+                "PUT",
+                f"{session._make_url(self.key)}?{query}",
+                headers=headers,
+                preload_content=True,
+                decode_content=True,
+            )
+            return parse_progress_response(response)
+
+    def put(
+        self, offset: int, contents: bytes | tuple[IO[bytes], int]
+    ) -> UploadProgress:
+        """Uploads `contents` starting at `offset`.
+
+        For streaming payloads, supply a tuple of the stream and its exact length
+        in bytes.
+
+        This method doesn't perform any automatic compression of the payload, so
+        the caller is responsible for applying compression to the entire payload
+        beforehand and passing chunks of the already compressed payload.
+
+        Raises `UploadOffsetMismatch` when the server rejects the offset,
+        `ResumableUploadUnavailable` for an unavailable session, or `ChunkTooSmall`
+        for a non-final chunk shorter than the granularity.
+        """
+        if isinstance(contents, bytes):
+            body: bytes | IO[bytes] = contents
+            length = len(contents)
+        else:
+            body, length = contents
+
+        if offset < 0 or length < 0:
+            raise ValueError("Chunk offset and length must not be negative")
+        if (
+            self._granularity is not None
+            and self._total_length is not None
+            and 0 < length < self._granularity
+            and offset + length < self._total_length
+        ):
+            raise ChunkTooSmall(
+                f"Non-final chunk {length} is smaller than upload granularity "
+                f"{self._granularity}"
+            )
+
+        session = self._session
+        query = urlencode({"session": self.token})
+        headers = session._make_headers()
+        headers["Upload-Offset"] = str(offset)
+        headers["Content-Length"] = str(length)
+        # Disable pool retries that replay the body. The resumable upload loop
+        # probes the persisted offset before resending data; connection retries
+        # retain the pool's policy.
+        retries = urllib3.Retry.from_int(session._pool.retries).new(
+            read=0, status=0, other=0, raise_on_status=False
+        )
+        with (
+            storage_span(
+                "resumable.put",
+                session._usecase,
+                session._scope,
+                key=self.key,
+                offset=offset,
+                size=length,
+            ),
+            measure_storage_operation(
+                session._metrics_backend, "resumable.put", session._usecase.name
+            ) as metrics,
+        ):
+            response = session._pool.request(
+                "PUT",
+                f"{session._make_url(self.key)}?{query}",
+                headers=headers,
+                body=body,
+                retries=retries,
+                preload_content=True,
+                decode_content=True,
+            )
+            progress = parse_progress_response(response)
+            metrics.record_size(length)
+            return progress
+
+    def cancel(self) -> None:
+        """Cancels the upload session, discarding uploaded bytes."""
+        session = self._session
+        query = urlencode({"session": self.token})
+        headers = session._make_headers()
+        with (
+            storage_span(
+                "resumable.cancel", session._usecase, session._scope, key=self.key
+            ),
+            measure_storage_operation(
+                session._metrics_backend, "resumable.cancel", session._usecase.name
+            ),
+        ):
+            response = session._pool.request(
+                "DELETE",
+                f"{session._make_url(self.key)}?{query}",
+                headers=headers,
+                preload_content=True,
+                decode_content=True,
+            )
+            error_type = (
+                ResumableUploadUnavailable
+                if response.status in (404, 410)
+                else RequestError
+            )
+            raise_for_status(response, error_type=error_type)
+
+
+@contextmanager
+def prepare_body(
+    contents: bytes | IO[bytes],
+    source_size: int,
+    compress: bool,
+    spool_dir: str | PathLike[str] | None,
+) -> Iterator[tuple[IO[bytes], int, int] | None]:
+    """Yield the body, source size, and compressed size (equal if uncompressed).
+
+    Reuse sized, seekable input when no compression is needed. Otherwise spool
+    the compressed bytes without closing the caller's stream.
+    Yield None if temporary-file creation fails, before consuming any input.
+    """
+    with (
+        BytesIO(contents) if isinstance(contents, bytes) else nullcontext(contents)
+    ) as source:
+        if not compress:
+            yield source, source_size, source_size
+            return
+
+        try:
+            temporary = TemporaryFile(dir=spool_dir)
+        except OSError:
+            yield None
+            return
+
+        with temporary as body:
+            source_size, compressed_size = zstandard.ZstdCompressor().copy_stream(
+                source, body
+            )
+            body.seek(0)
+            yield body, source_size, compressed_size
+
+
+def get_size(source: bytes | IO[bytes]) -> int | None:
+    """Return the buffer length or remaining stream size, or None if unsupported.
+
+    Streams are measured by seeking to the end, which may read data in transforming
+    streams. Failure to restore the original position propagates so callers cannot
+    upload from an unexpected position.
+    """
+    if isinstance(source, bytes):
+        return len(source)
+
+    try:
+        if not source.seekable():
+            return None
+        start = source.tell()
+    except (AttributeError, OSError):
+        return None
+
+    try:
+        source.seek(0, SEEK_END)
+        return max(0, source.tell() - start)
+    except OSError:
+        return None
+    finally:
+        source.seek(start)
+
+
+def is_transient(error: Exception) -> bool:
+    if isinstance(error, urllib3.exceptions.MaxRetryError):
+        # Exhausted status retries carry ResponseError rather than the response.
+        return isinstance(error.reason, urllib3.exceptions.ResponseError) or (
+            isinstance(error.reason, Exception) and is_transient(error.reason)
+        )
+    if isinstance(error, RequestError):
+        return error.status in (408, 429, 502, 503, 504)
+    return isinstance(
+        error,
+        (
+            NoUploadProgress,
+            urllib3.exceptions.ReadTimeoutError,
+            urllib3.exceptions.ProtocolError,
+        ),
+    )
+
+
+def upload(
+    session: Session,
+    body: IO[bytes],
+    compressed_size: int,
+    key: str | None = None,
+    compression: Compression | None = None,
+    content_type: str | None = None,
+    metadata: dict[str, str] | None = None,
+    expiration_policy: ExpirationPolicy | None = None,
+    origin: str | None = None,
+    filename: str | None = None,
+) -> str | None:
+    start = body.tell()
+    try:
+        handle = session._create_upload(
+            compressed_size,
+            key=key,
+            compression=compression,
+            content_type=content_type,
+            metadata=metadata,
+            expiration_policy=expiration_policy,
+            origin=origin,
+            filename=filename,
+        )
+    except Exception:
+        handle = None
+    if handle is None:
+        return None
+
+    try:
+        offset = 0
+        retries = 0
+        probe = False
+        while True:
+            try:
+                if probe:
+                    result = handle.progress()
+                else:
+                    body.seek(start + offset)
+                    try:
+                        result = handle.put(offset, (body, compressed_size - offset))
+                    except UploadOffsetMismatch as error:
+                        result = UploadIncomplete(error.offset)
+                if (
+                    isinstance(result, UploadIncomplete)
+                    and result.offset == offset
+                    and not probe
+                ):
+                    raise NoUploadProgress()
+            except Exception as error:
+                if not is_transient(error) or retries >= 2:
+                    raise
+                time.sleep(2 * 2**retries + random.uniform(0, 1))
+                retries += 1
+                probe = True
+                continue
+
+            if isinstance(result, UploadComplete):
+                return handle.key
+            if not offset <= result.offset <= compressed_size:
+                raise ValueError("Invalid upload offset")
+            if result.offset > offset:
+                retries = 0
+            offset = result.offset
+            probe = False
+    except Exception as error:
+        try:
+            handle.cancel()
+        except Exception:
+            pass
+        status = error.status if isinstance(error, RequestError) else None
+        response = error.response if isinstance(error, RequestError) else None
+        raise RequestError("upload failed", status, response) from error

{objectstore_client-0.2.8 → objectstore_client-0.2.10}/src/objectstore_client/client.py

@@ -3,10 +3,12 @@ from __future__ import annotations
 import math
 import warnings
 from collections.abc import Mapping, Sequence
+from contextlib import nullcontext
 from dataclasses import asdict, dataclass
 from datetime import UTC, datetime, timedelta
 from importlib.metadata import version
 from io import BytesIO
+from os import PathLike
 from typing import IO, Any, Literal, NamedTuple, cast
 from urllib.parse import urlparse
 
@@ -15,7 +17,7 @@ import urllib3
 import zstandard
 from urllib3.connectionpool import HTTPConnectionPool
 
-from objectstore_client import presign, utils
+from objectstore_client import _resumable, presign, utils
 from objectstore_client.auth import Permission, SecretKey, TokenProvider
 from objectstore_client.errors import (
     ExpiryExtensionRejected,
@@ -63,9 +65,13 @@ class Usecase:
     Usecases need to be statically defined in Objectstore's configuration server-side.
     Objectstore can make decisions based on the Usecase. For example, choosing the most
     suitable storage backend.
+
+    Names must be 3–64 ASCII characters from ``[A-Za-z0-9_-]``. Any permitted
+    character may appear in any position. Names are case-sensitive and are never
+    normalized. The name is read-only after construction.
     """
 
-    name: str
+    _name: str
     _compression: Compression
     _expiration_policy: ExpirationPolicy | None
 
@@ -74,11 +80,36 @@ class Usecase:
         name: str,
         compression: Compression = "zstd",
         expiration_policy: ExpirationPolicy | None = None,
+        resumable_threshold_bytes: int | Literal["none"] = 256 * 1024 * 1024,
     ):
-        self.name = name
+        """Create a usecase.
+
+        Raises ``ValueError`` if the name violates the naming rules on ``Usecase``,
+        or if the ``resumable_threshold_bytes`` is invalid.
+        """
+        if not 3 <= len(name) <= 64:
+            raise ValueError("usecase name must be 3–64 ASCII characters long")
+        if any(not (c.isascii() and c.isalnum()) and c not in "_-" for c in name):
+            raise ValueError(
+                "usecase name must contain only ASCII letters, digits, '_' or '-'"
+            )
+        self._name = name
+        
+        if resumable_threshold_bytes != "none" and (
+            type(resumable_threshold_bytes) is not int or resumable_threshold_bytes < 0
+        ):
+            raise ValueError(
+                'resumable_threshold_bytes must be a non-negative integer or "none"'
+            )
+        self._resumable_threshold_bytes = resumable_threshold_bytes
         self._compression = compression
         self._expiration_policy = expiration_policy
 
+    @property
+    def name(self) -> str:
+        """The validated usecase name."""
+        return self._name
+
 
 # Connect timeout used unless overridden in connection parameters.
 DEFAULT_CONNECT_TIMEOUT = 0.1
@@ -146,6 +177,8 @@ class Client:
             as-is for every request. Use a ``SecretKey`` for internal
             services that have access to the signing key, and a string for
             external services that receive a token from another source.
+        spool_dir: Directory that temporary files are created in when preparing
+            resumable uploads. ``None`` uses Python's default temporary directory.
     """
 
     def __init__(
@@ -157,6 +190,7 @@ class Client:
         timeout_ms: float | None = None,
         connection_kwargs: Mapping[str, Any] | None = None,
         token: TokenProvider | None = None,
+        spool_dir: str | PathLike[str] | None = None,
     ):
         if propagate_traces:
             warnings.warn(
@@ -168,7 +202,7 @@ class Client:
 
         connection_kwargs_to_use = asdict(_ConnectionDefaults())
 
-        if retries:
+        if retries is not None:
             connection_kwargs_to_use["retries"] = urllib3.Retry(
                 connect=retries,
                 # we only retry connection problems, as we cannot rewind our
@@ -195,6 +229,7 @@ class Client:
         self._metrics_backend = metrics_backend or NoOpMetricsBackend()
         self._propagate_traces = propagate_traces
         self._token = token
+        self._spool_dir = spool_dir
 
     def session(self, usecase: Usecase, **scopes: str | int | bool) -> Session:
         """
@@ -230,6 +265,7 @@ class Client:
             usecase,
             Scope(**scopes),
             self._token,
+            self._spool_dir,
         )
 
 
@@ -249,6 +285,7 @@ class Session:
         usecase: Usecase,
         scope: Scope,
         token: TokenProvider | None = None,
+        spool_dir: str | PathLike[str] | None = None,
     ):
         self._pool = pool
         self._base_path = base_path
@@ -257,6 +294,7 @@ class Session:
         self._usecase = usecase
         self._scope = scope
         self._token = token
+        self._spool_dir = spool_dir
 
     def mint_token(
         self,
@@ -320,6 +358,33 @@ class Session:
             headers["x-os-auth"] = f"Bearer {token}"
         return headers
 
+    def _metadata_headers(
+        self,
+        compression: Compression | None,
+        content_type: str | None = None,
+        metadata: dict[str, str] | None = None,
+        expiration_policy: ExpirationPolicy | None = None,
+        origin: str | None = None,
+        filename: str | None = None,
+    ) -> dict[str, str]:
+        """Build upload headers with the given compression and usecase expiration."""
+        headers = self._make_headers()
+        if compression and compression != "none":
+            headers["Content-Encoding"] = compression
+        if content_type:
+            headers["Content-Type"] = content_type
+        expiration_policy = expiration_policy or self._usecase._expiration_policy
+        if expiration_policy:
+            headers[HEADER_EXPIRATION] = format_expiration(expiration_policy)
+        if origin:
+            headers[HEADER_ORIGIN] = utils.encode_header_value(origin)
+        if filename is not None:
+            headers[HEADER_FILENAME] = utils.encode_header_value(filename)
+        if metadata:
+            for k, v in metadata.items():
+                headers[f"{HEADER_META_PREFIX}{k}"] = utils.encode_header_value(v)
+        return headers
+
     def _base_url(self) -> str:
         # urllib3 stores IPv6 hosts unbracketed (e.g. "::1"); bracket them so
         # the result is a valid absolute URL.
@@ -366,6 +431,7 @@ class Session:
         expiration_policy: ExpirationPolicy | None = None,
         origin: str | None = None,
         filename: str | None = None,
+        resumable_threshold_bytes: int | Literal["none"] | None = None,
     ) -> str:
         """
         Uploads the given `contents` to blob storage.
@@ -373,7 +439,7 @@ class Session:
         If no `key` is provided, one will be automatically generated and returned
         from this function.
 
-        The client will select the configured `default_compression` if none is given
+        The client will select the Usecase's configured compression if none is given
         explicitly. This can be overridden by explicitly giving a `compress` argument.
         Providing `"none"` as the argument will instruct the client to not apply
         any compression to this upload, which is useful for uncompressible formats.
@@ -386,6 +452,28 @@ class Session:
         to attempt to guess a `content_type` based on magic bytes.
 
         `compression` is deprecated in favor of `compress`.
+
+        .. rubric:: Resumable Uploads
+
+        This method uses Objectstore's Resumable Uploads API when the size of
+        ``contents`` is at least ``resumable_threshold_bytes``.
+        Pass ``resumable_threshold_bytes="none"`` to disable Resumable Uploads.
+        When not overridden, this threshold defaults to the one set on the Usecase.
+
+        Transient failures and writes that make no progress are retried up to
+        twice. The retry count resets whenever the server reports a higher offset.
+
+        For seekable binary streams, the remaining size is measured by seeking to
+        the end and restoring the original position. Prefer streams with efficient
+        seeking: transforming streams may read their entire input to find the end.
+        Non-seekable streams and streams whose size cannot be determined use a
+        regular upload without spooling.
+
+        Resumable uploads reuse the input unless compression is needed, in which
+        case the compressed payload is spooled in a temporary file
+        (``tempfile.TemporaryFile``) on disk before sending.
+        Set ``Client(spool_dir=<path>)`` if you wish to customize the directory where
+        the temporary files are created in.
         """
         if compression is not None:
             warnings.warn(
@@ -404,36 +492,31 @@ class Session:
         if precompressed and precompressed != "zstd":
             raise ValueError(f"Invalid compression: {precompressed}")
 
-        headers = self._make_headers()
-        body = BytesIO(contents) if isinstance(contents, bytes) else contents
-        original_body: IO[bytes] = body
+        if resumable_threshold_bytes is None:
+            resumable_threshold_bytes = self._usecase._resumable_threshold_bytes
+        if resumable_threshold_bytes != "none" and (
+            type(resumable_threshold_bytes) is not int or resumable_threshold_bytes < 0
+        ):
+            raise ValueError(
+                'resumable_threshold_bytes must be a non-negative integer or "none"'
+            )
+
+        source_size = None
+        if resumable_threshold_bytes != "none":
+            source_size = _resumable.get_size(contents)
 
         encoding = precompressed or compress or self._usecase._compression
-        if encoding != "none":
-            headers["Content-Encoding"] = encoding
 
         compress_with = encoding if precompressed is None else "none"
-        if compress_with == "zstd":
-            cctx = zstandard.ZstdCompressor()
-            body = cctx.stream_reader(original_body)
-            body = cast(IO[bytes], utils._ZstdCompressionReaderWrapper(body))
-
-        if content_type:
-            headers["Content-Type"] = content_type
-
-        expiration_policy = expiration_policy or self._usecase._expiration_policy
-        if expiration_policy:
-            headers[HEADER_EXPIRATION] = format_expiration(expiration_policy)
-
-        if origin:
-            headers[HEADER_ORIGIN] = utils.encode_header_value(origin)
 
-        if filename is not None:
-            headers[HEADER_FILENAME] = utils.encode_header_value(filename)
-
-        if metadata:
-            for k, v in metadata.items():
-                headers[f"{HEADER_META_PREFIX}{k}"] = utils.encode_header_value(v)
+        headers = self._metadata_headers(
+            compression=encoding,
+            content_type=content_type,
+            metadata=metadata,
+            expiration_policy=expiration_policy,
+            origin=origin,
+            filename=filename,
+        )
 
         if key == "":
             key = None
@@ -444,37 +527,56 @@ class Session:
                 self._metrics_backend, "put", self._usecase.name
             ) as metrics,
         ):
-            retries = None  # by default use the pool's value, set by the Client
-            if compress_with != "none":
-                # For on-the-fly compression, don't attempt read retries,
-                # as the stream cannot be rewound after data has been consumed.
-                pool_retries = self._pool.retries
-                if isinstance(pool_retries, urllib3.Retry):
-                    retries = pool_retries.new(read=0)
-                elif isinstance(pool_retries, int):
-                    retries = urllib3.Retry(pool_retries, read=0)
-
-            response = self._pool.request(
-                "POST" if not key else "PUT",
-                self._make_url(key),
-                body=body,
-                headers=headers,
-                preload_content=True,
-                decode_content=True,
-                retries=retries,
-            )
-            raise_for_status(response)
-            res = response.json()
+            result_key: str | None
+            if (
+                resumable_threshold_bytes != "none"
+                and source_size is not None
+                and source_size >= resumable_threshold_bytes
+            ):
+                with _resumable.prepare_body(
+                    contents,
+                    source_size,
+                    compress_with != "none",
+                    self._spool_dir,
+                ) as prepared:
+                    if prepared is None:
+                        # Temporary-file creation failed before consuming the input.
+                        result_key, source_size, compressed_size = self._put_direct(
+                            contents, key, headers, compress=compress_with != "none"
+                        )
+                    else:
+                        body, source_size, compressed_size = prepared
+                        result_key = _resumable.upload(
+                            self,
+                            body,
+                            compressed_size,
+                            key=key,
+                            compression=encoding,
+                            content_type=content_type,
+                            metadata=metadata,
+                            expiration_policy=expiration_policy,
+                            origin=origin,
+                            filename=filename,
+                        )
+                        if result_key is None:
+                            # Session creation failed or resumables are unsupported.
+                            # Send the prepared body without compressing it again.
+                            headers["Content-Length"] = str(compressed_size)
+                            result_key, _, _ = self._put_direct(
+                                body, key, headers, compress=False
+                            )
+            else:
+                result_key, source_size, compressed_size = self._put_direct(
+                    contents, key, headers, compress=compress_with != "none"
+                )
 
-            # Must do this after streaming `body` as that's what is responsible
-            # for advancing the seek position in both streams
-            if precompressed is None:
-                metrics.record_uncompressed_size(original_body.tell())
-            if encoding != "none":
-                metrics.record_compressed_size(body.tell(), encoding)
+            if precompressed is None and source_size is not None:
+                metrics.record_uncompressed_size(source_size)
+            if encoding != "none" and compressed_size is not None:
+                metrics.record_compressed_size(compressed_size, encoding)
 
             # Set after the response, since the key may be server-generated.
-            span.set_attribute("objectstore.key", res["key"])
+            span.set_attribute("objectstore.key", result_key)
             span.set_attribute("objectstore.compression", encoding)
             if metrics.uncompressed_size is not None:
                 span.set_attribute(
@@ -484,7 +586,62 @@ class Session:
                 span.set_attribute(
                     "objectstore.compressed_size", metrics.compressed_size
                 )
-            return res["key"]
+            return result_key
+
+    def _put_direct(
+        self,
+        contents: bytes | IO[bytes],
+        key: str | None,
+        headers: dict[str, str],
+        compress: bool,
+    ) -> tuple[str, int | None, int | None]:
+        """Return the key and final source/body positions when available."""
+        with (
+            BytesIO(contents) if isinstance(contents, bytes) else nullcontext(contents)
+        ) as original_body:
+            body = original_body
+            retries = None  # by default use the pool's value, set by the Client
+            try:
+                if compress:
+                    cctx = zstandard.ZstdCompressor()
+                    body = cctx.stream_reader(original_body, closefd=False)
+                    body = cast(IO[bytes], utils._ZstdCompressionReaderWrapper(body))
+
+                if compress:
+                    # For on-the-fly compression, don't attempt read retries,
+                    # as the stream cannot be rewound after data has been consumed.
+                    pool_retries = self._pool.retries
+                    if isinstance(pool_retries, urllib3.Retry):
+                        retries = pool_retries.new(read=0)
+                    elif isinstance(pool_retries, int):
+                        retries = urllib3.Retry(pool_retries, read=0)
+
+                response = self._pool.request(
+                    "POST" if not key else "PUT",
+                    self._make_url(key),
+                    body=body,
+                    headers=headers,
+                    preload_content=True,
+                    decode_content=True,
+                    retries=retries,
+                )
+                raise_for_status(response)
+                res = response.json()
+
+                # Read positions after streaming, without failing an upload if
+                # the source does not support tell().
+                try:
+                    source_size = original_body.tell()
+                except (AttributeError, OSError, ValueError):
+                    source_size = None
+                try:
+                    compressed_size = body.tell()
+                except (AttributeError, OSError, ValueError):
+                    compressed_size = None
+                return res["key"], source_size, compressed_size
+            finally:
+                if body is not original_body:
+                    body.close()
 
     def get(
         self,
@@ -779,6 +936,74 @@ class Session:
             )
             raise_for_status(response)
 
+    def _create_upload(
+        self,
+        object_length: int,
+        key: str | None = None,
+        compression: Compression | None = None,
+        content_type: str | None = None,
+        metadata: dict[str, str] | None = None,
+        expiration_policy: ExpirationPolicy | None = None,
+        origin: str | None = None,
+        filename: str | None = None,
+    ) -> _resumable.ResumableUpload | None:
+        """Create a resumable upload, or return None if the server declines.
+
+        `object_length` is the total length of the object to be uploaded.
+        Unlike regular uploads, the client does not automatically compress chunk
+        contents.
+        The caller must pre-compress the object according to `compression`, then
+        create the upload with the post-compression `object_length`. Offsets
+        similarly refer to the bytes after compression.
+        """
+        if object_length < 0:
+            raise ValueError("Object length must not be negative")
+        if compression is not None and compression not in ("none", "zstd"):
+            raise ValueError(f"Invalid compression: {compression}")
+
+        headers = self._metadata_headers(
+            compression=compression,
+            content_type=content_type,
+            metadata=metadata,
+            expiration_policy=expiration_policy,
+            origin=origin,
+            filename=filename,
+        )
+        headers["Upload-Length"] = str(object_length)
+
+        key = key or None
+        with (
+            storage_span(
+                "resumable.create", self._usecase, self._scope, key=key
+            ) as span,
+            measure_storage_operation(
+                self._metrics_backend, "resumable.create", self._usecase.name
+            ),
+        ):
+            response = self._pool.request(
+                "PUT" if key else "POST",
+                f"{self._make_url(key)}?upload_type=resumable",
+                headers=headers,
+                preload_content=True,
+                decode_content=True,
+            )
+            if response.status == 501:
+                return None
+            raise_for_status(response)
+            res = response.json()
+            span.set_attribute("objectstore.key", res["key"])
+            return _resumable.ResumableUpload(
+                self,
+                res["key"],
+                res["session"],
+                object_length,
+                res.get("granularity", 0),
+            )
+
+    def _resume_upload(self, key: str, token: str) -> _resumable.ResumableUpload:
+        """Reconstruct a resumable upload handle, without contacting the server."""
+        return _resumable.ResumableUpload(self, key, token)
+
     def initiate_multipart_upload(
         self,
         *,
@@ -805,28 +1030,14 @@ class Session:
         if compression and compression not in ("none", "zstd"):
             raise ValueError(f"Invalid compression: {compression}")
 
-        headers = self._make_headers()
-
-        compression = compression or self._usecase._compression
-        if compression and compression != "none":
-            headers["Content-Encoding"] = compression
-
-        if content_type:
-            headers["Content-Type"] = content_type
-
-        expiration_policy = expiration_policy or self._usecase._expiration_policy
-        if expiration_policy:
-            headers[HEADER_EXPIRATION] = format_expiration(expiration_policy)
-
-        if origin:
-            headers[HEADER_ORIGIN] = utils.encode_header_value(origin)
-
-        if filename is not None:
-            headers[HEADER_FILENAME] = utils.encode_header_value(filename)
-
-        if metadata:
-            for k, v in metadata.items():
-                headers[f"{HEADER_META_PREFIX}{k}"] = utils.encode_header_value(v)
+        headers = self._metadata_headers(
+            compression=compression or self._usecase._compression,
+            content_type=content_type,
+            metadata=metadata,
+            expiration_policy=expiration_policy,
+            origin=origin,
+            filename=filename,
+        )
 
         if key == "":
             key = None

{objectstore_client-0.2.8 → objectstore_client-0.2.10}/src/objectstore_client/errors.py

@@ -6,7 +6,7 @@ import urllib3
 class RequestError(Exception):
     """Exception raised if an API call to Objectstore fails."""
 
-    def __init__(self, message: str, status: int, response: str):
+    def __init__(self, message: str, status: int | None, response: str | None):
         super().__init__(message)
         self.status = status
         self.response = response