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,666 @@
1
+ """AD-4/AD-24 — the no-op command adapters, the inert tracer and its guard.
2
+
3
+ **No-op command adapters (AD-4).** One per ``*Command`` Protocol under
4
+ ``ports/``: :class:`NoopDatabase` (``DatabaseCommand``, both halves),
5
+ :class:`NoopArchiveWriter` (``ArchiveWriterCommand``),
6
+ :class:`NoopArchiveStore` (``ArchiveStoreCommand``), and the restore twins
7
+ :class:`NoopSiteFiles` (``SiteFilesCommand``), :class:`NoopConfigWriter`
8
+ (``ConfigCommand``), :class:`NoopSearchReplace` (``SearchReplaceCommand``) and
9
+ :class:`NoopRunJournal` (``RunJournalCommand``). A Dry Run binds them in
10
+ place of the real command halves (``cli.adapter_sets.dry_run_adapters``); the
11
+ query halves stay real. Each performs no effect, records the call into the
12
+ :class:`ActionLog` it was built with, emits ``phase_completed`` with
13
+ ``outcome="skipped_dry_run"`` and ``bytes=0`` (joining the step's phase when the
14
+ executor has one open) and returns a value of its declared type that lets the
15
+ plan continue. The no-op writer reads no Site Root file and calls no exclusion
16
+ policy (ADR-0019); the no-op store's staged Archive is an ``os.devnull`` writer
17
+ whose ``publish()`` returns ``False`` and calls no verifier (ADR-0022).
18
+ A restore twin's result says ``performed=False`` (ADR-0022); it records
19
+ ``keep``, ``exclude``, the **keys** of a config write — never its values — and
20
+ the journal event, so a restore Dry Run's log shows each skipped effect.
21
+ :class:`NoopDatabase`'s restore methods make the same AD-29 administrator
22
+ check as the real adapter, so a Dry Run refuses where the real Run would.
23
+
24
+ :class:`NoopTracer` implements ``ports.tracing.Tracer``, ``RunSpan`` and
25
+ ``PhaseSpan`` and records nothing; ``tracer=None`` means ``NoopTracer()``.
26
+
27
+ :class:`GuardedTracer` wraps the Run's tracer so tracing never changes an
28
+ outcome: the first exception any tracer call raises is logged once, at
29
+ WARNING, as ``tracer_failed`` with the tracer's type name, and every later
30
+ call for that Run is a no-op. Only ``Exception`` is caught —
31
+ ``KeyboardInterrupt`` and ``SystemExit`` still propagate.
32
+ """
33
+
34
+ from __future__ import annotations
35
+
36
+ import os
37
+ from collections.abc import Callable, Iterable, Iterator, Mapping, Sequence
38
+ from contextlib import AbstractContextManager, contextmanager
39
+ from dataclasses import dataclass
40
+ from pathlib import Path, PurePosixPath
41
+ from typing import IO, Final, TypeVar
42
+
43
+ import structlog
44
+
45
+ from l3io.wp.backup.adapters.config_writer import carry_sources
46
+ from l3io.wp.backup.adapters.database import ADMIN_FLAGS, ADMIN_SOURCE
47
+ from l3io.wp.backup.adapters.phase import SKIPPED_OUTCOME, join_open_phase, phase
48
+ from l3io.wp.backup.adapters.site_files import refuse_unsafe_clean_target
49
+ from l3io.wp.backup.core.backup import BackupStep
50
+ from l3io.wp.backup.domain.archive_format import (
51
+ ArchiveView,
52
+ ExtractResult,
53
+ Manifest,
54
+ MemberRole,
55
+ )
56
+ from l3io.wp.backup.domain.config import ConfigWriteResult
57
+ from l3io.wp.backup.domain.database import (
58
+ DatabaseLocation,
59
+ DumpResult,
60
+ EnsureOutcome,
61
+ LoadResult,
62
+ )
63
+ from l3io.wp.backup.domain.errors import AdminCredentialsRequiredError, RunTerminated
64
+ from l3io.wp.backup.domain.journal import JournalHeader
65
+ from l3io.wp.backup.domain.restore import RestorePhase
66
+ from l3io.wp.backup.domain.search_replace import (
67
+ UNRESOLVED_URL,
68
+ Replacement,
69
+ SearchReplaceReport,
70
+ UrlRelocation,
71
+ )
72
+ from l3io.wp.backup.domain.storage_target import StorageTarget
73
+ from l3io.wp.backup.ports.archive import ManifestBuilder
74
+ from l3io.wp.backup.ports.crypto import PayloadCipher
75
+ from l3io.wp.backup.ports.exclusion import ExclusionPolicy
76
+ from l3io.wp.backup.ports.site_files import require_site_relative, require_top_level
77
+ from l3io.wp.backup.ports.tracing import (
78
+ PhaseSpan,
79
+ Redactor,
80
+ RunSpan,
81
+ SpanAttributes,
82
+ Tracer,
83
+ )
84
+
85
+ __all__ = [
86
+ "JOURNAL_PHASE",
87
+ "ActionLog",
88
+ "GuardedTracer",
89
+ "NoopArchiveStore",
90
+ "NoopArchiveWriter",
91
+ "NoopConfigWriter",
92
+ "NoopDatabase",
93
+ "NoopRunJournal",
94
+ "NoopSearchReplace",
95
+ "NoopSiteFiles",
96
+ "NoopTracer",
97
+ "SkippedCall",
98
+ ]
99
+
100
+ _log = structlog.get_logger(__name__)
101
+
102
+ _T = TypeVar("_T")
103
+
104
+
105
+ class NoopTracer:
106
+ """A ``Tracer`` that is also its own ``RunSpan`` and ``PhaseSpan``."""
107
+
108
+ __slots__ = ()
109
+
110
+ @contextmanager
111
+ def run_span(
112
+ self,
113
+ *,
114
+ run_id: str,
115
+ operation: str,
116
+ attributes: SpanAttributes,
117
+ command_args: Sequence[str] | None,
118
+ secrets: Redactor,
119
+ ) -> Iterator[RunSpan]:
120
+ """Nothing is recorded."""
121
+ del run_id, operation, attributes, command_args, secrets
122
+ yield self
123
+
124
+ @contextmanager
125
+ def phase_span(self, phase: str, *, secrets: Redactor) -> Iterator[PhaseSpan]:
126
+ """Nothing is recorded."""
127
+ del phase, secrets
128
+ yield self
129
+
130
+ def set_attributes(
131
+ self, *, db_name: str | None = None, archive_bytes: int | None = None
132
+ ) -> None:
133
+ """Nothing is recorded."""
134
+ del db_name, archive_bytes
135
+
136
+ def set_outcome(
137
+ self,
138
+ *,
139
+ exit_code: int,
140
+ error_type: str | None = None,
141
+ archive_bytes: int | None = None,
142
+ ) -> None:
143
+ """Nothing is recorded."""
144
+ del exit_code, error_type, archive_bytes
145
+
146
+
147
+ _NOOP: Final = NoopTracer()
148
+ _NOOP_RUN_SPAN: Final[RunSpan] = _NOOP
149
+ _NOOP_PHASE_SPAN: Final[PhaseSpan] = _NOOP
150
+
151
+
152
+ class _Failed:
153
+ """The result of a tracer call that raised."""
154
+
155
+
156
+ _FAILED: Final = _Failed()
157
+
158
+
159
+ class GuardedTracer:
160
+ """A ``Tracer`` whose calls never raise; the first failure disables it."""
161
+
162
+ __slots__ = ("_disabled", "_inner")
163
+
164
+ def __init__(self, inner: Tracer) -> None:
165
+ self._inner = inner
166
+ self._disabled = False
167
+
168
+ def __repr__(self) -> str:
169
+ return f"GuardedTracer({type(self._inner).__name__})"
170
+
171
+ @property
172
+ def inner(self) -> Tracer:
173
+ """The tracer being guarded."""
174
+ return self._inner
175
+
176
+ def call(self, fn: Callable[[], _T], *, closing: bool = False) -> _T | _Failed:
177
+ """``fn()``, or :data:`_FAILED` once any call has raised.
178
+
179
+ ``closing`` marks the exit of a span that was entered: it is attempted
180
+ even after a failure, so a real tracer's span is still ended and its
181
+ context detached; it never logs a second ``tracer_failed``.
182
+ """
183
+ if self._disabled and not closing:
184
+ return _FAILED
185
+ try:
186
+ return fn()
187
+ except RunTerminated:
188
+ raise # a SIGTERM is the Run's, never the tracer's failure (BL-E002-092)
189
+ except Exception as exc:
190
+ if not self._disabled:
191
+ self._disabled = True
192
+ _log.warning(
193
+ "tracer_failed",
194
+ tracer=type(self._inner).__name__,
195
+ error=type(exc).__name__,
196
+ )
197
+ return _FAILED
198
+
199
+ @contextmanager
200
+ def _span(
201
+ self,
202
+ opener: Callable[[], AbstractContextManager[_T]],
203
+ wrap: Callable[[_T], _T],
204
+ fallback: _T,
205
+ ) -> Iterator[_T]:
206
+ manager = self.call(opener)
207
+ span: _T | _Failed = _FAILED
208
+ if not isinstance(manager, _Failed):
209
+ span = self.call(manager.__enter__)
210
+ if isinstance(manager, _Failed) or isinstance(span, _Failed):
211
+ yield fallback
212
+ return
213
+ try:
214
+ yield wrap(span)
215
+ except BaseException as exc:
216
+ failure = exc
217
+ self.call(
218
+ lambda: manager.__exit__(type(failure), failure, failure.__traceback__),
219
+ closing=True,
220
+ )
221
+ raise
222
+ self.call(lambda: manager.__exit__(None, None, None), closing=True)
223
+
224
+ @contextmanager
225
+ def run_span(
226
+ self,
227
+ *,
228
+ run_id: str,
229
+ operation: str,
230
+ attributes: SpanAttributes,
231
+ command_args: Sequence[str] | None,
232
+ secrets: Redactor,
233
+ ) -> Iterator[RunSpan]:
234
+ """The inner tracer's root span, guarded; a no-op span on failure."""
235
+ with self._span(
236
+ lambda: self._inner.run_span(
237
+ run_id=run_id,
238
+ operation=operation,
239
+ attributes=attributes,
240
+ command_args=command_args,
241
+ secrets=secrets,
242
+ ),
243
+ lambda span: _GuardedRunSpan(self, span),
244
+ _NOOP_RUN_SPAN,
245
+ ) as span:
246
+ yield span
247
+
248
+ @contextmanager
249
+ def phase_span(self, phase: str, *, secrets: Redactor) -> Iterator[PhaseSpan]:
250
+ """The inner tracer's phase span, guarded; a no-op span on failure."""
251
+ with self._span(
252
+ lambda: self._inner.phase_span(phase, secrets=secrets),
253
+ lambda span: _GuardedPhaseSpan(self, span),
254
+ _NOOP_PHASE_SPAN,
255
+ ) as span:
256
+ yield span
257
+
258
+
259
+ class _GuardedRunSpan:
260
+ __slots__ = ("_guard", "_span")
261
+
262
+ def __init__(self, guard: GuardedTracer, span: RunSpan) -> None:
263
+ self._guard, self._span = guard, span
264
+
265
+ def set_attributes(
266
+ self, *, db_name: str | None = None, archive_bytes: int | None = None
267
+ ) -> None:
268
+ self._guard.call(
269
+ lambda: self._span.set_attributes(
270
+ db_name=db_name, archive_bytes=archive_bytes
271
+ )
272
+ )
273
+
274
+ def set_outcome(self, *, exit_code: int, error_type: str | None) -> None:
275
+ self._guard.call(
276
+ lambda: self._span.set_outcome(exit_code=exit_code, error_type=error_type)
277
+ )
278
+
279
+
280
+ class _GuardedPhaseSpan:
281
+ __slots__ = ("_guard", "_span")
282
+
283
+ def __init__(self, guard: GuardedTracer, span: PhaseSpan) -> None:
284
+ self._guard, self._span = guard, span
285
+
286
+ def set_outcome(self, *, exit_code: int, archive_bytes: int | None) -> None:
287
+ self._guard.call(
288
+ lambda: self._span.set_outcome(
289
+ exit_code=exit_code, archive_bytes=archive_bytes
290
+ )
291
+ )
292
+
293
+
294
+ # --------------------------------------------------------------------------
295
+ # No-op command adapters (AD-4)
296
+ # --------------------------------------------------------------------------
297
+
298
+
299
+ @dataclass(frozen=True, slots=True)
300
+ class SkippedCall:
301
+ """One command a no-op adapter stood in for."""
302
+
303
+ adapter: str
304
+ method: str
305
+ target: str | None = None
306
+
307
+
308
+ class ActionLog:
309
+ """The commands a Dry Run did not perform, in the order they were reached."""
310
+
311
+ __slots__ = ("_calls",)
312
+
313
+ def __init__(self) -> None:
314
+ self._calls: list[SkippedCall] = []
315
+
316
+ def __repr__(self) -> str:
317
+ return f"ActionLog({len(self._calls)} calls)"
318
+
319
+ def record(self, adapter: str, method: str, target: str | None = None) -> None:
320
+ """Append one skipped call."""
321
+ self._calls.append(SkippedCall(adapter, method, target))
322
+
323
+ @property
324
+ def calls(self) -> tuple[SkippedCall, ...]:
325
+ """Every call recorded so far."""
326
+ return tuple(self._calls)
327
+
328
+
329
+ def _skip(phase_name: str, **fields: object) -> None:
330
+ """Mark the open phase ``skipped_dry_run``; ``phase_name`` only if none is open."""
331
+ with join_open_phase(phase_name) as record:
332
+ record.skip()
333
+ record.fields.update(fields)
334
+
335
+
336
+ def _names(paths: Iterable[PurePosixPath]) -> list[str]:
337
+ return sorted(str(p) for p in paths)
338
+
339
+
340
+ class NoopDatabase:
341
+ """``DatabaseCommand``: dumps, creates, loads and drops nothing.
342
+
343
+ ``administrator`` is whether the real adapter it stands in for has an
344
+ administrator bound: the provisioning methods (``ensure_database``,
345
+ ``drop_database``) refuse without one, as the real
346
+ ones do (AD-29); ``load_dump`` and ``drop_tables`` are the WordPress
347
+ account's.
348
+ """
349
+
350
+ __slots__ = ("_administrator", "_log")
351
+
352
+ def __init__(self, log: ActionLog, *, administrator: bool = False) -> None:
353
+ self._log = log
354
+ self._administrator = administrator
355
+
356
+ def _require_admin(self) -> None:
357
+ if not self._administrator:
358
+ raise AdminCredentialsRequiredError(ADMIN_SOURCE, flags=ADMIN_FLAGS)
359
+
360
+ def dump_to(self, location: DatabaseLocation, destination: Path) -> DumpResult:
361
+ """A zero-byte result; ``destination`` is not created."""
362
+ del destination
363
+ with join_open_phase(BackupStep.DUMP.value) as record:
364
+ record.skip()
365
+ self._log.record("NoopDatabase", "dump_to", location.name)
366
+ return DumpResult(bytes=0, duration_ms=0.0)
367
+
368
+ def ensure_database(self, location: DatabaseLocation) -> EnsureOutcome:
369
+ """Nothing created, granted or set."""
370
+ self._require_admin()
371
+ _skip(RestorePhase.LOAD_DUMP.name, method="ensure_database")
372
+ self._log.record("NoopDatabase", "ensure_database", location.name)
373
+ return EnsureOutcome(
374
+ created_database=False,
375
+ created_user=False,
376
+ password_set=False,
377
+ granted=False,
378
+ warnings=(SKIPPED_OUTCOME,),
379
+ performed=False,
380
+ )
381
+
382
+ def load_dump(
383
+ self,
384
+ location: DatabaseLocation,
385
+ source: IO[bytes] | Path,
386
+ *,
387
+ replace: bool = False,
388
+ prune_prefix: str | None = None,
389
+ ) -> LoadResult:
390
+ """Nothing loaded or dropped; ``source`` is not read."""
391
+ del source
392
+ _skip(
393
+ RestorePhase.LOAD_DUMP.name,
394
+ method="load_dump",
395
+ replace=replace,
396
+ prune_prefix=prune_prefix,
397
+ )
398
+ self._log.record("NoopDatabase", "load_dump", location.name)
399
+ return LoadResult(bytes=0, duration_ms=0.0, performed=False)
400
+
401
+ def drop_tables(
402
+ self, location: DatabaseLocation, *, prefix: str
403
+ ) -> tuple[str, ...]:
404
+ """``()``: nothing dropped."""
405
+ _skip(RestorePhase.LOAD_DUMP.name, method="drop_tables", prefix=prefix)
406
+ self._log.record("NoopDatabase", "drop_tables", location.name)
407
+ return ()
408
+
409
+ def drop_database(self, location: DatabaseLocation, *, confirm: str) -> bool:
410
+ """``False``: nothing dropped."""
411
+ del confirm
412
+ self._require_admin()
413
+ _skip(RestorePhase.CLEAN.name, method="drop_database")
414
+ self._log.record("NoopDatabase", "drop_database", location.name)
415
+ return False
416
+
417
+
418
+ class NoopArchiveWriter:
419
+ """``ArchiveWriterCommand``: collects, encrypts and writes nothing."""
420
+
421
+ __slots__ = ("_log",)
422
+
423
+ def __init__(self, log: ActionLog) -> None:
424
+ self._log = log
425
+
426
+ def write(
427
+ self,
428
+ out: IO[bytes],
429
+ *,
430
+ site_root: Path | None,
431
+ dump: Path | None,
432
+ config: Path,
433
+ exclusion: ExclusionPolicy,
434
+ cipher: PayloadCipher | None,
435
+ manifest_builder: ManifestBuilder,
436
+ workspace: Path,
437
+ ) -> Manifest:
438
+ """The Manifest of an empty index; nothing is read or written."""
439
+ del out, dump, config, exclusion, workspace
440
+ if site_root is not None:
441
+ with phase(BackupStep.COLLECT_SITE_ROOT.value) as record:
442
+ record.skip()
443
+ if cipher is not None:
444
+ with phase(BackupStep.ENCRYPT.value) as record:
445
+ record.skip()
446
+ with phase(BackupStep.WRITE_ARCHIVE.value) as record:
447
+ record.skip()
448
+ self._log.record("NoopArchiveWriter", "write")
449
+ return manifest_builder((), ())
450
+
451
+
452
+ class _NoopStagedArchive:
453
+ """A staged Archive that is never written, verified or published."""
454
+
455
+ __slots__ = ("_log", "_stream", "_target")
456
+
457
+ def __init__(self, log: ActionLog, target: str) -> None:
458
+ self._log = log
459
+ self._target = target
460
+ self._stream: IO[bytes] = Path(os.devnull).open("wb") # noqa: SIM115
461
+
462
+ @property
463
+ def stream(self) -> IO[bytes]:
464
+ """An ``os.devnull`` writer: nothing accumulates (AD-21)."""
465
+ return self._stream
466
+
467
+ @property
468
+ def staged_path(self) -> Path | None:
469
+ """``None``: nothing is staged on disk."""
470
+ return None
471
+
472
+ def publish(self) -> bool:
473
+ """``False``: not performed. No verifier is called."""
474
+ self._stream.close()
475
+ with phase(BackupStep.VERIFY.value) as record:
476
+ record.skip()
477
+ with phase(BackupStep.PUBLISH.value) as record:
478
+ record.skip()
479
+ self._log.record("NoopArchiveStore", "publish", self._target)
480
+ return False
481
+
482
+ def discard(self) -> None:
483
+ """Nothing was staged; the sink is closed."""
484
+ self._stream.close()
485
+
486
+
487
+ class NoopArchiveStore:
488
+ """``ArchiveStoreCommand``: stages nothing at the Storage Target."""
489
+
490
+ __slots__ = ("_log",)
491
+
492
+ def __init__(self, log: ActionLog) -> None:
493
+ self._log = log
494
+
495
+ def stage(self, target: StorageTarget) -> _NoopStagedArchive:
496
+ """A staged Archive whose stream discards every byte."""
497
+ self._log.record("NoopArchiveStore", "stage", str(target.path))
498
+ return _NoopStagedArchive(self._log, str(target.path))
499
+
500
+
501
+ class NoopSiteFiles:
502
+ """``SiteFilesCommand``: removes and extracts nothing."""
503
+
504
+ __slots__ = ("_log",)
505
+
506
+ def __init__(self, log: ActionLog) -> None:
507
+ self._log = log
508
+
509
+ def clean(self, site_root: Path, *, keep: frozenset[PurePosixPath]) -> int:
510
+ """``0``: nothing removed. ``keep`` and the target are checked as the
511
+ real one checks them, so an unsafe target is refused here too."""
512
+ require_site_relative(keep, argument="keep")
513
+ require_top_level(keep, argument="keep")
514
+ refuse_unsafe_clean_target(site_root.absolute())
515
+ _skip(RestorePhase.CLEAN.name, method="clean", keep=_names(keep))
516
+ self._log.record("NoopSiteFiles", "clean", str(site_root))
517
+ return 0
518
+
519
+ def extract(
520
+ self,
521
+ source: StorageTarget,
522
+ destination: Path,
523
+ view: ArchiveView,
524
+ *,
525
+ roles: frozenset[MemberRole],
526
+ exclude: frozenset[PurePosixPath] = frozenset(),
527
+ payload: Path | None = None,
528
+ ) -> ExtractResult:
529
+ """Nothing read or written; ``exclude`` is checked as the real one checks it."""
530
+ del source, view, payload
531
+ require_site_relative(exclude, argument="exclude")
532
+ _skip(
533
+ RestorePhase.EXTRACT.name,
534
+ method="extract",
535
+ roles=sorted(r.value for r in roles),
536
+ exclude=_names(exclude),
537
+ )
538
+ self._log.record("NoopSiteFiles", "extract", str(destination))
539
+ return ExtractResult(members=0, bytes=0, skipped_links=())
540
+
541
+
542
+ class NoopConfigWriter:
543
+ """``ConfigCommand``: writes, copies and replaces nothing.
544
+
545
+ Records constant **names** only: ``set_constants`` may be handed a
546
+ ``DB_PASSWORD`` value (relocation), and it must never reach a log.
547
+ """
548
+
549
+ __slots__ = ("_log",)
550
+
551
+ def __init__(self, log: ActionLog) -> None:
552
+ self._log = log
553
+
554
+ def _skipped(self, method: str, target: Path, keys: Iterable[str]) -> None:
555
+ _skip(RestorePhase.REWRITE_CONFIG.name, method=method, keys=sorted(keys))
556
+ self._log.record("NoopConfigWriter", method, str(target))
557
+
558
+ def set_constants(
559
+ self, config_file: Path, values: Mapping[str, str | int | bool]
560
+ ) -> ConfigWriteResult:
561
+ """Nothing changed; the keys of ``values`` are recorded, not the values."""
562
+ self._skipped("set_constants", config_file, values.keys())
563
+ return ConfigWriteResult(changed=(), performed=False)
564
+
565
+ def save_copy(self, config_file: Path, destination: Path) -> ConfigWriteResult:
566
+ """Nothing copied; ``destination`` is not created."""
567
+ del config_file
568
+ self._skipped("save_copy", destination, ())
569
+ return ConfigWriteResult(changed=(), performed=False)
570
+
571
+ def replace_file(
572
+ self,
573
+ config_file: Path,
574
+ content: str,
575
+ *,
576
+ keep: Sequence[str],
577
+ ) -> ConfigWriteResult:
578
+ """Nothing replaced and nothing written; the ``keep`` keys are recorded.
579
+
580
+ ``keep`` is carried into ``content`` in memory as the real writer
581
+ carries it (``carry_sources``, a read of ``config_file``), so what it
582
+ refuses -- a key the target does not define, a source that cannot be
583
+ carried, a ``getenv_docker()`` the Archive's text does not define --
584
+ the Dry Run refuses too.
585
+ """
586
+ carry_sources(config_file, content, keep)
587
+ self._skipped("replace_file", config_file, keep)
588
+ return ConfigWriteResult(changed=(), performed=False)
589
+
590
+
591
+ class NoopSearchReplace:
592
+ """``SearchReplaceCommand``: replaces nothing and reads nothing.
593
+
594
+ The planned pairs carry :data:`UNRESOLVED_URL` as ``old`` and every count
595
+ is ``None``: the stored URLs live in a database a Dry Run did not load.
596
+ """
597
+
598
+ __slots__ = ("_log",)
599
+
600
+ def __init__(self, log: ActionLog) -> None:
601
+ self._log = log
602
+
603
+ def relocate_content(
604
+ self,
605
+ site_root: Path,
606
+ urls: UrlRelocation,
607
+ *,
608
+ archive_encrypted: bool | None = None,
609
+ ) -> SearchReplaceReport:
610
+ """The planned pairs, ``old`` unresolved; nothing replaced."""
611
+ del archive_encrypted
612
+ targets = (urls.site_url, urls.home_url)
613
+ news = list(dict.fromkeys(u for u in targets if u is not None))
614
+ _skip(RestorePhase.SEARCH_REPLACE.name, method="relocate_content")
615
+ self._log.record("NoopSearchReplace", "relocate_content", str(site_root))
616
+ return SearchReplaceReport(
617
+ pairs=tuple(Replacement(old=UNRESOLVED_URL, new=new) for new in news),
618
+ replacements=None,
619
+ tables=None,
620
+ remaining=None,
621
+ merged=False,
622
+ )
623
+
624
+
625
+ #: The ``phase`` of a skipped journal call's ``phase_completed`` record. A
626
+ #: journal call is not a restore phase's effect, so it never joins one; the
627
+ #: restore phase it concerns is the record's ``journal_phase`` field.
628
+ JOURNAL_PHASE: Final = "JOURNAL"
629
+
630
+
631
+ class NoopRunJournal:
632
+ """``RunJournalCommand``: records nothing, so a Dry Run resolves nothing."""
633
+
634
+ __slots__ = ("_log",)
635
+
636
+ def __init__(self, log: ActionLog) -> None:
637
+ self._log = log
638
+
639
+ def _skipped(self, event: str, target: str | None = None, **fields: object) -> None:
640
+ # ``journal_event``: ``event`` is the log record's own name.
641
+ _skip(JOURNAL_PHASE, journal_event=event, **fields)
642
+ self._log.record("NoopRunJournal", event, target)
643
+
644
+ def begin_run(self, header: JournalHeader) -> None:
645
+ """Nothing written."""
646
+ self._skipped("begin_run", header.run_id)
647
+
648
+ def phase_started(self, phase: RestorePhase, target: str) -> None:
649
+ """Nothing written."""
650
+ self._skipped("phase_started", target, journal_phase=phase.value)
651
+
652
+ def step_completed(self, phase: RestorePhase, step: str) -> None:
653
+ """Nothing written."""
654
+ self._skipped("step_completed", step, journal_phase=phase.value)
655
+
656
+ def phase_completed(self, phase: RestorePhase) -> None:
657
+ """Nothing written."""
658
+ self._skipped("phase_completed", None, journal_phase=phase.value)
659
+
660
+ def finish_run(self) -> None:
661
+ """Nothing written."""
662
+ self._skipped("finish_run")
663
+
664
+ def resolve(self, run_id: str, resolved_by: str) -> None:
665
+ """Nothing resolved (ADR-0021)."""
666
+ self._skipped("resolve", run_id, resolved_by=resolved_by)