synology_apm_repo.sdk.api.repository module¶
Repository: one opened repository’s catalog/provider facade, and
locate()/resolve()’s ref dispatch across its catalogs.
- class synology_apm_repo.sdk.api.repository.SetKeyResult(verification, reopen_errors=())¶
Bases:
objectWhat
Repository.set_key()decided, and what it could not finish.- Variables:
verification (synology_apm_repo.sdk.dedup.keys.KeyVerification) – Whether the key verified. The repository’s
key_statusalready reflects it.reopen_errors (tuple[Exception, ...]) – Failures re-opening or closing an already-opened catalog while switching to a verified key. The key itself was still accepted; empty when nothing went wrong.
- verification: KeyVerification¶
- class synology_apm_repo.sdk.api.repository.Repository(store, layout, keys, key_verification, *, encrypted=None)¶
Bases:
objectOne opened repository: cheap metadata plus the catalog/provider calls that turn it into a browsable tree. Obtained from
Session’sdiscover/open, never constructed directly; theSessioncloses it (Session.close_reporeleases one early).- property layout: RepositoryLayout¶
Where and what kind of repository this is.
- property is_encrypted: bool | None¶
Whether this repository is encrypted, or
Nonewhen that couldn’t be determined.
- property key_verification: KeyVerification | None¶
The latest key verification outcome;
Nonewhen no key was tried.
- async set_key(key_string)¶
Try a key string against this repository. When it verifies, every already-opened catalog is reopened under it, and one that fails to switch is reported in
reopen_errorsrather than raised. When it doesn’t, open catalogs are left as they were andkey_statusbecomesINVALID.- Parameters:
key_string (str) –
"<userKeyID>@<base64 userKey>"; an empty string is malformed (Session.openreads it as no key).- Returns:
The verification outcome plus any catalog reopen failures.
- Raises:
KeyMaterialError –
key_stringis malformed.DataCorruptError – The repository’s key record is unreadable.
- Return type:
- async catalogs()¶
Every catalog this repository holds: a vault’s
connection_configrows, or those of each object-storage sibling, opening the unopened ones concurrently.Needs no key: these rows are plaintext, so catalog names can be shown before a key prompt. A catalog that fails to open raises rather than being skipped, so a short list is never mistaken for a repository with fewer catalogs.
- async catalog_by_id(catalog_id)¶
The
Catalogmatchingcatalog_id, orNone, opening only the catalogs that could match. A candidate’s open failure is raised, as incatalogs().
- workload_is_supported(workload)¶
Whether
workload’s type has an application-layer provider;Truedoesn’t guarantee every version resolves.
- async file_map_tree()¶
The diagnostic
file_maptree, browsable even when catalog metadata is missing. Always the first catalog’s: aRAWref has no catalog segment to pick an object-storage sibling by. Tracked like any provider.
- cache_names()¶
The names
invalidate_cachesaccepts: every cache of every catalog opened so far, in registration order, without repeats.
- cache_stats()¶
Counters of every cache of every catalog opened so far, keyed
<catalog index>.<cache name>.
- async invalidate_caches(*names)¶
Drop cached data so the next call re-reads the store: the named caches (see
cache_names), or every cache when none is named.Call this after the store changed; nothing else revalidates. Catalogs stay valid: only their caches are rebuilt, and the connection list is re-read when
db_sourcesis dropped. Providers handed out earlier keep their own connections and are not closed; fetch fresh ones to see new data.No catalog or provider call may be in flight: db connections and SaaS streams are closed and replaced. Does nothing while no catalog has been opened, since nothing is cached yet.
- Parameters:
names (str) – Cache names to drop; none means all.
- Raises:
KeyError – A name is not in
cache_names(), checked once a catalog is open (nothing was dropped).RuntimeError – The repository is closed.
ExceptionGroup – One or more resources failed to close or rebuild.
- async release_provider(provider)¶
Close
providerand stop tracking it, so the repository doesn’t keep it (and what it references) alive until its own close.The close runs to completion even if this call is cancelled, and the repository’s close waits for it.
- async locate(ref, *, raw=None)¶
Where
reflands. A human ref walks display names (withdisambiguate()suffixes) catalog -> workload -> version -> item as far as its segments go, so it may stop above a node; a canonical or raw ref always names a node.ref.repo_pathis ignored.A
NodeFrame’sprovideris tracked until the repository closes; a caller done with it earlier passes it torelease_provider.- Parameters:
- Returns:
The frame the ref reached.
- Raises:
NotFoundError – A segment matches nothing, or no node matches a canonical/raw ref.
InvalidArgumentError – A segment matches ambiguously, or a canonical ref is malformed.
KeyRequiredError – The ref goes below a catalog of an encrypted repository and no key was supplied.
KeyMismatchError – As above, but the last key supplied was rejected.
ValueError – The string is not a parseable ref.
- Return type:
- async resolve(ref, *, raw=None)¶
locate, butrefmust reach a node: a human ref names at least a catalog, workload and version.NodeFrame.unit()turns a leaf into itsRestorableUnit.- Parameters:
- Returns:
The
NodeFramethe ref reached.- Raises:
NotFoundError – No node matches the ref.
InvalidArgumentError – A human ref stops above a version, a canonical ref is malformed, or a segment matches ambiguously.
KeyRequiredError – The ref goes below a catalog of an encrypted repository and no key was supplied.
KeyMismatchError – As above, but the last key supplied was rejected.
ValueError – The string is not a parseable ref.
- Return type:
- async version_for_ref(ref)¶
Resolve a canonical ref’s catalog/workload/version prefix, for a caller that wants the version’s provider rather than one node in it.
- Parameters:
ref (str | NodeRef) – A canonical
NodeRefor its string form.- Returns:
Where the version is; its
catalog’sprovider()opens it.- Raises:
NotFoundError – The ref names no such catalog or version.
InvalidArgumentError – The ref is malformed.
ValueError – The string is not a parseable ref.
KeyRequiredError – The ref goes below a catalog of an encrypted repository and no key was supplied.
KeyMismatchError – As above, but the last key supplied was rejected.
- Return type:
- async verify(level=VerifyLevel.QUICK, *, progress=None, tuning=None)¶
Integrity check over every catalog, each distinct
DedupRepoonce (a vault’s catalogs share one). Opens every catalog first; atFULLlevel, catalogs over the same pool share one worker pool.- Parameters:
level (VerifyLevel) – How deep to check.
progress (ProgressCallback | None) – Receives a
Progresssnapshot as checking advances.tuning (VerifyTuning | None) – How the check spreads its reads (default
VerifyTuning()).
- Returns:
Every
Findingfrom every catalog.- Raises:
KeyRequiredError – The repository is encrypted and no key was supplied (an unkeyed walk would read zero versions and look clean).
KeyMismatchError – The last key supplied was rejected.
StorageBackendError – A store call failed mid-check.
- Return type: