synology_apm_repo.sdk.format.compression module¶
Chunk decompression dispatch (FORMAT-SPEC.md: SizeStore).
Decrypt before decompress: ciphertext length equals compressed length.
This module only decompresses; crypto only decrypts; callers sequence
the two.
- synology_apm_repo.sdk.format.compression.ZSTD_FRAME_MAGIC = b'(\xb5/\xfd'¶
Standard ZSTD frame magic, the first 4 bytes of every ZSTD frame (LZ4 blocks carry none).
- class synology_apm_repo.sdk.format.compression.CompressType(*values)¶
Bases:
EnumPer-chunk compression type, as recorded in
SizeStore(FORMAT-SPEC.md: SizeStore). Values match the on-disk encoding; 3 is skipped.- NONE = 0¶
- LZ4 = 1¶
- ZSTD = 2¶
- COMPACTED = 4¶
- synology_apm_repo.sdk.format.compression.decompress(ctype, data)¶
Decompress one chunk’s decrypted stored bytes back to exactly
FIXED_CHUNK_LENGTH(4096) bytes of plaintext.Single-chunk path; see
decompress_manyfor the batched form.datamay be amemoryview(copied only forNONE).- Raises:
ChunkCompactedError – For
CompressType.COMPACTED(unrecoverable, reclaimed by compaction).DataCorruptError – The chunk doesn’t decompress, or not to exactly 4096 bytes.
- synology_apm_repo.sdk.format.compression.decompress_many(items)¶
Batch form of
decompress: decompresses(compress_type, data)pairs, preserving order.datamay be amemoryview.A ZSTD entry’s result is a ``memoryview`` into a decode buffer it shares with the other ZSTD entries of its batch, not a copy (copying every frame is the most expensive decode step). Keeping one alive keeps that whole buffer alive; copy with
bytes()to keep one chunk alone.NONEentries return the input as given.- Raises:
ChunkCompactedError – An entry is
COMPACTED.DataCorruptError – A chunk fails to decompress to 4096 bytes.
- synology_apm_repo.sdk.format.compression.is_zstd_frame(head)¶
Whether
headopens with a standard ZSTD frame’s magic number — only its first 4 bytes are inspected.
- synology_apm_repo.sdk.format.compression.zstd_content_size(data)¶
The decompressed size
data’s zstd frame declares, orNoneifdatalacks the frame magic or the frame declares none. For callers that need the ceiling before decompressing.- Raises:
zstandard.ZstdError – The frame header is malformed.
- synology_apm_repo.sdk.format.compression.decompress_zstd_stream(data, *, max_output_size)¶
Decompress a whole ZSTD frame (e.g.
version.db.zstor a service-DB snapshot) into onebytes. A wrapper arounditer_decompressed_zstd(see it formax_output_size); a caller writing to a file should stream that iterator instead of holding the payload in memory.- Raises:
DataCorruptError – As
iter_decompressed_zstd.zstandard.ZstdError – As
iter_decompressed_zstd.
- synology_apm_repo.sdk.format.compression.iter_decompressed_zstd(data, *, max_output_size)¶
Decompress a whole ZSTD frame incrementally, yielding plaintext pieces. Does no I/O; the caller decides where the pieces go.
max_output_sizeis mandatory, with no default, as a decompression-bomb guard: pass a byte ceiling, orNoneonly for a source already trusted not to be hostile-sized (seeunits/saas/services.py’sopen_service_db). It is the fallback ceiling for a frame that declares no size; a declared size becomes the ceiling instead.Nonewith no declared size bounds nothing.Reads through the streaming reader and counts the total itself, because
ZstdDecompressor.decompress(max_output_size=...)ignores its cap when the frame declares a size. A declared size is also verified afterward, since a truncated frame can decode with fewer bytes than declared.- Raises:
DataCorruptError – The frame declares a content size that doesn’t match what decompression produced.
zstandard.ZstdError – The output exceeds the effective ceiling, or the frame is malformed.