synology_apm_repo.sdk.diagnostics module

Repository Layer sibling — raw, catalog-bypassing inspection of one physical file, addressed by a bare store-relative path rather than a NodeRef. For forensics tooling (the CLI’s dump command family) that needs “what does this byte layout actually say” for one .buk/composition/chunk-map file outside any discovered repository — the same Codec/Dedup Layer parsers the real read path uses, wrapped here so CLI/TUI code never imports format/storage/dedup internals directly for this. Every function here takes an already-resolved ObjectStore rather than opening one itself — the CLI decides local vs. --profile and hands in whichever store applies; open_local() is only the local-path adapter it uses for its own local case.

Deliberately out of scope: resolving a .<N> sequence-id suffix (FORMAT-SPEC.md: sequence-id-suffix) from a logical name — callers pass the literal on-disk filename, local or remote, the same way they always have.

synology_apm_repo.sdk.diagnostics.mode_flags(mode)

Bucket-header mode bits as their names — bit→string is format knowledge, not a CLI rendering concern.

synology_apm_repo.sdk.diagnostics.open_local(path)

Split a literal local file path into an ObjectStore rooted at the parent directory plus the bare filename — the CLI’s own adapter for its local (non---profile) case, so the actual reads still go through the storage layer, the same as every --profile-resolved remote store, rather than a second, ad hoc open() call here.

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

Bases: object

One --chunk-selected entry’s own fields, nested under BucketInspection when a specific chunk was asked for.

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
actual_size: int
size_check_ok: bool
chunk: ChunkEntryInspection | None = 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:

IndexError – chunk is out of range for this bucket’s own entry count.

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 own fields, mirroring ChunkMapEntryInspection’s shape one section down: map_crc_ok holds a real bool only when verify_map was given (set by _walk_composition_records), staying None otherwise.

head_off: int
status: str
map_num: int
mode: int
has_redundancy: bool
attr_leng: int
map_crc_ok: bool | None = 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: the header (if the file starts with one — subID=0 only), every record walked up to limit, the offset walking stopped at, and — only when the walk stopped because a record failed to parse partway through, not because it reached limit/the file’s end — that failure’s message.

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

Walk composition records in rel — the header, if present (subID=0 only), plus up to limit records starting at offset (default: right after the header, or byte 0 for a non-subID=0 file).

Raises the underlying ApmRepoError when nothing at all could be parsed (no header, and the record walk failed before it collected even one record); a failure partway through an otherwise-successful walk is reported in the returned CompositionWalk’s stopped_with_error instead.

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

Bases: object

A MAPPING chunk-map entry’s resolved chunk address — which stream, bucket, and chunk index it points at.

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 only carries a real value for a ChunkMapKind.MAPPING record; every other kind leaves it None.

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

Bases: object

The result of dumping one record’s ChunkMapRecord array — its own map-entry count, decoded entries, and (when checked) the mapCrc verdict.

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)

Dump the ChunkMapRecord array — the core read structure — of the record at offset: each entry’s kind, file/end offsets, inherit flag, map number and repeat count, plus (with verify=True) the chunk-map CRC check result.