3tears-backup 0.16.0__tar.gz

3tears_backup-0.16.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_backup-0.16.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_backup-0.16.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,19 @@
+# 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/pyproject.toml

@@ -0,0 +1,44 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "3tears-backup"
+version = "0.16.0"
+description = "Encrypted, GFS-rotated database backups to any ObjectStore, with restore verification"
+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 :: Database",
+    "Topic :: System :: Archiving :: Backup",
+    "Typing :: Typed",
+]
+# storage-agnostic: the engine takes an injected ObjectStore (S3 is one driver,
+# filesystem another), streams the dump through EncryptedObjectStore, and reads
+# the dump tool from the DB driver. object-store brings the store + the streaming
+# AEAD primitive; media-contracts is the ObjectStore protocol; observe is
+# structured logging.
+dependencies = [
+    "3tears-media-contracts",
+    "3tears-object-store",
+    "3tears-observe",
+]
+
+[project.urls]
+Repository = "https://github.com/pacepace/3tears"
+
+[tool.uv.sources]
+3tears-media-contracts = { workspace = true }
+3tears-object-store = { workspace = true }
+3tears-observe = { workspace = true }
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/threetears"]

3tears_backup-0.16.0/src/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",
+]

3tears_backup-0.16.0/src/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"}

3tears_backup-0.16.0/src/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))