synology_apm_repo.sdk.diagnostics module

Raw inspection of one physical .buk/composition/chunk-map file, addressed by a store-relative path instead of a NodeRef and bypassing the catalog, for forensics tooling such as the CLI’s dump commands. It uses the same parsers as the read path, so callers need no format/storage/dedup internals.

Every function takes an already-resolved ObjectStore (open_local() builds one for a local path) and the literal on-disk filename: a .<N> sequence-id suffix (FORMAT-SPEC.md: Sequence-id suffix mechanism) is not resolved from a logical name.

synology_apm_repo.sdk.diagnostics.mode_flags(mode)

Bucket-header mode bits as their names.

synology_apm_repo.sdk.diagnostics.open_local(path)

A local file path as an ObjectStore rooted at its parent directory plus the bare filename, for the functions here.

class synology_apm_repo.sdk.diagnostics.ChunkEntryInspection(index, compress_type, stored_len, effective_len, offset, length)

Bases: object

One bucket entry’s fields, as inspect_bucket’s chunk selected it.

index: int
compress_type: str
stored_len: int
effective_len: int
offset: int
length: int
class synology_apm_repo.sdk.diagnostics.BucketInspection(path, major, minor, mode, mode_flags, chunk_num, chunk_size_crc, compress_type_counts, expected_size, actual_size, size_check_ok, chunk=None)

Bases: object

A .buk file’s header, SizeStore summary, and the expected_bucket_size self-check.

path: str
major: int
minor: int
mode: int
mode_flags: list[str]
chunk_num: int
chunk_size_crc: int
compress_type_counts: dict[str, int]
expected_size: int | None

None for the legacy uncompressed layout, which has no expected_bucket_size formula; size_check_ok is None then too.

actual_size: int
size_check_ok: bool | None
chunk: ChunkEntryInspection | None
async synology_apm_repo.sdk.diagnostics.inspect_bucket(store, rel, *, chunk=None)

Inspect a .buk file’s header, SizeStore summary, and expected_bucket_size self-check.

Raises:
  • NotFoundError – rel does not exist, or chunk is out of range for this bucket’s entry count.

  • DataCorruptError – The header or SizeStore is corrupt and not repairable.

class synology_apm_repo.sdk.diagnostics.CompositionRecordInspection(head_off, status, map_num, mode, has_redundancy, attr_leng, map_crc_ok=None)

Bases: object

One composition record’s fields; map_crc_ok is None unless walk_composition was asked to verify_map.

head_off: int
status: str
map_num: int
mode: int
has_redundancy: bool
attr_leng: int
map_crc_ok: bool | None
class synology_apm_repo.sdk.diagnostics.CompositionWalk(path, header, records, next_offset, file_size, stopped_with_error=None)

Bases: object

walk_composition’s result.

Variables:
  • path (str) – The walked file, as rel named it.

  • header (tuple[int, int] | None) – The composition header’s (major, minor); None when the file has none (only subID=0 does).

  • records (list[synology_apm_repo.sdk.diagnostics.CompositionRecordInspection]) – The records walked, at most limit.

  • next_offset (int) – Where walking stopped.

  • file_size (int) – The file’s size, which bounds the walk.

  • stopped_with_error (str | None) – Why a record failed to parse, when that ended the walk before limit or the end of the file.

path: str
header: tuple[int, int] | None
records: list[CompositionRecordInspection]
next_offset: int
file_size: int
stopped_with_error: str | None
async synology_apm_repo.sdk.diagnostics.walk_composition(store, rel, *, offset=None, limit=10, verify_map=False)

The composition header of rel, if present, plus up to limit records from offset (default: right after the header, else byte 0). A parse failure after something was parsed is reported in stopped_with_error.

Raises:

ApmRepoError – Nothing could be parsed: no header, and not even one record.

class synology_apm_repo.sdk.diagnostics.ChunkMapAddrInspection(stream_id, bucket_id, chunk_idx)

Bases: object

A MAPPING chunk-map entry’s chunk address.

stream_id: int
bucket_id: int
chunk_idx: int
class synology_apm_repo.sdk.diagnostics.ChunkMapEntryInspection(index, kind, file_offset, end_offset, is_inherit, map_num, repeat, addr=None)

Bases: object

One ChunkMapRecord entry; addr is set only for a ChunkMapKind.MAPPING entry.

index: int
kind: str
file_offset: int
end_offset: int
is_inherit: bool
map_num: int
repeat: int
addr: ChunkMapAddrInspection | None
class synology_apm_repo.sdk.diagnostics.ChunkMapInspection(path, head_off, map_num, map_crc_ok, entries)

Bases: object

inspect_chunk_map’s result: the record’s entry count, the decoded entries, and the map-CRC verdict when checked.

path: str
head_off: int
map_num: int
map_crc_ok: bool | None
entries: list[ChunkMapEntryInspection]
async synology_apm_repo.sdk.diagnostics.inspect_chunk_map(store, rel, offset, *, limit=50, verify=False)

The first limit entries of the ChunkMapRecord array of the record at offset, plus the chunk-map CRC verdict when verify is set.