WASI & components

 host (wasmtime, node, ...)                guest.wasm
 ──────────────────────────                ──────────
 --dir ./data::/data   ── preopen fd 3 ──►  open("/data/x")   ok
                                            open("/etc/passwd") ENOTCAPABLE
 --env KEY=v           ── environ ──────►  getenv("KEY")
 (no -S inherit-network)                   connect(...)       denied
 stdin / stdout / stderr inherited         printf(...)        ok
 wall clock, random                        time(), rand()     ok

curl https://wasmtime.dev/install.sh -sSf | bash
wasmtime --version
 
wasmtime run app.wasm arg1 arg2        # "run" is default
wasmtime --dir ./data::/data app.wasm  # preopen
wasmtime --env API=x --env HOME app.wasm
wasmtime run --invoke 'add(1, 2)' comp.wasm
wasmtime serve -S cli --addr 0.0.0.0:8080 http.wasm
wasmtime compile app.wasm -o app.cwasm # AOT

package acme:shapes@0.1.0;
 
interface types {
  record point { x: f32, y: f32 }
 
  variant shape {
    circle(f32),
    rect(tuple<f32, f32>),
    empty,
  }
 
  enum unit { px, mm, inch }
 
  flags style { bold, italic, underline }
 
  type points = list<point>;
}
 
interface geometry {
  use types.{point, shape};
 
  area: func(s: shape) -> f32;
  centroid: func(pts: list<point>) -> option<point>;
  parse: func(src: string) -> result<shape, string>;
 
  resource canvas {
    constructor(width: u32, height: u32);
    draw: func(s: shape);
    pixels: func() -> list<u8>;
    blank: static func() -> canvas;
  }
}
 
world shapes {
  import log: func(msg: string);
  export geometry;
}

 component (shapes.wasm)
 ┌──────────────────────────────────────────────┐
 │  WIT world: import log, export geometry      │
 │   ┌──────────────┐  canon lower   ┌────────┐ │
 │   │ core module  │◄───────────────┤ import │ │
 │   │ (Rust, C...) │  canon lift    ├────────┤ │
 │   │ own memory,  ├───────────────►│ export │ │
 │   │ cabi_realloc │                └────────┘ │
 │   └──────────────┘                           │
 └──────────────────────────────────────────────┘
       ▲ strings, lists, records are copied and
       │ re-encoded at the boundary; no shared memory

cargo install --locked wasm-tools wac-cli wkg
npm i -D @bytecodealliance/jco
pip install componentize-py

# app.wasm imports acme:kv/store; redis.wasm exports it
wac plug app.wasm --plug redis.wasm -o composed.wasm
wasm-tools component wit composed.wasm   # fewer imports
 
# packages and components live in OCI registries
wkg get wasi:http@0.2.1          # a WIT package
wkg fetch                        # deps for ./wit
wkg publish composed.wasm        # configured registry
wkg oci pull ghcr.io/webassembly/wasi/http:0.2.1

use std::{env, fs, io::Write};
 
fn main() -> std::io::Result<()> {
    let path = env::args().nth(1).expect("usage: wc <file>");
    let text = fs::read_to_string(&path)?;
    let words = text.split_whitespace().count();
    let who = env::var("USER").unwrap_or("?".into());
    writeln!(std::io::stdout(), "{who}: {words} words")?;
    Ok(())
}

rustup target add wasm32-wasip1 wasm32-wasip2
cargo build --release --target wasm32-wasip2 # component
cargo build --release --target wasm32-wasip1 # core

W=target/wasm32-wasip2/release/wc.wasm
wasmtime run --dir ./notes::/notes --env USER=ada \
  $W /notes/todo.md
# ada: 42 words
 
wasmtime run $W /etc/passwd   # no preopen for /etc
# Error: Os { ..., kind: NotFound, ... }

package acme:calc@0.1.0;
 
interface ops {
  record stats { min: f64, max: f64, mean: f64 }
  summarize: func(xs: list<f64>) -> result<stats, string>;
}
 
world calc {
  export ops;
}

[lib]
crate-type = ["cdylib"]
 
[dependencies]
wit-bindgen = "0.62"

mod bindings {
    wit_bindgen::generate!({ path: "wit" });
    use super::Calc;
    export!(Calc);
}
use bindings::exports::acme::calc::ops::{Guest, Stats};
 
struct Calc;
 
impl Guest for Calc {
    fn summarize(xs: Vec<f64>) -> Result<Stats, String> {
        if xs.is_empty() {
            return Err("empty input".into());
        }
        let it = xs.iter().copied();
        let min = it.clone().fold(f64::MAX, f64::min);
        let max = it.fold(f64::MIN, f64::max);
        let mean = xs.iter().sum::<f64>() / xs.len() as f64;
        Ok(Stats { min, max, mean })
    }
}

cargo build --release --target wasm32-wasip2
wasm-tools component wit \
  target/wasm32-wasip2/release/calc.wasm
wasmtime run --invoke 'summarize([1.0, 5.0])' \
  target/wasm32-wasip2/release/calc.wasm

npx jco transpile calc.wasm -o src/calc --name calc
# src/calc/calc.js, calc.core.wasm, calc.d.ts,
# interfaces/acme-calc-ops.d.ts

import { ops } from "./calc/calc.js";
 
try {
  const s = ops.summarize(new Float64Array([1, 5, 9]));
  console.log(s.mean); // 5
} catch (e) {
  // result<_, string> error arrives as a thrown
  // ComponentError whose payload is the string
  console.error((e as { payload?: unknown }).payload);
}

import { readFile } from "node:fs/promises";
import { WASI } from "node:wasi";
import { argv, env } from "node:process";
 
const wasi = new WASI({
  version: "preview1",          // required
  args: ["wc", "/notes/todo.md"], // argv[0] first
  env: { USER: env.USER ?? "" },
  preopens: { "/notes": "./notes" }, // guest: host
});
const mod = await WebAssembly.compile(
  await readFile("./wc.wasm"),
);
const inst = await WebAssembly.instantiate(
  mod, wasi.getImportObject(),
);
const code = wasi.start(inst); // exit code
console.log("exit", code, argv.length);

package acme:greet@0.1.0;
 
world greeter {
  export greet: func(name: string) -> string;
}

export function greet(name: string): string {
  return `Hello, ${name}!`;
}

npx jco componentize greeter.ts -w wit -o greeter.wasm
npx jco wit greeter.wasm
wasmtime run --invoke 'greet("Ada")' greeter.wasm