Access OS services

The WASI (WebAssembly Systems Interface) standard is designed to allow WebAssembly applications to access operating system services. The wasm32-wasi target in the Rust compiler supports WASI. In this section, we will use an example project to show how to use Rust standard APIs to access operating system services.

Random numbers

The WebAssembly VM is a pure software construct. It does not have a hardware entropy source for random numbers. That’s why WASI defines a function for WebAssembly programs to call its host operating system to get a random seed. As a Rust developer, all you need is to use the popular (de facto standard) rand and/or getrandom crates. With the wasm32-wasi compiler backend, these crates generate the correct WASI calls in the WebAssembly bytecode. The Cargo.toml dependencies are as follows.

[dependencies] rand = "0.7.3" getrandom = "0.1.14"

The Rust code to get random number from WebAssembly is this.

  2. #![allow(unused)]
  3. fn main() {
  4. use rand::prelude::*;
  6. pub fn get_random_i32() -> i32 {
  7.   let x: i32 = random();
  8.   return x;
  9. }
  11. pub fn get_random_bytes() -> Vec<u8> {
  12.   let mut rng = thread_rng();
  13.   let mut arr = [0u8; 128];
  14.   rng.fill(&mut arr[..]);
  15.   return arr.to_vec();
  16. }
  17. }

Printing and debugging from Rust

The Rust println! marco just works in WASI. The statements print to the STDOUT of the process that runs the WasmEdge.

  2. #![allow(unused)]
  3. fn main() {
  4. pub fn echo(content: &str) -> String {
  5.   println!("Printed from wasi: {}", content);
  6.   return content.to_string();
  7. }
  8. }

Arguments and environment variables

It is possible to pass CLI arguments to and access OS environment variables in a WasmEdge application. They are just env::args() and env::vars() arrays in Rust.

  2. #![allow(unused)]
  3. fn main() {
  4. use std::env;
  6. pub fn print_env() {
  7.   println!("The env vars are as follows.");
  8.   for (key, value) in env::vars() {
  9.     println!("{}: {}", key, value);
  10.   }
  12.   println!("The args are as follows.");
  13.   for argument in env::args() {
  14.     println!("{}", argument);
  15.   }
  16. }
  17. }

Reading and writing files

WASI allows your Rust functions to access the host computer’s file system through the standard Rust std::fs API. In the Rust program, you operate on files through a relative path. The relative path’s root is specified when you start the WasmEdge runtime.

  2. #![allow(unused)]
  3. fn main() {
  4. use std::fs;
  5. use std::fs::File;
  6. use std::io::{Write, Read};
  8. pub fn create_file(path: &str, content: &str) {
  9.   let mut output = File::create(path).unwrap();
  10.   output.write_all(content.as_bytes()).unwrap();
  11. }
  13. pub fn read_file(path: &str) -> String {
  14.   let mut f = File::open(path).unwrap();
  15.   let mut s = String::new();
  16.   match f.read_to_string(&mut s) {
  17.     Ok(_) => s,
  18.     Err(e) => e.to_string(),
  19.   }
  20. }
  22. pub fn del_file(path: &str) {
  23.   fs::remove_file(path).expect("Unable to delete");
  24. }
  25. }

A main() app

With a main() function, the Rust program can be compiled into a standalone WebAssembly program.

  1. fn main() {
  2.   println!("Random number: {}", get_random_i32());
  3.   println!("Random bytes: {:?}", get_random_bytes());
  4.   println!("{}", echo("This is from a main function"));
  5.   print_env();
  6.   create_file("tmp.txt", "This is in a file");
  7.   println!("File content is {}", read_file("tmp.txt"));
  8.   del_file("tmp.txt");
  9. }

Use the command below to compile the Rust project.

cargo build --target wasm32-wasi

To run it in wasmedge, do the following. The --dir option maps the current directory of the command shell to the file system current directory inside the WebAssembly app.

$ wasmedge --dir .:. target/wasm32-wasi/debug/wasi.wasm hello Random number: -68634548 Random bytes: [87, 117, 194, 122, 74, 189, 29, 1, 113, 26, 90, 6, 151, 20, 11, 169, 131, 212, 161, 220, 216, 190, 77, 234, 30, 10, 159, 7, 14, 89, 81, 111, 247, 136, 39, 195, 83, 90, 153, 225, 66, 16, 150, 217, 137, 172, 216, 203, 251, 37, 4, 27, 32, 57, 76, 237, 99, 147, 24, 175, 208, 157, 3, 220, 46, 224, 199, 153, 144, 96, 120, 89, 160, 38, 171, 239, 87, 218, 41, 184, 220, 78, 157, 57, 229, 198, 222, 72, 219, 118, 237, 27, 229, 28, 51, 116, 88, 101, 40, 139, 160, 51, 156, 102, 66, 233, 101, 50, 131, 9, 253, 186, 73, 148, 85, 36, 155, 254, 168, 202, 23, 96, 181, 99, 120, 136, 28, 147] This is from a main function The env vars are as follows. ... ... The args are as follows. target/wasm32-wasi/debug/wasi.wasm hello File content is This is in a file

Functions

As we have seen, you can create WebAssembly functions in a Rust lib.rs project. You can also use WASI functions in those functions. However, an important caveat is that, without a main() function, you will need to explicitly call a helper function to initialize environment for WASI functions to work properly. In the Rust program, add a helper crate in Cargo.toml so that the WASI initialization code can be applied to your exported public library functions.

[dependencies] ... ... wasmedge-wasi-helper = "=0.2.0"

In the Rust function, we need to call _initialize() before we access any arguments and environment variables or operate any files.

  2. #![allow(unused)]
  3. fn main() {
  4. pub fn print_env() -> i32 {
  5.   _initialize();
  6.   ... ...
  7. }
  9. pub fn create_file(path: &str, content: &str) -> String {
  10.   _initialize();
  11.   ... ...
  12. }
  14. pub fn read_file(path: &str) -> String {
  15.   _initialize();
  16.   ... ...
  17. }
  19. pub fn del_file(path: &str) -> String {
  20.   _initialize();
  21.   ... ...
  22. }
  23. }