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

Per-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_many for the batched form. data may be a memoryview (copied only for NONE).

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. data may be a memoryview.

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. NONE entries return the input as given.

Raises:
synology_apm_repo.sdk.format.compression.is_zstd_frame(head)

Whether head opens 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, or None if data lacks 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.zst or a service-DB snapshot) into one bytes. A wrapper around iter_decompressed_zstd (see it for max_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_size is mandatory, with no default, as a decompression-bomb guard: pass a byte ceiling, or None only for a source already trusted not to be hostile-sized (see units/saas/services.py’s open_service_db). It is the fallback ceiling for a frame that declares no size; a declared size becomes the ceiling instead. None with 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.