ruby_wasm_ic_installer 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f2034d8defd5e242028c4055f48b77e5f08207eec658342d200923fe0b4257bb
+  data.tar.gz: 6e0ecb432de1e379a7ef8249737b578c5707048964abaeb161e68fab89ce4a32
+SHA512:
+  metadata.gz: ff062dcf67d25bd281b022120753aec1e94d126ba1e35bd5bf4028b676df59ddc70779057ba8e70a523d0a936ca3ae3e0acaad893807b7d7bf605b4bf92060e1
+  data.tar.gz: 11bd41e69ac06831ea4ab68e25bc6dcf40e4527a16c1f269c2f74b876ea3c4b78959e59722cc038bfd44b842980496887b10f7fa449c9c52a4e18ac459db90a9

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 the ruby_wasm_builder authors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,189 @@
+# ruby_wasm_ic_installer
+
+Install pure-Ruby gems into a Ruby canister on the Internet Computer, through
+calls, after it is deployed: the **Installer** for canisters packed by
+[ruby_wasm_builder](https://gitlab.com/phrug/ruby_wasm_builder).
+
+A packed Application carries its code in a 1 MiB buffer. Gems installed with
+this gem live in the canister's `/data` instead, so neither the buffer nor the
+module's size bounds them: Rack and Roda whole are 224 files and 1.1 MB, sent
+in one or a few calls, and the canister boots them within 2% of the same
+Application packed (measured on PocketIC; ruby_wasm_builder's W28).
+
+```bash
+ruby_wasm_ic_installer setup my_app        # once: wire the Installer into the Application
+# pack and deploy my_app as usual (pack.rb, icp deploy)
+ruby_wasm_ic_installer install my_app      # send the Gemfile.lock's gems the canister lacks
+icp deploy --mode upgrade                  # they load at the next boot
+```
+
+## What it does
+
+**Off chain,** `install` reads the Application's `Gemfile.lock` with Bundler's
+own parser (it resolves nothing: the lock is yours) and, for each locked gem:
+
+- fetches its `.gem` for platform `ruby` with `gem fetch` into a cache
+  (`~/.cache/ruby_wasm_ic_installer`), checking it against the lock's
+  `CHECKSUMS` when the lock has them;
+- **refuses** it if it has a C extension, or is locked only for a native
+  platform: a canister cannot load compiled code, so only pure Ruby can be
+  installed;
+- **skips** it, saying so, if `ruby_wasm_ic_minimal` is in the lock and stands
+  in for it (`stringio`, `strscan`, `date`), since the real ones are C
+  extensions;
+- opens only its `require_paths` (normally `lib/`);
+- **rewrites magic comments** naming an alias of an encoding a `minimal`
+  canister has (`# encoding: binary` to `ascii-8bit`, `ascii` to `us-ascii`),
+  and **refuses** a file in an encoding it lacks (`ISO-8859-1`, `Shift_JIS`).
+  A canister knows twelve encodings, each by one name and no alias, and reads
+  the comment before any Ruby runs. Every rewrite is in the report.
+
+It asks the canister what it has (`installed`), and sends **only the gem
+versions it lacks**, packed into calls of up to 2,000,000 bytes (the IC's
+ingress limit is 2 MiB). Then it writes the canister's **setup file**, last.
+Nothing changes what the canister runs until the **next upgrade**, which loads
+the new setup file; `install` says so and does not upgrade for you.
+
+**On the canister,** the canister half keeps one directory per gem version:
+
+```
+/data/gems/<name>-<version>/lib/...       a complete version
+/data/gems/.partial/<name>-<version>/     a version still arriving
+/data/setup.rb                            the setup file: a generation number and the load paths
+```
+
+A version arrives into `.partial` and is renamed into place when complete, so
+a run that stops half way leaves nothing half-installed (the next run clears
+it and sends the version again). The setup file puts each gem's load path on
+`$LOAD_PATH` at boot, in the lock's order, after `/app` (so anything you pack
+still wins) and before Ruby's own library.
+
+**Removing** a version is never automatic. `prune` removes every version that
+neither the running boot nor the pending setup file names; the canister
+refuses to remove one that either needs (Rack loads files lazily, through
+`autoload`, long after boot). Until you prune, you can go back by installing
+the previous lock again.
+
+**Only the canister's controllers** may install, commit or remove: the
+canister asks the IC whether the caller is one. `--identity` chooses who signs;
+whoever can upgrade the canister can install code into it, and no one else.
+`installed` is a public query: anyone can read which generation runs and which
+gem versions are there.
+
+## Wiring it into an Application: `setup`
+
+```bash
+ruby_wasm_ic_installer setup my_app [--yes | --check]
+```
+
+`setup` makes three changes, each between marker comments
+(`# >>> ruby_wasm_ic_installer` … `# <<< ruby_wasm_ic_installer`):
+
+- in **`ic-interface.rb`**, the Installer's four Declarations and their types:
+
+  ```ruby
+  type :InstallFile,   record(path: Text, body: Blob)
+  type :InstallSetup,  record(generation: Nat64, load_paths: Vec[Text])
+  type :InstallCommit, record(gems: Vec[Text], setup: Opt[:InstallSetup])
+  type :Installed,     record(running: Opt[Nat64], pending: Opt[Nat64], gems: Vec[Text], partial: Vec[Text],
+                              load_paths: Vec[Text], running_paths: Vec[Text])
+  update :install_put,    takes: [Vec[:InstallFile]], returns: Text
+  update :install_commit, takes: [:InstallCommit],    returns: Text
+  update :install_remove, takes: [Text],              returns: Text
+  query  :installed,      takes: [],                  returns: :Installed
+  ```
+
+- at the top of **`app.rb`** (after any shebang and magic comments), the
+  `require` of the canister half, which defines those four methods and loads
+  `/data/setup.rb` if there is one;
+- the canister half itself, copied to **`vendor/ruby_wasm_ic_installer/`**.
+  It uses only core Ruby and ruby_wasm_builder's `IC`, and loads on `minimal`.
+
+Running it again changes nothing. If the lines between the markers, or the
+vendored file, differ from what `setup` would write (your edit, or an older
+version's), it shows the diff and asks before writing; with no terminal it
+aborts unless `--yes`. If the Installer's names are already declared or
+defined outside the markers, it stops and shows where. `--check` prints the
+diffs and exits 1 if anything would change (for CI).
+
+The Application needs an `ic-interface.rb` already (one with no Interface file
+is served `run` alone). Pack and deploy it again after `setup`.
+
+Then require your installed gems in `app.rb` as usual, after the Installer's
+block. Before the first install and upgrade they are not there yet, so an
+Application that should boot either way rescues `LoadError`:
+
+```ruby
+APP = begin
+  require "ruby_wasm_ic_minimal"   # first, on minimal: the Encoding constants and stand-ins
+  require "ruby_wasm_ic_rack"
+  require "roda"
+  # ... your Roda app ...
+rescue LoadError
+  nil
+end
+```
+
+## Commands
+
+```
+ruby_wasm_ic_installer install CANISTER [--lock Gemfile.lock] [--dry-run] [icp options]
+ruby_wasm_ic_installer status  CANISTER [icp options]
+ruby_wasm_ic_installer prune   CANISTER [--dry-run] [icp options]
+ruby_wasm_ic_installer setup   APP_DIR  [--yes | --check]
+```
+
+`CANISTER` is the canister's name in your `icp.yaml`, or its principal. icp
+options pass through to `icp canister call`: `-e/--environment`,
+`-n/--network`, `--identity`, `--project-root` (icp's
+`--project-root-override`) and `--icp PATH`. Other options: `--cache DIR`,
+`--budget BYTES`.
+
+Every call goes through `icp canister call <canister> <method> --args-file
+<file> --args-format bin -o hex`, so it needs [icp-cli](https://cli.internetcomputer.org)
+1.6 or later. The gem encodes and decodes its few Candid types itself; it
+holds no keys and picks no network.
+
+Exit status: 0 done, 1 refused (by the canister, or by `setup`'s questions),
+2 a usage error or a gem it cannot install.
+
+## Limits
+
+- **Pure Ruby only.** A gem with a C extension reaches a canister only linked
+  into its Base Module.
+- **Gems from a gem server only;** a `git` or `path` source in the lock is
+  refused.
+- **A single file larger than one call** (about 2 MB) cannot be sent.
+- **The twelve encodings** are those a `minimal` canister was observed to have
+  (ruby_wasm_builder 0.6.0 to 0.8.0); a Build with more is a release of this gem.
+- The canister keeps no content hash of what it holds yet: `installed` reports
+  versions, not digests.
+
+## Development
+
+```bash
+bundle install
+bundle exec rake          # every spec on MRI, no network; fails below 95% line coverage
+bundle exec rake e2e      # the end-to-end spec on a local icp-cli network
+```
+
+The specs run the real canister half on MRI over a temporary `/data`, behind
+the same seam the command uses to call icp-cli, with real `.gem` files built
+by the specs and a stand-in for ruby_wasm_builder's `IC`. The Candid encoder
+is held byte for byte to what `@dfinity/didc` encodes for the same values
+(`spec/fixtures/didc-vectors.json`).
+
+`rake e2e` needs `E2E_BASE` (a published Base Module, 0.8.0 or later) and
+`E2E_PACKER` (that Release's unpacked packer), icp-cli as `icp` or `E2E_ICP`,
+and rubygems.org. It runs `setup` on a Roda Application, packs and deploys it,
+installs Rack, Roda and the two `ruby_wasm_ic` gems from a real lock, upgrades,
+serves a page through them, and checks that a second install sends nothing.
+If icp-cli cannot fetch its network launcher, download it by tag from
+`dfinity/icp-cli-network-launcher`'s releases and set
+`ICP_CLI_NETWORK_LAUNCHER_PATH`.
+
+## Versions
+
+- **0.1.0:** the first release.
+
+MIT licensed.

data/exe/ruby_wasm_ic_installer

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative "../lib/ruby_wasm_ic_installer"
+
+exit RubyWasmIcInstaller::CLI.start(ARGV)

data/lib/ruby_wasm_ic_installer/app_setup.rb

@@ -0,0 +1,176 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module RubyWasmIcInstaller
+  # `ruby_wasm_ic_installer setup <app_dir>` (W29, Q16 and Q17): wires an
+  # Application in. It writes a marked block of Declarations into its
+  # ic-interface.rb, a marked block at the top of its app.rb that requires the
+  # canister half, and the canister half itself under
+  # vendor/ruby_wasm_ic_installer/. Idempotent: run twice, it changes nothing
+  # the second time.
+  #
+  # When what is there differs from what it would write (the author's edit,
+  # or an older version's block), it shows the diff and asks before writing;
+  # with no terminal it aborts unless told `yes`. The Installer's names
+  # declared or defined outside the markers abort it, since it cannot merge
+  # into the author's own lines. `check` only reports. All files are written,
+  # or none.
+  class AppSetup
+    OPEN = "# >>> ruby_wasm_ic_installer"
+    CLOSE = "# <<< ruby_wasm_ic_installer"
+    NOTE = " (written by `ruby_wasm_ic_installer setup`; edit outside these lines)"
+    BLOCK = /^#{Regexp.escape(OPEN)}.*?^#{Regexp.escape(CLOSE)}\n?/m
+    NAMES = %w[install_put install_commit install_remove installed].freeze
+    TYPES = %w[InstallFile InstallSetup InstallCommit Installed].freeze
+    VENDOR = File.join("vendor", "ruby_wasm_ic_installer")
+    CANISTER_SOURCE = File.expand_path("canister.rb", __dir__)
+
+    INTERFACE = <<~RUBY
+      #{OPEN}#{NOTE}
+      type :InstallFile,   record(path: Text, body: Blob)
+      type :InstallSetup,  record(generation: Nat64, load_paths: Vec[Text])
+      type :InstallCommit, record(gems: Vec[Text], setup: Opt[:InstallSetup])
+      type :Installed,     record(running: Opt[Nat64], pending: Opt[Nat64], gems: Vec[Text], partial: Vec[Text],
+                                  load_paths: Vec[Text], running_paths: Vec[Text])
+      update :install_put,    takes: [Vec[:InstallFile]], returns: Text
+      update :install_commit, takes: [:InstallCommit],    returns: Text
+      update :install_remove, takes: [Text],              returns: Text
+      query  :installed,      takes: [],                  returns: :Installed
+      #{CLOSE}
+    RUBY
+
+    APP = <<~RUBY
+      #{OPEN}#{NOTE}
+      $LOAD_PATH.unshift(File.join(__dir__, "#{VENDOR}"))
+      require "ruby_wasm_ic_installer/canister"
+      #{CLOSE}
+    RUBY
+
+    Change = Struct.new(:path, :old, :new, :edited, keyword_init: true) do
+      def diff(root)
+        rel = path.delete_prefix("#{root}/")
+        Diff.unified(old.to_s, new, from: old ? "a/#{rel}" : "/dev/null", to: "b/#{rel}")
+      end
+    end
+
+    class Aborted < Error; end
+
+    # `io`: where it writes; `input`: where it reads an answer; `tty`: whether
+    # it may ask.
+    def initialize(app_dir, io: $stdout, input: $stdin, tty: nil)
+      @root = File.expand_path(app_dir)
+      @io = io
+      @input = input
+      @tty = tty.nil? ? input.respond_to?(:tty?) && input.tty? : tty
+    end
+
+    def changes
+      @changes ||= begin
+        check_application!
+        [interface_change, app_change, vendor_change].compact
+      end
+    end
+
+    # Exit status for --check: 0 when nothing would change.
+    def check
+      changes.each { @io.puts(_1.diff(@root)) }
+      @io.puts(changes.empty? ? "setup is current in #{@root}" : "setup would change #{changes.size} file(s)")
+      changes.empty? ? 0 : 1
+    end
+
+    def run(yes: false)
+      if changes.empty?
+        @io.puts("nothing to change: #{@root} is set up")
+        return []
+      end
+      edited = changes.select(&:edited)
+      unless edited.empty?
+        @io.puts("These lines differ from what setup writes (your edit, or an older setup's):")
+        edited.each { @io.puts(_1.diff(@root)) }
+        confirm!(yes)
+      end
+      changes.each do |c|
+        FileUtils.mkdir_p(File.dirname(c.path))
+        File.write(c.path, c.new)
+        @io.puts("wrote #{c.path.delete_prefix("#{@root}/")}")
+      end
+      @io.puts("pack the Application again, and deploy it, for the Installer's methods to exist")
+      changes
+    end
+
+    private
+
+    def check_application!
+      raise Error, "#{@root} has no app.rb: it is not an Application" unless File.file?(file("app.rb"))
+      return if File.file?(file("ic-interface.rb"))
+
+      raise Error, "#{@root} has no ic-interface.rb: the Installer's methods are Declarations, and an " \
+                   "Application without an Interface file is served `run` alone (ADR-0056); write one first"
+    end
+
+    def file(name) = File.join(@root, name)
+
+    def interface_change
+      path = file("ic-interface.rb")
+      old = File.read(path)
+      conflicts!(path, old, /^\s*(?:update|query)\s+:(#{NAMES.join('|')})\b|^\s*type\s+:(#{TYPES.join('|')})\b/)
+      replace_or_add(path, old, INTERFACE, at_top: false)
+    end
+
+    def app_change
+      path = file("app.rb")
+      old = File.read(path)
+      conflicts!(path, old, /^\s*def\s+(?:self\.)?(#{NAMES.join('|')})\b/)
+      replace_or_add(path, old, APP, at_top: true)
+    end
+
+    def vendor_change
+      path = File.join(@root, VENDOR, "ruby_wasm_ic_installer", "canister.rb")
+      new = File.read(CANISTER_SOURCE)
+      old = File.file?(path) ? File.read(path) : nil
+      return nil if old == new
+
+      Change.new(path: path, old: old, new: new, edited: !old.nil?)
+    end
+
+    # The Installer's names outside the markers: abort, with where they are.
+    def conflicts!(path, text, pattern)
+      outside = text.gsub(BLOCK) { |b| "\n" * b.count("\n") }
+      hits = outside.lines.each_with_index.select { |l, _| l.match?(pattern) }
+      return if hits.empty?
+
+      where = hits.map { |l, i| "  #{path.delete_prefix("#{@root}/")}:#{i + 1}: #{l.strip}" }.join("\n")
+      raise Aborted, "the Installer's names are already declared or defined outside its markers, and setup cannot " \
+                     "merge into your own lines; remove them, or move them inside the markers:\n#{where}"
+    end
+
+    def replace_or_add(path, old, block, at_top:)
+      if old.match?(BLOCK)
+        new = old.sub(BLOCK, block)
+        return nil if new == old
+
+        return Change.new(path: path, old: old, new: new, edited: true)
+      end
+      new = at_top ? insert_at_top(old, block) : "#{old}#{old.end_with?("\n") || old.empty? ? '' : "\n"}\n#{block}"
+      Change.new(path: path, old: old, new: new, edited: false)
+    end
+
+    # After a shebang and any magic comments, which must stay first.
+    def insert_at_top(old, block)
+      lines = old.lines
+      n = 0
+      n += 1 while n < lines.size && (lines[n].start_with?("#!") || lines[n].match?(/\A#.*(?:coding[:=]|frozen_string_literal|warn_indent|shareable_constant_value)/))
+      (lines[0, n] + [block] + lines[n..]).join
+    end
+
+    def confirm!(yes)
+      return if yes
+      raise Aborted, "aborted: no terminal to ask on; run again with --yes to write these changes" unless @tty
+
+      @io.print("Apply? [y/N] ")
+      answer = @input.gets.to_s.strip.downcase
+      raise Aborted, "aborted: nothing was written" unless %w[y yes].include?(answer)
+    end
+  end
+end

data/lib/ruby_wasm_ic_installer/candid.rb

@@ -0,0 +1,262 @@
+# frozen_string_literal: true
+
+module RubyWasmIcInstaller
+  # The off-chain half's Candid: only the few fixed types the Installer's own
+  # Declarations use, encoded and decoded by hand, so the gem needs no Candid
+  # library. Arguments go to `icp canister call --args-format bin` as these
+  # bytes, and replies come back from `-o hex`.
+  #
+  # Encoding writes exactly the types below. Decoding reads any well-formed
+  # message whose values are records, opts, vecs, text, blob, bool and the
+  # unsigned integers, and gives records as Hashes keyed by field hash (named
+  # through #record, below), which is all the canister half replies with.
+  module Candid
+    class Error < StandardError; end
+
+    MAGIC = "DIDL".b
+
+    # Type opcodes (the Candid spec's negative type codes, as SLEB128).
+    NULL = -1
+    BOOL = -2
+    NAT = -3
+    NAT8 = -5
+    NAT16 = -6
+    NAT32 = -7
+    NAT64 = -8
+    TEXT = -15
+    OPT = -18
+    VEC = -19
+    RECORD = -20
+
+    module_function
+
+    def leb(n)
+      raise Error, "cannot encode a negative number as LEB128: #{n}" if n.negative?
+
+      out = +"".b
+      loop do
+        byte = n & 0x7f
+        n >>= 7
+        out << (n.zero? ? byte : byte | 0x80).chr
+        return out if n.zero?
+      end
+    end
+
+    def sleb(n)
+      out = +"".b
+      loop do
+        byte = n & 0x7f
+        n >>= 7
+        done = (n.zero? && byte & 0x40 == 0) || (n == -1 && byte & 0x40 != 0)
+        out << (done ? byte : byte | 0x80).chr
+        return out if done
+      end
+    end
+
+    # The IDL hash of a field name.
+    def idl_hash(name)
+      name.to_s.bytes.reduce(0) { |h, b| (h * 223 + b) % (2**32) }
+    end
+
+    def text_value(s)
+      s = s.to_s
+      raise Error, "text must be valid UTF-8: #{s.inspect[0, 60]}" unless s.dup.force_encoding("UTF-8").valid_encoding?
+
+      leb(s.bytesize) + s.b
+    end
+
+    def blob_value(bytes) = leb(bytes.bytesize) + bytes.b
+
+    # (vec record { path : text; body : blob }): one install_put batch.
+    def install_files(files)
+      # The table in didc's order, depth first from the argument, so the
+      # bytes equal @dfinity/didc's for the same value (spec/fixtures).
+      table = types(
+        "\x6d".b + sleb(1),                                           # 0: vec InstallFile
+        record_type([["path", sleb(TEXT)], ["body", sleb(2)]]),       # 1: InstallFile
+        "\x6d".b + sleb(NAT8)                                         # 2: blob
+      )
+      values = leb(files.size) + files.map do |f|
+        record_value("path" => text_value(f.fetch(:path)), "body" => blob_value(f.fetch(:body)))
+      end.join.b
+      MAGIC + table + leb(1) + sleb(0) + values
+    end
+
+    # The size install_files would give one file inside a batch: what the
+    # batching counts against a call's budget.
+    def install_file_size(path, body)
+      leb(path.bytesize).bytesize + path.bytesize + leb(body.bytesize).bytesize + body.bytesize
+    end
+
+    # The fixed bytes of an install_files message holding `count` files.
+    def install_files_overhead(count) = install_files([]).bytesize - 1 + leb(count).bytesize
+
+    # (text)
+    def text_arg(s) = MAGIC + leb(0) + leb(1) + sleb(TEXT) + text_value(s)
+
+    # ()
+    def empty_args = MAGIC + leb(0) + leb(0)
+
+    # (record { gems : vec text; setup : opt record { generation : nat64;
+    # load_paths : vec text } }): one install_commit.
+    def install_commit(gems:, setup: nil)
+      table = types(
+        record_type([["gems", sleb(1)], ["setup", sleb(2)]]),                         # 0: InstallCommit
+        "\x6d".b + sleb(TEXT),                                                        # 1: vec text
+        "\x6e".b + sleb(3),                                                           # 2: opt InstallSetup
+        record_type([["generation", sleb(NAT64)], ["load_paths", sleb(1)]])           # 3: InstallSetup
+      )
+      setup_value =
+        if setup
+          "\x01".b + record_value("generation" => nat64_value(setup.fetch(:generation)),
+                                  "load_paths" => texts_value(setup.fetch(:load_paths)))
+        else
+          "\x00".b
+        end
+      MAGIC + table + leb(1) + sleb(0) + record_value("gems" => texts_value(gems), "setup" => setup_value)
+    end
+
+    def texts_value(list) = leb(list.size) + list.map { text_value(_1) }.join.b
+
+    def nat64_value(n)
+      raise Error, "nat64 out of range: #{n}" unless n.is_a?(Integer) && n.between?(0, 2**64 - 1)
+
+      [n].pack("Q<")
+    end
+
+    def types(*entries) = leb(entries.size) + entries.join.b
+
+    # A record type entry, its fields sorted by hash.
+    def record_type(fields)
+      sorted = fields.sort_by { |name, _| idl_hash(name) }
+      "\x6c".b + leb(sorted.size) + sorted.map { |name, t| leb(idl_hash(name)) + t }.join.b
+    end
+
+    # A record value: its fields' bytes in hash order.
+    def record_value(fields) = fields.sort_by { |name, _| idl_hash(name) }.map(&:last).join.b
+
+    # Decodes a reply of one value; records come back keyed by field hash.
+    def decode(bytes) = Reader.new(bytes).message
+
+    # A decoded record's fields by name.
+    def record(value, *names)
+      raise Error, "expected a record, got #{value.class}" unless value.is_a?(Hash)
+
+      names.to_h do |name|
+        h = idl_hash(name)
+        raise Error, "the record has no field #{name}" unless value.key?(h)
+
+        [name.to_sym, value[h]]
+      end
+    end
+
+    # The one-message reader. Types are resolved from the type table; values
+    # are read by them. Recursion is bounded, so a hostile reply cannot run
+    # it away.
+    class Reader
+      MAX_DEPTH = 32
+
+      def initialize(bytes)
+        @b = bytes.b
+        @i = 0
+      end
+
+      def message
+        raise Error, "not a Candid message (no DIDL header)" unless take(4) == MAGIC
+
+        @table = Array.new(uleb) { entry }
+        args = Array.new(uleb) { sleb_read }
+        values = args.map { |t| value(t, 0) }
+        raise Error, "#{@b.bytesize - @i} trailing bytes after the message" unless @i == @b.bytesize
+
+        values
+      end
+
+      private
+
+      def take(n)
+        raise Error, "the message ends early" if @i + n > @b.bytesize
+
+        @b.byteslice(@i, n).tap { @i += n }
+      end
+
+      def byte = take(1).ord
+
+      def uleb
+        n = 0
+        shift = 0
+        loop do
+          b = byte
+          n |= (b & 0x7f) << shift
+          return n if b < 0x80
+
+          shift += 7
+          raise Error, "a LEB128 number longer than 10 bytes" if shift > 63
+        end
+      end
+
+      def sleb_read
+        n = 0
+        shift = 0
+        loop do
+          b = byte
+          n |= (b & 0x7f) << shift
+          shift += 7
+          if b < 0x80
+            n -= (1 << shift) if b & 0x40 != 0
+            return n
+          end
+          raise Error, "a LEB128 number longer than 10 bytes" if shift > 63
+        end
+      end
+
+      def entry
+        case (op = sleb_read)
+        when OPT, VEC then [op, sleb_read]
+        when RECORD then [op, Array.new(uleb) { [uleb, sleb_read] }]
+        else raise Error, "type #{op} is not one the Installer reads"
+        end
+      end
+
+      def value(t, depth)
+        raise Error, "nested past #{MAX_DEPTH}" if depth > MAX_DEPTH
+        return primitive(t) if t.negative?
+
+        op, inner = @table.fetch(t) { raise Error, "type index #{t} is not in the table" }
+        case op
+        when OPT
+          case byte
+          when 0 then nil
+          when 1 then value(inner, depth + 1)
+          else raise Error, "an opt tag that is neither 0 nor 1"
+          end
+        when VEC
+          n = uleb
+          return take(n) if inner == NAT8
+
+          Array.new(n) { value(inner, depth + 1) }
+        when RECORD
+          inner.to_h { |h, ft| [h, value(ft, depth + 1)] }
+        end
+      end
+
+      def primitive(t)
+        case t
+        when NULL then nil
+        when BOOL then byte == 1
+        when NAT then uleb
+        when NAT8 then byte
+        when NAT16 then take(2).unpack1("S<")
+        when NAT32 then take(4).unpack1("L<")
+        when NAT64 then take(8).unpack1("Q<")
+        when TEXT
+          s = take(uleb).force_encoding("UTF-8")
+          raise Error, "text that is not UTF-8" unless s.valid_encoding?
+
+          s
+        else raise Error, "type #{t} is not one the Installer reads"
+        end
+      end
+    end
+  end
+end