synology_apm_repo.sdk.storage.layout module

Repository layout detection (FORMAT-SPEC.md: Locating the repository root).

Two shapes exist, both at a fixed depth:

  • Vault (APV, or any local-filesystem Copy destination): a directory (conventionally @ActiveProtectVault; detection is by marker, not name) is the repository root, one level under the admin-chosen shared folder. Identified by repo_info, link.key and .fully_created together at that path. One repository per root, one vault per shared folder.

  • Object storage (S3/Azure landed copies): the root contains an @ActiveProtectData/<12-char-repo-id>/ subtree, possibly with several sibling <repo-id> directories, and a parallel @ActiveProtectKey/{userKey,link}/ tree one level up from @ActiveProtectData. Each <repo-id> is an independent repository sharing the same key tree.

    repo_info is not a reliable marker there (it may exist only as repo_info.<N>). db/ and @data are always bare-named directories, so the pair is the marker; requiring both guards against unrelated directories that merely contain db.

Neither shape nests more than one level under what an admin provisioned (a shared folder, a bucket), so a connection pointed up to two levels above that still finds every repository. _DEFAULT_MAX_DEPTH bounds the walk at that, so a misdirected scan of an unrelated tree can’t run away.

synology_apm_repo.sdk.storage.layout.REPO_INFO_NAME = 'repo_info'

The logical name of the repository-root repo_info file, as FORMAT-SPEC.md’s repo_info section defines it.

class synology_apm_repo.sdk.storage.layout.RepoKind(*values)

Bases: Enum

Which of the two physical repository backends a RepoLayout describes.

VAULT = 'vault'
OBJECT_STORE = 'object_store'
class synology_apm_repo.sdk.storage.layout.RepoLayout(kind, repo_root, key_root=None, repo_id=None)

Bases: object

Where one catalog (a vault, or one <repo-id> directory) lives within an ObjectStore: what DedupRepo.open() takes. Built from a RepositoryLayout by catalog_repo_layouts.

Variables:
  • kind (synology_apm_repo.sdk.storage.layout.RepoKind) – Vault or object storage.

  • repo_root (str) – Store-relative repository root ("": the store root).

  • key_root (str | None) – Store-relative @ActiveProtectKey directory for object storage, or None if not found or not applicable.

  • repo_id (str | None) – The 12-character repository id for object storage, when known.

kind: RepoKind
repo_root: str
key_root: str | None
repo_id: str | None
class synology_apm_repo.sdk.storage.layout.RepositoryLayout(kind, repo_root, key_root=None, catalog_ids=None)

Bases: object

Where one Repository (a bucket, or a vault’s own shared folder) lives within an ObjectStore.

Variables:
  • kind (synology_apm_repo.sdk.storage.layout.RepoKind) – Vault or object storage.

  • repo_root (str) – Store-relative root ("": the store root).

  • key_root (str | None) – Store-relative @ActiveProtectKey directory, or None.

  • catalog_ids (list[str] | None) – For OBJECT_STORE, the valid repo-id children of @ActiveProtectData/ (an empty list: none). None for VAULT (catalogs come from db/connection_config) and when root is an individual repository directory with no derivable bucket-root ancestor (see _data_dir_ancestor).

kind: RepoKind
repo_root: str
key_root: str | None
catalog_ids: list[str] | None
property display_root: str

repo_root without its @ActiveProtectVault/ @ActiveProtectData segments, at any depth: the part worth showing a user (the folders above the repository, an object-storage repo id); "" for a vault at the store root.

async synology_apm_repo.sdk.storage.layout.iter_repository_layouts(store, root='', *, max_depth=2)

Walk down from root looking for Repository roots (a bucket, or a vault’s shared folder), yielding each as found. A bucket with several catalogs yields one RepositoryLayout whose catalog_ids lists them.

Only exists()/listdir() calls, never a scan into Pool/ Composition/db. A found root ends the walk along its branch; otherwise max_depth (default 2, see the module docstring) bounds it.

synology_apm_repo.sdk.storage.layout.catalog_repo_layouts(layout)

The RepoLayout(s) layout resolves to, each openable by DedupRepo.open().

A vault, or an OBJECT_STORE layout with catalog_ids of None, yields one RepoLayout at layout.repo_root (a vault’s catalogs come from db/connection_config after opening). Otherwise one per catalog_ids entry, rooted at its @ActiveProtectData/<repo-id> directory and sharing layout.key_root. Empty only when catalog_ids is an empty list.

synology_apm_repo.sdk.storage.layout.key_probe_layout(layout)

A RepoLayout carrying only the fields dedup.keys reads for key and encryption resolution (probe_encrypted/resolve_vault_key/ verify), built from a RepositoryLayout without opening a catalog. Used by discovery’s key probe and Repository.set_key().

async synology_apm_repo.sdk.storage.layout.detect_repository_layout(store, root='')

Detect the Repository layout at root. A bucket’s several repository ids are not an error; they appear in catalog_ids.

Raises:

NotFoundError – root is not a repository root.