kobako 0.28.0 → 0.30.0

data/lib/kobako/catalog/snippets.rb

@@ -7,7 +7,7 @@ module Kobako
   module Catalog
     class Snippets # :nodoc:
       def initialize
-        @entries = [] # : Array[Kobako::Snippet::Source | Kobako::Snippet::Binary]
+        @entries = [] # : Array[Kobako::Snippet::Source | Kobako::Snippet::Bytecode]
         @compiled = {} # : Hash[Kobako::Snippet::Source, String]
         @compile_tried = false
       end
@@ -40,21 +40,17 @@ module Kobako
         if binary
           raise ArgumentError, "cannot combine binary: with code: / name:" if code || name
 
-          register_binary!(binary)
+          register_binary(binary)
         else
-          register_source!(code, name)
+          register_source(code, name)
         end
       end
 
       private
 
-      # The native side frames a source body only as UTF-8 text, so source
-      # read as bytes is re-tagged, and bytes that are not UTF-8 are refused
-      # here rather than failing every invocation.
-      def register_source!(code, name)
-        code, name = ensure_source_args!(code, name)
-        body = code.dup.force_encoding(Encoding::UTF_8)
-        raise ArgumentError, "code must be UTF-8 text" unless body.valid_encoding?
+      def register_source(code, name)
+        code, name = ensure_source_args(code, name)
+        body = Catalog.to_utf8(code, "code")
 
         name_sym = normalize_name(name)
         if @entries.any? { |e| e.is_a?(Snippet::Source) && e.name == name_sym }
@@ -67,7 +63,7 @@ module Kobako
 
       # The +code:+ type check runs first so an explicit +code: nil+ reads
       # as a type error rather than a missing keyword.
-      def ensure_source_args!(code, name)
+      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?
@@ -77,10 +73,10 @@ module Kobako
 
       # Kept as bytes whatever encoding the caller tagged them with, since
       # the guest reads them as bytecode rather than text.
-      def register_binary!(bytes)
+      def register_binary(bytes)
         raise ArgumentError, "binary must be a String, got #{bytes.class}" unless bytes.is_a?(String)
 
-        @entries << Snippet::Binary.new(body: bytes.dup.force_encoding(Encoding::ASCII_8BIT))
+        @entries << Snippet::Bytecode.new(body: bytes.dup.force_encoding(Encoding::ASCII_8BIT))
         nil
       end
 
@@ -90,9 +86,9 @@ module Kobako
         case entry
         when Snippet::Source
           compiled = @compiled[entry]
-          compiled ? [Snippet::Binary::KIND, nil, compiled] : [Snippet::Source::KIND, entry.name.to_s, entry.body]
+          compiled ? [Snippet::Bytecode::KIND, nil, compiled] : [Snippet::Source::KIND, entry.name.to_s, entry.body]
         else
-          [Snippet::Binary::KIND, nil, entry.body]
+          [Snippet::Bytecode::KIND, nil, entry.body]
         end
       end
 

data/lib/kobako/catalog.rb

@@ -5,8 +5,19 @@ require_relative "catalog/services"
 require_relative "catalog/snippets"
 require_relative "catalog/flags"
 require_relative "catalog/extensions"
+require_relative "catalog/mount"
+require_relative "catalog/grants"
 
 module Kobako
   module Catalog # :nodoc:
+    # The native side carries a registered text only as UTF-8, so text read
+    # as bytes is re-tagged, and bytes that are not UTF-8 are refused at
+    # registration rather than failing every invocation.
+    def self.to_utf8(text, what)
+      utf8 = text.dup.force_encoding(Encoding::UTF_8)
+      raise ArgumentError, "#{what} must be UTF-8 text" unless utf8.valid_encoding?
+
+      utf8
+    end
   end
 end

data/lib/kobako/codec/decoder.rb

@@ -13,8 +13,9 @@ module Kobako
       # from the decoded payload reports a broken invariant as
       # InvalidTypeError without its own Utils.with_boundary.
       def self.decode(bytes)
+        ValueBudget.assert_within(bytes, State.current.value_budget)
         value = FACTORY.load(bytes.b)
-        validate_utf8!(value)
+        validate_utf8(value)
         block_given? ? yield(value) : value
       # msgpack gem raises the format/type errors below; +ArgumentError+
       # covers a yielded block's Value Object invariants — a wire violation
@@ -29,23 +30,23 @@ module Kobako
         raise TruncatedInputError, e.message
       end
 
-      # +str+ family payloads must be UTF-8
-      # (docs/wire/payload-msgpack.md § Text and Bytes). The msgpack gem
+      # +str+ family payloads must be UTF-8, since a sender carries bytes
+      # that are not UTF-8 as +bin+. The msgpack gem
       # returns UTF-8-tagged Strings for
       # str family but does not validate the bytes; +bin+ family decodes
       # to ASCII-8BIT. Walk the tree once and reject invalid UTF-8 in any
-      # str-typed leaf via Utils.assert_utf8!.
+      # str-typed leaf via Utils.assert_utf8.
       class << self
         private
 
-        def validate_utf8!(value)
+        def validate_utf8(value)
           case value
-          when String then Utils.assert_utf8!(value, "str payload") if value.encoding == Encoding::UTF_8
-          when Array  then value.each { |v| validate_utf8!(v) }
+          when String then Utils.assert_utf8(value, "str payload") if value.encoding == Encoding::UTF_8
+          when Array  then value.each { |v| validate_utf8(v) }
           when Hash
             value.each do |key, val|
-              validate_utf8!(key)
-              validate_utf8!(val)
+              validate_utf8(key)
+              validate_utf8(val)
             end
           end
         end

data/lib/kobako/codec/ext_types.rb

@@ -10,13 +10,11 @@ require_relative "../handle"
 module Kobako
   module Codec # :nodoc:
     module ExtTypes # :nodoc:
-      # MessagePack ext type code reserved for Symbol
-      # (docs/wire/payload-msgpack.md § ext 0x00 — Symbol). Module-private —
+      # MessagePack ext type code reserved for Symbol. Module-private —
       # mirrors +codec::EXT_SYMBOL+ on the
       # Rust side.
       EXT_SYMBOL = 0x00
-      # MessagePack ext type code reserved for Capability Handle
-      # (docs/wire/payload-msgpack.md § ext 0x01 — Handle). Module-private —
+      # MessagePack ext type code reserved for Capability Handle. Module-private —
       # mirrors +codec::EXT_HANDLE+ on the
       # Rust side.
       EXT_HANDLE = 0x01
@@ -51,7 +49,7 @@ module Kobako
         # unpacker would otherwise apply to invalid bytes.
         def unpack_symbol(payload)
           name = payload.b.force_encoding(Encoding::UTF_8)
-          Utils.assert_utf8!(name, "Symbol payload")
+          Utils.assert_utf8(name, "Symbol payload")
           name.to_sym
         end
 
@@ -63,7 +61,7 @@ module Kobako
         # shape. The sighting is recorded so a Handle-free decode can skip the
         # downstream resolution walk.
         def unpack_handle(payload, state)
-          state.record_handle!
+          state.record_handle
           bytes = payload.b
           raise InvalidTypeError, "Handle payload must be 4 bytes, got #{bytes.bytesize}" unless bytes.bytesize == 4
 

data/lib/kobako/codec/handle_walk.rb

@@ -8,8 +8,7 @@ module Kobako
     module HandleWalk # :nodoc:
       # Inclusive Integer range the msgpack gem encodes without raising
       # +RangeError+ at encode time — signed +int 64+ minimum through
-      # unsigned +uint 64+ maximum (docs/wire/payload-msgpack.md § Integer
-      # Range).
+      # unsigned +uint 64+ maximum, the range every wire Integer fits.
       # 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
@@ -17,8 +16,7 @@ module Kobako
       # represents a different concept entirely.
       MSGPACK_INT_RANGE = (-(2**63)..((2**64) - 1))
 
-      # Whether +value+ falls in the codec's type set
-      # (docs/wire/payload-msgpack.md § Type Mapping). The +depth+ bound
+      # Whether +value+ falls in the codec's closed type set. The +depth+ bound
       # makes a self-referential container —
       # reachable as a cyclic Hash key on the +#run+ argument path — read as
       # non-representable rather than looping.
@@ -32,7 +30,7 @@ module Kobako
       # than crossing as a token the guest→host restore walk could not
       # round-trip.
       def self.deep_wrap(value, handles, depth = 0)
-        guard_nesting!(depth)
+        guard_nesting(depth)
         case value
         when ::Array then value.map { |element| deep_wrap(element, handles, depth + 1) }
         when ::Hash  then deep_wrap_hash(value, handles, depth)
@@ -64,7 +62,7 @@ module Kobako
         # A reference cycle necessarily trips the nesting bound, so a +#run+
         # argument fails as a clean +Kobako::SandboxError+ rather than an
         # unbounded host recursion.
-        def guard_nesting!(depth)
+        def guard_nesting(depth)
           return unless depth > MAX_NESTING_DEPTH
 
           raise Kobako::SandboxError,

data/lib/kobako/codec/nesting.rb

@@ -9,12 +9,12 @@ module Kobako
     module Nesting # :nodoc:
       # Raise InvalidTypeError when +value+ nests past MAX_NESTING_DEPTH; a
       # value nested exactly to the bound passes.
-      def self.assert_within_bound!(value, depth = 0)
+      def self.assert_within_bound(value, depth = 0)
         case value
-        when ::Array then assert_members_within_bound!(value, depth)
+        when ::Array then assert_members_within_bound(value, depth)
         when ::Hash
-          assert_members_within_bound!(value.keys, depth)
-          assert_members_within_bound!(value.values, depth)
+          assert_members_within_bound(value.keys, depth)
+          assert_members_within_bound(value.values, depth)
         end
       end
 
@@ -22,7 +22,7 @@ module Kobako
       # level deeper. A member is matched by class rather than asked about
       # itself — it may be a BasicObject — and only one that could be a
       # container is walked into.
-      def self.assert_members_within_bound!(members, depth)
+      def self.assert_members_within_bound(members, depth)
         return if members.empty?
         if depth >= MAX_NESTING_DEPTH
           raise InvalidTypeError,
@@ -30,9 +30,9 @@ module Kobako
         end
         return unless members.any?(::Enumerable)
 
-        members.grep(::Enumerable) { |member| assert_within_bound!(member, depth + 1) }
+        members.grep(::Enumerable) { |member| assert_within_bound(member, depth + 1) }
       end
-      private_class_method :assert_members_within_bound!
+      private_class_method :assert_members_within_bound
     end
   end
 end

data/lib/kobako/codec/state.rb

@@ -2,8 +2,9 @@
 
 module Kobako
   module Codec
-    # Whether a Capability Handle crossed the decode in flight, kept per
-    # thread so plain instance variables stay sound.
+    # Whether a Capability Handle crossed the decode in flight, and the
+    # value budget a decode is held to, kept per thread so plain instance
+    # variables stay sound.
     class State # :nodoc:
       # Thread-local slot holding the calling thread's State.
       STATE_KEY = :__kobako_codec_state__
@@ -18,6 +19,21 @@ module Kobako
 
       def initialize
         @carried_handle = false
+        @value_budget = nil
+      end
+
+      # The most values a decode on this thread may build, or nil for no
+      # budget.
+      attr_reader :value_budget
+
+      # A nested invocation on the same thread restores the outer one's
+      # budget when it returns.
+      def within_value_budget(budget)
+        outer = @value_budget
+        @value_budget = budget
+        yield
+      ensure
+        @value_budget = outer
       end
 
       # ExtTypes#unpack_handle is the sole chokepoint every Handle passes
@@ -30,7 +46,7 @@ module Kobako
 
       # Record that an ext 0x01 Capability Handle crossed the current
       # decode; #track_handles reports it to the bracketing caller.
-      def record_handle!
+      def record_handle
         @carried_handle = true
       end
     end

data/lib/kobako/codec/utils.rb

@@ -5,7 +5,7 @@ require_relative "error"
 module Kobako
   module Codec
     module Utils # :nodoc:
-      def self.assert_utf8!(string, label)
+      def self.assert_utf8(string, label)
         return if string.valid_encoding?
 
         raise InvalidEncodingError, "#{label} is not valid UTF-8"

data/lib/kobako/codec/value_budget.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require_relative "error"
+
+module Kobako
+  module Codec
+    # Counts the values a payload holds before the decoder builds any, so a
+    # guest cannot make the host build more objects than it could hold in
+    # its own memory. Every value takes at
+    # least one byte, so a payload no longer than the budget needs no count.
+    #
+    # The count stops at the first byte it cannot frame and leaves that
+    # payload for the decoder to refuse in its own words.
+    module ValueBudget # :nodoc:
+      # Marker to the body width of a scalar with no length field.
+      SCALARS = {
+        0xc0 => 0, 0xc2 => 0, 0xc3 => 0, 0xca => 4, 0xcb => 8,
+        0xcc => 1, 0xcd => 2, 0xce => 4, 0xcf => 8,
+        0xd0 => 1, 0xd1 => 2, 0xd2 => 4, 0xd3 => 8,
+        0xd4 => 2, 0xd5 => 3, 0xd6 => 5, 0xd7 => 9, 0xd8 => 17
+      }.freeze
+      # Marker to a container's count width and the values each entry holds.
+      COUNTS = { 0xdc => [2, 1], 0xdd => [4, 1], 0xde => [2, 2], 0xdf => [4, 2] }.freeze
+      # Marker to a str, bin, or ext's length width and type tag width.
+      LENGTHS = {
+        0xc4 => [1, 0], 0xc5 => [2, 0], 0xc6 => [4, 0],
+        0xd9 => [1, 0], 0xda => [2, 0], 0xdb => [4, 0],
+        0xc7 => [1, 1], 0xc8 => [2, 1], 0xc9 => [4, 1]
+      }.freeze
+      UINT = { 1 => "C", 2 => "n", 4 => "N" }.freeze
+      private_constant :SCALARS, :COUNTS, :LENGTHS, :UINT
+
+      def self.assert_within(bytes, budget)
+        return if budget.nil? || bytes.bytesize <= budget
+
+        remaining = budget
+        pending = 1
+        pos = 0
+        while pending.positive?
+          pos, children = step(bytes, pos)
+          return if pos.nil?
+          raise InvalidTypeError, "payload holds more than #{budget} values" if (remaining -= 1).negative?
+
+          pending += children - 1
+        end
+      end
+
+      # The position after the value at +pos+, nil for one the payload
+      # cannot frame, and the values it holds directly.
+      def self.step(bytes, pos)
+        marker = bytes.getbyte(pos) or return [nil, 0]
+        pos += 1
+        case marker
+        when 0x00..0x7f, 0xe0..0xff then [pos, 0]
+        when 0x80..0x8f then [pos, (marker & 0x0f) * 2]
+        when 0x90..0x9f then [pos, marker & 0x0f]
+        when 0xa0..0xbf then [pos + (marker & 0x1f), 0]
+        else step_framed(bytes, pos, marker)
+        end
+      end
+
+      def self.step_framed(bytes, pos, marker)
+        return [pos + SCALARS.fetch(marker), 0] if SCALARS.key?(marker)
+
+        width, per = COUNTS[marker]
+        return [pos + width, uint(bytes, pos, width) * per] if width && per
+
+        width, tag = LENGTHS[marker]
+        return [nil, 0] unless width && tag
+
+        [pos + width + tag + uint(bytes, pos, width), 0]
+      end
+
+      # A length cut short reads as zero, so the count runs off the end and
+      # stops there.
+      def self.uint(bytes, pos, width)
+        slice = bytes.byteslice(pos, width).to_s
+        return 0 if slice.bytesize < width
+
+        slice.unpack1(UINT.fetch(width)) # : Integer
+      end
+
+      private_class_method :step, :step_framed, :uint
+    end
+  end
+end

data/lib/kobako/codec.rb

@@ -5,6 +5,7 @@ require_relative "codec/utils"
 require_relative "codec/handle_walk"
 require_relative "codec/nesting"
 require_relative "codec/state"
+require_relative "codec/value_budget"
 require_relative "codec/ext_types"
 require_relative "codec/encoder"
 require_relative "codec/decoder"
@@ -23,5 +24,11 @@ module Kobako
     def self.track_handles(&block)
       State.current.track_handles(&block)
     end
+
+    # Holds every decode the block runs on this thread to +budget+ values,
+    # or to none when +budget+ is nil.
+    def self.within_value_budget(budget, &block)
+      State.current.within_value_budget(budget, &block)
+    end
   end
 end

data/lib/kobako/context.rb

@@ -17,12 +17,12 @@ module Kobako
   #
   #   sandbox.eval("Req::Current.user_id") { |ctx| ctx.bind("Req::Current", request) }
   class Context
-    def initialize(runtime:, services:, snippets:, flags:, extensions:) # :nodoc:
+    def initialize(runtime:, services:, extensions:, grants:, preamble:) # :nodoc:
       @runtime = runtime
       @services = services
-      @snippets = snippets
-      @flags = flags
       @extensions = extensions
+      @grants = grants
+      @preamble = preamble
       @resolved = {} # : Hash[String, Transport::Exposure]
       @overrides = {} # : Hash[String, Transport::Exposure]
       @handles = Catalog::Handles.new
@@ -45,6 +45,26 @@ module Kobako
       self
     end
 
+    # Use +filesystem+ for the mount at +at+ during this invocation only,
+    # with its own +access+ and block, as Sandbox#mount takes them. Returns
+    # +self+.
+    #
+    # Raises TypeError for a path that is no String or something other than
+    # a Filesystem, and ArgumentError when nothing was mounted at +at+ on the
+    # Sandbox, for a malformed path or an unknown access, or when called
+    # after the block has returned.
+    def mount(at, filesystem, access: :read, &policy)
+      raise ArgumentError, "Kobako::Context is spent; ctx.mount is only valid inside the #eval / #run block" if @spent
+
+      Runtime.validate_mount(at, access, filesystem)
+      mount = Catalog::Mount.new(at: at, access: access, filesystem: filesystem, policy: policy)
+      raise ArgumentError, "cannot override unmounted path #{at.inspect}" unless @grants.include?(mount)
+
+      mounts = @mounts ||= {} # : Hash[String, Catalog::Mount]
+      mounts[mount.key] = mount
+      self
+    end
+
     # A fillable left unfilled raises like an unbound path, so the guest's
     # call fails closed instead of reaching the sentinel.
     def lookup(path) # :nodoc:
@@ -57,21 +77,25 @@ module Kobako
 
     def eval(code, &block) # :nodoc:
       collect_overrides(&block) if block
-      invoke!(:eval) do
-        @runtime.eval(dispatch_handler, @services.paths, @snippets.entries, @flags.entries, code.b)
-      end
+      invoke(:eval) { @runtime.eval(dispatch_handler, setup, code.b) }
     end
 
     def run(request, &block) # :nodoc:
       collect_overrides(&block) if block
-      invoke!(:run, entrypoint: request.entrypoint) do
-        @runtime.run(dispatch_handler, @services.paths, @snippets.entries, @flags.entries,
-                     request.entrypoint.to_s, request.payload(@handles))
+      invoke(:run, entrypoint: request.entrypoint) do
+        @runtime.run(dispatch_handler, setup, request.entrypoint.to_s, request.encode_payload(@handles))
       end
     end
 
     private
 
+    # What the Runtime builds the invocation from: the Preamble's parts,
+    # then this invocation's mounts.
+    def setup
+      paths, snippets, flags = @preamble
+      [paths, snippets, flags, @grants.entries(@mounts || {})]
+    end
+
     # The Context is spent once the block returns, so a captured +ctx+ used
     # later raises. A block that raises propagates before the guest drives,
     # so the guest never runs and no Execution is produced.
@@ -83,17 +107,20 @@ module Kobako
 
     # Handed to the Runtime as a call argument, so the Runtime holds no
     # dispatch state and the Proc stays GC-rooted for the synchronous call.
+    # Built once per invocation, so every Call it answers shares one
+    # BlockFailure.
     def dispatch_handler
+      failure = Transport::BlockFailure.new
       lambda do |target, method_name, block_given, payload, guest_yielder|
         call = Transport::Call.new(target: target, method_name: method_name,
                                    block_given: block_given, payload: payload)
-        Transport::Dispatcher.dispatch(call, self, @handles, guest_yielder)
+        Transport::Dispatcher.dispatch(call, self, @handles, failure, guest_yielder)
       end
     end
 
     # Every Snapshot carries usage and captures, trap or not, so they stay
     # readable after a rescued trap.
-    def populate_observability!(snapshot)
+    def populate_observability(snapshot)
       @usage = Usage.new(wall_time: snapshot.wall_time, memory_peak: snapshot.memory_peak)
       @stdout_capture = Capture.new(bytes: snapshot.stdout, truncated: snapshot.stdout_truncated?)
       @stderr_capture = Capture.new(bytes: snapshot.stderr, truncated: snapshot.stderr_truncated?)
@@ -130,14 +157,14 @@ module Kobako
     # that raises propagates unwrapped and leaves the guest unrun. A
     # could-not-start fault ran no invocation at all, so it carries no
     # Execution and gains only the verb prefix.
-    def invoke!(verb, entrypoint: nil)
+    def invoke(verb, entrypoint: nil)
       @resolved = @extensions.resolve.transform_values { |object| Transport::Exposure.of(object) }
       begin
         snapshot = yield
       rescue Kobako::TrapError => e
         raise with_verb(e, verb)
       end
-      populate_observability!(snapshot)
+      populate_observability(snapshot)
       trap = snapshot.trap_error
       return settle_outcome(snapshot, verb, entrypoint) unless trap
 

data/lib/kobako/errors.rb

@@ -8,11 +8,7 @@ module Kobako
   # The base of every error kobako raises.
   class Error < StandardError; end
 
-  # Gives an invocation failure the Execution of the run that failed, so a
-  # rescue reads its captures and usage as a successful caller would.
-  # +execution+ is +nil+ when the failure came before the guest ran.
-  module CarriesExecution
-    # The Execution of the run that failed.
+  module Recorded # :nodoc:
     attr_reader :execution
 
     def with_execution(execution) # :nodoc:
@@ -23,8 +19,11 @@ module Kobako
 
   # The engine stopped the guest: a trap, a cap reached, or an outcome that
   # could not be read. The next invocation on the same Sandbox runs as usual.
+  # +execution+ is the failed run's Execution, so a rescue reads its captures
+  # and usage as a successful caller would; it is +nil+ when the failure came
+  # before the guest ran.
   class TrapError < Error
-    include CarriesExecution
+    include Recorded
   end
 
   # The invocation ran past its +timeout+.
@@ -41,10 +40,7 @@ module Kobako
   # The Guest Binary is missing at +wasm_path+.
   class ModuleNotBuiltError < SetupError; end
 
-  # What the guest reported about a failure.
-  module Diagnosable
-    # Where the failure came from (<tt>"sandbox"</tt> or <tt>"service"</tt>),
-    # the name of the class that raised it, and its backtrace.
+  module Diagnosable # :nodoc:
     attr_reader :origin, :klass, :backtrace_lines
 
     def initialize(message, origin: nil, klass: nil, backtrace_lines: nil) # :nodoc:
@@ -57,15 +53,19 @@ module Kobako
 
   # The guest failed: the script raised or did not compile, the Guest Binary
   # could not start the run, or what it produced could not be read.
+  # +origin+ (<tt>"sandbox"</tt> or <tt>"service"</tt>), +klass+ and
+  # +backtrace_lines+ say where it came from, which class raised it, and its
+  # backtrace. +execution+ is the failed run's Execution, as on TrapError.
   class SandboxError < Error
     include Diagnosable
-    include CarriesExecution
+    include Recorded
   end
 
-  # A Service call failed and the guest left it unrescued.
+  # A Service call failed and the guest left it unrescued. It carries
+  # +origin+, +klass+, +backtrace_lines+ and +execution+ as SandboxError does.
   class ServiceError < Error
     include Diagnosable
-    include CarriesExecution
+    include Recorded
   end
 
   # The call reached no Service method: nothing is bound there, the Handle
@@ -73,7 +73,8 @@ module Kobako
   # same on purpose, so a target discloses nothing about what it defines.
   class NoServiceError < ServiceError; end
 
-  # The call reached the Service method with arguments that did not fit.
+  # The Service method refused its arguments: the call would not bind, or
+  # the method raised +ArgumentError+ over what it was given.
   class ServiceArgumentError < ServiceError; end
 
   # Raised at a Service's +yield+ when the guest block raised; rescue it as

data/lib/kobako/filesystem.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Kobako
+  # The Filesystems a Sandbox can mount for the guest's +File+, each
+  # answered in Rust by the kind of the same name. Hand one to
+  # Sandbox#mount:
+  #
+  #   sandbox.mount("/data", Kobako::Filesystem::Tmpfs.new("config.yml" => yaml))
+  #
+  # [<tt>Tmpfs.new(files = {}, size: 64 MiB, nr_inodes:)</tt>]
+  #   Files held in memory for as long as the object lives, seeded from a
+  #   Hash of path to contents. Every invocation shares them; one that
+  #   should start empty mounts a new Tmpfs through Context#mount.
+  # [<tt>Bind.new(path)</tt>]
+  #   A host directory and everything beneath it. Nothing outside it is
+  #   reachable, a symbolic link pointing out included.
+  # [<tt>Overlay.new(lower: [filesystem, ...], upper: tmpfs)</tt>]
+  #   Read-only lower Layers, topmost first, under an upper Tmpfs that
+  #   takes every change, as Linux's overlayfs stacks them. Without
+  #   +upper+ the view is read-only and needs two lower Layers. It takes
+  #   at most 500 lower Layers and stacks at most two Overlays deep.
+  #
+  # A Tmpfs is bounded as a tmpfs mount is: its files hold
+  # at most +size+ bytes together, and it holds at most +nr_inodes+ files and
+  # directories, its root among them; +nil+ lifts either bound. Without
+  # +nr_inodes+ it holds one for each 4 KiB of +size+, and the root. Past
+  # either, the guest raises Errno::ENOSPC.
+  #
+  # Any object answering +open+ and +stat+ mounts too, as a Filesystem
+  # written in Ruby; its methods take the names of +File+, +Dir+, and +IO+.
+  # Its +stat+ answers +directory?+, +size+, and +ino+, an +ino+ naming one
+  # directory for as long as the guest holds it open. Its names match
+  # exactly, as a mount's block judges them as given. A name may hold a
+  # <tt>\\</tt>, which the guest's paths never separate on, so one joined
+  # to a Windows host path is the Filesystem's to refuse.
+  #
+  # Each method beyond +open+ and +stat+ is optional, and a change it lacks
+  # raises <tt>Errno::EROFS</tt> in the guest:
+  #
+  # [<tt>children(path)</tt>]
+  #   Entry names, as Dir.children gives them.
+  # [<tt>mkdir(path)</tt>, <tt>rmdir(path)</tt>, <tt>unlink(path)</tt>, <tt>rename(from, to)</tt>]
+  #   The changes a writable mount passes on.
+  #
+  # A +stat+ may also answer +dev+, else the Filesystem stands for one
+  # device, and +ftype+, which says a FIFO, a socket, or a device is one
+  # so the guest's open is refused without asking +open+.
+  #
+  # The file +open+ answers takes the guest's reads and writes, each named
+  # as +IO+ names it:
+  #
+  # [<tt>pread(length, offset)</tt>, +size+]
+  #   Required: the bytes there, +nil+ or EOFError at the end, and the
+  #   length.
+  # [<tt>pwrite(data, offset)</tt>, <tt>truncate(length)</tt>]
+  #   The bytes written, and nothing; without them a write raises
+  #   <tt>Errno::EROFS</tt>.
+  # [<tt>append(data)</tt>]
+  #   Writes all of +data+ at the end in one step, so another writer's
+  #   append never lands over it, and answers where the file then ends;
+  #   without it an append raises <tt>Errno::ENOTSUP</tt>.
+  # [+fsync+, +close+]
+  #   Nothing; without them there is nothing to flush or release.
+  # [+stat+]
+  #   What <tt>stat(path)</tt> answers, for the file's times and count of
+  #   names; without it the file has one name and no time.
+  module Filesystem
+  end
+end