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.



144
145
146
 
# File 'lib/microsandbox/agent.rb', line 144

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:



118
119
120
 
# File 'lib/microsandbox/agent.rb', line 118

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. nil (the default) uses the core default (~10s); 0 fails fast (an immediate deadline); a negative or non-finite value raises Error.

Yield Parameters:

Returns:



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

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) 


126
127
128
 
# File 'lib/microsandbox/agent.rb', line 126

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

Instance Method Details

#close ⇒ nil

Close the connection. Idempotent.

Returns:

  • (nil) 


182
183
184
185
 
# File 'lib/microsandbox/agent.rb', line 182

def close
  @native.close
  nil
end

#ready_bytes ⇒ String

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

Returns:

  • (String) 


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

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:



152
153
154
 
# File 'lib/microsandbox/agent.rb', line 152

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) 


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

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:



160
161
162
163
 
# File 'lib/microsandbox/agent.rb', line 160

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