ruby_wasm_ic_installer 0.1.1

data/lib/ruby_wasm_ic_installer/magic_comment.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module RubyWasmIcInstaller
+  # A file's magic comment, against the three encodings a `minimal` canister
+  # claims: UTF-8, US-ASCII and ASCII-8BIT (ADR-0053). The comment is read in
+  # C before any Ruby runs, so no stand-in can help: an alias of one of the
+  # three is rewritten to its canonical name, found with MRI's own
+  # Encoding.find (W29, Q9), and any other encoding refuses the gem.
+  #
+  # That includes the nine other names a canister lists (UTF-16 and UTF-32
+  # and their byte orders, UTF8-MAC, EUC-JP, Windows-31J): they are names
+  # with no encoding behind them, so a file whose comment names one loads
+  # with no error and is read as ASCII-8BIT, its literals wrong (W30, 28
+  # October 2026). A change to the table is a release of this gem.
+  module MagicComment
+    CLAIMED_ENCODINGS = %w[ASCII-8BIT UTF-8 US-ASCII].freeze
+
+    # Listed by a `minimal` canister and not claimed: refused with their own
+    # reason, since an author may expect them to work.
+    UNCLAIMED_ENCODINGS = %w[UTF-16BE UTF-16LE UTF-32BE UTF-32LE UTF-16 UTF-32 UTF8-MAC EUC-JP Windows-31J].freeze
+
+    # Ruby reads a magic comment on the first line, or the second after a
+    # shebang. `coding: x`, `coding=x`, `-*- coding: x -*-` and
+    # `encoding: x` all match.
+    PATTERN = /\A(#.*?coding[:=][ \t]*)([\w.\-]+)/
+
+    Rewrite = Struct.new(:file, :line, :from, :to, keyword_init: true)
+
+    class Refused < Error; end
+
+    module_function
+
+    # [new_body, rewrite or nil]; raises Refused for an encoding a canister
+    # lacks or one MRI does not know.
+    def fix(file, body)
+      lines = body.b.lines
+      idx = comment_line(lines) or return [body, nil]
+      m = lines[idx].match(PATTERN)
+      name = m[2]
+      canonical = canonical!(file, name)
+      return [body, nil] if canonical.casecmp?(name)
+
+      lines[idx] = lines[idx].sub(PATTERN) { "#{m[1]}#{canonical.downcase}" }
+      [lines.join, Rewrite.new(file: file, line: idx + 1, from: name, to: canonical.downcase)]
+    end
+
+    def comment_line(lines)
+      return 0 if lines[0]&.match?(PATTERN)
+      return 1 if lines[0]&.start_with?("#!") && lines[1]&.match?(PATTERN)
+
+      nil
+    end
+
+    def canonical!(file, name)
+      enc = begin
+        Encoding.find(name)
+      rescue ArgumentError
+        raise Refused, "#{file} names the encoding #{name.inspect}, which Ruby does not know"
+      end
+      known = CLAIMED_ENCODINGS.find { _1.casecmp?(enc.name) }
+      return known if known
+
+      said = "#{file} is written in #{enc.name} (its magic comment says #{name.inspect})"
+      if UNCLAIMED_ENCODINGS.any? { _1.casecmp?(enc.name) }
+        raise Refused, "#{said}: a minimal canister lists that name but has no #{enc.name} behind it, so the file " \
+                       "would load as ASCII-8BIT; only #{CLAIMED_ENCODINGS.join(', ')} are claimed"
+      end
+      raise Refused, "#{said}, which a minimal canister does not have: it has #{CLAIMED_ENCODINGS.join(', ')}, " \
+                     "and transcodes nothing"
+    end
+  end
+end

data/lib/ruby_wasm_ic_installer/plan.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module RubyWasmIcInstaller
+  # What one install run sends (W29, Q10): every prepared gem the canister
+  # lacks, whole, packed into install_put batches by bytes, each followed by
+  # an install_commit for the gems it completed; then one install_commit that
+  # writes the setup file, unless the pending one already says the same.
+  #
+  # A batch is at most `budget` bytes of Candid (2 MiB is the ingress limit;
+  # W28 saw 2,093,069 bytes pass and 2,101,455 refused at submission, so the
+  # default leaves room for the envelope icp-cli adds). A gem bigger than a
+  # batch spans several; .partial holds it until its commit.
+  class Plan
+    DEFAULT_BUDGET = 2_000_000
+
+    Step = Struct.new(:method, :args, :note, keyword_init: true)
+
+    attr_reader :steps, :sent, :generation
+
+    # `prepared`: GemFiles::Prepared in the lock's order (stand-ins already
+    # left out). `installed`: the canister's installed() record.
+    def initialize(prepared, installed, budget: DEFAULT_BUDGET)
+      @budget = budget
+      have = installed[:gems]
+      @sent = prepared.reject { have.include?(_1.name_version) }
+      @steps = []
+      # A version half-sent by an earlier run is cleared first: its files are
+      # resent whole, so nothing stale is committed with them.
+      (installed[:partial] & @sent.map(&:name_version)).each do |nv|
+        @steps << Step.new(method: "install_remove", args: Candid.text_arg(nv), note: "clear #{nv} from .partial")
+      end
+      batch!
+      setup!(prepared, installed)
+    end
+
+    def empty? = @steps.empty?
+
+    private
+
+    def batch!
+      files = []
+      size = 0
+      done = []
+      flush = lambda do
+        next if files.empty?
+
+        @steps << Step.new(method: "install_put", args: Candid.install_files(files),
+                           note: "#{files.size} files, #{files.sum { _1[:body].bytesize }} bytes")
+        unless done.empty?
+          @steps << Step.new(method: "install_commit", args: Candid.install_commit(gems: done),
+                             note: "commit #{done.join(', ')}")
+        end
+        files = []
+        size = 0
+        done = []
+      end
+      @sent.each do |gem|
+        gem.files.each do |rel, body|
+          path = "#{gem.name_version}/#{rel}"
+          one = Candid.install_file_size(path, body)
+          if one + Candid.install_files_overhead(1) > @budget
+            raise Error, "#{path} is #{body.bytesize} bytes, more than one call can carry (#{@budget})"
+          end
+
+          flush.call if size + one + Candid.install_files_overhead(files.size + 1) > @budget
+          files << { path: path, body: body }
+          size += one
+        end
+        done << gem.name_version
+      end
+      flush.call
+    end
+
+    def setup!(prepared, installed)
+      paths = prepared.flat_map { |g| g.require_paths.map { "#{g.name_version}/#{_1}" } }
+      return if installed[:pending] && installed[:load_paths] == paths
+
+      @generation = [installed[:pending], installed[:running]].compact.max.to_i + 1
+      @steps << Step.new(method: "install_commit",
+                         args: Candid.install_commit(gems: [], setup: { generation: @generation, load_paths: paths }),
+                         note: "write setup generation #{@generation} (#{paths.size} load paths)")
+    end
+  end
+end

data/lib/ruby_wasm_ic_installer/runner.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require "open3"
+require "tempfile"
+
+module RubyWasmIcInstaller
+  # The one way the off-chain half reaches a canister (W29, Q13):
+  # `icp canister call <canister> <method> --args-file <file> --args-format
+  # bin -o hex`, with `--query` for a query. The author's icp.yaml,
+  # environment, network and identity pass through as `icp_args`; the
+  # Installer holds no keys and picks no network. A file carries the
+  # arguments because one command-line argument is capped at 128 KiB and a
+  # batch is up to 2 MiB.
+  #
+  # It is also the test seam: the specs give the Installer a runner whose
+  # #call answers from a canister held in memory.
+  class Runner
+    class CallError < Error
+      attr_reader :refusal
+
+      def initialize(message, refusal: nil)
+        super(message)
+        @refusal = refusal
+      end
+    end
+
+    # `spawn` is called as spawn.(*argv) and returns [stdout, stderr, status];
+    # the default is Open3.capture3.
+    def initialize(canister:, icp: "icp", icp_args: [], spawn: nil)
+      @canister = canister
+      @icp = icp
+      @icp_args = icp_args
+      @spawn = spawn || Open3.method(:capture3)
+    end
+
+    # The reply's bytes.
+    def call(method, args, query: false)
+      Tempfile.create(["ruby_wasm_ic_installer", ".bin"], binmode: true) do |f|
+        f.write(args)
+        f.flush
+        argv = [@icp, "canister", "call", @canister, method, "--args-file", f.path, "--args-format", "bin",
+                "-o", "hex", *(query ? ["--query"] : []), *@icp_args]
+        out, err, status = @spawn.call(*argv)
+        raise CallError.new("#{method}: #{err.strip.empty? ? out.strip : err.strip}", refusal: refusal(err)) \
+          unless status.success?
+
+        hex = out.strip
+        raise CallError, "#{method}: icp replied #{out.inspect[0, 200]}, not hex" unless hex.match?(/\A(?:[0-9a-fA-F]{2})+\z/)
+
+        [hex].pack("H*")
+      end
+    end
+
+    private
+
+    # The text after `refused: ` in a trap message, if the canister refused.
+    def refusal(err) = err[/refused: (.*?)(?:'|"|$)/, 1]
+  end
+end

data/lib/ruby_wasm_ic_installer/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module RubyWasmIcInstaller
+  VERSION = "0.1.1"
+end

data/lib/ruby_wasm_ic_installer.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+# ruby_wasm_ic_installer: the Installer (W29). Its off-chain half, loaded
+# here, sends an Application's pure-Ruby gems into a Ruby canister packed by
+# ruby_wasm_builder; its canister half, ruby_wasm_ic_installer/canister.rb,
+# is carried by the Application and is never loaded by this file.
+module RubyWasmIcInstaller
+  class Error < StandardError; end
+end
+
+require_relative "ruby_wasm_ic_installer/version"
+require_relative "ruby_wasm_ic_installer/candid"
+require_relative "ruby_wasm_ic_installer/lockfile"
+require_relative "ruby_wasm_ic_installer/magic_comment"
+require_relative "ruby_wasm_ic_installer/gem_files"
+require_relative "ruby_wasm_ic_installer/plan"
+require_relative "ruby_wasm_ic_installer/runner"
+require_relative "ruby_wasm_ic_installer/installer"
+require_relative "ruby_wasm_ic_installer/diff"
+require_relative "ruby_wasm_ic_installer/app_setup"
+require_relative "ruby_wasm_ic_installer/cli"

metadata

@@ -0,0 +1,65 @@
+--- !ruby/object:Gem::Specification
+name: ruby_wasm_ic_installer
+version: !ruby/object:Gem::Version
+  version: 0.1.1
+platform: ruby
+authors:
+- the ruby_wasm_builder authors
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2026-10-28 00:00:00.000000000 Z
+dependencies: []
+description: 'The Installer for canisters packed by ruby_wasm_builder: reads an Application''s
+  Gemfile.lock, fetches its pure-Ruby gems and sends the ones a canister lacks through
+  `icp canister call`, into /data, where a carried canister half loads them at the
+  next boot. `setup` wires the canister half into an Application.'
+email:
+executables:
+- ruby_wasm_ic_installer
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- exe/ruby_wasm_ic_installer
+- lib/ruby_wasm_ic_installer.rb
+- lib/ruby_wasm_ic_installer/app_setup.rb
+- lib/ruby_wasm_ic_installer/candid.rb
+- lib/ruby_wasm_ic_installer/canister.rb
+- lib/ruby_wasm_ic_installer/cli.rb
+- lib/ruby_wasm_ic_installer/diff.rb
+- lib/ruby_wasm_ic_installer/gem_files.rb
+- lib/ruby_wasm_ic_installer/installer.rb
+- lib/ruby_wasm_ic_installer/lockfile.rb
+- lib/ruby_wasm_ic_installer/magic_comment.rb
+- lib/ruby_wasm_ic_installer/plan.rb
+- lib/ruby_wasm_ic_installer/runner.rb
+- lib/ruby_wasm_ic_installer/version.rb
+homepage: https://github.com/graial/ruby_wasm_ic_installer
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/graial/ruby_wasm_ic_installer
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.11
+signing_key:
+specification_version: 4
+summary: Install pure-Ruby gems into a Ruby canister on the Internet Computer, through
+  calls
+test_files: []