Class: Kobako::Handle

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

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) and as a #run argument auto-wrapped by the host.

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.restore, which exists at exactly two call sites: Kobako::Codec::Factory#unpack_handle (wire decode) and Kobako::Codec::HandleWalk.deep_wrap / Kobako::Transport::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.

Returns:

  • (Integer) 
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.

Returns:

  • (Integer) 
0x7fff_ffff

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(id:) ⇒ Handle

Returns a new instance of Handle.

Parameters:

  • id: (Integer)

Raises:

  • (ArgumentError) 


36
37
38
39
40
41
 
# File 'lib/kobako/handle.rb', line 36

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

Instance Attribute Details

#id ⇒ Integer (readonly)

Returns the value of attribute id.

Returns:

  • (Integer) 


6
7
8
 
# File 'sig/kobako/handle.rbs', line 6

def id
  @id
end

Class Method Details

.restore(id) ⇒ Handle

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 Catalog::Handles. Both paths live inside lib/kobako/ and treat this method as a package-private constructor.

Parameters:

  • id (Integer)

Returns:



55
56
57
 
# File 'lib/kobako/handle.rb', line 55

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

Instance Method Details

#== ⇒ Boolean

Parameters:

  • other (Object)

Returns:

  • (Boolean) 


14
 
# File 'sig/kobako/handle.rbs', line 14

def ==: (untyped other) -> bool

#hash ⇒ Integer

Returns:

  • (Integer) 


16
 
# File 'sig/kobako/handle.rbs', line 16

def hash: () -> Integer

#with ⇒ Handle

Parameters:

  • id: (Integer)

Returns:



12
 
# File 'sig/kobako/handle.rbs', line 12

def with: (?id: Integer) -> Handle