3tears-object-store 0.14.0__tar.gz

3tears_object_store-0.14.0/.gitignore

@@ -0,0 +1,216 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+#poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+#pdm.lock
+#pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+#pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+# Abstra
+# Abstra is an AI-powered process automation framework.
+# Ignore directories containing user credentials, local state, and settings.
+# Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#  Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#  that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#  and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#  you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Cursor
+#  Cursor is an AI-powered code editor. `.cursorignore` specifies files/directories to
+#  exclude from AI features like autocomplete and code analysis. Recommended for sensitive data
+#  refer to https://docs.cursor.com/context/ignore-files
+.cursorignore
+.cursorindexingignore
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Claude Code local state
+.claude/
+
+# prawduct session evidence (local governance artifacts, never shipped)
+.prawduct/
+
+# macOS folder metadata
+.DS_Store

3tears_object_store-0.14.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mark Pace
+
+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.

3tears_object_store-0.14.0/PKG-INFO

@@ -0,0 +1,51 @@
+Metadata-Version: 2.4
+Name: 3tears-object-store
+Version: 0.14.0
+Summary: Streaming S3-compatible object store for large binary artifacts (Path-2)
+Project-URL: Repository, https://github.com/pacepace/3tears
+Author: pace
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.14
+Requires-Dist: 3tears
+Requires-Dist: 3tears-media-contracts
+Requires-Dist: 3tears-observe
+Requires-Dist: aioboto3>=13
+Description-Content-Type: text/markdown
+
+# 3tears-object-store
+
+Streaming S3-compatible object store for large binary artifacts (Path-2 of
+the scope-and-objects design): pcaps, DB dumps, rendered reports, evidence.
+
+Implements the dependency-free `ObjectStore` protocol from
+`3tears-media-contracts` over any S3-compatible backend (MinIO in dev, S3 in
+prod). **Streaming by contract** — uploads move through one part-size buffer
+at a time via S3 multipart; downloads yield the response body in chunks — so
+a multi-GB object never has to sit whole in a pod's memory.
+
+Keys follow the platform's locked scope-first scheme (`keys.build_object_key`):
+
+```
+<customer_id>/<scope>/<category>/<YYYY>/<MM>/<DD>/<object_id>/<filename>
+```
+
+Lifted from metallm's `S3Service` and made streaming.
+
+## Dependency note
+
+`aioboto3` (the async S3 client) tracks `aiobotocore`, which caps `botocore`
+below the latest sync-`boto3` release. Adding this package therefore pins the
+workspace's `botocore`/`boto3` lower and transitively pulls `wrapt` and `lxml`
+down a major version. That cap is inherent to using an async S3 client and is
+accepted — the full 3tears suite is green under the resolved set. If any
+package comes to rely on `wrapt>=2` or `lxml>=6` behavior, add an explicit
+lower bound at the workspace level so resolution fails loudly instead of
+silently regressing.

3tears_object_store-0.14.0/README.md

@@ -0,0 +1,29 @@
+# 3tears-object-store
+
+Streaming S3-compatible object store for large binary artifacts (Path-2 of
+the scope-and-objects design): pcaps, DB dumps, rendered reports, evidence.
+
+Implements the dependency-free `ObjectStore` protocol from
+`3tears-media-contracts` over any S3-compatible backend (MinIO in dev, S3 in
+prod). **Streaming by contract** — uploads move through one part-size buffer
+at a time via S3 multipart; downloads yield the response body in chunks — so
+a multi-GB object never has to sit whole in a pod's memory.
+
+Keys follow the platform's locked scope-first scheme (`keys.build_object_key`):
+
+```
+<customer_id>/<scope>/<category>/<YYYY>/<MM>/<DD>/<object_id>/<filename>
+```
+
+Lifted from metallm's `S3Service` and made streaming.
+
+## Dependency note
+
+`aioboto3` (the async S3 client) tracks `aiobotocore`, which caps `botocore`
+below the latest sync-`boto3` release. Adding this package therefore pins the
+workspace's `botocore`/`boto3` lower and transitively pulls `wrapt` and `lxml`
+down a major version. That cap is inherent to using an async S3 client and is
+accepted — the full 3tears suite is green under the resolved set. If any
+package comes to rely on `wrapt>=2` or `lxml>=6` behavior, add an explicit
+lower bound at the workspace level so resolution fails loudly instead of
+silently regressing.

3tears_object_store-0.14.0/pyproject.toml

@@ -0,0 +1,44 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "3tears-object-store"
+version = "0.14.0"
+description = "Streaming S3-compatible object store for large binary artifacts (Path-2)"
+readme = "README.md"
+requires-python = ">=3.14"
+authors = [{name = "pace"}]
+license = "MIT"
+license-files = ["LICENSE"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Framework :: AsyncIO",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Software Development :: Libraries",
+    "Typing :: Typed",
+]
+# the contract is dependency-free (media-contracts); this impl package
+# isolates the aioboto3 (-> aiobotocore -> botocore) S3 client tree so it
+# never leaks into the contract or its other consumers. core (``3tears``) is
+# pulled in for the secret_refs resolver used by the wiring helper -- core is
+# foundational + acyclic and brings no aioboto3, so the isolation still holds.
+dependencies = [
+    "3tears",
+    "3tears-media-contracts",
+    "3tears-observe",
+    "aioboto3>=13",
+]
+
+[project.urls]
+Repository = "https://github.com/pacepace/3tears"
+
+[tool.uv.sources]
+3tears = { workspace = true }
+3tears-media-contracts = { workspace = true }
+3tears-observe = { workspace = true }
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/threetears"]

3tears_object_store-0.14.0/src/threetears/object_store/__init__.py

@@ -0,0 +1,11 @@
+"""Streaming S3-compatible object store for large binary artifacts (Path-2)."""
+
+# the key builder is a CONTRACT (the locked scope-first layout), so it lives in
+# the dependency-free media-contracts package -- a producing tool can build a key
+# without inheriting this package's aioboto3 client tree. re-exported here for
+# back-compat with callers importing it off the impl package.
+from threetears.media.contracts.keys import build_object_key, sanitize_segment
+from threetears.object_store.s3 import S3ObjectStore
+from threetears.object_store.wiring import build_s3_object_store
+
+__all__ = ["S3ObjectStore", "build_object_key", "build_s3_object_store", "sanitize_segment"]

3tears_object_store-0.14.0/src/threetears/object_store/s3.py

@@ -0,0 +1,354 @@
+"""Streaming S3-compatible object store (aioboto3).
+
+Implements :class:`threetears.media.contracts.ObjectStore` over any
+S3-compatible backend (MinIO in dev, S3 in prod). Never buffers a whole
+object: uploads stream through one part-size buffer at a time via S3
+multipart (or a single PUT when the whole object fits one part); downloads
+yield the response body in chunks. Lifted from metallm's ``S3Service`` and
+made streaming.
+"""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator
+from typing import Any
+
+import aioboto3  # type: ignore[import-untyped]
+from botocore.config import Config as BotoConfig  # type: ignore[import-untyped]
+from botocore.exceptions import ClientError  # type: ignore[import-untyped]
+from threetears.media.contracts import ObjectListing, ObjectStore
+from threetears.observe import get_logger
+
+__all__ = ["S3ObjectStore"]
+
+log = get_logger(__name__)
+
+#: S3 multipart parts must be >= 5 MiB (except the final part). The default
+#: part size doubles as the upload buffer ceiling -- one part-size buffer is
+#: the most memory a single ``put`` holds, regardless of total object size.
+_MIN_PART_SIZE = 5 * 1024 * 1024
+_DEFAULT_PART_SIZE = 8 * 1024 * 1024
+
+#: streamed-download chunk size.
+_DOWNLOAD_CHUNK_SIZE = 1024 * 1024
+
+#: S3 ``DeleteObjects`` accepts at most 1000 keys per request; the reconciler
+#: sweep batches to this ceiling.
+_DELETE_BATCH_SIZE = 1000
+
+
+class S3ObjectStore:
+    """Streaming ObjectStore over an S3-compatible backend.
+
+    :param endpoint_url: S3 endpoint (e.g. ``http://minio:9000``); ``None``
+        uses the AWS default endpoint
+    :ptype endpoint_url: str | None
+    :param access_key: access key id
+    :ptype access_key: str
+    :param secret_key: secret access key
+    :ptype secret_key: str
+    :param bucket: target bucket name
+    :ptype bucket: str
+    :param region: AWS region (MinIO ignores it; AWS S3 requires it)
+    :ptype region: str
+    :param part_size_bytes: multipart part size / upload buffer ceiling;
+        must be >= 5 MiB
+    :ptype part_size_bytes: int
+    :param session: aioboto3 session to use; defaults to a fresh
+        ``aioboto3.Session()``. Injectable so tests can supply a fake client.
+    :ptype session: Any
+    """
+
+    def __init__(
+        self,
+        *,
+        endpoint_url: str | None,
+        access_key: str,
+        secret_key: str,
+        bucket: str,
+        region: str = "us-east-1",
+        part_size_bytes: int = _DEFAULT_PART_SIZE,
+        session: Any = None,
+    ) -> None:
+        if part_size_bytes < _MIN_PART_SIZE:
+            raise ValueError("part_size_bytes must be >= 5 MiB (S3 multipart minimum)")
+        self._endpoint_url = endpoint_url
+        self._access_key = access_key
+        self._secret_key = secret_key
+        self._bucket = bucket
+        self._region = region
+        self._part_size = part_size_bytes
+        self._session = session if session is not None else aioboto3.Session()
+
+    def _client(self) -> Any:
+        """Return an async-context-manager S3 client.
+
+        :return: aioboto3 client context manager
+        :rtype: Any
+        """
+        return self._session.client(
+            "s3",
+            endpoint_url=self._endpoint_url,
+            aws_access_key_id=self._access_key,
+            aws_secret_access_key=self._secret_key,
+            region_name=self._region,
+            config=BotoConfig(signature_version="s3v4"),
+        )
+
+    async def ensure_bucket(self) -> None:
+        """Create the configured bucket if it does not already exist.
+
+        :return: nothing
+        :rtype: None
+        """
+        async with self._client() as client:
+            try:
+                await client.head_bucket(Bucket=self._bucket)
+            except ClientError as err:
+                code = str(err.response.get("Error", {}).get("Code", ""))
+                if code not in ("404", "NoSuchBucket", "NotFound"):
+                    raise
+                await client.create_bucket(Bucket=self._bucket)
+                log.info(
+                    "object store bucket created",
+                    extra={"extra_data": {"bucket": self._bucket}},
+                )
+
+    async def put(
+        self,
+        key: str,
+        body: AsyncIterator[bytes],
+        *,
+        content_type: str,
+        size: int | None = None,
+    ) -> None:
+        """Stream ``body`` to ``key``.
+
+        Peak memory is one part plus the latest incoming chunk -- bounded
+        independent of total object size (a multi-GB object never sits whole
+        in memory). A single PUT is used when the whole object fits one
+        part, otherwise S3 multipart. On any failure the partial multipart
+        upload is aborted so no orphaned parts linger.
+
+        :param key: tenant-scoped object key
+        :ptype key: str
+        :param body: async iterator yielding the object's bytes in chunks
+        :ptype body: AsyncIterator[bytes]
+        :param content_type: MIME type stored on the object
+        :ptype content_type: str
+        :param size: total byte length when known (advisory; the impl
+            streams regardless)
+        :ptype size: int | None
+        :return: nothing
+        :rtype: None
+        """
+        async with self._client() as client:
+            buffer = bytearray()
+            upload_id: str | None = None
+            parts: list[dict[str, Any]] = []
+            part_number = 1
+            completed = False
+            try:
+                async for chunk in body:
+                    buffer.extend(chunk)
+                    while len(buffer) >= self._part_size:
+                        if upload_id is None:
+                            created = await client.create_multipart_upload(
+                                Bucket=self._bucket,
+                                Key=key,
+                                ContentType=content_type,
+                            )
+                            upload_id = created["UploadId"]
+                        part = bytes(buffer[: self._part_size])
+                        del buffer[: self._part_size]
+                        resp = await client.upload_part(
+                            Bucket=self._bucket,
+                            Key=key,
+                            PartNumber=part_number,
+                            UploadId=upload_id,
+                            Body=part,
+                        )
+                        parts.append({"ETag": resp["ETag"], "PartNumber": part_number})
+                        part_number += 1
+                if upload_id is None:
+                    await client.put_object(
+                        Bucket=self._bucket,
+                        Key=key,
+                        Body=bytes(buffer),
+                        ContentType=content_type,
+                    )
+                else:
+                    if buffer:
+                        resp = await client.upload_part(
+                            Bucket=self._bucket,
+                            Key=key,
+                            PartNumber=part_number,
+                            UploadId=upload_id,
+                            Body=bytes(buffer),
+                        )
+                        parts.append({"ETag": resp["ETag"], "PartNumber": part_number})
+                    await client.complete_multipart_upload(
+                        Bucket=self._bucket,
+                        Key=key,
+                        UploadId=upload_id,
+                        MultipartUpload={"Parts": parts},
+                    )
+                completed = True
+            finally:
+                if upload_id is not None and not completed:
+                    try:
+                        await client.abort_multipart_upload(Bucket=self._bucket, Key=key, UploadId=upload_id)
+                        log.info(
+                            "aborted partial multipart upload after error",
+                            extra={"extra_data": {"key": key, "upload_id": upload_id}},
+                        )
+                    except ClientError as abort_err:
+                        log.warning(
+                            "failed to abort multipart upload after error",
+                            extra={
+                                "extra_data": {
+                                    "key": key,
+                                    "upload_id": upload_id,
+                                    "error": str(abort_err),
+                                }
+                            },
+                        )
+        log.debug(
+            "object stored",
+            extra={
+                "extra_data": {
+                    "key": key,
+                    "multipart": upload_id is not None,
+                    "parts": len(parts),
+                }
+            },
+        )
+
+    async def open_read(self, key: str) -> AsyncIterator[bytes]:
+        """Open ``key`` for streaming read, yielding bytes in chunks.
+
+        :param key: object key
+        :ptype key: str
+        :return: async iterator over the object's bytes
+        :rtype: AsyncIterator[bytes]
+        """
+        async with self._client() as client:
+            resp = await client.get_object(Bucket=self._bucket, Key=key)
+            async for chunk in resp["Body"].iter_chunks(_DOWNLOAD_CHUNK_SIZE):
+                yield chunk
+
+    async def delete(self, key: str) -> None:
+        """Delete a single object.
+
+        :param key: object key
+        :ptype key: str
+        :return: nothing
+        :rtype: None
+        """
+        async with self._client() as client:
+            await client.delete_object(Bucket=self._bucket, Key=key)
+
+    async def delete_many(self, keys: list[str]) -> None:
+        """Delete many objects, batched to S3's 1000-key request limit.
+
+        The reconciler sweep can exceed 1000 keys, so deletes are chunked
+        into ``_DELETE_BATCH_SIZE`` requests rather than one oversized call
+        S3/MinIO would reject.
+
+        :param keys: object keys to delete
+        :ptype keys: list[str]
+        :return: nothing
+        :rtype: None
+        """
+        if keys:
+            async with self._client() as client:
+                for start in range(0, len(keys), _DELETE_BATCH_SIZE):
+                    batch = keys[start : start + _DELETE_BATCH_SIZE]
+                    await client.delete_objects(
+                        Bucket=self._bucket,
+                        Delete={
+                            "Objects": [{"Key": k} for k in batch],
+                            "Quiet": True,
+                        },
+                    )
+
+    async def _iter_contents(self, prefix: str | None) -> AsyncIterator[dict[str, Any]]:
+        """Yield each ``Contents`` entry across every listing page.
+
+        Shared pagination for :meth:`list_keys` and :meth:`list_entries` so the
+        continuation-token walk lives in one place.
+
+        :param prefix: key-prefix filter, or ``None`` for the whole bucket
+        :ptype prefix: str | None
+        :return: async iterator over raw ``list_objects_v2`` ``Contents`` dicts
+        :rtype: AsyncIterator[dict[str, Any]]
+        """
+        async with self._client() as client:
+            token: str | None = None
+            while True:
+                kwargs: dict[str, Any] = {"Bucket": self._bucket}
+                if prefix is not None:
+                    kwargs["Prefix"] = prefix
+                if token is not None:
+                    kwargs["ContinuationToken"] = token
+                resp = await client.list_objects_v2(**kwargs)
+                for obj in resp.get("Contents", []):
+                    yield obj
+                if not resp.get("IsTruncated"):
+                    break
+                token = resp.get("NextContinuationToken")
+
+    async def list_keys(self, prefix: str | None = None) -> AsyncIterator[str]:
+        """Yield object keys (paginated), optionally restricted to ``prefix``.
+
+        :param prefix: key-prefix filter (e.g. a tenant's ``<customer_id>/``);
+            ``None`` lists the whole bucket
+        :ptype prefix: str | None
+        :return: async iterator over object keys
+        :rtype: AsyncIterator[str]
+        """
+        async for obj in self._iter_contents(prefix):
+            yield obj["Key"]
+
+    async def list_entries(self, prefix: str | None = None) -> AsyncIterator[ObjectListing]:
+        """Yield object listings (key + last-modified + size), optionally by ``prefix``.
+
+        Carries the ``LastModified`` + ``Size`` metadata S3 already returns on a
+        list so the reconciler can judge orphan age without a per-key HEAD.
+
+        :param prefix: key-prefix filter (e.g. a tenant's ``<customer_id>/``);
+            ``None`` lists the whole bucket
+        :ptype prefix: str | None
+        :return: async iterator over object listings
+        :rtype: AsyncIterator[ObjectListing]
+        """
+        async for obj in self._iter_contents(prefix):
+            yield ObjectListing(
+                key=obj["Key"],
+                last_modified=obj["LastModified"],
+                size_bytes=int(obj["Size"]),
+            )
+
+    async def presigned_get_url(self, key: str, *, expires_in: int = 300) -> str:
+        """Presigned GET URL for delivery -- bytes never cross the agent.
+
+        :param key: object key
+        :ptype key: str
+        :param expires_in: URL validity in seconds
+        :ptype expires_in: int
+        :return: presigned URL
+        :rtype: str
+        """
+        async with self._client() as client:
+            url: str = await client.generate_presigned_url(
+                "get_object",
+                Params={"Bucket": self._bucket, "Key": key},
+                ExpiresIn=expires_in,
+            )
+        return url
+
+
+#: static conformance guarantee -- S3ObjectStore must satisfy the ObjectStore
+#: contract this package exists to implement. mypy verifies the structural
+#: match here; a missing or mismatched method fails type-checking.
+_OBJECTSTORE_IMPL: type[ObjectStore] = S3ObjectStore

3tears_object_store-0.14.0/src/threetears/object_store/wiring.py

@@ -0,0 +1,81 @@
+"""Build a configured :class:`S3ObjectStore` from config + secret references.
+
+A producing or consuming pod wires its object store from deployment config:
+``endpoint_url`` + ``bucket`` + ``region`` as plain values, and the S3
+credentials as platform *secret references* (``env://`` in dev, ``k8s://`` in
+prod) that this helper resolves at construction via
+:func:`threetears.core.security.secret_refs.resolve_secret`. The raw
+credentials are unwrapped at the last moment and live only inside the returned
+store -- never logged, never returned, never held in a plain string here.
+
+This lives beside the impl (not in a pod) so every pod -- the pure-``threetears``
+tool pod, an SDK-spawned pod, the reconciler -- wires its store the same tested
+way rather than re-resolving refs by hand.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from threetears.core.security.secret_refs import resolve_secret
+from threetears.observe import get_logger
+from threetears.object_store.s3 import S3ObjectStore
+
+__all__ = ["build_s3_object_store"]
+
+_log = get_logger(__name__)
+
+
+def build_s3_object_store(
+    *,
+    endpoint_url: str | None,
+    bucket: str,
+    access_key_ref: str,
+    secret_key_ref: str,
+    region: str = "us-east-1",
+    session: Any = None,
+) -> S3ObjectStore:
+    """Resolve the credential references and construct a streaming store.
+
+    :param endpoint_url: S3 endpoint (e.g. ``http://minio:9000``); ``None`` uses
+        the AWS default endpoint
+    :ptype endpoint_url: str | None
+    :param bucket: target bucket name
+    :ptype bucket: str
+    :param access_key_ref: secret reference for the access key id
+        (``env://VAR`` / ``k8s://path``); resolved here
+    :ptype access_key_ref: str
+    :param secret_key_ref: secret reference for the secret access key; resolved here
+    :ptype secret_key_ref: str
+    :param region: AWS region (MinIO ignores it; AWS S3 requires it)
+    :ptype region: str
+    :param session: aioboto3 session passthrough for tests; ``None`` lets the
+        store create its own
+    :ptype session: Any
+    :return: a streaming object store ready to put/get/delete
+    :rtype: S3ObjectStore
+    :raises SecretResolutionError: when either credential reference is malformed,
+        names an unknown/unimplemented scheme, or cannot be resolved
+    """
+    access_key = resolve_secret(access_key_ref).get_secret_value()
+    secret_key = resolve_secret(secret_key_ref).get_secret_value()
+    store = S3ObjectStore(
+        endpoint_url=endpoint_url,
+        access_key=access_key,
+        secret_key=secret_key,
+        bucket=bucket,
+        region=region,
+        session=session,
+    )
+    _log.info(
+        "built S3 object store",
+        extra={
+            "extra_data": {
+                # config shape only -- never the resolved credential values.
+                "bucket": bucket,
+                "region": region,
+                "endpoint_configured": endpoint_url is not None,
+            }
+        },
+    )
+    return store

3tears_object_store-0.14.0/tests/integration/test_s3_objectstore.py

@@ -0,0 +1,108 @@
+"""Live integration tests for S3ObjectStore against a running MinIO.
+
+Marked ``integration`` so the default unit run excludes them. Defaults
+target the dev MinIO from the compose stack (localhost:9000, minioadmin,
+bucket ``3tears-objects``); override via ``OBJECT_STORE_*`` env vars.
+"""
+
+from __future__ import annotations
+
+import os
+from collections.abc import AsyncIterator
+
+import pytest
+
+from threetears.object_store.s3 import S3ObjectStore
+
+pytestmark = pytest.mark.integration
+
+_ENDPOINT = os.environ.get("OBJECT_STORE_ENDPOINT", "http://localhost:9000")
+_ACCESS = os.environ.get("OBJECT_STORE_ACCESS_KEY", "minioadmin")
+_SECRET = os.environ.get("OBJECT_STORE_SECRET_KEY", "minioadmin")
+_BUCKET = os.environ.get("OBJECT_STORE_BUCKET", "3tears-objects")
+
+
+def _store(part_size_bytes: int = 8 * 1024 * 1024) -> S3ObjectStore:
+    """Build a store pointed at the dev MinIO.
+
+    :param part_size_bytes: multipart part size
+    :ptype part_size_bytes: int
+    :return: configured store
+    :rtype: S3ObjectStore
+    """
+    return S3ObjectStore(
+        endpoint_url=_ENDPOINT,
+        access_key=_ACCESS,
+        secret_key=_SECRET,
+        bucket=_BUCKET,
+        part_size_bytes=part_size_bytes,
+    )
+
+
+async def _collect(stream: AsyncIterator[bytes]) -> bytes:
+    """Drain a byte stream into one buffer (test helper only).
+
+    :param stream: async byte stream
+    :ptype stream: AsyncIterator[bytes]
+    :return: full content
+    :rtype: bytes
+    """
+    out = bytearray()
+    async for chunk in stream:
+        out.extend(chunk)
+    return bytes(out)
+
+
+async def _aiter(data: bytes, chunk: int) -> AsyncIterator[bytes]:
+    """Yield ``data`` in ``chunk``-sized pieces as an async iterator.
+
+    :param data: source bytes
+    :ptype data: bytes
+    :param chunk: chunk size
+    :ptype chunk: int
+    :return: async byte stream
+    :rtype: AsyncIterator[bytes]
+    """
+    for i in range(0, len(data), chunk):
+        yield data[i : i + chunk]
+
+
+@pytest.mark.asyncio
+async def test_put_get_delete_roundtrip_small() -> None:
+    """A small object round-trips via single PUT + streamed read + presign."""
+    store = _store()
+    key = "itest/small.txt"
+    payload = b"hello streaming object store"
+
+    await store.put(key, _aiter(payload, 4), content_type="text/plain")
+    got = await _collect(store.open_read(key))
+    assert got == payload
+
+    url = await store.presigned_get_url(key)
+    assert "itest/small.txt" in url
+
+    keys = [k async for k in store.list_keys(prefix="itest/")]
+    assert key in keys
+
+    await store.delete(key)
+    after = [k async for k in store.list_keys(prefix="itest/")]
+    assert key not in after
+
+
+@pytest.mark.asyncio
+async def test_put_get_roundtrip_multipart_large() -> None:
+    """An object larger than one part round-trips via multipart upload."""
+    store = _store(part_size_bytes=5 * 1024 * 1024)
+    key = "itest/large.bin"
+    payload = os.urandom(12 * 1024 * 1024)  # 12 MiB -> 3 parts at 5 MiB
+
+    await store.put(
+        key,
+        _aiter(payload, 1024 * 1024),
+        content_type="application/octet-stream",
+        size=len(payload),
+    )
+    got = await _collect(store.open_read(key))
+    assert got == payload
+
+    await store.delete(key)

3tears_object_store-0.14.0/tests/unit/test_s3_streaming.py

@@ -0,0 +1,324 @@
+"""Unit tests for S3ObjectStore streaming/batching branches.
+
+Uses an in-memory fake S3 client injected via the constructor ``session``
+seam, so the critical paths the live-MinIO happy-path can't cheaply cover
+run in CI: empty / exact-multiple / single-giant-chunk / abort-on-failure
+uploads, >1000-key delete batching, and multi-page listing.
+"""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator
+from datetime import UTC, datetime
+from typing import Any
+
+import pytest
+
+from threetears.object_store.s3 import S3ObjectStore
+
+
+# parity-exempt: aiobotocore StreamingBody stub -- botocore's dynamically-built response body has no importable Protocol to declare parity against; only iter_chunks is exercised
+class _FakeBody:
+    """Streaming body stub exposing aiobotocore's ``iter_chunks``."""
+
+    def __init__(self, data: bytes) -> None:
+        self._data = data
+
+    async def iter_chunks(self, size: int) -> AsyncIterator[bytes]:
+        """Yield the body in ``size``-byte chunks.
+
+        :param size: chunk size
+        :ptype size: int
+        :return: async byte stream
+        :rtype: AsyncIterator[bytes]
+        """
+        for i in range(0, len(self._data), size):
+            yield self._data[i : i + size]
+
+
+class _S3State:
+    """In-memory backend state shared across clients from one fake session."""
+
+    def __init__(self) -> None:
+        self.objects: dict[str, bytes] = {}
+        self.mtimes: dict[str, datetime] = {}
+        self.delete_batches: list[list[str]] = []
+        self.aborted: list[str] = []
+        self.completed: list[str] = []
+        self.page_size: int = 1000
+        self.fail_part: int | None = None
+
+
+# parity-exempt: aioboto3 S3 client stub -- a botocore-generated client with hundreds of operations and no importable Protocol; only the get/put/list/delete/presign calls S3ObjectStore makes are stubbed
+class _FakeS3Client:
+    """Minimal in-memory S3 client matching the calls S3ObjectStore makes."""
+
+    def __init__(self, state: _S3State) -> None:
+        self._s = state
+        self._mpu: dict[str, dict[int, bytes]] = {}
+        self._counter = 0
+
+    async def __aenter__(self) -> _FakeS3Client:
+        return self
+
+    async def __aexit__(self, *exc: object) -> bool:
+        return False
+
+    async def create_multipart_upload(self, *, Bucket: str, Key: str, ContentType: str | None = None) -> dict[str, Any]:
+        self._counter += 1
+        uid = f"mpu-{self._counter}"
+        self._mpu[uid] = {}
+        return {"UploadId": uid}
+
+    async def upload_part(
+        self, *, Bucket: str, Key: str, PartNumber: int, UploadId: str, Body: bytes
+    ) -> dict[str, Any]:
+        if self._s.fail_part is not None and PartNumber == self._s.fail_part:
+            raise RuntimeError("simulated upload_part failure")
+        self._mpu[UploadId][PartNumber] = bytes(Body)
+        return {"ETag": f'"etag-{PartNumber}"'}
+
+    async def complete_multipart_upload(
+        self, *, Bucket: str, Key: str, UploadId: str, MultipartUpload: dict[str, Any]
+    ) -> dict[str, Any]:
+        stored = self._mpu.pop(UploadId)
+        self._s.objects[Key] = b"".join(stored[p["PartNumber"]] for p in MultipartUpload["Parts"])
+        self._s.completed.append(Key)
+        return {}
+
+    async def abort_multipart_upload(self, *, Bucket: str, Key: str, UploadId: str) -> dict[str, Any]:
+        self._mpu.pop(UploadId, None)
+        self._s.aborted.append(Key)
+        return {}
+
+    async def put_object(self, *, Bucket: str, Key: str, Body: bytes, ContentType: str | None = None) -> dict[str, Any]:
+        self._s.objects[Key] = bytes(Body)
+        return {}
+
+    async def get_object(self, *, Bucket: str, Key: str) -> dict[str, Any]:
+        return {"Body": _FakeBody(self._s.objects[Key])}
+
+    async def delete_object(self, *, Bucket: str, Key: str) -> dict[str, Any]:
+        self._s.objects.pop(Key, None)
+        return {}
+
+    async def delete_objects(self, *, Bucket: str, Delete: dict[str, Any]) -> dict[str, Any]:
+        batch = [o["Key"] for o in Delete["Objects"]]
+        self._s.delete_batches.append(batch)
+        for k in batch:
+            self._s.objects.pop(k, None)
+        return {}
+
+    async def list_objects_v2(
+        self, *, Bucket: str, Prefix: str | None = None, ContinuationToken: str | None = None
+    ) -> dict[str, Any]:
+        matched = sorted(k for k in self._s.objects if Prefix is None or k.startswith(Prefix))
+        start = int(ContinuationToken) if ContinuationToken else 0
+        page = matched[start : start + self._s.page_size]
+        _epoch = datetime(2020, 1, 1, tzinfo=UTC)
+        resp: dict[str, Any] = {
+            "Contents": [
+                {
+                    "Key": k,
+                    "Size": len(self._s.objects[k]),
+                    "LastModified": self._s.mtimes.get(k, _epoch),
+                }
+                for k in page
+            ]
+        }
+        if start + self._s.page_size < len(matched):
+            resp["IsTruncated"] = True
+            resp["NextContinuationToken"] = str(start + self._s.page_size)
+        return resp
+
+
+# parity-exempt: aioboto3 Session.client() factory stub -- an external SDK context-manager factory with no importable Protocol to mirror
+class _FakeSession:
+    """Fake aioboto3 session handing out fresh in-memory clients."""
+
+    def __init__(self, state: _S3State) -> None:
+        self._state = state
+
+    def client(self, *args: object, **kwargs: object) -> _FakeS3Client:
+        """Return a fresh fake client over the shared state.
+
+        :return: fake S3 client
+        :rtype: _FakeS3Client
+        """
+        return _FakeS3Client(self._state)
+
+
+def _store(state: _S3State, *, part_size_bytes: int = 5 * 1024 * 1024) -> S3ObjectStore:
+    """Build a store wired to the in-memory fake session.
+
+    :param state: shared fake backend state
+    :ptype state: _S3State
+    :param part_size_bytes: multipart part size
+    :ptype part_size_bytes: int
+    :return: store under test
+    :rtype: S3ObjectStore
+    """
+    return S3ObjectStore(
+        endpoint_url=None,
+        access_key="k",
+        secret_key="s",
+        bucket="b",
+        part_size_bytes=part_size_bytes,
+        session=_FakeSession(state),
+    )
+
+
+async def _aiter(data: bytes, chunk: int) -> AsyncIterator[bytes]:
+    """Yield ``data`` in ``chunk``-sized pieces.
+
+    :param data: source bytes
+    :ptype data: bytes
+    :param chunk: chunk size
+    :ptype chunk: int
+    :return: async byte stream
+    :rtype: AsyncIterator[bytes]
+    """
+    for i in range(0, len(data), chunk):
+        yield data[i : i + chunk]
+
+
+async def _empty() -> AsyncIterator[bytes]:
+    """An empty async byte stream.
+
+    :return: async byte stream that yields nothing
+    :rtype: AsyncIterator[bytes]
+    """
+    if False:  # pragma: no cover
+        yield b""
+
+
+@pytest.mark.asyncio
+async def test_put_empty_object_uses_single_put() -> None:
+    """A 0-byte object stores via a single empty PUT (no multipart)."""
+    state = _S3State()
+    await _store(state).put("k/empty", _empty(), content_type="application/octet-stream")
+    assert state.objects["k/empty"] == b""
+    assert state.completed == []
+
+
+@pytest.mark.asyncio
+async def test_put_small_object_uses_single_put() -> None:
+    """An object under one part stores via a single PUT."""
+    state = _S3State()
+    await _store(state).put("k/small", _aiter(b"hello", 2), content_type="text/plain")
+    assert state.objects["k/small"] == b"hello"
+    assert state.completed == []
+
+
+@pytest.mark.asyncio
+async def test_put_exact_multiple_skips_empty_final_part() -> None:
+    """An object exactly N*part_size completes without a 0-byte final part."""
+    part = 5 * 1024 * 1024
+    state = _S3State()
+    payload = b"x" * (2 * part)
+    await _store(state, part_size_bytes=part).put(
+        "k/exact", _aiter(payload, part), content_type="application/octet-stream"
+    )
+    assert state.objects["k/exact"] == payload
+    assert state.completed == ["k/exact"]
+
+
+@pytest.mark.asyncio
+async def test_put_multipart_with_remainder() -> None:
+    """A full part plus a remainder round-trips via multipart."""
+    part = 5 * 1024 * 1024
+    state = _S3State()
+    payload = b"y" * (part + 1234)
+    await _store(state, part_size_bytes=part).put(
+        "k/rem", _aiter(payload, 65536), content_type="application/octet-stream"
+    )
+    assert state.objects["k/rem"] == payload
+
+
+@pytest.mark.asyncio
+async def test_put_single_chunk_larger_than_part() -> None:
+    """One giant incoming chunk is drained into multiple parts."""
+    part = 5 * 1024 * 1024
+    state = _S3State()
+    payload = b"z" * (3 * part)
+    await _store(state, part_size_bytes=part).put(
+        "k/big", _aiter(payload, 3 * part), content_type="application/octet-stream"
+    )
+    assert state.objects["k/big"] == payload
+
+
+@pytest.mark.asyncio
+async def test_put_aborts_multipart_on_mid_stream_failure() -> None:
+    """A failure mid-upload aborts the multipart -- no orphaned parts."""
+    part = 5 * 1024 * 1024
+    state = _S3State()
+    state.fail_part = 2
+    payload = b"w" * (3 * part)
+    with pytest.raises(RuntimeError, match="simulated upload_part failure"):
+        await _store(state, part_size_bytes=part).put(
+            "k/fail", _aiter(payload, part), content_type="application/octet-stream"
+        )
+    assert state.aborted == ["k/fail"]
+    assert "k/fail" not in state.objects
+
+
+@pytest.mark.asyncio
+async def test_delete_many_batches_over_the_1000_key_limit() -> None:
+    """>1000 keys are chunked into <=1000-key DeleteObjects requests."""
+    state = _S3State()
+    keys = [f"k/{i}" for i in range(2500)]
+    await _store(state).delete_many(keys)
+    assert [len(b) for b in state.delete_batches] == [1000, 1000, 500]
+    assert all(len(b) <= 1000 for b in state.delete_batches)
+
+
+@pytest.mark.asyncio
+async def test_delete_many_empty_is_noop() -> None:
+    """Deleting an empty list issues no request."""
+    state = _S3State()
+    await _store(state).delete_many([])
+    assert state.delete_batches == []
+
+
+@pytest.mark.asyncio
+async def test_list_keys_paginates_and_filters_by_prefix() -> None:
+    """list_keys walks every page and honors the prefix filter."""
+    state = _S3State()
+    state.page_size = 2
+    for i in range(5):
+        state.objects[f"p/{i}"] = b"x"
+    state.objects["other"] = b"x"
+    keys = [k async for k in _store(state).list_keys(prefix="p/")]
+    assert sorted(keys) == ["p/0", "p/1", "p/2", "p/3", "p/4"]
+
+
+@pytest.mark.asyncio
+async def test_list_entries_carries_key_size_and_mtime() -> None:
+    """list_entries paginates and yields each object's key, size, and mtime."""
+    state = _S3State()
+    state.page_size = 2
+    older = datetime(2021, 6, 1, tzinfo=UTC)
+    newer = datetime(2023, 6, 1, tzinfo=UTC)
+    state.objects["p/old"] = b"abc"
+    state.mtimes["p/old"] = older
+    state.objects["p/new"] = b"defgh"
+    state.mtimes["p/new"] = newer
+    state.objects["p/mid"] = b"z"
+    state.objects["other"] = b"x"
+    entries = {e.key: e async for e in _store(state).list_entries(prefix="p/")}
+    assert sorted(entries) == ["p/mid", "p/new", "p/old"]
+    assert entries["p/old"].size_bytes == 3
+    assert entries["p/old"].last_modified == older
+    assert entries["p/new"].size_bytes == 5
+    assert entries["p/new"].last_modified == newer
+    # unset mtime falls back to the fake's epoch default, never crashes
+    assert entries["p/mid"].last_modified == datetime(2020, 1, 1, tzinfo=UTC)
+
+
+@pytest.mark.asyncio
+async def test_open_read_streams_back_the_object() -> None:
+    """open_read yields the stored bytes in chunks."""
+    state = _S3State()
+    state.objects["k/r"] = b"abcdefgh"
+    chunks = [c async for c in _store(state).open_read("k/r")]
+    assert b"".join(chunks) == b"abcdefgh"

3tears_object_store-0.14.0/tests/unit/test_wiring.py

@@ -0,0 +1,106 @@
+"""Tests for build_s3_object_store -- secret-ref resolution into a store.
+
+A capturing fake session records the kwargs the store hands to ``session.client``
+when it opens a connection, so we can assert the RESOLVED credentials + the
+endpoint/region config reach the S3 client without touching the store's private
+attributes (the store deliberately exposes none).
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+import pytest
+
+from threetears.core.security.secret_refs import SecretResolutionError
+from threetears.object_store.wiring import build_s3_object_store
+
+
+class _NoopClient:
+    """An S3 client stub that satisfies the ensure_bucket() call path."""
+
+    async def __aenter__(self) -> _NoopClient:
+        return self
+
+    async def __aexit__(self, *exc: object) -> bool:
+        return False
+
+    async def head_bucket(self, **kwargs: object) -> dict[str, Any]:
+        return {}
+
+
+class _CapturingSession:
+    """Fake aioboto3 session recording the kwargs of the last client() call."""
+
+    def __init__(self) -> None:
+        self.client_kwargs: dict[str, Any] | None = None
+
+    def client(self, *args: object, **kwargs: Any) -> _NoopClient:
+        self.client_kwargs = kwargs
+        return _NoopClient()
+
+
+async def test_resolved_creds_and_config_reach_the_client(monkeypatch: pytest.MonkeyPatch) -> None:
+    """env:// refs resolve and flow (with endpoint/region) into session.client()."""
+    monkeypatch.setenv("TEST_S3_ACCESS_KEY", "AKIA-RESOLVED")
+    monkeypatch.setenv("TEST_S3_SECRET_KEY", "SECRET-RESOLVED")
+    session = _CapturingSession()
+    store = build_s3_object_store(
+        endpoint_url="http://minio:9000",
+        bucket="3tears-objects",
+        access_key_ref="env://TEST_S3_ACCESS_KEY",
+        secret_key_ref="env://TEST_S3_SECRET_KEY",
+        region="eu-west-1",
+        session=session,
+    )
+    # opening a client (ensure_bucket) is what hands the resolved creds to aioboto3.
+    await store.ensure_bucket()
+    assert session.client_kwargs is not None
+    assert session.client_kwargs["aws_access_key_id"] == "AKIA-RESOLVED"
+    assert session.client_kwargs["aws_secret_access_key"] == "SECRET-RESOLVED"
+    assert session.client_kwargs["endpoint_url"] == "http://minio:9000"
+    assert session.client_kwargs["region_name"] == "eu-west-1"
+
+
+def test_no_credential_value_is_logged(monkeypatch: pytest.MonkeyPatch, caplog: pytest.LogCaptureFixture) -> None:
+    """The build log emits config shape only -- never the resolved secret values."""
+    monkeypatch.setenv("TEST_AK", "AKIA-SUPERSECRET-VALUE")
+    monkeypatch.setenv("TEST_SK", "SK-SUPERSECRET-VALUE")
+    with caplog.at_level(logging.DEBUG, logger="threetears.object_store.wiring"):
+        build_s3_object_store(
+            endpoint_url="http://minio:9000",
+            bucket="b",
+            access_key_ref="env://TEST_AK",
+            secret_key_ref="env://TEST_SK",
+        )
+    blob = " ".join(
+        [r.getMessage() for r in caplog.records] + [repr(getattr(r, "extra_data", None)) for r in caplog.records]
+    )
+    assert "AKIA-SUPERSECRET-VALUE" not in blob
+    assert "SK-SUPERSECRET-VALUE" not in blob
+    # sanity: the build log actually fired, so the assertion above is not vacuous.
+    assert any("built S3 object store" in r.getMessage() for r in caplog.records)
+
+
+def test_unknown_scheme_ref_raises(monkeypatch: pytest.MonkeyPatch) -> None:
+    """A credential ref naming an unknown scheme fails closed at build time."""
+    monkeypatch.setenv("TEST_S3_SECRET_KEY", "ok")
+    with pytest.raises(SecretResolutionError):
+        build_s3_object_store(
+            endpoint_url=None,
+            bucket="b",
+            access_key_ref="bogus://nope",
+            secret_key_ref="env://TEST_S3_SECRET_KEY",
+        )
+
+
+def test_missing_env_ref_raises() -> None:
+    """An env:// ref pointing at an unset variable fails closed at build time."""
+    with pytest.raises(SecretResolutionError):
+        build_s3_object_store(
+            endpoint_url=None,
+            bucket="b",
+            access_key_ref="env://DEFINITELY_UNSET_S3_KEY_XYZ",
+            secret_key_ref="env://ALSO_UNSET_S3_SECRET_XYZ",
+        )