synology_apm_repo.sdk.storage.generations module

S3/Azure db/<name>.<N> generation selection (FORMAT-SPEC.md: Multi-generation selection). The single place this rule lives; dedup/repository.py uses it for db/<name> and repo_info.

The naive “largest .<N> suffix” rule (resolve_seq_file) is not enough here: a db/<name> generation can be written to S3/Azure before its transaction commits, so the largest suffix can be uncommitted or superseded. The answer needs the transaction log:

  1. ``latest_txn`` (latest_transaction_id): the largest repo_transactions/repo_transaction.<N> filename, opened and parsed — the answer is that file’s embedded transaction_id, never the filename’s own <N> (the two are not the same number).

  2. ``file_map``/``repo_info`` (anything not in SUPPLEMENTAL_TABLES): among db/<name>.<N>’s suffixes, the largest one strictly less than latest_txn — a generation written at or after the latest committed transaction is exactly the “written but not yet committed” case above.

  3. The 9 supplemental tables (SUPPLEMENTAL_TABLES) use an independent, simpler rule: the largest suffix that also has a matching suppl_transaction_ids/<N> marker file — a numbering completely unrelated to repo_transactions/’s own.

A logical name with no .<N> variant falls back to the bare name.

synology_apm_repo.sdk.storage.generations.SUPPLEMENTAL_TABLES = frozenset({'agent_connection', 'connection_config', 'copy_file', 'copy_source_version', 'copy_target_file', 'copy_target_version', 'copy_target_version_meta', 'file_meta', 'workload_config'})

The supplemental tables, resolved by the suppl_transaction_ids/ marker rule, not the transaction-log rule (FORMAT-SPEC.md: Multi-generation selection). copy_target_file is listed for completeness; it shares copy_target_version’s physical file (see PHYSICAL_NAME_ALIASES).

synology_apm_repo.sdk.storage.generations.PHYSICAL_NAME_ALIASES: dict[str, str] = {'copy_target_file': 'copy_target_version'}

Logical db/<name> names with no on-disk object of their own: copy_target_file lives inside the copy_target_version[.N] file. DedupRepo.db applies it before generation resolution, on both layouts.

synology_apm_repo.sdk.storage.generations.Listdir

A function returning a directory’s entry names, such as DirCache.listdir.

alias of Callable[[str], Awaitable[list[str]]]

async synology_apm_repo.sdk.storage.generations.latest_transaction_id(store, transactions_dir, *, listdir=None)

The latest committed transaction id, per FORMAT-SPEC.md: Multi-generation selection: the transaction_id embedded in the highest-numbered repo_transaction.<N> file.

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

  • transactions_dir (str) – The repo_transactions directory.

  • listdir (Callable[[str], Awaitable[list[str]]] | None) – How to list transactions_dir; defaults to listing store directly (pass a DirCache.listdir to share the listing).

Raises:
async synology_apm_repo.sdk.storage.generations.resolve_generation(store, db_dir, name, *, transactions_dir, suppl_dir, listdir=None)

The correct db/<name>[.<N>] logical path for name on an OBJECT_STORE layout: the largest .<N> strictly less than the latest committed transaction for most tables, or the largest .<N> with a matching suppl_transaction_ids marker for the 9 supplemental tables (FORMAT-SPEC.md: Multi-generation selection). A name with no .<N> variant resolves to the bare name.

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

  • db_dir (str) – The db directory, joined with layout.repo_root.

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

  • transactions_dir (str) – repo_transactions directory, likewise joined.

  • suppl_dir (str) – suppl_transaction_ids directory, likewise joined.

  • listdir (Callable[[str], Awaitable[list[str]]] | None) – How to list the three directories; defaults to listing store directly (pass a DirCache.listdir to share listings across the several db/<name> resolutions one repository does).

Returns:

The store-relative path of the chosen generation.

Raises:
  • NotFoundError – .<N> variants exist but none is valid under the applicable rule (an inconsistent or partial repository copy), or transactions_dir holds no repo_transaction.<N>.

  • DataCorruptError – The latest repo_transaction.<N> is corrupt.

Return type:

str