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

1"""The backup archive format: its manifest, members, limits, and the previews built from them.""" 

2 

3from __future__ import annotations 

4 

5import hashlib 

6import json 

7import re 

8from dataclasses import dataclass 

9from datetime import datetime 

10from typing import Any 

11 

12from copytrading_engine.backup.ports import AccountSnapshotSchemaProvider 

13from copytrading_engine.backup.schema_catalog import APPLICATION_DATABASE_VERSION 

14 

15ARCHIVE_FORMAT = "copytrading-backup" 

16 

17 

18FORMAT_VERSION = 1 

19 

20 

21MANIFEST_NAME = "manifest.json" 

22 

23 

24MAX_MEMBER_BYTES = 2 * 1024 * 1024 * 1024 

25 

26 

27CANDIDATE_MANIFEST_NAME = ".restore-candidate-manifest.json" 

28 

29 

30DIGEST = re.compile(r"^[0-9a-f]{64}$") 

31 

32 

33ACCOUNT_DATABASE = re.compile(r"^accounts/([A-Za-z0-9_-]{1,64})/execution\.sqlite3$") 

34 

35 

36RESTORE_STAGE = re.compile(r"^restore-[0-9a-f]{32}$") 

37 

38 

39APPLICATION_SCHEMA_PREFIX = f"sqlite:application:{APPLICATION_DATABASE_VERSION};components=" 

40 

41 

42def is_sqlite_member(member_path: str) -> bool: 

43 return member_path == "application.db" or ACCOUNT_DATABASE.fullmatch(member_path) is not None 

44 

45 

46class BackupManifestError(ValueError): 

47 """A backup is incomplete, corrupt, unsafe, or incompatible.""" 

48 

49 

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}" 

61 

62 

63@dataclass(frozen=True, slots=True) 

64class BackupMember: 

65 path: str 

66 size: int 

67 sha256: str 

68 schema_version: str 

69 

70 

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, ...] 

78 

79 

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, ...] 

86 

87 

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 

98 

99 

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 } 

117 

118 

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) 

122 

123 

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 } 

144 

145 

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 

154 

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 

162 

163 

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()