WAGI: WebAssembly Gateway Interface

WAGI is the easiest way to get started doing cloud-side WebAssembly apps.

WARNING: This is experimental code. It is not considered production-grade by its developers, neither is it "supported" software.

DeisLabs is experimenting with many WASM technologies right now. This is one of a multitude of projects (including Krustlet) designed to test the limits of WebAssembly as a cloud-based runtime.

tl;dr

WAGI allows you to run WebAssembly WASI binaries as HTTP handlers. Write a "command line" application that prints a few headers, and compile it to WASM32-WASI. Add an entry to the modules.toml matching URL to WASM module. That's it.

You can use any programming language that can compile to WASM32-WASI.

Quickstart

Here's the fastest way to try out WAGI. For details, checkout out the documentation.

To run the WAGI server, use cargo run -- --config examples/modules.toml.

This will start WAGI on http://localhost:3000.

Use a browser or a tool like curl to test:

$ curl -v http://localhost:3000/hello/world
*   Trying 127.0.0.1...
* TCP_NODELAY set
* Connected to localhost (127.0.0.1) port 3000 (#0)
> GET /hello/world HTTP/1.1
> Host: localhost:3000
> User-Agent: curl/7.64.1
> Accept: */*
>
< HTTP/1.1 200 OK
< content-type: text/html; charset=UTF-8
< content-length: 12
< date: Wed, 14 Oct 2020 22:00:59 GMT
<
hello world
* Connection #0 to host localhost left intact
* Closing connection 0

To add your own modules, compile your code to wasm32-wasi format and add them to the modules.toml file.

Examples and Demos

env_wagi: Dump the environment that WAGI sets up, including env vars and args.
hello-wagi-grain: An easy-to-read Grain example for WAGI.
hello-wagi-as: AssemblyScript example using environment variables and query params.

If you want to understand the details, read the Common Gateway Interface 1.1 specification. While this is not an exact implementation, it is very close. See the "Differences" section below for the differences.

Contributing

We hang out in the #krustlet channel of the Kubernetes Slack. If WAGI gains popularity, we'll create a dedicated channel (probably on a more fitting Slack server).

WAGI is experimental, and we welcome contributions to improve the project. In fact, we're delighted that you're even reading this section of the docs!

For bug fixes:

Please, pretty please, file issues for anything you find. This is a new project, and we are SURE there are some bugs to work out.
If you want to write some code, feel free to open PRs to fix issues. You may want to drop a comment on the issue to let us know you're working on it (so we don't duplicate effort).

For refactors and tests:

We welcome any changes to improve performance, clean up code, add tests, etc.
For style/idiom guidelines, we follow the same conventions as Krustlet

For features:

If there is already an issue for that feature, please let us know in the comments if you plan on working on it.
If you have a new idea, file an issue describing it, and we will happily discuss it.

Since this is an experimental repository, we might be a little slow to answer.

Code of Conduct

This project has adopted the Microsoft Open Source Code of Conduct.

For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.

thomastaylor312 / wagi