synology_apm_repo.sdk.units.saas.stream module

SaasStream: the browsing layer shared by every SaaS workload.

A “stream” is saas/<connection_config_id>/<streamUuid>/ — its own db/{saas_snapshot,saas_version} (plain SQLite, never aHlT- enveloped even on an encrypted repository, unlike copy_meta_file’s per-file envelope) track snapshots (one per distinct backup job) and versions (one per run of that job) independently of db/copy_target_version.

A catalog Version carries no key directly usable against file_map; resolving it to the actual saas_obj means two SQLite lookups (SaasStream.stream_version_for) followed by a file_map path with an ambiguous middle segment (SaasStream.open_saas_obj).

stream_version is a monotonically increasing per-stream generation counter; several catalog Version rows can share one. It records which generation a version was written into, not where its content lives now: a later generation’s composition record is a superset of an earlier one’s, and older generations are garbage-collected server-side (FORMAT-SPEC.md: Generic SaaS object addressing). So a missing generation is routine rotation, and resolve_saas_obj forward-resolves to the nearest later live generation, bounded by stream_info.latest_complete_version.

Callers go through SaasStreamCache, which shares one SaasStream (and its resolution caches) per stream.

class synology_apm_repo.sdk.units.saas.stream.ResolvedSaasObj(dedup_file, requested_stream_version, stream_version)

Bases: object

A version’s opened saas_obj and which generation was read.

Variables:
  • dedup_file (synology_apm_repo.sdk.dedup.dedup_file.DedupFile) – The opened saas_obj.

  • requested_stream_version (int) – The version’s own recorded stream_version.

  • stream_version (int) – The generation actually read: requested_stream_version or a later one, when routine rotation removed it.

dedup_file: DedupFile
requested_stream_version: int
stream_version: int
class synology_apm_repo.sdk.units.saas.stream.SaasStream(repo, connection_config_id, stream_uuid)

Bases: AsyncClosing

async close()

Close every SQLite connection this instance opened, including one still being opened when this is called; open none afterwards.

async stream_version_for(version)

Resolve a catalog Version’s (saas_snapshot_uuid, saas_version_id) to its recorded stream_version, via snapshot_info then version_info.

Raises:

NotFoundError – Either lookup has no row, or a db file is missing or unreadable.

async open_saas_obj(version)

resolve_saas_obj(version)’s file.

async resolve_saas_obj(version)

Locate and open this catalog Version’s saas_obj.

Reads the nearest live generation at or after version’s recorded stream_version (see the module docstring).

Raises:

NotFoundError – stream_version_for fails, or no live generation exists from that stream_version through stream_info.latest_complete_version (a genuine gap; ref names the originally-requested path).

class synology_apm_repo.sdk.units.saas.stream.SaasStreamCache(repo, *, maxsize=8)

Bases: AsyncClosing

One SaasStream per (connection_config_id, saas_stream_uuid), shared by every version of that stream so its resolution caches pay off. SaaS providers borrow streams from it and never close them.

Holds at most maxsize streams, evicting the least recently used one not in use (see _stream_for). invalidate() (the saas_streams cache-invalidation hook) closes every stream and keeps serving; close() also refuses every later lookup.

Raises:

ValueError – maxsize is less than 1.

cache_stats()

Counters of the stream LRU, keyed saas_streams.

async open_saas_obj(version)

resolve_saas_obj(version)’s file.

async resolve_saas_obj(version)

version’s saas_obj via its stream’s shared SaasStream; see SaasStream.resolve_saas_obj for semantics and errors.

async invalidate()

Close and drop every stream; the next lookup builds a fresh one.

async close()

invalidate(), then refuse every later lookup.