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
| Word | What it means | Example |
|---|---|---|
| Component | a module plus typed imports and exports | |
| WIT | the language that describes those types | calc.wit |
| Interface | a named group of functions and types | math |
| World | everything one component imports and exports | |
| Package | the name and version of a set of interfaces | demo:[email protected] |
| Lift | to 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
docker exec tools cat calc.witShown here, not run. Press Start lab to type it into your own lab’s terminal.
Worked example: the parts of calc.wit
| Line | Kind | What it says |
|---|---|---|
| package demo:[email protected]; | package | Namespace demo, name calc, version 0.1.0 |
| interface math { ... } | interface | One function, add: func(a: u32, b: u32) -> u32 |
| world calculator { export math; } | world | A component that gives math |
| world doubler { import math; export double: ... } | world | Needs 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
docker exec wasm wasmtime run --invoke 'add(2, 3)' calc.watShown here, not run. Press Start lab to type it into your own lab’s terminal.
Add two numbers that are too big
docker exec wasm wasmtime run --invoke 'add(4000000000, 500000000)' calc.watShown 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
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?