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: object

The validated generic shell of a 64-byte header. raw is the full 64 bytes, for format modules to slice their payload fields from.

magic: bytes
major: int
minor: int
raw: bytes
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:
  • data (bytes | bytearray) – Bytes starting at the header.

  • expect_magic (bytes) – The format’s magic (see MAGIC).

  • max_major (int | None) – Highest accepted major version; None accepts any.

  • spec (str | None) – FORMAT-SPEC.md: ... citation attached to errors.

Returns:

The validated shell.

Raises:
Return type:

IndexHeader

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 by repo_info and repo_transaction.

Parameters:
  • data (bytes) – Bytes starting at the header.

  • expect_magic (bytes) – The format’s magic.

  • spec (str | None) – FORMAT-SPEC.md: ... citation attached to errors.

  • payload_kind (str) – Names the payload in error messages.

Returns:

(header, decoded JSON payload).

Raises:
  • FormatError – The payload is shorter than data_size declares.

  • 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 by verify_crc32 and format.redundancy.attempt_repair).

synology_apm_repo.sdk.format.headers.verify_crc32(data, expected, *, label, spec=None)

Raise DataCorruptError unless compute_crc32(data) matches expected; the verify-or-raise shape shared by every binary format.

Parameters:
  • data (bytes | bytearray | memoryview) – The checked bytes.

  • expected (int) – The stored CRC32.

  • spec (str | None) – FORMAT-SPEC.md: ... citation attached to the error.

  • label (str) – Names the checked region in the error message (e.g. "header", "payload", "RecordHead").

Raises:

DataCorruptError – The computed CRC32 doesn’t match expected.