kobako 0.11.0 → 0.11.2

data/lib/kobako/codec/utils.rb

@@ -1,12 +1,11 @@
 # frozen_string_literal: true
 
 require_relative "error"
-require_relative "../handle"
 
 module Kobako
   module Codec
-    # Codec helpers shared by the host-side encoders and decoders.
-    # Three concerns live here today:
+    # Byte-boundary helpers shared by the host-side encoder and decoder.
+    # Two concerns live here:
     #
     #   - UTF-8 assertion at the codec boundary
     #     ({docs/wire-codec.md}[link:../../../docs/wire-codec.md]
@@ -16,14 +15,9 @@ module Kobako
     #   - +ArgumentError+ translation at the codec boundary
     #     ({with_boundary}) so the public taxonomy stays
     #     {Kobako::Codec::Error}.
-    #   - Representability predicate ({representable?}) and the symmetric
-    #     host→guest +#run+ argument walk ({deep_wrap}) used by
-    #     +Kobako::Transport::Run#encode+ to route non-representable leaves
-    #     through the Sandbox's +Kobako::Catalog::Handles+.
     #
-    # All helpers are pure — they only inspect inputs, never mutate
-    # them — except {deep_wrap}, whose only side effect is allocating
-    # new Handle ids into the supplied table.
+    # Both helpers are pure — they only inspect inputs, never mutate them.
+    # The host↔guest Handle substitution walk lives in {HandleWalk}.
     module Utils
       module_function
 
@@ -53,113 +47,6 @@ module Kobako
       rescue ::ArgumentError => e
         raise InvalidType, e.message
       end
-
-      # Inclusive Integer range the msgpack gem encodes without raising
-      # +RangeError+ at encode time — signed +int 64+ minimum through
-      # unsigned +uint 64+ maximum
-      # ({docs/wire-codec.md}[link:../../../docs/wire-codec.md] § Type
-      # Mapping #3, the +fixint+ / +int 8..64+ / +uint 8..64+ union).
-      # Anchored as a +Range+ so {primitive_type?} stays a single
-      # dispatch line. This is the codec's encode domain — not to
-      # be confused with the Handle id range, which lives on
-      # +Kobako::Handle+ as +MIN_ID+ / +MAX_ID+ (1..2^31 − 1) and
-      # represents a different concept entirely.
-      MSGPACK_INT_RANGE = (-(2**63)..((2**64) - 1))
-
-      # Codec-type predicate
-      # ({docs/wire-codec.md}[link:../../../docs/wire-codec.md] § Type
-      # Mapping). Returns +true+ when +value+ belongs to the closed
-      # 12-entry codec type set — +nil+, +TrueClass+, +FalseClass+,
-      # +Integer+ (in the +i64..u64+ value domain), +Float+, +String+,
-      # +Symbol+, +Kobako::Handle+, +Array+ whose every element is itself
-      # representable, or +Hash+ whose every key and value are
-      # representable. Integers outside the codec's signed-64 /
-      # unsigned-64 union are rejected so the predicate agrees with the
-      # msgpack gem's encode-time +RangeError+ behaviour the codec
-      # already surfaces as {UnsupportedType}.
-      def representable?(value)
-        primitive_type?(value) || container_representable?(value)
-      end
-
-      # Deep-walk Array / Hash containers in +value+ and replace every
-      # leaf that fails {representable?} with a +Kobako::Handle+
-      # allocated from +handler+. The
-      # walk only descends through representable container shapes
-      # (Array, Hash) one structural level at a time; a non-representable
-      # leaf is wrapped as-is without inspecting its internal structure.
-      # An existing +Kobako::Handle+ is representable and passes through
-      # unchanged — auto-wrap never re-wraps a Handle.
-      #
-      # +value+ may be any Ruby value; +handler+ must respond to
-      # +#alloc(object) -> Kobako::Handle+ (a host-side
-      # +Kobako::Catalog::Handles+). Returns a structurally equivalent value
-      # whose leaves are either representable or +Kobako::Handle+
-      # tokens.
-      #
-      # The block bodies spell +Utils.deep_wrap+ explicitly rather than
-      # the unqualified +deep_wrap+ because +module_function+ makes the
-      # instance copy of these helpers private; an implicit receiver
-      # inside a block would resolve against the enclosing +self+
-      # (still +Utils+ at definition time, but the qualified form keeps
-      # the dispatch readable when the recursive call sits inside a
-      # Proc captured from elsewhere).
-      def deep_wrap(value, handler)
-        case value
-        when ::Array then value.map { |element| Utils.deep_wrap(element, handler) }
-        when ::Hash  then value.transform_values { |val| Utils.deep_wrap(val, handler) }
-        else
-          representable?(value) ? value : handler.alloc(value)
-        end
-      end
-
-      # Deep-walk Array / Hash containers in +value+ and replace every
-      # +Kobako::Handle+ leaf with the host-side object +handler+ resolves
-      # it to. The symmetric inverse of {deep_wrap}: that walk allocates objects
-      # into Handles on the host→guest argument path; this walk resolves
-      # Handles back to their objects on every guest→host value path — the
-      # +#eval+ / +#run+ result and the yield-block result alike. The walk
-      # descends through Array elements and Hash keys and values one
-      # structural level at a time; any non-Handle leaf passes through
-      # unchanged.
-      #
-      # +value+ is a decoded Ruby value (a Handle here is a wire-decoded
-      # +Kobako::Handle+, never a guest-forged one); +handler+ must
-      # respond to +#fetch(id) -> object+ (a host-side
-      # +Kobako::Catalog::Handles+). +handler.fetch+ raises
-      # +Kobako::SandboxError+ for an id with no live binding, the
-      # corrupted-runtime fallback.
-      def deep_restore(value, handler)
-        case value
-        when ::Array then value.map { |element| Utils.deep_restore(element, handler) }
-        when ::Hash
-          value.to_h { |key, val| [Utils.deep_restore(key, handler), Utils.deep_restore(val, handler)] }
-        when Kobako::Handle then handler.fetch(value.id)
-        else value
-        end
-      end
-
-      # The non-container branch of {representable?}: returns +true+ for
-      # the scalar leaves and an existing Handle. Not part of the
-      # public surface; reach for {representable?} instead.
-      def primitive_type?(value)
-        case value
-        when ::NilClass, ::TrueClass, ::FalseClass, ::Float, ::String, ::Symbol, Kobako::Handle then true
-        when ::Integer then MSGPACK_INT_RANGE.cover?(value)
-        else false
-        end
-      end
-
-      # The container branch of {representable?}: recurses into Array
-      # elements and Hash key+value pairs through the public
-      # {representable?}. Not part of the public surface; reach for
-      # {representable?} instead.
-      def container_representable?(value)
-        case value
-        when ::Array then value.all? { |element| Utils.representable?(element) }
-        when ::Hash  then value.all? { |key, val| Utils.representable?(key) && Utils.representable?(val) }
-        else false
-        end
-      end
     end
   end
 end

data/lib/kobako/codec.rb

@@ -2,6 +2,7 @@
 
 require_relative "codec/error"
 require_relative "codec/utils"
+require_relative "codec/handle_walk"
 require_relative "codec/factory"
 require_relative "codec/encoder"
 require_relative "codec/decoder"

data/lib/kobako/handle.rb

@@ -17,7 +17,7 @@ module Kobako
   # fields on raised error objects. The Host Gem itself constructs
   # Handles through {.restore}, which exists at exactly two call
   # sites: +Kobako::Codec::Factory#unpack_handle+ (wire decode) and
-  # +Kobako::Codec::Utils.deep_wrap+ / +Kobako::Transport::Dispatcher#wrap_as_handle+
+  # +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.
   #

data/lib/kobako/outcome.rb

@@ -14,13 +14,6 @@ module Kobako
   # +Kobako::Outcome::Panic+. The byte-level msgpack codec at
   # +Kobako::Codec+ is invoked for the body itself; otherwise
   # nothing in +Transport+ participates.
-  #
-  #   * tag 0x01, decode OK                 → return decoded value
-  #   * tag 0x01, decode fails              → SandboxError
-  #   * tag 0x02, origin="service"          → ServiceError
-  #   * tag 0x02, origin="sandbox"/missing  → SandboxError
-  #   * tag 0x02, decode fails              → SandboxError
-  #   * unknown tag                         → TrapError
   module Outcome
     # First byte of the OUTCOME_BUFFER for the success branch — body is
     # the bare msgpack encoding of the returned value
@@ -47,9 +40,8 @@ module Kobako
     # TrapError for unknown or absent tag
     # ({docs/wire-codec.md ABI Signatures}[link:../../docs/wire-codec.md]:
     # zero-length output and unrecognised first byte both walk the trap
-    # path). The user-facing message stays in caller vocabulary — the
-    # raw tag byte (or absence) belongs in +details+ for operators, not
-    # in the message a caller sees.
+    # path). The absent-vs-present distinction selects the message;
+    # the raw byte is not actionable to a caller and is not surfaced.
     def build_trap_error(tag)
       if tag.nil?
         TrapError.new("Sandbox exited without producing a result")

data/lib/kobako/sandbox.rb

@@ -289,7 +289,7 @@ module Kobako
       # token; restore it to the host object the guest referenced before
       # handing the value to the Host App. @handler still holds this
       # invocation's table — reset only happens at the next #begin_invocation!.
-      Codec::Utils.deep_restore(Outcome.decode(snapshot.return_bytes), @handler)
+      Codec::HandleWalk.deep_restore(Outcome.decode(snapshot.return_bytes), @handler)
     rescue Kobako::TrapError => e
       raise trap_class_for(e), "Sandbox##{verb} failed: #{e.message}"
     ensure

data/lib/kobako/transport/dispatcher.rb

@@ -100,13 +100,9 @@ module Kobako
       end
 
       # 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). Four
-      # error buckets:
-      # +Kobako::Codec::Error+ → type="runtime" (malformed request);
-      # +UndefinedTargetError+ → type="undefined"; +ArgumentError+ →
-      # type="argument" (arity mismatch); everything else →
-      # type="runtime".
+      # envelope (binary msgpack). +error+ is the +StandardError+ caught by
+      # {#dispatch}'s rescue; the +type+ field tells the guest which kind
+      # of failure it was so it can raise the matching proxy-side error.
       def encode_caught_error(error)
         case error
         when Kobako::Codec::Error then encode_error("runtime",

data/lib/kobako/transport/run.rb

@@ -51,8 +51,8 @@ module Kobako
       # 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}[link:../../../docs/wire-codec.md]).
-      # Walks +args+ / +kwargs+ through {Codec::Utils.deep_wrap} so any
-      # non-wire-representable leaf is allocated into +handler+ and
+      # Walks +args+ / +kwargs+ through {Codec::HandleWalk.deep_wrap} so
+      # any non-wire-representable leaf is allocated into +handler+ and
       # replaced with a +Kobako::Handle+; the
       # +handler+ argument is the Sandbox's table, sharing the same
       # allocator the guest→host return path uses.
@@ -64,8 +64,8 @@ module Kobako
       def encode(handler)
         Codec::Encoder.encode(
           "entrypoint" => entrypoint,
-          "args" => Codec::Utils.deep_wrap(args, handler),
-          "kwargs" => Codec::Utils.deep_wrap(kwargs, handler)
+          "args" => Codec::HandleWalk.deep_wrap(args, handler),
+          "kwargs" => Codec::HandleWalk.deep_wrap(kwargs, handler)
         )
       end
 

data/lib/kobako/transport/yielder.rb

@@ -82,7 +82,7 @@ module Kobako
       # Array / Hash one level at a time; a plain value passes through
       # unchanged.
       def restore(value)
-        Kobako::Codec::Utils.deep_restore(value, @handler)
+        Kobako::Codec::HandleWalk.deep_restore(value, @handler)
       end
 
       # Reify a +YieldResponse+ tag 0x04 payload into a +RuntimeError+ the

data/lib/kobako/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Kobako
-  VERSION = "0.11.0"
+  VERSION = "0.11.2"
 end

data/sig/kobako/codec/handle_walk.rbs

@@ -0,0 +1,17 @@
+module Kobako
+  module Codec
+    module HandleWalk
+      MSGPACK_INT_RANGE: Range[Integer]
+
+      def self?.representable?: (untyped value) -> bool
+
+      def self?.deep_wrap: (untyped value, Kobako::Catalog::Handles handler) -> untyped
+
+      def self?.deep_restore: (untyped value, Kobako::Catalog::Handles handler) -> untyped
+
+      def self?.primitive_type?: (untyped value) -> bool
+
+      def self?.container_representable?: (untyped value) -> bool
+    end
+  end
+end

data/sig/kobako/codec/utils.rbs

@@ -1,21 +1,9 @@
 module Kobako
   module Codec
     module Utils
-      MSGPACK_INT_RANGE: Range[Integer]
-
       def self?.assert_utf8!: (String string, String label) -> void
 
       def self?.with_boundary: [T] () { () -> T } -> T
-
-      def self?.representable?: (untyped value) -> bool
-
-      def self?.deep_wrap: (untyped value, Kobako::Catalog::Handles handler) -> untyped
-
-      def self?.deep_restore: (untyped value, Kobako::Catalog::Handles handler) -> untyped
-
-      def self?.primitive_type?: (untyped value) -> bool
-
-      def self?.container_representable?: (untyped value) -> bool
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: kobako
 version: !ruby/object:Gem::Version
-  version: 0.11.0
+  version: 0.11.2
 platform: ruby
 authors:
 - Aotokitsuruya
@@ -53,6 +53,7 @@ files:
 - Cargo.toml
 - LICENSE
 - README.md
+- SECURITY.md
 - data/kobako.wasm
 - ext/kobako/Cargo.toml
 - ext/kobako/extconf.rb
@@ -63,7 +64,9 @@ files:
 - ext/kobako/src/runtime/capture.rs
 - ext/kobako/src/runtime/config.rs
 - ext/kobako/src/runtime/dispatch.rs
+- ext/kobako/src/runtime/errors.rs
 - ext/kobako/src/runtime/exports.rs
+- ext/kobako/src/runtime/frames.rs
 - ext/kobako/src/runtime/guest_mem.rs
 - ext/kobako/src/runtime/instance_pre.rs
 - ext/kobako/src/runtime/invocation.rs
@@ -80,6 +83,7 @@ files:
 - lib/kobako/codec/encoder.rb
 - lib/kobako/codec/error.rb
 - lib/kobako/codec/factory.rb
+- lib/kobako/codec/handle_walk.rb
 - lib/kobako/codec/utils.rb
 - lib/kobako/errors.rb
 - lib/kobako/fault.rb
@@ -118,6 +122,7 @@ files:
 - sig/kobako/codec/encoder.rbs
 - sig/kobako/codec/error.rbs
 - sig/kobako/codec/factory.rbs
+- sig/kobako/codec/handle_walk.rbs
 - sig/kobako/codec/utils.rbs
 - sig/kobako/errors.rbs
 - sig/kobako/fault.rbs