wasmer 0.1.1

data/Cargo.toml

@@ -0,0 +1,21 @@
+[package]
+publish = false
+name = "ruby-ext-wasm"
+version = "0.1.1"
+authors = ["Ivan Enderlin <ivan.enderlin@hoa-project.net>"]
+edition = "2018"
+description = "Ruby extension to run WebAssembly binaries"
+readme = "README.md"
+repository = "https://github.com/wasmerio/ruby-ext-wasm"
+keywords = ["ruby", "extension", "webassembly"]
+categories = ["wasm"]
+
+[lib]
+name = "wasmer"
+crate-type = ["dylib"]
+
+[dependencies]
+wasmer-runtime = "0.3.0"
+wasmer-runtime-core = "0.3.0"
+rutie = "0.5.4"
+lazy_static = "1.3.0"

data/Gemfile

@@ -0,0 +1,9 @@
+source "https://rubygems.org"
+
+gemspec
+
+group :test do
+  gem 'minitest', '~> 5.10'
+  gem 'minitest-reporters', '~> 1.1'
+  gem 'color_pound_spec_reporter', '~> 0.0.6'
+end

data/README.md

@@ -0,0 +1,279 @@
+<p align="center">
+  <a href="https://wasmer.io" target="_blank" rel="noopener noreferrer">
+    <img width="400" src="https://raw.githubusercontent.com/wasmerio/wasmer/master/logo.png" alt="Wasmer logo">
+  </a>
+</p>
+
+<p align="center">
+  <a href="https://spectrum.chat/wasmer">
+    <img src="https://withspectrum.github.io/badge/badge.svg" alt="Join the Wasmer Community"></a>
+  <a href="https://github.com/wasmerio/wasmer/blob/master/LICENSE">
+    <img src="https://img.shields.io/github/license/wasmerio/wasmer.svg" alt="License"></a>
+</p>
+
+# The Ruby extension to run WebAssembly
+
+The goal of the project is to be able to run WebAssembly binaries from
+Ruby directly. So much fun coming!
+
+_Under Development, don't use it in product yet_.
+
+## What is WebAssembly?
+
+Quoting [the WebAssembly site](https://webassembly.org/):
+
+> WebAssembly (abbreviated Wasm) is a binary instruction format for a
+> stack-based virtual machine. Wasm is designed as a portable target
+> for compilation of high-level languages like C/C++/Rust, enabling
+> deployment on the web for client and server applications.
+
+About speed:
+
+> WebAssembly aims to execute at native speed by taking advantage of
+> [common hardware
+> capabilities](https://webassembly.org/docs/portability/#assumptions-for-efficient-execution)
+> available on a wide range of platforms.
+
+About safety:
+
+> WebAssembly describes a memory-safe, sandboxed [execution
+> environment](https://webassembly.org/docs/semantics/#linear-memory) […].
+
+## Example
+
+There is a toy program in `examples/simple.rs`, written in Rust (or
+any other language that compiles to Wasm):
+
+```rust
+#[no_mangle]
+pub extern fn sum(x: i32, y: i32) -> i32 {
+    x + y
+}
+```
+
+Once this program compiled to WebAssembly, we end up with a
+`examples/simple.wasm` binary file.
+
+Then, we can execute it in Ruby (!) with the `examples/simple.rb` file:
+
+```rb
+require "wasmer"
+
+bytes = IO.read "simple.wasm", mode: "rb"
+instance = Instance.new bytes
+puts instance.exports.sum 1, 2
+```
+
+And then, finally, enjoy by running:
+
+```sh
+$ ruby simple.rb
+3
+```
+
+## API documentation
+
+### The `Instance` class
+
+Instantiates a WebAssembly module represented by bytes, and calls exported functions on it:
+
+```ruby
+require "wasmer"
+
+# Get the Wasm module as bytes.
+wasm_bytes = IO.read "my_program.wasm", mode: "rb"
+
+# Instantiates the Wasm module.
+instance = Instance.new wasm_bytes
+
+# Call a function on it.
+result = instance.exports.sum 1, 2
+
+puts result # 3
+```
+
+All exported functions are accessible on the `exports`
+getter. Arguments of these functions are automatically casted to
+WebAssembly values.
+
+The `memory` getter exposes the `Memory` class representing the memory
+of that particular instance, e.g.:
+
+```ruby
+view = instance.memory.uint8_view
+```
+
+See below for more information.
+
+### The `Memory` class
+
+A WebAssembly instance has its own memory, represented by the `Memory`
+class. It is accessible by the `Instance.memory` getter.
+
+The `Memory` class offers methods to create views of the memory
+internal buffer, e.g. `uint8_view`, `int8_view`, `uint16_view`
+etc. All these methods accept one optional argument: `offset`, to
+subset the memory buffer at a particular offset. These methods return
+respectively a `*Array` object, i.e. `uint8_view` returns a
+`Uint8Array` object etc.
+
+```ruby
+offset = 7
+view = instance.memory.uint8_view offset
+
+puts view[0]
+```
+
+#### The `*Array` classes
+
+These classes represent views over a memory buffer of an instance.
+
+| Class | View buffer as a sequence of… | Bytes per element |
+|-|-|-|
+| `Int8Array` | `int8` | 1 |
+| `Uint8Array` | `uint8` | 1 |
+| `Int16Array` | `int16` | 2 |
+| `Uint16Array` | `uint16` | 2 |
+| `Int32Array` | `int32` | 4 |
+| `Uint32Array` | `uint32` | 4 |
+
+All these classes share the same implementation. Taking the example of
+`Uint8Array`, the class looks like this:
+
+```ruby
+class Uint8Array
+    def bytes_per_element
+    def length
+    def [](index)
+    def []=(index, value)
+end
+```
+
+Let's see it in action:
+
+```ruby
+require "wasmer"
+
+# Get the Wasm module as bytes.
+wasm_bytes = IO.read "my_program.wasm", mode: "rb"
+
+# Instantiates the Wasm module.
+instance = Instance.new wasm_bytes
+
+# Call a function that returns a pointer to a string for instance.
+pointer = instance.exports.return_string
+
+# Get the memory view, with the offset set to `pointer` (default is 0).
+memory = instance.memory.uint8_view pointer
+
+# Read the string pointed by the pointer.
+nth = 0
+string = ""
+
+while true
+  char = memory[nth]
+
+  if 0 == char
+    break
+  end
+
+  string += char.chr
+  nth += 1
+end
+
+puts string # Hello, World!
+```
+
+Notice that `*Array` treat bytes in little-endian, as required by the
+WebAssembly specification, [Chapter Structure, Section Instructions,
+Sub-Section Memory
+Instructions](https://webassembly.github.io/spec/core/syntax/instructions.html#memory-instructions):
+
+> All values are read and written in [little
+> endian](https://en.wikipedia.org/wiki/Endianness#Little-endian) byte
+> order.
+
+Each view shares the same memory buffer internally. Let's have some fun:
+
+```ruby
+int8 = instance.memory.int8_view
+int16 = instance.memory.int16_view
+int32 = instance.memory.int32_view
+
+               b₁
+            ┌┬┬┬┬┬┬┐
+int8[0] = 0b00000001
+               b₂
+            ┌┬┬┬┬┬┬┐
+int8[1] = 0b00000100
+               b₃
+            ┌┬┬┬┬┬┬┐
+int8[2] = 0b00010000
+               b₄
+            ┌┬┬┬┬┬┬┐
+int8[3] = 0b01000000
+
+// No surprise with the following assertions.
+                  b₁
+               ┌┬┬┬┬┬┬┐
+assert_equal 0b00000001, int8[0]
+                  b₂
+               ┌┬┬┬┬┬┬┐
+assert_equal 0b00000100, int8[1]
+                  b₃
+               ┌┬┬┬┬┬┬┐
+assert_equal 0b00010000, int8[2]
+                  b₄
+               ┌┬┬┬┬┬┬┐
+assert_equal 0b01000000, int8[3]
+
+// The `int16` view reads 2 bytes.
+                  b₂       b₁
+               ┌┬┬┬┬┬┬┐ ┌┬┬┬┬┬┬┐
+assert_equal 0b00000100_00000001, int16[0]
+                  b₄       b₃
+               ┌┬┬┬┬┬┬┐ ┌┬┬┬┬┬┬┐
+assert_equal 0b01000000_00010000, int16[1]
+
+// The `int32` view reads 4 bytes.
+                  b₄       b₃       b₂       b₁
+               ┌┬┬┬┬┬┬┐ ┌┬┬┬┬┬┬┐ ┌┬┬┬┬┬┬┐ ┌┬┬┬┬┬┬┐
+assert_equal 0b01000000_00010000_00000100_00000001, int32[0]
+```
+
+### The `Module` class
+
+The `Module` class contains one static method `validate`, that checks
+whether the given bytes represent valid WebAssembly bytes:
+
+```ruby
+require "wasmer"
+
+wasm_bytes = IO.read "my_program.wasm", mode: "rb"
+
+if not Module.validate wasm_bytes
+    puts "The program seems corrupted."
+end
+```
+
+This function returns a boolean.
+
+## Install and Testing
+
+To compile the entire project, run the following commands:
+
+```sh
+$ just build
+$ just test
+$ ruby examples/simple.rb
+```
+
+(Yes, you need [`just`](https://github.com/casey/just/)).
+
+## License
+
+The entire project is under the BSD-3-Clause license. Please read [the
+`LICENSE` file][license].
+
+
+[license]: https://github.com/wasmerio/wasmer/blob/master/LICENSE

data/Rakefile

@@ -0,0 +1,21 @@
+require "rbconfig"
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+desc 'Build the Rust extension'
+task :build_lib do
+  sh 'cargo build --release'
+end
+
+desc 'Install the bundle'
+task :bundle_install do
+  sh 'bundle install'
+end
+
+Rake::TestTask.new(test: [:bundle_install, :build_lib]) do |t|
+  t.libs << "tests"
+  t.libs << "lib"
+  t.test_files = FileList["tests/**/*_test.rb"]
+end
+
+task :default => :test

data/justfile

@@ -0,0 +1,23 @@
+# Compile and install the Ruby extension.
+build:
+	rake build_lib
+
+# Run the tests.
+test:
+	rake test
+
+# Build the `.gem` file.
+gem:
+	rake build
+
+# Clean the project.
+clean:
+	cargo clean
+	rake clean
+	rake clobber
+
+
+# Local Variables:
+# mode: makefile
+# End:
+# vim: set ft=make :

data/lib/wasmer.rb

@@ -0,0 +1,6 @@
+require 'wasmer/version'
+require 'rutie'
+
+module Wasmer
+  Rutie.new(:wasmer).init 'Init_wasmer', __dir__
+end

data/lib/wasmer/version.rb

@@ -0,0 +1,3 @@
+module Wasmer
+  VERSION = "0.1.1"
+end

data/src/instance.rs

@@ -0,0 +1,282 @@
+//! The `Instance` WebAssembly class.
+
+use crate::memory::{Memory, RubyMemory, MEMORY_WRAPPER};
+use lazy_static::lazy_static;
+use rutie::{
+    class, methods,
+    rubysys::{class, value::ValueType},
+    types::{Argc, Value},
+    util::str_to_cstring,
+    wrappable_struct, AnyException, AnyObject, Array, Class, Exception, Fixnum, Float, Object,
+    RString, Symbol, VM,
+};
+use std::{mem, rc::Rc};
+use wasmer_runtime::{self as runtime, imports, Export};
+use wasmer_runtime_core::types::Type;
+
+/// The `ExportedFunctions` Ruby class.
+pub struct ExportedFunctions {
+    /// The WebAssembly runtime.
+    instance: Rc<runtime::Instance>,
+}
+
+impl ExportedFunctions {
+    /// Create a new instance of the `ExportedFunctions` Ruby class.
+    pub fn new(instance: Rc<runtime::Instance>) -> Self {
+        Self { instance }
+    }
+
+    /// Call an exported function on the given WebAssembly instance.
+    pub fn method_missing(&self, method_name: &str, arguments: Array) -> AnyObject {
+        let function = self
+            .instance
+            .dyn_func(method_name)
+            .map_err(|_| {
+                VM::raise_ex(AnyException::new(
+                    "RuntimeError",
+                    Some(&format!("Function `{}` does not exist.", method_name)),
+                ))
+            })
+            .unwrap();
+        let signature = function.signature();
+        let parameters = signature.params();
+        let number_of_parameters = parameters.len() as isize;
+        let number_of_arguments = arguments.length() as isize;
+        let diff: isize = number_of_parameters - number_of_arguments;
+
+        if diff > 0 {
+            VM::raise_ex(AnyException::new(
+                "ArgumentError",
+                Some(&format!(
+                    "Missing {} argument(s) when calling `{}`: Expect {} argument(s), given {}.",
+                    diff, method_name, number_of_parameters, number_of_arguments
+                )),
+            ));
+            unreachable!();
+        } else if diff < 0 {
+            VM::raise_ex(AnyException::new(
+                "ArgumentError",
+                Some(&format!(
+                    "Given {} extra argument(s) when calling `{}`: Expect {} argument(s), given {}.",
+                    diff.abs(), method_name, number_of_parameters, number_of_arguments
+                )),
+            ));
+            unreachable!();
+        }
+
+        let mut function_arguments =
+            Vec::<runtime::Value>::with_capacity(number_of_parameters as usize);
+
+        for (nth, (parameter, argument)) in parameters.iter().zip(arguments.into_iter()).enumerate()
+        {
+            let value = match (parameter, argument.ty()) {
+                (Type::I32, ValueType::Fixnum) => runtime::Value::I32(
+                    argument
+                        .try_convert_to::<Fixnum>()
+                        .map_err(|_| {
+                            VM::raise_ex(AnyException::new(
+                                "TypeError",
+                                Some(&format!(
+                                    "Cannot convert argument #{} to a WebAssembly i32 value.",
+                                    nth + 1
+                                )),
+                            ))
+                        })
+                        .unwrap()
+                        .to_i32(),
+                ),
+                (Type::I64, ValueType::Fixnum) => runtime::Value::I64(
+                    argument
+                        .try_convert_to::<Fixnum>()
+                        .map_err(|_| {
+                            VM::raise_ex(AnyException::new(
+                                "TypeError",
+                                Some(&format!(
+                                    "Cannot convert argument #{} to a WebAssembly i64 value.",
+                                    nth + 1
+                                )),
+                            ))
+                        })
+                        .unwrap()
+                        .to_i64(),
+                ),
+                (Type::F32, ValueType::Float) => runtime::Value::F32(
+                    argument
+                        .try_convert_to::<Float>()
+                        .map_err(|_| {
+                            VM::raise_ex(AnyException::new(
+                                "TypeError",
+                                Some(&format!(
+                                    "Cannot convert argument #{} to a WebAssembly f32 value.",
+                                    nth + 1
+                                )),
+                            ))
+                        })
+                        .unwrap()
+                        .to_f64() as f32,
+                ),
+                (Type::F64, ValueType::Float) => runtime::Value::F64(
+                    argument
+                        .try_convert_to::<Float>()
+                        .map_err(|_| {
+                            VM::raise_ex(AnyException::new(
+                                "TypeError",
+                                Some(&format!(
+                                    "Cannot convert argument #{} to a WebAssembly f64 value.",
+                                    nth + 1
+                                )),
+                            ))
+                        })
+                        .unwrap()
+                        .to_f64(),
+                ),
+                (_, ty) => {
+                    VM::raise_ex(AnyException::new(
+                        "ArgumentError",
+                        Some(&format!(
+                            "Cannot convert argument #{} to a WebAssembly value. Only integers and floats are supported. Given `{:?}`.",
+                            nth + 1,
+                            ty
+                        ))));
+                    unreachable!()
+                }
+            };
+
+            function_arguments.push(value);
+        }
+
+        let results = function
+            .call(function_arguments.as_slice())
+            .map_err(|e| VM::raise_ex(AnyException::new("RuntimeError", Some(&format!("{}", e)))))
+            .unwrap();
+
+        match results[0] {
+            runtime::Value::I32(result) => Fixnum::new(result as i64).into(),
+            runtime::Value::I64(result) => Fixnum::new(result).into(),
+            runtime::Value::F32(result) => Float::new(result as f64).into(),
+            runtime::Value::F64(result) => Float::new(result).into(),
+        }
+    }
+}
+
+wrappable_struct!(
+    ExportedFunctions,
+    ExportedFunctionsWrapper,
+    EXPORTED_FUNCTIONS_WRAPPER
+);
+
+class!(RubyExportedFunctions);
+
+/// Glue code to call the `ExportedFunctions.method_missing` method.
+pub extern "C" fn ruby_exported_functions_method_missing(
+    argc: Argc,
+    argv: *const AnyObject,
+    itself: RubyExportedFunctions,
+) -> AnyObject {
+    let arguments = Value::from(0);
+
+    unsafe {
+        let argv_pointer: *const Value = mem::transmute(argv);
+
+        class::rb_scan_args(argc, argv_pointer, str_to_cstring("*").as_ptr(), &arguments)
+    };
+
+    let mut arguments = Array::from(arguments);
+    let method_name = unsafe { arguments.shift().to::<Symbol>() };
+    let method_name = method_name.to_str();
+
+    itself
+        .get_data(&*EXPORTED_FUNCTIONS_WRAPPER)
+        .method_missing(method_name, arguments)
+}
+
+/// The `Instance` Ruby class.
+pub struct Instance {
+    /// The WebAssembly instance.
+    instance: Rc<runtime::Instance>,
+}
+
+impl Instance {
+    /// Create a new instance of the `Instance` Ruby class.
+    /// The constructor receives bytes from a string.
+    pub fn new(bytes: &[u8]) -> Self {
+        let import_object = imports! {};
+        let instance = Rc::new(
+            runtime::instantiate(bytes, &import_object)
+                .map_err(|e| {
+                    VM::raise_ex(AnyException::new(
+                        "RuntimeError",
+                        Some(&format!("Failed to instantiate the module:\n    {}", e)),
+                    ))
+                })
+                .unwrap(),
+        );
+
+        Self { instance }
+    }
+}
+
+wrappable_struct!(Instance, InstanceWrapper, INSTANCE_WRAPPER);
+
+class!(RubyInstance);
+
+#[rustfmt::skip]
+methods!(
+    RubyInstance,
+    _itself,
+    // Glue code to call the `Instance.new` method.
+    fn ruby_instance_new(bytes: RString) -> AnyObject {
+        let instance = Instance::new(
+            bytes
+                .map_err(|_| {
+                    VM::raise_ex(AnyException::new(
+                        "ArgumentError",
+                        Some("WebAssembly module must be represented by Ruby bytes only."),
+                    ))
+                })
+                .unwrap()
+                .to_bytes_unchecked(),
+        );
+        let exported_functions = ExportedFunctions::new(instance.instance.clone());
+
+        let memory = instance
+            .instance
+            .exports()
+            .find_map(|(_, export)| match export {
+                Export::Memory(memory) => Some(Memory::new(Rc::new(memory))),
+                _ => None,
+            })
+            .ok_or_else(|| VM::raise_ex(AnyException::new("RuntimeError", Some("The WebAssembly module has no exported memory."))))
+            .unwrap();
+
+        let mut ruby_instance: AnyObject =
+            Class::from_existing("Instance").wrap_data(instance, &*INSTANCE_WRAPPER);
+
+        let ruby_exported_functions: RubyExportedFunctions =
+            Class::from_existing("ExportedFunctions")
+                .wrap_data(exported_functions, &*EXPORTED_FUNCTIONS_WRAPPER);
+
+        ruby_instance.instance_variable_set("@exports", ruby_exported_functions);
+
+        let ruby_memory: RubyMemory =
+            Class::from_existing("Memory").wrap_data(memory, &*MEMORY_WRAPPER);
+
+        ruby_instance.instance_variable_set("@memory", ruby_memory);
+
+        ruby_instance
+    }
+
+    // Glue code to call the `Instance.exports` getter method.
+    fn ruby_instance_exported_functions() -> RubyExportedFunctions {
+        unsafe {
+            _itself
+                .instance_variable_get("@exports")
+                .to::<RubyExportedFunctions>()
+        }
+    }
+
+    // Glue code to call the `Instance.memory` getter method.
+    fn ruby_instance_memory() -> RubyMemory {
+        unsafe { _itself.instance_variable_get("@memory").to::<RubyMemory>() }
+    }
+);