Module: Kobako::RPC::Dispatcher

Defined in:
lib/kobako/rpc/dispatcher.rb

Overview

Pure-function dispatcher for guest-initiated RPC calls. Decodes a msgpack-encoded Request envelope, resolves the target object through the Server (path lookup or HandleTable lookup), invokes the method, and returns a msgpack-encoded Response envelope.

The module is stateless — all mutable state is threaded through the server argument so Dispatcher has no instance variables and no side effects beyond mutating the HandleTable via alloc when a non-wire- representable return value must be wrapped (SPEC.md B-14).

Entry point:

Kobako::RPC::Dispatcher.dispatch(request_bytes, server)
# => msgpack-encoded Response bytes (never raises)

Defined Under Namespace

Classes: DisconnectedTargetError, UndefinedTargetError

Class Method Summary collapse

Class Method Details

.dispatch(request_bytes, server) ⇒ Object

Dispatch a single RPC request and return the encoded response bytes. Called by Kobako::RPC::Server#dispatch which is invoked from the Rust ext inside __kobako_dispatch. request_bytes is the msgpack-encoded Request envelope. server is the live Server for this run, used to resolve path-based targets via #lookup and to access the #handle_table for Handle-based targets and return-value wrapping. Always returns a binary String — never raises. Any failure during decode, lookup, or method invocation is reified as a Response.error envelope so the guest sees the failure as a normal RPC error rather than a wasm trap (SPEC.md B-12).



45
46
47
48
49
50
51
52
53
54
55
 
# File 'lib/kobako/rpc/dispatcher.rb', line 45

def dispatch(request_bytes, server)
  request = Kobako::RPC.decode_request(request_bytes)
  handle_table = server.handle_table
  target = resolve_target(request.target, server, handle_table)
  args = request.args.map { |v| resolve_arg(v, handle_table) }
  kwargs = request.kwargs.transform_values { |v| resolve_arg(v, handle_table) }
  value = invoke(target, request.method_name, args, kwargs)
  encode_ok(value, server)
rescue StandardError => e
  encode_caught_error(e)
end

.encode_caught_error(error) ⇒ Object

Map an error caught at the dispatch boundary to a Response.error envelope. error is the StandardError caught by #dispatch‘s rescue. Returns a msgpack-encoded Response envelope (binary). Four error buckets (SPEC.md B-12): Kobako::Codec::Error → type=“runtime” (wire decode failed); DisconnectedTargetError → type=“disconnected” (E-14); UndefinedTargetError → type=“undefined” (E-13); ArgumentError →type=“argument” (B-12 arity mismatch); everything else →type=“runtime”.



66
67
68
69
70
71
72
73
74
 
# File 'lib/kobako/rpc/dispatcher.rb', line 66

def encode_caught_error(error)
  case error
  when Kobako::Codec::Error then encode_error("runtime", "wire decode failed: #{error.message}")
  when DisconnectedTargetError then encode_error("disconnected", error.message)
  when UndefinedTargetError    then encode_error("undefined", error.message)
  when ArgumentError           then encode_error("argument", error.message)
  else                              encode_error("runtime", "#{error.class}: #{error.message}")
  end
end

.encode_error(type, message) ⇒ Object 



162
163
164
165
166
 
# File 'lib/kobako/rpc/dispatcher.rb', line 162

def encode_error(type, message)
  fault = Kobako::RPC::Fault.new(type: type, message: message)
  response = Kobako::RPC::Response.error(fault)
  Kobako::RPC.encode_response(response)
end

.encode_ok(value, server) ⇒ Object

Encode value as a Response.ok envelope. When the value is not wire-representable per B-13[link:../../../SPEC.md]‘s type mapping, the UnsupportedType rescue routes it through the HandleTable via #wrap_as_handle and re-encodes with the Capability Handle in place (SPEC.md B-14). The happy path encodes exactly once.



147
148
149
150
151
152
 
# File 'lib/kobako/rpc/dispatcher.rb', line 147

def encode_ok(value, server)
  response = Kobako::RPC::Response.ok(value)
  Kobako::RPC.encode_response(response)
rescue Kobako::Codec::UnsupportedType
  encode_ok(wrap_as_handle(value, server), server)
end

.invoke(target, method, args, kwargs) ⇒ Object

Dispatch method on target. kwargs is already Symbol-keyed (the Envelope::Request invariant pins it). The empty-kwargs branch omits the ** splat so Ruby 3.x’s strict kwargs separation does not reject calls to no-kwarg methods when the wire carries the uniform empty-map shape.



81
82
83
84
85
86
87
 
# File 'lib/kobako/rpc/dispatcher.rb', line 81

def invoke(target, method, args, kwargs)
  if kwargs.empty?
    target.public_send(method.to_sym, *args)
  else
    target.public_send(method.to_sym, *args, **kwargs)
  end
end

.require_live_object!(id, handle_table) ⇒ Object

Resolve id through the HandleTable, distinguishing the :disconnected sentinel (E-14) from an unknown id (E-13).



132
133
134
135
136
137
138
139
 
# File 'lib/kobako/rpc/dispatcher.rb', line 132

def require_live_object!(id, handle_table)
  object = handle_table.fetch(id)
  raise DisconnectedTargetError, "Handle id #{id} is disconnected" if object == :disconnected

  object
rescue Kobako::HandleTableError => e
  raise UndefinedTargetError, e.message
end

.resolve_arg(value, handle_table) ⇒ Object

SPEC.md B-16 — An RPC::Handle arriving as a positional or keyword argument identifies a host-side object previously allocated by a prior RPC’s Handle wrap (B-14). Resolve it back to the Ruby object before the dispatch reaches public_send. A Handle whose entry is the :disconnected sentinel (E-14) raises DisconnectedTargetError so the dispatcher emits a Response.error with type=“disconnected”.



95
96
97
98
99
100
101
102
 
# File 'lib/kobako/rpc/dispatcher.rb', line 95

def resolve_arg(value, handle_table)
  case value
  when Kobako::RPC::Handle
    require_live_object!(value.id, handle_table)
  else
    value
  end
end

.resolve_handle(handle, handle_table) ⇒ Object 



126
127
128
 
# File 'lib/kobako/rpc/dispatcher.rb', line 126

def resolve_handle(handle, handle_table)
  require_live_object!(handle.id, handle_table)
end

.resolve_path(path, server) ⇒ Object 



120
121
122
123
124
 
# File 'lib/kobako/rpc/dispatcher.rb', line 120

def resolve_path(path, server)
  server.lookup(path)
rescue KeyError => e
  raise UndefinedTargetError, e.message
end

.resolve_target(target, server, handle_table) ⇒ Object

Resolve a Request target to the Ruby object the Server (or HandleTable) holds. String targets go through the Server; Handle targets (ext 0x01) go through the HandleTable.

Target type is already validated by RPC.decode_request before this method is reached, so no else-branch is needed here —the wire layer is the system boundary that enforces the invariant.



111
112
113
114
115
116
117
118
 
# File 'lib/kobako/rpc/dispatcher.rb', line 111

def resolve_target(target, server, handle_table)
  case target
  when String
    resolve_path(target, server)
  when Kobako::RPC::Handle
    resolve_handle(target, handle_table)
  end
end

.wrap_as_handle(value, server) ⇒ Object

Allocate value in the Server’s HandleTable and return a Handle that the wire codec can carry (SPEC.md B-14). Used as the fallback path of #encode_ok when value has no wire representation.



158
159
160
 
# File 'lib/kobako/rpc/dispatcher.rb', line 158

def wrap_as_handle(value, server)
  Kobako::RPC::Handle.new(server.handle_table.alloc(value))
end