askrobots / dbbasic-object-server
Public
Runs live, versioned Python application objects on one VM, with a suite of apps: projects, notes, tasks, files and more.
danq9
signup: the person chooses the password and name on the confirm page
83c7aa6
2 weeks, 5 days ago
History
object_backup.py · 24.2 KB · 727 lines
| 1 | """Runtime backup and restore helpers for DBBASIC Object Server. |
| 2 | |
| 3 | The runtime backup format is intentionally narrow. It captures live object |
| 4 | source and runtime-owned data, but it does not include deployment secrets, |
| 5 | systemd units, provider metadata, virtualenvs, caches, or git history. |
| 6 | """ |
| 7 | from __future__ import annotations |
| 8 | |
| 9 | import argparse |
| 10 | import io |
| 11 | import json |
| 12 | import os |
| 13 | import re |
| 14 | import tarfile |
| 15 | from dataclasses import asdict, dataclass |
| 16 | from datetime import datetime, timezone |
| 17 | from pathlib import Path, PurePosixPath |
| 18 | from typing import Any, Sequence |
| 19 | |
| 20 | from object_namespace import DEFAULT_OBJECTS_DIR, OBJECTS_DIR_ENV |
| 21 | from object_versions import DEFAULT_DATA_DIR |
| 22 | |
| 23 | DATA_DIR_ENV = "DBBASIC_DATA_DIR" |
| 24 | BACKUPS_DIR_ENV = "DBBASIC_BACKUPS_DIR" |
| 25 | BACKUP_FORMAT_VERSION = 1 |
| 26 | MANIFEST_NAME = "dbbasic-backup-manifest.json" |
| 27 | BACKUPS_DIR = "backups" |
| 28 | RUNTIME_DATA_DIRS = ( |
| 29 | "state", |
| 30 | "logs", |
| 31 | "versions", |
| 32 | "source_changes", |
| 33 | "schema_versions", |
| 34 | "record_changes", |
| 35 | "package_changes", |
| 36 | "package_baselines", |
| 37 | "reconciles", |
| 38 | "file_changes", |
| 39 | "files", |
| 40 | "schemas", |
| 41 | "collections", |
| 42 | ) |
| 43 | SKIP_PARTS = {"__pycache__", ".git", ".venv", "node_modules"} |
| 44 | SKIP_SUFFIXES = (".pyc", ".pyo", ".tmp", ".lock") |
| 45 | RESTORE_POINT_LABEL_RE = re.compile(r"^[a-z0-9][a-z0-9_.-]{0,127}$") |
| 46 | |
| 47 | |
| 48 | class BackupError(Exception): |
| 49 | """Base exception for backup operations.""" |
| 50 | |
| 51 | |
| 52 | class BackupRestoreError(BackupError): |
| 53 | """Raised when a backup cannot be safely restored.""" |
| 54 | |
| 55 | |
| 56 | @dataclass(frozen=True) |
| 57 | class BackupSummary: |
| 58 | path: str |
| 59 | format_version: int |
| 60 | created_at: str |
| 61 | files: int |
| 62 | bytes: int |
| 63 | entries: list[str] |
| 64 | warnings: list[str] |
| 65 | |
| 66 | def to_dict(self) -> dict[str, Any]: |
| 67 | return asdict(self) |
| 68 | |
| 69 | |
| 70 | @dataclass(frozen=True) |
| 71 | class BackupVerification: |
| 72 | path: str |
| 73 | ok: bool |
| 74 | format_version: int | None |
| 75 | files: int |
| 76 | bytes: int |
| 77 | entries: list[str] |
| 78 | errors: list[str] |
| 79 | warnings: list[str] |
| 80 | manifest: dict[str, Any] | None |
| 81 | |
| 82 | def to_dict(self) -> dict[str, Any]: |
| 83 | return asdict(self) |
| 84 | |
| 85 | |
| 86 | @dataclass(frozen=True) |
| 87 | class RestoreSummary: |
| 88 | backup_path: str |
| 89 | objects_dir: str |
| 90 | data_dir: str |
| 91 | files: int |
| 92 | bytes: int |
| 93 | overwritten: bool |
| 94 | pruned_files: int = 0 |
| 95 | pruned_dirs: int = 0 |
| 96 | scoped: bool = False |
| 97 | selected: int = 0 |
| 98 | |
| 99 | def to_dict(self) -> dict[str, Any]: |
| 100 | return asdict(self) |
| 101 | |
| 102 | |
| 103 | def create_runtime_backup( |
| 104 | output_path: Path | str, |
| 105 | *, |
| 106 | objects_dir: Path | str | None = None, |
| 107 | data_dir: Path | str | None = None, |
| 108 | created_at: str | None = None, |
| 109 | ) -> BackupSummary: |
| 110 | """Create a tar/gzip archive containing object source and runtime data.""" |
| 111 | output = Path(output_path) |
| 112 | objects_path = _objects_dir(objects_dir) |
| 113 | data_path = _data_dir(data_dir) |
| 114 | timestamp = created_at or _utc_timestamp() |
| 115 | |
| 116 | members: list[tuple[Path, PurePosixPath]] = [] |
| 117 | warnings: list[str] = [] |
| 118 | entries: list[str] = [] |
| 119 | file_count = 0 |
| 120 | byte_count = 0 |
| 121 | |
| 122 | for source_path, archive_root in _runtime_sources(objects_path, data_path): |
| 123 | if not source_path.exists(): |
| 124 | continue |
| 125 | if not source_path.is_dir(): |
| 126 | warnings.append(f"skipped non-directory source: {archive_root.as_posix()}") |
| 127 | continue |
| 128 | |
| 129 | entries.append(archive_root.as_posix()) |
| 130 | for path, archive_name in _iter_backup_members(source_path, archive_root): |
| 131 | members.append((path, archive_name)) |
| 132 | if path.is_file(): |
| 133 | file_count += 1 |
| 134 | byte_count += path.stat().st_size |
| 135 | |
| 136 | if file_count == 0: |
| 137 | warnings.append("backup contains no runtime files") |
| 138 | |
| 139 | manifest = { |
| 140 | "format_version": BACKUP_FORMAT_VERSION, |
| 141 | "created_at": timestamp, |
| 142 | "type": "dbbasic-runtime", |
| 143 | "entries": entries, |
| 144 | "files": file_count, |
| 145 | "bytes": byte_count, |
| 146 | "notes": [ |
| 147 | "deployment secrets are not included", |
| 148 | "systemd service files are not included", |
| 149 | "git history and virtualenvs are not included", |
| 150 | ], |
| 151 | "warnings": warnings, |
| 152 | } |
| 153 | |
| 154 | output.parent.mkdir(parents=True, exist_ok=True) |
| 155 | with tarfile.open(output, "w:gz", format=tarfile.PAX_FORMAT) as archive: |
| 156 | _add_manifest(archive, manifest) |
| 157 | for path, archive_name in members: |
| 158 | _add_path(archive, path, archive_name) |
| 159 | |
| 160 | return BackupSummary( |
| 161 | path=str(output), |
| 162 | format_version=BACKUP_FORMAT_VERSION, |
| 163 | created_at=timestamp, |
| 164 | files=file_count, |
| 165 | bytes=byte_count, |
| 166 | entries=entries, |
| 167 | warnings=warnings, |
| 168 | ) |
| 169 | |
| 170 | |
| 171 | def create_runtime_restore_point( |
| 172 | label: str, |
| 173 | *, |
| 174 | objects_dir: Path | str | None = None, |
| 175 | data_dir: Path | str | None = None, |
| 176 | backups_dir: Path | str | None = None, |
| 177 | created_at: str | None = None, |
| 178 | ) -> BackupSummary: |
| 179 | """Create a named runtime backup under the configured restore-point directory.""" |
| 180 | clean_label = _restore_point_label(label) |
| 181 | timestamp = created_at or _utc_timestamp() |
| 182 | output_dir = _backups_dir(backups_dir, data_dir=data_dir) |
| 183 | output_path = output_dir / f"{_backup_filename_timestamp(timestamp)}-{clean_label}.tar.gz" |
| 184 | return create_runtime_backup( |
| 185 | output_path, |
| 186 | objects_dir=objects_dir, |
| 187 | data_dir=data_dir, |
| 188 | created_at=timestamp, |
| 189 | ) |
| 190 | |
| 191 | |
| 192 | def verify_runtime_backup(backup_path: Path | str) -> BackupVerification: |
| 193 | """Inspect a runtime backup archive without extracting it.""" |
| 194 | path = Path(backup_path) |
| 195 | errors: list[str] = [] |
| 196 | warnings: list[str] = [] |
| 197 | manifest: dict[str, Any] | None = None |
| 198 | entries: set[str] = set() |
| 199 | file_count = 0 |
| 200 | byte_count = 0 |
| 201 | |
| 202 | try: |
| 203 | with tarfile.open(path, "r:*") as archive: |
| 204 | manifest = _read_manifest(archive, errors) |
| 205 | for member in archive.getmembers(): |
| 206 | if member.name == MANIFEST_NAME: |
| 207 | continue |
| 208 | errors.extend(_validate_member(member)) |
| 209 | root = _member_entry(member.name) |
| 210 | if root is not None: |
| 211 | entries.add(root) |
| 212 | if member.isfile(): |
| 213 | file_count += 1 |
| 214 | byte_count += member.size |
| 215 | except (tarfile.TarError, OSError) as exc: |
| 216 | errors.append(f"cannot read backup archive: {exc}") |
| 217 | |
| 218 | format_version = None |
| 219 | if manifest is not None: |
| 220 | format_version = _manifest_int(manifest.get("format_version")) |
| 221 | if format_version != BACKUP_FORMAT_VERSION: |
| 222 | errors.append(f"unsupported backup format version: {format_version}") |
| 223 | if _manifest_int(manifest.get("files")) != file_count: |
| 224 | errors.append("manifest file count does not match archive") |
| 225 | if _manifest_int(manifest.get("bytes")) != byte_count: |
| 226 | errors.append("manifest byte count does not match archive") |
| 227 | warnings.extend(str(warning) for warning in manifest.get("warnings", [])) |
| 228 | |
| 229 | return BackupVerification( |
| 230 | path=str(path), |
| 231 | ok=not errors, |
| 232 | format_version=format_version, |
| 233 | files=file_count, |
| 234 | bytes=byte_count, |
| 235 | entries=sorted(entries), |
| 236 | errors=errors, |
| 237 | warnings=warnings, |
| 238 | manifest=manifest, |
| 239 | ) |
| 240 | |
| 241 | |
| 242 | def read_backup_member(backup_path: Path | str, member_name: str) -> bytes | None: |
| 243 | """Return the bytes of one archive member, or None if it is not present. |
| 244 | |
| 245 | ``member_name`` is expected to be an internal archive relpath produced by |
| 246 | server code (e.g. "data/collections/notes/records.tsv"), not raw user |
| 247 | input — but it is still validated defensively against traversal. |
| 248 | """ |
| 249 | _safe_archive_path(member_name) |
| 250 | with tarfile.open(backup_path, "r:*") as archive: |
| 251 | try: |
| 252 | member = archive.getmember(member_name) |
| 253 | except KeyError: |
| 254 | return None |
| 255 | extracted = archive.extractfile(member) |
| 256 | if extracted is None: |
| 257 | return None |
| 258 | return extracted.read() |
| 259 | |
| 260 | |
| 261 | def _normalize_select(select: Sequence[str]) -> list[str]: |
| 262 | normalized: list[str] = [] |
| 263 | for raw in select: |
| 264 | cleaned = str(raw).strip("/") |
| 265 | if not (cleaned == "objects" or cleaned.startswith("objects/") |
| 266 | or cleaned == "data" or cleaned.startswith("data/")): |
| 267 | raise BackupRestoreError(f"invalid restore selector: {raw!r}") |
| 268 | normalized.append(cleaned) |
| 269 | return normalized |
| 270 | |
| 271 | |
| 272 | def _member_selected(name: str, selectors: list[str]) -> bool: |
| 273 | for selector in selectors: |
| 274 | if name == selector or name.startswith(selector + "/"): |
| 275 | return True |
| 276 | return False |
| 277 | |
| 278 | |
| 279 | def restore_runtime_backup( |
| 280 | backup_path: Path | str, |
| 281 | *, |
| 282 | objects_dir: Path | str, |
| 283 | data_dir: Path | str, |
| 284 | overwrite: bool = False, |
| 285 | prune_extra: bool = False, |
| 286 | select: Sequence[str] | None = None, |
| 287 | ) -> RestoreSummary: |
| 288 | """Restore a runtime backup into explicit object and data directories. |
| 289 | |
| 290 | ``select``, when provided, scopes the restore to archive members whose |
| 291 | name equals one of the selectors or is nested under one (e.g. |
| 292 | "data/collections/notes"). Combining ``select`` with ``prune_extra`` is |
| 293 | refused — pruning is a whole-instance operation. |
| 294 | """ |
| 295 | if prune_extra and not overwrite: |
| 296 | raise BackupRestoreError("prune_extra requires overwrite=True") |
| 297 | if select is not None and prune_extra: |
| 298 | raise BackupRestoreError("select cannot be combined with prune_extra") |
| 299 | |
| 300 | selectors = _normalize_select(select) if select is not None else None |
| 301 | |
| 302 | backup = Path(backup_path) |
| 303 | objects_path = Path(objects_dir) |
| 304 | data_path = Path(data_dir) |
| 305 | verification = verify_runtime_backup(backup) |
| 306 | if not verification.ok: |
| 307 | raise BackupRestoreError("; ".join(verification.errors)) |
| 308 | |
| 309 | selected_count = 0 |
| 310 | planned: list[tuple[tarfile.TarInfo, Path]] = [] |
| 311 | with tarfile.open(backup, "r:*") as archive: |
| 312 | for member in archive.getmembers(): |
| 313 | if member.name == MANIFEST_NAME: |
| 314 | continue |
| 315 | if selectors is not None: |
| 316 | if not _member_selected(member.name, selectors): |
| 317 | continue |
| 318 | selected_count += 1 |
| 319 | destination = _member_destination(member.name, objects_path, data_path) |
| 320 | planned.append((member, destination)) |
| 321 | if member.isdir(): |
| 322 | if destination.exists() and not destination.is_dir(): |
| 323 | raise BackupRestoreError(f"restore target is not a directory: {destination}") |
| 324 | continue |
| 325 | if destination.exists() and not overwrite: |
| 326 | raise BackupRestoreError(f"restore target already exists: {destination}") |
| 327 | |
| 328 | if selectors is not None and selected_count == 0: |
| 329 | raise BackupRestoreError( |
| 330 | f"no files in the backup match the selection: {', '.join(selectors)}" |
| 331 | ) |
| 332 | |
| 333 | pruned_files = 0 |
| 334 | pruned_dirs = 0 |
| 335 | if prune_extra: |
| 336 | keep_paths = {destination.resolve(strict=False) for _, destination in planned} |
| 337 | pruned_files, pruned_dirs = _prune_extra_runtime_paths( |
| 338 | objects_path, |
| 339 | data_path, |
| 340 | keep_paths, |
| 341 | ) |
| 342 | |
| 343 | restored_files = 0 |
| 344 | restored_bytes = 0 |
| 345 | for member, destination in planned: |
| 346 | if member.isdir(): |
| 347 | destination.mkdir(parents=True, exist_ok=True) |
| 348 | _chmod_from_member(destination, member) |
| 349 | continue |
| 350 | |
| 351 | extracted = archive.extractfile(member) |
| 352 | if extracted is None: |
| 353 | raise BackupRestoreError(f"cannot read archive member: {member.name}") |
| 354 | destination.parent.mkdir(parents=True, exist_ok=True) |
| 355 | _write_restored_file(destination, extracted.read(), member) |
| 356 | restored_files += 1 |
| 357 | restored_bytes += member.size |
| 358 | |
| 359 | return RestoreSummary( |
| 360 | backup_path=str(backup), |
| 361 | objects_dir=str(objects_path), |
| 362 | data_dir=str(data_path), |
| 363 | files=restored_files, |
| 364 | bytes=restored_bytes, |
| 365 | overwritten=overwrite, |
| 366 | pruned_files=pruned_files, |
| 367 | pruned_dirs=pruned_dirs, |
| 368 | scoped=selectors is not None, |
| 369 | selected=selected_count, |
| 370 | ) |
| 371 | |
| 372 | |
| 373 | def _objects_dir(value: Path | str | None) -> Path: |
| 374 | if value is not None: |
| 375 | return Path(value) |
| 376 | return Path(os.environ.get(OBJECTS_DIR_ENV, DEFAULT_OBJECTS_DIR)) |
| 377 | |
| 378 | |
| 379 | def _data_dir(value: Path | str | None) -> Path: |
| 380 | if value is not None: |
| 381 | return Path(value) |
| 382 | return Path(os.environ.get(DATA_DIR_ENV, DEFAULT_DATA_DIR)) |
| 383 | |
| 384 | |
| 385 | def _backups_dir(value: Path | str | None, *, data_dir: Path | str | None) -> Path: |
| 386 | if value is not None: |
| 387 | return Path(value) |
| 388 | env_value = os.environ.get(BACKUPS_DIR_ENV) |
| 389 | if env_value: |
| 390 | return Path(env_value) |
| 391 | return _data_dir(data_dir) / BACKUPS_DIR |
| 392 | |
| 393 | |
| 394 | def _restore_point_label(value: str) -> str: |
| 395 | label = str(value).strip().lower() |
| 396 | if not RESTORE_POINT_LABEL_RE.fullmatch(label): |
| 397 | raise BackupRestoreError(f"invalid restore point label: {value!r}") |
| 398 | return label |
| 399 | |
| 400 | |
| 401 | def _backup_filename_timestamp(timestamp: str) -> str: |
| 402 | compact = timestamp.replace("+00:00", "Z") |
| 403 | compact = compact.replace("-", "").replace(":", "").replace(".", "") |
| 404 | compact = compact.replace("+", "") |
| 405 | if not compact.endswith("Z"): |
| 406 | compact = f"{compact}Z" |
| 407 | return compact |
| 408 | |
| 409 | |
| 410 | def _runtime_sources(objects_dir: Path, data_dir: Path) -> list[tuple[Path, PurePosixPath]]: |
| 411 | sources = [(objects_dir, PurePosixPath("objects"))] |
| 412 | for name in RUNTIME_DATA_DIRS: |
| 413 | sources.append((data_dir / name, PurePosixPath("data") / name)) |
| 414 | return sources |
| 415 | |
| 416 | |
| 417 | def _restore_roots(objects_dir: Path, data_dir: Path) -> list[Path]: |
| 418 | return [objects_dir, *(data_dir / name for name in RUNTIME_DATA_DIRS)] |
| 419 | |
| 420 | |
| 421 | def _prune_extra_runtime_paths( |
| 422 | objects_dir: Path, |
| 423 | data_dir: Path, |
| 424 | keep_paths: set[Path], |
| 425 | ) -> tuple[int, int]: |
| 426 | pruned_files = 0 |
| 427 | pruned_dirs = 0 |
| 428 | for root in _restore_roots(objects_dir, data_dir): |
| 429 | if not root.exists() or not root.is_dir(): |
| 430 | continue |
| 431 | paths = sorted(root.rglob("*"), key=lambda path: len(path.parts), reverse=True) |
| 432 | for path in paths: |
| 433 | if path.resolve(strict=False) in keep_paths: |
| 434 | continue |
| 435 | if path.is_symlink() or path.is_file(): |
| 436 | path.unlink() |
| 437 | pruned_files += 1 |
| 438 | continue |
| 439 | if path.is_dir(): |
| 440 | try: |
| 441 | path.rmdir() |
| 442 | except OSError: |
| 443 | continue |
| 444 | pruned_dirs += 1 |
| 445 | return pruned_files, pruned_dirs |
| 446 | |
| 447 | |
| 448 | def _iter_backup_members( |
| 449 | source_root: Path, |
| 450 | archive_root: PurePosixPath, |
| 451 | ) -> list[tuple[Path, PurePosixPath]]: |
| 452 | members: list[tuple[Path, PurePosixPath]] = [(source_root, archive_root)] |
| 453 | children = sorted(source_root.rglob("*"), key=lambda path: path.relative_to(source_root).as_posix()) |
| 454 | for path in children: |
| 455 | if _should_skip(path, source_root): |
| 456 | continue |
| 457 | relative = path.relative_to(source_root).as_posix() |
| 458 | members.append((path, archive_root / relative)) |
| 459 | return members |
| 460 | |
| 461 | |
| 462 | def _should_skip(path: Path, source_root: Path) -> bool: |
| 463 | relative = path.relative_to(source_root) |
| 464 | parts = relative.parts |
| 465 | if any(part in SKIP_PARTS for part in parts): |
| 466 | return True |
| 467 | if any(part.startswith(".") for part in parts): |
| 468 | return True |
| 469 | if path.suffix in SKIP_SUFFIXES: |
| 470 | return True |
| 471 | return not (path.is_dir() or path.is_file()) |
| 472 | |
| 473 | |
| 474 | def _add_manifest(archive: tarfile.TarFile, manifest: dict[str, Any]) -> None: |
| 475 | payload = json.dumps(manifest, indent=2, sort_keys=True).encode("utf-8") |
| 476 | info = tarfile.TarInfo(MANIFEST_NAME) |
| 477 | info.size = len(payload) |
| 478 | info.mode = 0o644 |
| 479 | info.mtime = int(datetime.now(timezone.utc).timestamp()) |
| 480 | _normalize_tarinfo(info) |
| 481 | archive.addfile(info, io.BytesIO(payload)) |
| 482 | |
| 483 | |
| 484 | def _add_path(archive: tarfile.TarFile, path: Path, archive_name: PurePosixPath) -> None: |
| 485 | info = archive.gettarinfo(str(path), arcname=archive_name.as_posix()) |
| 486 | _normalize_tarinfo(info) |
| 487 | if path.is_dir(): |
| 488 | archive.addfile(info) |
| 489 | return |
| 490 | with path.open("rb") as file_obj: |
| 491 | archive.addfile(info, file_obj) |
| 492 | |
| 493 | |
| 494 | def _normalize_tarinfo(info: tarfile.TarInfo) -> None: |
| 495 | info.uid = 0 |
| 496 | info.gid = 0 |
| 497 | info.uname = "" |
| 498 | info.gname = "" |
| 499 | info.pax_headers = {} |
| 500 | |
| 501 | |
| 502 | def _read_manifest(archive: tarfile.TarFile, errors: list[str]) -> dict[str, Any] | None: |
| 503 | try: |
| 504 | member = archive.getmember(MANIFEST_NAME) |
| 505 | except KeyError: |
| 506 | errors.append("backup manifest is missing") |
| 507 | return None |
| 508 | |
| 509 | manifest_file = archive.extractfile(member) |
| 510 | if manifest_file is None: |
| 511 | errors.append("backup manifest cannot be read") |
| 512 | return None |
| 513 | |
| 514 | try: |
| 515 | payload = json.loads(manifest_file.read().decode("utf-8")) |
| 516 | except (UnicodeDecodeError, json.JSONDecodeError) as exc: |
| 517 | errors.append(f"backup manifest is invalid JSON: {exc}") |
| 518 | return None |
| 519 | |
| 520 | if not isinstance(payload, dict): |
| 521 | errors.append("backup manifest must be a JSON object") |
| 522 | return None |
| 523 | return payload |
| 524 | |
| 525 | |
| 526 | def _validate_member(member: tarfile.TarInfo) -> list[str]: |
| 527 | errors: list[str] = [] |
| 528 | try: |
| 529 | path = _safe_archive_path(member.name) |
| 530 | except BackupRestoreError as exc: |
| 531 | return [str(exc)] |
| 532 | |
| 533 | if member.issym() or member.islnk(): |
| 534 | errors.append(f"archive member uses links: {member.name}") |
| 535 | elif not (member.isfile() or member.isdir()): |
| 536 | errors.append(f"archive member has unsupported type: {member.name}") |
| 537 | |
| 538 | parts = path.parts |
| 539 | if not parts: |
| 540 | errors.append("archive member has empty name") |
| 541 | elif parts[0] == "objects": |
| 542 | pass |
| 543 | elif parts[0] == "data": |
| 544 | if len(parts) == 1: |
| 545 | pass |
| 546 | elif parts[1] not in RUNTIME_DATA_DIRS: |
| 547 | errors.append(f"archive member uses unsupported data directory: {member.name}") |
| 548 | else: |
| 549 | errors.append(f"archive member is outside runtime backup roots: {member.name}") |
| 550 | |
| 551 | return errors |
| 552 | |
| 553 | |
| 554 | def _safe_archive_path(name: str) -> PurePosixPath: |
| 555 | path = PurePosixPath(name) |
| 556 | if not name or path.is_absolute(): |
| 557 | raise BackupRestoreError(f"unsafe archive member path: {name!r}") |
| 558 | if any(part in {"", ".", ".."} for part in path.parts): |
| 559 | raise BackupRestoreError(f"unsafe archive member path: {name!r}") |
| 560 | return path |
| 561 | |
| 562 | |
| 563 | def _member_entry(name: str) -> str | None: |
| 564 | try: |
| 565 | path = _safe_archive_path(name) |
| 566 | except BackupRestoreError: |
| 567 | return None |
| 568 | if path.parts[0] == "objects": |
| 569 | return "objects" |
| 570 | if path.parts[0] == "data" and len(path.parts) > 1: |
| 571 | return f"data/{path.parts[1]}" |
| 572 | return None |
| 573 | |
| 574 | |
| 575 | def _member_destination(name: str, objects_dir: Path, data_dir: Path) -> Path: |
| 576 | path = _safe_archive_path(name) |
| 577 | parts = path.parts |
| 578 | if parts[0] == "objects": |
| 579 | destination = objects_dir.joinpath(*parts[1:]) |
| 580 | _ensure_under(destination, objects_dir) |
| 581 | return destination |
| 582 | |
| 583 | if parts[0] == "data": |
| 584 | if len(parts) == 1: |
| 585 | destination = data_dir |
| 586 | elif parts[1] in RUNTIME_DATA_DIRS: |
| 587 | destination = data_dir.joinpath(*parts[1:]) |
| 588 | else: |
| 589 | raise BackupRestoreError(f"unsupported data directory in backup: {name}") |
| 590 | _ensure_under(destination, data_dir) |
| 591 | return destination |
| 592 | |
| 593 | raise BackupRestoreError(f"unsupported backup root: {name}") |
| 594 | |
| 595 | |
| 596 | def _ensure_under(path: Path, root: Path) -> None: |
| 597 | try: |
| 598 | path.resolve(strict=False).relative_to(root.resolve(strict=False)) |
| 599 | except ValueError as exc: |
| 600 | raise BackupRestoreError(f"restore target escapes runtime root: {path}") from exc |
| 601 | |
| 602 | |
| 603 | def _write_restored_file(destination: Path, payload: bytes, member: tarfile.TarInfo) -> None: |
| 604 | temp_path = destination.with_name(f".{destination.name}.restore.tmp") |
| 605 | with temp_path.open("wb") as file_obj: |
| 606 | file_obj.write(payload) |
| 607 | temp_path.replace(destination) |
| 608 | _chmod_from_member(destination, member) |
| 609 | |
| 610 | |
| 611 | def _chmod_from_member(path: Path, member: tarfile.TarInfo) -> None: |
| 612 | mode = member.mode & 0o777 |
| 613 | if mode: |
| 614 | path.chmod(mode) |
| 615 | |
| 616 | |
| 617 | def _manifest_int(value: Any) -> int | None: |
| 618 | if isinstance(value, int): |
| 619 | return value |
| 620 | try: |
| 621 | return int(value) |
| 622 | except (TypeError, ValueError): |
| 623 | return None |
| 624 | |
| 625 | |
| 626 | def _utc_timestamp() -> str: |
| 627 | return datetime.now(timezone.utc).isoformat().replace("+00:00", "Z") |
| 628 | |
| 629 | |
| 630 | def main(argv: list[str] | None = None) -> int: |
| 631 | parser = argparse.ArgumentParser(description="Create, verify, and restore DBBASIC runtime backups.") |
| 632 | subcommands = parser.add_subparsers(dest="command", required=True) |
| 633 | |
| 634 | create = subcommands.add_parser("create", help="create a runtime backup") |
| 635 | create.add_argument("output", type=Path) |
| 636 | create.add_argument("--objects-dir", type=Path) |
| 637 | create.add_argument("--data-dir", type=Path) |
| 638 | create.add_argument("--json", action="store_true") |
| 639 | |
| 640 | verify = subcommands.add_parser("verify", help="verify a runtime backup") |
| 641 | verify.add_argument("backup", type=Path) |
| 642 | verify.add_argument("--json", action="store_true") |
| 643 | |
| 644 | restore = subcommands.add_parser("restore", help="restore a runtime backup") |
| 645 | restore.add_argument("backup", type=Path) |
| 646 | restore.add_argument("--objects-dir", type=Path, required=True) |
| 647 | restore.add_argument("--data-dir", type=Path, required=True) |
| 648 | restore.add_argument("--overwrite", action="store_true") |
| 649 | restore.add_argument("--prune-extra", action="store_true") |
| 650 | restore.add_argument("--collection", action="append", default=[]) |
| 651 | restore.add_argument("--only", action="append", default=[]) |
| 652 | restore.add_argument("--preview", action="store_true") |
| 653 | restore.add_argument("--json", action="store_true") |
| 654 | |
| 655 | args = parser.parse_args(argv) |
| 656 | |
| 657 | try: |
| 658 | if args.command == "create": |
| 659 | result = create_runtime_backup( |
| 660 | args.output, |
| 661 | objects_dir=args.objects_dir, |
| 662 | data_dir=args.data_dir, |
| 663 | ) |
| 664 | _print_result(result.to_dict(), json_output=args.json) |
| 665 | return 0 |
| 666 | if args.command == "verify": |
| 667 | result = verify_runtime_backup(args.backup) |
| 668 | _print_result(result.to_dict(), json_output=args.json) |
| 669 | return 0 if result.ok else 1 |
| 670 | if args.command == "restore": |
| 671 | select = [f"data/collections/{name}" for name in args.collection] + list(args.only) |
| 672 | if args.preview: |
| 673 | if len(args.collection) != 1 or args.only: |
| 674 | raise BackupRestoreError( |
| 675 | "--preview requires exactly one --collection and no --only paths" |
| 676 | ) |
| 677 | import object_backup_index |
| 678 | import object_collections |
| 679 | |
| 680 | collection = args.collection[0] |
| 681 | if not object_collections.validate_collection_name(collection): |
| 682 | raise BackupRestoreError(f"invalid collection name: {collection!r}") |
| 683 | member_name = f"data/collections/{collection}/records.tsv" |
| 684 | archived_raw = read_backup_member(args.backup, member_name) |
| 685 | live_raw = object_backup_index._live_records_tsv(collection, data_dir=args.data_dir) |
| 686 | backup_rows = object_backup_index._parse_tsv_by_id(archived_raw) |
| 687 | live_rows = object_backup_index._parse_tsv_by_id(live_raw) |
| 688 | diff = object_backup_index._diff_records(backup_rows, live_rows) |
| 689 | result = { |
| 690 | "target": {"kind": "collection", "name": collection}, |
| 691 | "backup_id": str(args.backup), |
| 692 | "present_in_backup": archived_raw is not None, |
| 693 | **diff, |
| 694 | } |
| 695 | _print_result(result, json_output=args.json) |
| 696 | return 0 |
| 697 | result = restore_runtime_backup( |
| 698 | args.backup, |
| 699 | objects_dir=args.objects_dir, |
| 700 | data_dir=args.data_dir, |
| 701 | overwrite=args.overwrite, |
| 702 | prune_extra=args.prune_extra, |
| 703 | select=select or None, |
| 704 | ) |
| 705 | _print_result(result.to_dict(), json_output=args.json) |
| 706 | return 0 |
| 707 | except BackupError as exc: |
| 708 | if getattr(args, "json", False): |
| 709 | print(json.dumps({"ok": False, "error": str(exc)}, indent=2)) |
| 710 | else: |
| 711 | print(f"ERROR: {exc}") |
| 712 | return 1 |
| 713 | |
| 714 | return 1 |
| 715 | |
| 716 | |
| 717 | def _print_result(result: dict[str, Any], *, json_output: bool) -> None: |
| 718 | if json_output: |
| 719 | print(json.dumps(result, indent=2)) |
| 720 | return |
| 721 | |
| 722 | for key, value in result.items(): |
| 723 | print(f"{key}: {value}") |
| 724 | |
| 725 | |
| 726 | if __name__ == "__main__": |
| 727 | raise SystemExit(main()) |