synology_apm_repo.sdk.format.addressing module

Chunk addressing and the two path-layering schemes that key off it (FORMAT-SPEC.md: Pool path layering; Composition file splitting).

Directory-name constants (Pool, Composition, …) live in the Dedup Layer’s repository.py (FORMAT-SPEC.md: directory layout). This module computes only the id-layering fragment relative to a caller-supplied root.

class synology_apm_repo.sdk.format.addressing.ChunkAddress(stream_id, bucket_id, chunk_idx)

Bases: NamedTuple

A single uint64 chunk address: streamID(8b) | bucketID(40b) | chunkIdx(16b) (FORMAT-SPEC.md: ChunkAddress).

Fields are not range-checked on construction or by from_int; an out-of-range field surfaces downstream (DataCorruptError for an over-capacity chunk_idx, NotFoundError for a bogus bucket_id) or as a verify() finding.

A NamedTuple, not a frozen dataclass: built per chunk, where it is cheaper.

stream_id: StreamId

Alias for field number 0

bucket_id: BucketId

Alias for field number 1

chunk_idx: ChunkIdx

Alias for field number 2

classmethod from_int(data)

Unpack a raw uint64 chunk address (not range-checked).

to_int()

Pack into the raw uint64 form.

advance(k)

Advance by k chunks, carrying into bucket_id when chunk_idx reaches BUCKET_MAX_CHUNK_NUM (8192), not at the packed field’s 16-bit boundary.

Raises:

ValueError – k is negative.

synology_apm_repo.sdk.format.addressing.pool_layer_path(stream_id, bucket_id)

Relative path (no Pool/ prefix, no .buk/.inf/… suffix) for bucket_id within stream_id’s pool: <streamID>/[ancestor layers.../]<bucketID> (FORMAT-SPEC.md: Pool path layering).

For a .inf/.fgp/.ref group path, pass the group’s starting bucket id (group_start_bucket_id), not an individual bucket’s.

synology_apm_repo.sdk.format.addressing.composition_session_dir(stream_id, session_id)

Relative path (no Composition/ prefix) to a session’s directory: <streamID>/[ancestor layers.../]<sessionID>.com (FORMAT-SPEC.md: Composition file splitting). Unlike the Pool leaf, the leaf carries a .com suffix.

synology_apm_repo.sdk.format.addressing.composition_path(stream_id, session_id, sub_id)

Full relative path (no Composition/ prefix, no sequence-id suffix) to a composition sub-file: <sessionDir>/[ancestor layers.../]c<subID> (FORMAT-SPEC.md: Composition file splitting).

synology_apm_repo.sdk.format.addressing.split_layer_leaf(layer_path)

Split a pool_layer_path()/composition_path() result into (dir_part, leaf). dir_part is "" when there are no ancestor layers; pass it to join_path, which tolerates that.

synology_apm_repo.sdk.format.addressing.split_composition_offset(global_offset)

Split a composition-record global offset into (sub_id, offset_within_subfile): off >> 24 and off & (16 MiB - 1) (FORMAT-SPEC.md: Composition file splitting).

synology_apm_repo.sdk.format.addressing.group_start_bucket_id(bucket_id)

The starting bucket id of the 1024-bucket group bucket_id belongs to: bucket_id & ~(GROUP_BUCKET_NUM - 1).