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 generic IndexHeader shell, present only at the very start of a session’s subID=0 file.

  • RecordHead (32 bytes) — one per backup version, at comp_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 reuse parse_index_header for it.

record_total_length predicts the exact file offset of the next record.

class synology_apm_repo.sdk.format.composition.CompositionHeader(major, minor)

Bases: object

Parsed composition sub-file header.

major: int
minor: int
synology_apm_repo.sdk.format.composition.parse_composition_header(data)

Parse the 64-byte header at the start of a session’s subID=0 file (FORMAT-SPEC.md: Composition file splitting).

Raises:
class synology_apm_repo.sdk.format.composition.CompositionStatus(*values)

Bases: Enum

A record’s status (FORMAT-SPEC.md: RecordHead). The restore path never branches on it: a record reached via file_map is COMPLETE in practice, but INTERRUPTED is 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: object

Parsed 32-byte RecordHead (FORMAT-SPEC.md: RecordHead).

status: CompositionStatus
map_num: int
map_crc: int
mode: int
attr_leng: int
attr_crc: int
property has_redundancy: bool
synology_apm_repo.sdk.format.composition.parse_record_head(data)

Decode the 32-byte RecordHead at the start of data. The pre-Redundancy record layout is refused outright.

Raises:
synology_apm_repo.sdk.format.composition.verify_chunk_map_crc(map_array_bytes, expected_crc)

Validate a full ChunkMapRecord array’s bytes against a RecordHead.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; verify and diagnostics call 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). Only verify calls 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’s headOff.

synology_apm_repo.sdk.format.composition.chunk_map_array_offset(head_off)

Session-global offset where a record’s ChunkMapRecord array begins, right after its RecordHead (FORMAT-SPEC.md: RecordHead).