synology_apm_repo.sdk.storage.sqlite_source module¶
peel() and SqliteSource: one way to open each of the six
envelope -> SQLite sources:
source |
envelope chain |
|---|---|
repository |
raw |
|
aHlT? -> raw |
|
aHlT? -> zstd |
|
raw |
embedded |
raw |
service-level DB (saas_obj slice) |
zstd |
Only two envelope kinds exist (aHlT AES-CTR, then optionally a
standard ZSTD frame), each detected by its magic bytes, so callers needn’t
know which source they have.
- class synology_apm_repo.sdk.storage.sqlite_source.Envelope(*values)¶
Bases:
EnumWhich wrapper(s)
peelstripped, outermost first; informational (diagnostics/--verbose).- AHLT = 'aHlT'¶
- ZSTD = 'zstd'¶
- synology_apm_repo.sdk.storage.sqlite_source.peel(data, *, vault_key=None, max_zstd_output_size)¶
Strip whichever envelope(s)
dataactually has, auto-detected by magic, returning(payload, envelopes_stripped). A payload that isn’t zstd-framed is a valid outcome, not an error.max_zstd_output_sizeis mandatory and only the fallback ceiling for a zstd frame that declares no size (seeformat.compression.iter_decompressed_zstd); passNoneexplicitly only for a source already known to be trusted.- Raises:
KeyRequiredError –
dataisaHlT-enveloped but novault_keywas given.DataCorruptError – The
aHlTheader fails its magic or CRC check, or a zstd frame’s declared content size doesn’t match what decompression produced.FormatError –
datahas theaHlTmagic but is shorter than its 64-byte header.zstandard.ZstdError – The zstd frame is malformed or exceeds its ceiling.
- class synology_apm_repo.sdk.storage.sqlite_source.SqliteSource(connection, *, path=None, tmp_dir=None)¶
Bases:
AsyncClosingA connection to plain SQLite content, the common tail of all six sources in this module’s docstring.
Build one with the async classmethod factories (
from_bytes,from_raw_store, …). Usable asasync with, orawait close()directly. Except for afrom_raw_storeof a plainLocalFsStorefile (opened read-only in place), the content is a private temp copy, removed on close; the copy’s connection is writable (seefrom_bytes), so the source repository is never modified.- property path: str | None¶
The temp file’s path for a source built by
from_bytesorfrom_enveloped_bytes, elseNone. For a caller that must inspect the file’s raw bytes, which no query againstconnectioncan express.
- async classmethod from_bytes(data)¶
Materialize plain (post-
peel) SQLitedatato a private temp file and open a writable connection to it, soapply_index_hintcan build an index.close()unlinks the file.- Raises:
ResourceLimitExceededError –
datadoesn’t fit in the system temp directory withdisk_space’s reserve left free.
- async classmethod from_enveloped_bytes(data, *, vault_key=None, max_output_size, tmp_dir=None, what)¶
Like
from_bytes(), but fordatathat may still beaHlT/zstd enveloped (an embeddedObjectDBslice, a SaaS service-level DB snapshot,version.db.zst), streaming the decompressed result straight into the temp file. Returns(source, envelopes_stripped).- Parameters:
max_output_size (int | None) – Mandatory fallback ceiling for a zstd frame that declares no size (a declared size sizes the disk-space check and caps the write instead; see
format.compression.iter_decompressed_zstd).Nonewith no declared size caps the write at the free space abovedisk_space’s reserve instead.tmp_dir (str | Path | None) – Directory for the temp file; the system temp directory when omitted.
what (str) – Names
data’s source in error messages.
- Raises:
DataCorruptError –
datamatches the zstd/aHlTmagic but doesn’t decode, isaHlT-enveloped with novault_key, or a declared content size doesn’t match what decompression produced.FormatError –
datahas theaHlTmagic but is shorter than its 64-byte header.ResourceLimitExceededError – The declared size (or, absent one,
max_output_size) doesn’t fit intmp_dirwithdisk_space’s reserve left free, or an unsized, uncapped write outgrows that space.
- async classmethod from_raw_store(store, path, *, listing=None)¶
Open
pathfromstorefor a caller that knows it is never enveloped (db/<name>,saas/*/db/saas_{version,snapshot}). Delegates toopen_sqlite: a plainLocalFsStorefile without a non-empty-walopens read-only in place, anything else via a private materialized copy.listing,path’s directory as already listed, answers for the-wal/-shmsidecars with no request (open_sqlite).- Raises:
ResourceLimitExceededError – The materialized copy doesn’t fit in the system temp directory with
disk_space’s reserve left free.
- async classmethod from_enveloped_store(store, path, *, vault_key, tmp_dir=None, what)¶
Read and open
pathfromstore— for a source that may beaHlT-enveloped (copy_meta_file/*/target.db, FORMAT-SPEC.md: Landing directory layout) and may have a real-wal/-shmsidecar. The main file and each sidecar are unwrapped independently, streaming into the temp file, with the decompressed size bounded by_MAX_TARGET_DB_DECOMPRESS_SIZE_FALLBACKasfrom_enveloped_bytesbounds it bymax_output_size.- Parameters:
- Raises:
DataCorruptError – As
from_enveloped_bytes, for the main file or a sidecar (including a missingvault_key).FormatError – As
from_enveloped_bytes.ResourceLimitExceededError – As
from_enveloped_bytes.
- async close()¶
Closes the connection and removes its temp file or directory, the latter even if the close fails or is cancelled. There, a removal Windows refuses while the connection’s thread still holds the file is retried once that thread exits; any other removal failure becomes a note on the close’s error. Safe to call more than once.
- synology_apm_repo.sdk.storage.sqlite_source.close_on_error(source)¶
Closes
sourceif the wrapped block raises, then re-raises, so a caller validating an already-opensourcedoesn’t leak it.