wasval 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 0c40e62ec75efb8c895a87bdf907ffe4e339d1954e5e4ea7368e2652732e3156
+  data.tar.gz: 964d7ad7932d2fe91a8e27a87a188ac54a0de84eb008407da778bab3c13f6d3a
+SHA512:
+  metadata.gz: ab1cbfd5146a97b4c06852070840a20060b1101ee6d28a27f98f0c5fdfaa68979c198c03c88abefa0ec7fa9d6483defe8be58002f2a8d2cdc04820ebc900baf9
+  data.tar.gz: 9523a2fd9f67374216d3f3d5a5f4d1e8072e821a2563b777522f21ef20d07c8004b3ffeedf0aeec6dad7d19809f2a20140b8d0ec775808f583e8142211f17627

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,10 @@
+# Code of Conduct
+
+"wasval" follows [The Ruby Community Conduct Guideline](https://www.ruby-lang.org/en/conduct) in all "collaborative space", which is defined as community communications channels (such as mailing lists, submitted patches, commit comments, etc.):
+
+* Participants will be tolerant of opposing views.
+* Participants must ensure that their language and actions are free of personal attacks and disparaging personal remarks.
+* When interpreting the words and actions of others, participants should always assume good intentions.
+* Behaviour which can be reasonably considered harassment will not be tolerated.
+
+If you have any concerns about behaviour within this project, please contact us at ["yuuji.yaginuma@gmail.com"](mailto:"yuuji.yaginuma@gmail.com").

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Yuji Yaginuma
+
+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,128 @@
+# Wasval
+
+Wasval is a Ruby sandbox that executes Ruby code safely inside a WebAssembly runtime (via [wasmtime](https://github.com/bytecodealliance/wasmtime-rb)).
+
+## Installation
+
+```bash
+bundle add wasval
+```
+
+Or install directly:
+
+```bash
+gem install wasval
+```
+
+## Setup
+
+Wasval requires a `ruby.wasm` binary. Install it with the built-in installer:
+
+```ruby
+require "wasval"
+
+Wasval::Install::RubyWasm.new.install
+```
+
+`install` downloads the `ruby.wasm` binary and also generates a pre-compiled `ruby.cwasm` (serialized WebAssembly module) alongside it. Both files are saved to `~/.wasval/` by default (`ruby.wasm` and `ruby.cwasm`). The `.cwasm` file is a pre-compiled module that significantly reduces startup time on subsequent executions, though it is larger in file size than the `.wasm` binary.
+
+If you only need the `.wasm` binary without pre-compilation, use `download` instead:
+
+```ruby
+Wasval::Install::RubyWasm.new.download
+```
+
+The binary is downloaded from the [ruby.wasm releases](https://github.com/ruby/ruby.wasm/releases).
+
+By default, Ruby 3.4 is used. You can change the Ruby version via the `WASVAL_RUBY_VERSION` environment variable or the `ruby_version:` option:
+
+```ruby
+Wasval::Install::RubyWasm.new(ruby_version: "3.3").install
+```
+
+```bash
+WASVAL_RUBY_VERSION=3.3 bundle exec ruby -e "require 'wasval'; Wasval::Install::RubyWasm.new.install"
+```
+
+You can customize the destination via the `WASVAL_RUBY_WASM_PATH` environment variable or the `dest:` option:
+
+```ruby
+Wasval::Install::RubyWasm.new(dest: "/path/to/ruby.wasm").download
+```
+
+## Usage
+
+Set the `WASVAL_RUBY_WASM_PATH` environment variable to point to the `ruby.wasm` binary, then execute Ruby code:
+
+```ruby
+result = Wasval.execute("puts 'hello'")
+
+result.status        # => :success
+result.output        # => "hello\n"
+result.success?      # => true
+```
+
+### Configuration
+
+```ruby
+Wasval.configure do |config|
+  config.timeout      = 10   # seconds (default: 5)
+  config.memory_limit = 256  # MB (default: 128)
+end
+```
+
+You can also pass per-call overrides:
+
+```ruby
+result = Wasval.execute(code, timeout: 3, memory_limit: 32)
+```
+
+### Result
+
+`Wasval.execute` returns a `Wasval::Result` with the following attributes:
+
+| Attribute | Description |
+|---|---|
+| `status` | `:success`, `:syntax_error`, `:runtime_error`, `:timeout`, `:memory_limit`, `:sandbox_error` |
+| `output` | Captured stdout |
+| `stderr` | Captured stderr |
+| `error_message` | Human-readable error description (nil on success) |
+
+Helper methods: `success?`, `timeout?`, `error_type`.
+
+## Performance and Memory Considerations
+
+Wasval supports two binary formats for the Ruby WebAssembly runtime:
+
+- **`.wasm`** — The standard WebAssembly binary. It is portable and can be used across different WebAssembly runtimes, but requires compilation at load time, which results in higher memory usage and longer startup latency on first use.
+- **`.cwasm`** — A serialized (pre-compiled) module specific to Wasmtime. It is the output of ahead-of-time compilation of the `.wasm` binary, so the runtime can load it directly without recompilation. This eliminates the compilation overhead, significantly reducing both memory usage and first execution latency. Note that `.cwasm` files are larger than their `.wasm` counterparts and are tied to the specific version of Wasmtime used to generate them.
+
+When loading a `.wasm` binary at runtime, please be aware of the following:
+
+- **Memory usage**: Loading ruby.wasm requires a significant amount of memory. Ensure your environment has sufficient memory available before using this gem.
+- **First execution latency**: The first call to `Wasval.execute` incurs additional overhead due to loading and initializing the WebAssembly runtime. Subsequent calls will be faster.
+
+Using `.cwasm` (generated by `Wasval::Install::RubyWasm.new.install`) is recommended for production use, as both concerns above do not apply.
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, install the ruby.wasm binary:
+
+```bash
+bundle exec ruby -e "require 'wasval'; Wasval::Install::RubyWasm.new.download"
+```
+
+Set `WASVAL_RUBY_WASM_PATH` and run the tests:
+
+```bash
+export WASVAL_RUBY_WASM_PATH=~/.wasval/ruby.wasm
+bundle exec rake test
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/y-yagi/wasval.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "minitest/test_task"
+
+Minitest::TestTask.create do |t|
+  t.warning = true
+  t.verbose = true
+end
+
+task default: :test

data/lib/wasval/config.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Wasval
+  class Config
+    DEFAULT_TIMEOUT = 5
+    DEFAULT_MEMORY_LIMIT = 128
+
+    attr_accessor :timeout, :memory_limit
+
+    def initialize
+      @timeout = DEFAULT_TIMEOUT
+      @memory_limit = DEFAULT_MEMORY_LIMIT
+    end
+  end
+end

data/lib/wasval/executor.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+require "wasmtime"
+
+module Wasval
+  class Executor
+    STDOUT_BUFFER_SIZE = 10 * 1024 * 1024  # 10 MB
+    STDERR_BUFFER_SIZE = 1 * 1024 * 1024   # 1 MB
+    WASM_PATH = ENV["WASVAL_RUBY_WASM_PATH"]
+    CWASM_PATH = ENV["WASVAL_RUBY_CWASM_PATH"]
+
+    def initialize
+      @engine = Wasmtime::Engine.new(epoch_interruption: true)
+
+      if WASM_PATH
+        @mod = Wasmtime::Module.from_file(@engine, WASM_PATH)
+      elsif CWASM_PATH
+        @mod = Wasmtime::Module.deserialize_file(@engine, CWASM_PATH)
+      else
+        raise ArgumentError.new "Please specify 'WASVAL_RUBY_WASM_PATH' or 'WASVAL_RUBY_CWASM_PATH' env"
+      end
+    end
+
+    def execute(code:, timeout:, memory_limit:)
+      if code.nil? || code.strip.empty?
+        return Result.new(
+          status: :sandbox_error,
+          output: "",
+          stderr: "",
+          error_message: "code must not be nil or empty"
+        )
+      end
+
+      stdout_buf = +""
+      stderr_buf = +""
+
+      wasi_config = Wasmtime::WasiConfig.new
+        .set_argv(["ruby", "-"])
+        .set_stdin_string(wrapped_code(code))
+        .set_stdout_buffer(stdout_buf, STDOUT_BUFFER_SIZE)
+        .set_stderr_buffer(stderr_buf, STDERR_BUFFER_SIZE)
+
+      store = Wasmtime::Store.new(@engine,
+        wasi_p1_config: wasi_config,
+        limits: { memory_size: memory_limit * 1024 * 1024 }
+      )
+      store.set_epoch_deadline(timeout)
+
+      linker = Wasmtime::Linker.new(@engine)
+      Wasmtime::WASI::P1.add_to_linker_sync(linker)
+
+      @engine.start_epoch_interval(1000)
+
+      begin
+        linker.instantiate(store, @mod).invoke("_start")
+        classify_output(stdout_buf, stderr_buf, store)
+      rescue Wasmtime::WasiExit
+        classify_output(stdout_buf, stderr_buf, store)
+      rescue Wasmtime::Trap => e
+        if e.code == :interrupt
+          Result.new(status: :timeout, output: stdout_buf, stderr: "", error_message: "execution timed out")
+        elsif store.linear_memory_limit_hit?
+          Result.new(status: :memory_limit, output: stdout_buf, stderr: "", error_message: "memory limit exceeded")
+        else
+          Result.new(status: :sandbox_error, output: stdout_buf, stderr: stderr_buf, error_message: e.message)
+        end
+      rescue Wasmtime::Error => e
+        if store.linear_memory_limit_hit?
+          Result.new(status: :memory_limit, output: stdout_buf, stderr: "", error_message: "memory limit exceeded")
+        else
+          Result.new(status: :sandbox_error, output: stdout_buf, stderr: stderr_buf, error_message: e.message)
+        end
+      rescue => e
+        Result.new(status: :sandbox_error, output: stdout_buf, stderr: stderr_buf, error_message: e.message)
+      end
+    end
+
+    private
+
+    def wrapped_code(code)
+      <<~RUBY
+        begin
+          eval(#{code.inspect}, binding, "(user_code)", 1)
+        rescue SyntaxError => e
+          $stderr.print "WASVAL:syntax_error:\#{e.message}"
+          exit 1
+        rescue => e
+          $stderr.print "WASVAL:runtime_error:\#{e.class}:\#{e.message}"
+          exit 1
+        end
+      RUBY
+    end
+
+    def classify_output(stdout, stderr, store)
+      if store.linear_memory_limit_hit?
+        return Result.new(status: :memory_limit, output: stdout, stderr: "", error_message: "memory limit exceeded")
+      end
+
+      if (match = stderr.match(/WASVAL:syntax_error:(.+)/m))
+        clean_stderr = stderr.gsub(/^WASVAL:.*$/, "").strip
+        Result.new(status: :syntax_error, output: stdout, stderr: clean_stderr, error_message: match[1].strip)
+      elsif (match = stderr.match(/WASVAL:runtime_error:([^:]+):(.+)/m))
+        clean_stderr = stderr.gsub(/^WASVAL:.*$/, "").strip
+        error_msg = "#{match[1]}: #{match[2].strip}"
+        Result.new(status: :runtime_error, output: stdout, stderr: clean_stderr, error_message: error_msg)
+      elsif stderr.match?(/cannot load such file/)
+        Result.new(status: :runtime_error, output: stdout, stderr: stderr, error_message: stderr)
+      else
+        Result.new(status: :success, output: stdout, stderr: stderr, error_message: nil)
+      end
+    end
+  end
+end

data/lib/wasval/install/ruby_wasm.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+require "zlib"
+require "rubygems/package"
+require "fileutils"
+require "tmpdir"
+require "wasmtime"
+
+module Wasval
+  module Install
+    class RubyWasm
+      GITHUB_RELEASES_URL = "https://github.com/ruby/ruby.wasm/releases/latest/download"
+      TARGET = "wasm32-unknown-wasip1"
+      BINARY_PATH_IN_TAR = "usr/local/bin/ruby"
+      DEFAULT_INSTALL_DIR = File.expand_path("~/.wasval")
+      DEFAULT_BINARY_NAME = "ruby.wasm"
+      DEFAULT_SERIALIZED_BINARY_NAME = "ruby.cwasm"
+
+      attr_reader :dest, :serialized_dest, :ruby_version, :profile
+
+      def initialize(dest: nil, serialized_dest: nil, ruby_version: nil, profile: :full)
+        @ruby_version = ruby_version || ENV["WASVAL_RUBY_VERSION"] || default_ruby_version
+        @profile = profile.to_s
+        @dest = dest || ENV["WASVAL_RUBY_WASM_PATH"] || File.join(DEFAULT_INSTALL_DIR, DEFAULT_BINARY_NAME)
+        @serialized_dest = serialized_dest || ENV["WASVAL_RUBY_CWASM_PATH"] || File.join(File.dirname(@dest), DEFAULT_SERIALIZED_BINARY_NAME)
+      end
+
+      def download
+        FileUtils.mkdir_p(File.dirname(dest))
+        Dir.mktmpdir do |tmpdir|
+          tarball_path = File.join(tmpdir, tarball_name)
+          download_file(download_url, tarball_path)
+          extract_binary(tarball_path)
+        end
+        dest
+      end
+
+      def install
+        download
+        serialize
+      end
+
+      def serialize
+        engine = Wasmtime::Engine.new(epoch_interruption: true)
+        mod = Wasmtime::Module.from_file(engine, dest)
+        FileUtils.mkdir_p(File.dirname(serialized_dest))
+        File.binwrite(serialized_dest, mod.serialize)
+        serialized_dest
+      end
+
+      def installed?
+        File.exist?(dest)
+      end
+
+      def tarball_name
+        "ruby-#{ruby_version}-#{TARGET}-#{profile}.tar.gz"
+      end
+
+      def download_url
+        "#{GITHUB_RELEASES_URL}/#{tarball_name}"
+      end
+
+      private
+
+      def default_ruby_version
+        "3.4"
+      end
+
+      def download_file(url, dest_path, redirect_limit: 10)
+        raise "Too many redirects for #{url}" if redirect_limit == 0
+
+        uri = URI.parse(url)
+        Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https") do |http|
+          http.request(Net::HTTP::Get.new(uri)) do |response|
+            case response
+            when Net::HTTPSuccess
+              File.open(dest_path, "wb") do |f|
+                response.read_body { |chunk| f.write(chunk) }
+              end
+            when Net::HTTPRedirection
+              download_file(response["location"], dest_path, redirect_limit: redirect_limit - 1)
+            else
+              raise "Failed to download #{url}: #{response.code} #{response.message}"
+            end
+          end
+        end
+      end
+
+      def extract_binary(tarball_path)
+        Zlib::GzipReader.open(tarball_path) do |gz|
+          Gem::Package::TarReader.new(gz) do |tar|
+            tar.each do |entry|
+              next unless entry.file? && entry.full_name.end_with?(BINARY_PATH_IN_TAR)
+
+              File.open(dest, "wb") { |f| f.write(entry.read) }
+              File.chmod(0o755, dest)
+              return
+            end
+          end
+        end
+        raise "Ruby binary not found in tarball (expected path: #{BINARY_PATH_IN_TAR})"
+      end
+    end
+  end
+end

data/lib/wasval/result.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Wasval
+  class Result
+    VALID_STATUSES = %i[success syntax_error runtime_error timeout memory_limit sandbox_error].freeze
+
+    attr_reader :status, :output, :stderr, :error_message
+
+    def initialize(status:, output:, stderr:, error_message:)
+      raise ArgumentError, "invalid status: #{status}" unless VALID_STATUSES.include?(status)
+
+      @status = status
+      @output = output.to_s
+      @stderr = stderr.to_s
+      @error_message = error_message
+
+      freeze
+    end
+
+    def success?
+      @status == :success
+    end
+
+    def timeout?
+      @status == :timeout
+    end
+
+    def error_type
+      return nil if @status == :success
+
+      @status
+    end
+  end
+end

data/lib/wasval/version.rb

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

data/lib/wasval.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require_relative "wasval/version"
+require_relative "wasval/config"
+require_relative "wasval/result"
+require_relative "wasval/executor"
+require_relative "wasval/install/ruby_wasm"
+
+module Wasval
+  class Error < StandardError; end
+
+  class << self
+    def execute(code, timeout: nil, memory_limit: nil)
+      resolved_timeout = timeout || config.timeout
+      resolved_memory = memory_limit || config.memory_limit
+
+      executor.execute(code: code, timeout: resolved_timeout, memory_limit: resolved_memory)
+    end
+
+    def configure
+      yield config
+    end
+
+    def config
+      @config ||= Config.new
+    end
+
+    def executor
+      @executor ||= Executor.new
+    end
+  end
+end

metadata

@@ -0,0 +1,78 @@
+--- !ruby/object:Gem::Specification
+name: wasval
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Yuji Yaginuma
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: ruby_wasm
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: wasmtime
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+email:
+- yuuji.yaginuma@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CODE_OF_CONDUCT.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/wasval.rb
+- lib/wasval/config.rb
+- lib/wasval/executor.rb
+- lib/wasval/install/ruby_wasm.rb
+- lib/wasval/result.rb
+- lib/wasval/version.rb
+homepage: https://github.com/y-yagi/wasval/
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/y-yagi/wasval/
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.3.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.3
+specification_version: 4
+summary: Execute 'eval' in a WASM runtime
+test_files: []