synology_apm_repo.sdk.storage.base module¶
The ObjectStore protocol — the sole boundary between “how bytes are
fetched” and everything above it.
Four read methods of pure byte/existence semantics, plus close(). Sequence-id suffixes, SQLite,
WAL files and repository layout are built on top of an ObjectStore in
this package (seqid, layout, sqlite, generations), so a new
backend only implements those five.
All paths are "/"-separated strings relative to the store’s root, never
pathlib.Path and never absolute; a backend like S3 has no working
directory or OS path separator.
- synology_apm_repo.sdk.storage.base.NETWORK_CONNECT_TIMEOUT = 5¶
Seconds a network store waits to connect. The client libraries’ batch-tuned defaults are capped to what an interactive caller, such as the TUI’s connect dialog, can wait through.
- synology_apm_repo.sdk.storage.base.NETWORK_READ_TIMEOUT = 15¶
Seconds a network store waits for one request’s response; see
NETWORK_CONNECT_TIMEOUT.
- class synology_apm_repo.sdk.storage.base.Entry(name, size)¶
Bases:
NamedTupleOne entry
ObjectStore.listdirreports.
- class synology_apm_repo.sdk.storage.base.ObjectStore(*args, **kwargs)¶
Bases:
ProtocolRead-only, byte-oriented access to one repository’s storage tree.
Every method is
async def:LocalFsStoreandSmbStorerun their blocking calls on worker threads, whileS3StoreandAzureStoresit onaiohttp.Implementations MUST be safe to call concurrently, from several asyncio Tasks or from OS threads.
Implementations MUST NOT expose any mutating method;
@runtime_checkablechecks only that the methods below exist.Every failure surfaces as an
ApmRepoError:NotFoundError,PermissionDeniedError, orStorageBackendErrorfor anything else (network, timeout, service or OS I/O error) — never a client library’s own exception.- async read(path, offset=0, length=None)¶
Return up to
lengthbytes starting atoffsetinpath.length=Nonereads to end-of-file. Short reads at end-of-file return fewer bytes than requested, never pad or raise.- Raises:
NotFoundError –
pathdoes not exist.PermissionDeniedError – Access was denied.
StorageBackendError – The backend failed to serve the request.
- async size(path)¶
Return the total byte length of
path.- Raises:
NotFoundError –
pathdoes not exist or is a directory.PermissionDeniedError – Access was denied.
StorageBackendError – The backend failed to serve the request.
- async exists(path)¶
Return whether
pathexists (file or directory). Never raises for a merely-absent path.LocalFsStoreandSmbStorealso returnFalsewhen access is denied, so probing candidate paths never aborts a search;S3Store/AzureStoreraisePermissionDeniedErrorfor it. Any backend raisesStorageBackendErrorwhen the request itself fails.
- async listdir(path)¶
Return the immediate entries (files and subdirectories) directly under
path, sorted by name, each with the size its listing reported, so a caller needing sizes stats nothing.- Raises:
NotFoundError –
pathdoes not exist or is not a directory (LocalFsStore,SmbStore).S3Store/AzureStorehave no directories and return[]for an absent prefix.PermissionDeniedError – Access was denied.
StorageBackendError – The backend failed to serve the request.
- async close()¶
Release what the store holds (network clients, sessions, threads); a no-op for one holding nothing, such as
LocalFsStore. Safe to call more than once.
- async synology_apm_repo.sdk.storage.base.list_names(store, path)¶
store.listdir(path)’s names alone, sorted.
- class synology_apm_repo.sdk.storage.base.SyncReadable(*args, **kwargs)¶
Bases:
ProtocolAn
ObjectStorewhosereadis a blocking call it hops to a thread anyway (LocalFsStore), offering that call directly, so a caller already on a worker thread reads without a second hop. Optional: a wrapper such asTracingStoredoes not offer it, so its reads keep going through the wrapper.- read_sync(path, offset=0, length=None)¶
ObjectStore.read’s contract, blocking the calling thread.
- synology_apm_repo.sdk.storage.base.join_path(*parts)¶
Join
partsinto one store-relative,"/"-separated path, skipping empty parts (repo_rootis often"") and stripping stray leading/trailing"/". EveryObjectStorepath is built this way.Every
"/"-separated segment of every part is checked, since one part may be a catalog-derived string containing several segments. Rejected:a
".."segment, which would escape the store root.a segment containing a backslash: the convention is
"/"only, and on Windows a backslash would later be read as a separator bypathlib.
This is the primary path-safety check (
SmbStorehas none of its own);LocalFsStorealso checks the assembled path as a backstop.- Raises:
NotFoundError – a segment is
".."or contains a backslash.
- synology_apm_repo.sdk.storage.base.backend_key(path)¶
Strip
path’s leading/trailing"/"for S3 object keys and Azure blob names, which reject a leading"/".