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

Free lesson

WIT interfaces and WebAssembly components

After this lesson: I can read a WIT world and say what a component imports and exports.

65 min lesson3 commandsWebAssembly lab: Wasmtime, WASI capabilities, WIT components and plugin limits

Programs that agree on types, not languages

A WebAssembly component is a module wrapped with a typed description of what it imports and exports, written in WIT, the WebAssembly Interface Type language. With it, a component written in Rust can hand a string or a list to one written in Python.

Today you read a WIT file and call a component through it.

By the end of this lesson

Note

I can read a WIT world and say what a component imports and exports.

Key words

WordWhat it meansExample
Componenta module plus typed imports and exports
WITthe language that describes those typescalc.wit
Interfacea named group of functions and typesmath
Worldeverything one component imports and exports
Packagethe name and version of a set of interfacesdemo:[email protected]
Liftto turn a core function into a typed one

The cells students fill in are left blank in this preview.

A core module only speaks in numbers

A plain module, a core module, passes four kinds of value: i32, i64, f32 and f64. A string has to travel as a place in memory and a length, and both sides must agree how.

The Component Model fixes that agreement once, in the canonical ABI. WIT says string, list or record, and the runtime moves the bytes. Two components never share memory.

Read the lab's WIT file

Command
docker exec tools cat calc.wit

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

Worked example: the parts of calc.wit

LineKindWhat it says
package demo:[email protected];packageNamespace demo, name calc, version 0.1.0
interface math { ... }interfaceOne function, add: func(a: u32, b: u32) -> u32
world calculator { export math; }worldA component that gives math
world doubler { import math; export double: ... }worldNeeds math, gives double

The cells students fill in are left blank in this preview.

A component is a module plus its types

Open calc.wat with docker exec tools cat calc.wat. Inside is an ordinary core module whose add takes two i32 and returns one.

A canon lift line turns that into add: func(a: u32, b: u32) -> u32, the type WIT promised. The component exports it inside the instance demo:calc/[email protected]. Wasmtime can call it by name with --invoke.

Call the component's add

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.

Add two numbers that are too big

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

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

A world is a contract with the host

A world lists what a component needs and what it gives. The host must supply every import before the component can start, so the world is the whole of what it may touch.

WASI is written as WIT worlds too. A command-line component imports interfaces such as wasi:filesystem and wasi:cli/environment, and exports wasi:cli/run. A host can read that list before it runs anything.

A common mistake

Warning

Many people think a WIT file is code that runs. WIT only describes types and functions, like a contract. The code is in the component, and the same WIT can be met by components written in any language.

Try it: why 4.5 billion became 205032704

Code: python
MASK = 2 ** 32

def add_u32(a, b):
    # A core i32.add keeps only the low 32 bits of the sum.
    return (a + b) % MASK

def as_signed(n):
    # The same 32 bits, read as a signed number.
    if n >= 2 ** 31:
        return n - MASK
    return n

for pair in [[2, 3], [4000000000, 500000000], [3000000000, 0]]:
    total = add_u32(pair[0], pair[1])
    print(pair[0], "+", pair[1], "=", total, "as u32 and", as_signed(total), "as s32")
# Add [4294967295, 1] to the list. What does it wrap to?

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

Teaching a class? Set this module for your students with a teacher guide, marked assignments and a lab for every student.