Class: Kobako::Invocation

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

Overview

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

An Invocation 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 Invocation.new is safe to encode and ship to the guest.

Invocation sits at top level, not under Kobako::RPC: RPC in SPEC is the guest→host capability channel (Server / Client / Request / Response); Invocation is the opposite direction (host→guest entrypoint dispatch). #encode takes the Sandbox’s HandleTable 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 Kobako::RPC::Dispatcher#wrap_as_handle (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 “Invocation 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::Snippet::Table::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: {}) ⇒ Invocation

steep:ignore:start



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

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

Instance Method Details

#encode(handle_table) ⇒ Object

Encode this Invocation 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 handle_table and replaced with a Kobako::Handle (docs/behavior.md B-34); the handle_table 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).



68
69
70
71
72
73
74
 
# File 'lib/kobako/invocation.rb', line 68

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