synology_apm_repo.sdk.format.headers module¶
The generic 64-byte IndexHeader shell shared by every binary format in
this project (FORMAT-SPEC.md: 64-byte header shell):
offset size field
0 4 magic (ASCII)
4 2 major (BE u16)
6 2 minor (BE u16)
8 52 format-specific payload
60 4 header CRC32 (BE u32) = crc32(0, buf, 60)
Validation order (identical for every format, FORMAT-SPEC.md: 64-byte header shell): magic, then header CRC, then major-only version acceptance. Any minor is accepted.
This module owns only the shell (magic / CRC / version); each format module
(bucket.py, composition.py, …) decodes its own payload fields and
calls parse_index_header for the shell checks.
- class synology_apm_repo.sdk.format.headers.IndexHeader(magic, major, minor, raw)¶
Bases:
objectThe validated generic shell of a 64-byte header.
rawis the full 64 bytes, for format modules to slice their payload fields from.
- synology_apm_repo.sdk.format.headers.parse_index_header(data, *, expect_magic, max_major=None, spec=None)¶
Validate and parse the generic 64-byte header shell at the start of
data(which may be longer; only the first 64 bytes are read).- Parameters:
- Returns:
The validated shell.
- Raises:
FormatError –
datais shorter than 64 bytes.DataCorruptError – A magic or header-CRC mismatch.
UnsupportedVersionError –
max_majoris given andmajorexceeds it.
- Return type:
- synology_apm_repo.sdk.format.headers.parse_json_payload_header(data, *, expect_magic, spec=None, payload_kind='payload')¶
Shared shell for a format whose 64-byte header (validated via
parse_index_header) is followed by a CRC32’d JSON payload:json_crc(BE u32) at offset 8,data_size(BE u64) at offset 12, payload at[HEADER_LEN, HEADER_LEN + data_size). Used byrepo_infoandrepo_transaction.- Parameters:
- Returns:
(header, decoded JSON payload).- Raises:
FormatError – The payload is shorter than
data_sizedeclares.DataCorruptError – A payload CRC mismatch (in addition to
parse_index_header’s own magic/header-CRC checks), or a payload that is not a JSON object.
- Return type:
tuple[IndexHeader, dict[str, Any]]
- synology_apm_repo.sdk.format.headers.compute_crc32(data)¶
zlib.crc32(data) & 0xFFFFFFFF, the unsigned 32-bit form every CRC32 check compares against (shared byverify_crc32andformat.redundancy.attempt_repair).
- synology_apm_repo.sdk.format.headers.verify_crc32(data, expected, *, label, spec=None)¶
Raise
DataCorruptErrorunlesscompute_crc32(data)matchesexpected; the verify-or-raise shape shared by every binary format.- Parameters:
- Raises:
DataCorruptError – The computed CRC32 doesn’t match
expected.