synology_apm_repo.sdk.format.composition module¶
Composition file format (FORMAT-SPEC.md: Composition file splitting; RecordHead).
Two independent binary structures live in a composition sub-file:
CompositionHeader(64 bytes) — the genericIndexHeadershell, present only at the very start of a session’ssubID=0file.RecordHead(32 bytes) — one per backup version, atcomp_offset(db/file_map.comp_offset) within the session’s global offset space. This is a bespoke structure: 2-byte magic (not 4), and its own CRC covering[0,28)stored at offset 28 (not the generic shell’s[0,60)/60) — do not reuseparse_index_headerfor it.
record_total_length predicts the exact file offset of the next
record.
- class synology_apm_repo.sdk.format.composition.CompositionHeader(major, minor)¶
Bases:
objectParsed composition sub-file header.
- synology_apm_repo.sdk.format.composition.parse_composition_header(data)¶
Parse the 64-byte header at the start of a session’s
subID=0file (FORMAT-SPEC.md: Composition file splitting).- Raises:
FormatError –
datais shorter than 64 bytes.DataCorruptError – A magic or header-CRC mismatch, or
subFileSizeis not the fixed 16 MiB every sub-file uses.UnsupportedVersionError –
majoris not exactly 1 (the only value ever written).
- class synology_apm_repo.sdk.format.composition.CompositionStatus(*values)¶
Bases:
EnumA record’s status (FORMAT-SPEC.md: RecordHead). The restore path never branches on it: a record reached via
file_mapisCOMPLETEin practice, butINTERRUPTEDis decoded rather than rejected.- COMPLETE = 0¶
- INTERRUPTED = 1¶
- class synology_apm_repo.sdk.format.composition.RecordHead(status, map_num, map_crc, mode, attr_leng, attr_crc)¶
Bases:
objectParsed 32-byte
RecordHead(FORMAT-SPEC.md: RecordHead).- status: CompositionStatus¶
- synology_apm_repo.sdk.format.composition.parse_record_head(data)¶
Decode the 32-byte
RecordHeadat the start ofdata. The pre-Redundancy record layout is refused outright.- Raises:
FormatError –
datais shorter than 32 bytes.DataCorruptError – A magic or head-CRC mismatch, or an unknown status.
UnsupportedVersionError – The
Redundancymode bit is absent.
- synology_apm_repo.sdk.format.composition.verify_chunk_map_crc(map_array_bytes, expected_crc)¶
Validate a full
ChunkMapRecordarray’s bytes against aRecordHead.map_crc(FORMAT-SPEC.md: RecordHead).Not called by
parse_record_head, which would force every read to load the whole (possibly multi-hundred-MB) array;verifyanddiagnosticscall it explicitly.- Raises:
DataCorruptError – The CRC32 does not match.
- synology_apm_repo.sdk.format.composition.verify_attr_crc(attr_bytes, expected_crc)¶
Validate a record’s JSON attribute blob against
RecordHead.attr_crc(FORMAT-SPEC.md: RecordHead). Onlyverifycalls it.- Raises:
DataCorruptError – The CRC32 does not match.
- synology_apm_repo.sdk.format.composition.record_total_length(map_num, attr_leng)¶
Total byte length of one composition record starting at its
headOff:RECORD_HEAD_LENGTH + map_num*20 + attr_leng + redundancy_size(map_num*20, 8192)(FORMAT-SPEC.md: RecordHead; ChunkCrcStore & Redundancy).Records are packed back-to-back with no padding, so
headOff + record_total_length(...)is exactly the next record’sheadOff.
- synology_apm_repo.sdk.format.composition.chunk_map_array_offset(head_off)¶
Session-global offset where a record’s
ChunkMapRecordarray begins, right after itsRecordHead(FORMAT-SPEC.md: RecordHead).