FAAS in Go together with WASM, WASI and Rust

Design

Let’s begin with a high-level diagram describing how the system works:

The steps numbered within the diagram are:

1. The FAAS server receives an HTTP GET request, with a path consisting of
   a module title (func within the instance within the diagram) and an arbitrary
   question string.
2. The FAAS server finds and hundreds the WASM module similar to the module
   title it was offered, and invokes it with an outline of the HTTP request.
3. The module emits output to its stdout, which is captured by the FAAS server.
4. The FAAS server makes use of the module’s stdout because the contents of an HTTP Response
   to the request it acquired.

The FAAS server

We’ll begin our deep dive with the FAAS server itself (full code here). The
HTTP dealing with half is simple:

func httpHandler(w http.ResponseWriter, req *http.Request) {
  elements := strings.Break up(strings.Trim(req.URL.Path, "/"), "/")
  if len(elements) < 1 {
    http.Error(w, "need /{modulename} prefix", http.StatusBadRequest)
    return
  }
  mod := elements[0]
  log.Printf("module %v requested with question %v", mod, req.URL.Question())

  env := map[string]string{
    "http_path":   req.URL.Path,
    "http_method": req.Methodology,
    "http_host":   req.Host,
    "http_query":  req.URL.Question().Encode(),
    "remote_addr": req.RemoteAddr,
  }

  modpath := fmt.Sprintf("goal/%v.wasm", mod)
  log.Printf("loading module %v", modpath)
  out, err := invokeWasmModule(mod, modpath, env)
  if err != nil {
    log.Printf("error loading module %v", modpath)
    http.Error(w, "unable to search out module "+modpath, http.StatusNotFound)
    return
  }

  // The module's stdout is written into the response.
  fmt.Fprint(w, out)
}

func important() {
  mux := http.NewServeMux()
  mux.HandleFunc("/", httpHandler)
  log.Deadly(http.ListenAndServe(":8080", mux))
}

This server listens on port 8080 (be at liberty to vary this or make it
extra configurable), and registers a catch-all handler for the foundation path. The
handler parses the precise request URL to search out the module title. It then shops
some info to go to the loaded module within the env map.

The loaded module is discovered with a filesystem lookup within the goal listing
relative to the FAAS server binary. All of that is only for demonstration
functions and might be simply modified, after all. The handler then calls
invokeWasmModule, which we’ll get to shortly. This operate returns the
invoked module’s stdout, which the handler prints out into the HTTP response.

Working WASM code in Go

Given a WASM module, how can we run it programmatically in Go? There are a number of
high-quality WASM runtimes that work exterior the browser surroundings, and lots of
of them have Go bindings; for instance wasmtime-go. The one I like most,
nonetheless, is wazero; it is a
zero-dependency, pure Go runtime that does not have any stipulations besides
working a go get. Our FAAS server is utilizing wazero to load and run
WASM modules.

This is invokeWasmModule:

// invokeWasmModule invokes the given WASM module (given as a file path),
// setting its env vars in line with env. Returns the module's stdout.
func invokeWasmModule(modname string, wasmPath string, env map[string]string) (string, error) {
  ctx := context.Background()

  r := wazero.NewRuntime(ctx)
  defer r.Shut(ctx)
  wasi_snapshot_preview1.MustInstantiate(ctx, r)

  // Instantiate the wasm runtime, organising exported features from the host
  // that the wasm module can use for logging functions.
  _, err := r.NewHostModuleBuilder("env").
    NewFunctionBuilder().
    WithFunc(func(v uint32) {
      log.Printf("[%v]: %v", modname, v)
    }).
    Export("log_i32").
    NewFunctionBuilder().
    WithFunc(func(ctx context.Context, mod api.Module, ptr uint32, len uint32) {
      // Learn the string from the module's exported reminiscence.
      if bytes, okay := mod.Reminiscence().Learn(ptr, len); okay {
        log.Printf("[%v]: %v", modname, string(bytes))
      } else {
        log.Printf("[%v]: log_string: unable to learn wasm reminiscence", modname)
      }
    }).
    Export("log_string").
    Instantiate(ctx)
  if err != nil {
    return "", err
  }

  wasmObj, err := os.ReadFile(wasmPath)
  if err != nil {
    return "", err
  }

  // Arrange stdout redirection and env vars for the module.
  var stdoutBuf bytes.Buffer
  config := wazero.NewModuleConfig().WithStdout(&stdoutBuf)

  for okay, v := vary env {
    config = config.WithEnv(okay, v)
  }

  // Instantiate the module. This invokes the _start operate by default.
  _, err = r.InstantiateWithConfig(ctx, wasmObj, config)
  if err != nil {
    return "", err
  }

  return stdoutBuf.String(), nil
}

Attention-grabbing issues to notice about this code:

• wazero helps WASI, which needs to be instantiated explicitly to be usable
  by the loaded modules.
• Numerous the code offers with exporting logging features from the host (the
  Go code of the FAAS server) to the WASM module.
• We arrange the loaded module’s stdout to be redirected to a buffer, and arrange
  its surroundings variables to match the env map handed in.

There are a number of method for host code to work together with WASM modules utilizing solely the
WASI API and ABI. Right here, we go for utilizing surroundings variables for enter and
stdout for output, however there are different choices (see the Different assets
part within the backside for some pointers).

That is it – the entire FAAS server, about 100 LOC of commented Go code. Now
let’s transfer on to see some WASM modules this factor can load and run.

Writing modules in Go

We will compile Go code to WASM that makes use of WASI. This is a fundamental Go program that
emits a greeting and a list of its surroundings variables to stdout:

package deal important

import (
  "fmt"
  "os"
)

func important() {
  fmt.Println("goenv surroundings:")

  for _, e := vary os.Environ() {
    fmt.Println(" ", e)
  }
}

Till just lately, the one solution to compile Go code to WASM that works exterior the
browser was by utilizing the TinyGo compiler. In our
FAAS venture construction, the invocation from the foundation listing is:

$ tinygo construct -o goal/goenv.wasm -target=wasi examples/goenv/goenv.go

Sharp-eyed readers will recall that the goal/ listing is exactly the place
the FAAS server appears for *.wasm recordsdata to load as modules. Now that we have
positioned a module named goenv.wasm there, we’re able to launch our server
with go run . within the root listing. We will concern a HTTP request to its
goenv module in a separate terminal:

$ curl "localhost:8080/goenv?foo=bar&id=1234"
goenv surroundings:
  http_method=GET
  http_host=localhost:8080
  http_query=foo=bar&id=1234
  remote_addr=127.0.0.1:59268
  http_path=/goenv

And searching on the terminal the place the FAAS server runs we’ll see some logging
like:

2023/04/29 06:35:59 module goenv requested with question map[foo:[bar] id:[1234]]
2023/04/29 06:35:59 loading module goal/goenv.wasm

As I’ve talked about earlier than, this was the principle solution to compile to WASI till
just lately. Within the upcoming Go launch (model 1.21), new assist for the WASI
goal is included in the principle Go toolchain (the gc compiler) . It is
simple to strive right this moment both by constructing Go from supply, or utilizing gotip:

$ GOOS=wasip1 GOARCH=wasm gotip construct -o goal/goenv.wasm examples/goenv/goenv.go

(the wasip1 goal title refers to “WASI Preview 1”)

Writing modules in Rust

Rust is one other language that has good assist for WASM and WASI within the construct
system. After including the wasm32-wasi goal with rustup, it is as easy
as passing the goal title to cargo:

$ cargo construct --target wasm32-wasi --release

The code is simple, equally to the Go model:

use std::env;

fn important() {
    println!("rustenv surroundings:");

    for (key, worth) in env::vars() {
        println!("  {key}: {worth}");
    }
}

Writing modules in WebAssembly Textual content (WAT)

As we have seen, compiling Go and Rust code to WASM is pretty simple; searching for a
problem, let’s write a module in WAT! As I’ve written before, I get pleasure from
writing instantly in WAT; it is instructional, and produces remarkably compact
binaries.

The “instructional” side rapidly turns into obvious when desirous about our job.
How precisely am I supposed to write down to stdout or learn surroundings variables utilizing
WASM? That is the place WASI is available in. WASI defines each an API and ABI, each of
which will likely be seen in our pattern. The next reveals some code snippets with
explanations; for the complete code take a look at the sample repository.

First, I need to present how output to stdout is completed; we begin by importing
the fd_write WASI system name:

(import "wasi_snapshot_preview1" "fd_write" (func $fd_write (param i32 i32 i32 i32) (outcome i32)))

Apparently, it has 4 i32 parameters and returns an i32; what do all
of those imply? Sadly, WASI documentation may use lots of work; the
assets I discovered helpful are :

1. Legacy preview 1 specs
2. C header descriptions of these functions

With this in hand, I used to be capable of concoct a helpful println equal in
WAT that makes use of fd_write beneath the hood:

;; println prints a string to stdout utilizing WASI.
;; It takes the string's deal with and size as parameters.
(func $println (param $strptr i32) (param $len i32)
    ;; Print the string pointed to by $strptr first.
    ;;   fd=1
    ;;   information vector with the pointer and size
    (i32.retailer (world.get $datavec_addr) (native.get $strptr))
    (i32.retailer (world.get $datavec_len) (native.get $len))
    (name $fd_write
        (i32.const 1)
        (world.get $datavec_addr)
        (i32.const 1)
        (world.get $fdwrite_ret)
    )
    drop

    ;; Print out a newline.
    (i32.retailer (world.get $datavec_addr) (i32.const 850))
    (i32.retailer (world.get $datavec_len) (i32.const 1))
    (name $fd_write
        (i32.const 1)
        (world.get $datavec_addr)
        (i32.const 1)
        (world.get $fdwrite_ret)
    )
    drop
)

This makes use of some globals that you will have to lookup within the full code sample
for those who’re . This is one other helper operate that prints out a
zero-terminated string to stdout:

;; show_env emits a single env var pair to stdout. envptr factors to it,
;; and it is 0-terminated.
(func $show_env (param $envptr i32)
    (native $i i32)
    (native.set $i (i32.const 0))

    ;; for i = 0; envptr[i] != 0; i++
    (loop $count_loop (block $break_count_loop
        (i32.eqz (i32.load8_u (i32.add (native.get $envptr) (native.get $i))))
        br_if $break_count_loop

        (native.set $i (i32.add (native.get $i) (i32.const 1)))
        br $count_loop
    ))

    (name $println (native.get $envptr) (native.get $i))
)

The enjoyable half about writing meeting is that there aren’t any abstractions.
The whole lot is out within the open. You understand how strings are sometimes represented
utilizing both zero termination (like in C) or a (begin, len) pair?
In guide WAT code that makes use of WASI now we have the pleasure of utilizing each approaches
in the identical program 🙂

Lastly, our important operate:

(func $important (export "_start")
    (native $i i32)
    (native $num_of_envs i32)
    (native $next_env_ptr i32)

    (name $log_string (i32.const 750) (i32.const 19))

    ;; Discover out the variety of env vars.
    (name $environ_sizes_get (world.get $env_count) (world.get $env_len))
    drop

    ;; Get the env vars themselves into reminiscence.
    (name $environ_get (world.get $env_ptrs) (world.get $env_buf))
    drop

    ;; Print out the preamble
    (name $println (i32.const 800) (i32.const 19))

    ;; for i = 0; i != *env_count; i++
    ;;   present env var i
    (native.set $num_of_envs (i32.load (world.get $env_count)))
    (native.set $i (i32.const 0))
    (loop $envvar_loop (block $break_envvar_loop
        (i32.eq (native.get $i) (native.get $num_of_envs))
        (br_if $break_envvar_loop)

        ;; next_env_ptr <- env_ptrs[i*4]
        (native.set
            $next_env_ptr
            (i32.load (i32.add  (world.get $env_ptrs)
                                (i32.mul (native.get $i) (i32.const 4)))))

        ;; print out this env var
        (name $show_env (native.get $next_env_ptr))

        (native.set $i (i32.add (native.get $i) (i32.const 1)))
        (br $envvar_loop)
    ))
)

We will now compile this WAT code right into a FAAS module and re-run the server:

$ wat2wasm examples/watenv.wat -o goal/watenv.wasm
$ go run .

Let’s strive it:

$ curl "localhost:8080/watenv?foo=bar&id=1234"
watenv surroundings:
http_host=localhost:8080
http_query=foo=bar&id=1234
remote_addr=127.0.0.1:43868
http_path=/watenv
http_method=GET

$ wasm-objdump -x goal/goenv.wasm

... snip

Export[2]:
 - func[1028] <_rt0_wasm_wasip1> -> "_start"
 - reminiscence[0] -> "reminiscence"

... snip

WASI and plugins

The FAAS server introduced on this put up is clearly an instance of creating
plugins utilizing WASM and WASI. That is an rising and thrilling space in
programming and many progress is being made on a number of fronts. Proper now,
WASI modules are restricted to interacting with the surroundings by way of means like
surroundings variables and stdin/stdout; whereas that is superb for interacting
with the skin world, for host-to-module communication it isn’t wonderful, in
my expertise. Due to this fact the WASM requirements committee is working of additional
enhancements to WASI which will embrace sockets and different technique of passing information
between hosts and modules.

Within the meantime, initiatives are making do with what they’ve. For instance, the
sqlc Go package helps WASM plugins. The communication
with plugins occurs as follows: the host encodes a command right into a protobuf
and emits it to the plugin’s stdin; it then reads the plugin’s stdout for a
protobuf-encoded response.

Different initiatives are taking extra maverick approaches; for instance, the Envoy
proxy helps WASM plugins by defining a customized
API and ABI between the host and WASM modules. I will most likely write extra about
this in a later put up.

Different assets

Listed here are some further assets on the identical subject as this put up: