kobako 0.27.0 → 0.29.0

data/sig/kobako/catalog/mount.rbs

@@ -0,0 +1,28 @@
+module Kobako
+  module Catalog
+    class Mount < Data
+      type access = Kobako::Filesystem::access
+
+      type policy = ^(String path, access access) -> boolish
+
+      type tuple = [String, access, Kobako::Filesystem::mountable, policy?]
+
+      attr_reader at: String
+      attr_reader access: access
+      attr_reader filesystem: Kobako::Filesystem::mountable
+      attr_reader policy: policy?
+
+      def self.new: (at: untyped, access: untyped, filesystem: untyped, policy: policy?) -> Mount
+
+      def key: () -> String
+
+      def conflict: (Mount other) -> String?
+
+      def to_native: () -> tuple
+
+      private
+
+      def nested?: (String other) -> bool
+    end
+  end
+end

data/sig/kobako/catalog/services.rbs

@@ -1,7 +1,7 @@
 module Kobako
   module Catalog
     class Services
-      NAME_PATTERN: Regexp
+      RESERVED_NAMESPACE: String
 
       def initialize: () -> void
 
@@ -13,14 +13,12 @@ module Kobako
 
       def paths: () -> Array[String]
 
-      def seal!: () -> self
-
-      def sealed?: () -> bool
-
       private
 
       def validate_path!: (Symbol | String path) -> String
 
+      def reserved?: (String path) -> bool
+
       def collision?: (String path) -> bool
     end
   end

data/sig/kobako/catalog/snippets.rbs

@@ -1,21 +1,21 @@
 module Kobako
   module Catalog
     class Snippets
-      NAME_PATTERN: Regexp
-
-      type entry = Kobako::Snippet::Source | Kobako::Snippet::Binary
+      type entry = Kobako::Snippet::Source | Kobako::Snippet::Bytecode
 
       type tuple = [Symbol, String?, String]
 
       def initialize: () -> void
 
-      def register: (?code: String?, ?name: (Symbol | String)?, ?binary: String?) -> (Symbol | nil)
+      def register: (?code: String?, ?name: (Symbol | String)?, ?binary: String?) -> nil
 
       def entries: () -> Array[tuple]
 
+      def compile: () { (Array[tuple] entries) -> Array[String]? } -> nil
+
       private
 
-      def register_source!: (String? code, (Symbol | String)? name) -> Symbol
+      def register_source!: (String? code, (Symbol | String)? name) -> nil
 
       def ensure_source_args!: (String? code, (Symbol | String)? name) -> [String, Symbol | String]
 

data/sig/kobako/catalog.rbs

@@ -1,4 +1,5 @@
 module Kobako
   module Catalog
+    def self.to_utf8!: (String text, String what) -> String
   end
 end

data/sig/kobako/codec/ext_types.rbs

@@ -5,21 +5,23 @@ module Kobako
       EXT_HANDLE: Integer
       UNREPRESENTABLE_GUARD_ID: Integer
 
-      def self?.build_factory: () -> MessagePack::Factory
+      def self.build_factory: () -> MessagePack::Factory
 
-      def self?.pack_symbol: (Symbol symbol) -> String
+      private
 
-      def self?.unpack_symbol: (String payload) -> Symbol
+      def self.pack_symbol: (Symbol symbol) -> String
 
-      def self?.pack_handle: (Kobako::Handle handle) -> String
+      def self.unpack_symbol: (String payload) -> Symbol
 
-      def self?.unpack_handle: (String payload, State state) -> Kobako::Handle
+      def self.pack_handle: (Kobako::Handle handle) -> String
 
-      def self?.register_symbol: (MessagePack::Factory factory) -> void
+      def self.unpack_handle: (String payload, State state) -> Kobako::Handle
 
-      def self?.register_handle: (MessagePack::Factory factory) -> void
+      def self.register_symbol: (MessagePack::Factory factory) -> void
 
-      def self?.register_unrepresentable: (MessagePack::Factory factory) -> void
+      def self.register_handle: (MessagePack::Factory factory) -> void
+
+      def self.register_unrepresentable: (MessagePack::Factory factory) -> void
     end
 
     FACTORY: MessagePack::Factory

data/sig/kobako/codec/handle_walk.rbs

@@ -3,19 +3,21 @@ module Kobako
     module HandleWalk
       MSGPACK_INT_RANGE: Range[Integer]
 
-      def self?.representable?: (untyped value, ?Integer depth) -> bool
+      def self.representable?: (untyped value, ?Integer depth) -> bool
 
-      def self?.deep_wrap: (untyped value, Kobako::Codec::_HandleTable handler, ?Integer depth) -> untyped
+      def self.deep_wrap: (untyped value, Kobako::Codec::_HandleTable handles, ?Integer depth) -> untyped
 
-      def self?.guard_nesting!: (Integer depth) -> void
+      def self.deep_restore: (untyped value, Kobako::Codec::_HandleTable handles) -> untyped
 
-      def self?.deep_wrap_hash: (Hash[untyped, untyped] hash, Kobako::Codec::_HandleTable handler, Integer depth) -> Hash[untyped, untyped]
+      private
 
-      def self?.deep_restore: (untyped value, Kobako::Codec::_HandleTable handler) -> untyped
+      def self.guard_nesting!: (Integer depth) -> void
 
-      def self?.primitive_type?: (untyped value) -> bool
+      def self.deep_wrap_hash: (Hash[untyped, untyped] hash, Kobako::Codec::_HandleTable handles, Integer depth) -> Hash[untyped, untyped]
 
-      def self?.container_representable?: (untyped value, Integer depth) -> bool
+      def self.primitive_type?: (untyped value) -> bool
+
+      def self.container_representable?: (untyped value, Integer depth) -> bool
     end
   end
 end

data/sig/kobako/codec/state.rbs

@@ -5,8 +5,14 @@ module Kobako
 
       def self.current: () -> State
 
+      @carried_handle: bool
+      @value_budget: Integer?
+
+      attr_reader value_budget: Integer?
+
       def track_handles: [T] { () -> T } -> [T, bool]
-      def record_handle!: () -> void
+      def record_handle: () -> void
+      def within_value_budget: [T] (Integer? budget) { () -> T } -> T
 
       private
 

data/sig/kobako/codec/utils.rbs

@@ -1,9 +1,9 @@
 module Kobako
   module Codec
     module Utils
-      def self?.assert_utf8!: (String string, String label) -> void
+      def self.assert_utf8!: (String string, String label) -> void
 
-      def self?.with_boundary: [T] () { () -> T } -> T
+      def self.with_boundary: [T] () { () -> T } -> T
     end
   end
 end

data/sig/kobako/codec/value_budget.rbs

@@ -0,0 +1,23 @@
+module Kobako
+  module Codec
+    module ValueBudget
+      SCALARS: Hash[Integer, Integer]
+
+      COUNTS: Hash[Integer, [Integer, Integer]]
+
+      LENGTHS: Hash[Integer, [Integer, Integer]]
+
+      UINT: Hash[Integer, String]
+
+      def self.assert_within!: (String bytes, Integer? budget) -> void
+
+      private
+
+      def self.step: (String bytes, Integer pos) -> [Integer?, Integer]
+
+      def self.step_framed:(String bytes, Integer pos, Integer marker) -> [Integer?, Integer]
+
+      def self.uint: (String bytes, Integer pos, Integer width) -> Integer
+    end
+  end
+end

data/sig/kobako/codec.rbs

@@ -14,11 +14,13 @@ module Kobako
 
     def self.track_handles: [T] { () -> T } -> [T, bool]
 
+    def self.within_value_budget: [T] (Integer? budget) { () -> T } -> T
+
     # The Handle allocator/resolver a wire walk works against: alloc
     # registers a non-wire-representable object and returns its Handle,
     # fetch resolves a wire Handle id back to the live object. The
-    # Sandbox's Kobako::Catalog::Handles is the production conformer;
-    # modelled structurally so the Codec and Transport tiers need no
+    # Kobako::Catalog::Handles each invocation mints is the production
+    # conformer; modelled structurally so the Codec and Transport tiers need no
     # upward dependency on Catalog.
     interface _HandleTable
       def alloc: (untyped object) -> Kobako::Handle

data/sig/kobako/constant_name.rbs

@@ -0,0 +1,3 @@
+module Kobako
+  CONSTANT_NAME: Regexp
+end

data/sig/kobako/context.rbs

@@ -1,14 +1,21 @@
 module Kobako
   class Context
+    type preamble = [Array[String], Array[Kobako::Catalog::Snippets::tuple], Array[Kobako::Catalog::Flags::tuple]]
+
+    @mounts: Hash[String, Kobako::Catalog::Mount]?
+
     def initialize: (
       runtime: Kobako::Runtime,
       services: Kobako::Catalog::Services,
-      snippets: Kobako::Catalog::Snippets,
-      extensions: Kobako::Catalog::Extensions
+      extensions: Kobako::Catalog::Extensions,
+      grants: Kobako::Catalog::Grants,
+      preamble: preamble
     ) -> void
 
     def bind: (Symbol | String path, untyped object) -> self
 
+    def mount: (String at, Kobako::Filesystem::mountable filesystem, ?access: Kobako::Filesystem::access) ?{ (String path, Kobako::Filesystem::access access) -> boolish } -> self
+
     def lookup: (Symbol | String path) -> Kobako::Transport::Exposure
 
     def eval: (String code) ?{ (Kobako::Context) -> void } -> Kobako::Execution
@@ -17,20 +24,20 @@ module Kobako
 
     private
 
+    def setup: () -> Kobako::Runtime::setup
+
     def collect_overrides: () { (Kobako::Context) -> void } -> void
 
     def dispatch_handler: () -> Kobako::Transport::dispatch_proc
 
-    def populate_observability!: (Kobako::Runtime::Snapshot snapshot) -> void
-
-    def trap_class_for: (Kobako::TrapError err) -> singleton(Kobako::TrapError)
+    def populate_observability:(Kobako::Snapshot snapshot) -> void
 
-    def trap_error_for: (Kobako::Runtime::Snapshot snapshot, Symbol verb) -> Kobako::TrapError
+    def with_verb: (Kobako::TrapError err, Symbol verb) -> Kobako::TrapError
 
     def build_execution: (untyped value, failed: bool) -> Kobako::Execution
 
-    def settle_outcome: (Kobako::Runtime::Snapshot snapshot, Symbol verb, Symbol? entrypoint) -> Kobako::Execution
+    def settle_outcome: (Kobako::Snapshot snapshot, Symbol verb, Symbol? entrypoint) -> Kobako::Execution
 
-    def invoke!: (Symbol verb, ?entrypoint: Symbol?) { () -> Kobako::Runtime::Snapshot } -> Kobako::Execution
+    def invoke!: (Symbol verb, ?entrypoint: Symbol?) { () -> Kobako::Snapshot } -> Kobako::Execution
   end
 end

data/sig/kobako/errors.rbs

@@ -2,14 +2,14 @@ module Kobako
   class Error < StandardError
   end
 
-  module CarriesExecution
+  module Recorded
     attr_reader execution: Kobako::Execution?
 
     def with_execution: (Kobako::Execution execution) -> self
   end
 
   class TrapError < Error
-    include CarriesExecution
+    include Recorded
   end
 
   class TimeoutError < TrapError
@@ -39,12 +39,12 @@ module Kobako
 
   class SandboxError < Error
     include Diagnosable
-    include CarriesExecution
+    include Recorded
   end
 
   class ServiceError < Error
     include Diagnosable
-    include CarriesExecution
+    include Recorded
   end
 
   class NoServiceError < ServiceError
@@ -60,12 +60,18 @@ module Kobako
   class YieldValueError < Error
   end
 
+  class UnsupportedError < Error
+  end
+
   class HandleExhaustedError < SandboxError
   end
 
   class BytecodeError < SandboxError
   end
 
+  class UnsupportedFlagError < SandboxError
+  end
+
   class UndefinedEntrypointError < SandboxError
     attr_reader name: Symbol?
     attr_reader available: Array[Symbol]

data/sig/kobako/filesystem.rbs

@@ -0,0 +1,88 @@
+module Kobako
+  module Filesystem
+    type mountable = Memory | Temporary | Directory | Overlay | _Readable
+
+    type access = :read | :read_write
+
+    # What a Filesystem written in Ruby answers to be mounted. One that
+    # also answers _Listable lists its directories, and one answering
+    # _Writable takes changes too; each method it lacks is refused alone.
+    interface _Readable
+      def open: (String path, Integer flags) -> _File
+      def stat: (String path) -> _Stat
+    end
+
+    interface _Listable
+      def children: (String path) -> Array[String]
+    end
+
+    interface _Writable
+      def mkdir: (String path) -> void
+      def rmdir: (String path) -> void
+      def unlink: (String path) -> void
+      def rename: (String from, String to, directory: bool?) -> void
+    end
+
+    # A file a Filesystem written in Ruby opened; +::File+ answers it. One
+    # that also answers _WritableFile takes writes too, one answering
+    # _AppendableFile takes appends, and any file may answer _SyncableFile
+    # to flush or _ClosableFile to close.
+    interface _File
+      def pread: (Integer length, Integer offset) -> String?
+      def size: () -> Integer
+    end
+
+    interface _WritableFile
+      def pwrite: (String data, Integer offset) -> Integer
+      def truncate: (Integer length) -> void
+    end
+
+    # Writes all of +data+ at the end in one step, answering where the file
+    # then ends.
+    interface _AppendableFile
+      def append: (String data) -> Integer
+    end
+
+    interface _SyncableFile
+      def fsync: () -> void
+    end
+
+    interface _ClosableFile
+      def close: () -> void
+    end
+
+    # What a Filesystem written in Ruby's +stat+ answers, as +File::Stat+
+    # does; an +ino+ of zero names no identity. One that also answers
+    # _StatDevice names the device its +ino+ belongs to.
+    interface _Stat
+      def directory?: () -> boolish
+      def size: () -> Integer
+      def ino: () -> Integer
+    end
+
+    interface _StatDevice
+      def dev: () -> Integer
+    end
+
+    class Memory
+      # A bare <tt>"path" => contents</tt> arrives as keywords, which RBS
+      # cannot key by String; a Symbol keyword past +limit+ and +inodes+
+      # raises ArgumentError.
+      def initialize: (?Hash[String, String] files, ?limit: Integer?, ?inodes: Integer?, **String) -> void
+    end
+
+    class Temporary
+      def initialize: (?limit: Integer?, ?inodes: Integer?) -> void
+    end
+
+    class Directory
+      def initialize: (String path) -> void
+    end
+
+    class Overlay
+      def initialize: () -> void
+      def layer: (mountable filesystem, ?access: access) -> Overlay
+    end
+
+  end
+end

data/sig/kobako/guest_yielder.rbs

@@ -0,0 +1,9 @@
+module Kobako
+  # Frame-scoped guest re-entry handle the ext hands the dispatch Proc as
+  # its last argument — the production conformer of
+  # +Kobako::Transport::_GuestYielder+, answering the Yield Reply already
+  # split off the core envelope.
+  class GuestYielder
+    def call: (String args_bytes) -> [Symbol, String, String?]
+  end
+end

data/sig/kobako/outcome.rbs

@@ -6,18 +6,16 @@ module Kobako
 
     type panic_fields = [String, String, String, Array[String], Array[String]]
 
-    def self?.reify: (Symbol kind, String payload, panic_fields? panic, ?entrypoint: Symbol?) -> Kobako::Codec::wire_value
+    def self.reify: (String payload, panic_fields? panic, ?entrypoint: Symbol?) -> Kobako::Codec::wire_value
 
-    # Everything below is private_class_method at runtime; RBS cannot mark a
-    # `self?` method private, so the declarations stay visible to the checker.
-    def self?.panic_error: (panic_fields panic, Symbol? entrypoint) -> (SandboxError | ServiceError)
+    private
 
-    def self?.error_class: (String origin, String klass) -> (singleton(SandboxError) | singleton(ServiceError))
+    def self.panic_error: (panic_fields panic, Symbol? entrypoint) -> (SandboxError | ServiceError)
 
-    def self?.trap_error: (Symbol kind) -> TrapError
+    def self.error_class: (String origin, String klass) -> (singleton(SandboxError) | singleton(ServiceError))
 
-    def self?.decode_value: (String payload) -> Kobako::Codec::wire_value
+    def self.decode_value: (String payload) -> Kobako::Codec::wire_value
 
-    def self?.wire_error: (String message, ?diagnostic: String?) -> Transport::Error
+    def self.wire_error: (String message, ?diagnostic: String?) -> Transport::Error
   end
 end

data/sig/kobako/pool.rbs

@@ -31,7 +31,7 @@ module Kobako
 
     def checkin: (Kobako::Sandbox sandbox) -> void
 
-    def release_capacity!: () -> void
+    def release_capacity: () -> void
 
     def monotonic_now: () -> Float
 

data/sig/kobako/runtime.rbs

@@ -2,62 +2,38 @@ module Kobako
   class Runtime
     def self.default_path: () -> String
 
+    def self.validate_mount!: (untyped at, untyped access, untyped filesystem) -> nil
+
     def self.from_path: (
       String path,
-      (Float | Integer)? timeout_seconds,
-      Integer? memory_limit,
-      Integer? stdout_limit,
-      Integer? stderr_limit,
-      Symbol profile,
-      Symbol gvl
+      timeout: (Float | Integer)?,
+      setup_timeout: (Float | Integer)?,
+      memory_limit: Integer?,
+      stdout_limit: Integer?,
+      stderr_limit: Integer?,
+      open_file_limit: Integer?,
+      profile: Symbol,
+      gvl: Symbol
     ) -> Runtime
 
-    def eval: (
-      Kobako::Transport::dispatch_proc dispatch,
-      Array[String] paths,
-      String source,
-      Array[Kobako::Catalog::Snippets::tuple] snippets
-    ) -> Kobako::Runtime::Snapshot
+    type setup = [
+      Array[String],
+      Array[Kobako::Catalog::Snippets::tuple],
+      Array[Kobako::Catalog::Flags::tuple],
+      Array[Kobako::Catalog::Mount::tuple]
+    ]
+
+    def eval: (Kobako::Transport::dispatch_proc dispatch, setup setup, String source) -> Kobako::Snapshot
 
     def run: (
       Kobako::Transport::dispatch_proc dispatch,
-      Array[String] paths,
-      Array[Kobako::Catalog::Snippets::tuple] snippets,
+      setup setup,
       String entrypoint,
       String payload
-    ) -> Kobako::Runtime::Snapshot
+    ) -> Kobako::Snapshot
 
     def profile: () -> Symbol
 
-    # Frame-scoped guest re-entry handle the ext hands the dispatch Proc as
-    # its last argument — the production conformer of
-    # +Kobako::Transport::_GuestYielder+, answering the Yield Reply already
-    # split off the core envelope.
-    class GuestYielder
-      def call: (String args_bytes) -> [Symbol, String, String?]
-    end
-
-    # One invocation's result — the whole Snapshot the driver produced.
-    class Snapshot
-      def outcome: () -> [Symbol, String, Kobako::Outcome::panic_fields?]
-
-      def trapped?: () -> bool
-
-      def trap_kind: () -> Symbol?
-
-      def trap_message: () -> String?
-
-      def wall_time: () -> Float
-
-      def memory_peak: () -> Integer
-
-      def stdout: () -> String
-
-      def stdout_truncated?: () -> bool
-
-      def stderr: () -> String
-
-      def stderr_truncated?: () -> bool
-    end
+    def compile: (Kobako::Context::preamble preamble) -> Array[String]?
   end
 end

data/sig/kobako/sandbox.rbs

@@ -7,14 +7,16 @@ module Kobako
 
     # Forwarded to @options via Forwardable#def_delegators.
     def timeout: () -> Float?
+    def setup_timeout: () -> Float?
     def memory_limit: () -> Integer?
     def stdout_limit: () -> Integer?
     def stderr_limit: () -> Integer?
+    def open_file_limit: () -> Integer?
     def profile: () -> Symbol
     def gvl: () -> Symbol
 
     # Every keyword beyond wasm_path forwards verbatim to
-    # SandboxOptions.new (the four caps + the profile floor).
+    # SandboxOptions.new (the caps + the profile floor).
     def initialize: (
       ?wasm_path: String?,
       **untyped options
@@ -24,9 +26,13 @@ module Kobako
 
     def install: (*untyped extensions) -> Kobako::Sandbox
 
+    def mount: (String at, Kobako::Filesystem::mountable filesystem, ?access: Kobako::Filesystem::access) ?{ (String path, Kobako::Filesystem::access access) -> boolish } -> Kobako::Sandbox
+
     def preload: (code: String, name: Symbol | String) -> Kobako::Sandbox
                | (binary: String) -> Kobako::Sandbox
 
+    def flag: (Symbol | String name, ?String value, ?advisory: bool) -> Kobako::Sandbox
+
     def run: (Symbol | String target, *untyped args, **untyped kwargs) ?{ (Kobako::Context) -> void } -> Kobako::Execution
 
     def eval: (String code) ?{ (Kobako::Context) -> void } -> Kobako::Execution
@@ -37,6 +43,10 @@ module Kobako
 
     def new_invocation: () -> Kobako::Context
 
+    def preamble: (Array[Kobako::Catalog::Snippets::tuple] snippets) -> Kobako::Context::preamble
+
+    def refuse_once_invoked!: (String verb) -> void
+
     def begin_invocation!: () -> void
   end
 end

data/sig/kobako/sandbox_options.rbs

@@ -1,50 +1,68 @@
 module Kobako
   class SandboxOptions < Data
     DEFAULT_TIMEOUT_SECONDS: Float
+    DEFAULT_SETUP_TIMEOUT_SECONDS: Float
     DEFAULT_MEMORY_LIMIT: Integer
     DEFAULT_OUTPUT_LIMIT: Integer
+    DEFAULT_OPEN_FILE_LIMIT: Integer
     DEFAULT_PROFILE: Symbol
     PROFILES: Array[Symbol]
     GVL_MODES: Array[Symbol]
     DEFAULT_GVL: Symbol
+    VALUE_BYTES: Integer
 
     attr_reader timeout: Float?
+    attr_reader setup_timeout: Float?
     attr_reader memory_limit: Integer?
     attr_reader stdout_limit: Integer?
     attr_reader stderr_limit: Integer?
+    attr_reader open_file_limit: Integer?
     attr_reader profile: Symbol
     attr_reader gvl: Symbol
 
     def self.new: (
       ?timeout: (Float | Integer)?,
+      ?setup_timeout: (Float | Integer)?,
       ?memory_limit: Integer?,
       ?stdout_limit: Integer?,
       ?stderr_limit: Integer?,
+      ?open_file_limit: Integer?,
       ?profile: Symbol,
       ?gvl: Symbol
     ) -> SandboxOptions
 
     def initialize: (
       ?timeout: (Float | Integer)?,
+      ?setup_timeout: (Float | Integer)?,
       ?memory_limit: Integer?,
       ?stdout_limit: Integer?,
       ?stderr_limit: Integer?,
+      ?open_file_limit: Integer?,
       ?profile: Symbol,
       ?gvl: Symbol
     ) -> void
 
-    def enforce_floor!: (Symbol declared) -> void
+    def to_h: () -> {
+      timeout: Float?,
+      setup_timeout: Float?,
+      memory_limit: Integer?,
+      stdout_limit: Integer?,
+      stderr_limit: Integer?,
+      open_file_limit: Integer?,
+      profile: Symbol,
+      gvl: Symbol
+    }
 
-    private
+    def value_budget: () -> Integer?
 
-    def normalize_timeout: ((Float | Integer)? timeout) -> Float?
+    def enforce_floor!: (Symbol declared) -> void
 
-    def normalize_memory_limit: (Integer? memory_limit) -> Integer?
+    private
 
-    def normalize_output_limit: (Integer? limit, String name) -> Integer?
+    def normalize_timeout: ((Float | Integer)? timeout, String name) -> Float?
 
-    def normalize_profile: (untyped profile) -> Symbol
+    def normalize_limit: (Integer? limit, String name) -> Integer?
 
-    def normalize_gvl: (untyped gvl) -> Symbol
+    def normalize_choice: (untyped value, Array[Symbol] choices, String name) -> Symbol
   end
 end