synology_apm_repo.sdk.catalog.version module

Version: one db/copy_target_version row (+ _meta when present), the queries that list or look one up, its meta-directory resolution, and open_target_db() for the Device and FS providers.

version_spec is AES-256-CTR ciphertext whenever the repository has a vault key (FORMAT-SPEC.md: copy_target_version.version_spec encryption); parse_version_spec decrypts and parses it.

class synology_apm_repo.sdk.catalog.version.VersionMeta(target_meta_path, meta_filenames, status)

Bases: object

A version’s _meta sidecar, when present: its directory, the filenames it holds, and its own status code.

target_meta_path: str
meta_filenames: tuple[str, ...]
status: int
class synology_apm_repo.sdk.catalog.version.Version(version_id, version_uid, workload_id, connection_config_id, target_type, target_id, saas_stream_uuid, saas_snapshot_uuid, saas_version_id, deleted, display_name, meta)

Bases: object

One browsable db/copy_target_version row (+ _meta when present).

Variables:
  • target_type (str) – The raw column value, normally a TargetType value.

  • deleted (bool) – The row’s deleted flag.

  • display_name (str) – The backup time in local time ("YYYY-MM-DD HH:MM:SS"), or version_uid when it can’t be read.

  • meta (synology_apm_repo.sdk.catalog.version.VersionMeta | None) – The copy_target_version_meta row, or None when none landed.

version_id: VersionId
version_uid: VersionUid
workload_id: WorkloadId
connection_config_id: ConnectionConfigId
target_type: str
target_id: TargetId
saas_stream_uuid: StreamUuid
saas_snapshot_uuid: SnapshotUuid
saas_version_id: SaasVersionId
deleted: bool
display_name: str
meta: VersionMeta | None
property is_saas: bool

Whether this is a SaaS (GWS/M365) version.

synology_apm_repo.sdk.catalog.version.resolve_meta_filename(meta, name, *, ref=None)

Return name (e.g. "target.db") after confirming it is in meta.meta_filenames, the meta directory’s authoritative file list (FORMAT-SPEC.md: dedup data mapping chain).

Raises:

NotFoundError – name was never registered for this version.

synology_apm_repo.sdk.catalog.version.resolve_copy_meta_dir(version, repo_root)

The copy_meta_file/<dir> under repo_root holding a device or FS version’s meta files (target.db, …), named by the last component of copy_target_version_meta.target_meta_path.

Raises:

NotFoundError – version has no meta row, or its target_meta_path is malformed.

async synology_apm_repo.sdk.catalog.version.open_target_db(repo, version, meta_dir)

Open <meta_dir>/target.db (aHlT-enveloped or not, with any -wal/-shm sidecar; FORMAT-SPEC.md: Landing directory layout), checked against meta_filenames. version.meta must be set, as resolve_copy_meta_dir already required.

Raises:
  • NotFoundError – target.db is not in meta_filenames.

  • DataCorruptError – The file or a sidecar claims an aHlT/zstd frame that doesn’t decode (or not to its declared size), or is aHlT-enveloped and the repository has no vault key.

  • ResourceLimitExceededError – Its temporary copy, or a sidecar’s, doesn’t fit in free disk space with the reserve left free.

async synology_apm_repo.sdk.catalog.version.target_version_id(target_db, meta_dir)

target.db’s own version_table.version_id.

Raises:

NotFoundError – version_table has no row.

async synology_apm_repo.sdk.catalog.version.versions(repo, workload, *, include_deleted=False)

workload’s browsable versions, newest backup first (the time display_name shows); one without a readable time sorts last, ties by version_id descending.

Raises:

DataCorruptError – A copy_target_version_meta row’s meta_filenames is not a JSON array.

async synology_apm_repo.sdk.catalog.version.version_by_uid(repo, version_uid)

The version with version_uid, deleted or not, decrypting only its row. None if it doesn’t exist or isn’t browsable.

Raises:

DataCorruptError – As versions.

async synology_apm_repo.sdk.catalog.version.version_file_ids(repo, version)

Every fid this version registered in copy_target_file (a PC/PS version’s disk fragments); empty when the repository has no copy_target_version database.

async synology_apm_repo.sdk.catalog.version.version_additional_meta(repo, version)

version_spec.status.additional_meta (SaaS connector bookkeeping, e.g. its object-name index), parsed; None whenever it can’t be read, including when a level of it is not of its expected JSON type.

class synology_apm_repo.sdk.catalog.version.ParsedVersionStatus(status=None, start_time=None, end_time=None)

Bases: object

The version_spec.status fields this module reads, named as the JSON keys.

status: object
start_time: object
end_time: object
synology_apm_repo.sdk.catalog.version.parse_version_spec(version_spec_raw, version_uid, vault_key)

One copy_target_version.version_spec value, decrypted whenever vault_key is given (the column has no marker to probe) and JSON-parsed; None on any failure.