Coverage for src/copytrading_engine/backup/manifest.py: 91%
80 statements
« prev ^ index » next coverage.py v7.16.2, created at 2026-11-16 16:55 +0000
« prev ^ index » next coverage.py v7.16.2, created at 2026-11-16 16:55 +0000
1"""The backup archive format: its manifest, members, limits, and the previews built from them."""
3from __future__ import annotations
5import hashlib
6import json
7import re
8from dataclasses import dataclass
9from datetime import datetime
10from typing import Any
12from copytrading_engine.backup.ports import AccountSnapshotSchemaProvider
13from copytrading_engine.backup.schema_catalog import APPLICATION_DATABASE_VERSION
15ARCHIVE_FORMAT = "copytrading-backup"
18FORMAT_VERSION = 1
21MANIFEST_NAME = "manifest.json"
24MAX_MEMBER_BYTES = 2 * 1024 * 1024 * 1024
27CANDIDATE_MANIFEST_NAME = ".restore-candidate-manifest.json"
30DIGEST = re.compile(r"^[0-9a-f]{64}$")
33ACCOUNT_DATABASE = re.compile(r"^accounts/([A-Za-z0-9_-]{1,64})/execution\.sqlite3$")
36RESTORE_STAGE = re.compile(r"^restore-[0-9a-f]{32}$")
39APPLICATION_SCHEMA_PREFIX = f"sqlite:application:{APPLICATION_DATABASE_VERSION};components="
42def is_sqlite_member(member_path: str) -> bool:
43 return member_path == "application.db" or ACCOUNT_DATABASE.fullmatch(member_path) is not None
46class BackupManifestError(ValueError):
47 """A backup is incomplete, corrupt, unsafe, or incompatible."""
50def account_schema_version(snapshot_schema: AccountSnapshotSchemaProvider) -> str:
51 execution_revision = snapshot_schema.execution_schema_revision
52 snapshot_version = snapshot_schema.snapshot_json_schema_version
53 if ( 53 ↛ 59line 53 didn't jump to line 59 because the condition on line 53 was never true
54 type(execution_revision) is not int
55 or execution_revision <= 0
56 or type(snapshot_version) is not int
57 or snapshot_version <= 0
58 ):
59 raise BackupManifestError("account database schema version is invalid")
60 return f"sqlite:execution:{execution_revision};ledger_snapshot_json:{snapshot_version}"
63@dataclass(frozen=True, slots=True)
64class BackupMember:
65 path: str
66 size: int
67 sha256: str
68 schema_version: str
71@dataclass(frozen=True, slots=True)
72class BackupManifest:
73 format_version: int
74 created_at: datetime
75 installation_id: str
76 environment_ids: tuple[str, ...]
77 members: tuple[BackupMember, ...]
80@dataclass(frozen=True, slots=True)
81class RestorePreview:
82 manifest: BackupManifest
83 matches_installation: bool
84 account_ids: tuple[str, ...]
85 credential_references: tuple[str, ...]
88@dataclass(frozen=True, slots=True)
89class PendingRestoreCandidate:
90 candidate_id: str
91 previous_generation: str
92 active_generation: str
93 installation_id: str
94 environment_ids: tuple[str, ...]
95 account_ids: tuple[str, ...]
96 credential_references: tuple[str, ...]
97 candidate_valid: bool
100def manifest_dict(manifest: BackupManifest) -> dict[str, Any]:
101 return {
102 "format": ARCHIVE_FORMAT,
103 "format_version": manifest.format_version,
104 "created_at": manifest.created_at.isoformat(),
105 "installation_id": manifest.installation_id,
106 "environment_ids": list(manifest.environment_ids),
107 "members": [
108 {
109 "path": member.path,
110 "size": member.size,
111 "sha256": member.sha256,
112 "schema_version": member.schema_version,
113 }
114 for member in manifest.members
115 ],
116 }
119def backup_manifest_payload(manifest: BackupManifest) -> dict[str, Any]:
120 """Return the public IPC view of a completed archive manifest."""
121 return manifest_dict(manifest)
124def restore_preview_payload(preview: RestorePreview, staging_id: str) -> dict[str, Any]:
125 return {
126 "format_version": preview.manifest.format_version,
127 "created_at": preview.manifest.created_at.isoformat(),
128 "installation_id": preview.manifest.installation_id,
129 "matches_installation": preview.matches_installation,
130 "environment_ids": list(preview.manifest.environment_ids),
131 "account_ids": list(preview.account_ids),
132 "credential_references": list(preview.credential_references),
133 "staging_id": staging_id,
134 "members": [
135 {
136 "path": member.path,
137 "size": member.size,
138 "sha256": member.sha256,
139 "schema_version": member.schema_version,
140 }
141 for member in preview.manifest.members
142 ],
143 }
146def json_object(content: bytes) -> dict[str, Any]:
147 def unique_object(pairs: list[tuple[str, Any]]) -> dict[str, Any]:
148 result: dict[str, Any] = {}
149 for key, value in pairs:
150 if key in result: 150 ↛ 151line 150 didn't jump to line 151 because the condition on line 150 was never true
151 raise BackupManifestError("JSON contains a duplicate field")
152 result[key] = value
153 return result
155 try:
156 raw = json.loads(content, object_pairs_hook=unique_object)
157 except (UnicodeDecodeError, json.JSONDecodeError) as exc:
158 raise BackupManifestError("operational JSON is invalid") from exc
159 if not isinstance(raw, dict): 159 ↛ 160line 159 didn't jump to line 160 because the condition on line 159 was never true
160 raise BackupManifestError("operational JSON must be an object")
161 return raw
164def manifest_digest(manifest: BackupManifest) -> str:
165 payload = json.dumps(manifest_dict(manifest), sort_keys=True, separators=(",", ":"))
166 return hashlib.sha256(payload.encode("utf-8")).hexdigest()