Class: Microsandbox::AgentClient

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

Overview

A low-level **raw agent client** — the byte-level transport to a sandbox’s ‘agentd` over its relay socket. This is the rawest tier of the SDK: it moves CBOR-encoded protocol frames in and out; encoding/decoding the bodies is up to you. Most users want Sandbox#exec/Sandbox#fs instead; reach for this to drive `agentd` protocol features the high-level API does not expose, or to bridge the relay socket to another transport (see AgentClient.socket_path).

Mirrors the ‘AgentClient` in the official Python/Node/Go SDKs.

Examples:

one-shot request/response

Microsandbox::AgentClient.connect_sandbox("my-box") do |client|
  frame = client.request(0, cbor_encoded_request)
  handle(frame.body)
end

Constant Summary collapse

FLAG_TERMINAL =

Frame flag bits (mirror the protocol constants in the other SDKs).

0b0000_0001
FLAG_SESSION_START = 
0b0000_0010
FLAG_SHUTDOWN = 
0b0000_0100

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(native) ⇒ AgentClient

Returns a new instance of AgentClient.



138
139
140
 
# File 'lib/microsandbox/agent.rb', line 138

def initialize(native)
  @native = native
end

Class Method Details

.connect_path(path, timeout: nil, &block) ⇒ AgentClient, Object

Connect to an agentd relay socket by path. See connect_sandbox.

Returns:



112
113
114
 
# File 'lib/microsandbox/agent.rb', line 112

def connect_path(path, timeout: nil, &block)
  wrap(Native::AgentClient.connect_path(path.to_s, timeout && Float(timeout)), &block)
end

.connect_sandbox(name, timeout: nil) {|client| ... } ⇒ AgentClient, Object

Connect to a running sandbox by name (max 128 UTF-8 bytes). With a block, the client is yielded and closed when the block returns.

Parameters:

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

    handshake timeout in seconds (default ~10s)

Yield Parameters:

Returns:



106
107
108
 
# File 'lib/microsandbox/agent.rb', line 106

def connect_sandbox(name, timeout: nil, &block)
  wrap(Native::AgentClient.connect_sandbox(name.to_s, timeout && Float(timeout)), &block)
end

.socket_path(name) ⇒ String

Resolve a sandbox’s agent relay socket path without connecting — the same path connect_sandbox would dial. Useful for bridging the socket to another byte transport. The sandbox need not be running.

Returns:

  • (String) 


120
121
122
 
# File 'lib/microsandbox/agent.rb', line 120

def socket_path(name)
  Native::AgentClient.socket_path(name.to_s)
end

Instance Method Details

#close ⇒ nil

Close the connection. Idempotent.

Returns:

  • (nil) 


176
177
178
179
 
# File 'lib/microsandbox/agent.rb', line 176

def close
  @native.close
  nil
end

#ready_bytes ⇒ String

The cached handshake ‘core.ready` frame body (CBOR bytes).

Returns:

  • (String) 


170
171
172
 
# File 'lib/microsandbox/agent.rb', line 170

def ready_bytes
  @native.ready_bytes
end

#request(flags, body) ⇒ AgentFrame

Send one frame and await a single response frame.

Parameters:

  • flags (Integer) —

    frame flag bits

  • body (String) —

    CBOR-encoded body bytes

Returns:



146
147
148
 
# File 'lib/microsandbox/agent.rb', line 146

def request(flags, body)
  AgentFrame.new(@native.request(Integer(flags), body.to_s))
end

#send_frame(id, flags, body) ⇒ nil

Send a follow-up frame on an existing correlation id (e.g. a stream’s Microsandbox::AgentStream#id). Named send_frame rather than send so it does not shadow Ruby’s ‘Object#send`. Maps to the protocol “send” in the other SDKs.

Returns:

  • (nil) 


163
164
165
166
 
# File 'lib/microsandbox/agent.rb', line 163

def send_frame(id, flags, body)
  @native.send(Integer(id), Integer(flags), body.to_s)
  nil
end

#stream(flags, body) ⇒ AgentStream

Open a streaming session.

Parameters:

  • flags (Integer)
  • body (String)

Returns:



154
155
156
157
 
# File 'lib/microsandbox/agent.rb', line 154

def stream(flags, body)
  opened = @native.stream_open(Integer(flags), body.to_s)
  AgentStream.new(@native, opened["id"], opened["handle"])
end