Class: Kobako::Handle

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

Overview

Wire-level value object for an ext-0x01 Capability Handle, used in both directions across the Sandbox boundary: as a Service method’s return value (guest→host return path; docs/behavior.md B-14) and as a #run argument auto-wrapped by the host (docs/behavior.md B-34).

SPEC pins the binary layout to fixext 4 with a 4-byte big-endian u32 payload (docs/wire-codec.md § Ext Types → ext 0x01). ID 0 is reserved as the invalid sentinel; the maximum valid ID is 0x7fff_ffff (2^31 - 1).

The constructor is internal to the Host Gem. Kobako::Handle.new is privatised so Host App code cannot fabricate a Handle from a bare integer; legitimate Handle instances enter Host App code only as fields on raised error objects. The Host Gem itself constructs Handles through Handle.from_wire, which exists at exactly two call sites: Kobako::Codec::Factory#unpack_handle (wire decode) and Kobako::Codec::Utils.deep_wrap / Kobako::RPC::Dispatcher#wrap_as_handle (allocator paths). Both live inside lib/kobako/ and are not part of any public surface.

The mruby counterpart Kobako::Handle lives inside the Wasm guest under the same canonical name and shares neither code nor instances with this host-side class.

Constant Summary collapse

MIN_ID =

Inclusive lower bound on the wire Handle ID. ID 0 is reserved as the invalid sentinel and is never allocated.

1
MAX_ID =

Inclusive upper bound on the wire Handle ID. The cap matches the u32 signed-positive range so Handle IDs fit in a signed integer on either side of the wire without re-encoding.

0x7fff_ffff

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(id:) ⇒ Handle

steep:ignore:start

Raises:

  • (ArgumentError) 


38
39
40
41
42
43
 
# File 'lib/kobako/handle.rb', line 38

def initialize(id:)
  raise ArgumentError, "Handle id must be Integer" unless id.is_a?(Integer)
  raise ArgumentError, "Handle id #{id} out of range [#{MIN_ID}, #{MAX_ID}]" unless id.between?(MIN_ID, MAX_ID)

  super
end

Class Method Details

.from_wire(id) ⇒ Object

Host Gem–internal factory. Allocates the Data instance through Class#allocate and dispatches #initialize explicitly so the invariant checks still run, while keeping the public .new privatised against Host App callers.

Two collaborators call this: the codec when an ext 0x01 frame is decoded off the wire, and the allocator paths when a host-side Ruby object is registered into the Sandbox’s HandleTable. Both paths live inside lib/kobako/ and treat this method as a package-private constructor.



58
59
60
 
# File 'lib/kobako/handle.rb', line 58

def self.from_wire(id)
  allocate.tap { |handle| handle.send(:initialize, id: id) }
end