Easier to read with cream paper, a tint, more contrast or larger text? Choose your colours and text, once, for every page.

Free lesson

WebAssembly Basics

The whole lesson is free and interactive. Read it here, or press Start lab to run it for real in a live lab, with no account needed.

Container lab10 min read7 commands

A program that can only touch what you give it

WebAssembly is a small binary format for programs that runs on any machine with a runtime. Outside the browser it runs plugins and tools in a sandbox: the program can reach no file, setting or network unless the runtime is told to hand it over. This lab runs Wasmtime, the runtime from the Bytecode Alliance.

By the end of this lesson

Note

I can run a WebAssembly program with Wasmtime and grant it only what it needs.

Key words

  • WebAssembly: a portable binary format for programs.
  • Runtime: the program that runs WebAssembly, here Wasmtime.
  • WASI: the standard way a WebAssembly program asks for files and settings.
  • Capability: one thing a program has been given, such as a folder.
  • Component: a WebAssembly program with typed imports and exports.
  • Fuel: a budget of work that stops a program when it runs out.

Starter: what you already know

Note

Answer in your head. 1. Can a program built for a laptop run unchanged on a phone? 2. What is a folder permission for? 3. Why would you not run a program from a stranger on your own computer? Answers: usually not, it was built for one kind of processor; to say who may read or change files; it could read or delete your files.

Before you start

Note

Press Start the lab on the bar at the top of this lesson and wait until it says it is running. There are two services. wasm runs Wasmtime and has no shell, so each Run is docker exec wasm wasmtime .... tools has Python and a shell, and both see the same folder. Each Run button below types its command into your lab's terminal, one after another in the same session. To watch them, or to type your own, press Open terminal on the bar.

Run a first program

hello.wat is a WebAssembly program written in the text format, which Wasmtime reads directly. It asks WASI for one thing, a way to write text, and prints Hello from WebAssembly.

Command
docker exec wasm wasmtime run hello.wat

Shown here, not run. Press Start lab to type it into your own lab’s terminal.

Ask for a file with nothing granted

cat.wat prints a file. Here no folder was granted, so it has nowhere to look and prints cannot open notes.txt: WASI error 8. The file is right there in the data folder, but the program was not given that folder.

Command
docker exec wasm wasmtime run cat.wat notes.txt

Shown here, not run. Press Start lab to type it into your own lab’s terminal.

Grant one folder

The option --dir data hands the program the data folder and nothing else. Now it prints the shopping list: Shopping for Saturday, bread, milk, eggs. A path that climbs out of the folder, such as ../private/key.txt, would still be refused.

Command
docker exec wasm wasmtime run --dir data cat.wat notes.txt

Shown here, not run. Press Start lab to type it into your own lab’s terminal.

Grant one setting

env.wat lists its environment variables. Wasmtime passes none unless told to, so a password in the host's settings stays private. With --env CITY=Leeds it prints CITY=Leeds and nothing more.

Command
docker exec wasm wasmtime run --env CITY=Leeds env.wat

Shown here, not run. Press Start lab to type it into your own lab’s terminal.

Check

Tip

Why did cat.wat fail the first time even though notes.txt exists? Answer: no folder was granted, so the program had no way to reach any file.

Call a component by name

calc.wat is a component: a program with typed functions, described in calc.wit. Wasmtime calls its add with the numbers 2 and 3 and prints 5.

Command
docker exec wasm wasmtime run --invoke 'add(2, 3)' calc.wat

Shown here, not run. Press Start lab to type it into your own lab’s terminal.

Run two components joined into one

doubler.wat needs an add function it does not have. app.wat joins it to calc.wat, so doubler uses calc's add. Asked to double 21, it prints 42. Run on its own, doubler would be refused because nothing gives it add.

Command
docker exec wasm wasmtime run --invoke 'double(21)' app.wat

Shown here, not run. Press Start lab to type it into your own lab’s terminal.

Stop a program that never ends

spin.wat loops for ever. Given a budget of 100000 units of fuel, it runs until the budget is spent, and Wasmtime stops it with wasm trap: all fuel consumed by WebAssembly. Wasmtime itself carries on.

Command
docker exec wasm wasmtime run -W fuel=100000 spin.wat

Shown here, not run. Press Start lab to type it into your own lab’s terminal.

A common mistake

Warning

Many people think a WebAssembly program can read anything the person running it can read. It can only use what Wasmtime hands it, such as one folder or one setting. Give it the least it needs, because whatever you do grant, it can use.

Exit check

Tip

Answer without looking back. 1. Which option hands a program a folder? 2. Which environment variables does a program see by default? 3. Why was doubler.wat refused on its own? 4. What stops a program that never ends? Answers: --dir; none; nothing gave it add; a fuel budget or a time limit.

For teachers

Tip

This lesson is a small example of a lesson worked in a lab: the steps and the Run buttons are the lesson, and the lab is each student's own copy. The lab is two services, Wasmtime with no shell and a Python service that writes the files, and nothing here marks itself: the student hands in a short write-up of one experiment with the commands and what Wasmtime printed. Key learning points: 1. A WebAssembly program reaches only what the runtime grants. 2. A component has typed imports and exports, and two can be joined. 3. Fuel or a time limit stops a runaway program. Common mistake: thinking the program can read whatever its user can. Equipment: the lab and a browser. Tip: show the data and private folders side by side before the third Run. Copy it into your own module and change it, or build one from scratch with the Lab menu in the lesson builder.

About this lab and its source: WebAssembly lab: Wasmtime, WASI capabilities, WIT components and plugin limits

Teaching a class? Set these lessons for your students with marking and a lab for every student.