Service: WASM Runner - EyevinnOSC/community GitHub Wiki

WASM Runner

WASM Runner (serviceId eyevinn-wasm-runner) runs a WebAssembly (WASM) application as a serverless application. It downloads the WASM file and executes it in Docker with the wasmtime runtime. In Eyevinn Open Source Cloud (OSC) it is a long-running service instance under the MIT license. Source: Eyevinn/wasm-runner.

What it can do

  • Run a WASM application compiled for the wasm32-wasip1 target that follows WASI conventions with a _start entry point.
  • Load the WASM file from a URL (WasmUrl, for example a file in a MinIO bucket) or from a GitHub repository containing a .wasm file (GithubUrl).
  • Answer HTTP requests with the output of the application; the body of a POST is delivered on STDIN and what the application writes to STDOUT is returned.
  • Let the application interact with other OSC services (OscAccessToken) and read its configuration from an Application Config Service instance (ConfigService).

Creating an instance

Compile your application and make the .wasm file downloadable, for example by uploading it to a bucket on a MinIO instance (serviceId minio-minio). Then call create-service-instance with serviceId: "eyevinn-wasm-runner":

{
  "name": "guide",
  "WasmUrl": "https://<minio-endpoint>/code/main.wasm"
}

To run a GitHub repository instead, set GithubUrl (for example https://github.com/<org>/<repo>/, with a branch as https://github.com/<org>/<repo>#<branch>) and, for a private repository, GithubToken as {{secrets.NAME}}.

Wait for the instance to be running (wait-for-service-ready) and use describe-service-instance to get the URL.

CLI equivalent:

npx -y @osaas/cli create eyevinn-wasm-runner ghdemo -o WasmUrl=https://<minio-endpoint>/artifacts/main.wasm

Options

Option Required Type Meaning
name Yes string Name of the instance. Alphanumeric, at most 20 characters.
WasmUrl No string URL of your WASM code, for example https://<minio-endpoint>/code/main.wasm. The file should be compiled for wasm32-wasip1 and have a _start entry point.
GithubUrl No string GitHub repository URL containing a .wasm file, in the form https://github.com/<org>/<repo>/. The runner clones the repository and executes the first .wasm file it finds. A branch can be given as a fragment: https://github.com/<org>/<repo>#<branch>. Sets GITHUB_URL.
GithubToken No string, sensitive GitHub personal access token, only needed when the repository in GithubUrl is private.
OscAccessToken No string, sensitive OSC personal access token, needed if the code you run interacts with other OSC services. Create one on the API Access page (see Finding Your API Token).
ConfigService No string Name of your Application Config Service instance, used to provide configuration to the application instead of local environment variables. Works the same way as when you configure a Web Runner instance.

Sensitive options (GithubToken, OscAccessToken) should be service secrets passed as {{secrets.NAME}} as the whole field value. Changing a secret later does not restart a running instance.

Using the instance

Hello world

Create main.rs:

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

Compile it to WASM, upload main.wasm to a bucket and create a runner with its URL:

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

Then call the instance URL:

% curl https://<tenant>-guide.eyevinn-wasm-runner.auto.prod-se.osaas.io
Hello, world!

Echo application

This example sends data to the WASM application. It echoes STDIN to STDOUT. Create echo.rs:

use std::io::{self, BufRead, BufReader};

fn main() {
  let stdin = io::stdin();
  let reader = BufReader::new(stdin.lock());

  for line in reader.lines() {
    match line {
      Ok(content) => println!("{}", content),
      Err(e) => eprintln!("Error reading input: {}", e),
    }
  }
}

Compile it with rustc echo.rs --target wasm32-wasip1, upload it and create a runner with its URL. What you POST in the body is received on STDIN and the output is returned:

% curl -X POST -H 'Content-Type: text/plain' -d 'Hello' https://<tenant>-echo.eyevinn-wasm-runner.auto.prod-se.osaas.io
Hello

Continuous integration (CI) workflow

You can create a continuous integration (CI) workflow to build and deploy your application as a serverless WASM runner with GitHub workflows and Open Source Cloud.

As an example we will create a GitHub workflow for this sample application that will build and deploy when code is pushed to main branch.

name: Deploy on push to main
on:
  push:
    branches:
      - main

Then we add a job for building and deploying the WASM code. First we checkout the code, install the WebAssembly target and compile the code to WASM.

jobs:
  deploy:
    runs-on: ubuntu-latest
    permissions:
      contents: write
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
      - name: Install target for WebAssembly
        run: rustup target add wasm32-wasip1
      - name: Build WebAssembly
        run: rustc main.rs --target wasm32-wasip1

Then upload the WASM code to a bucket.

      - name: Upload WebAssembly artifact to bucket
        run: |
          aws s3 cp --endpoint-url https://eyevinnlab-birme.minio-minio.auto.prod-se.osaas.io main.wasm s3://artifacts/main.wasm
        env:
          AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
          AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}

And final step is to deploy the code to a WASM Runner. An existing WASM Runner instance cannot be updated with a new WASM file, so the workflow first removes the existing instance and creates a new one, using the OSC command line tool.

      - name: Deploy as WASM runner in Open Source Cloud
        run: |
          npx -y @osaas/cli remove eyevinn-wasm-runner ghdemo -y || true
          npx -y @osaas/cli create eyevinn-wasm-runner ghdemo -o WasmUrl=https://artifacts.osaas.io/artifacts/main.wasm
        env:
          OSC_ACCESS_TOKEN: ${{ secrets.OSC_ACCESS_TOKEN }}

AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY and OSC_ACCESS_TOKEN are stored as secrets in the GitHub repository.

Full example is available in this GitHub repository.

Limitations

  • An existing WASM Runner instance is not updated with a new WASM file; remove it and create a new one (as in the CI workflow above).

Resources

⚠️ **GitHub.com Fallback** ⚠️