wasm-runner

Docker container that downloads a WASM compiled file and running using wasmedge runtime. Available as an open web service in Eyevinn Open Source Cloud.

Supported WASM modules

The runner starts wasmedge once per HTTP request, so the module must be a core WebAssembly module built for WASI preview 1 that exports _start. Rust (wasm32-wasip1), TinyGo (-target wasm32-wasip1) and C/C++ with a WASI SDK all produce such a module.

Not supported are Spin (Fermyon) applications and any module that exports wasi:http/incoming-handler, WebAssembly components (Component Model, WASI preview 2), and in-container build steps. Spin is built on Wasmtime and has a different entry point, so a Spin build does not run here.

The runner does not turn a failed start into an error status. It always answers 200 with whatever the module wrote to stdout.

For several HTTP routes, use a Node.js, Python or Go My App instead.

Usage

Build container image:

% docker build -t wasm-runner:local .

Create a sample application (example in Rust)

fn main() {
  println!("Hello, world!");
}

Compile to wasm:

% rustup target add wasm32-wasip1
% rustc main.rs --target wasm32-wasip1

Upload main.wasm to a bucket for download and then run the container providing the URL to the WASM file:

% docker run --rm \
  -p 8080:8080 \
  -e WASM_URL=https://eyevinnlab-birme.minio-minio.auto.prod.osaas.io/code/main.wasm \
  wasm-runner:local

Alternatively, provide a GitHub repository URL containing a .wasm file:

% docker run --rm \
  -p 8080:8080 \
  -e GITHUB_URL=https://github.com/<org>/<repo>/ \
  wasm-runner:local

For private repositories, provide a GitHub personal access token:

% docker run --rm \
  -p 8080:8080 \
  -e GITHUB_URL=https://github.com/<org>/<repo>/ \
  -e GITHUB_TOKEN=<token> \
  wasm-runner:local

You can specify a branch using a URL fragment:

% docker run --rm \
  -p 8080:8080 \
  -e GITHUB_URL=https://github.com/<org>/<repo>#<branch> \
  wasm-runner:local

The entrypoint will clone the repository, find the first .wasm file, and run it. The WASM module is expected to follow the WASI convention and export a _start entry point (the default for wasmedge).

The WASM application main.wasm can now be invoked through the HTTP server on port 8080. Provides these endpoints:

Method	Path	Description
GET	/	Invoke the application and return what the application writes to STDOUT
POST	/	Invoke the application and the request body is provided to the application on STDIN. Return STDOUT output

% curl http://localhost:8080/
Hello, world!

Binary and non-text responses

By default the runner returns STDOUT as text with Content-Type: text/plain; charset=utf-8. A module that needs to return raw bytes with its own content type (for example an image) can opt in by starting STDOUT with a header block:

OSC-HTTP-Response: 1
Content-Type: image/png

<raw bytes>

• The first line must be exactly OSC-HTTP-Response: 1, followed by a newline (\n or \r\n). Output that does not start with it is returned as before.
• Content-Type is required and may appear once. No other header is supported.
• An empty line ends the header block. Everything after it is sent unmodified as the response body, with status 200.
• If the block is malformed, the runner answers 500 with a text/plain message starting Invalid OSC-HTTP-Response header block: and the reason. The header block must end within the first 8192 bytes.

Example in Rust, using only the standard library:

use std::io::Write;
fn main() {
    let png: &[u8] = include_bytes!("logo.png");
    let mut out = std::io::stdout().lock();
    out.write_all(b"OSC-HTTP-Response: 1\nContent-Type: image/png\n\n").unwrap();
    out.write_all(png).unwrap();
    out.flush().unwrap();
}

% curl -s http://localhost:8080/ -o out.png

Environment Variables

Variable	Required	Description
WASM_URL	Yes*	URL to a .wasm file to download and run. Mutually exclusive with GITHUB_URL / GIT_URL.
GITHUB_URL	Yes*	URL to a GitHub repository containing a .wasm file. Mutually exclusive with WASM_URL. Alias for GIT_URL.
GIT_URL	Yes*	URL to a Git repository containing a .wasm file. Supports a branch suffix (#<branch>). Mutually exclusive with WASM_URL.
GITHUB_TOKEN	No	Personal access token for cloning private GitHub repositories. Alias for GIT_TOKEN.
GIT_TOKEN	No	Personal access token for cloning private Git repositories.
CONFIG_SVC	No	Hostname of the OSC parameter store service. When set alongside OSC_ACCESS_TOKEN, environment variables are loaded from the config service before the WASM module starts.
OSC_ACCESS_TOKEN	No	OSC service access token. Required for config service integration (CONFIG_SVC).
OSC_REFRESH_TOKEN	No	Set by the runner from the original OSC_ACCESS_TOKEN before the token exchange.
CONFIG_API_KEY	No	API key for encrypted parameter store. When set alongside OSC_ACCESS_TOKEN and CONFIG_SVC, secret parameters are decrypted before being injected as environment variables.

* Exactly one of WASM_URL, GITHUB_URL, or GIT_URL must be provided.

Contributing

See CONTRIBUTING

License

This project is licensed under the MIT License, see LICENSE.

Support

Join our community on Slack where you can post any questions regarding any of our open source projects. Eyevinn's consulting business can also offer you:

• Further development of this component
• Customization and integration of this component into your platform
• Support and maintenance agreement

Contact sales@eyevinn.se if you are interested.

About Eyevinn Technology

Eyevinn Technology is an independent consultant firm specialized in video and streaming. Independent in a way that we are not commercially tied to any platform or technology vendor. As our way to innovate and push the industry forward we develop proof-of-concepts and tools. The things we learn and the code we write we share with the industry in blogs and by open sourcing the code we have written.

Want to know more about Eyevinn and how it is to work here. Contact us at work@eyevinn.se!