Class: Kobako::Transport::Run

Inherits:
Object
  • Object
show all
Defined in:
lib/kobako/transport/run.rb

Overview

Host-side value object for a single Sandbox#run invocation (docs/wire-codec.md Invocation channels; docs/behavior.md B-31).

A Run captures the host-layer concept of “a single #run call”: the entrypoint constant name plus its positional and keyword arguments. Host pre-flight (E-24 / E-25 / E-29 / E-30) is enforced at construction so the Value Object is the single source of truth —anything that passes Run.new is safe to encode and ship to the guest.

Run is the host→guest entrypoint dispatch envelope (the #run request shape), the symmetric counterpart to the guest→host Request envelope. #encode takes the Sandbox’s Catalog::Handles and routes any non-wire-representable args / kwargs leaf through it as a Kobako::Handle (docs/behavior.md B-34) — the symmetric counterpart of the guest→host wrap path in the dispatcher (B-14). A Kobako::Handle that arrives **already constructed** in the caller’s args / kwargs is rejected at construction (E-29): legitimate Handles only enter Host App code through error fields, so a Handle reaching the call site is by definition smuggled in. The #encode output is the “Run envelope” that ships through the __kobako_run command buffer.

Built on the class X < Data.define(…) subclass form (the Steep-friendly shape — see lib/kobako/outcome/panic.rb).

Constant Summary collapse

NAME_PATTERN =

Ruby constant-name pattern enforced on the entrypoint Symbol (docs/behavior.md E-25). Parallel to Kobako::Catalog::Snippets::NAME_PATTERN; the two constants name the same regex but cover distinct surfaces (snippet identity vs. entrypoint resolution) so a future divergence stays local.

/\A[A-Z]\w*\z/

Instance Method Summary collapse

Constructor Details

#initialize(entrypoint:, args: [], kwargs: {}) ⇒ Run

Returns a new instance of Run.



46
47
48
49
50
51
 
# File 'lib/kobako/transport/run.rb', line 46

def initialize(entrypoint:, args: [], kwargs: {})
  entrypoint = normalize_entrypoint(entrypoint)
  args = validate_args!(args)
  kwargs = validate_kwargs!(kwargs)
  super
end

Instance Method Details

#encode(handler) ⇒ Object

Encode this Run to the msgpack bytes the guest’s __kobako_run entry point consumes as its command-buffer payload (docs/wire-codec.md Invocation channels). Walks args / kwargs through Codec::Utils.deep_wrap so any non-wire-representable leaf is allocated into handler and replaced with a Kobako::Handle (docs/behavior.md B-34); the handler argument is the Sandbox’s table, sharing the same allocator the guest→host return path (B-14) uses.

Layout: msgpack map with string keys “entrypoint” (Symbol via ext 0x00), “args” (Array), “kwargs” (Map with Symbol keys); any wrapped leaf rides as ext 0x01 in its original position (docs/wire-codec.md § ext 0x01 position rules).



67
68
69
70
71
72
73
 
# File 'lib/kobako/transport/run.rb', line 67

def encode(handler)
  Codec::Encoder.encode(
    "entrypoint" => entrypoint,
    "args" => Codec::Utils.deep_wrap(args, handler),
    "kwargs" => Codec::Utils.deep_wrap(kwargs, handler)
  )
end