Markdown Parser

The following steps describe an implementation of a WASI markdown parser, in Rust, using pulldown-cmark.

First, we will generate a new executable with cargo:

cargo new --bin rust_wasi_markdown_parser
cd rust_wasi_markdown_parser

Also, we need to add the structopt and pulldown_cmark crates to our project:

cargo add structopt pulldown_cmark

Then, we will open the src/main.rs and enter the following contents. Please see the comments to understand what our program will be doing.

src/main.rs

// Import our CLI parsing libraries (And PathBuf for reading paths)
extern crate structopt;

use structopt::StructOpt;
use std::path::PathBuf;

// Import our markdown parser library, crate
extern crate pulldown_cmark;

use pulldown_cmark::{html, Parser};

// Import from the standard library, to allow reading from the file system
use std::fs;

// Define our CLI options using structopt
#[derive(StructOpt)]
#[structopt(name = "rust_wasi_markdown_parser", about = "Markdown to HTML renderer CLI, written with Rust & WASI")]
pub struct Options {
    /// The markdown file to render
    #[structopt(parse(from_os_str))]
    filename: PathBuf,
}

// Our entrypoint into our WASI module
fn main() {

    // Get the passed CLI options
    let options = Options::from_args();

    // Read the markdown file into a string
    let contents = fs::read_to_string(options.filename)
        .expect("Something went wrong reading the file");

    // Run our parsing function to get back an HTML string
    let result = render_markdown(contents);

    // Print out the resulting HTML to standard out
    println!("{}", result);
}

pub fn render_markdown(markdown: String) -> String {
    let mut html_buf = String::new();
    let parser = Parser::new(&markdown[..]);
    html::push_html(&mut html_buf, parser);
    html_buf
}

Next, we will want to add WASI as a target that we can compile to. We will ask the rustup tool to install support for WASI. Then, we will compile our program to WASI. To do this we will run:

rustup target add wasm32-wasi
cargo build --target wasm32-wasi

Our wasm file should be compiled to target/wasm32-wasi/debug/rust_wasi_markdown_parser.wasm. It is worth noting that even though the WASI APIs are not being used directly, when we compile our program to target WASI, the rust APIs and standard library will be using these WASI APIs under the hood for us! Now that we have our program compiled to target WASI, let's run our program!

To do this, we can use the Wasmtime CLI. However, there is one thing to note about Wasmtime, WASI, and the capability based security model. We need to give our program explicit access to read files on our device. Wasm modules that implement WASI will not have this capability unless we give them the capability.

To grant the capability to read in a directory using the Wasmtime CLI, we need to use the --dir flag. --dir will instruct wasmtime to make the passed directory available to access files from. (You can also --mapdir GUEST_DIRECTORY::HOST_DIRECTORY to make it available under a different path inside the content.) For example:

wasmtime --dir . my-wasi-program.wasm

For this example, we will be passing a markdown file to our program called: example_markdown.md, that will exist in whatever our current directory (./) is. Our markdown file, example_markdown.md, will contain:

# Hello!

I am example markdown for this demo!

So, to run our compiled WASI program, we will run:

wasmtime --dir . target/wasm32-wasi/debug/rust_wasi_markdown_parser.wasm -- ./example_markdown.md

Which should look like the following:

<h1>Hello!</h1>
<p>I am example markdown for this demo!</p>

Hooray! We were able to write a Wasm Module, that uses WASI to read a markdown file, parse the markdown, and write the output to stdout! Continue reading to see more examples of using Wasmtime to execute Wasm Modules, from the CLI or even embedded in your application!