Running Rust in the Browser with Web Assembly

Running Rust in the Browser with WASM

The post Running Rust in the Browser with Web Assembly first appeared on Qvault.

I’ve recently been working on a Rust course for the Qvault app. In order to write a more engaging course, I want students to be able to write and execute code right in the browser. As I’ve learned from my previous posts on this topic, the easiest way to sandbox code execution on a server is to not execute code on a server. Enter Web Assembly, stage left.

For those of you who don’t care about how it works, and just want to give it a try, checkout the demo: Rust WASM Playground.

How It Works

The architecture is fairly simple:

  • User writes code in the browser
  • Browser sends code to server
  • Server adds some glue and compiles code to WASM
  • Server sends WASM bytes or compiler errors back to browser
  • Browser runs WASM and displays console output, or shows compiler errors

Writing code and shipping it to the server hopefully needs no explanation, it’s a simple text editor coupled with the fetch API. The first interesting thing we do is compile the code on the server.

Compiling the Code

Qvault’s server is written in Go. I have a simple HTTP handler with the following signature:

func (cfg config) compileRustHandler(w http.ResponseWriter, r *http.Request)

At the start of the function we unmarshal the code which was provided in a JSON body:

type parameters struct {
        Code string
}

decoder := json.NewDecoder(r.Body)
params := parameters{}
err := decoder.Decode(&params)
if err != nil {
        respondWithError(w, 500, "Couldn't decode parameters")
        return
}

Next, we create a temporary folder on disk that we’ll use as a “scratch pad” to create a Rust project.

usr, err := user.Current()
if err != nil {
        respondWithError(w, 500, "Couldn't get system user")
        return
}
workingDir := filepath.Join(usr.HomeDir, ".wasm", uuid.New().String())
err = os.MkdirAll(workingDir, os.ModePerm)
if err != nil {
        respondWithError(w, 500, "Couldn't create directory for compilation")
        return
}
defer func() {
        err = os.RemoveAll(workingDir)
        if err != nil {
                respondWithError(w, 500, "Couldn't clean up code from compilation")
                return
        }
}()

As you can see, we create the project under the .wasm/uuid path in the home directory. We also defer an os.RemoveAll function that will delete this folder when we are doing handling this request.

Next we setup a helper function that will run an operating system command and return the stderr, if it exists:

func runCmd(workingDir, name string, args ...string) error {
        cmd := exec.Command(name, args...)
        cmd.Dir = filepath.Join(workingDir)
        stdErrReader, err := cmd.StderrPipe()
        if err != nil {
                return err
        }
        if err := cmd.Start(); err != nil {
                return err
        }
        stdErr, err := ioutil.ReadAll(stdErrReader)
        if err != nil {
                return err
        }
        if err := cmd.Wait(); err != nil {
                if len(stdErr) > 0 {
                        return fmt.Errorf("%s", stdErr)
                }
                return err
        }
        return nil
}

Next, (back in the HTTP handler) we use that function to create a new Rust project in our temporary directory:

const projectName = "main"
err = runCmd(workingDir, "cargo", "new", projectName)
if err != nil {
        respondWithError(w, 500, err.Error())
        return
}

After that, we need to write the code we were given to disk. Before we do that, however, we need to add some glue. The glue code will override Rust’s print macros so that we can provide JavaScript functions that will capture stdout. I thank Sterling Demille for open sourcing this glue:

// copied from https://github.com/DeMille/wasm-glue
#![feature(set_stdio)]
#![feature(panic_col)]

use std::ffi::CString;
use std::os::raw::c_char;
use std::fmt;
use std::fmt::Write;
use std::panic;
use std::io;


// these are the functions you'll need to privide with JS
extern {
    fn print(ptr: *const c_char);
    fn eprint(ptr: *const c_char);
    fn trace(ptr: *const c_char);
}


fn _print(buf: &str) -> io::Result<()> {
    let cstring = CString::new(buf)?;

    unsafe {
        print(cstring.as_ptr());
    }

    Ok(())
}

fn _eprint(buf: &str) -> io::Result<()> {
    let cstring = CString::new(buf)?;

    unsafe {
        eprint(cstring.as_ptr());
    }

    Ok(())
}

/// Used by the "print" macro
#[doc(hidden)]
pub fn _print_args(args: fmt::Arguments) {
    let mut buf = String::new();
    let _ = buf.write_fmt(args);
    let _ = _print(&buf);
}

/// Used by the "eprint" macro
#[doc(hidden)]
pub fn _eprint_args(args: fmt::Arguments) {
    let mut buf = String::new();
    let _ = buf.write_fmt(args);
    let _ = _eprint(&buf);
}

/// Overrides the default "print!" macro.
#[macro_export]
macro_rules! print {
    ($($arg:tt)*) => ($crate::_print_args(format_args!($($arg)*)));
}

/// Overrides the default "eprint!" macro.
#[macro_export]
macro_rules! eprint {
    ($($arg:tt)*) => ($crate::_eprint_args(format_args!($($arg)*)));
}


type PrintFn = fn(&str) -> io::Result<()>;

struct Printer {
    printfn: PrintFn,
    buffer: String,
    is_buffered: bool,
}

impl Printer {
    fn new(printfn: PrintFn, is_buffered: bool) -> Printer {
        Printer {
            buffer: String::new(),
            printfn,
            is_buffered,
        }
    }
}

impl io::Write for Printer {
    fn write(&mut self, buf: &[u8]) -> io::Result<usize> {
        self.buffer.push_str(&String::from_utf8_lossy(buf));

        if !self.is_buffered {
            (self.printfn)(&self.buffer)?;
            self.buffer.clear();

            return Ok(buf.len());
        }

        if let Some(i) = self.buffer.rfind('\n') {
            let buffered = {
                let (first, last) = self.buffer.split_at(i);
                (self.printfn)(first)?;

                String::from(&last[1..])
            };

            self.buffer.clear();
            self.buffer.push_str(&buffered);
        }

        Ok(buf.len())
    }

    fn flush(&mut self) -> io::Result<()> {
        (self.printfn)(&self.buffer)?;
        self.buffer.clear();

        Ok(())
    }
}


/// Sets a line-buffered stdout, uses your JavaScript "print" function
pub fn set_stdout() {
    let printer = Printer::new(_print, true);
    io::set_print(Some(Box::new(printer)));
}

/// Sets an unbuffered stdout, uses your JavaScript "print" function
pub fn set_stdout_unbuffered() {
    let printer = Printer::new(_print, false);
    io::set_print(Some(Box::new(printer)));
}

/// Sets a line-buffered stderr, uses your JavaScript "eprint" function
pub fn set_stderr() {
    let eprinter = Printer::new(_eprint, true);
    io::set_panic(Some(Box::new(eprinter)));
}

/// Sets an unbuffered stderr, uses your JavaScript "eprint" function
pub fn set_stderr_unbuffered() {
    let eprinter = Printer::new(_eprint, false);
    io::set_panic(Some(Box::new(eprinter)));
}

/// Sets a custom panic hook, uses your JavaScript "trace" function
pub fn set_panic_hook() {
    panic::set_hook(Box::new(|info| {
        let file = info.location().unwrap().file();
        let line = info.location().unwrap().line();
        let col = info.location().unwrap().column();

        let msg = match info.payload().downcast_ref::<&'static str>() {
            Some(s) => *s,
            None => {
                match info.payload().downcast_ref::<String>() {
                    Some(s) => &s[..],
                    None => "Box<Any>",
                }
            }
        };

        let err_info = format!("Panicked at '{}', {}:{}:{}", msg, file, line, col);
        let cstring = CString::new(err_info).unwrap();

        unsafe {
            trace(cstring.as_ptr());
        }
    }));
}

/// Sets stdout, stderr, and a custom panic hook
pub fn hook() {
    set_stdout();
    set_stderr();
    set_panic_hook();
}

All we need to do is concatenate that glue code to the user provided code, and call hook() as the first thing in main().

func writeRustToDisk(workingDir, projectName, code string) error {
        // remove old code
        codePath := filepath.Join(workingDir, projectName, "src", "main.rs")
        os.Remove(codePath)

        // create the new file
        f, err := os.Create(codePath)
        if err != nil {
                return errors.New("Couldn't open code file for compilation")
        }
        defer f.Close()

        // write the glue
        _, err = f.WriteString(rustGlue)
        if err != nil {
                return errors.New("Couldn't write code to file for compilation")
        }

        // add the hook
        code = addHook(code)

        // write the rest of the code
        dat := []byte(code)
        _, err = f.Write(dat)
        if err != nil {
                return errors.New("Couldn't write code to file for compilation")
        }
        return nil
}

Where rustGlue is just a string constant containing the glue from the previous step, and addHook is a function that uses a regex to insert the hook() call properly:

func addHook(code string) string {
        regex := regexp.MustCompile(`(fn\s*main\(\)\s*)\{`)
        return regex.ReplaceAllString(code, `fn main(){hook();`)
}

Next, the all-important compilation step:

err = runCmd(
        filepath.Join(workingDir, projectName),
        "cargo",
        "+nightly",
        "build",
        "--target",
        "wasm32-unknown-unknown",
        "--release",
)
if err != nil {
        errString := err.Error()
        fmt.Println(errString)
        parts := strings.Split(errString, workingDir)
        if len(parts) < 2 {
                respondWithError(w, 500, errString)
                return
        }
        respondWithError(w, 400, parts[1])
        return
}

A simple cargo build with WASM as the target. If there is an error, we strip out some of the filesystem information before sending it back to the frontend.

We use wasm-gc to optimize the build:

err = runCmd(
        filepath.Join(workingDir, projectName),
        "wasm-gc",
        "target",
        "wasm32-unknown-unknown",
        "release",
        "main.wasm",
)
if err != nil {
        respondWithError(w, 500, err.Error())
        return
}

Finally we send the WASM back to the frontend as raw bytes:

dat, err := ioutil.ReadFile(filepath.Join(workingDir, projectName, "target", "wasm32-unknown-unknown", "release", "main.wasm"))
if err != nil {
        respondWithError(w, 500, err.Error())
        return
}
w.Write(dat)

Frontend – Executing the WASM Bundle

The Rust front-end has a lot of similarities to the Go front end. They both use Web Workers to optimize the user experience of executing potentially expensive code in the browser. If you need to catch-up on how that’s done, read up on my web workers explanation here.

The main difference here comes down to the rust_worker.js file. The equivalent of go_worker.js from the referenced article:

// send(line) sends a single line of stdout back to the browser to // be rendered in the on-screen console
function send(line){
  postMessage({
    message: readString(line)
  });
}

// keep a WebAssembly memory reference for readString
let memory;

// read a null terminated c string at a wasm memory buffer index
function readString(ptr) {
  const view = new Uint8Array(memory.buffer);

  let end = ptr;
  while (view[end]) ++end;

  const buf = new Uint8Array(view.subarray(ptr, end));
  return (new TextDecoder()).decode(buf);
}

// addEventListener is a handler that get's called whenever the
// main thread (editor) sends us some WASM to execute
addEventListener('message', async (e) => {
  const result = await WebAssembly.instantiate(e.data, {
    // here we define the print, eprint, and trace
    // functions as specified in the glue from above
    // they just send stdout back using the send function
    env: {
      print(ptr){
        send(ptr);
      },
      eprint(ptr) {
        send(ptr);
      },
      trace(ptr) {
        send(ptr);
      }
    }
  });

  memory = result.instance.exports.memory;

  // run the main() function of the WASM code 
  await result.instance.exports.main();

  // let the editor know we've sent all the output and have
  // finished
  postMessage({
    done: true
  });
}, false);

Thanks For Reading!

Follow us on Twitter @q_vault if you have any questions or comments

Take some coding courses on our new platform

Subscribe to our Newsletter for more programming articles



source https://qvault.io/2020/10/12/running-rust-in-the-browser-with-web-assembly/

Comments

Post a Comment

Popular posts from this blog

Why is Exclusive Or (XOR) Important in Cryptography?

Image
If you are getting into cryptography, or just trying to understand the fundamentals, you may have noticed that the exclusive-or operation is used quite often, especially in ciphers. What is XOR ( ⊕ )? XOR, or “exclusive or” operates on binary data. It returns true if both of its inputs are opposites (one false and one true), otherwise, it returns false. An example in go code would be something like: func exclusiveOr(a bool, b bool) bool { return a != b } XOR Cipher – The Perfect Cipher The XOR operation can be used as a simple cipher for encrypting and decrypting messages with a single key. This is known as symmetric encryption. It is interesting to note that if: The key is the same size as the message The key is kept secret and generated truly randomly Then the cipher is impossible to crack. This is known as a one time pad . However, a simple XOR shouldn’t be used in production due to the key length needing to be too long to be practical. Cipher Example A...
Read more

Base64 vs Base58 Encoding

Image
By Lane Wagner –  @wagslane  on Twitter Base64 is one of the most popular encoding formats for representing data. Have some binary data? Base64 encode it for convenient readability and parsing. Base58 is just another encoding format (with 58 characters instead of 64, and has gained popularity largely due to Bitcoin and other cryptocurrencies. When it comes to data encoding, there is typically a trade-off made between: Human Readability: Do humans have a good idea of what is being represented at a glance? Efficient data compression: How many bytes are used to represent the same data? Let’s rank Base58, Base64, and ASCII encoding against each other using these metrics! First: A Note on Binary All data is stored in a raw binary format on computers. These encoding formats (Base64, Base58, and ASCII) are just different ways of reading and writing binary data. For example, in Base64 the binary code 000000 represents the letter A , but in ASCII the binary 00000000 repres...
Read more

(Very) Basic Intro to Hash Functions (SHA-256, MD-5, etc)

Image
This is going to be a basic introduction to hash functions. I will assume most of my audience is here to gain an understanding of why hash functions are used and the basic idea of why they work. My goal is to explain it in a general sense, I will be omitting proofs and implementation details and instead focusing on the high-level principles. Why Use A Hash Function? Hash functions are used all over the internet in order to securely store passwords, find duplicate records, quickly store and retrieve data, and more. For example,  Qvault  uses hashes to extend master passwords into private encryption keys. A longer list of uses here:  https://en.wikipedia.org/wiki/Hash_function#Uses I want to focus on several important features of hash functions, arguably the most important features. Hash functions scramble data deterministically No matter the input, the output of a hash function always has the same size The original data can not be retrieved from the scrambled d...
Read more