Class: Microsandbox::SnapshotInfo

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

Overview

Metadata for a snapshot artifact, returned by Microsandbox::Snapshot.create/Microsandbox::Snapshot.open/ Microsandbox::Snapshot.get/Microsandbox::Snapshot.list/Microsandbox::Snapshot.list_dir/Microsandbox::Snapshot.load.

digest and path are always present. The artifact-opening paths (create/open/list_dir, and Microsandbox::SandboxHandle#snapshot) carry the full descriptor — size_bytes, image_ref, image_manifest_digest, format, fstype, parent_digest, created_at, source_sandbox, and labels. The index paths (get/list/load) populate name, parent_digest, image_ref, format, size_bytes, created_at, and the index-only locality/availability/migration_state columns (descriptor-only fields such as source_sandbox/labels are nil/empty there).

Snapshots come in two state families (see #state_kind): "file" — a concrete disk payload, where #format/#fstype/#size_bytes are set — and "checkpoint" — a manifest-backed state, where those are nil and the checkpoint_* fields are set instead.

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(data) ⇒ SnapshotInfo

Returns a new instance of SnapshotInfo.



56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
 
# File 'lib/microsandbox/snapshot.rb', line 56

def initialize(data)
  @digest = data["digest"]
  @path = data["path"]
  @name = data["name"]
  @parent_digest = data["parent_digest"]
  @image_ref = data["image_ref"]
  @image_manifest_digest = data["image_manifest_digest"]
  @fstype = data["fstype"]
  @source_sandbox = data["source_sandbox"]
  @labels = data["labels"] || {}
  @format = data["format"]
  @size_bytes = data["size_bytes"]
  @created_at_ms = data["created_at_ms"]
  @scope = data["scope"]
  @state_kind = data["state_kind"]
  @checkpoint_id = data["checkpoint_id"]
  @checkpoint_manifest_digest = data["checkpoint_manifest_digest"]
  @locality = data["locality"]
  @availability = data["availability"]
  @migration_state = data["migration_state"]
  @migration_error_code = data["migration_error_code"]
end

Instance Attribute Details

#availability ⇒ String? (readonly)

Returns index availability, normally "ready" (index paths).

Returns:

  • (String, nil) —

    index availability, normally "ready" (index paths)



48
49
50
 
# File 'lib/microsandbox/snapshot.rb', line 48

def availability
  @availability
end

#checkpoint_id ⇒ String? (readonly)

Returns stable checkpoint id (checkpoint state only).

Returns:

  • (String, nil) —

    stable checkpoint id (checkpoint state only)



42
43
44
 
# File 'lib/microsandbox/snapshot.rb', line 42

def checkpoint_id
  @checkpoint_id
end

#checkpoint_manifest_digest ⇒ String? (readonly)

Returns checkpoint-manifest digest (checkpoint state only).

Returns:

  • (String, nil) —

    checkpoint-manifest digest (checkpoint state only)



44
45
46
 
# File 'lib/microsandbox/snapshot.rb', line 44

def checkpoint_manifest_digest
  @checkpoint_manifest_digest
end

#digest ⇒ String (readonly)

Returns descriptor digest ("sha256:…") — the canonical identity.

Returns:

  • (String) —

    descriptor digest ("sha256:…") — the canonical identity



22
23
24
 
# File 'lib/microsandbox/snapshot.rb', line 22

def digest
  @digest
end

#fstype ⇒ String? (readonly)

Returns payload filesystem type, e.g. "ext4" (file state only).

Returns:

  • (String, nil) —

    payload filesystem type, e.g. "ext4" (file state only)



34
35
36
 
# File 'lib/microsandbox/snapshot.rb', line 34

def fstype
  @fstype
end

#image_manifest_digest ⇒ String? (readonly)

Returns OCI manifest digest of the pinned image (descriptor paths).

Returns:

  • (String, nil) —

    OCI manifest digest of the pinned image (descriptor paths)



32
33
34
 
# File 'lib/microsandbox/snapshot.rb', line 32

def image_manifest_digest
  @image_manifest_digest
end

#image_ref ⇒ String? (readonly)

Returns source OCI image reference.

Returns:

  • (String, nil) —

    source OCI image reference



30
31
32
 
# File 'lib/microsandbox/snapshot.rb', line 30

def image_ref
  @image_ref
end

#labels ⇒ Hash{String=>String} (readonly)

Returns user labels ({} for index-only entries).

Returns:

  • (Hash{String=>String}) —

    user labels ({} for index-only entries)



38
39
40
 
# File 'lib/microsandbox/snapshot.rb', line 38

def labels
  @labels
end

#locality ⇒ String? (readonly)

Returns index locality: "embedded" or "linked" (index paths).

Returns:

  • (String, nil) —

    index locality: "embedded" or "linked" (index paths)



46
47
48
 
# File 'lib/microsandbox/snapshot.rb', line 46

def locality
  @locality
end

#migration_error_code ⇒ String? (readonly)

Returns stable failure code when a v0.6.6→v0.6.7 descriptor migration was blocked (index paths).

Returns:

  • (String, nil) —

    stable failure code when a v0.6.6→v0.6.7 descriptor migration was blocked (index paths)



54
55
56
 
# File 'lib/microsandbox/snapshot.rb', line 54

def migration_error_code
  @migration_error_code
end

#migration_state ⇒ String? (readonly)

Returns descriptor-migration state, normally "canonical" ("reverse_complete" after downgrade tooling ran; index paths).

Returns:

  • (String, nil) —

    descriptor-migration state, normally "canonical" ("reverse_complete" after downgrade tooling ran; index paths)



51
52
53
 
# File 'lib/microsandbox/snapshot.rb', line 51

def migration_state
  @migration_state
end

#name ⇒ String? (readonly)

Returns name alias (nil for digest-only entries).

Returns:

  • (String, nil) —

    name alias (nil for digest-only entries)



26
27
28
 
# File 'lib/microsandbox/snapshot.rb', line 26

def name
  @name
end

#parent_digest ⇒ String? (readonly)

Returns parent snapshot digest.

Returns:

  • (String, nil) —

    parent snapshot digest



28
29
30
 
# File 'lib/microsandbox/snapshot.rb', line 28

def parent_digest
  @parent_digest
end

#path ⇒ String (readonly)

Returns artifact directory path.

Returns:

  • (String) —

    artifact directory path



24
25
26
 
# File 'lib/microsandbox/snapshot.rb', line 24

def path
  @path
end

#size_bytes ⇒ Integer? (readonly)

Returns payload size in bytes (nil for checkpoint state).

Returns:

  • (Integer, nil) —

    payload size in bytes (nil for checkpoint state)



40
41
42
 
# File 'lib/microsandbox/snapshot.rb', line 40

def size_bytes
  @size_bytes
end

#source_sandbox ⇒ String? (readonly)

Returns best-effort source-sandbox name, if recorded.

Returns:

  • (String, nil) —

    best-effort source-sandbox name, if recorded



36
37
38
 
# File 'lib/microsandbox/snapshot.rb', line 36

def source_sandbox
  @source_sandbox
end

#state_kind ⇒ String? (readonly)

Returns state family: "file" or "checkpoint".

Returns:

  • (String, nil) —

    state family: "file" or "checkpoint"



91
92
93
 
# File 'lib/microsandbox/snapshot.rb', line 91

def state_kind
  @state_kind
end

Instance Method Details

#created_at ⇒ Time?

Returns:

  • (Time, nil) 


94
95
96
 
# File 'lib/microsandbox/snapshot.rb', line 94

def created_at
  @created_at_ms && Time.at(@created_at_ms / 1000.0)
end

#format ⇒ Symbol?

Returns disk format (:raw or :qcow2; nil for checkpoint state).

Returns:

  • (Symbol, nil) —

    disk format (:raw or :qcow2; nil for checkpoint state)



80
81
82
 
# File 'lib/microsandbox/snapshot.rb', line 80

def format
  @format&.to_sym
end

#inspect ⇒ Object 



113
114
115
 
# File 'lib/microsandbox/snapshot.rb', line 113

def inspect
  "#<Microsandbox::SnapshotInfo digest=#{@digest.inspect}#{" name=#{@name.inspect}" if @name}>"
end

#open ⇒ SnapshotInfo

Re-open this snapshot's artifact (cheap metadata validation), returning a fully-populated Microsandbox::SnapshotInfo. Addresses by path, so it works even for artifacts that were never added to the local index.

Returns:



102
103
104
 
# File 'lib/microsandbox/snapshot.rb', line 102

def open
  Snapshot.open(@path || @digest)
end

#remove(force: false) ⇒ nil

Remove this snapshot's artifact and its index row.

Parameters:

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

    remove even if it has indexed children

Returns:

  • (nil) 


109
110
111
 
# File 'lib/microsandbox/snapshot.rb', line 109

def remove(force: false)
  Snapshot.remove(@path || @digest, force: force)
end

#scope ⇒ Symbol?

Returns payload scope — :disk today, :resumable once VM pause/resume lands upstream.

Returns:

  • (Symbol, nil) —

    payload scope — :disk today, :resumable once VM pause/resume lands upstream



86
87
88
 
# File 'lib/microsandbox/snapshot.rb', line 86

def scope
  @scope&.to_sym
end