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_sizebytes of underlying data, checkpointed everycoveragebytes:16 (header) + 4 * ceil(data_size / coverage) (StepCrc array) + min(data_size, 2 * coverage) (parity)(FORMAT-SPEC.md: ChunkCrcStore & Redundancy).coverageis 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:
objectOne parsed Redundancy trailer: the rolling per-window CRC32 checkpoints (
step_crc, one percoverage-byte window of the protected data, the last possibly shorter) plus the XOR parity ring buffer (parity, at most2*coveragebytes) thatattempt_repairreconstructs from.
- 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 –
datais 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 matchexpected_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 whetherbad_idx+1is also corrupt), then checks the whole candidate againstexpected_crc; a non-Noneresult is confirmed correct.- Returns:
The repaired
data(same length), orNoneif 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