Run Wasm Outside the Browser Using WASI

Topic Overview

WASI: Wasm Outside the Browser

WASI (WebAssembly System Interface) gives Wasm modules portable syscalls: files, clocks, randomness, without baking in a JavaScript host. Runtimes like Wasmtime and Wasmer implement WASI on Linux, macOS, and Windows.

Capability-Based I/O

Instead of implicit full filesystem access, WASI uses capability handles passed at instantiation:

• \`fd_write\` to stdout via preopened descriptor 1
• \`fd_read\` for input
• \`clock_time_get\` for monotonic time

Compile with \`clang --target=wasm32-wasi\`, link with \`wasm-ld\`, run with \`wasmtime run hello.wasm\`.

For example, \`printf("hello\\n")\` lowers to WASI \`fd_write\` on the stdout capability the runtime injects at startup.

This is how Figma-scale C/C++ codebases run server-side without a browser embedding.

Design Notes

Preopened directories are capabilities, not global filesystem access. A module cannot open `/etc/passwd` unless the runtime explicitly grants that path at instantiation time.

For This Exercise

This exercise asks you to document running a Wasm module under WASI. You will explain the compile flags, runtime command, and how capabilities replace browser JS imports for I/O.

You will use the same mental model here when reading production interpreter source later in the track. Sketch one concrete input on paper, predict the outcome, then confirm with code. That discipline catches logic errors early and makes debugging far faster when you extend the implementation in follow-on tasks.

Your Task

Implement a small WASI host: the runtime side of wasi_snapshot_preview1 that a Wasm module calls through imports. The guest passes only integers, and all data lives in its linear memory. For example, fd_write receives a pointer to an array of iovecs ({u32 buf, u32 len}, little-endian) and writes the byte count back to a result pointer. Files are reachable only through preopened directories: WASI is capability-based, so a path is always resolved relative to a directory fd and may never escape it. Every call returns a WASI errno.

Input

;; starts a comment. Text arguments are double-quoted, with \\n, \\t and \\" escapes.

Host setup and inspection (no guest call):

cCopy
Loading…

Guest calls:

cCopy
Loading…

Rules

• Standard fds: fd 0 is stdin (read right only), and fds 1 and 2 are stdout/stderr (write right only). Preopened dirs have no read/write rights.
• fd_write/fd_read:
  • errors: badf for a closed or unknown fd, isdir for a directory, notcapable without the right, fault if an iovec or buffer lies outside memory;
  • otherwise process the iovecs in order and store the total count at the result pointer;
  • writing to stdout/stderr prints stdout <- "…" (or stderr) per iovec, escaped (\\n, \\", \\\\, and \\xNN for other non-printables);
  • files are read and written at the fd's own offset, which starts at 0.
• path_open, checked in this order:
  1. inval for unknown flags or neither read nor write;
  2. badf for a bad dirfd, notdir if it is not a directory;
  3. notcapable for an absolute path, or a .. that would climb above the directory. . and .. are resolved textually;
  4. isdir if the path names the directory itself;
  5. noent if the file is missing and create isn't given;
  6. otherwise create/truncate as asked, take the lowest free fd ≥ 3, store it at FD_PTR (fault if outside memory), and print opened HOSTPATH as fd N.
• fd_close of a closed or unknown fd gives badf.
• proc_exit prints proc_exit(C): module exited with code C. Any later guest call prints CALL: the module has exited.
• Errno values: success 0, badf 8, exist 20, fault 21, inval 28, isdir 31, noent 44, notdir 54, notcapable 76.

Output

cCopy
Loading…

Each call first echoes itself as shown, then prints its effects, then -> errno N (name).

Errors:

• usage lines for malformed commands: fd_write: FD IOVS IOVS_LEN OUT_PTR, path_open: DIRFD "PATH" read|write|create|trunc[,..] FD_PTR, poke: ADDR "TEXT", peek: ADDR LEN (0-64), …;
• cat: no host file X;
• unknown call X.

Example

Input:

cCopy
Loading…

Output:

cCopy
Loading…

Requirements

1. Read every guest pointer through bounds-checked 32-bit little-endian helpers. A bad pointer must become fault, never a host crash.
2. Resolve paths component by component against the directory's capability. Never pass guest paths to the host file system.

Hidden tests cover reads with two iovecs, rights enforcement, .. escapes and absolute paths, a path that dips into a subdirectory and back, create and trunc, a bad dirfd, a non-directory dirfd, bad flags, a double close, an out-of-bounds iovec, and calls after exit.