Module: Kobako::Transport::Dispatcher

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

Overview

Pure-function dispatcher for guest-initiated transport calls. Decodes a msgpack-encoded Request envelope, resolves the target object through the Catalog::Namespaces (path lookup) or Catalog::Handles (Handle lookup), invokes the method, and returns a msgpack-encoded Response envelope.

The module is stateless — all mutable state is threaded through arguments so Dispatcher has no instance variables and no side effects beyond mutating the Catalog::Handles via alloc when a non-wire-representable return value must be wrapped (docs/behavior.md B-14).

Entry point:

Kobako::Transport::Dispatcher.dispatch(request_bytes, namespaces, handler, yield_to_guest)
# => msgpack-encoded Response bytes (never raises)

Defined Under Namespace

Classes: UndefinedTargetError

Class Method Summary collapse

Class Method Details

.dispatch(request_bytes, namespaces, handler, yield_to_guest) ⇒ Object

Dispatch a single transport request and return the encoded Response bytes (docs/behavior.md B-12). Invoked from the Runtime#on_dispatch Proc that Kobako::Sandbox#initialize installs on the ext side; namespaces, handler, and yield_to_guest are captured in that Proc’s closure so the Dispatcher stays stateless and the registry doesn’t need to publish accessors for the Sandbox-owned Catalog::Handles or Runtime. yield_to_guest is a String → String callable (typically Runtime#yield_to_active_invocation bound as a lambda) used only when the Request carries block_given: true. Always returns a binary String — every failure path is reified as a Response.error envelope so the guest sees a transport error rather than a wasm trap.



84
85
86
87
88
89
90
91
92
93
94
95
 
# File 'lib/kobako/transport/dispatcher.rb', line 84

def dispatch(request_bytes, namespaces, handler, yield_to_guest)
  request = Kobako::Transport::Request.decode(request_bytes)
  target = resolve_target(request.target, namespaces, handler)
  args, kwargs = resolve_call_args(request, handler)
  yielder = Yielder.new(yield_to_guest, BREAK_THROW, handler) if request.block_given
  value = catch(BREAK_THROW) { invoke(target, request.method_name, args, kwargs, yielder) }
  encode_ok(value, handler)
rescue StandardError => e
  encode_caught_error(e)
ensure
  yielder&.invalidate!
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). Three error buckets (docs/behavior.md B-12): Kobako::Codec::Error → type=“runtime” (malformed request); UndefinedTargetError → type=“undefined” (E-13); ArgumentError →type=“argument” (B-12 arity mismatch); everything else →type=“runtime”.



115
116
117
118
119
120
121
122
123
 
# File 'lib/kobako/transport/dispatcher.rb', line 115

def encode_caught_error(error)
  case error
  when Kobako::Codec::Error then encode_error("runtime",
                                              "Sandbox received a malformed request: #{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 



237
238
239
240
241
 
# File 'lib/kobako/transport/dispatcher.rb', line 237

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

.encode_ok(value, handler) ⇒ Object

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



222
223
224
225
226
227
 
# File 'lib/kobako/transport/dispatcher.rb', line 222

def encode_ok(value, handler)
  response = Kobako::Transport::Response.ok(value)
  response.encode
rescue Kobako::Codec::UnsupportedType
  encode_ok(wrap_as_handle(value, handler), handler)
end

.invoke(target, method, args, kwargs, yielder = nil) ⇒ Object

Dispatch method on target. kwargs is already Symbol-keyed (the 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.

yielder is the host-side Yielder materialised when the guest call site supplied a block (docs/behavior.md B-23); its Yielder#to_proc rides the &block slot. &nil is a no-op block argument in Ruby, so the same call site handles both cases without an explicit conditional.



137
138
139
140
141
142
143
144
145
146
 
# File 'lib/kobako/transport/dispatcher.rb', line 137

def invoke(target, method, args, kwargs, yielder = nil)
  name = method.to_sym
  reject_meta_method!(target, name)
  block = yielder&.to_proc
  if kwargs.empty?
    target.public_send(name, *args, &block)
  else
    target.public_send(name, *args, **kwargs, &block)
  end
end

.reject_meta_method!(target, name) ⇒ Object

Guard the public_send below against ambient reflection methods (docs/behavior.md B-42). A public method whose owner is a META_OWNERS or GADGET_OWNERS module is rejected, except CALLABLE_ALLOW on a gadget target (a bound lambda stays invocable). A name with no concrete public method is allowed only when the target opts into it via respond_to? (dynamic method_missing Services), since the dangerous methods are all concretely defined and therefore never reach that branch.



156
157
158
159
160
161
162
163
164
165
166
167
 
# File 'lib/kobako/transport/dispatcher.rb', line 156

def reject_meta_method!(target, name)
  owner = target.public_method(name).owner
  gadget = GADGET_OWNERS.include?(owner)
  return unless META_OWNERS.include?(owner) || gadget
  return if gadget && CALLABLE_ALLOW.include?(name)

  raise UndefinedTargetError, "method #{name.inspect} is not a Service method"
rescue NameError
  return if target.respond_to?(name)

  raise UndefinedTargetError, "no public method #{name.inspect} on target"
end

.require_live_object!(id, handler) ⇒ Object

Resolve id through the Catalog::Handles. An unknown id (E-13) surfaces as UndefinedTargetError.



210
211
212
213
214
 
# File 'lib/kobako/transport/dispatcher.rb', line 210

def require_live_object!(id, handler)
  handler.fetch(id)
rescue Kobako::SandboxError => e
  raise UndefinedTargetError, e.message
end

.resolve_arg(value, handler) ⇒ Object

docs/behavior.md B-16 — A Kobako::Handle arriving as a positional or keyword argument identifies a host-side object previously allocated by a prior transport call’s Handle wrap (B-14). Resolve it back to the Ruby object before the dispatch reaches public_send.



173
174
175
176
177
178
179
180
 
# File 'lib/kobako/transport/dispatcher.rb', line 173

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

.resolve_call_args(request, handler) ⇒ Object

Resolve positional and keyword arguments off request in one step. Both pass through #resolve_arg so Capability Handles round-trip back to the host-side Ruby object before the call reaches public_send.



101
102
103
104
105
 
# File 'lib/kobako/transport/dispatcher.rb', line 101

def resolve_call_args(request, handler)
  args = request.args.map { |v| resolve_arg(v, handler) }
  kwargs = request.kwargs.transform_values { |v| resolve_arg(v, handler) }
  [args, kwargs]
end

.resolve_handle(handle, handler) ⇒ Object 



204
205
206
 
# File 'lib/kobako/transport/dispatcher.rb', line 204

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

.resolve_path(path, namespaces) ⇒ Object 



198
199
200
201
202
 
# File 'lib/kobako/transport/dispatcher.rb', line 198

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

.resolve_target(target, namespaces, handler) ⇒ Object

Resolve a Request target to the Ruby object the registry (or Catalog::Handles) holds. String targets go through the registry; Handle targets (ext 0x01) go through the Catalog::Handles.

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



189
190
191
192
193
194
195
196
 
# File 'lib/kobako/transport/dispatcher.rb', line 189

def resolve_target(target, namespaces, handler)
  case target
  when String
    resolve_path(target, namespaces)
  when Kobako::Handle
    resolve_handle(target, handler)
  end
end

.wrap_as_handle(value, handler) ⇒ Object

Allocate value in the Sandbox’s Catalog::Handles and return a Handle that the wire codec can carry (docs/behavior.md B-14). Used as the fallback path of #encode_ok when value has no wire representation.



233
234
235
 
# File 'lib/kobako/transport/dispatcher.rb', line 233

def wrap_as_handle(value, handler)
  handler.alloc(value)
end