kobako 0.2.1 → 0.3.0

data/lib/kobako/snippet/source.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Kobako
+  module Snippet
+    # Kobako::Snippet::Source — value object representing a single
+    # +#preload(code:, name:)+ entry held by +Kobako::Snippet::Table+
+    # ({docs/behavior.md B-32}[link:../../../docs/behavior.md]).
+    #
+    # +name+ is the canonical +Symbol+ identity baked into the loaded
+    # IREP's +debug_info+; backtrace frames originating in this snippet
+    # surface as +(snippet:Name):line+. +body+ is the UTF-8 mruby source
+    # detached from the caller's reference at +Table#register+ time so
+    # later mutation of the original String cannot bleed through.
+    #
+    # The class is a +Data.define+ subclass — frozen, value-equal, and
+    # carries no mutation API. Callers (chiefly +Table+) construct
+    # instances via keyword form +Source.new(name: ..., body: ...)+.
+    # Wire-form construction is the +Table+'s responsibility, mirroring
+    # +Kobako::RPC.encode_request+'s pattern of reading attributes off a
+    # carrier rather than asking the carrier to self-describe.
+    class Source < Data.define(:name, :body)
+      # The +kind+ field value carried by source snippets in their Frame
+      # 3 wire envelope entry
+      # ({docs/wire-codec.md Invocation channels}[link:../../../docs/wire-codec.md]).
+      KIND = "source"
+    end
+  end
+end

data/lib/kobako/snippet/table.rb

@@ -0,0 +1,174 @@
+# frozen_string_literal: true
+
+require "msgpack"
+
+require_relative "binary"
+require_relative "source"
+
+module Kobako
+  module Snippet
+    # Kobako::Snippet::Table — per-Sandbox insertion-ordered registry of
+    # preloaded snippets
+    # ({docs/behavior.md B-32 / B-33}[link:../../../docs/behavior.md]).
+    #
+    # Entries replay against the fresh +mrb_state+ before per-invocation
+    # source / entrypoint resolution. Each +Source+ entry's +name+ is its
+    # canonical identity — the filename baked into the loaded IREP's
+    # +debug_info+ that surfaces in every backtrace frame originating
+    # from the snippet as +(snippet:Name):line+. Duplicate names within
+    # the +code:+ form would produce ambiguous attribution and are
+    # rejected at registration time
+    # ({docs/behavior.md E-33}[link:../../../docs/behavior.md]).
+    # +Binary+ entries carry no host-side name — their canonical name
+    # lives in the bytecode's +debug_info+ and is read by the guest at
+    # load time; the host does not extract it.
+    #
+    # Sealing (B-33) is governed by the owning Sandbox — the table itself
+    # is append-only and exposes no mutation API beyond +#register+; the
+    # Sandbox guards +#register+ behind the seal check before delegating.
+    class Table
+      # Ruby constant-name pattern enforced on snippet names
+      # ({docs/behavior.md E-34}[link:../../../docs/behavior.md]).
+      NAME_PATTERN = /\A[A-Z]\w*\z/
+
+      def initialize
+        @entries = [] # : Array[Kobako::Snippet::Source | Kobako::Snippet::Binary]
+      end
+
+      # Serialize the registered snippets to wire bytes. Each entry
+      # contributes a msgpack map shape; the collection rides as a single
+      # msgpack array. An empty table serializes to an empty array, never
+      # absent. The wire codec is an implementation detail — callers
+      # receive a binary +String+ that the +Kobako::Wasm+ layer ships
+      # through the invocation channel. Mirrors the
+      # +Kobako::RPC.encode_request+ pattern: entry value objects stay
+      # pure carriers, this method reads their attributes externally.
+      def encode
+        MessagePack.pack(@entries.map { |entry| entry_payload(entry) })
+      end
+
+      # Register one preloaded snippet in either of two forms
+      # ({docs/behavior.md B-32}[link:../../../docs/behavior.md]).
+      #
+      #   * Source form +register(code: src, name: Name)+ — +src+ is the
+      #     mruby source as a String; the bytes are re-encoded as UTF-8
+      #     and detached from the caller's reference. +name+ is a Symbol
+      #     or String matching +NAME_PATTERN+. Returns the Symbol form
+      #     of +name+.
+      #   * Binary form +register(binary: bytes)+ — +bytes+ is
+      #     precompiled RITE bytecode as a String, duplicated and forced
+      #     to ASCII-8BIT so msgpack-ruby ships it as +bin+. Returns
+      #     +nil+ — bytecode entries are anonymous on the host side; any
+      #     structural validation
+      #     ({docs/behavior.md E-37 / E-38}[link:../../../docs/behavior.md])
+      #     is deferred to the guest at first replay.
+      #
+      # The two forms are mutually exclusive: shape validation lives
+      # here so callers (chiefly +Kobako::Sandbox#preload+) collapse to
+      # a single delegation. Raises +ArgumentError+ on mixed forms,
+      # missing keywords, wrong types, malformed +name+ (E-34), or
+      # duplicate +code:+ +name+ (E-33).
+      def register(code: nil, name: nil, binary: nil)
+        if binary
+          raise ArgumentError, "cannot combine binary: with code: / name:" if code || name
+
+          register_binary!(binary)
+        else
+          register_source!(code, name)
+        end
+      end
+
+      # Iterate over registered entries in insertion order. Yields each
+      # entry (a +Kobako::Snippet::Source+ or +Kobako::Snippet::Binary+).
+      # Returns an Enumerator when no block is given.
+      def each(&)
+        @entries.each(&)
+      end
+
+      # Canonical names of every registered +Source+ entry, in insertion
+      # order. +Binary+ entries are skipped — their names live in
+      # bytecode +debug_info+ on the guest side and are not extracted by
+      # the host.
+      def names
+        @entries.filter_map { |entry| entry.name if entry.is_a?(Source) }
+      end
+
+      # Number of registered snippets.
+      def size
+        @entries.size
+      end
+
+      # Whether no snippets are registered.
+      def empty?
+        @entries.empty?
+      end
+
+      private
+
+      # Source-form register path. Delegates argument-shape checks to
+      # +ensure_source_args!+ (which returns the narrowed
+      # +[code, name]+ pair), normalises +name+ to a Symbol, rejects
+      # duplicates (E-33), and appends the Source entry.
+      def register_source!(code, name)
+        code, name = ensure_source_args!(code, name)
+        name_sym = normalize_name(name)
+        raise ArgumentError, "snippet #{name_sym.inspect} already preloaded" if names.include?(name_sym)
+
+        @entries << Source.new(name: name_sym, body: code.dup.force_encoding(Encoding::UTF_8))
+        name_sym
+      end
+
+      # Shape-only validation for the +code:+ + +name:+ pair. Returns
+      # the pair with +nil+ narrowed away so callers can treat both as
+      # present. The +code:+ type check runs before the +name:+
+      # presence check so callers passing +code: nil+ explicitly see
+      # the type error rather than the "missing keyword" error.
+      def ensure_source_args!(code, name)
+        raise ArgumentError, "missing keyword: code: + name:, or binary:" if code.nil? && name.nil?
+        raise ArgumentError, "code must be a String, got #{code.class}" unless code.is_a?(String)
+        raise ArgumentError, "missing keyword: name:" if name.nil?
+
+        [code, name]
+      end
+
+      # Binary-form register path. Validates the +binary:+ payload
+      # type and appends the Binary entry. The bytes are duplicated and
+      # forced to ASCII-8BIT so msgpack-ruby picks the +bin+ family on
+      # the wire.
+      def register_binary!(bytes)
+        raise ArgumentError, "binary must be a String, got #{bytes.class}" unless bytes.is_a?(String)
+
+        @entries << Binary.new(body: bytes.dup.force_encoding(Encoding::ASCII_8BIT))
+        nil
+      end
+
+      # Build the msgpack-ready Hash for one entry. Source entries
+      # contribute their host-side +name+; Binary entries omit it
+      # because the canonical name lives in the bytecode's embedded
+      # +debug_info+ and is read by the guest at load time
+      # ({docs/wire-codec.md Invocation channels}[link:../../../docs/wire-codec.md]).
+      def entry_payload(entry)
+        case entry
+        when Source
+          { "name" => entry.name.to_s, "kind" => Source::KIND, "body" => entry.body }
+        when Binary
+          { "kind" => Binary::KIND, "body" => entry.body }
+        end
+      end
+
+      def normalize_name(name)
+        unless name.is_a?(Symbol) || name.is_a?(String)
+          raise ArgumentError, "snippet name must be a Symbol or String, got #{name.class}"
+        end
+
+        name_str = name.to_s
+        unless NAME_PATTERN.match?(name_str)
+          raise ArgumentError,
+                "snippet name must match #{NAME_PATTERN.inspect} (got #{name.inspect})"
+        end
+
+        name_str.to_sym
+      end
+    end
+  end
+end

data/lib/kobako/snippet.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require_relative "snippet/binary"
+require_relative "snippet/source"
+require_relative "snippet/table"
+
+module Kobako
+  # Kobako::Snippet — namespace for the per-Sandbox preloaded snippet
+  # registry and its entry value objects
+  # ({docs/behavior.md B-32 / B-33}[link:../../docs/behavior.md]).
+  #
+  # The +Table+ owns insertion-ordered storage and seal-coordination with
+  # the owning Sandbox; +Source+ is the value object representing a single
+  # +#preload(code:, name:)+ entry. Entry types live as siblings under
+  # this module rather than nested under +Table+ so they remain plain
+  # value objects with no implicit dependency on the registry that holds
+  # them.
+  module Snippet
+  end
+end

data/lib/kobako/version.rb

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

data/sig/kobako/errors.rbs

@@ -49,4 +49,7 @@ module Kobako
 
   class HandleTableExhausted < HandleTableError
   end
+
+  class BytecodeError < SandboxError
+  end
 end

data/sig/kobako/invocation.rbs

@@ -0,0 +1,23 @@
+module Kobako
+  class Invocation < Data
+    NAME_PATTERN: Regexp
+
+    attr_reader entrypoint: Symbol
+    attr_reader args: Array[untyped]
+    attr_reader kwargs: Hash[Symbol, untyped]
+
+    def self.new: (entrypoint: Symbol | String, ?args: Array[untyped], ?kwargs: Hash[untyped, untyped]) -> Invocation
+
+    def initialize: (entrypoint: Symbol | String, ?args: Array[untyped], ?kwargs: Hash[untyped, untyped]) -> void
+
+    def encode: () -> String
+
+    private
+
+    def normalize_entrypoint: (Symbol | String target) -> Symbol
+
+    def validate_args!: (Array[untyped] args) -> Array[untyped]
+
+    def validate_kwargs!: (Hash[untyped, untyped] kwargs) -> Hash[Symbol, untyped]
+  end
+end

data/sig/kobako/sandbox.rbs

@@ -1,18 +1,18 @@
 module Kobako
   class Sandbox
-    DEFAULT_OUTPUT_LIMIT: Integer
-
-    DEFAULT_TIMEOUT_SECONDS: Float
-
-    DEFAULT_MEMORY_LIMIT: Integer
+    extend Forwardable
 
     attr_reader wasm_path: String
     attr_reader instance: Kobako::Wasm::Instance
-    attr_reader stdout_limit: Integer
-    attr_reader stderr_limit: Integer
-    attr_reader timeout: Float?
-    attr_reader memory_limit: Integer?
+    attr_reader options: Kobako::SandboxOptions
     attr_reader services: Kobako::RPC::Server
+    attr_reader snippets: Kobako::Snippet::Table
+
+    # Forwarded to @options via Forwardable#def_delegators.
+    def timeout: () -> Float?
+    def memory_limit: () -> Integer?
+    def stdout_limit: () -> Integer
+    def stderr_limit: () -> Integer
 
     def initialize: (
       ?wasm_path: String?,
@@ -32,22 +32,21 @@ module Kobako
 
     def define: (Symbol | String name) -> Kobako::RPC::Namespace
 
-    def run: (String source) -> untyped
+    def preload: (code: String, name: Symbol | String) -> Kobako::Sandbox
+               | (binary: String) -> Kobako::Sandbox
 
-    private
+    def run: (Symbol | String target, *untyped args, **untyped kwargs) -> untyped
 
-    def clear_captures!: () -> void
+    def eval: (String code) -> untyped
 
-    def normalize_timeout: ((Float | Integer)? timeout) -> Float?
+    private
 
-    def normalize_memory_limit: (Integer? memory_limit) -> Integer?
+    def clear_captures!: () -> void
 
-    def reset_run_state!: () -> void
+    def begin_invocation!: () -> void
 
     def read_captures!: () -> void
 
-    def run_guest: (String preamble, String source) -> void
-
-    def take_result!: () -> untyped
+    def invoke!: (Symbol verb) { () -> void } -> untyped
   end
 end

data/sig/kobako/sandbox_options.rbs

@@ -0,0 +1,32 @@
+module Kobako
+  class SandboxOptions < Data
+    DEFAULT_TIMEOUT_SECONDS: Float
+    DEFAULT_MEMORY_LIMIT: Integer
+    DEFAULT_OUTPUT_LIMIT: Integer
+
+    attr_reader timeout: Float?
+    attr_reader memory_limit: Integer?
+    attr_reader stdout_limit: Integer
+    attr_reader stderr_limit: Integer
+
+    def self.new: (
+      ?timeout: (Float | Integer)?,
+      ?memory_limit: Integer?,
+      ?stdout_limit: Integer?,
+      ?stderr_limit: Integer?
+    ) -> SandboxOptions
+
+    def initialize: (
+      ?timeout: (Float | Integer)?,
+      ?memory_limit: Integer?,
+      ?stdout_limit: Integer?,
+      ?stderr_limit: Integer?
+    ) -> void
+
+    private
+
+    def normalize_timeout: ((Float | Integer)? timeout) -> Float?
+
+    def normalize_memory_limit: (Integer? memory_limit) -> Integer?
+  end
+end

data/sig/kobako/snippet/binary.rbs

@@ -0,0 +1,12 @@
+module Kobako
+  module Snippet
+    class Binary < Data
+      KIND: String
+
+      attr_reader body: String
+
+      def self.new: (body: String) -> Binary
+                  | (String body) -> Binary
+    end
+  end
+end

data/sig/kobako/snippet/source.rbs

@@ -0,0 +1,13 @@
+module Kobako
+  module Snippet
+    class Source < Data
+      KIND: String
+
+      attr_reader name: Symbol
+      attr_reader body: String
+
+      def self.new: (name: Symbol, body: String) -> Source
+                  | (Symbol name, String body) -> Source
+    end
+  end
+end

data/sig/kobako/snippet/table.rbs

@@ -0,0 +1,36 @@
+module Kobako
+  module Snippet
+    class Table
+      NAME_PATTERN: Regexp
+
+      type entry = Kobako::Snippet::Source | Kobako::Snippet::Binary
+
+      def initialize: () -> void
+
+      def register: (?code: String?, ?name: (Symbol | String)?, ?binary: String?) -> (Symbol | nil)
+
+      def encode: () -> String
+
+      def each: () { (entry) -> void } -> Array[entry]
+              | () -> Enumerator[entry, Array[entry]]
+
+      def names: () -> Array[Symbol]
+
+      def size: () -> Integer
+
+      def empty?: () -> bool
+
+      private
+
+      def register_source!: (String? code, (Symbol | String)? name) -> Symbol
+
+      def ensure_source_args!: (String? code, (Symbol | String)? name) -> [String, Symbol | String]
+
+      def register_binary!: (String bytes) -> nil
+
+      def entry_payload: (entry) -> Hash[String, untyped]
+
+      def normalize_name: (Symbol | String name) -> Symbol
+    end
+  end
+end

data/sig/kobako/snippet.rbs

@@ -0,0 +1,4 @@
+module Kobako
+  module Snippet
+  end
+end

data/sig/kobako/wasm.rbs

@@ -25,7 +25,9 @@ module Kobako
 
       def server=: (Kobako::RPC::Server server) -> void
 
-      def run: (String preamble, String source) -> void
+      def eval: (String preamble, String source, String snippets) -> void
+
+      def run: (String preamble, String snippets, String envelope) -> void
 
       def stdout: () -> [String, bool]
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: kobako
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.3.0
 platform: ruby
 authors:
 - Aotokitsuruya
@@ -69,6 +69,7 @@ files:
 - lib/kobako/codec/factory.rb
 - lib/kobako/codec/utils.rb
 - lib/kobako/errors.rb
+- lib/kobako/invocation.rb
 - lib/kobako/outcome.rb
 - lib/kobako/outcome/panic.rb
 - lib/kobako/rpc.rb
@@ -80,6 +81,11 @@ files:
 - lib/kobako/rpc/namespace.rb
 - lib/kobako/rpc/server.rb
 - lib/kobako/sandbox.rb
+- lib/kobako/sandbox_options.rb
+- lib/kobako/snippet.rb
+- lib/kobako/snippet/binary.rb
+- lib/kobako/snippet/source.rb
+- lib/kobako/snippet/table.rb
 - lib/kobako/version.rb
 - lib/kobako/wasm.rb
 - sig/kobako.rbs
@@ -90,6 +96,7 @@ files:
 - sig/kobako/codec/factory.rbs
 - sig/kobako/codec/utils.rbs
 - sig/kobako/errors.rbs
+- sig/kobako/invocation.rbs
 - sig/kobako/outcome.rbs
 - sig/kobako/outcome/panic.rbs
 - sig/kobako/rpc.rbs
@@ -101,6 +108,11 @@ files:
 - sig/kobako/rpc/namespace.rbs
 - sig/kobako/rpc/server.rbs
 - sig/kobako/sandbox.rbs
+- sig/kobako/sandbox_options.rbs
+- sig/kobako/snippet.rbs
+- sig/kobako/snippet/binary.rbs
+- sig/kobako/snippet/source.rbs
+- sig/kobako/snippet/table.rbs
 - sig/kobako/wasm.rbs
 homepage: https://github.com/elct9620/kobako
 licenses: