Class: Microsandbox::Snapshot

Inherits:
Object
  • Object
show all
Defined in:
lib/microsandbox/snapshot.rb

Overview

Creation and management of sandbox snapshots. A snapshot captures a stopped sandbox's disk state into a portable artifact; boot from it with Sandbox.create(from_snapshot: "name-or-digest").

v0.6.7 descriptor contract: artifacts are identified by their own name and live at dest_dir/<name>; the descriptor file is snapshot.json. Artifacts written by ≤0.10.x gems (manifest.json) are migrated automatically by the runtime on first use — after which older gem versions can no longer read them (downgrade requires the msb self downgrade tooling).

Class Method Summary collapse

Class Method Details

.create(name, from_sandbox:, dest_dir: nil, labels: nil, force: false, record_integrity: false, resumable: false) ⇒ SnapshotInfo

Create a snapshot named name from a stopped sandbox.

Parameters:

  • name (String) —

    the snapshot's own name (its identity)

  • from_sandbox (String) —

    name of the (stopped) source sandbox

  • dest_dir (String, nil) (defaults to: nil) —

    parent directory override — the artifact is written at dest_dir/<name> (default: the snapshots dir)

  • labels (Hash, nil) (defaults to: nil) —

    user labels

  • force (Boolean) (defaults to: false) —

    overwrite an existing artifact at the destination

  • record_integrity (Boolean) (defaults to: false) —

    record persistent payload integrity (a Merkle content digest) in the artifact — opt-in since runtime v0.6.9 because hashing large allocated uppers is expensive; without it verify reports :not_recorded

  • resumable (Boolean) (defaults to: false) —

    request a resumable (memory+device) snapshot; raises UnsupportedError until VM pause/resume lands upstream

Returns:



173
174
175
176
177
178
179
180
181
182
 
# File 'lib/microsandbox/snapshot.rb', line 173

def create(name, from_sandbox:, dest_dir: nil, labels: nil, force: false,
  record_integrity: false, resumable: false)
  opts = {"from_sandbox" => from_sandbox.to_s}
  opts["dest_dir"] = dest_dir.to_s if dest_dir
  opts["labels"] = stringify(labels) if labels
  opts["force"] = true if force
  opts["record_integrity"] = true if record_integrity
  opts["resumable"] = true if resumable
  SnapshotInfo.new(Native::Snapshot.create(name.to_s, opts))
end

.get(name_or_digest) ⇒ SnapshotInfo

Metadata for a snapshot by name or digest.

Returns:



195
196
197
 
# File 'lib/microsandbox/snapshot.rb', line 195

def get(name_or_digest)
  SnapshotInfo.new(Native::Snapshot.get(name_or_digest.to_s))
end

.list ⇒ Array<SnapshotInfo>

All snapshots indexed in the local cache.

Returns:



201
202
203
 
# File 'lib/microsandbox/snapshot.rb', line 201

def list
  Native::Snapshot.list.map { |info| SnapshotInfo.new(info) }
end

.list_dir(dir) ⇒ Array<SnapshotInfo>

Enumerate snapshot artifacts under a directory by parsing each subdirectory's snapshot.json, without touching the local index — for inspecting external/un-imported collections (e.g. a mounted volume).

Returns:



209
210
211
 
# File 'lib/microsandbox/snapshot.rb', line 209

def list_dir(dir)
  Native::Snapshot.list_dir(dir.to_s).map { |info| SnapshotInfo.new(info) }
end

.load(archive_path, dest: nil) ⇒ SnapshotInfo

Unpack a snapshot archive into the snapshots dir. Renamed from import in 0.11.0, mirroring the v0.6.7 SDKs.

Parameters:

  • dest (String, nil) (defaults to: nil) —

    explicit destination directory

Returns:



255
256
257
 
# File 'lib/microsandbox/snapshot.rb', line 255

def load(archive_path, dest: nil)
  SnapshotInfo.new(Native::Snapshot.load(archive_path.to_s, dest&.to_s))
end

.open(name_or_path) ⇒ SnapshotInfo

Open a snapshot artifact by bare name or path (cheap metadata validation; does not read the payload). Unlike get, this also works for artifacts addressed by path that were never indexed, and it returns the full descriptor.

Returns:



189
190
191
 
# File 'lib/microsandbox/snapshot.rb', line 189

def open(name_or_path)
  SnapshotInfo.new(Native::Snapshot.open(name_or_path.to_s))
end

.reindex(dir = nil) ⇒ Integer

Rebuild the local snapshot index from a directory (defaults to the configured snapshots dir). The repair for index drift or out-of-band imports that list/get can't otherwise see.

Parameters:

  • dir (String, nil) (defaults to: nil)

Returns:

  • (Integer) —

    number of indexed snapshots



218
219
220
 
# File 'lib/microsandbox/snapshot.rb', line 218

def reindex(dir = nil)
  Native::Snapshot.reindex(dir&.to_s)
end

.remove(name_or_path, force: false) ⇒ nil

Remove a snapshot artifact by name or path.

Parameters:

  • force (Boolean) (defaults to: false) —

    remove even if referenced

Returns:

  • (nil) 


225
226
227
228
 
# File 'lib/microsandbox/snapshot.rb', line 225

def remove(name_or_path, force: false)
  Native::Snapshot.remove(name_or_path.to_s, force)
  nil
end

.save(name_or_path, out_path, with_parents: false, with_image: false, plain_tar: false) ⇒ nil

Bundle a snapshot into a .tar.zst (or plain .tar) archive. Renamed from export in 0.11.0, mirroring the v0.6.7 SDKs.

Parameters:

  • with_parents (Boolean) (defaults to: false) —

    include ancestor snapshots

  • with_image (Boolean) (defaults to: false) —

    include OCI image artifacts (boots offline)

  • plain_tar (Boolean) (defaults to: false) —

    write an uncompressed .tar

Returns:

  • (nil) 


242
243
244
245
246
247
248
249
 
# File 'lib/microsandbox/snapshot.rb', line 242

def save(name_or_path, out_path, with_parents: false, with_image: false, plain_tar: false)
  opts = {}
  opts["with_parents"] = true if with_parents
  opts["with_image"] = true if with_image
  opts["plain_tar"] = true if plain_tar
  Native::Snapshot.save(name_or_path.to_s, out_path.to_s, opts)
  nil
end

.verify(name_or_path) ⇒ SnapshotVerifyReport

Verify a snapshot's recorded payload integrity.

Returns:



232
233
234
 
# File 'lib/microsandbox/snapshot.rb', line 232

def verify(name_or_path)
  SnapshotVerifyReport.new(Native::Snapshot.verify(name_or_path.to_s))
end