This is a simple tutorial to get started with WASI HTTP using the
wasmtime serve
command in Wasmtime 14.0. It runs an HTTP server and
forwards requests to a Wasm component via the WASI HTTP API.
The WASI HTTP API is settling down but as of this writing not quite stable. This tutorial uses a snapshot of it that's implemented in Wasmtime 14.0.0.
With that said...
First, install cargo component
,
version 0.3.1, which is a tool for building Wasm components implemented in
Rust. (See here for information about building Wasm components from other
languages too!)
With that, build the Wasm component from the source in this repository:
$ cargo component build
Compiling hello-wasi-http v0.0.0 (/home/wasm/hello-wasi-http)
Finished dev [unoptimized + debuginfo] target(s) in 0.17s
Creating component /home/wasm/hello-wasi-http/target/wasm32-wasi/debug/hello_wasi_http.wasm
$
This builds a Wasm component, target/wasm32-wasi/debug/hello_wasi_http.wasm
.
To run it, we'll need at least Wasmtime 14.0.3. Installation instructions are on wasmtime.dev:
$ curl https://wasmtime.dev/install.sh -sSf | bash
Then, in a new terminal, we can run wasmtime serve
on our Wasm component:
$ wasmtime serve target/wasm32-wasi/debug/hello_wasi_http.wasm
This starts up an HTTP server on 0.0.0.0:8080
(the specific address and port
can be configured with the --addr=
flag).
With that running, in another window, we can now make requests!
$ curl http://localhost:8080
Hello, wasi:http/proxy world!
wasmtime serve
uses the proxy world, which is a specialized world just for
accepting requests and producing responses. One interesting thing about the proxy
world is that it doesn't have a filesystem or network API. If you add code to the
example that tries to access files or network sockets, it won't be able to build,
because those APIs are not available in this world. This allows proxy components
to run in many different places, including specialized serverless environments
which may not provide traditional filesystem and network access.
But what if you do want to have it serve some files? One option will be to use WASI-Virt, which is a tool that can bundle a filesystem with a component.
Another option is to use a custom world. The proxy world is meant to be able
to run in many different environments, but if you know your environment and
you know it has a filesystem, you could create your own world, by including
both the "wasi:http/proxy" and "wasi:filesystem/types" or any other APIs you want
the Wasm to be able to access. This would require a custom embedding of Wasmtime,
as it wouldn't run under plain wasmtime serve
, so it's a little more work to
set up.
In the future, we expect to see standard worlds emerge that combine WASI HTTP with many other APIs, such as wasi-cloud-core.
If you're interested in tutorials for any of these options, please reach out and say hi!
Here are my notes on how I created this repository, in case you're intersted in recreating it.
Run cargo-component new --reactor
to create a new project:
$ cargo component new --reactor hello-wasi-http
Created binary (application) `hello-wasi-http` package
Updated manifest of package `hello-wasi-http`
Generated source file `src/main.rs`
$ cd hello-wasi-http
Copy the wit
directory from Wasmtime 14.0.0, to ensure that we're using the
same version of the API that Wasmtime is built with:
https://github.com/bytecodealliance/wasmtime/tree/release-14.0.0
I then manually trimmed the filesystem and sockets dependencies out.
In the future, we'll have wit dependencies stored in a registry, which will make this all much easier.
I derived src/lib.rs
from Wasmtime's
crates/test-programs/src/bin/api_proxy.rs
contents on the main
branch,
adapted it to work with cargo component, in particular by adding:
cargo_component_bindings::generate!();
and renaming the T
type to Component
, which the bindings expect.
Add dependencies:
$ cargo component add --target --path wit/deps/clocks wasi:clocks
$ cargo component add --target --path wit/deps/io wasi:io
$ cargo component add --target --path wit/deps/random wasi:random
$ cargo component add --target --path wit/deps/cli wasi:cli
$ cargo component add --target --path wit/deps/logging wasi:logging
These don't all actually get used in this tutorial, but they're currently needed because of some of the interfaces we copied in from the Wasmtime tree reference them.
TODO: I should also make a api_proxy_streaming.rs version to show streaming.