synology_apm_repo.sdk.format.redundancy module

Redundancy blob sizing and self-repair (FORMAT-SPEC.md: ChunkCrcStore & Redundancy).

Every Composition record and .buk bucket carries a trailing Redundancy blob: a 2*coverage-byte ring-buffer XOR parity (even-indexed windows into parity[0:coverage], odd-indexed into parity[coverage:2*coverage]) plus a rolling CRC32 checkpoint after each window (StepCrc). Because the checkpoint is rolling, not independent per window, this mechanism can locate and repair at most one corrupted region, bounded to two consecutive coverage-windows — a “single-disk-failure RAID” limit, not N-way parity.

redundancy_size computes the blob’s on-disk length (see expected_bucket_size, composition.py’s record_total_length). parse_redundancy_blob/attempt_repair do the repair (dedup.redundancy_repair fetches the trailer and runs it).

synology_apm_repo.sdk.format.redundancy.redundancy_size(data_size, coverage)

Total byte length of a Redundancy blob covering data_size bytes of underlying data, checkpointed every coverage bytes:

16 (header) + 4 * ceil(data_size / coverage) (StepCrc array) + min(data_size, 2 * coverage) (parity) (FORMAT-SPEC.md: ChunkCrcStore & Redundancy).

coverage is 256 for bucket trailers (REDUNDANCY_COVERAGE_BUCKET), 8192 for composition record trailers (REDUNDANCY_COVERAGE_COMPOSITION).

class synology_apm_repo.sdk.format.redundancy.RedundancyBlob(coverage, data_size, step_crc, parity)

Bases: object

One parsed Redundancy trailer: the rolling per-window CRC32 checkpoints (step_crc, one per coverage-byte window of the protected data, the last possibly shorter) plus the XOR parity ring buffer (parity, at most 2*coverage bytes) that attempt_repair reconstructs from.

coverage: int
data_size: int
step_crc: tuple[int, ...]
parity: bytes
synology_apm_repo.sdk.format.redundancy.parse_redundancy_blob(data, *, data_size, coverage)

Parse a Redundancy trailer of redundancy_size(data_size, coverage) bytes (FORMAT-SPEC.md: ChunkCrcStore & Redundancy). The header’s coverage and data size are checked against the caller’s values (known independently from the record or bucket header), not trusted.

Raises:

FormatError – data is too short, or its magic, version, coverage or data_size doesn’t match; the blob is unusable for repair.

synology_apm_repo.sdk.format.redundancy.attempt_repair(data, redundancy_raw, *, coverage, expected_crc)

Best-effort, in-memory self-repair of data (known not to match expected_crc) using its trailing Redundancy blob (FORMAT-SPEC.md: ChunkCrcStore & Redundancy).

Reconstructs windows [bad_idx, bad_idx+1] around the first divergent rolling checkpoint (the checkpoint alone can’t tell whether bad_idx+1 is also corrupt), then checks the whole candidate against expected_crc; a non-None result is confirmed correct.

Returns:

The repaired data (same length), or None if the blob doesn’t parse, the scan can’t localize the damage, or the candidate still fails the CRC. Never raises.

Return type:

bytes | None