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.
Files changed (98) hide show
  1. l3io/wp/backup/__init__.py +22 -0
  2. l3io/wp/backup/_version.py +31 -0
  3. l3io/wp/backup/adapters/__init__.py +9 -0
  4. l3io/wp/backup/adapters/clock.py +22 -0
  5. l3io/wp/backup/adapters/config_writer.py +702 -0
  6. l3io/wp/backup/adapters/credential_providers.py +236 -0
  7. l3io/wp/backup/adapters/crypto.py +237 -0
  8. l3io/wp/backup/adapters/database.py +1555 -0
  9. l3io/wp/backup/adapters/database_load.py +1263 -0
  10. l3io/wp/backup/adapters/exclusions.py +83 -0
  11. l3io/wp/backup/adapters/journal.py +507 -0
  12. l3io/wp/backup/adapters/lock.py +372 -0
  13. l3io/wp/backup/adapters/noop.py +666 -0
  14. l3io/wp/backup/adapters/phase.py +218 -0
  15. l3io/wp/backup/adapters/preflight.py +869 -0
  16. l3io/wp/backup/adapters/redaction.py +237 -0
  17. l3io/wp/backup/adapters/restore_extension.py +341 -0
  18. l3io/wp/backup/adapters/restore_runner.py +1030 -0
  19. l3io/wp/backup/adapters/site_files.py +191 -0
  20. l3io/wp/backup/adapters/store.py +227 -0
  21. l3io/wp/backup/adapters/tar.py +1648 -0
  22. l3io/wp/backup/adapters/tracing.py +235 -0
  23. l3io/wp/backup/adapters/workspace.py +299 -0
  24. l3io/wp/backup/adapters/wpcli.py +584 -0
  25. l3io/wp/backup/adapters/wpcli_child.py +135 -0
  26. l3io/wp/backup/api/__init__.py +104 -0
  27. l3io/wp/backup/api/errors.py +344 -0
  28. l3io/wp/backup/api/operations.py +427 -0
  29. l3io/wp/backup/cli/__init__.py +228 -0
  30. l3io/wp/backup/cli/adapter_sets.py +255 -0
  31. l3io/wp/backup/cli/backup.py +1118 -0
  32. l3io/wp/backup/cli/context.py +382 -0
  33. l3io/wp/backup/cli/credentials.py +310 -0
  34. l3io/wp/backup/cli/doctor.py +171 -0
  35. l3io/wp/backup/cli/exit.py +171 -0
  36. l3io/wp/backup/cli/logging.py +147 -0
  37. l3io/wp/backup/cli/output.py +111 -0
  38. l3io/wp/backup/cli/parser.py +853 -0
  39. l3io/wp/backup/cli/passphrase.py +301 -0
  40. l3io/wp/backup/cli/preflight.py +227 -0
  41. l3io/wp/backup/cli/privileges.py +327 -0
  42. l3io/wp/backup/cli/restore.py +1571 -0
  43. l3io/wp/backup/cli/restore_report.py +396 -0
  44. l3io/wp/backup/cli/restore_request.py +560 -0
  45. l3io/wp/backup/cli/scope.py +31 -0
  46. l3io/wp/backup/cli/settings.py +524 -0
  47. l3io/wp/backup/cli/verify.py +286 -0
  48. l3io/wp/backup/core/__init__.py +9 -0
  49. l3io/wp/backup/core/archive_choice.py +156 -0
  50. l3io/wp/backup/core/backup.py +105 -0
  51. l3io/wp/backup/core/config_location.py +257 -0
  52. l3io/wp/backup/core/exclusions.py +189 -0
  53. l3io/wp/backup/core/relocation.py +437 -0
  54. l3io/wp/backup/core/restore.py +1246 -0
  55. l3io/wp/backup/core/restore_journal.py +541 -0
  56. l3io/wp/backup/core/restore_space.py +224 -0
  57. l3io/wp/backup/core/verify.py +198 -0
  58. l3io/wp/backup/domain/__init__.py +9 -0
  59. l3io/wp/backup/domain/archive_format.py +1072 -0
  60. l3io/wp/backup/domain/backup_scope.py +21 -0
  61. l3io/wp/backup/domain/config.py +27 -0
  62. l3io/wp/backup/domain/credentials.py +125 -0
  63. l3io/wp/backup/domain/database.py +113 -0
  64. l3io/wp/backup/domain/errors.py +1434 -0
  65. l3io/wp/backup/domain/exclusion.py +74 -0
  66. l3io/wp/backup/domain/exit_codes.py +87 -0
  67. l3io/wp/backup/domain/flag_map.py +246 -0
  68. l3io/wp/backup/domain/journal.py +142 -0
  69. l3io/wp/backup/domain/lock.py +61 -0
  70. l3io/wp/backup/domain/preflight.py +126 -0
  71. l3io/wp/backup/domain/restore.py +181 -0
  72. l3io/wp/backup/domain/search_replace.py +59 -0
  73. l3io/wp/backup/domain/secret.py +61 -0
  74. l3io/wp/backup/domain/site.py +60 -0
  75. l3io/wp/backup/domain/storage_target.py +60 -0
  76. l3io/wp/backup/ports/__init__.py +33 -0
  77. l3io/wp/backup/ports/adapter_set.py +66 -0
  78. l3io/wp/backup/ports/archive.py +136 -0
  79. l3io/wp/backup/ports/clock.py +23 -0
  80. l3io/wp/backup/ports/config.py +71 -0
  81. l3io/wp/backup/ports/crypto.py +30 -0
  82. l3io/wp/backup/ports/database.py +129 -0
  83. l3io/wp/backup/ports/exclusion.py +33 -0
  84. l3io/wp/backup/ports/journal.py +53 -0
  85. l3io/wp/backup/ports/lock.py +48 -0
  86. l3io/wp/backup/ports/preflight.py +23 -0
  87. l3io/wp/backup/ports/restore.py +59 -0
  88. l3io/wp/backup/ports/search_replace.py +40 -0
  89. l3io/wp/backup/ports/site_files.py +95 -0
  90. l3io/wp/backup/ports/tracing.py +80 -0
  91. l3io/wp/backup/py.typed +0 -0
  92. l3io_wordpress_backup-1.0.0.dist-info/METADATA +593 -0
  93. l3io_wordpress_backup-1.0.0.dist-info/RECORD +98 -0
  94. l3io_wordpress_backup-1.0.0.dist-info/WHEEL +4 -0
  95. l3io_wordpress_backup-1.0.0.dist-info/entry_points.txt +2 -0
  96. l3io_wordpress_backup-1.0.0.dist-info/licenses/LICENSE +21 -0
  97. wpbackup2/__init__.py +7 -0
  98. wpbackup2/__main__.py +8 -0
@@ -0,0 +1,372 @@
1
+ """AD-19 — ``FcntlSiteLock``: the Site Lock as a kernel advisory lock.
2
+
3
+ The lock for a canonical Site Root is ``<sha256 of the path>.lock`` in the
4
+ per-user state directory (``platformdirs.user_state_path("l3io-wp-backup") /
5
+ "locks"``, mode ``0700``), held with ``fcntl.flock(LOCK_EX | LOCK_NB)``. The
6
+ kernel releases an ``flock`` when its holder dies for any reason, SIGKILL
7
+ included, so a lock whose holder is gone is never live: what it leaves is a
8
+ stale holder record (``<same>.json``, ``0600``), which the next acquirer
9
+ overwrites after logging ``stale_lock_reclaimed``. PID liveness only words that
10
+ warning; the kernel lock alone decides ownership, so PID reuse cannot matter.
11
+
12
+ The lock directory is never inside the Site Root — a restore scope could
13
+ otherwise delete the lock it holds — and an unusable directory is
14
+ ``SiteLockLocationError`` (``NOT_READY``): a Run never proceeds unlocked. It is
15
+ injected through the constructor for tests, never read from the environment
16
+ here.
17
+
18
+ **Re-entrancy.** ``flock`` on a second descriptor conflicts even within one
19
+ process, so a per-process registry, keyed by lock file, counts depth: a second
20
+ ``acquire`` by the **same** ``run_id`` increments it, the release that brings it
21
+ to zero unlocks, and an acquire by a different ``run_id`` refuses. A child made
22
+ with ``fork`` inherits the descriptor and the registry; use ``spawn``.
23
+ """
24
+
25
+ from __future__ import annotations
26
+
27
+ import contextlib
28
+ import errno
29
+ import hashlib
30
+ import json
31
+ import os
32
+ import socket
33
+ import tempfile
34
+ import threading
35
+ from dataclasses import dataclass
36
+ from pathlib import Path
37
+ from types import TracebackType
38
+ from typing import Final, Self
39
+
40
+ import platformdirs
41
+ import structlog
42
+
43
+ from l3io.wp.backup.adapters.workspace import private_state_directories
44
+ from l3io.wp.backup.domain.errors import (
45
+ InvalidSiteDescriptorError,
46
+ SiteLockedError,
47
+ SiteLockLocationError,
48
+ SiteLockReleaseError,
49
+ )
50
+ from l3io.wp.backup.domain.lock import LockHolder, utc_z
51
+
52
+ __all__ = [
53
+ "APP_NAME",
54
+ "FcntlLockHandle",
55
+ "FcntlSiteLock",
56
+ "default_lock_dir",
57
+ "state_root",
58
+ ]
59
+
60
+ #: The per-user state directory's application name, shared with Epic 3.
61
+ APP_NAME: Final = "l3io-wp-backup"
62
+ _DIR_MODE: Final = 0o700
63
+ _FILE_MODE: Final = 0o600
64
+ #: A holder record is a few hundred bytes; anything larger is not one.
65
+ _RECORD_LIMIT: Final = 64 * 1024
66
+
67
+ _log = structlog.get_logger(__name__)
68
+
69
+
70
+ def state_root() -> Path:
71
+ """The per-user state directory: ``platformdirs.user_state_path(APP_NAME)``."""
72
+ return platformdirs.user_state_path(APP_NAME)
73
+
74
+
75
+ def default_lock_dir() -> Path:
76
+ """The per-user lock directory: ``<user state dir>/locks``."""
77
+ return state_root() / "locks"
78
+
79
+
80
+ # ``fcntl`` is imported where it is used, not at module import: on a platform
81
+ # without it (native Windows) importing this module must not crash a command
82
+ # before preflight refuses the platform (BL-E008-008).
83
+ def _lock_exclusive(fd: int) -> None:
84
+ import fcntl
85
+
86
+ fcntl.flock(fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
87
+
88
+
89
+ def _unlock(fd: int) -> None:
90
+ import fcntl
91
+
92
+ fcntl.flock(fd, fcntl.LOCK_UN)
93
+
94
+
95
+ @dataclass(slots=True)
96
+ class _Held:
97
+ """One Site this process holds: its descriptor, holder and depth."""
98
+
99
+ fd: int
100
+ holder: LockHolder
101
+ record_path: Path
102
+ depth: int
103
+
104
+
105
+ _REGISTRY: dict[Path, _Held] = {}
106
+ _REGISTRY_LOCK = threading.Lock()
107
+
108
+
109
+ def _inside(path: Path, root: Path) -> bool:
110
+ return path == root or path.is_relative_to(root)
111
+
112
+
113
+ def _read_record(path: Path) -> tuple[bool, LockHolder | None]:
114
+ """Whether a holder record exists, and the holder it names if readable."""
115
+ try:
116
+ fd = os.open(path, os.O_RDONLY | os.O_NOFOLLOW | os.O_CLOEXEC)
117
+ except FileNotFoundError:
118
+ return False, None
119
+ except OSError:
120
+ return True, None
121
+ try:
122
+ with os.fdopen(fd, "rb") as handle:
123
+ raw = handle.read(_RECORD_LIMIT + 1)
124
+ if len(raw) > _RECORD_LIMIT:
125
+ return True, None
126
+ record = json.loads(raw.decode("utf-8"))
127
+ if not isinstance(record, dict):
128
+ return True, None
129
+ return True, LockHolder.from_record(record)
130
+ except (OSError, UnicodeDecodeError, ValueError, TypeError):
131
+ return True, None
132
+
133
+
134
+ def _write_record(path: Path, holder: LockHolder, site_root: Path) -> None:
135
+ """Replace the holder record atomically, ``0600``, with ``json.dumps``."""
136
+ fd, tmp = tempfile.mkstemp(dir=path.parent, prefix=".", suffix=".tmp")
137
+ try:
138
+ with os.fdopen(fd, "w", encoding="utf-8") as handle:
139
+ handle.write(json.dumps(holder.as_record(str(site_root)), sort_keys=True))
140
+ handle.flush()
141
+ os.fsync(handle.fileno())
142
+ Path(tmp).replace(path)
143
+ except BaseException:
144
+ with contextlib.suppress(OSError):
145
+ Path(tmp).unlink()
146
+ raise
147
+
148
+
149
+ def _pid_alive(pid: int) -> bool:
150
+ """Words the stale-lock warning only; never decides ownership."""
151
+ try:
152
+ os.kill(pid, 0)
153
+ except ProcessLookupError:
154
+ return False
155
+ except OSError:
156
+ return True
157
+ return True
158
+
159
+
160
+ def _holder_fields(holder: LockHolder | None) -> dict[str, object]:
161
+ if holder is None:
162
+ return {"holder_run_id": None, "holder_pid": None, "holder_started_at": None}
163
+ return {
164
+ "holder_run_id": holder.run_id,
165
+ "holder_pid": holder.pid,
166
+ "holder_started_at": utc_z(holder.started_at),
167
+ "holder_hostname": holder.hostname,
168
+ }
169
+
170
+
171
+ def _refusal(
172
+ site_root: Path, lock_path: Path, holder: LockHolder | None
173
+ ) -> SiteLockedError:
174
+ fields = _holder_fields(holder)
175
+ _log.error(
176
+ "site_locked", site_root=str(site_root), lock_path=str(lock_path), **fields
177
+ )
178
+ if holder is None:
179
+ return SiteLockedError(site_root, lock_path)
180
+ return SiteLockedError(
181
+ site_root,
182
+ lock_path,
183
+ holder_run_id=holder.run_id,
184
+ holder_pid=holder.pid,
185
+ holder_started_at=utc_z(holder.started_at),
186
+ holder_hostname=holder.hostname,
187
+ )
188
+
189
+
190
+ class FcntlLockHandle:
191
+ """One acquisition of a Site Lock; the release that ends the last unlocks."""
192
+
193
+ __slots__ = ("_lock_path", "_released", "_site_root")
194
+
195
+ def __init__(self, site_root: Path, lock_path: Path) -> None:
196
+ self._site_root = site_root
197
+ self._lock_path = lock_path
198
+ self._released = False
199
+
200
+ @property
201
+ def site_root(self) -> Path:
202
+ """The canonical Site Root the lock is keyed on."""
203
+ return self._site_root
204
+
205
+ @property
206
+ def lock_path(self) -> Path:
207
+ """The lock file."""
208
+ return self._lock_path
209
+
210
+ def release(self) -> None:
211
+ """Release this acquisition; :class:`SiteLockReleaseError` if repeated."""
212
+ with _REGISTRY_LOCK:
213
+ held = _REGISTRY.get(self._lock_path)
214
+ if self._released or held is None:
215
+ raise SiteLockReleaseError(self._site_root)
216
+ self._released = True
217
+ held.depth -= 1
218
+ if held.depth > 0:
219
+ return
220
+ del _REGISTRY[self._lock_path]
221
+ try:
222
+ # Removed while still held: a later holder's record is never
223
+ # deleted, and a record left behind means the holder died.
224
+ held.record_path.unlink(missing_ok=True)
225
+ finally:
226
+ try:
227
+ _unlock(held.fd)
228
+ finally:
229
+ os.close(held.fd)
230
+ _log.debug(
231
+ "site_lock_released",
232
+ site_root=str(self._site_root),
233
+ lock_path=str(self._lock_path),
234
+ )
235
+
236
+ def __enter__(self) -> Self:
237
+ return self
238
+
239
+ def __exit__(
240
+ self,
241
+ exc_type: type[BaseException] | None,
242
+ exc: BaseException | None,
243
+ tb: TracebackType | None,
244
+ ) -> None:
245
+ self.release()
246
+
247
+ def __repr__(self) -> str:
248
+ return f"FcntlLockHandle(site_root={str(self._site_root)!r})"
249
+
250
+
251
+ class FcntlSiteLock:
252
+ """The Site Lock over ``fcntl.flock``; ``lock_dir`` overrides the default."""
253
+
254
+ def __init__(self, lock_dir: Path | None = None) -> None:
255
+ self._lock_dir = lock_dir
256
+
257
+ def _directory(self, site_root: Path) -> Path:
258
+ """The lock directory, created ``0700``, never inside ``site_root``."""
259
+ configured = default_lock_dir() if self._lock_dir is None else self._lock_dir
260
+ directory = Path(configured).absolute()
261
+ try:
262
+ if _inside(directory.resolve(), site_root):
263
+ reason = f"it is inside the site root {str(site_root)!r}"
264
+ raise SiteLockLocationError(directory, reason)
265
+ # BL-E008-027: checked before and after it is created.
266
+ private_state_directories(directory, root=state_root())
267
+ # A symlink placed after the check above is caught here.
268
+ directory = directory.resolve(strict=True)
269
+ if _inside(directory, site_root):
270
+ reason = f"it is inside the site root {str(site_root)!r}"
271
+ raise SiteLockLocationError(directory, reason)
272
+ if directory.stat().st_mode & 0o077:
273
+ directory.chmod(_DIR_MODE)
274
+ if not os.access(directory, os.W_OK | os.X_OK):
275
+ raise SiteLockLocationError(directory, "it is not writable")
276
+ except OSError as exc:
277
+ reason = f"it cannot be created or used ({exc.strerror or exc})"
278
+ raise SiteLockLocationError(directory, reason) from exc
279
+ return directory
280
+
281
+ def acquire(self, site_root: Path, holder: LockHolder) -> FcntlLockHandle:
282
+ """Hold ``site_root``'s lock for ``holder``.
283
+
284
+ ``site_root`` is canonicalised (``resolve(strict=True)``), so every
285
+ spelling of one Site takes one lock. :class:`SiteLockedError` names the
286
+ holder when another Run holds it.
287
+ """
288
+ try:
289
+ canonical = Path(site_root).resolve(strict=True)
290
+ except (OSError, RuntimeError) as exc:
291
+ msg = "site root does not exist"
292
+ raise InvalidSiteDescriptorError(
293
+ msg, paths=(str(Path(site_root).absolute()),)
294
+ ) from exc
295
+ directory = self._directory(canonical)
296
+ digest = hashlib.sha256(str(canonical).encode()).hexdigest()
297
+ lock_path = directory / f"{digest}.lock"
298
+ record_path = directory / f"{digest}.json"
299
+ with _REGISTRY_LOCK:
300
+ held = _REGISTRY.get(lock_path)
301
+ if held is not None:
302
+ if held.holder.run_id != holder.run_id:
303
+ raise _refusal(canonical, lock_path, held.holder)
304
+ held.depth += 1
305
+ return FcntlLockHandle(canonical, lock_path)
306
+ fd = self._lock(canonical, lock_path, record_path)
307
+ _REGISTRY[lock_path] = _Held(
308
+ fd=fd, holder=holder, record_path=record_path, depth=1
309
+ )
310
+ try:
311
+ self._reclaim_and_record(canonical, lock_path, record_path, holder)
312
+ except BaseException:
313
+ del _REGISTRY[lock_path]
314
+ try:
315
+ _unlock(fd)
316
+ finally:
317
+ os.close(fd)
318
+ raise
319
+ _log.info(
320
+ "site_lock_acquired", site_root=str(canonical), lock_path=str(lock_path)
321
+ )
322
+ return FcntlLockHandle(canonical, lock_path)
323
+
324
+ @staticmethod
325
+ def _lock(site_root: Path, lock_path: Path, record_path: Path) -> int:
326
+ """The lock file's descriptor, flocked; refuses if another holds it."""
327
+ flags = os.O_RDWR | os.O_CREAT | os.O_NOFOLLOW | os.O_CLOEXEC
328
+ try:
329
+ fd = os.open(lock_path, flags, _FILE_MODE)
330
+ except OSError as exc:
331
+ reason = f"the lock file cannot be opened ({exc.strerror or exc})"
332
+ raise SiteLockLocationError(lock_path, reason) from exc
333
+ try:
334
+ os.fchmod(fd, _FILE_MODE)
335
+ _lock_exclusive(fd)
336
+ except OSError as exc:
337
+ os.close(fd)
338
+ if exc.errno in (errno.EWOULDBLOCK, errno.EAGAIN, errno.EACCES):
339
+ _, holder = _read_record(record_path)
340
+ raise _refusal(site_root, lock_path, holder) from None
341
+ reason = f"the lock file cannot be locked ({exc.strerror or exc})"
342
+ raise SiteLockLocationError(lock_path, reason) from exc
343
+ return fd
344
+
345
+ @staticmethod
346
+ def _reclaim_and_record(
347
+ site_root: Path, lock_path: Path, record_path: Path, holder: LockHolder
348
+ ) -> None:
349
+ """Warn about a dead holder's record, then write this holder's."""
350
+ present, previous = _read_record(record_path)
351
+ if present:
352
+ fields = _holder_fields(previous)
353
+ alive = (
354
+ None
355
+ if previous is None or previous.hostname != socket.gethostname()
356
+ else _pid_alive(previous.pid)
357
+ )
358
+ _log.warning(
359
+ "stale_lock_reclaimed",
360
+ site_root=str(site_root),
361
+ lock_path=str(lock_path),
362
+ # ``previous_*``: ``run_id`` is the current Run's correlation key.
363
+ previous_run_id=fields["holder_run_id"],
364
+ previous_pid=fields["holder_pid"],
365
+ previous_started_at=fields["holder_started_at"],
366
+ previous_pid_alive=alive,
367
+ )
368
+ try:
369
+ _write_record(record_path, holder, site_root)
370
+ except OSError as exc:
371
+ reason = f"the holder record cannot be written ({exc.strerror or exc})"
372
+ raise SiteLockLocationError(record_path, reason) from exc