3tears-backup 0.16.0__py3-none-any.whl

3tears_backup-0.16.0.dist-info/METADATA

@@ -0,0 +1,41 @@
+Metadata-Version: 2.4
+Name: 3tears-backup
+Version: 0.16.0
+Summary: Encrypted, GFS-rotated database backups to any ObjectStore, with restore verification
+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 :: Database
+Classifier: Topic :: System :: Archiving :: Backup
+Classifier: Typing :: Typed
+Requires-Python: >=3.14
+Requires-Dist: 3tears-media-contracts
+Requires-Dist: 3tears-object-store
+Requires-Dist: 3tears-observe
+Description-Content-Type: text/markdown
+
+# 3tears-backup
+
+Encrypted, grandfather-father-son (GFS) rotated **database backups** to any
+`ObjectStore`, with **restore verification** — built on 3tears primitives so it
+drops into any 3tears app.
+
+- **Storage-agnostic.** The engine takes an injected `ObjectStore`
+  (`3tears-object-store` — S3 is the first driver, filesystem the second) and
+  streams the dump through `EncryptedObjectStore`, so a multi-GB dump is
+  client-side AES-256-GCM encrypted and never sits whole in memory.
+- **Postgres *and* Yugabyte.** A pluggable `DbDumpDriver` wraps the right dump
+  tool; the engine autodetects the target from `version()`.
+- **GFS retention.** Keep N daily / weekly / monthly backups; prune the rest.
+- **Restore-verified.** Backups are proven by restoring into a throwaway
+  temporary database, with an optional hook to spin a stack against it.
+
+Configuration is an injected, frozen `BackupConfig` — construct it however you
+like (a `from_env` factory reads `THREETEARS_BACKUP_*` with defaults; most apps
+will build it from control-plane settings instead).

3tears_backup-0.16.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+threetears/backup/__init__.py,sha256=Q0wHoXRe93VkKcAXONLOD_3oMbIAdI29v9Nhb077ra8,1089
+threetears/backup/config.py,sha256=NvqI8MzZEPwkekRLSvAOl2e6_pB2uAjdupp1K5mLykk,4358
+threetears/backup/drivers.py,sha256=7-xkpxiMrtgJzvhF89xUvBUhI7J6cIXb9fXTDUJpXDU,4505
+threetears/backup/engine.py,sha256=FXW7MOEAbQ0CjfODiKuzV_hsOvpiDJ_MTqc5Cwn25wM,6864
+threetears/backup/gzip.py,sha256=eQSug2NINbmxquvaGnpeb52c_qJIpLUf8LmktRxxcWs,1637
+threetears/backup/process.py,sha256=a0XcIWRXfytQnoppIeXYLDyHFM4MkxygTKHV7YoAxu8,7437
+threetears/backup/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+threetears/backup/retention.py,sha256=2pR-QJgIhO7mRNpS_pAIg3jQh9HefX9N0BMwezPiRiM,5366
+threetears/backup/verify.py,sha256=6IzFGmnwsUIHQQhcfxIuMaKKD3uExDHdLFJIThE7DRE,7705
+3tears_backup-0.16.0.dist-info/METADATA,sha256=GuBmWkzT-roxoJ5ogY_fT8NHjYLVshLl_bqmiBRG8vc,1836
+3tears_backup-0.16.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+3tears_backup-0.16.0.dist-info/licenses/LICENSE,sha256=7GWEoEOcFJenZLt4LDzqH2K7QLxo_2m8rzG7Vv8VGXo,1066
+3tears_backup-0.16.0.dist-info/RECORD,,

3tears_backup-0.16.0.dist-info/WHEEL

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

3tears_backup-0.16.0.dist-info/licenses/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.

threetears/backup/__init__.py

@@ -0,0 +1,44 @@
+"""Encrypted, GFS-rotated database backups to any ObjectStore, with restore verification."""
+
+from threetears.backup.config import BackupConfig
+from threetears.backup.drivers import (
+    DbDumpDriver,
+    PostgresDriver,
+    YugabyteDriver,
+    detect_driver,
+    driver_for_version,
+)
+from threetears.backup.engine import BackupEngine, DeleteNotAllowedError
+from threetears.backup.process import BackupToolError
+from threetears.backup.retention import (
+    BackupRecord,
+    GfsRetention,
+    RetentionDecision,
+)
+from threetears.backup.verify import (
+    RestoreVerifier,
+    VerificationResult,
+    count_tables,
+    make_subprocess_hook,
+    make_temp_db_provisioner,
+)
+
+__all__ = [
+    "BackupConfig",
+    "BackupEngine",
+    "BackupRecord",
+    "BackupToolError",
+    "DbDumpDriver",
+    "DeleteNotAllowedError",
+    "GfsRetention",
+    "PostgresDriver",
+    "RestoreVerifier",
+    "RetentionDecision",
+    "VerificationResult",
+    "YugabyteDriver",
+    "count_tables",
+    "detect_driver",
+    "driver_for_version",
+    "make_subprocess_hook",
+    "make_temp_db_provisioner",
+]

threetears/backup/config.py

@@ -0,0 +1,93 @@
+"""Injected configuration for the backup engine.
+
+:class:`BackupConfig` is a frozen value object you *pass in* -- the engine never reaches for the
+environment itself. Most apps build it from control-plane settings; :meth:`BackupConfig.from_env`
+is a convenience that reads ``THREETEARS_BACKUP_*`` with sensible defaults for the simple case.
+
+It is deliberately storage-agnostic: there is no bucket here. The backend is an injected
+``ObjectStore`` (which already knows where it writes), so the same config drives an S3 backup or a
+filesystem one. What lives here is the encryption passphrase, the key prefix, the GFS retention
+counts, and the delete safety switch.
+"""
+
+from __future__ import annotations
+
+import os
+from collections.abc import Mapping
+from dataclasses import dataclass
+
+from pydantic import SecretStr
+
+__all__ = ["BackupConfig"]
+
+_ENV_PREFIX = "THREETEARS_BACKUP_"
+
+
+@dataclass(frozen=True, slots=True)
+class BackupConfig:
+    """Backup engine configuration (injected; never self-loaded).
+
+    :param passphrase: AES-256-GCM encryption passphrase (per-object scrypt-derived key).
+    :param prefix: object-key prefix under which backups are written/listed.
+    :param retention_daily: number of daily backups to keep (>= 1).
+    :param retention_weekly: number of weekly backups to keep (>= 1).
+    :param retention_monthly: number of monthly backups to keep (>= 1).
+    :param allow_delete: master switch for destructive operations (delete / retention prune).
+    :param dump_timeout_seconds: wall-clock ceiling for a dump/restore subprocess (> 0).
+    :param encryption_work_factor: scrypt cost N for the per-object key (power of two > 1); the
+        default is deployment-grade, lower it only to trade brute-force resistance for speed.
+    """
+
+    passphrase: SecretStr
+    prefix: str = "backups"
+    retention_daily: int = 7
+    retention_weekly: int = 4
+    retention_monthly: int = 3
+    allow_delete: bool = False
+    dump_timeout_seconds: int = 3600
+    encryption_work_factor: int = 2**18
+
+    def __post_init__(self) -> None:
+        if not self.prefix or self.prefix != self.prefix.strip("/"):
+            raise ValueError("prefix must be non-empty with no leading/trailing '/'")
+        for name in ("retention_daily", "retention_weekly", "retention_monthly"):
+            if getattr(self, name) < 1:
+                raise ValueError(f"{name} must be >= 1")
+        if self.dump_timeout_seconds <= 0:
+            raise ValueError("dump_timeout_seconds must be > 0")
+        if self.encryption_work_factor <= 1 or (self.encryption_work_factor & (self.encryption_work_factor - 1)) != 0:
+            raise ValueError("encryption_work_factor must be a power of two greater than 1")
+        if not self.passphrase.get_secret_value():
+            raise ValueError("passphrase must not be empty")
+
+    @classmethod
+    def from_env(cls, env: Mapping[str, str] | None = None) -> BackupConfig:
+        """Build a config from ``THREETEARS_BACKUP_*`` variables (defaults fill the rest).
+
+        :param env: environment mapping to read (defaults to ``os.environ``).
+        :raises ValueError: when ``THREETEARS_BACKUP_PASSPHRASE`` is unset, or a value is invalid.
+        """
+        source = os.environ if env is None else env
+        passphrase = source.get(f"{_ENV_PREFIX}PASSPHRASE")
+        if not passphrase:
+            raise ValueError(f"{_ENV_PREFIX}PASSPHRASE is required")
+        return cls(
+            passphrase=SecretStr(passphrase),
+            prefix=source.get(f"{_ENV_PREFIX}PREFIX", "backups"),
+            retention_daily=_int(source, "RETENTION_DAILY", 7),
+            retention_weekly=_int(source, "RETENTION_WEEKLY", 4),
+            retention_monthly=_int(source, "RETENTION_MONTHLY", 3),
+            allow_delete=_bool(source, "ALLOW_DELETE", default=False),
+            dump_timeout_seconds=_int(source, "DUMP_TIMEOUT_SECONDS", 3600),
+            encryption_work_factor=_int(source, "ENCRYPTION_WORK_FACTOR", 2**18),
+        )
+
+
+def _int(source: Mapping[str, str], suffix: str, default: int) -> int:
+    raw = source.get(f"{_ENV_PREFIX}{suffix}")
+    return default if raw is None else int(raw)
+
+
+def _bool(source: Mapping[str, str], suffix: str, *, default: bool) -> bool:
+    raw = source.get(f"{_ENV_PREFIX}{suffix}")
+    return default if raw is None else raw.strip().lower() in {"1", "true", "yes", "on"}

threetears/backup/drivers.py

@@ -0,0 +1,109 @@
+"""Pluggable database dump/restore drivers, with Postgres/Yugabyte autodetection.
+
+A driver knows one thing the engine doesn't: which command-line tool dumps and restores its
+database, and with which flags. :class:`PostgresDriver` uses ``pg_dump``/``pg_restore`` (custom
+archive format); :class:`YugabyteDriver` uses ``ysql_dump``/``ysqlsh`` (plain SQL) — Yugabyte
+ships its own fork of the tools. The engine picks one by asking the database ``SELECT version()``:
+Yugabyte stamps ``-YB-`` into its version string (the same tell scriob's ``is_yugabyte`` uses).
+
+The argv builders and :func:`driver_for_version` are pure (unit-tested without a database); the
+actual dump/restore streams through the shared subprocess plumbing in :mod:`threetears.backup.process`.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from collections.abc import AsyncIterator, Mapping
+from typing import ClassVar, Protocol, runtime_checkable
+
+from threetears.backup.process import feed_stdin, stream_stdout
+
+__all__ = ["DbDumpDriver", "PostgresDriver", "YugabyteDriver", "detect_driver", "driver_for_version"]
+
+#: the marker Yugabyte stamps into ``version()`` (e.g. "... (YugabyteDB 2.20 ... -YB-...)").
+_YUGABYTE_MARKER = "-YB-"
+
+
+class DbDumpDriver(ABC):
+    """Abstract dump/restore driver: declares the argv, inherits the streaming."""
+
+    name: ClassVar[str]
+    #: True when the dump format is already compressed (so the engine skips gzip).
+    compressed: ClassVar[bool]
+
+    @abstractmethod
+    def dump_argv(self, dsn: str) -> list[str]:
+        """Argv that dumps ``dsn`` to stdout."""
+
+    @abstractmethod
+    def restore_argv(self, dsn: str) -> list[str]:
+        """Argv that restores into ``dsn`` from stdin."""
+
+    def dump(
+        self, dsn: str, *, env: Mapping[str, str] | None = None, timeout: float | None = None
+    ) -> AsyncIterator[bytes]:
+        """Stream a dump of ``dsn`` as bytes (bounded by ``timeout`` seconds when given)."""
+        return stream_stdout(self.dump_argv(dsn), env=env, timeout=timeout)
+
+    async def restore(
+        self,
+        dsn: str,
+        source: AsyncIterator[bytes],
+        *,
+        env: Mapping[str, str] | None = None,
+        timeout: float | None = None,
+    ) -> None:
+        """Restore ``source`` (a dump stream) into ``dsn`` (bounded by ``timeout`` seconds)."""
+        await feed_stdin(self.restore_argv(dsn), source, env=env, timeout=timeout)
+
+
+class PostgresDriver(DbDumpDriver):
+    """Vanilla PostgreSQL via ``pg_dump`` (custom format) + ``pg_restore``."""
+
+    name: ClassVar[str] = "postgres"
+    compressed: ClassVar[bool] = True  # pg_dump custom format is zlib-compressed already
+
+    def dump_argv(self, dsn: str) -> list[str]:
+        return ["pg_dump", "--dbname", dsn, "--format=custom", "--no-owner", "--no-privileges"]
+
+    def restore_argv(self, dsn: str) -> list[str]:
+        # a fresh (empty) target — the verifier's temp db — so no --clean is needed; fail loudly.
+        return ["pg_restore", "--dbname", dsn, "--no-owner", "--no-privileges", "--exit-on-error"]
+
+
+class YugabyteDriver(DbDumpDriver):
+    """YugabyteDB via ``ysql_dump`` (plain SQL) + ``ysqlsh``."""
+
+    name: ClassVar[str] = "yugabyte"
+    compressed: ClassVar[bool] = False  # ysql_dump emits plain SQL — gzip it
+
+    def dump_argv(self, dsn: str) -> list[str]:
+        return ["ysql_dump", "--dbname", dsn, "--no-owner", "--no-privileges"]
+
+    def restore_argv(self, dsn: str) -> list[str]:
+        # ysqlsh reads SQL from stdin; ON_ERROR_STOP makes a bad statement a non-zero exit.
+        return ["ysqlsh", "--dbname", dsn, "--quiet", "--set", "ON_ERROR_STOP=1"]
+
+
+def driver_for_version(version: str) -> DbDumpDriver:
+    """Pick a driver from a ``version()`` string.
+
+    :param version: the output of ``SELECT version()``.
+    :return: a :class:`YugabyteDriver` if the string carries the Yugabyte marker, else Postgres.
+    """
+    return YugabyteDriver() if _YUGABYTE_MARKER in version else PostgresDriver()
+
+
+@runtime_checkable
+class _VersionSource(Protocol):
+    async def fetchval(self, query: str) -> object: ...
+
+
+async def detect_driver(conn: _VersionSource) -> DbDumpDriver:
+    """Autodetect the driver by querying ``version()`` on an open connection.
+
+    :param conn: anything with an async ``fetchval(query)`` (e.g. an asyncpg connection).
+    :return: the driver matching the connected database engine.
+    """
+    version = await conn.fetchval("SELECT version()")
+    return driver_for_version(str(version))

threetears/backup/engine.py

@@ -0,0 +1,156 @@
+"""The backup engine — encrypted, compressed, GFS-rotated DB backups over any ObjectStore.
+
+:class:`BackupEngine` composes the pieces: it wraps the injected backend store in
+:class:`EncryptedObjectStore` (so backups are encrypted *by construction* — a caller can't
+accidentally write plaintext), streams the driver's dump through gzip when the format isn't already
+compressed, and writes it under a date-partitioned key. Listing, retention pruning, and restore all
+funnel back through the same encrypted store. Destructive operations (delete, retention prune) are
+gated on ``config.allow_delete``.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from datetime import UTC, datetime
+from uuid import uuid7
+
+from threetears.media.contracts import ObjectStore
+from threetears.object_store import EncryptedObjectStore
+from threetears.observe import get_logger
+
+from threetears.backup.config import BackupConfig
+from threetears.backup.drivers import DbDumpDriver
+from threetears.backup.gzip import gunzip_stream, gzip_stream
+from threetears.backup.retention import BackupRecord, GfsRetention, RetentionDecision
+
+__all__ = ["BackupEngine", "DeleteNotAllowedError"]
+
+log = get_logger(__name__)
+
+_ENCRYPTED_CONTENT_TYPE = "application/octet-stream"
+_KEY_STAMP_FORMAT = "%Y%m%dT%H%M%SZ"
+
+
+def _created_at_from_key(key: str, *, fallback: datetime) -> datetime:
+    """Parse the creation timestamp encoded in a backup key's filename.
+
+    Keys are ``<prefix>/<Y>/<m>/<d>/<YYYYMMDDThhmmssZ>-<id>.<driver>.<suffix>.enc``; the stamp is
+    the filename up to the first ``-``. A key we didn't write (no parseable stamp) falls back to the
+    store's last-modified so a foreign object still sorts sanely.
+    """
+    stamp = key.rsplit("/", 1)[-1].split("-", 1)[0]
+    try:
+        parsed = datetime.strptime(stamp, _KEY_STAMP_FORMAT).replace(tzinfo=UTC)
+    except ValueError:
+        parsed = fallback
+    return parsed
+
+
+class DeleteNotAllowedError(RuntimeError):
+    """A destructive operation was attempted while ``config.allow_delete`` is False."""
+
+
+class BackupEngine:
+    """Create / list / restore / prune encrypted database backups.
+
+    :param config: the injected :class:`BackupConfig`.
+    :param store: the backend :class:`ObjectStore` (S3, filesystem, …); wrapped in encryption here.
+    :param driver: the :class:`DbDumpDriver` for the target database.
+    :param env: environment for the dump/restore subprocess (e.g. ``PGPASSWORD``).
+    """
+
+    def __init__(
+        self,
+        config: BackupConfig,
+        store: ObjectStore,
+        driver: DbDumpDriver,
+        *,
+        env: Mapping[str, str] | None = None,
+    ) -> None:
+        self._config = config
+        self._driver = driver
+        self._env = env
+        # encrypt by construction: everything written/read goes through the AEAD wrapper.
+        self._store: ObjectStore = EncryptedObjectStore(
+            store, config.passphrase, scrypt_n=config.encryption_work_factor
+        )
+
+    def _key_for(self, when: datetime) -> str:
+        stamp = when.strftime("%Y%m%dT%H%M%SZ")
+        suffix = "dump" if self._driver.compressed else "dump.gz"
+        return f"{self._config.prefix}/{when:%Y/%m/%d}/{stamp}-{uuid7().hex[:8]}.{self._driver.name}.{suffix}.enc"
+
+    async def create_backup(self, source_dsn: str, *, when: datetime | None = None) -> BackupRecord:
+        """Dump ``source_dsn``, compress+encrypt it, and store it.
+
+        :param source_dsn: connection string of the database to back up.
+        :param when: backup timestamp (defaults to now, UTC) — also the storage partition.
+        :return: the record for the written backup.
+        """
+        moment = when or datetime.now(UTC)
+        key = self._key_for(moment)
+        stream = self._driver.dump(source_dsn, env=self._env, timeout=self._config.dump_timeout_seconds)
+        if not self._driver.compressed:
+            stream = gzip_stream(stream)
+        await self._store.put(key, stream, content_type=_ENCRYPTED_CONTENT_TYPE)
+        size = await self._size_of(key)
+        log.info("backup created", extra={"extra_data": {"key": key, "size_bytes": size, "driver": self._driver.name}})
+        return BackupRecord(key=key, created_at=moment, size_bytes=size)
+
+    async def restore_into(self, target_dsn: str, key: str) -> None:
+        """Restore the backup at ``key`` into ``target_dsn`` (decrypt → gunzip → driver restore)."""
+        stream = self._store.open_read(key)
+        if not self._driver.compressed:
+            stream = gunzip_stream(stream)
+        await self._driver.restore(target_dsn, stream, env=self._env, timeout=self._config.dump_timeout_seconds)
+        log.info("backup restored", extra={"extra_data": {"key": key, "driver": self._driver.name}})
+
+    async def list_backups(self) -> list[BackupRecord]:
+        """List stored backups (newest first), timed by the timestamp encoded in each key."""
+        records = [
+            BackupRecord(
+                key=entry.key,
+                created_at=_created_at_from_key(entry.key, fallback=entry.last_modified),
+                size_bytes=entry.size_bytes,
+            )
+            async for entry in self._store.list_entries(f"{self._config.prefix}/")
+        ]
+        records.sort(key=lambda r: r.created_at, reverse=True)
+        return records
+
+    async def plan_retention(self) -> RetentionDecision:
+        """Compute (without deleting) which backups GFS retention would keep vs prune."""
+        records = await self.list_backups()
+        return GfsRetention.from_config(self._config).select(records)
+
+    async def apply_retention(self) -> RetentionDecision:
+        """Prune backups outside the GFS policy. Requires ``allow_delete``.
+
+        :raises DeleteNotAllowedError: when ``config.allow_delete`` is False.
+        """
+        if not self._config.allow_delete:
+            raise DeleteNotAllowedError("retention prune requires config.allow_delete=True")
+        decision = await self.plan_retention()
+        if decision.delete:
+            await self._store.delete_many([r.key for r in decision.delete])
+        log.info(
+            "retention pruned", extra={"extra_data": {"deleted": len(decision.delete), "kept": len(decision.keep)}}
+        )
+        return decision
+
+    async def delete_backup(self, key: str) -> None:
+        """Delete one backup. Requires ``allow_delete``.
+
+        :raises DeleteNotAllowedError: when ``config.allow_delete`` is False.
+        """
+        if not self._config.allow_delete:
+            raise DeleteNotAllowedError("delete requires config.allow_delete=True")
+        await self._store.delete(key)
+
+    async def _size_of(self, key: str) -> int:
+        size = 0
+        async for entry in self._store.list_entries(key):
+            if entry.key == key:
+                size = entry.size_bytes
+                break
+        return size

threetears/backup/gzip.py

@@ -0,0 +1,46 @@
+"""Streaming gzip (de)compression for dump bytes.
+
+A driver whose dump format isn't already compressed (Yugabyte's plain SQL) is gzipped on the way
+to the store and gunzipped on the way back. Both directions are incremental (``zlib`` objects), so
+a multi-GB dump streams through without buffering.
+"""
+
+from __future__ import annotations
+
+import zlib
+from collections.abc import AsyncIterator
+
+__all__ = ["gunzip_stream", "gzip_stream"]
+
+_GZIP_WBITS = 16 + zlib.MAX_WBITS  # emit a gzip header/trailer
+_GUNZIP_WBITS = 32 + zlib.MAX_WBITS  # auto-detect gzip or zlib on the way back
+
+
+async def gzip_stream(source: AsyncIterator[bytes]) -> AsyncIterator[bytes]:
+    """Yield gzip-compressed chunks for ``source``."""
+    compressor = zlib.compressobj(wbits=_GZIP_WBITS)
+    async for chunk in source:
+        block = compressor.compress(chunk)
+        if block:
+            yield block
+    tail = compressor.flush()
+    if tail:
+        yield tail
+
+
+async def gunzip_stream(source: AsyncIterator[bytes]) -> AsyncIterator[bytes]:
+    """Yield decompressed chunks for a gzip stream ``source``.
+
+    :raises ValueError: if the stream ends before the gzip trailer (truncated / incomplete).
+    """
+    decompressor = zlib.decompressobj(wbits=_GUNZIP_WBITS)
+    async for chunk in source:
+        block = decompressor.decompress(chunk)
+        if block:
+            yield block
+    tail = decompressor.flush()
+    if tail:
+        yield tail
+    # flush() does NOT raise on a truncated stream; eof is False until the gzip trailer is consumed.
+    if not decompressor.eof:
+        raise ValueError("truncated gzip stream: trailer not reached")

threetears/backup/process.py

@@ -0,0 +1,174 @@
+"""Subprocess plumbing shared by every dump driver.
+
+Two primitives: :func:`stream_stdout` runs a command and yields its stdout in chunks (the *dump*
+side — pg_dump/ysql_dump write the archive to stdout), and :func:`feed_stdin` runs a command and
+streams bytes into its stdin (the *restore* side — pg_restore/ysqlsh read the archive from stdin).
+
+Both drain stderr concurrently (so a chatty tool can't deadlock on a full stderr pipe), enforce an
+optional wall-clock ``timeout``, and — critically — **never leave a child running**: if the caller
+aborts, the operation times out, or the input stream errors, the child is killed before the helper
+returns (otherwise a child blocked on a full stdout pipe would wedge ``proc.wait()`` forever). A
+non-zero exit raises :class:`BackupToolError` carrying the captured stderr; when a restore child
+dies early and breaks the stdin pipe, the exit-code diagnosis wins over the raw ``BrokenPipeError``.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import os
+import signal
+from collections.abc import AsyncIterator, Mapping
+
+__all__ = ["BackupToolError", "feed_stdin", "stream_stdout"]
+
+_READ_CHUNK = 1 << 16  # 64 KiB
+_TIMED_OUT = -1  # synthetic returncode used in the timeout message
+
+
+class BackupToolError(RuntimeError):
+    """A dump/restore subprocess exited non-zero (or timed out).
+
+    :param tool: the command that failed (argv[0]).
+    :param returncode: the process exit code (``-1`` for a timeout).
+    :param stderr: the captured standard error (decoded, best-effort).
+    """
+
+    def __init__(self, tool: str, returncode: int, stderr: str) -> None:
+        super().__init__(f"{tool} failed (exit {returncode}): {stderr.strip()}")
+        self.tool = tool
+        self.returncode = returncode
+        self.stderr = stderr
+
+
+async def _drain(stream: asyncio.StreamReader | None) -> bytes:
+    return b"" if stream is None else await stream.read()
+
+
+def _kill(proc: asyncio.subprocess.Process) -> None:
+    """SIGKILL the whole child process group if it is still running.
+
+    Killing the *group* (children are spawned with ``start_new_session=True``) ensures no
+    grandchild is orphaned — and, critically, that no descendant keeps the stderr pipe's write end
+    open, which would otherwise wedge the concurrent stderr drain on an abort/timeout.
+    """
+    if proc.returncode is None:
+        try:
+            os.killpg(os.getpgid(proc.pid), signal.SIGKILL)
+        except ProcessLookupError:
+            pass
+
+
+async def stream_stdout(
+    argv: list[str], *, env: Mapping[str, str] | None = None, timeout: float | None = None
+) -> AsyncIterator[bytes]:
+    """Run ``argv`` and yield its stdout in chunks; raise on a non-zero exit or timeout.
+
+    :param argv: the command and its arguments.
+    :param env: environment for the child (e.g. ``PGPASSWORD``); ``None`` inherits.
+    :param timeout: wall-clock ceiling in seconds; ``None`` disables it.
+    :raises BackupToolError: when the command exits non-zero or exceeds ``timeout``.
+    """
+    proc = await asyncio.create_subprocess_exec(
+        *argv,
+        stdout=asyncio.subprocess.PIPE,
+        stderr=asyncio.subprocess.PIPE,
+        env=dict(env) if env is not None else None,
+        start_new_session=True,  # own process group, so _kill can take down the whole tree
+    )
+    stderr_task = asyncio.ensure_future(_drain(proc.stderr))
+    deadline = None if timeout is None else asyncio.get_running_loop().time() + timeout
+    assert proc.stdout is not None
+    reached_eof = False
+    try:
+        while True:
+            try:
+                chunk = await _read_within(proc.stdout, deadline)
+            except TimeoutError:
+                _kill(proc)
+                stderr = (await stderr_task).decode(errors="replace")
+                raise BackupToolError(argv[0], _TIMED_OUT, f"timed out after {timeout}s. {stderr}") from None
+            if not chunk:
+                reached_eof = True
+                break
+            yield chunk
+    finally:
+        # if the consumer aborted (GeneratorExit) or we errored before EOF, the child may be
+        # blocked writing to a now-undrained stdout pipe — kill it so wait() can't hang.
+        if not reached_eof:
+            _kill(proc)
+        stderr_final = (await stderr_task).decode(errors="replace")
+        returncode = await proc.wait()
+    if returncode != 0:
+        raise BackupToolError(argv[0], returncode, stderr_final)
+
+
+async def _read_within(stream: asyncio.StreamReader, deadline: float | None) -> bytes:
+    if deadline is None:
+        return await stream.read(_READ_CHUNK)
+    remaining = deadline - asyncio.get_running_loop().time()
+    if remaining <= 0:
+        raise TimeoutError
+    return await asyncio.wait_for(stream.read(_READ_CHUNK), timeout=remaining)
+
+
+async def feed_stdin(
+    argv: list[str],
+    source: AsyncIterator[bytes],
+    *,
+    env: Mapping[str, str] | None = None,
+    timeout: float | None = None,
+) -> None:
+    """Run ``argv`` and stream ``source`` into its stdin; raise on a non-zero exit or timeout.
+
+    :param argv: the command and its arguments.
+    :param source: async iterator of bytes to write to the child's stdin.
+    :param env: environment for the child; ``None`` inherits.
+    :param timeout: wall-clock ceiling in seconds; ``None`` disables it.
+    :raises BackupToolError: when the command exits non-zero or exceeds ``timeout``.
+    """
+    proc = await asyncio.create_subprocess_exec(
+        *argv,
+        stdin=asyncio.subprocess.PIPE,
+        stdout=asyncio.subprocess.DEVNULL,
+        stderr=asyncio.subprocess.PIPE,
+        env=dict(env) if env is not None else None,
+        start_new_session=True,  # own process group, so _kill can take down the whole tree
+    )
+    stderr_task = asyncio.ensure_future(_drain(proc.stderr))
+    pumped = False
+    try:
+        if timeout is None:
+            await _pump_stdin(proc, source)
+        else:
+            await asyncio.wait_for(_pump_stdin(proc, source), timeout=timeout)
+        pumped = True
+    except TimeoutError:
+        _kill(proc)
+        stderr = (await stderr_task).decode(errors="replace")
+        raise BackupToolError(argv[0], _TIMED_OUT, f"timed out after {timeout}s. {stderr}") from None
+    finally:
+        # only kill on the abnormal path (source raised / timed out); on success let the child
+        # finish and exit cleanly rather than SIGKILLing it out from under a good run.
+        if not pumped:
+            _kill(proc)
+        stderr_final = (await stderr_task).decode(errors="replace")
+        returncode = await proc.wait()
+    if returncode != 0:
+        raise BackupToolError(argv[0], returncode, stderr_final)
+
+
+async def _pump_stdin(proc: asyncio.subprocess.Process, source: AsyncIterator[bytes]) -> None:
+    assert proc.stdin is not None
+    try:
+        async for chunk in source:
+            proc.stdin.write(chunk)
+            await proc.stdin.drain()
+        proc.stdin.close()
+        await proc.stdin.wait_closed()
+    except BrokenPipeError, ConnectionResetError:
+        # the child died early; it will have a non-zero exit + stderr, so let the caller's
+        # returncode check surface BackupToolError (the real diagnosis) rather than this pipe error.
+        pass
+    # wait for the child to finish INSIDE the timed region, so ``timeout`` bounds the whole
+    # restore (a child that reads its stdin fast but then processes for a long time is still capped).
+    await proc.wait()

threetears/backup/retention.py

@@ -0,0 +1,135 @@
+"""Grandfather-father-son (GFS) retention for backup pruning.
+
+The policy keeps, for each tier, the **newest backup of each of the most recent N periods**: the
+newest per calendar *day* for ``daily`` days, the newest per ISO *week* for ``weekly`` weeks, and
+the newest per calendar *month* for ``monthly`` months. A backup survives if it is the
+newest-in-its-period for any tier still inside that tier's window; the kept sets are unioned.
+
+This is deliberately *period-based*, not date-classification-based. An earlier model tagged a
+backup as monthly/weekly only if it happened to fall on the 1st / a Sunday -- so a schedule that
+ever missed those days left a month or week with no keeper. Promoting the newest backup *within*
+each period instead means every populated day/week/month keeps a representative regardless of when
+in the period the backup ran.
+
+:meth:`GfsRetention.select` is pure (records in, keep/delete split out, nothing mutated) so the
+engine can dry-run a prune before deleting anything. The record is a small generic value
+(:class:`BackupRecord`), so this composes over an ``ObjectStore`` listing as readily as a DB table.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Iterable
+from dataclasses import dataclass
+from datetime import datetime
+
+from threetears.observe import get_logger
+
+from threetears.backup.config import BackupConfig
+
+__all__ = ["BackupRecord", "GfsRetention", "RetentionDecision"]
+
+log = get_logger(__name__)
+
+#: a period identity derived from a timestamp (calendar day, ISO week, or calendar month).
+_PeriodKey = tuple[int, ...]
+
+
+@dataclass(frozen=True, slots=True)
+class BackupRecord:
+    """One backup as retention sees it: a key, when it was made, and its size."""
+
+    key: str
+    created_at: datetime
+    size_bytes: int = 0
+
+
+@dataclass(frozen=True, slots=True)
+class RetentionDecision:
+    """The outcome of applying a policy: what to keep, what to prune."""
+
+    keep: tuple[BackupRecord, ...]
+    delete: tuple[BackupRecord, ...]
+
+
+def _day_key(when: datetime) -> _PeriodKey:
+    return (when.year, when.month, when.day)
+
+
+def _week_key(when: datetime) -> _PeriodKey:
+    iso = when.isocalendar()  # ISO week is year-boundary safe (late Dec can be week 1 of next year)
+    return (iso.year, iso.week)
+
+
+def _month_key(when: datetime) -> _PeriodKey:
+    return (when.year, when.month)
+
+
+class GfsRetention:
+    """A grandfather-father-son retention policy (newest backup per recent day/week/month).
+
+    :param daily: number of recent days to keep a backup for (>= 1).
+    :param weekly: number of recent ISO weeks to keep a backup for (>= 1).
+    :param monthly: number of recent months to keep a backup for (>= 1).
+    """
+
+    def __init__(self, *, daily: int = 7, weekly: int = 4, monthly: int = 3) -> None:
+        for label, value in (("daily", daily), ("weekly", weekly), ("monthly", monthly)):
+            if value < 1:
+                raise ValueError(f"{label} retention must be >= 1")
+        self._daily = daily
+        self._weekly = weekly
+        self._monthly = monthly
+
+    @classmethod
+    def from_config(cls, config: BackupConfig) -> GfsRetention:
+        """Build the policy from a :class:`BackupConfig`."""
+        return cls(
+            daily=config.retention_daily,
+            weekly=config.retention_weekly,
+            monthly=config.retention_monthly,
+        )
+
+    def select(self, records: Iterable[BackupRecord]) -> RetentionDecision:
+        """Split records into keep/delete by the newest-per-period policy.
+
+        :param records: the candidate backups (any order).
+        :return: the keep/delete decision (input records preserved, never mutated).
+        """
+        ordered = sorted(records, key=lambda r: (r.created_at, r.key), reverse=True)
+        daily = self._period_keepers(ordered, _day_key, self._daily)
+        weekly = self._period_keepers(ordered, _week_key, self._weekly)
+        monthly = self._period_keepers(ordered, _month_key, self._monthly)
+        keep_keys = daily | weekly | monthly
+
+        keep = tuple(r for r in ordered if r.key in keep_keys)
+        delete = tuple(r for r in ordered if r.key not in keep_keys)
+        log.info(
+            "gfs retention evaluated",
+            extra={
+                "extra_data": {
+                    "keep": len(keep),
+                    "delete": len(delete),
+                    "daily_keepers": len(daily),
+                    "weekly_keepers": len(weekly),
+                    "monthly_keepers": len(monthly),
+                }
+            },
+        )
+        return RetentionDecision(keep=keep, delete=delete)
+
+    @staticmethod
+    def _period_keepers(
+        ordered: list[BackupRecord],
+        period_of: Callable[[datetime], _PeriodKey],
+        keep_periods: int,
+    ) -> set[str]:
+        """Keys of the newest backup in each of the ``keep_periods`` most recent populated periods.
+
+        ``ordered`` is newest-first, so the first record seen for a period *is* that period's newest,
+        and periods are first-seen in most-recent-first order.
+        """
+        newest_in_period: dict[_PeriodKey, str] = {}
+        for record in ordered:
+            newest_in_period.setdefault(period_of(record.created_at), record.key)
+        recent_periods = list(newest_in_period)[:keep_periods]
+        return {newest_in_period[period] for period in recent_periods}

threetears/backup/verify.py

@@ -0,0 +1,198 @@
+"""Restore verification — prove a backup actually restores.
+
+A backup you can't restore is a false comfort. :class:`RestoreVerifier` restores a backup into a
+**throwaway temporary database** (never the source, never a shared schema — a real separate database
+so ``pg_restore`` is fully isolated), runs assertions against it, and optionally invokes a
+``post_restore_hook`` — the extension point for "spin a test stack against the restored data". The
+temp database is created and dropped around the check.
+
+Everything the verifier touches is injected: the temp-database *provisioner* (an async context
+manager yielding a dsn), the *assertions*, and the *hook*. That keeps the orchestration unit-testable
+with fakes; :func:`make_temp_db_provisioner` and :func:`count_tables` are the real
+asyncpg-backed defaults for integration use.
+"""
+
+from __future__ import annotations
+
+import os
+from collections.abc import AsyncIterator, Awaitable, Callable, Mapping
+from contextlib import AbstractAsyncContextManager, asynccontextmanager
+from dataclasses import dataclass, field
+from typing import Any, Protocol, runtime_checkable
+from urllib.parse import urlparse, urlunparse
+from uuid import uuid7
+
+from threetears.observe import get_logger
+
+from threetears.backup.process import feed_stdin
+
+__all__ = [
+    "Assertions",
+    "PostRestoreHook",
+    "RestoreVerifier",
+    "SupportsRestore",
+    "TempDbProvisioner",
+    "VerificationResult",
+    "count_tables",
+    "make_subprocess_hook",
+    "make_temp_db_provisioner",
+]
+
+log = get_logger(__name__)
+
+#: yields the dsn of a fresh, empty temporary database, and tears it down on exit.
+TempDbProvisioner = Callable[[], AbstractAsyncContextManager[str]]
+#: run against the restored temp dsn; returns named checks recorded on the result.
+Assertions = Callable[[str], Awaitable[Mapping[str, Any]]]
+#: the opt-in extension point (e.g. boot a stack against the restored dsn).
+PostRestoreHook = Callable[[str], Awaitable[None]]
+
+
+@runtime_checkable
+class SupportsRestore(Protocol):
+    """The only capability the verifier needs from the engine: restore a backup into a dsn.
+
+    :class:`~threetears.backup.engine.BackupEngine` satisfies this structurally; segregating it
+    keeps the verifier decoupled from the full engine surface.
+    """
+
+    async def restore_into(self, target_dsn: str, key: str) -> None: ...
+
+
+@dataclass(frozen=True, slots=True)
+class VerificationResult:
+    """Outcome of verifying one backup."""
+
+    key: str
+    ok: bool
+    checks: dict[str, Any] = field(default_factory=dict)
+    hook_ran: bool = False
+
+
+class RestoreVerifier:
+    """Verify backups by restoring them into a temporary database.
+
+    :param engine: anything that can :meth:`restore_into` a dsn (a :class:`BackupEngine`).
+    :param provision_temp_db: factory yielding an async context manager over a fresh temp dsn.
+    :param assertions: optional check run against the restored dsn (defaults to none).
+    :param post_restore_hook: optional subprocess/stack hook run against the restored dsn.
+    """
+
+    def __init__(
+        self,
+        engine: SupportsRestore,
+        provision_temp_db: TempDbProvisioner,
+        *,
+        assertions: Assertions | None = None,
+        post_restore_hook: PostRestoreHook | None = None,
+    ) -> None:
+        self._engine = engine
+        self._provision = provision_temp_db
+        self._assertions = assertions
+        self._hook = post_restore_hook
+
+    async def verify(self, key: str) -> VerificationResult:
+        """Restore ``key`` into a temp database, run assertions + the hook, then tear it down."""
+        checks: dict[str, Any] = {}
+        hook_ran = False
+        async with self._provision() as temp_dsn:
+            await self._engine.restore_into(temp_dsn, key)
+            if self._assertions is not None:
+                checks = dict(await self._assertions(temp_dsn))
+            if self._hook is not None:
+                await self._hook(temp_dsn)
+                hook_ran = True
+        log.info("restore verified", extra={"extra_data": {"key": key, "checks": checks, "hook_ran": hook_ran}})
+        return VerificationResult(key=key, ok=True, checks=checks, hook_ran=hook_ran)
+
+
+def _swap_database(dsn: str, database: str) -> str:
+    parsed = urlparse(dsn)
+    return urlunparse(parsed._replace(path=f"/{database}"))
+
+
+def make_temp_db_provisioner(
+    admin_dsn: str,
+    *,
+    connect: Callable[[str], Awaitable[Any]],
+    name_prefix: str = "verify_restore_",
+) -> TempDbProvisioner:
+    """Build a provisioner that CREATEs a temp database and DROPs it on exit (asyncpg).
+
+    :param admin_dsn: a dsn with rights to CREATE/DROP DATABASE (e.g. the maintenance db).
+    :param connect: an async connect callable (``asyncpg.connect``); injected for testability.
+    :param name_prefix: prefix for the generated temp database name.
+    :return: a :data:`TempDbProvisioner`.
+    """
+
+    @asynccontextmanager
+    async def provision() -> AsyncIterator[str]:
+        database = f"{name_prefix}{uuid7().hex[:12]}"
+        admin = await connect(admin_dsn)
+        try:
+            await admin.execute(f'CREATE DATABASE "{database}"')
+        finally:
+            await admin.close()
+        try:
+            yield _swap_database(admin_dsn, database)
+        finally:
+            cleanup = await connect(admin_dsn)
+            try:
+                await cleanup.execute(f'DROP DATABASE IF EXISTS "{database}"')
+            finally:
+                await cleanup.close()
+
+    return provision
+
+
+def count_tables(*, connect: Callable[[str], Awaitable[Any]]) -> Assertions:
+    """Default assertion: the restored database has at least one user table (asyncpg).
+
+    Counts base tables across every non-system schema (excluding ``pg_catalog`` /
+    ``information_schema``), not just ``public`` — real apps put their tables in named schemas
+    (scriob's live in ``platform``), so a ``public``-only check would read zero and falsely fail.
+
+    :param connect: an async connect callable (``asyncpg.connect``); injected for testability.
+    :return: an :data:`Assertions` recording ``{"tables": n}`` and asserting ``n > 0``.
+    """
+
+    async def assertion(dsn: str) -> Mapping[str, Any]:
+        conn = await connect(dsn)
+        try:
+            count = await conn.fetchval(
+                "SELECT count(*) FROM information_schema.tables "
+                "WHERE table_type = 'BASE TABLE' "
+                "AND table_schema NOT IN ('pg_catalog', 'information_schema')"
+            )
+        finally:
+            await conn.close()
+        tables = int(count)
+        if tables < 1:
+            raise AssertionError("restored database has no user tables")
+        return {"tables": tables}
+
+    return assertion
+
+
+def make_subprocess_hook(argv: list[str], *, dsn_env: str = "RESTORED_DATABASE_URL") -> PostRestoreHook:
+    """Build a hook that runs ``argv`` with the restored dsn exported in the environment.
+
+    The stubbed extension point for "start a test stack against the restored database": off unless a
+    caller wires it in. The restored dsn is passed to the child via ``dsn_env`` (default
+    ``RESTORED_DATABASE_URL``).
+
+    :param argv: the command to run after a successful restore.
+    :param dsn_env: environment variable the restored dsn is exported under.
+    :return: a :data:`PostRestoreHook`.
+    """
+
+    async def hook(dsn: str) -> None:
+        await feed_stdin(argv, _no_stdin(), env={**os.environ, dsn_env: dsn})
+
+    return hook
+
+
+async def _no_stdin() -> AsyncIterator[bytes]:
+    """An empty byte stream — the hook command takes its input from the environment, not stdin."""
+    return
+    yield b""  # pragma: no cover - the bare `yield` only makes this an async generator