second-state / ssvm-napi

SSVM Node.js Addon

Second State WebAssembly VM for Node.js Addon

The Second State VM (SSVM) is a high-performance WebAssembly runtime optimized for server-side applications. This project provides support for accessing SSVM as a Node.js addon. It allows Node.js applications to call WebAssembly functions written in Rust or other high-performance languages. Why do you want to run WebAssembly on the server-side? The SSVM addon could interact with the wasm files generated by the ssvmup compiler tool.

NOTICE

SSVM Node.js Addon is in active development.

In the current stage, our prebuilt version only supports x86_64 and aarch64 Linux. Or you could use --build-from-source flag to build from source during addon installation.

Requirements

After SSVM Napi 0.4.0 release, we upgrade the base image from Ubuntu 18.04 to Ubuntu 20.04.

Users should install the dependencies by the following requirments:

• boost >= 1.65.0
• llvm >= 10
• liblld-10-dev >= 10
• libstdc++6 >= 6.0.28 (GLIBCXX >= 3.4.28)
• g++ version >= 9.0 (Optional, if you have to build from source)

Prepare environment

Use our docker image (recommended)

$ docker pull secondstate/ssvm

For ubuntu 20.04

# Tools and libraries
$ sudo apt install -y \
	software-properties-common \
	cmake \
	libboost-all-dev

# And you will need to install llvm for ssvm-aot tools
$ sudo apt install -y \
	llvm-dev \
	liblld-10-dev

# SSVM supports both clang++ and g++ compilers
# You can choose one of them for building this project
$ sudo apt install -y gcc g++
$ sudo apt install -y clang

Verify the version of llvm

$ sudo apt list | grep llvm
...omitted...
llvm-dev/focal,now 1:10.0-50~exp1 amd64 [installed]
llvm-runtime/focal,now 1:10.0-50~exp1 amd64 [installed,automatic]
llvm/focal,now 1:10.0-50~exp1 amd64 [installed,automatic]
...omitted...

# If the version is 1:10.x, then your llvm version is correct.

Verify the version of libstdc++6

$ strings /usr/lib/x86_64-linux-gnu/libstdc++.so.6 | grep GLIBCXX
...omitted...
GLIBCXX_3.4.24
GLIBCXX_3.4.25
GLIBCXX_3.4.26
GLIBCXX_3.4.27
GLIBCXX_3.4.28
GLIBCXX_DEBUG_MESSAGE_LENGTH

# If you can find GLIBCXX_3.4.28 in the output, then your libstdc++6 version is correct.

Works with Rust library using Wasm-Bindgen

Please refer to Tutorial: A Wasm-Bindgen application.

Works with Rust application using standalone wasm32-wasi backend

Please refer to Tutorial: A standalone wasm32-wasi application.

APIs

Constructor: ssvm.VM(wasm, ssvm_options) -> vm_instance

• Create a ssvm instance by given wasm file and options.
• Arguments:
  • wasm: Input wasm file, can be the following three formats:
    1. Wasm file path (String, e.g. /tmp/hello.wasm)
    2. Wasm bytecode format which is the content of a wasm binary file (Uint8Array)
  • options: An options object for setup the SSVM execution environment.
    • options
      • args : An array of strings that Wasm application will get as function arguments. Default: [].
      • env : An object like process.env that Wasm application will get as its environment variables. Default: {}.
      • preopens : An object which maps '<guest_path>:<host_path>'. E.g. {'/sandbox': '/some/real/path/that/wasm/can/access'} Default: {}.
      • EnableWasiStartFunction : This option will disable wasm-bindgen mode and prepare the working environment for standalone wasm program. If you want to run an appliation with main(), you should set this to true. Default: false.
      • EnableAOT : This option will enable ssvm aot mode. Default: false.
      • EnableMeasurement : This option will enable measurement but decrease its performance. Default: false.
      • AllowCommands : An array of strings that indicate what commands are allowed to execute in the SSVM Process Module. Default [].
      • AllowAllCommands : Allow users to call any command in the SSVM Process Module. This option will overwrite the AllowCommands. Default: false.
• Return value:
  • vm_instance: A ssvm instance.

Methods

Start() -> Integer

• Emit _start() and expect the return value type is Integer which represents the error code from main().
• Arguments:
  • If you want to append arguments for the standalone wasm program, please set the args in wasi options.
• Example:

let error_code = Start();

Run(function_name, args...) -> void

• Emit function_name with args and expect the return value type is void.
• Arguments:
  • function_name : The function name which users want to emit.
  • args <Integer/String/Uint8Array>*: The function arguments. The delimiter is ,
• Example:

Run("Print", 1234);

RunInt(function_name, args...) -> Integer

• Emit function_name with args and expect the return value type is Integer (Int32).
• Arguments:
  • function_name : The function name which users want to emit.
  • args <Integer/String/Uint8Array>*: The function arguments. The delimiter is ,
• Example:

let result = RunInt("Add", 1, 2);
// result should be 3

RunUInt(function_name, args...) -> Integer

• Emit function_name with args and expect the return value type is Integer (UInt32).
• Arguments:
  • function_name : The function name which users want to emit.
  • args <Integer/String/Uint8Array>*: The function arguments. The delimiter is ,
• Example:

let result = RunInt("Add", 1, 2);
// result should be 3

RunInt64(function_name, args...) -> BigInt

• Emit function_name with args and expect the return value type is BigInt (Int64).
• Arguments:
  • function_name : The function name which users want to emit.
  • args <Integer/String/Uint8Array>*: The function arguments. The delimiter is ,
• Example:

let result = RunInt("Add", 1, 2);
// result should be 3

RunUInt64(function_name, args...) -> BigInt

• Emit function_name with args and expect the return value type is BigInt (UInt64).
• Arguments:
  • function_name : The function name which users want to emit.
  • args <Integer/String/Uint8Array>*: The function arguments. The delimiter is ,
• Example:

let result = RunInt("Add", 1, 2);
// result should be 3

RunString(function_name, args...) -> String

• Emit function_name with args and expect the return value type is String.
• Arguments:
  • function_name : The function name which users want to emit.
  • args <Integer/String/Uint8Array>*: The function arguments. The delimiter is ,
• Example:

let result = RunString("PrintMathScore", "Amy", 98);
// result: "Amy’s math score is 98".

RunUint8Array(function_name, args...) -> Uint8Array

• Emit function_name with args and expect the return value type is Uint8Array.
• Arguments:
  • function_name : The function name which users want to emit.
  • args <Integer/String/Uint8Array>*: The function arguments. The delimiter is ,
• Example:

let result = RunUint8Array("Hash", "Hello, world!");
// result: "[12, 22, 33, 42, 51]".

Compile(output_filename) -> boolean

• Compile a given wasm file (can be a file path or a byte array) into a native binary whose name is the given output_filename.
• This function uses SSVM AOT compiler.
• Return false when the compilation failed.

// Compile only
let vm = ssvm.VM("/path/to/wasm/file", options);
vm.Compile("/path/to/aot/file");

// When you want to run the compiled file
let vm = ssvm.VM("/path/to/aot/file", options);
vm.RunXXX("Func", args);

GetStatistics() -> Object

• If you want to enable measurement, set the option EnableMeasurement to true. But please notice that enabling measurement will significantly affect performance.
• Get the statistics of execution runtime.
• Return Value Statistics
  • Measure -> : To show if the measurement is enabled or not.
  • TotalExecutionTime -> : Total execution time (Wasm exeuction time + Host function execution time) in `` unit.
  • WasmExecutionTime -> : Wasm instructions execution time in ns unit.
  • HostFunctionExecutionTime -> : Host functions (e.g. eei or wasi functions) execution time in ns unit.
  • InstructionCount -> : The number of executed instructions in this execution.
  • TotalGasCost -> : The cost of this execution.
  • InstructionPerSecond -> : The instructions per second of this execution.

  let result = RunInt("Add", 1, 2);
  // result should be 3
  let stat = GetStatistics();
  /*
  If the `EnableMeasurement: true`:
  
  stat = Statistics:  {
    Measure: true,
    TotalExecutionTime: 1512,
    WasmExecutionTime: 1481,
    HostFunctionExecutionTime: 31,
    InstructionCount: 27972,
    TotalGasCost: 27972,
    InstructionPerSecond: 18887238.35246455
  }
  
  Else:
  
  stat = Statistics:  {
    Measure: false
  }
  */

ssvm-napi's Issues

vm.Run not a function

hi, I just copy the example
pub fn store_bytes (data: &[u8]){ println!("{:?}", data); }
and run
ssvmup build
and generate

module.exports.store_bytes = function(data) { if (Buffer.isBuffer(data) && data.byteLength < Buffer.poolSize) data = new Uint8Array(data.buffer.slice(data.byteOffset, data.byteOffset + data.byteLength)); vm.Run('store_bytes', data); };
but vm.Run not a function

Node.js crashes at CTRL-C

When I press CTRL-C to quit a node.js server when running SSVM, it crashes with the following message.

FATAL [default] CRASH HANDLED; Application has crashed due to [SIGINT] signal
    ======= Backtrace: =========
    [1]  0x65ad8) [0x7fa989a3ead8]:_modules/ssvm/lib/binding/linux-x64/ssvm.node(+0x65ad8) [0x7fa989a3ead8]
    [2]  0x46470) [0x7fa98c3f6470]:_64-linux-gnu/libc.so.6(+0x46470) [0x7fa98c3f6470]
    [3]  0x76) [0x7fa98c4d2416]:_64-linux-gnu/libc.so.6(epoll_pwait+0x76) [0x7fa98c4d2416]
    [4] node() [0xa80f1f]
    [5]  0x14b) [0xa7012b]:_run+0x14b) [0xa7012b]
    [6]  0x565) [0x9045b5]:_ZN4node5StartEPN2v87IsolateEPNS_11IsolateDataERKSt6vectorISsSaISsEES9_+0x565) [0x9045b5]
    [7]  0x48f) [0x90282f]:_ZN4node5StartEiPPc+0x48f) [0x90282f]
    [8]  0xf3) [0x7fa98c3d71e3]:_64-linux-gnu/libc.so.6(__libc_start_main+0xf3) [0x7fa98c3d71e3]
    [9] node() [0x8bbe95]

2020-07-29 00:12:46,638 WARNING [default] Aborting application. Reason: Fatal log at [../ssvm-core/thirdparty/easyloggingpp/easylogging++.cc:2876]
Aborted

Rename to WasmEdge-napi

After SSVM becomes CNCF's sandbox project, we will need to rename the related tools to WasmEdge- prefix.

Support for Big Sur on x64?

Fails on npm -o as there is no Darwin tar ball?

Is there some other steps required?

Implement a new API to get exported wasm functions

VM instantiation using Buffer (as apposed to string)

At present the VM instantiation is coded to accept a hex string.

Joey is storing the native wasm executables and instantiating the VM using Buffer with the belief that SSVM no longer needs to convert native wasm into hex string any more.

When instantiating a VM instance, Joey gets the following error (node:22715) UnhandledPromiseRejectionWarning: Error: wasm file expected

Can SSVM be changed to accept Buffer instead of string?

Thank you

missing releases for arm64

I'm trying to install SSVM on RPiOS with npm, which throws a 404 on https://github.com/second-state/ssvm-napi/releases/download/0.7.3/ssvm-linux-arm.tar.gz. I checked and there are no releases for ARM for versions 0.7.2 and 0.7.3.

Here are the installation logs (shortened bc of failed source compilation)

> [email protected] install /home/pi/Documents/nodejs-rust/smartcore-ssvm/node_modules/ssvm
> node-pre-gyp install --fallback-to-build

node-pre-gyp ERR! install response status 404 Not Found on https://github.com/second-state/ssvm-napi/releases/download/0.7.3/ssvm-linux-arm.tar.gz
node-pre-gyp WARN Pre-built binaries not installable for [email protected] and [email protected] (node-v83 ABI, glibc) (falling back to source compile with node-gyp)
node-pre-gyp WARN Hit error response status 404 Not Found on https://github.com/second-state/ssvm-napi/releases/download/0.7.3/ssvm-linux-arm.tar.gz

Is there any limitation on which node version can be used?

Additional info

$ node -v
v14.16.1

$ npm -v
6.14.12

uname -a
Linux raspberrypi 4.19.57-v7+ #1244 SMP Thu Jul 4 18:45:25 BST 2019 armv7l GNU/Linux