objectstore-client 0.0.2__tar.gz

objectstore_client-0.0.2/LICENSE.md

@@ -0,0 +1,105 @@
+# Functional Source License, Version 1.1, Apache 2.0 Future License
+
+## Abbreviation
+
+FSL-1.1-Apache-2.0
+
+## Notice
+
+Copyright 2018-2024 Functional Software, Inc. dba Sentry
+
+## Terms and Conditions
+
+### Licensor ("We")
+
+The party offering the Software under these Terms and Conditions.
+
+### The Software
+
+The "Software" is each version of the software that we make available under
+these Terms and Conditions, as indicated by our inclusion of these Terms and
+Conditions with the Software.
+
+### License Grant
+
+Subject to your compliance with this License Grant and the Patents,
+Redistribution and Trademark clauses below, we hereby grant you the right to
+use, copy, modify, create derivative works, publicly perform, publicly display
+and redistribute the Software for any Permitted Purpose identified below.
+
+### Permitted Purpose
+
+A Permitted Purpose is any purpose other than a Competing Use. A Competing Use
+means making the Software available to others in a commercial product or
+service that:
+
+1. substitutes for the Software;
+
+2. substitutes for any other product or service we offer using the Software
+   that exists as of the date we make the Software available; or
+
+3. offers the same or substantially similar functionality as the Software.
+
+Permitted Purposes specifically include using the Software:
+
+1. for your internal use and access;
+
+2. for non-commercial education;
+
+3. for non-commercial research; and
+
+4. in connection with professional services that you provide to a licensee
+   using the Software in accordance with these Terms and Conditions.
+
+### Patents
+
+To the extent your use for a Permitted Purpose would necessarily infringe our
+patents, the license grant above includes a license under our patents. If you
+make a claim against any party that the Software infringes or contributes to
+the infringement of any patent, then your patent license to the Software ends
+immediately.
+
+### Redistribution
+
+The Terms and Conditions apply to all copies, modifications and derivatives of
+the Software.
+
+If you redistribute any copies, modifications or derivatives of the Software,
+you must include a copy of or a link to these Terms and Conditions and not
+remove any copyright notices provided in or with the Software.
+
+### Disclaimer
+
+THE SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTIES OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING WITHOUT LIMITATION WARRANTIES OF FITNESS FOR A PARTICULAR
+PURPOSE, MERCHANTABILITY, TITLE OR NON-INFRINGEMENT.
+
+IN NO EVENT WILL WE HAVE ANY LIABILITY TO YOU ARISING OUT OF OR RELATED TO THE
+SOFTWARE, INCLUDING INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES,
+EVEN IF WE HAVE BEEN INFORMED OF THEIR POSSIBILITY IN ADVANCE.
+
+### Trademarks
+
+Except for displaying the License Details and identifying us as the origin of
+the Software, you have no right under these Terms and Conditions to use our
+trademarks, trade names, service marks or product names.
+
+## Grant of Future License
+
+We hereby irrevocably grant you an additional license to use the Software under
+the Apache License, Version 2.0 that is effective on the second anniversary of
+the date we make the Software available. On or after that date, you may use the
+Software under the Apache License, Version 2.0, in which case the following
+will apply:
+
+Licensed under the Apache License, Version 2.0 (the "License"); you may not use
+this file except in compliance with the License.
+
+You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed
+under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
+CONDITIONS OF ANY KIND, either express or implied. See the License for the
+specific language governing permissions and limitations under the License.

objectstore_client-0.0.2/PKG-INFO

@@ -0,0 +1,168 @@
+Metadata-Version: 2.3
+Name: objectstore-client
+Version: 0.0.2
+Summary: Client SDK for Objectstore, the Sentry object storage platform
+Author: Sentry
+Author-email: Sentry <oss@sentry.io>
+License: # Functional Source License, Version 1.1, Apache 2.0 Future License
+         
+         ## Abbreviation
+         
+         FSL-1.1-Apache-2.0
+         
+         ## Notice
+         
+         Copyright 2018-2024 Functional Software, Inc. dba Sentry
+         
+         ## Terms and Conditions
+         
+         ### Licensor ("We")
+         
+         The party offering the Software under these Terms and Conditions.
+         
+         ### The Software
+         
+         The "Software" is each version of the software that we make available under
+         these Terms and Conditions, as indicated by our inclusion of these Terms and
+         Conditions with the Software.
+         
+         ### License Grant
+         
+         Subject to your compliance with this License Grant and the Patents,
+         Redistribution and Trademark clauses below, we hereby grant you the right to
+         use, copy, modify, create derivative works, publicly perform, publicly display
+         and redistribute the Software for any Permitted Purpose identified below.
+         
+         ### Permitted Purpose
+         
+         A Permitted Purpose is any purpose other than a Competing Use. A Competing Use
+         means making the Software available to others in a commercial product or
+         service that:
+         
+         1. substitutes for the Software;
+         
+         2. substitutes for any other product or service we offer using the Software
+            that exists as of the date we make the Software available; or
+         
+         3. offers the same or substantially similar functionality as the Software.
+         
+         Permitted Purposes specifically include using the Software:
+         
+         1. for your internal use and access;
+         
+         2. for non-commercial education;
+         
+         3. for non-commercial research; and
+         
+         4. in connection with professional services that you provide to a licensee
+            using the Software in accordance with these Terms and Conditions.
+         
+         ### Patents
+         
+         To the extent your use for a Permitted Purpose would necessarily infringe our
+         patents, the license grant above includes a license under our patents. If you
+         make a claim against any party that the Software infringes or contributes to
+         the infringement of any patent, then your patent license to the Software ends
+         immediately.
+         
+         ### Redistribution
+         
+         The Terms and Conditions apply to all copies, modifications and derivatives of
+         the Software.
+         
+         If you redistribute any copies, modifications or derivatives of the Software,
+         you must include a copy of or a link to these Terms and Conditions and not
+         remove any copyright notices provided in or with the Software.
+         
+         ### Disclaimer
+         
+         THE SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTIES OF ANY KIND, EXPRESS OR
+         IMPLIED, INCLUDING WITHOUT LIMITATION WARRANTIES OF FITNESS FOR A PARTICULAR
+         PURPOSE, MERCHANTABILITY, TITLE OR NON-INFRINGEMENT.
+         
+         IN NO EVENT WILL WE HAVE ANY LIABILITY TO YOU ARISING OUT OF OR RELATED TO THE
+         SOFTWARE, INCLUDING INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES,
+         EVEN IF WE HAVE BEEN INFORMED OF THEIR POSSIBILITY IN ADVANCE.
+         
+         ### Trademarks
+         
+         Except for displaying the License Details and identifying us as the origin of
+         the Software, you have no right under these Terms and Conditions to use our
+         trademarks, trade names, service marks or product names.
+         
+         ## Grant of Future License
+         
+         We hereby irrevocably grant you an additional license to use the Software under
+         the Apache License, Version 2.0 that is effective on the second anniversary of
+         the date we make the Software available. On or after that date, you may use the
+         Software under the Apache License, Version 2.0, in which case the following
+         will apply:
+         
+         Licensed under the Apache License, Version 2.0 (the "License"); you may not use
+         this file except in compliance with the License.
+         
+         You may obtain a copy of the License at
+         
+         http://www.apache.org/licenses/LICENSE-2.0
+         
+         Unless required by applicable law or agreed to in writing, software distributed
+         under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
+         CONDITIONS OF ANY KIND, either express or implied. See the License for the
+         specific language governing permissions and limitations under the License.
+Requires-Dist: sentry-sdk>=2.42.1
+Requires-Dist: urllib3>=2.5.0
+Requires-Dist: zstandard>=0.18.0
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+
+# Objectstore Client
+
+The client is used to interface with the objectstore backend. It handles
+responsibilities like transparent compression, and making sure that uploads and
+downloads are done as efficiently as possible.
+
+## Usage
+
+```python
+import datetime
+
+from objectstore_client import ClientBuilder, NoOpMetricsBackend, TimeToLive
+
+client_builder = ClientBuilder(
+    "http://localhost:8888",
+    "my_usecase",
+    metrics_backend=NoOpMetricsBackend(),  # optionally, provide your own MetricsBackend implementation
+)
+client = client_builder.for_project(42, 424242)
+
+object_id = client.put(
+    b"Hello, world!",
+    metadata={"key": "value"},
+    expiration_policy=TimeToLive(datetime.timedelta(days=1)),
+)
+
+result = client.get(object_id)
+
+content = result.payload.read()
+assert content == b"Hello, world!"
+assert result.metadata.custom["key"] == "value"
+
+client.delete(object_id)
+```
+
+## Development
+
+### Environment Setup
+
+The considerations for setting up the development environment that can be found in the main [README](../README.md) apply for this package as well.
+
+### Pre-commit hook
+
+A configuration to set up a git pre-commit hook using [pre-commit](https://github.com/pre-commit/pre-commit) is available at the root of the repository.
+
+To install it, run
+```sh
+pre-commit install
+```
+
+The hook will automatically run some checks before every commit, including the linters and formatters we run in CI.

objectstore_client-0.0.2/README.md

@@ -0,0 +1,51 @@
+# Objectstore Client
+
+The client is used to interface with the objectstore backend. It handles
+responsibilities like transparent compression, and making sure that uploads and
+downloads are done as efficiently as possible.
+
+## Usage
+
+```python
+import datetime
+
+from objectstore_client import ClientBuilder, NoOpMetricsBackend, TimeToLive
+
+client_builder = ClientBuilder(
+    "http://localhost:8888",
+    "my_usecase",
+    metrics_backend=NoOpMetricsBackend(),  # optionally, provide your own MetricsBackend implementation
+)
+client = client_builder.for_project(42, 424242)
+
+object_id = client.put(
+    b"Hello, world!",
+    metadata={"key": "value"},
+    expiration_policy=TimeToLive(datetime.timedelta(days=1)),
+)
+
+result = client.get(object_id)
+
+content = result.payload.read()
+assert content == b"Hello, world!"
+assert result.metadata.custom["key"] == "value"
+
+client.delete(object_id)
+```
+
+## Development
+
+### Environment Setup
+
+The considerations for setting up the development environment that can be found in the main [README](../README.md) apply for this package as well.
+
+### Pre-commit hook
+
+A configuration to set up a git pre-commit hook using [pre-commit](https://github.com/pre-commit/pre-commit) is available at the root of the repository.
+
+To install it, run
+```sh
+pre-commit install
+```
+
+The hook will automatically run some checks before every commit, including the linters and formatters we run in CI.

objectstore_client-0.0.2/pyproject.toml

@@ -0,0 +1,21 @@
+[project]
+name = "objectstore-client"
+version = "0.0.2"
+description = "Client SDK for Objectstore, the Sentry object storage platform"
+readme = "README.md"
+authors = [
+    {name = "Sentry", email = "oss@sentry.io"},
+]
+homepage = "https://getsentry.github.io/objectstore/"
+repository = "https://github.com/getsentry/objectstore"
+license = { file = "LICENSE.md" }
+requires-python = ">=3.13"
+dependencies = [
+    "sentry-sdk>=2.42.1",
+    "urllib3>=2.5.0",
+    "zstandard>=0.18.0",
+]
+
+[build-system]
+requires = ["uv_build"]
+build-backend = "uv_build"

objectstore_client-0.0.2/src/objectstore_client/__init__.py

@@ -0,0 +1,23 @@
+from objectstore_client.client import Client, ClientBuilder, ClientError, GetResult
+from objectstore_client.metadata import (
+    Compression,
+    ExpirationPolicy,
+    Metadata,
+    TimeToIdle,
+    TimeToLive,
+)
+from objectstore_client.metrics import MetricsBackend, NoOpMetricsBackend
+
+__all__ = [
+    "Client",
+    "ClientBuilder",
+    "ClientError",
+    "GetResult",
+    "Compression",
+    "ExpirationPolicy",
+    "Metadata",
+    "TimeToIdle",
+    "TimeToLive",
+    "MetricsBackend",
+    "NoOpMetricsBackend",
+]

objectstore_client-0.0.2/src/objectstore_client/client.py

@@ -0,0 +1,269 @@
+from __future__ import annotations
+
+from io import BytesIO
+from typing import IO, Literal, NamedTuple, NotRequired, Self, TypedDict, cast
+from urllib.parse import urlencode
+
+import sentry_sdk
+import urllib3
+import zstandard
+from urllib3.connectionpool import HTTPConnectionPool
+
+from objectstore_client.metadata import (
+    HEADER_EXPIRATION,
+    HEADER_META_PREFIX,
+    Compression,
+    ExpirationPolicy,
+    Metadata,
+    format_expiration,
+)
+from objectstore_client.metrics import (
+    MetricsBackend,
+    NoOpMetricsBackend,
+    measure_storage_operation,
+)
+
+Permission = Literal["read", "write"]
+
+
+class Scope(TypedDict):
+    organization: int
+    project: NotRequired[int]
+
+
+class GetResult(NamedTuple):
+    metadata: Metadata
+    payload: IO[bytes]
+
+
+class ClientBuilder:
+    def __init__(
+        self,
+        objectstore_base_url: str,
+        usecase: str,
+        metrics_backend: MetricsBackend | None = None,
+        propagate_traces: bool = False,
+        default_expiration_policy: ExpirationPolicy | None = None,
+        retries: urllib3.Retry | None = None,
+        timeout: urllib3.Timeout | None = None,
+    ):
+        self._base_url = objectstore_base_url
+        self._usecase = usecase
+
+        # We only retry connection problems, as we cannot rewind our compression stream.
+        self._retries = retries or urllib3.Retry(connect=3, redirect=5)
+        # The read timeout is defined to be "between consecutive read operations",
+        # which should mean one chunk of the response, with a large response being
+        # split into multiple chunks.
+        # We define both as 500ms which is still very conservative,
+        # given that we are in the same network,
+        # and expect our backends to respond in <100ms.
+        self._timeout =  timeout or urllib3.Timeout(connect=0.5, read=0.5)
+
+        self._default_compression: Compression = "zstd"
+        self._default_expiration_policy = (
+            format_expiration(default_expiration_policy)
+            if default_expiration_policy
+            else None
+        )
+        self._propagate_traces = propagate_traces
+        self._metrics_backend = metrics_backend or NoOpMetricsBackend()
+
+    def _make_client(self, scope: str) -> Client:
+        pool = urllib3.connectionpool.connection_from_url(
+            self._base_url, retries=self._retries, timeout=self._timeout
+        )
+        return Client(
+            pool,
+            self._default_compression,
+            self._default_expiration_policy,
+            self._usecase,
+            scope,
+            self._propagate_traces,
+            self._metrics_backend,
+        )
+
+    def default_compression(self, default_compression: Compression) -> Self:
+        self._default_compression = default_compression
+        return self
+
+    def for_organization(self, organization_id: int) -> Client:
+        return self._make_client(f"org.{organization_id}")
+
+    def for_project(self, organization_id: int, project_id: int) -> Client:
+        return self._make_client(f"org.{organization_id}/proj.{project_id}")
+
+
+class Client:
+    _default_compression: Compression
+
+    def __init__(
+        self,
+        pool: HTTPConnectionPool,
+        default_compression: Compression,
+        default_expiration_policy: str | None,
+        usecase: str,
+        scope: str,
+        propagate_traces: bool,
+        metrics_backend: MetricsBackend,
+    ):
+        self._pool = pool
+        self._default_compression = default_compression
+        self._default_expiration_policy = default_expiration_policy
+        self._usecase = usecase
+        self._scope = scope
+        self._propagate_traces = propagate_traces
+        self._metrics_backend = metrics_backend
+
+    def _make_headers(self) -> dict[str, str]:
+        if self._propagate_traces:
+            return dict(sentry_sdk.get_current_scope().iter_trace_propagation_headers())
+        return {}
+
+    def _make_url(self, id: str | None, full: bool = False) -> str:
+        base_path = f"/v1/{id}" if id else "/v1/"
+        qs = urlencode({"usecase": self._usecase, "scope": self._scope})
+        if full:
+            return f"http://{self._pool.host}:{self._pool.port}{base_path}?{qs}"
+        else:
+            return f"{base_path}?{qs}"
+
+    def put(
+        self,
+        contents: bytes | IO[bytes],
+        id: str | None = None,
+        compression: Compression | Literal["none"] | None = None,
+        content_type: str | None = None,
+        metadata: dict[str, str] | None = None,
+        expiration_policy: ExpirationPolicy | None = None,
+    ) -> str:
+        """
+        Uploads the given `contents` to blob storage.
+
+        If no `id` is provided, one will be automatically generated and returned
+        from this function.
+
+        The client will select the configured `default_compression` if none is given
+        explicitly.
+        This can be overridden by explicitly giving a `compression` argument.
+        Providing `"none"` as the argument will instruct the client to not apply
+        any compression to this upload, which is useful for uncompressible formats.
+        """
+        headers = self._make_headers()
+        body = BytesIO(contents) if isinstance(contents, bytes) else contents
+        original_body: IO[bytes] = body
+
+        compression = compression or self._default_compression
+        if compression == "zstd":
+            cctx = zstandard.ZstdCompressor()
+            body = cctx.stream_reader(original_body)
+            headers["Content-Encoding"] = "zstd"
+
+        if content_type:
+            headers["Content-Type"] = content_type
+
+        if expiration_policy:
+            headers[HEADER_EXPIRATION] = format_expiration(expiration_policy)
+        elif self._default_expiration_policy:
+            headers[HEADER_EXPIRATION] = self._default_expiration_policy
+
+        if metadata:
+            for k, v in metadata.items():
+                headers[f"{HEADER_META_PREFIX}{k}"] = v
+
+        with measure_storage_operation(
+            self._metrics_backend, "put", self._usecase
+        ) as metric_emitter:
+            response = self._pool.request(
+                "PUT",
+                self._make_url(id),
+                body=body,
+                headers=headers,
+                preload_content=True,
+                decode_content=True,
+            )
+            raise_for_status(response)
+            res = response.json()
+
+            # Must do this after streaming `body` as that's what is responsible
+            # for advancing the seek position in both streams
+            metric_emitter.record_uncompressed_size(original_body.tell())
+            if compression and compression != "none":
+                metric_emitter.record_compressed_size(body.tell(), compression)
+            return res["key"]
+
+    def get(self, id: str, decompress: bool = True) -> GetResult:
+        """
+        This fetches the blob with the given `id`, returning an `IO` stream that
+        can be read.
+
+        By default, content that was uploaded compressed will be automatically
+        decompressed, unless `decompress=True` is passed.
+        """
+
+        headers = self._make_headers()
+        with measure_storage_operation(self._metrics_backend, "get", self._usecase):
+            response = self._pool.request(
+                "GET",
+                self._make_url(id),
+                preload_content=False,
+                decode_content=False,
+                headers=headers,
+            )
+            raise_for_status(response)
+        # OR: should I use `response.stream()`?
+        stream = cast(IO[bytes], response)
+        metadata = Metadata.from_headers(response.headers)
+
+        if metadata.compression and decompress:
+            if metadata.compression != "zstd":
+                raise NotImplementedError(
+                    "Transparent decoding of anything but `zstd` is not implemented yet"
+                )
+
+            metadata.compression = None
+            dctx = zstandard.ZstdDecompressor()
+            stream = dctx.stream_reader(stream, read_across_frames=True)
+
+        return GetResult(metadata, stream)
+
+    def object_url(self, id: str) -> str:
+        """
+        Generates a GET url to the object with the given `id`.
+
+        This can then be used by downstream services to fetch the given object.
+        NOTE however that the service does not strictly follow HTTP semantics,
+        in particular in relation to `Accept-Encoding`.
+        """
+        return self._make_url(id, full=True)
+
+    def delete(self, id: str) -> None:
+        """
+        Deletes the blob with the given `id`.
+        """
+
+        headers = self._make_headers()
+        with measure_storage_operation(self._metrics_backend, "delete", self._usecase):
+            response = self._pool.request(
+                "DELETE",
+                self._make_url(id),
+                headers=headers,
+            )
+            raise_for_status(response)
+
+
+class ClientError(Exception):
+    def __init__(self, message: str, status: int, response: str):
+        super().__init__(message)
+        self.status = status
+        self.response = response
+
+
+def raise_for_status(response: urllib3.BaseHTTPResponse) -> None:
+    if response.status >= 400:
+        res = str(response.data or response.read())
+        raise ClientError(
+            f"Objectstore request failed with status {response.status}",
+            response.status,
+            res,
+        )

objectstore_client-0.0.2/src/objectstore_client/metadata.py

@@ -0,0 +1,112 @@
+from __future__ import annotations
+
+import itertools
+import re
+from collections.abc import Mapping
+from dataclasses import dataclass
+from datetime import timedelta
+from typing import Literal, cast
+
+Compression = Literal["zstd"]
+
+HEADER_EXPIRATION = "x-sn-expiration"
+HEADER_META_PREFIX = "x-snme-"
+
+
+@dataclass
+class TimeToIdle:
+    delta: timedelta
+
+
+@dataclass
+class TimeToLive:
+    delta: timedelta
+
+
+ExpirationPolicy = TimeToIdle | TimeToLive
+
+
+@dataclass
+class Metadata:
+    content_type: str | None
+    compression: Compression | None
+    expiration_policy: ExpirationPolicy | None
+    custom: dict[str, str]
+
+    @classmethod
+    def from_headers(cls, headers: Mapping[str, str]) -> Metadata:
+        content_type = "application/octet-stream"
+        compression = None
+        expiration_policy = None
+        custom_metadata = {}
+
+        for k, v in headers.items():
+            if k == "content-type":
+                content_type = v
+            elif k == "content-encoding":
+                compression = cast(Compression | None, v)
+            elif k == HEADER_EXPIRATION:
+                expiration_policy = parse_expiration(v)
+            elif k.startswith(HEADER_META_PREFIX):
+                custom_metadata[k[len(HEADER_META_PREFIX) :]] = v
+
+        return Metadata(
+            content_type=content_type,
+            compression=compression,
+            expiration_policy=expiration_policy,
+            custom=custom_metadata,
+        )
+
+
+def format_expiration(expiration_policy: ExpirationPolicy) -> str:
+    if isinstance(expiration_policy, TimeToIdle):
+        return f"tti:{format_timedelta(expiration_policy.delta)}"
+    elif isinstance(expiration_policy, TimeToLive):
+        return f"ttl:{format_timedelta(expiration_policy.delta)}"
+
+
+def parse_expiration(value: str) -> ExpirationPolicy | None:
+    if value.startswith("tti:"):
+        return TimeToIdle(parse_timedelta(value[4:]))
+    elif value.startswith("ttl:"):
+        return TimeToLive(parse_timedelta(value[4:]))
+
+    return None
+
+
+def format_timedelta(delta: timedelta) -> str:
+    days = delta.days
+    output = f"{days} days" if days else ""
+    if seconds := delta.seconds:
+        if output:
+            output += " "
+        output += f"{seconds} seconds"
+
+    return output
+
+
+TIME_SPLIT = re.compile(r"[^\W\d_]+|\d+")
+
+
+def parse_timedelta(delta: str) -> timedelta:
+    words = TIME_SPLIT.findall(delta)
+    seconds = 0
+
+    for num, unit in itertools.batched(words, n=2, strict=True):
+        num = int(num)
+        multiplier = 0
+
+        if unit.startswith("w"):
+            multiplier = 86400 * 7
+        elif unit.startswith("d"):
+            multiplier = 86400
+        elif unit.startswith("h"):
+            multiplier = 3600
+        elif unit.startswith("m") and not unit.startswith("ms"):
+            multiplier = 60
+        elif unit.startswith("s"):
+            multiplier = 1
+
+        seconds += num * multiplier
+
+    return timedelta(seconds=seconds)

objectstore_client-0.0.2/src/objectstore_client/metrics.py

@@ -0,0 +1,182 @@
+from __future__ import annotations
+
+import time
+from abc import abstractmethod
+from collections.abc import Generator, Mapping
+from contextlib import contextmanager
+from typing import Protocol, runtime_checkable
+
+Tags = Mapping[str, str]
+
+
+@runtime_checkable
+class MetricsBackend(Protocol):
+    """
+    An abstract class that defines the interface for metrics backends.
+    """
+
+    @abstractmethod
+    def increment(
+        self,
+        name: str,
+        value: int | float = 1,
+        tags: Tags | None = None,
+    ) -> None:
+        """
+        Increments a counter metric by a given value.
+        """
+        raise NotImplementedError
+
+    @abstractmethod
+    def gauge(self, name: str, value: int | float, tags: Tags | None = None) -> None:
+        """
+        Sets a gauge metric to the given value.
+        """
+        raise NotImplementedError
+
+    @abstractmethod
+    def distribution(
+        self,
+        name: str,
+        value: int | float,
+        tags: Tags | None = None,
+        unit: str | None = None,
+    ) -> None:
+        """
+        Records a distribution metric.
+        """
+        raise NotImplementedError
+
+
+class NoOpMetricsBackend(MetricsBackend):
+    """
+    Default metrics backend that does not record anything.
+    """
+
+    def increment(
+        self,
+        name: str,
+        value: int | float = 1,
+        tags: Tags | None = None,
+    ) -> None:
+        pass
+
+    def gauge(self, name: str, value: int | float, tags: Tags | None = None) -> None:
+        pass
+
+    def distribution(
+        self,
+        name: str,
+        value: int | float,
+        tags: Tags | None = None,
+        unit: str | None = None,
+    ) -> None:
+        pass
+
+
+class StorageMetricEmitter:
+    def __init__(self, backend: MetricsBackend, operation: str, usecase: str):
+        self.backend = backend
+        self.operation = operation
+        self.usecase = usecase
+
+        # These may be set during or after the enclosed operation
+        self.start: int | None = None
+        self.elapsed: float | None = None
+        self.uncompressed_size: int | None = None
+        self.compressed_size: int | None = None
+        self.compression: str = "unknown"
+
+    def record_latency(self, elapsed: float) -> None:
+        tags = {"usecase": self.usecase}
+        self.backend.distribution(
+            f"storage.{self.operation}.latency", elapsed, tags=tags
+        )
+        self.elapsed = elapsed
+
+    def record_uncompressed_size(self, value: int) -> None:
+        tags = {"usecase": self.usecase, "compression": "none"}
+        self.backend.distribution(
+            f"storage.{self.operation}.size", value, tags=tags, unit="byte"
+        )
+        self.uncompressed_size = value
+
+    def record_compressed_size(self, value: int, compression: str = "unknown") -> None:
+        tags = {"usecase": self.usecase, "compression": compression}
+        self.backend.distribution(
+            f"storage.{self.operation}.size", value, tags=tags, unit="byte"
+        )
+        self.compressed_size = value
+        self.compression = compression
+
+    def maybe_record_compression_ratio(self) -> None:
+        if not self.uncompressed_size or not self.compressed_size:
+            return None
+
+        tags = {"usecase": self.usecase, "compression": self.compression}
+        self.backend.distribution(
+            f"storage.{self.operation}.compression_ratio",
+            self.compressed_size / self.uncompressed_size,
+            tags=tags,
+        )
+
+    def maybe_record_throughputs(self) -> None:
+        if not self.elapsed or self.elapsed <= 0:
+            return None
+
+        sizes = []
+        if self.uncompressed_size:
+            sizes.append((self.uncompressed_size, "none"))
+        if self.compressed_size:
+            sizes.append((self.compressed_size, self.compression))
+
+        for size, compression in sizes:
+            tags = {"usecase": self.usecase, "compression": compression}
+            self.backend.distribution(
+                f"storage.{self.operation}.throughput", size / self.elapsed, tags=tags
+            )
+            self.backend.distribution(
+                f"storage.{self.operation}.inverse_throughput",
+                self.elapsed / size,
+                tags=tags,
+            )
+
+
+@contextmanager
+def measure_storage_operation(
+    backend: MetricsBackend,
+    operation: str,
+    usecase: str,
+    uncompressed_size: int | None = None,
+    compressed_size: int | None = None,
+    compression: str = "unknown",
+) -> Generator[StorageMetricEmitter]:
+    """
+    Context manager which records the latency of the enclosed storage operation.
+    Can also record the compressed or uncompressed size of an object, the
+    compression ratio, the throughput, and the inverse throughput.
+
+    Yields a `StorageMetricEmitter` because for some operations (GET) the size
+    is not known until the inside of the enclosed block.
+    """
+    emitter = StorageMetricEmitter(backend, operation, usecase)
+
+    if uncompressed_size:
+        emitter.record_uncompressed_size(uncompressed_size)
+    if compressed_size:
+        emitter.record_compressed_size(compressed_size, compression)
+
+    start = time.monotonic()
+
+    # Yield an emitter in case the size becomes known inside the enclosed block
+    try:
+        yield emitter
+
+    finally:
+        elapsed = time.monotonic() - start
+        emitter.record_latency(elapsed)
+
+        # If `uncompressed_size` and/or `compressed_size` have been set, we have
+        # extra metrics we can send.
+        emitter.maybe_record_compression_ratio()
+        emitter.maybe_record_throughputs()