Class: Microsandbox::SandboxHandle

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

Overview

A controllable handle to a sandbox, returned by Microsandbox::Sandbox.get, Microsandbox::Sandbox.list, and Microsandbox::Sandbox.list_with. Carries a metadata snapshot (captured when fetched) plus the fine-grained lifecycle surface — stop_with_timeout, request_stop, request_kill, request_drain, wait_until_stopped — that mirrors the official SDKs' SandboxHandle. (The live Sandbox from Microsandbox::Sandbox.create/ Microsandbox::Sandbox.start carries only the high-level stop/kill/drain/wait.)

As of v0.5.8 this replaces the old read-only SandboxInfo (kept as a deprecated constant alias); #status here is a synchronous snapshot.

Instance Method Summary collapse

Constructor Details

#initialize(native) ⇒ SandboxHandle

Returns a new instance of SandboxHandle.



16
17
18
 
# File 'lib/microsandbox/sandbox.rb', line 16

def initialize(native)
  @native = native
end

Instance Method Details

#config ⇒ Hash

The sandbox's stored configuration, parsed into a Hash (image, cpus, memory, mounts, …). Mirrors the Python/Node config.

Returns:

  • (Hash) 


115
116
117
 
# File 'lib/microsandbox/sandbox.rb', line 115

def config
  JSON.parse(@native.config_json)
end

#config_json ⇒ String

The sandbox's stored configuration as a raw JSON string (synchronous — the handle already carries it, no runtime round-trip). Mirrors the Python/Node config_json.

Returns:

  • (String) 


108
109
110
 
# File 'lib/microsandbox/sandbox.rb', line 108

def config_json
  @native.config_json
end

#created_at ⇒ Time?

Returns:

  • (Time, nil) 


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

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

#inspect ⇒ Object 



135
136
137
 
# File 'lib/microsandbox/sandbox.rb', line 135

def inspect
  "#<Microsandbox::SandboxHandle name=#{name.inspect} status=#{status}>"
end

#kill ⇒ nil

Force-kill the sandbox (SIGKILL).

Returns:

  • (nil) 


63
64
65
66
 
# File 'lib/microsandbox/sandbox.rb', line 63

def kill
  @native.kill
  nil
end

#kill_with_timeout(timeout) ⇒ nil

Force-kill, waiting up to timeout seconds for the process to disappear.

Parameters:

  • timeout (Numeric)

Returns:

  • (nil) 


71
72
73
74
 
# File 'lib/microsandbox/sandbox.rb', line 71

def kill_with_timeout(timeout)
  @native.kill_with_timeout(Sandbox.send(:coerce_duration, timeout, "timeout"))
  nil
end

#name ⇒ String

Returns:

  • (String) 


21
 
# File 'lib/microsandbox/sandbox.rb', line 21

def name = @native.name

#request_drain ⇒ nil

Request a graceful drain (SIGUSR1) and return immediately, without waiting.

Returns:

  • (nil) 


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

def request_drain
  @native.request_drain
  nil
end

#request_kill ⇒ nil

Send the force-kill request and return immediately, without waiting.

Returns:

  • (nil) 


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

def request_kill
  @native.request_kill
  nil
end

#request_stop ⇒ nil

Send the graceful-shutdown request and return immediately, without waiting. Pair with #wait_until_stopped.

Returns:

  • (nil) 


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

def request_stop
  @native.request_stop
  nil
end

#running? ⇒ Boolean

Whether the fetch-time #status snapshot is :running / :stopped. Like #status, these do NOT refresh: to observe a state change after #request_stop/#request_kill/#request_drain, use #wait_until_stopped or re-fetch the handle with Microsandbox::Sandbox.get.

Returns:

  • (Boolean) 


31
 
# File 'lib/microsandbox/sandbox.rb', line 31

def running? = status == :running

#snapshot(name) ⇒ SnapshotInfo

Snapshot this (stopped) sandbox under a bare name, resolved under the snapshots dir. Convenience equivalent of Snapshot.create(name, name: <snapshot-name>) addressed by this handle.

Parameters:

  • name (String) —

    destination snapshot name

Returns:



124
125
126
 
# File 'lib/microsandbox/sandbox.rb', line 124

def snapshot(name)
  SnapshotInfo.new(@native.snapshot(name.to_s))
end

#snapshot_to(path) ⇒ SnapshotInfo

Snapshot this (stopped) sandbox to an explicit filesystem path.

Parameters:

  • path (String) —

    destination directory

Returns:



131
132
133
 
# File 'lib/microsandbox/sandbox.rb', line 131

def snapshot_to(path)
  SnapshotInfo.new(@native.snapshot_to(path.to_s))
end

#status ⇒ Symbol

Returns :created, :starting, :running, :draining, :paused, :stopped, or :crashed (a snapshot, captured when this handle was fetched).

Returns:

  • (Symbol) —

    :created, :starting, :running, :draining, :paused, :stopped, or :crashed (a snapshot, captured when this handle was fetched)



25
 
# File 'lib/microsandbox/sandbox.rb', line 25

def status = @native.status.to_sym

#stop ⇒ nil

Gracefully stop the sandbox (SIGTERM→SIGKILL escalation, 10s default).

Returns:

  • (nil) 


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

def stop
  @native.stop
  nil
end

#stop_with_timeout(timeout) ⇒ nil

Gracefully stop with a custom escalation timeout.

Parameters:

  • timeout (Numeric) —

    seconds to wait before escalating to SIGKILL

Returns:

  • (nil) 


56
57
58
59
 
# File 'lib/microsandbox/sandbox.rb', line 56

def stop_with_timeout(timeout)
  @native.stop_with_timeout(Sandbox.send(:coerce_duration, timeout, "timeout"))
  nil
end

#stopped? ⇒ Boolean

Returns:

  • (Boolean) 


32
 
# File 'lib/microsandbox/sandbox.rb', line 32

def stopped? = status == :stopped

#updated_at ⇒ Time?

Returns:

  • (Time, nil) 


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

def updated_at
  ms = @native.updated_at_ms
  ms && Time.at(ms / 1000.0)
end

#wait_until_stopped ⇒ SandboxStopResult

Block until the sandbox is observed in a terminal (non-running) state.

Returns:



100
101
102
 
# File 'lib/microsandbox/sandbox.rb', line 100

def wait_until_stopped
  SandboxStopResult.new(@native.wait_until_stopped)
end