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 upper layer into a portable artifact; boot from it with ‘Sandbox.create(from_snapshot: “name-or-digest”)`.

Class Method Summary collapse

Class Method Details

.create(source_sandbox, name: nil, path: nil, labels: nil, force: false, record_integrity: false) ⇒ SnapshotInfo

Create a snapshot of a stopped sandbox.

Parameters:

  • source_sandbox (String) —

    name of the (stopped) source sandbox

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

    destination name under the snapshots dir

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

    explicit destination directory (alternative to name)

  • 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) —

    compute + record upper-layer integrity

Returns:



122
123
124
125
126
127
128
129
130
 
# File 'lib/microsandbox/snapshot.rb', line 122

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

.export(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.

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) 


189
190
191
192
193
194
195
196
 
# File 'lib/microsandbox/snapshot.rb', line 189

def export(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.export(name_or_path.to_s, out_path.to_s, opts)
  nil
end

.get(name_or_digest) ⇒ SnapshotInfo

Metadata for a snapshot by name or digest.

Returns:



143
144
145
 
# File 'lib/microsandbox/snapshot.rb', line 143

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

.import(archive_path, dest: nil) ⇒ SnapshotInfo

Unpack a snapshot archive into the snapshots dir.

Parameters:

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

    explicit destination directory

Returns:



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

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

.list ⇒ Array<SnapshotInfo>

All snapshots indexed in the local cache.

Returns:



149
150
151
 
# File 'lib/microsandbox/snapshot.rb', line 149

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 ‘manifest.json`, without touching the local index — for inspecting external/un-imported collections (e.g. a mounted volume).

Returns:



157
158
159
 
# File 'lib/microsandbox/snapshot.rb', line 157

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

.open(name_or_path) ⇒ SnapshotInfo

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

Returns:



137
138
139
 
# File 'lib/microsandbox/snapshot.rb', line 137

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



166
167
168
 
# File 'lib/microsandbox/snapshot.rb', line 166

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) 


173
174
175
176
 
# File 'lib/microsandbox/snapshot.rb', line 173

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

.verify(name_or_path) ⇒ SnapshotVerifyReport

Verify a snapshot’s recorded upper-layer integrity.

Returns:



180
181
182
 
# File 'lib/microsandbox/snapshot.rb', line 180

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