synology_apm_repo.sdk.dedup.repository module

DedupRepo: opens one repository root and ties RepoInfo/key material/Pool/CompositionReader together behind open_file()/open_composition().

Repository-root path constants (FORMAT-SPEC.md: Locating the repository root, and directory layout) are uniform across both layout kinds — <repo_root>/@data/Pool, <repo_root>/@data/Composition, <repo_root>/db/; only layout.repo_root itself differs (the vault root directly for RepoKind.VAULT, or @ActiveProtectData/<repoId> for RepoKind.OBJECT_STORE).

synology_apm_repo.sdk.dedup.repository.DB_SOURCE_NAMES = frozenset({'connection_config', 'copy_target_version', 'copy_target_version_meta', 'file_map', 'file_meta', 'vault_link_key', 'workload_config'})

Every db/<name> DedupRepo.db() serves (copy_target_file is aliased to copy_target_version before lookup). This closed set is what bounds _db_sources: add a name here when a new caller needs one.

synology_apm_repo.sdk.dedup.repository.FILE_MAP_STATUS_COMPLETE = 2

The db/file_map.status of a complete file, the only one locate_file accepts; see its Raises section for the others (FORMAT-SPEC.md: db/file_map). Public because units.saas.stream pre-filters candidates with it.

class synology_apm_repo.sdk.dedup.repository.FileLocation(stream_id, session_id, comp_offset, block, file_size)

Bases: object

One db/file_map row, resolved to what DedupRepo.open_composition needs plus (when available) file_meta.file_size. status is not carried here — locate_file already rejects every row except Complete (FORMAT-SPEC.md: db/file_map) before constructing one.

stream_id: StreamId
session_id: SessionId
comp_offset: CompOffset
block: int
file_size: int | None
class synology_apm_repo.sdk.dedup.repository.DedupRepo(store, layout, info, dir_cache, *, fixed_dir_cache=None, vault_key=None, limits=CacheLimits(bucket_readers=16, bucket_readers_interactive=64, chunks=4096, composition_records=64, composition_pages=128, saas_streams=8, dir_scan=256, dir_fixed=64, allocation_tables=256, forward_resolutions=4096), verify=VerifyPolicy(ciphertext_crc=False, fingerprint=False))

Bases: AsyncClosing

One opened repository: its Pool, a cache of read-only db/<name> sqlite connections, and a repo-wide CompositionRecord cache shared by every CompositionReader it builds. Hands back a DedupFile via open_file/open_composition. Async context manager; close() releases the connections and caches.

Variables:
  • layout – The RepoLayout this repository was opened from.

  • info – The parsed repo_info.

caches

Every cache this repository owns, by name; see CacheManager.

property store: ObjectStore

The ObjectStore this repository was opened against, for callers above Catalog that need a raw read outside Pool/ CompositionReader/db() (e.g. catalog’s link-key display-name lookup).

property vault_key: bytes | None

The resolved VaultKey (None for an unencrypted repository or one opened without key material), for callers that decrypt outside Pool (e.g. catalog.version.open_target_db peeling an aHlT-enveloped target.db).

property dir_cache: DirCache

This repository’s DirCache for bulk-scannable directories (Pool leaves, Composition, a SaaS stream’s db/).

async repo_info_path()

The store path of the repo_info generation this repository uses — on object storage the committed one, as open reads it.

Raises:

NotFoundError – No usable repo_info exists.

new_pool(*, verify)

A separate Pool over this repository’s chunks, with its own caches (sized by this repository’s CacheLimits) and verify policy; it shares this repository’s directory cache.

async classmethod open(store, layout, keys=None, *, limits=CacheLimits(bucket_readers=16, bucket_readers_interactive=64, chunks=4096, composition_records=64, composition_pages=128, saas_streams=8, dir_scan=256, dir_fixed=64, allocation_tables=256, forward_resolutions=4096), verify=VerifyPolicy(ciphertext_crc=False, fingerprint=False))

Open layout. Reads only repo_info and, given keys for an encrypted repository, the wrapped VaultKey record; never scans Pool or Composition.

Parameters:
  • store (ObjectStore) – The repository’s ObjectStore.

  • layout (RepoLayout) – Where the repository root lives.

  • keys (KeyMaterial | None) – Key material; None opens without a VaultKey.

  • limits (CacheLimits) – Bounds of every cache this repository owns: the Pool’s, the directory caches and the composition-record cache.

  • verify (VerifyPolicy) – The per-chunk checks every Pool read runs.

Raises:
async db(name)

Open (and cache) a connection to db/<name>.

Read-only against the store: the fast path opens the real file immutable; the slow path opens a private materialized copy read-write (so an index hint can take effect) whose writes never reach the store.

name is first resolved through PHYSICAL_NAME_ALIASES ("copy_target_file" lives inside "copy_target_version"’s file), so both names share one connection.

On a RepoKind.OBJECT_STORE layout the generation is chosen by FORMAT-SPEC.md: Multi-generation selection (resolve_generation), not the largest .<N> suffix, since a generation can exist on disk before its transaction commits. db/<name> is always raw (never aHlT/zstd-enveloped).

Parameters:

name (str) – Logical db/<name>.

Returns:

The cached connection; close() owns its lifetime.

Raises:
Return type:

Connection

async locate_file(path)

Look up path in db/file_map and supplement it with file_meta.file_size when a matching row exists. file_meta.path is only unique per connection_config_id; this takes the first match.

Raises:
  • NotFoundError – no row for path at all, or its status is Initialized/Written/Compacted (0/1/3) — not yet, or no longer, resolvable content (FORMAT-SPEC.md: db/file_map).

  • DataCorruptError – the row’s status is Corrupted/Tainted (4/5) — the format itself flags this data as known-bad.

async file_map_paths_with_prefix(prefix, *, status=None)

Every db/file_map path starting with prefix, sorted. %/_/\ in prefix match literally.

status, when given, restricts to rows at exactly that file_map.status value (FORMAT-SPEC.md: db/file_map); without it, unlike locate_file, no status filtering applies.

async open_file(path, *, fallback_size=None)

Resolve path via db/file_map and return a ready-to-read DedupFile, sized by file_meta.file_size, or by fallback_size when file_meta records none for it.

Raises:
open_composition(stream_id, session_id, comp_offset, size=None)

A DedupFile for a (stream_id, session_id, comp_offset) triple, with size as its known size (None: unknown). Its CompositionReader shares this repository’s composition-record cache.

composition_reader(stream_id, session_id, *, shared_cache=False)

A CompositionReader for one session’s Composition, caching its records in this repository’s shared cache only with shared_cache.

async close()

Close every cached sqlite connection (and any temp file or directory a slow-path materialization created) and drop every other cache this repository holds, via caches.invalidate_all().

In-flight fetches are settled first, and every resource gets a close attempt, bounded by a timeout, even if an earlier one failed.

Raises:

ExceptionGroup – One or more resources failed to close.