microsandbox-rb 0.9.2 → 0.11.0

data/lib/microsandbox/snapshot.rb

@@ -2,17 +2,23 @@
 
 module Microsandbox
   # Metadata for a snapshot artifact, returned by {Snapshot.create}/{Snapshot.open}/
-  # {Snapshot.get}/{Snapshot.list}/{Snapshot.list_dir}/{Snapshot.import}.
+  # {Snapshot.get}/{Snapshot.list}/{Snapshot.list_dir}/{Snapshot.load}.
   #
   # `digest` and `path` are always present. The artifact-opening paths
   # (`create`/`open`/`list_dir`, and {SandboxHandle#snapshot}) carry the full
-  # manifest — `size_bytes`, `image_ref`, `image_manifest_digest`, `format`,
+  # descriptor — `size_bytes`, `image_ref`, `image_manifest_digest`, `format`,
   # `fstype`, `parent_digest`, `created_at`, `source_sandbox`, and `labels`. The
-  # index paths (`get`/`list`/`import`) populate `name`, `parent_digest`,
-  # `image_ref`, `format`, `size_bytes`, and `created_at` (manifest-only fields
-  # such as `fstype`/`source_sandbox`/`labels` are nil/empty there).
+  # 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.
   class SnapshotInfo
-    # @return [String] manifest digest ("sha256:…") — the canonical identity
+    # @return [String] descriptor digest ("sha256:…") — the canonical identity
     attr_reader :digest
     # @return [String] artifact directory path
     attr_reader :path
@@ -22,16 +28,30 @@ module Microsandbox
     attr_reader :parent_digest
     # @return [String, nil] source OCI image reference
     attr_reader :image_ref
-    # @return [String, nil] OCI manifest digest of the pinned image (manifest paths)
+    # @return [String, nil] OCI manifest digest of the pinned image (descriptor paths)
     attr_reader :image_manifest_digest
-    # @return [String, nil] upper-layer filesystem type, e.g. "ext4" (manifest paths)
+    # @return [String, nil] payload filesystem type, e.g. "ext4" (file state only)
     attr_reader :fstype
     # @return [String, nil] best-effort source-sandbox name, if recorded
     attr_reader :source_sandbox
     # @return [Hash{String=>String}] user labels ({} for index-only entries)
     attr_reader :labels
-    # @return [Integer, nil] artifact size in bytes
+    # @return [Integer, nil] payload size in bytes (nil for checkpoint state)
     attr_reader :size_bytes
+    # @return [String, nil] stable checkpoint id (checkpoint state only)
+    attr_reader :checkpoint_id
+    # @return [String, nil] checkpoint-manifest digest (checkpoint state only)
+    attr_reader :checkpoint_manifest_digest
+    # @return [String, nil] index locality: "embedded" or "linked" (index paths)
+    attr_reader :locality
+    # @return [String, nil] index availability, normally "ready" (index paths)
+    attr_reader :availability
+    # @return [String, nil] descriptor-migration state, normally "canonical"
+    #   ("reverse_complete" after downgrade tooling ran; index paths)
+    attr_reader :migration_state
+    # @return [String, nil] stable failure code when a v0.6.6→v0.6.7 descriptor
+    #   migration was blocked (index paths)
+    attr_reader :migration_error_code
 
     def initialize(data)
       @digest = data["digest"]
@@ -46,13 +66,30 @@ module Microsandbox
       @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
 
-    # @return [Symbol, nil] disk format (:raw or :qcow2)
+    # @return [Symbol, nil] disk format (:raw or :qcow2; nil for checkpoint state)
     def format
       @format&.to_sym
     end
 
+    # @return [Symbol, nil] payload scope — :disk today, :resumable once VM
+    #   pause/resume lands upstream
+    def scope
+      @scope&.to_sym
+    end
+
+    # @return [String, nil] state family: "file" or "checkpoint"
+    attr_reader :state_kind
+
     # @return [Time, nil]
     def created_at
       @created_at_ms && Time.at(@created_at_ms / 1000.0)
@@ -78,17 +115,19 @@ module Microsandbox
     end
   end
 
-  # The result of {Snapshot.verify}.
+  # The result of {Snapshot.verify}. Schema-1 descriptors always record
+  # integrity, so a returned report is always `:verified` — an integrity
+  # mismatch raises {SnapshotIntegrityError} instead of returning.
   class SnapshotVerifyReport
-    # @return [String] manifest digest
+    # @return [String] descriptor digest
     attr_reader :digest
     # @return [String] artifact directory path
     attr_reader :path
-    # @return [Symbol] :not_recorded or :verified
+    # @return [Symbol] :verified
     attr_reader :status
-    # @return [String, nil] digest algorithm (when :verified)
+    # @return [String] digest algorithm
     attr_reader :algorithm
-    # @return [String, nil] matched content digest (when :verified)
+    # @return [String] matched content digest
     attr_reader :content_digest
 
     def initialize(data)
@@ -101,38 +140,47 @@ module Microsandbox
 
     # @return [Boolean] whether content integrity was recorded and matched
     def verified? = @status == :verified
-    # @return [Boolean] whether no integrity descriptor was recorded
-    def not_recorded? = @status == :not_recorded
   end
 
   # Creation and management of sandbox snapshots. A snapshot captures a stopped
-  # sandbox's upper layer into a portable artifact; boot from it with
+  # 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 Snapshot
     class << self
-      # Create a snapshot of a stopped sandbox.
+      # Create a snapshot named `name` from a stopped sandbox.
       #
-      # @param source_sandbox [String] name of the (stopped) source sandbox
-      # @param name [String, nil] destination name under the snapshots dir
-      # @param path [String, nil] explicit destination directory (alternative to name)
+      # @param name [String] the snapshot's own name (its identity)
+      # @param from_sandbox [String] name of the (stopped) source sandbox
+      # @param dest_dir [String, nil] parent directory override — the artifact
+      #   is written at `dest_dir/<name>` (default: the snapshots dir)
       # @param labels [Hash, nil] user labels
       # @param force [Boolean] overwrite an existing artifact at the destination
-      # @param record_integrity [Boolean] compute + record upper-layer integrity
+      # @param record_integrity [Boolean] accepted for compatibility; schema-1
+      #   descriptors always record integrity, so this is a no-op
+      # @param resumable [Boolean] request a resumable (memory+device) snapshot;
+      #   raises {UnsupportedError} until VM pause/resume lands upstream
       # @return [SnapshotInfo]
-      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
+      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
-        SnapshotInfo.new(Native::Snapshot.create(source_sandbox.to_s, opts))
+        opts["resumable"] = true if resumable
+        SnapshotInfo.new(Native::Snapshot.create(name.to_s, opts))
       end
 
       # Open a snapshot artifact by bare name or path (cheap metadata
-      # validation; does not read the upper layer). Unlike {get}, this also
+      # 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 manifest.
+      # returns the full descriptor.
       # @return [SnapshotInfo]
       def open(name_or_path)
         SnapshotInfo.new(Native::Snapshot.open(name_or_path.to_s))
@@ -151,7 +199,7 @@ module Microsandbox
       end
 
       # Enumerate snapshot artifacts under a directory by parsing each
-      # subdirectory's `manifest.json`, without touching the local index — for
+      # subdirectory's `snapshot.json`, without touching the local index — for
       # inspecting external/un-imported collections (e.g. a mounted volume).
       # @return [Array<SnapshotInfo>]
       def list_dir(dir)
@@ -175,31 +223,33 @@ module Microsandbox
         nil
       end
 
-      # Verify a snapshot's recorded upper-layer integrity.
+      # Verify a snapshot's recorded payload integrity.
       # @return [SnapshotVerifyReport]
       def verify(name_or_path)
         SnapshotVerifyReport.new(Native::Snapshot.verify(name_or_path.to_s))
       end
 
       # Bundle a snapshot into a `.tar.zst` (or plain `.tar`) archive.
+      # Renamed from `export` in 0.11.0, mirroring the v0.6.7 SDKs.
       # @param with_parents [Boolean] include ancestor snapshots
       # @param with_image [Boolean] include OCI image artifacts (boots offline)
       # @param plain_tar [Boolean] write an uncompressed `.tar`
       # @return [nil]
-      def export(name_or_path, out_path, with_parents: false, with_image: false, plain_tar: false)
+      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.export(name_or_path.to_s, out_path.to_s, opts)
+        Native::Snapshot.save(name_or_path.to_s, out_path.to_s, opts)
         nil
       end
 
-      # Unpack a snapshot archive into the snapshots dir.
+      # Unpack a snapshot archive into the snapshots dir. Renamed from
+      # `import` in 0.11.0, mirroring the v0.6.7 SDKs.
       # @param dest [String, nil] explicit destination directory
       # @return [SnapshotInfo]
-      def import(archive_path, dest: nil)
-        SnapshotInfo.new(Native::Snapshot.import(archive_path.to_s, dest&.to_s))
+      def load(archive_path, dest: nil)
+        SnapshotInfo.new(Native::Snapshot.load(archive_path.to_s, dest&.to_s))
       end
 
       private

data/lib/microsandbox/version.rb

@@ -8,12 +8,12 @@ module Microsandbox
   # Versioning section of the README for the full gem-to-runtime map. Must equal
   # the native ext's Cargo crate version (`Native.version`), enforced by
   # spec/unit/version_spec.rb.
-  VERSION = "0.9.2"
+  VERSION = "0.11.0"
 
   # The upstream microsandbox runtime release this gem build embeds — the `tag`
   # pinned on the `microsandbox`/`microsandbox-network` git deps in
   # ext/microsandbox/Cargo.toml. Exposed at runtime as
   # {Microsandbox.runtime_version}. spec/unit/version_spec.rb asserts it stays in
   # sync with the Cargo tag so it can't silently drift out of date.
-  RUNTIME_VERSION = "v0.6.3"
+  RUNTIME_VERSION = "v0.6.7"
 end

data/lib/microsandbox.rb

@@ -27,9 +27,11 @@ require_relative "microsandbox/image"
 require_relative "microsandbox/volume"
 require_relative "microsandbox/snapshot"
 require_relative "microsandbox/patch"
+require_relative "microsandbox/root_disk"
 require_relative "microsandbox/network"
 require_relative "microsandbox/agent"
 require_relative "microsandbox/ssh"
+require_relative "microsandbox/modification"
 require_relative "microsandbox/sandbox"
 
 # Microsandbox — lightweight microVM sandboxes for Ruby.

data/sig/microsandbox.rbs

@@ -52,6 +52,7 @@ module Microsandbox
   class SnapshotSandboxRunningError < Error end
   class SnapshotImageMissingError < Error end
   class SnapshotIntegrityError < Error end
+  class SnapshotMigrationError < Error end
   class NetworkPolicyError < Error end
   class SecretViolationError < Error end
   class TlsError < Error end
@@ -173,7 +174,14 @@ module Microsandbox
     def config_json: () -> String
     def config: () -> Hash[String, untyped]
     def snapshot: (String name) -> SnapshotInfo
-    def snapshot_to: (String path) -> SnapshotInfo
+    def ping: () -> PingResult
+    def touch: () -> TouchResult
+    def modify: (?cpus: Integer?, ?max_cpus: Integer?, ?memory: Integer?, ?max_memory: Integer?,
+                 ?env: Hash[untyped, untyped]?, ?remove_env: Array[String]?,
+                 ?labels: Hash[untyped, untyped]?, ?remove_labels: Array[String]?,
+                 ?workdir: String?, ?secrets: Hash[untyped, untyped]?,
+                 ?remove_secrets: Array[String]?, ?policy: (Symbol | String)?,
+                 ?dry_run: bool) -> ModificationPlan
   end
 
   # Deprecated alias for SandboxHandle (was a read-only metadata type pre-v0.5.8).
@@ -190,8 +198,34 @@ module Microsandbox
     def observed_at: () -> Time
   end
 
+  class PingResult
+    def initialize: (Hash[String, untyped] data) -> void
+    def name: () -> String
+    def latency: () -> Float
+    def latency_ms: () -> Float
+  end
+
+  class TouchResult
+    def initialize: (Hash[String, untyped] data) -> void
+    def name: () -> String
+    def activity_seq: () -> Integer
+  end
+
+  class ModificationPlan
+    def initialize: (Hash[String, untyped] data) -> void
+    def sandbox: () -> String
+    def status: () -> String
+    def policy: () -> Symbol
+    def applied?: () -> bool
+    def changes: () -> Array[Hash[Symbol, untyped]]
+    def conflicts: () -> Array[Hash[Symbol, untyped]]
+    def warnings: () -> Array[Hash[Symbol, untyped]]
+    def resize_status: () -> Array[Hash[Symbol, untyped]]
+  end
+
   class Sandbox
-    def self.create: (String name, ?image: String?, ?cpus: Integer?, ?memory: Integer?,
+    def self.create: (String name, ?image: String?, ?cpus: Integer?, ?max_cpus: Integer?,
+                      ?memory: Integer?, ?max_memory: Integer?,
                       ?env: Hash[untyped, untyped]?, ?workdir: String?, ?shell: String?,
                       ?user: String?, ?hostname: String?, ?labels: Hash[untyped, untyped]?,
                       ?scripts: Hash[untyped, untyped]?, ?entrypoint: Array[String]?,
@@ -203,6 +237,7 @@ module Microsandbox
                       ?patches: Array[Hash[untyped, untyped]]?, ?from_snapshot: String?,
                       ?fstype: String?, ?init: (String | Symbol | Hash[untyped, untyped])?, ?ephemeral: bool,
                       ?log_level: (String | Symbol)?, ?quiet_logs: bool, ?security: (String | Symbol)?,
+                      ?root_disk: (Integer | Hash[untyped, untyped])?,
                       ?oci_upper_size: Integer?, ?max_duration: Integer?, ?idle_timeout: Integer?,
                       ?rlimits: Hash[untyped, untyped]?, ?pull_policy: (String | Symbol)?,
                       ?registry_auth: Hash[untyped, untyped]?, ?registry_insecure: bool,
@@ -238,6 +273,14 @@ module Microsandbox
     def fs: () -> FS
     def ssh: () -> SshOps
     def metrics: () -> Metrics
+    def ping: () -> PingResult
+    def touch: () -> TouchResult
+    def modify: (?cpus: Integer?, ?max_cpus: Integer?, ?memory: Integer?, ?max_memory: Integer?,
+                 ?env: Hash[untyped, untyped]?, ?remove_env: Array[String]?,
+                 ?labels: Hash[untyped, untyped]?, ?remove_labels: Array[String]?,
+                 ?workdir: String?, ?secrets: Hash[untyped, untyped]?,
+                 ?remove_secrets: Array[String]?, ?policy: (Symbol | String)?,
+                 ?dry_run: bool) -> ModificationPlan
     def logs: (?tail: Integer?, ?since_ms: Numeric?, ?until_ms: Numeric?,
                ?sources: Array[String | Symbol]?) -> Array[LogEntry]
     def metrics_stream: (?interval: Numeric) -> MetricsStream
@@ -344,6 +387,9 @@ module Microsandbox
     def self.inspect: (?String? reference) -> (ImageDetail | String)
     def self.remove: (String reference, ?force: bool) -> nil
     def self.prune: () -> ImagePruneReport
+    def self.load: (String input_path, ?tag: (String | Array[String])?) -> Array[ImageInfo]
+    def self.save: ((String | Array[String]) reference, output_path: String,
+                    ?format: (String | Symbol)) -> nil
   end
 
   class VolumeInfo
@@ -396,6 +442,14 @@ module Microsandbox
     def labels: () -> Hash[String, String]
     def size_bytes: () -> Integer?
     def format: () -> Symbol?
+    def scope: () -> Symbol?
+    def state_kind: () -> String?
+    def checkpoint_id: () -> String?
+    def checkpoint_manifest_digest: () -> String?
+    def locality: () -> String?
+    def availability: () -> String?
+    def migration_state: () -> String?
+    def migration_error_code: () -> String?
     def created_at: () -> Time?
     def open: () -> SnapshotInfo
     def remove: (?force: bool) -> nil
@@ -405,15 +459,15 @@ module Microsandbox
     def digest: () -> String
     def path: () -> String
     def status: () -> Symbol
-    def algorithm: () -> String?
-    def content_digest: () -> String?
+    def algorithm: () -> String
+    def content_digest: () -> String
     def verified?: () -> bool
-    def not_recorded?: () -> bool
   end
 
   class Snapshot
-    def self.create: (String source_sandbox, ?name: String?, ?path: String?,
-                      ?labels: Hash[untyped, untyped]?, ?force: bool, ?record_integrity: bool) -> SnapshotInfo
+    def self.create: (String name, from_sandbox: String, ?dest_dir: String?,
+                      ?labels: Hash[untyped, untyped]?, ?force: bool, ?record_integrity: bool,
+                      ?resumable: bool) -> SnapshotInfo
     def self.open: (String name_or_path) -> SnapshotInfo
     def self.get: (String name_or_digest) -> SnapshotInfo
     def self.list: () -> Array[SnapshotInfo]
@@ -421,9 +475,9 @@ module Microsandbox
     def self.reindex: (?String? dir) -> Integer
     def self.remove: (String name_or_path, ?force: bool) -> nil
     def self.verify: (String name_or_path) -> SnapshotVerifyReport
-    def self.export: (String name_or_path, String out_path, ?with_parents: bool,
-                      ?with_image: bool, ?plain_tar: bool) -> nil
-    def self.import: (String archive_path, ?dest: String?) -> SnapshotInfo
+    def self.save: (String name_or_path, String out_path, ?with_parents: bool,
+                    ?with_image: bool, ?plain_tar: bool) -> nil
+    def self.load: (String archive_path, ?dest: String?) -> SnapshotInfo
   end
 
   module Patch
@@ -453,14 +507,23 @@ module Microsandbox
     def self.deny: (?destination: untyped?, ?direction: (String | Symbol),
                     ?protocol: (String | Symbol)?, ?protocols: Array[String | Symbol]?,
                     ?port: (String | Integer)?, ?ports: Array[String | Integer]?) -> Hash[String, untyped]
+    def self.allow_dns: () -> Hash[String, untyped]
+    def self.deny_dns: () -> Hash[String, untyped]
+  end
+
+  module RootDisk
+    def self.managed: (?Integer? size_mib) -> Hash[String, untyped]
+    def self.tmpfs: (?Integer? size_mib) -> Hash[String, untyped]
+    def self.disk: (String path, ?format: (String | Symbol)?, ?fstype: String?) -> Hash[String, untyped]
   end
 
   class NetworkPolicy
+    PROFILES: Array[String]
     PRESET_ALIASES: Hash[String, String]
-    def self.public_only: () -> NetworkPolicy
+    REMOVED_PRESETS: Hash[String, String]
+    def self.from_profiles: (*(String | Symbol) profiles) -> NetworkPolicy
     def self.none: () -> NetworkPolicy
     def self.allow_all: () -> NetworkPolicy
-    def self.non_local: () -> NetworkPolicy
     def self.preset: ((String | Symbol) name) -> NetworkPolicy
     def self.custom: (?default_egress: (String | Symbol)?, ?default_ingress: (String | Symbol)?,
                       ?rules: Array[Hash[untyped, untyped]], ?deny_domains: Array[String],

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: microsandbox-rb
 version: !ruby/object:Gem::Version
-  version: 0.9.2
+  version: 0.11.0
 platform: ruby
 authors:
 - ya-luotao
@@ -68,8 +68,10 @@ files:
 - lib/microsandbox/image.rb
 - lib/microsandbox/log_entry.rb
 - lib/microsandbox/metrics.rb
+- lib/microsandbox/modification.rb
 - lib/microsandbox/network.rb
 - lib/microsandbox/patch.rb
+- lib/microsandbox/root_disk.rb
 - lib/microsandbox/sandbox.rb
 - lib/microsandbox/snapshot.rb
 - lib/microsandbox/ssh.rb