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 db/<name>

raw

copy_meta_file/*/target.db

aHlT? -> raw

version.db.zst

aHlT? -> zstd

saas/*/db/saas_{version,snapshot}

raw

embedded ObjectDB (saas_obj slice)

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: Enum

Which wrapper(s) peel stripped, 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) data actually 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_size is mandatory and only the fallback ceiling for a zstd frame that declares no size (see format.compression.iter_decompressed_zstd); pass None explicitly only for a source already known to be trusted.

Raises:
  • KeyRequiredError – data is aHlT-enveloped but no vault_key was given.

  • DataCorruptError – The aHlT header fails its magic or CRC check, or a zstd frame’s declared content size doesn’t match what decompression produced.

  • FormatError – data has the aHlT magic 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: AsyncClosing

A 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 as async with, or await close() directly. Except for a from_raw_store of a plain LocalFsStore file (opened read-only in place), the content is a private temp copy, removed on close; the copy’s connection is writable (see from_bytes), so the source repository is never modified.

property path: str | None

The temp file’s path for a source built by from_bytes or from_enveloped_bytes, else None. For a caller that must inspect the file’s raw bytes, which no query against connection can express.

async classmethod from_bytes(data)

Materialize plain (post-peel) SQLite data to a private temp file and open a writable connection to it, so apply_index_hint can build an index. close() unlinks the file.

Raises:

ResourceLimitExceededError – data doesn’t fit in the system temp directory with disk_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 for data that may still be aHlT/zstd enveloped (an embedded ObjectDB slice, 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). None with no declared size caps the write at the free space above disk_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 – data matches the zstd/aHlT magic but doesn’t decode, is aHlT-enveloped with no vault_key, or a declared content size doesn’t match what decompression produced.

  • FormatError – data has the aHlT magic but is shorter than its 64-byte header.

  • ResourceLimitExceededError – The declared size (or, absent one, max_output_size) doesn’t fit in tmp_dir with disk_space’s reserve left free, or an unsized, uncapped write outgrows that space.

async classmethod from_raw_store(store, path, *, listing=None)

Open path from store for a caller that knows it is never enveloped (db/<name>, saas/*/db/saas_{version,snapshot}). Delegates to open_sqlite: a plain LocalFsStore file without a non-empty -wal opens read-only in place, anything else via a private materialized copy. listing, path’s directory as already listed, answers for the -wal/-shm sidecars 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 path from store — for a source that may be aHlT-enveloped (copy_meta_file/*/target.db, FORMAT-SPEC.md: Landing directory layout) and may have a real -wal/-shm sidecar. 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_FALLBACK as from_enveloped_bytes bounds it by max_output_size.

Parameters:
  • tmp_dir (str | Path | None) – Directory for the temp file; the system temp directory when omitted.

  • what (str) – Names path in error messages.

Raises:
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 source if the wrapped block raises, then re-raises, so a caller validating an already-open source doesn’t leak it.