l3io-wordpress-backup 1.0.0__py3-none-any.whl

l3io/wp/backup/domain/exclusion.py

@@ -0,0 +1,74 @@
+"""FR-5 — the exclusion value types both ``core/exclusions`` and ``adapters/tar`` name.
+
+Pure. Epic 4 owns the policy and its default patterns; this module defines only
+the values that cross the ``ExclusionPolicy`` port, and :data:`INCLUDE_EVERYTHING`,
+the policy that excludes nothing — what a Safety Snapshot passes, and what the
+default resolves to until E008-S01-001 binds Epic 4's set.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import StrEnum
+from pathlib import PurePosixPath
+from typing import Final
+
+__all__ = [
+    "INCLUDE_EVERYTHING",
+    "ExcludedEntry",
+    "ExclusionDecision",
+    "ExclusionSource",
+    "IncludeEverything",
+]
+
+
+class ExclusionSource(StrEnum):
+    """Where an exclusion policy's patterns came from (the Manifest's key).
+
+    The one type for the value (BL-E004-016): ``ExclusionSet.source``,
+    ``ManifestExclusions.source`` and :class:`IncludeEverything`. A host's own
+    ``ExclusionPolicy`` returns its ``str`` value; the backup converts it when
+    it records the Manifest.
+    """
+
+    DEFAULT = "default"
+    CUSTOM = "custom"
+    NONE = "none"
+
+
+@dataclass(frozen=True, slots=True)
+class ExcludedEntry:
+    """One path left out of the Archive, and the pattern that left it out."""
+
+    path: str
+    pattern: str
+    is_dir: bool
+
+
+@dataclass(frozen=True, slots=True)
+class ExclusionDecision:
+    """The policy's answer for one path."""
+
+    excluded: bool
+    pattern: str | None
+    protected: bool
+
+
+_INCLUDED: Final = ExclusionDecision(excluded=False, pattern=None, protected=False)
+
+
+@dataclass(frozen=True, slots=True)
+class IncludeEverything:
+    """The policy that excludes nothing; satisfies the ``ExclusionPolicy`` port."""
+
+    source: ExclusionSource = ExclusionSource.NONE
+    patterns: tuple[str, ...] = ()
+
+    def decide(self, relative: PurePosixPath, *, is_dir: bool) -> ExclusionDecision:
+        """Every path is included."""
+        del relative, is_dir
+        return _INCLUDED
+
+
+#: The one instance.
+INCLUDE_EVERYTHING: Final = IncludeEverything()

l3io/wp/backup/domain/exit_codes.py

@@ -0,0 +1,87 @@
+"""FR-21 — the exit-code table: the one source of truth for what a Run exits with.
+
+The family codes are those of ``l3io-wp-database``'s ``cli.Exit`` (v0.2.0):
+0 OK, 1 FAILED, 2 USAGE, 3 REFUSED, 4 CREDENTIALS, 5 UNREACHABLE and
+7 NOT_READY, with **6 reserved for the family** and therefore not a member.
+Two codes are this package's own: 8 VERIFICATION_FAILED and 9 LOCKED — the
+next free values after the family's 7, skipping the reserved 6 (decided
+2026-10-20). If the family later reserves a block above 7, these move before
+the first release, never after. ``tests/contracts/test_exit_codes_family.py``
+checks the family members against database's enum without an import here.
+
+**Append-only (PRD §10).** A value is never renumbered or reused; a member is
+added only for a genuinely new kind of failure, and only by E002.
+
+**How later failures map onto this table**, without a new member:
+
+- a non-empty restore target (FR-7) and an incomplete journal (AD-18) are
+  refusals: ``REFUSED``;
+- a missing tool — WP-CLI (FR-13), or any FR-27 prerequisite — is
+  ``NOT_READY``;
+- a decryption failure (Epic 4) is ``CREDENTIALS`` for a missing or wrong key
+  and ``VERIFICATION_FAILED`` for corrupt ciphertext — except under ``verify
+  --authenticate``, where a wrong passphrase is ``VERIFICATION_FAILED`` too
+  (``PassphraseRejectedError``; Shawn, 2026-11-03): the Archive could not be
+  authenticated.
+
+Each error class carries its code as the class attribute
+``BackupError.exit_code`` (``domain/errors.py``); the CLI reads that attribute
+and never matches over classes.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from enum import IntEnum, unique
+from types import MappingProxyType
+from typing import Final
+
+__all__ = [
+    "DESCRIPTIONS",
+    "INTERRUPTED_EXIT",
+    "INTERRUPTED_REASON",
+    "RESERVED",
+    "ExitCode",
+]
+
+
+@unique
+class ExitCode(IntEnum):
+    """The process exit code of a ``wpbackup2`` Run."""
+
+    OK = 0
+    FAILED = 1
+    USAGE = 2
+    REFUSED = 3
+    CREDENTIALS = 4
+    UNREACHABLE = 5
+    NOT_READY = 7
+    VERIFICATION_FAILED = 8
+    LOCKED = 9
+
+
+#: A Run stopped by Ctrl-C (``KeyboardInterrupt``) exits with the shell's
+#: convention, 128 + SIGINT, which is not a member of :class:`ExitCode`; its
+#: ``run_finished`` and ``command_failed`` records name it
+#: :data:`INTERRUPTED_REASON`.
+INTERRUPTED_EXIT: Final = 130
+#: The ``exit_reason`` an interrupted Run's records carry.
+INTERRUPTED_REASON: Final = "INTERRUPTED"
+
+#: Values the family reserves; never a member of :class:`ExitCode`.
+RESERVED: Final[frozenset[int]] = frozenset({6})
+
+#: One line per member, used by the CLI's stderr message, ``--help`` and README.
+DESCRIPTIONS: Final[Mapping[ExitCode, str]] = MappingProxyType(
+    {
+        ExitCode.OK: "the Run succeeded",
+        ExitCode.FAILED: "the Run failed for a reason no other code names",
+        ExitCode.USAGE: "the command line was invalid",
+        ExitCode.REFUSED: "a check found a reason not to act; nothing was done",
+        ExitCode.CREDENTIALS: "credentials were missing, unusable or rejected",
+        ExitCode.UNREACHABLE: "the database server could not be reached",
+        ExitCode.NOT_READY: "a required tool or optional extra is not available",
+        ExitCode.VERIFICATION_FAILED: "the archive failed verification",
+        ExitCode.LOCKED: "another Run holds the site lock",
+    }
+)

l3io/wp/backup/domain/flag_map.py

@@ -0,0 +1,246 @@
+"""AD-25 — the restore flags map to ``(RestoreMode, OverrideSet)`` through one table.
+
+The restore subcommand's mode-selecting flags, and what each one means:
+
+* ``--mode {files,db,all}`` chooses the parts restored. The table is keyed by
+  the :class:`~l3io.wp.backup.domain.backup_scope.BackupScope` the CLI's
+  ``CLI_MODE_TO_SCOPE`` translates it to, so there is no second spelling table.
+* ``--cleanfirst`` authorises **clearing the Site Root**, and nothing else.
+* ``--drop-database`` is accepted and changes nothing (owner decision 63):
+  every database restore loads straight into the live database and drops the
+  tables carrying the site's prefix first (decisions 49 and 53), so there is
+  no previous database to remove. It still selects ``database-clean`` with
+  ``--mode db``, which now behaves as ``database``; with ``--mode files`` or
+  ``--mode all`` it selects what the same flags without it select. The CLI
+  logs WARNING ``deprecated_option`` when it is given.
+* ``--force`` waives FR-7's non-empty-target refusal for exactly the parts the
+  Mode restores. It selects no Mode and authorises no removal: it yields an
+  :class:`~l3io.wp.backup.domain.restore.OverrideSet`, a distinct type.
+
+:data:`FLAG_MAP` is a **literal** of all 24 combinations, not a comprehension,
+so each row can be reviewed against FR-6. It is total — there is no default
+branch — and ``tests/contracts/test_flag_map.py`` derives the combinations from
+the parser's ``restore mode`` argument group and asserts equality.
+
+Behaviour change from v0.2.21 (B-3): ``--force`` no longer means
+``ALLCLEAN``, and ``--cleanfirst`` no longer removes the database. Since
+owner decision 63, ``--mode all --cleanfirst`` alone selects ``all-clean``.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+from types import MappingProxyType
+from typing import Final, TypeAlias
+
+from l3io.wp.backup.domain.backup_scope import BackupScope
+from l3io.wp.backup.domain.errors import FlagCombinationRejectedError
+from l3io.wp.backup.domain.restore import (
+    Override,
+    OverrideSet,
+    RestoreMode,
+    RestorePart,
+)
+
+__all__ = [
+    "COVERED_FLAGS",
+    "FLAG_MAP",
+    "FlagCombination",
+    "FlagEntry",
+    "FlagRejection",
+    "authorizing_combination",
+    "combination",
+    "resolve_flags",
+]
+
+#: One reachable flag combination, as ``(dest, value)`` pairs sorted by ``dest``.
+FlagCombination: TypeAlias = tuple[tuple[str, object], ...]
+
+#: The ``dest`` names of the restore flags this table maps. Asserted equal to
+#: the ``restore mode`` argument group of the parser itself.
+COVERED_FLAGS: Final[frozenset[str]] = frozenset(
+    {"mode", "cleanfirst", "drop_database", "force"}
+)
+
+
+@dataclass(frozen=True, slots=True)
+class FlagRejection:
+    """A combination that expresses no Restore Mode, and what would."""
+
+    reason: str
+    use_instead: str
+
+
+def combination(
+    *, mode: BackupScope, cleanfirst: bool, drop_database: bool, force: bool
+) -> FlagCombination:
+    """The table key for one set of restore flag values."""
+    return (
+        ("cleanfirst", cleanfirst),
+        ("drop_database", drop_database),
+        ("force", force),
+        ("mode", mode),
+    )
+
+
+_NONE = OverrideSet.none()
+_FILES = OverrideSet(waived=frozenset({Override.NONEMPTY_FILES}))
+_DATABASE = OverrideSet(waived=frozenset({Override.NONEMPTY_DATABASE}))
+_BOTH = OverrideSet(
+    waived=frozenset({Override.NONEMPTY_FILES, Override.NONEMPTY_DATABASE})
+)
+
+_DATABASE_CLEAN = FlagRejection(
+    reason="--cleanfirst clears the Site Root, which --mode db does not restore",
+    use_instead=(
+        "use --mode all --cleanfirst to clear the Site Root and restore both; "
+        "--mode db alone already replaces every table with the site's prefix"
+    ),
+)
+
+_F = BackupScope.FILES
+_D = BackupScope.DATABASE
+_A = BackupScope.ALL
+
+#: AD-25's table, decided 2026-10-20. Every row is FR-6's; nothing re-derives it.
+FlagEntry: TypeAlias = tuple[RestoreMode, OverrideSet] | FlagRejection
+FLAG_MAP: Final[Mapping[FlagCombination, FlagEntry]] = MappingProxyType(
+    {
+        # --mode files
+        combination(mode=_F, cleanfirst=False, drop_database=False, force=False): (
+            RestoreMode.FILES,
+            _NONE,
+        ),
+        combination(mode=_F, cleanfirst=False, drop_database=False, force=True): (
+            RestoreMode.FILES,
+            _FILES,
+        ),
+        combination(mode=_F, cleanfirst=True, drop_database=False, force=False): (
+            RestoreMode.FILES_CLEAN,
+            _NONE,
+        ),
+        combination(mode=_F, cleanfirst=True, drop_database=False, force=True): (
+            RestoreMode.FILES_CLEAN,
+            _FILES,
+        ),
+        # --drop-database changes nothing (owner decision 63).
+        combination(mode=_F, cleanfirst=False, drop_database=True, force=False): (
+            RestoreMode.FILES,
+            _NONE,
+        ),
+        combination(mode=_F, cleanfirst=False, drop_database=True, force=True): (
+            RestoreMode.FILES,
+            _FILES,
+        ),
+        combination(mode=_F, cleanfirst=True, drop_database=True, force=False): (
+            RestoreMode.FILES_CLEAN,
+            _NONE,
+        ),
+        combination(mode=_F, cleanfirst=True, drop_database=True, force=True): (
+            RestoreMode.FILES_CLEAN,
+            _FILES,
+        ),
+        # --mode db
+        combination(mode=_D, cleanfirst=False, drop_database=False, force=False): (
+            RestoreMode.DATABASE,
+            _NONE,
+        ),
+        combination(mode=_D, cleanfirst=False, drop_database=False, force=True): (
+            RestoreMode.DATABASE,
+            _DATABASE,
+        ),
+        combination(mode=_D, cleanfirst=False, drop_database=True, force=False): (
+            RestoreMode.DATABASE_CLEAN,
+            _NONE,
+        ),
+        combination(mode=_D, cleanfirst=False, drop_database=True, force=True): (
+            RestoreMode.DATABASE_CLEAN,
+            _DATABASE,
+        ),
+        combination(
+            mode=_D, cleanfirst=True, drop_database=False, force=False
+        ): _DATABASE_CLEAN,
+        combination(
+            mode=_D, cleanfirst=True, drop_database=False, force=True
+        ): _DATABASE_CLEAN,
+        combination(
+            mode=_D, cleanfirst=True, drop_database=True, force=False
+        ): _DATABASE_CLEAN,
+        combination(
+            mode=_D, cleanfirst=True, drop_database=True, force=True
+        ): _DATABASE_CLEAN,
+        # --mode all
+        combination(mode=_A, cleanfirst=False, drop_database=False, force=False): (
+            RestoreMode.ALL,
+            _NONE,
+        ),
+        combination(mode=_A, cleanfirst=False, drop_database=False, force=True): (
+            RestoreMode.ALL,
+            _BOTH,
+        ),
+        combination(mode=_A, cleanfirst=True, drop_database=True, force=False): (
+            RestoreMode.ALL_CLEAN,
+            _NONE,
+        ),
+        combination(mode=_A, cleanfirst=True, drop_database=True, force=True): (
+            RestoreMode.ALL_CLEAN,
+            _BOTH,
+        ),
+        # Owner decision 63: --cleanfirst alone selects all-clean, and
+        # --drop-database changes nothing.
+        combination(mode=_A, cleanfirst=True, drop_database=False, force=False): (
+            RestoreMode.ALL_CLEAN,
+            _NONE,
+        ),
+        combination(mode=_A, cleanfirst=True, drop_database=False, force=True): (
+            RestoreMode.ALL_CLEAN,
+            _BOTH,
+        ),
+        combination(mode=_A, cleanfirst=False, drop_database=True, force=False): (
+            RestoreMode.ALL,
+            _NONE,
+        ),
+        combination(mode=_A, cleanfirst=False, drop_database=True, force=True): (
+            RestoreMode.ALL,
+            _BOTH,
+        ),
+    }
+)
+
+
+def resolve_flags(flags: FlagCombination) -> tuple[RestoreMode, OverrideSet]:
+    """AD-25's one total function: the Mode and waivers ``flags`` express.
+
+    Raises :class:`FlagCombinationRejectedError` (``USAGE``) for a
+    combination that expresses no Mode, and ``KeyError`` for one outside the
+    table — there is no default.
+    """
+    entry = FLAG_MAP[flags]
+    if isinstance(entry, FlagRejection):
+        raise FlagCombinationRejectedError(
+            reason=entry.reason, use_instead=entry.use_instead
+        )
+    return entry
+
+
+def authorizing_combination(mode: RestoreMode, part: RestorePart) -> FlagCombination:
+    """The combination that selects ``mode`` and waives ``part``'s refusal.
+
+    Derived from :data:`FLAG_MAP`, so a refusal message names the waiving flag
+    from the table rather than from text typed into the message. Raises
+    ``ValueError`` when ``mode`` does not restore ``part``, since then there
+    is no refusal to waive. A combination without ``--drop-database`` is
+    preferred (owner decision 63: the flag changes nothing).
+    """
+    ordered = sorted(
+        FLAG_MAP.items(), key=lambda item: dict(item[0])["drop_database"] is True
+    )
+    for flags, entry in ordered:
+        if isinstance(entry, FlagRejection):
+            continue
+        entry_mode, overrides = entry
+        if entry_mode is mode and overrides.waives(part):
+            return flags
+    msg = f"Restore Mode {mode.value!r} does not restore the {part}"
+    raise ValueError(msg)

l3io/wp/backup/domain/journal.py

@@ -0,0 +1,142 @@
+"""AD-18.1 — the Run Journal's values (ADR-0020, ADR-0021).
+
+Pure values; the durable write sequence and the file layout are
+``adapters/journal.py``'s (Epic 3, E003-S02-005).
+
+:class:`JournalHeader` is what a restore records before its first effect.
+``cutover_targets`` and ``prior_constants`` may hold only
+:data:`JOURNALED_CONSTANTS`, so ``DB_PASSWORD`` cannot be journaled; the
+header's mappings are read-only, so no key is added after that check.
+``phase_undo`` is Epic 7's per-phase undo text and ``saved_config`` the path of
+the config copy ``--overwrite-wp-config`` saves, so a later Run derives the
+undo from the record alone.
+
+:class:`JournalEntry` stores no undo: ``step`` names the step a
+``step_completed`` entry completed, and the undo is derived when the journal is
+read (ADR-0020).
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+from pathlib import PurePosixPath
+from typing import Final, Literal, NoReturn, TypeVar
+
+from l3io.wp.backup.domain.restore import RestoreMode, RestorePhase
+
+__all__ = [
+    "JOURNALED_CONSTANTS",
+    "JournalEntry",
+    "JournalEvent",
+    "JournalHeader",
+    "JournalRecord",
+    "ReadOnlyDict",
+]
+
+#: The only ``wp-config.php`` constants a journal may hold. Never a secret.
+JOURNALED_CONSTANTS: Final = frozenset({"DB_NAME", "DB_HOST", "DB_USER"})
+
+#: What a journal entry records.
+JournalEvent = Literal["phase_started", "step_completed", "phase_completed"]
+
+
+_K = TypeVar("_K")
+_V = TypeVar("_V")
+
+
+class ReadOnlyDict(dict[_K, _V]):
+    """A ``dict`` no one can change after it is built.
+
+    Why not ``types.MappingProxyType``: ``dataclasses.asdict`` deep-copies any
+    value that is not a ``dict``, and a ``mappingproxy`` cannot be copied, so
+    the header would no longer round-trip (the story's testability AC). Python
+    3.11 has no ``frozendict``. Being a ``dict``, ``asdict`` rebuilds it with
+    ``type(obj)(pairs)``; ``__reduce__`` lets ``copy``/``pickle`` do the same.
+    """
+
+    __slots__ = ()
+
+    def _refuse(self, *_: object, **__: object) -> NoReturn:
+        msg = "a journal mapping is read-only"
+        raise TypeError(msg)
+
+    __setitem__ = __delitem__ = _refuse
+    clear = pop = popitem = setdefault = update = _refuse
+    __ior__ = _refuse
+
+    def __hash__(self) -> int:  # type: ignore[override]
+        return hash(frozenset(self.items()))
+
+    def __reduce__(self) -> tuple[type[ReadOnlyDict[_K, _V]], tuple[dict[_K, _V]]]:
+        return (type(self), (dict(self),))
+
+
+def _journaled(field: str, keys: Mapping[str, object]) -> None:
+    refused = sorted(set(keys) - JOURNALED_CONSTANTS)
+    if refused:
+        msg = (
+            f"{field} may hold only {sorted(JOURNALED_CONSTANTS)}; "
+            f"refused keys: {refused}"
+        )
+        raise ValueError(msg)
+
+
+@dataclass(frozen=True, slots=True)
+class JournalHeader:
+    """What a restore records before its first effect (AD-18.1).
+
+    ``live_database_before`` is the Site Descriptor's ``DB_NAME`` and
+    ``load_database`` the name the plan would load into, in every Mode: the
+    live database itself, or a relocation's (owner decision 49).
+    ``staging_database`` is always ``None`` since the direct load; it stays
+    in the record so a journal an earlier version wrote, which named one,
+    is read back unchanged. A files-only Mode loads nothing: it records them all
+    the same, and the undo text never reads them, since it has no
+    ``LOAD_DUMP`` phase.
+    """
+
+    run_id: str
+    started_at: str
+    site_root: PurePosixPath
+    restore_mode: RestoreMode
+    archive: str
+    snapshot_path: str | None
+    live_database_before: str
+    staging_database: str | None
+    wp_config_path: str
+    load_database: str
+    cutover_keys: tuple[str, ...]
+    cutover_targets: Mapping[str, str]
+    prior_constants: Mapping[str, str | None]
+    phase_undo: Mapping[RestorePhase, str]
+    saved_config: str | None
+
+    def __post_init__(self) -> None:
+        # Key names only in the message: a refused key's value is never shown.
+        _journaled("cutover_targets", self.cutover_targets)
+        _journaled("prior_constants", self.prior_constants)
+        # Read-only copies: neither the caller's later mutation nor a write
+        # through the header can add a key after the check above.
+        object.__setattr__(self, "cutover_keys", tuple(self.cutover_keys))
+        for name in ("cutover_targets", "prior_constants", "phase_undo"):
+            object.__setattr__(self, name, ReadOnlyDict(getattr(self, name)))
+
+
+@dataclass(frozen=True, slots=True)
+class JournalEntry:
+    """One journal event. No undo is stored; it is derived on read (ADR-0020)."""
+
+    event: JournalEvent
+    phase: RestorePhase
+    at: str
+    target: str | None
+    step: str | None
+
+
+@dataclass(frozen=True, slots=True)
+class JournalRecord:
+    """A journal as read back: its header and its entries, in order."""
+
+    header: JournalHeader
+    entries: tuple[JournalEntry, ...]

l3io/wp/backup/domain/lock.py

@@ -0,0 +1,61 @@
+"""AD-19 — the Site Lock's value types: who holds a Site.
+
+:class:`LockHolder` is the record a holding Run leaves beside its lock file
+(``adapters/lock.py``) so a refused Run can name it. It carries no credential
+and no Site content — only the Run ID, PID, start time and hostname.
+``started_at`` is rendered UTC ISO-8601 with the ``Z`` designator, the one
+spelling (E002-S01-001).
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+from datetime import UTC, datetime
+
+__all__ = ["LockHolder", "utc_z"]
+
+
+def utc_z(moment: datetime) -> str:
+    """``moment`` as UTC ISO-8601 with the ``Z`` designator."""
+    return moment.astimezone(UTC).isoformat().replace("+00:00", "Z")
+
+
+@dataclass(frozen=True, slots=True)
+class LockHolder:
+    """The Run holding a Site Lock."""
+
+    run_id: str
+    pid: int
+    started_at: datetime
+    hostname: str
+
+    def as_record(self, site_root: str) -> dict[str, object]:
+        """The holder record's fields, with the canonical Site Root in clear."""
+        return {
+            "run_id": self.run_id,
+            "pid": self.pid,
+            "started_at": utc_z(self.started_at),
+            "hostname": self.hostname,
+            "site_root": site_root,
+        }
+
+    @classmethod
+    def from_record(cls, record: Mapping[str, object]) -> LockHolder:
+        """The holder a record names; ``TypeError``/``ValueError`` if not one."""
+        run_id, pid = record.get("run_id"), record.get("pid")
+        started, hostname = record.get("started_at"), record.get("hostname")
+        if not (
+            isinstance(run_id, str)
+            and isinstance(pid, int)
+            and not isinstance(pid, bool)
+            and isinstance(started, str)
+            and isinstance(hostname, str)
+        ):
+            msg = "not a Site Lock holder record"
+            raise TypeError(msg)
+        moment = datetime.fromisoformat(started.replace("Z", "+00:00"))
+        if moment.tzinfo is None:
+            msg = "holder record started_at has no timezone"
+            raise ValueError(msg)
+        return cls(run_id=run_id, pid=pid, started_at=moment, hostname=hostname)