l3io-wordpress-backup 1.0.0__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- l3io/wp/backup/__init__.py +22 -0
- l3io/wp/backup/_version.py +31 -0
- l3io/wp/backup/adapters/__init__.py +9 -0
- l3io/wp/backup/adapters/clock.py +22 -0
- l3io/wp/backup/adapters/config_writer.py +702 -0
- l3io/wp/backup/adapters/credential_providers.py +236 -0
- l3io/wp/backup/adapters/crypto.py +237 -0
- l3io/wp/backup/adapters/database.py +1555 -0
- l3io/wp/backup/adapters/database_load.py +1263 -0
- l3io/wp/backup/adapters/exclusions.py +83 -0
- l3io/wp/backup/adapters/journal.py +507 -0
- l3io/wp/backup/adapters/lock.py +372 -0
- l3io/wp/backup/adapters/noop.py +666 -0
- l3io/wp/backup/adapters/phase.py +218 -0
- l3io/wp/backup/adapters/preflight.py +869 -0
- l3io/wp/backup/adapters/redaction.py +237 -0
- l3io/wp/backup/adapters/restore_extension.py +341 -0
- l3io/wp/backup/adapters/restore_runner.py +1030 -0
- l3io/wp/backup/adapters/site_files.py +191 -0
- l3io/wp/backup/adapters/store.py +227 -0
- l3io/wp/backup/adapters/tar.py +1648 -0
- l3io/wp/backup/adapters/tracing.py +235 -0
- l3io/wp/backup/adapters/workspace.py +299 -0
- l3io/wp/backup/adapters/wpcli.py +584 -0
- l3io/wp/backup/adapters/wpcli_child.py +135 -0
- l3io/wp/backup/api/__init__.py +104 -0
- l3io/wp/backup/api/errors.py +344 -0
- l3io/wp/backup/api/operations.py +427 -0
- l3io/wp/backup/cli/__init__.py +228 -0
- l3io/wp/backup/cli/adapter_sets.py +255 -0
- l3io/wp/backup/cli/backup.py +1118 -0
- l3io/wp/backup/cli/context.py +382 -0
- l3io/wp/backup/cli/credentials.py +310 -0
- l3io/wp/backup/cli/doctor.py +171 -0
- l3io/wp/backup/cli/exit.py +171 -0
- l3io/wp/backup/cli/logging.py +147 -0
- l3io/wp/backup/cli/output.py +111 -0
- l3io/wp/backup/cli/parser.py +853 -0
- l3io/wp/backup/cli/passphrase.py +301 -0
- l3io/wp/backup/cli/preflight.py +227 -0
- l3io/wp/backup/cli/privileges.py +327 -0
- l3io/wp/backup/cli/restore.py +1571 -0
- l3io/wp/backup/cli/restore_report.py +396 -0
- l3io/wp/backup/cli/restore_request.py +560 -0
- l3io/wp/backup/cli/scope.py +31 -0
- l3io/wp/backup/cli/settings.py +524 -0
- l3io/wp/backup/cli/verify.py +286 -0
- l3io/wp/backup/core/__init__.py +9 -0
- l3io/wp/backup/core/archive_choice.py +156 -0
- l3io/wp/backup/core/backup.py +105 -0
- l3io/wp/backup/core/config_location.py +257 -0
- l3io/wp/backup/core/exclusions.py +189 -0
- l3io/wp/backup/core/relocation.py +437 -0
- l3io/wp/backup/core/restore.py +1246 -0
- l3io/wp/backup/core/restore_journal.py +541 -0
- l3io/wp/backup/core/restore_space.py +224 -0
- l3io/wp/backup/core/verify.py +198 -0
- l3io/wp/backup/domain/__init__.py +9 -0
- l3io/wp/backup/domain/archive_format.py +1072 -0
- l3io/wp/backup/domain/backup_scope.py +21 -0
- l3io/wp/backup/domain/config.py +27 -0
- l3io/wp/backup/domain/credentials.py +125 -0
- l3io/wp/backup/domain/database.py +113 -0
- l3io/wp/backup/domain/errors.py +1434 -0
- l3io/wp/backup/domain/exclusion.py +74 -0
- l3io/wp/backup/domain/exit_codes.py +87 -0
- l3io/wp/backup/domain/flag_map.py +246 -0
- l3io/wp/backup/domain/journal.py +142 -0
- l3io/wp/backup/domain/lock.py +61 -0
- l3io/wp/backup/domain/preflight.py +126 -0
- l3io/wp/backup/domain/restore.py +181 -0
- l3io/wp/backup/domain/search_replace.py +59 -0
- l3io/wp/backup/domain/secret.py +61 -0
- l3io/wp/backup/domain/site.py +60 -0
- l3io/wp/backup/domain/storage_target.py +60 -0
- l3io/wp/backup/ports/__init__.py +33 -0
- l3io/wp/backup/ports/adapter_set.py +66 -0
- l3io/wp/backup/ports/archive.py +136 -0
- l3io/wp/backup/ports/clock.py +23 -0
- l3io/wp/backup/ports/config.py +71 -0
- l3io/wp/backup/ports/crypto.py +30 -0
- l3io/wp/backup/ports/database.py +129 -0
- l3io/wp/backup/ports/exclusion.py +33 -0
- l3io/wp/backup/ports/journal.py +53 -0
- l3io/wp/backup/ports/lock.py +48 -0
- l3io/wp/backup/ports/preflight.py +23 -0
- l3io/wp/backup/ports/restore.py +59 -0
- l3io/wp/backup/ports/search_replace.py +40 -0
- l3io/wp/backup/ports/site_files.py +95 -0
- l3io/wp/backup/ports/tracing.py +80 -0
- l3io/wp/backup/py.typed +0 -0
- l3io_wordpress_backup-1.0.0.dist-info/METADATA +593 -0
- l3io_wordpress_backup-1.0.0.dist-info/RECORD +98 -0
- l3io_wordpress_backup-1.0.0.dist-info/WHEEL +4 -0
- l3io_wordpress_backup-1.0.0.dist-info/entry_points.txt +2 -0
- l3io_wordpress_backup-1.0.0.dist-info/licenses/LICENSE +21 -0
- wpbackup2/__init__.py +7 -0
- wpbackup2/__main__.py +8 -0
|
@@ -0,0 +1,136 @@
|
|
|
1
|
+
"""AD-4/AD-21 — the Archive store port, split into a query and a command.
|
|
2
|
+
|
|
3
|
+
No method moves Archive bytes as ``bytes``: a staged Archive is written through
|
|
4
|
+
a file object (AD-21, AG-13). A Dry Run binds the real query and a no-op
|
|
5
|
+
command.
|
|
6
|
+
|
|
7
|
+
``ArchiveProbe`` (AD-23, AG-7) is a query port over an Archive's bytes: raw
|
|
8
|
+
facts only, it never decides a format (``domain.archive_format.classify``
|
|
9
|
+
does). Its one ``bytes`` return is :meth:`ArchiveProbe.read_member`, bounded by
|
|
10
|
+
``max_bytes`` and exempted by name in ``tests/contracts/test_port_types.py``
|
|
11
|
+
(ADR-0016 amendment).
|
|
12
|
+
|
|
13
|
+
``ArchiveWriterCommand`` (ADR-0019) is where the Site Root is collected, the
|
|
14
|
+
payload encrypted and the Archive written, so a Dry Run, binding its no-op,
|
|
15
|
+
reads no Site Root file and writes nothing.
|
|
16
|
+
"""
|
|
17
|
+
|
|
18
|
+
from __future__ import annotations
|
|
19
|
+
|
|
20
|
+
from collections.abc import Callable, Mapping
|
|
21
|
+
from pathlib import Path
|
|
22
|
+
from typing import IO, Protocol, runtime_checkable
|
|
23
|
+
|
|
24
|
+
from l3io.wp.backup.domain.archive_format import (
|
|
25
|
+
ArchiveView,
|
|
26
|
+
Manifest,
|
|
27
|
+
ManifestMember,
|
|
28
|
+
MemberDigest,
|
|
29
|
+
MemberIndex,
|
|
30
|
+
)
|
|
31
|
+
from l3io.wp.backup.domain.exclusion import ExcludedEntry
|
|
32
|
+
from l3io.wp.backup.domain.storage_target import StorageTarget
|
|
33
|
+
from l3io.wp.backup.ports.crypto import PayloadCipher
|
|
34
|
+
from l3io.wp.backup.ports.exclusion import ExclusionPolicy
|
|
35
|
+
|
|
36
|
+
__all__ = [
|
|
37
|
+
"ArchiveProbe",
|
|
38
|
+
"ArchiveStoreCommand",
|
|
39
|
+
"ArchiveStoreQuery",
|
|
40
|
+
"ArchiveWriterCommand",
|
|
41
|
+
"ManifestBuilder",
|
|
42
|
+
"StagedArchive",
|
|
43
|
+
]
|
|
44
|
+
|
|
45
|
+
#: Builds the Manifest from the member index written and what was excluded.
|
|
46
|
+
ManifestBuilder = Callable[
|
|
47
|
+
[tuple[ManifestMember, ...], tuple[ExcludedEntry, ...]], Manifest
|
|
48
|
+
]
|
|
49
|
+
|
|
50
|
+
|
|
51
|
+
class StagedArchive(Protocol):
|
|
52
|
+
"""An Archive being written, invisible at its destination until published."""
|
|
53
|
+
|
|
54
|
+
@property
|
|
55
|
+
def stream(self) -> IO[bytes]:
|
|
56
|
+
"""Where the Archive's bytes are written."""
|
|
57
|
+
...
|
|
58
|
+
|
|
59
|
+
@property
|
|
60
|
+
def staged_path(self) -> Path | None:
|
|
61
|
+
"""The temporary file the bytes land in; ``None`` when none exists."""
|
|
62
|
+
...
|
|
63
|
+
|
|
64
|
+
def publish(self) -> bool:
|
|
65
|
+
"""Make the Archive visible; ``False`` only for the no-op store."""
|
|
66
|
+
...
|
|
67
|
+
|
|
68
|
+
def discard(self) -> None:
|
|
69
|
+
"""Remove the staged bytes; nothing becomes visible."""
|
|
70
|
+
...
|
|
71
|
+
|
|
72
|
+
|
|
73
|
+
class ArchiveStoreQuery(Protocol):
|
|
74
|
+
"""What the Archive store can answer without changing anything."""
|
|
75
|
+
|
|
76
|
+
def exists(self, target: StorageTarget) -> bool:
|
|
77
|
+
"""Whether an Archive already exists at ``target``."""
|
|
78
|
+
...
|
|
79
|
+
|
|
80
|
+
|
|
81
|
+
@runtime_checkable
|
|
82
|
+
class ArchiveStoreCommand(Protocol):
|
|
83
|
+
"""What changes the Archive store."""
|
|
84
|
+
|
|
85
|
+
def stage(self, target: StorageTarget) -> StagedArchive:
|
|
86
|
+
"""Begin writing an Archive for ``target``."""
|
|
87
|
+
...
|
|
88
|
+
|
|
89
|
+
|
|
90
|
+
@runtime_checkable
|
|
91
|
+
class ArchiveWriterCommand(Protocol):
|
|
92
|
+
"""What collects a Site and writes its Archive (ADR-0019)."""
|
|
93
|
+
|
|
94
|
+
def write(
|
|
95
|
+
self,
|
|
96
|
+
out: IO[bytes],
|
|
97
|
+
*,
|
|
98
|
+
site_root: Path | None,
|
|
99
|
+
dump: Path | None,
|
|
100
|
+
config: Path,
|
|
101
|
+
exclusion: ExclusionPolicy,
|
|
102
|
+
cipher: PayloadCipher | None,
|
|
103
|
+
manifest_builder: ManifestBuilder,
|
|
104
|
+
workspace: Path,
|
|
105
|
+
) -> Manifest:
|
|
106
|
+
"""Write one Archive into ``out``; its Manifest.
|
|
107
|
+
|
|
108
|
+
``site_root`` is ``None`` for a ``database`` scope and ``dump`` for
|
|
109
|
+
``files``. ``workspace`` is the Run's private directory, where the
|
|
110
|
+
payload is staged before it is copied into ``out``.
|
|
111
|
+
"""
|
|
112
|
+
...
|
|
113
|
+
|
|
114
|
+
|
|
115
|
+
class ArchiveProbe(Protocol):
|
|
116
|
+
"""What can be read from an Archive without writing anything."""
|
|
117
|
+
|
|
118
|
+
def member_index(self, source: StorageTarget) -> MemberIndex:
|
|
119
|
+
"""The outer tar's member names and Manifest text, streamed once."""
|
|
120
|
+
...
|
|
121
|
+
|
|
122
|
+
def member_digests(self, source: StorageTarget) -> Mapping[str, MemberDigest]:
|
|
123
|
+
"""Every outer member's type, size and SHA-256, streamed once."""
|
|
124
|
+
...
|
|
125
|
+
|
|
126
|
+
def read_member(
|
|
127
|
+
self,
|
|
128
|
+
source: StorageTarget,
|
|
129
|
+
view: ArchiveView,
|
|
130
|
+
path: str,
|
|
131
|
+
*,
|
|
132
|
+
max_bytes: int,
|
|
133
|
+
payload: Path | None = None,
|
|
134
|
+
) -> bytes:
|
|
135
|
+
"""One regular-file member's bytes, at most ``max_bytes`` of them."""
|
|
136
|
+
...
|
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
"""AD-16 — the clock port: a query, so a test can fix a Run's time.
|
|
2
|
+
|
|
3
|
+
``adapters.clock.SystemClock`` is the real one.
|
|
4
|
+
"""
|
|
5
|
+
|
|
6
|
+
from __future__ import annotations
|
|
7
|
+
|
|
8
|
+
from datetime import datetime
|
|
9
|
+
from typing import Protocol
|
|
10
|
+
|
|
11
|
+
__all__ = ["Clock"]
|
|
12
|
+
|
|
13
|
+
|
|
14
|
+
class Clock(Protocol):
|
|
15
|
+
"""Tells the time, and measures durations."""
|
|
16
|
+
|
|
17
|
+
def now(self) -> datetime:
|
|
18
|
+
"""The current time, tz-aware UTC."""
|
|
19
|
+
...
|
|
20
|
+
|
|
21
|
+
def monotonic_ns(self) -> int:
|
|
22
|
+
"""A monotonic reading in nanoseconds, for durations only (BL-E003-100)."""
|
|
23
|
+
...
|
|
@@ -0,0 +1,71 @@
|
|
|
1
|
+
"""AD-4/AD-18.2/AD-18.4 — the ``wp-config.php`` port, a query and a command (ADR-0023).
|
|
2
|
+
|
|
3
|
+
:class:`ConfigQuery` reads the **restore target's** constants (Epic 3's
|
|
4
|
+
``prior_constants``); it does not build a Site Descriptor, which stays
|
|
5
|
+
``adapters/database.py``'s (AD-3). :class:`ConfigCommand` holds the file
|
|
6
|
+
effects of a restore: rewriting constants, and the two of
|
|
7
|
+
``--overwrite-wp-config`` — saving a copy and replacing the file with the
|
|
8
|
+
Archive's copy, handed over as text so no intermediate file exists and a Dry
|
|
9
|
+
Run's no-op twin writes nothing (BL-E003-057, ADR-0023 amendment). The real
|
|
10
|
+
adapter is E002-S02-009's; it alone imports ``l3io.wp.config``.
|
|
11
|
+
|
|
12
|
+
``set_constants`` may receive a ``DB_PASSWORD`` value (relocation): the real
|
|
13
|
+
adapter registers it with the Run's ``SecretRegistry`` and the no-op records
|
|
14
|
+
the keys only.
|
|
15
|
+
"""
|
|
16
|
+
|
|
17
|
+
from __future__ import annotations
|
|
18
|
+
|
|
19
|
+
from collections.abc import Mapping, Sequence
|
|
20
|
+
from pathlib import Path
|
|
21
|
+
from typing import Final, Protocol, runtime_checkable
|
|
22
|
+
|
|
23
|
+
from l3io.wp.backup.domain.config import ConfigWriteResult, ConstantValue
|
|
24
|
+
|
|
25
|
+
__all__ = ["WHOLE_FILE", "ConfigCommand", "ConfigQuery"]
|
|
26
|
+
|
|
27
|
+
#: The ``key`` of a ``ConfigWriteFailedError`` about the file, not one constant.
|
|
28
|
+
WHOLE_FILE: Final = "(whole file)"
|
|
29
|
+
|
|
30
|
+
|
|
31
|
+
class ConfigQuery(Protocol):
|
|
32
|
+
"""What can be read from a ``wp-config.php`` without changing it."""
|
|
33
|
+
|
|
34
|
+
def read_constants(
|
|
35
|
+
self, config_file: Path, keys: Sequence[str]
|
|
36
|
+
) -> Mapping[str, ConstantValue]:
|
|
37
|
+
"""``keys``' values in ``config_file``; ``None`` for an undefined one."""
|
|
38
|
+
...
|
|
39
|
+
|
|
40
|
+
|
|
41
|
+
@runtime_checkable
|
|
42
|
+
class ConfigCommand(Protocol):
|
|
43
|
+
"""What changes a ``wp-config.php``."""
|
|
44
|
+
|
|
45
|
+
def set_constants(
|
|
46
|
+
self, config_file: Path, values: Mapping[str, str | int | bool]
|
|
47
|
+
) -> ConfigWriteResult:
|
|
48
|
+
"""Set ``values`` in ``config_file``; the names changed."""
|
|
49
|
+
...
|
|
50
|
+
|
|
51
|
+
def save_copy(self, config_file: Path, destination: Path) -> ConfigWriteResult:
|
|
52
|
+
"""Copy ``config_file`` to ``destination`` at mode ``0600``, fsynced."""
|
|
53
|
+
...
|
|
54
|
+
|
|
55
|
+
def replace_file(
|
|
56
|
+
self,
|
|
57
|
+
config_file: Path,
|
|
58
|
+
content: str,
|
|
59
|
+
*,
|
|
60
|
+
keep: Sequence[str],
|
|
61
|
+
) -> ConfigWriteResult:
|
|
62
|
+
"""Replace ``config_file`` with ``content``, ``keep`` carried in first.
|
|
63
|
+
|
|
64
|
+
``content`` is the Archive's ``wp-config.php`` text, decoded without
|
|
65
|
+
newline translation. ``keep`` names the target's constants whose
|
|
66
|
+
definitions are carried into it in memory, as the source the target
|
|
67
|
+
wrote (owner decision 48), before anything is written; the new file is
|
|
68
|
+
written beside ``config_file``, fsynced and moved over it with
|
|
69
|
+
``os.replace``, keeping mode and owner.
|
|
70
|
+
"""
|
|
71
|
+
...
|
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
"""ADR-0024 — the payload cipher port.
|
|
2
|
+
|
|
3
|
+
Applied once to the whole payload, streaming from a reader to a writer (AD-21).
|
|
4
|
+
A transform, neither query nor command. Epic 4's passphrase-only
|
|
5
|
+
``adapters/crypto.PassphraseCipher`` implements it (E004-S01-003), built only by
|
|
6
|
+
``adapters/crypto.build_payload_cipher``. ``backup``, ``restore`` and ``verify
|
|
7
|
+
--authenticate`` bind a real cipher whenever a passphrase resolves.
|
|
8
|
+
"""
|
|
9
|
+
|
|
10
|
+
from __future__ import annotations
|
|
11
|
+
|
|
12
|
+
from typing import IO, Protocol
|
|
13
|
+
|
|
14
|
+
__all__ = ["PayloadCipher"]
|
|
15
|
+
|
|
16
|
+
|
|
17
|
+
class PayloadCipher(Protocol):
|
|
18
|
+
"""Encrypts or decrypts the payload as a stream."""
|
|
19
|
+
|
|
20
|
+
def check(self) -> None:
|
|
21
|
+
"""Raise before any write if the cipher cannot run."""
|
|
22
|
+
...
|
|
23
|
+
|
|
24
|
+
def encrypt(self, reader: IO[bytes], writer: IO[bytes]) -> None:
|
|
25
|
+
"""Read plaintext from ``reader`` and write ciphertext to ``writer``."""
|
|
26
|
+
...
|
|
27
|
+
|
|
28
|
+
def decrypt(self, reader: IO[bytes], writer: IO[bytes]) -> None:
|
|
29
|
+
"""Read ciphertext from ``reader`` and write plaintext to ``writer``."""
|
|
30
|
+
...
|
|
@@ -0,0 +1,129 @@
|
|
|
1
|
+
"""AD-4/AD-29 — the database port: backup and restore halves, query and command.
|
|
2
|
+
|
|
3
|
+
No method takes a credential: the WordPress source and, when given, the
|
|
4
|
+
administrator source are bound into the adapter at construction. The Dump is
|
|
5
|
+
written to a path, never returned as ``bytes`` (AD-21).
|
|
6
|
+
|
|
7
|
+
**The restore halves (E002-S02-012; owner decisions 53 and 55, ADR-0027).**
|
|
8
|
+
A restore loads straight into the live database as the WordPress account:
|
|
9
|
+
:meth:`DatabaseQuery.check_load`, :meth:`DatabaseCommand.load_dump` and
|
|
10
|
+
:meth:`DatabaseCommand.drop_tables` answer as that account, and
|
|
11
|
+
``load_dump(..., replace=True, prune_prefix=<site prefix>)`` first drops every
|
|
12
|
+
table and view carrying the site's prefix, so the database holds exactly the
|
|
13
|
+
Dump's tables afterwards; tables without the prefix are never touched.
|
|
14
|
+
:meth:`DatabaseQuery.survey_target` observes as the WordPress account and
|
|
15
|
+
turns to the administrator only when that account cannot see the database
|
|
16
|
+
(AD-29 as amended). ``ensure_database``, ``check_ensure`` and
|
|
17
|
+
``drop_database`` answer through the bound administrator and raise
|
|
18
|
+
``AdminCredentialsRequiredError`` before any connection when none is bound.
|
|
19
|
+
``load_dump`` takes no credential or decryption parameter (ADR-0015
|
|
20
|
+
amendment, ADR-0024).
|
|
21
|
+
"""
|
|
22
|
+
|
|
23
|
+
from __future__ import annotations
|
|
24
|
+
|
|
25
|
+
from dataclasses import dataclass
|
|
26
|
+
from pathlib import Path
|
|
27
|
+
from typing import IO, Protocol, runtime_checkable
|
|
28
|
+
|
|
29
|
+
from l3io.wp.backup.domain.database import (
|
|
30
|
+
DatabaseLocation,
|
|
31
|
+
DatabaseTargetState,
|
|
32
|
+
DumpResult,
|
|
33
|
+
EnsureOutcome,
|
|
34
|
+
LoadResult,
|
|
35
|
+
Readiness,
|
|
36
|
+
)
|
|
37
|
+
|
|
38
|
+
__all__ = ["DatabaseCommand", "DatabaseQuery", "DbTls"]
|
|
39
|
+
|
|
40
|
+
|
|
41
|
+
class DatabaseQuery(Protocol):
|
|
42
|
+
"""What can be learned about a database without changing anything."""
|
|
43
|
+
|
|
44
|
+
def check_dump(self, location: DatabaseLocation) -> Readiness:
|
|
45
|
+
"""Whether a dump of ``location`` would run, as finding codes."""
|
|
46
|
+
...
|
|
47
|
+
|
|
48
|
+
def survey_target(
|
|
49
|
+
self,
|
|
50
|
+
location: DatabaseLocation,
|
|
51
|
+
*,
|
|
52
|
+
table_prefix: str,
|
|
53
|
+
wordpress_user: str | None,
|
|
54
|
+
) -> DatabaseTargetState:
|
|
55
|
+
"""What the WordPress account, else the administrator, observes (AD-29)."""
|
|
56
|
+
...
|
|
57
|
+
|
|
58
|
+
def check_ensure(self, location: DatabaseLocation) -> Readiness:
|
|
59
|
+
"""Whether ``ensure_database(location)`` would run."""
|
|
60
|
+
...
|
|
61
|
+
|
|
62
|
+
def check_load(
|
|
63
|
+
self,
|
|
64
|
+
location: DatabaseLocation,
|
|
65
|
+
*,
|
|
66
|
+
source: Path | None,
|
|
67
|
+
replace: bool = False,
|
|
68
|
+
prune_prefix: str | None = None,
|
|
69
|
+
) -> Readiness:
|
|
70
|
+
"""Whether ``load_dump`` into ``location`` with the same options would run."""
|
|
71
|
+
...
|
|
72
|
+
|
|
73
|
+
|
|
74
|
+
@runtime_checkable
|
|
75
|
+
class DatabaseCommand(Protocol):
|
|
76
|
+
"""What produces database artefacts or changes a database."""
|
|
77
|
+
|
|
78
|
+
def dump_to(self, location: DatabaseLocation, destination: Path) -> DumpResult:
|
|
79
|
+
"""Dump ``location`` to ``destination`` atomically, at mode ``0600``."""
|
|
80
|
+
...
|
|
81
|
+
|
|
82
|
+
def ensure_database(self, location: DatabaseLocation) -> EnsureOutcome:
|
|
83
|
+
"""Create ``location``'s database and the WordPress account as needed."""
|
|
84
|
+
...
|
|
85
|
+
|
|
86
|
+
def load_dump(
|
|
87
|
+
self,
|
|
88
|
+
location: DatabaseLocation,
|
|
89
|
+
source: IO[bytes] | Path,
|
|
90
|
+
*,
|
|
91
|
+
replace: bool = False,
|
|
92
|
+
prune_prefix: str | None = None,
|
|
93
|
+
) -> LoadResult:
|
|
94
|
+
"""Load the plain Dump ``source`` into ``location.name``.
|
|
95
|
+
|
|
96
|
+
Without ``replace`` the database must be empty. With it, the Dump is
|
|
97
|
+
loaded over what is there, after every table and view whose name
|
|
98
|
+
starts with ``prune_prefix`` (when given) was dropped
|
|
99
|
+
(``LoadResult.dropped``).
|
|
100
|
+
"""
|
|
101
|
+
...
|
|
102
|
+
|
|
103
|
+
def drop_tables(
|
|
104
|
+
self, location: DatabaseLocation, *, prefix: str
|
|
105
|
+
) -> tuple[str, ...]:
|
|
106
|
+
"""Drop every table and view of ``location`` starting with ``prefix``."""
|
|
107
|
+
...
|
|
108
|
+
|
|
109
|
+
def drop_database(self, location: DatabaseLocation, *, confirm: str) -> bool:
|
|
110
|
+
"""Drop ``location``'s database; whether it was performed."""
|
|
111
|
+
...
|
|
112
|
+
|
|
113
|
+
|
|
114
|
+
@dataclass(frozen=True, slots=True)
|
|
115
|
+
class DbTls:
|
|
116
|
+
"""The TLS every database connection of a Run uses (owner decision 56).
|
|
117
|
+
|
|
118
|
+
``mode`` is an ``adapters/database.py::DB_TLS_MODES`` value, or ``None``
|
|
119
|
+
for no requirement: the connection is made the way WordPress makes it.
|
|
120
|
+
``ca_file`` is the CA bundle that verifies the server, ``None`` meaning the
|
|
121
|
+
system store; it needs a verifying ``mode``. A port-level value
|
|
122
|
+
(BL-E003-099; ``Path`` keeps it out of ``domain/``): it holds no
|
|
123
|
+
``l3io.wp.database`` type (ADR-0015 amendment), so ``RestoreRequest`` and
|
|
124
|
+
the library carry no adapters-layer type; ``adapters/database.py``
|
|
125
|
+
validates and applies it.
|
|
126
|
+
"""
|
|
127
|
+
|
|
128
|
+
mode: str | None = None
|
|
129
|
+
ca_file: Path | None = None
|
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
"""FR-5 — the exclusion policy port (decided 2026-10-27).
|
|
2
|
+
|
|
3
|
+
A pure query. Epic 4's ``ExclusionSet`` satisfies it structurally and owns its
|
|
4
|
+
constructors; this port defines none. ``domain.exclusion.INCLUDE_EVERYTHING``
|
|
5
|
+
is the policy that excludes nothing.
|
|
6
|
+
"""
|
|
7
|
+
|
|
8
|
+
from __future__ import annotations
|
|
9
|
+
|
|
10
|
+
from pathlib import PurePosixPath
|
|
11
|
+
from typing import Protocol
|
|
12
|
+
|
|
13
|
+
from l3io.wp.backup.domain.exclusion import ExclusionDecision
|
|
14
|
+
|
|
15
|
+
__all__ = ["ExclusionPolicy"]
|
|
16
|
+
|
|
17
|
+
|
|
18
|
+
class ExclusionPolicy(Protocol):
|
|
19
|
+
"""Decides, per Site Root path, whether it goes into the Archive."""
|
|
20
|
+
|
|
21
|
+
@property
|
|
22
|
+
def source(self) -> str:
|
|
23
|
+
"""``"default"``, ``"custom"`` or ``"none"``."""
|
|
24
|
+
...
|
|
25
|
+
|
|
26
|
+
@property
|
|
27
|
+
def patterns(self) -> tuple[str, ...]:
|
|
28
|
+
"""The patterns this policy applies, as the operator would read them."""
|
|
29
|
+
...
|
|
30
|
+
|
|
31
|
+
def decide(self, relative: PurePosixPath, *, is_dir: bool) -> ExclusionDecision:
|
|
32
|
+
"""The decision for ``relative``, a path under the Site Root."""
|
|
33
|
+
...
|
|
@@ -0,0 +1,53 @@
|
|
|
1
|
+
"""AD-18.1 — the Run Journal port, a query and a command (ADR-0020, ADR-0021).
|
|
2
|
+
|
|
3
|
+
The real pair is ``adapters/journal.py``'s (Epic 3, E003-S02-005), which owns
|
|
4
|
+
the durable write sequence and the file layout. A Dry Run binds the real query
|
|
5
|
+
and the no-op command, so it records nothing and resolves nothing.
|
|
6
|
+
"""
|
|
7
|
+
|
|
8
|
+
from __future__ import annotations
|
|
9
|
+
|
|
10
|
+
from pathlib import PurePosixPath
|
|
11
|
+
from typing import Protocol, runtime_checkable
|
|
12
|
+
|
|
13
|
+
from l3io.wp.backup.domain.journal import JournalHeader, JournalRecord
|
|
14
|
+
from l3io.wp.backup.domain.restore import RestorePhase
|
|
15
|
+
|
|
16
|
+
__all__ = ["RunJournalCommand", "RunJournalQuery"]
|
|
17
|
+
|
|
18
|
+
|
|
19
|
+
class RunJournalQuery(Protocol):
|
|
20
|
+
"""What can be read from the Run Journals without changing them."""
|
|
21
|
+
|
|
22
|
+
def incomplete(self, site_root: PurePosixPath) -> JournalRecord | None:
|
|
23
|
+
"""The unresolved journal of a Run on ``site_root`` that never finished."""
|
|
24
|
+
...
|
|
25
|
+
|
|
26
|
+
|
|
27
|
+
@runtime_checkable
|
|
28
|
+
class RunJournalCommand(Protocol):
|
|
29
|
+
"""What writes a Run's journal."""
|
|
30
|
+
|
|
31
|
+
def begin_run(self, header: JournalHeader) -> None:
|
|
32
|
+
"""Record ``header`` durably, before the Run's first effect."""
|
|
33
|
+
...
|
|
34
|
+
|
|
35
|
+
def phase_started(self, phase: RestorePhase, target: str) -> None:
|
|
36
|
+
"""Record that ``phase`` began against ``target``."""
|
|
37
|
+
...
|
|
38
|
+
|
|
39
|
+
def step_completed(self, phase: RestorePhase, step: str) -> None:
|
|
40
|
+
"""Record that the named ``step`` of ``phase`` completed."""
|
|
41
|
+
...
|
|
42
|
+
|
|
43
|
+
def phase_completed(self, phase: RestorePhase) -> None:
|
|
44
|
+
"""Record that ``phase`` completed."""
|
|
45
|
+
...
|
|
46
|
+
|
|
47
|
+
def finish_run(self) -> None:
|
|
48
|
+
"""Record that the Run finished; its journal is no longer incomplete."""
|
|
49
|
+
...
|
|
50
|
+
|
|
51
|
+
def resolve(self, run_id: str, resolved_by: str) -> None:
|
|
52
|
+
"""Acknowledge the incomplete journal of ``run_id`` (ADR-0021)."""
|
|
53
|
+
...
|
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
"""AD-19 — the Site Lock port: one Run per Site.
|
|
2
|
+
|
|
3
|
+
``SiteLock`` is command-only, on the single-role allowance in
|
|
4
|
+
``ports/__init__.py``: taking the lock is Run machinery, not a Site write, so a
|
|
5
|
+
Dry Run takes it for real and there is no no-op. ``adapters.lock.FcntlSiteLock``
|
|
6
|
+
is the real one. The composition root acquires it (``cli.context.open_run``)
|
|
7
|
+
before the first read of Site state and releases it in the Run's ``finally``.
|
|
8
|
+
"""
|
|
9
|
+
|
|
10
|
+
from __future__ import annotations
|
|
11
|
+
|
|
12
|
+
from pathlib import Path
|
|
13
|
+
from types import TracebackType
|
|
14
|
+
from typing import Protocol, Self
|
|
15
|
+
|
|
16
|
+
from l3io.wp.backup.domain.lock import LockHolder
|
|
17
|
+
|
|
18
|
+
__all__ = ["LockHandle", "SiteLock"]
|
|
19
|
+
|
|
20
|
+
|
|
21
|
+
class LockHandle(Protocol):
|
|
22
|
+
"""A held Site Lock; released once, or used as a context manager."""
|
|
23
|
+
|
|
24
|
+
@property
|
|
25
|
+
def site_root(self) -> Path:
|
|
26
|
+
"""The canonical Site Root the lock is keyed on."""
|
|
27
|
+
...
|
|
28
|
+
|
|
29
|
+
def release(self) -> None:
|
|
30
|
+
"""Release it; ``SiteLockReleaseError`` if already released."""
|
|
31
|
+
...
|
|
32
|
+
|
|
33
|
+
def __enter__(self) -> Self: ...
|
|
34
|
+
|
|
35
|
+
def __exit__(
|
|
36
|
+
self,
|
|
37
|
+
exc_type: type[BaseException] | None,
|
|
38
|
+
exc: BaseException | None,
|
|
39
|
+
tb: TracebackType | None,
|
|
40
|
+
) -> None: ...
|
|
41
|
+
|
|
42
|
+
|
|
43
|
+
class SiteLock(Protocol):
|
|
44
|
+
"""Acquires the lock for a canonical Site Root."""
|
|
45
|
+
|
|
46
|
+
def acquire(self, site_root: Path, holder: LockHolder) -> LockHandle:
|
|
47
|
+
"""Hold ``site_root``'s lock for ``holder``; ``SiteLockedError`` if held."""
|
|
48
|
+
...
|
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
"""AD-13 — the preflight port: are the tools a plan needs usable? A query.
|
|
2
|
+
|
|
3
|
+
It changes nothing, so a Dry Run runs it for real. Until Epic 5 supplies the
|
|
4
|
+
generic ``adapters/preflight`` (``shutil.which`` and a version probe), the
|
|
5
|
+
roots bind ``cli.preflight.RootPreflight`` (``root_preflight``).
|
|
6
|
+
"""
|
|
7
|
+
|
|
8
|
+
from __future__ import annotations
|
|
9
|
+
|
|
10
|
+
from collections.abc import Sequence
|
|
11
|
+
from typing import Protocol
|
|
12
|
+
|
|
13
|
+
from l3io.wp.backup.domain.preflight import ToolRequirement, ToolStatus
|
|
14
|
+
|
|
15
|
+
__all__ = ["Preflight"]
|
|
16
|
+
|
|
17
|
+
|
|
18
|
+
class Preflight(Protocol):
|
|
19
|
+
"""Reports what it finds for each required tool."""
|
|
20
|
+
|
|
21
|
+
def check(self, requirements: Sequence[ToolRequirement]) -> Sequence[ToolStatus]:
|
|
22
|
+
"""One status per requirement it could look for."""
|
|
23
|
+
...
|
|
@@ -0,0 +1,59 @@
|
|
|
1
|
+
"""AD-1, AD-4, ADR-0016 — what a restore's executor reaches effects through.
|
|
2
|
+
|
|
3
|
+
:class:`RestorePorts` is declared here, once; E003-S02-003, E003-S02-005 and
|
|
4
|
+
E003-S02-006 cite it. It lives in ``ports/``, not ``core/``: its fields name
|
|
5
|
+
port types and ``core/`` may not import ``ports/``. ``adapters`` is the Run's
|
|
6
|
+
bound :class:`~l3io.wp.backup.ports.adapter_set.AdapterSet`, held whole
|
|
7
|
+
(``tests/contracts/test_adapter_set_owner.py`` refuses a second class holding
|
|
8
|
+
port halves), so a Dry Run is these ports over ``dry_run_adapters(...)``'s
|
|
9
|
+
set. :func:`restore_ports` is the one constructor; only the restore root
|
|
10
|
+
(E003-S02-006) calls it.
|
|
11
|
+
"""
|
|
12
|
+
|
|
13
|
+
from __future__ import annotations
|
|
14
|
+
|
|
15
|
+
from collections.abc import Callable
|
|
16
|
+
from dataclasses import dataclass
|
|
17
|
+
from pathlib import Path
|
|
18
|
+
|
|
19
|
+
from l3io.wp.backup.domain.preflight import ToolRequirement
|
|
20
|
+
from l3io.wp.backup.ports.adapter_set import AdapterSet
|
|
21
|
+
|
|
22
|
+
__all__ = ["RestorePorts", "restore_ports"]
|
|
23
|
+
|
|
24
|
+
|
|
25
|
+
@dataclass(frozen=True, slots=True)
|
|
26
|
+
class RestorePorts:
|
|
27
|
+
"""The Run's bound adapters and the three callables a restore also needs.
|
|
28
|
+
|
|
29
|
+
``preflight`` raises the first unmet tool requirement
|
|
30
|
+
(``PreflightFailedError``); ``free_bytes(path)`` is the free bytes of the
|
|
31
|
+
filesystem holding ``path`` (``shutil.disk_usage``, bound by the root);
|
|
32
|
+
``cutover_credentials`` returns the relocated WordPress account's
|
|
33
|
+
password at call time, or is ``None`` without relocation.
|
|
34
|
+
"""
|
|
35
|
+
|
|
36
|
+
adapters: AdapterSet
|
|
37
|
+
preflight: Callable[[tuple[ToolRequirement, ...]], None]
|
|
38
|
+
free_bytes: Callable[[Path], int]
|
|
39
|
+
cutover_credentials: Callable[[], str] | None
|
|
40
|
+
|
|
41
|
+
def __repr__(self) -> str:
|
|
42
|
+
# The credential callable is named, never called.
|
|
43
|
+
return f"RestorePorts(adapters={self.adapters!r})"
|
|
44
|
+
|
|
45
|
+
|
|
46
|
+
def restore_ports(
|
|
47
|
+
adapters: AdapterSet,
|
|
48
|
+
*,
|
|
49
|
+
preflight: Callable[[tuple[ToolRequirement, ...]], None],
|
|
50
|
+
free_bytes: Callable[[Path], int],
|
|
51
|
+
cutover_credentials: Callable[[], str] | None,
|
|
52
|
+
) -> RestorePorts:
|
|
53
|
+
"""The one constructor of :class:`RestorePorts`; every keyword required."""
|
|
54
|
+
return RestorePorts(
|
|
55
|
+
adapters=adapters,
|
|
56
|
+
preflight=preflight,
|
|
57
|
+
free_bytes=free_bytes,
|
|
58
|
+
cutover_credentials=cutover_credentials,
|
|
59
|
+
)
|
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
"""FR-12 — the search-replace port (E007-S01-003). Command-only, by design.
|
|
2
|
+
|
|
3
|
+
There is no ``SearchReplaceQuery``: every WP-CLI read this relocation makes
|
|
4
|
+
depends on a loaded Dump and a rewritten ``wp-config.php``, both produced by
|
|
5
|
+
commands. A "real query" in a Dry Run would read the target's **current**
|
|
6
|
+
database and report differently from the real Run (AD-4), so the no-op twin
|
|
7
|
+
reports the planned pairs with their stored URLs unresolved instead.
|
|
8
|
+
|
|
9
|
+
It takes :class:`~l3io.wp.backup.domain.search_replace.UrlRelocation`, not
|
|
10
|
+
Epic 7's ``Relocation``; Epic 7 projects onto it.
|
|
11
|
+
"""
|
|
12
|
+
|
|
13
|
+
from __future__ import annotations
|
|
14
|
+
|
|
15
|
+
from pathlib import Path
|
|
16
|
+
from typing import Protocol, runtime_checkable
|
|
17
|
+
|
|
18
|
+
from l3io.wp.backup.domain.search_replace import SearchReplaceReport, UrlRelocation
|
|
19
|
+
|
|
20
|
+
__all__ = ["SearchReplaceCommand"]
|
|
21
|
+
|
|
22
|
+
|
|
23
|
+
@runtime_checkable
|
|
24
|
+
class SearchReplaceCommand(Protocol):
|
|
25
|
+
"""What rewrites a restored Site's stored URLs."""
|
|
26
|
+
|
|
27
|
+
def relocate_content(
|
|
28
|
+
self,
|
|
29
|
+
site_root: Path,
|
|
30
|
+
urls: UrlRelocation,
|
|
31
|
+
*,
|
|
32
|
+
archive_encrypted: bool | None = None,
|
|
33
|
+
) -> SearchReplaceReport:
|
|
34
|
+
"""Replace the stored ``siteurl``/``home`` with ``urls`` across the content.
|
|
35
|
+
|
|
36
|
+
``archive_encrypted`` is whether the restored Archive was encrypted
|
|
37
|
+
(authenticated), for the record a replacer logs; ``None`` when not
|
|
38
|
+
known. Passed by the caller, never shared state (BL-E007-020).
|
|
39
|
+
"""
|
|
40
|
+
...
|