WebAssembly and WASI

// Package platform reports how shelf reaches its host.
package platform

// Name returns a description of the host interface in use.
func Name() string { return name }

package platform

// The _js suffix is a GOOS constraint: only GOOS=js builds this file.
const name = "JavaScript host (syscall/js)"

package platform

// The _wasip1 suffix is a GOOS constraint, too.
const name = "WASI preview 1 host"

//go:build !js && !wasip1

package platform

const name = "native operating system"

//go:build wasm

package platform

// Memory growth is only observable on GOARCH=wasm.
func init() { _ = name }

$ for t in darwin/arm64 js/wasm wasip1/wasm linux/amd64; do printf "%s: " $t; GOOS=${t%/*} GOARCH=${t#*/} go list -f '{{.GoFiles}}' ./platform; done
darwin/arm64: [platform.go platform_other.go]
js/wasm: [platform.go platform_js.go wasm_only.go]
wasip1/wasm: [platform.go platform_wasip1.go wasm_only.go]
linux/amd64: [platform.go platform_other.go]

$ go build ./js
package example.com/shelf/js: build constraints exclude all Go files in .../g6w8/js

$ GOOS=js GOARCH=wasm go run -exec="$(go env GOROOT)/lib/wasm/go_js_wasm_exec" ./hello
hello from js/wasm
$ PATH="$(go env GOROOT)/lib/wasm:$PATH" GOOS=js GOARCH=wasm go run ./hello
hello from js/wasm

$ PATH="$(go env GOROOT)/lib/wasm:$PATH" GOOS=js GOARCH=wasm go test ./catalog
ok  	example.com/shelf/catalog	0.116s

//go:build js && wasm

// Command shelfjs exposes the catalogue's ISBN validation to JavaScript.
package main

import (
	"errors"
	"fmt"
	"syscall/js"

	"example.com/shelf/catalog"
)

// parseISBN adapts catalog.ParseISBN to the func(this, args) shape that
// js.FuncOf requires. It returns a plain JavaScript object.
func parseISBN(this js.Value, args []js.Value) any {
	if len(args) != 1 || args[0].Type() != js.TypeString {
		return js.Global().Get("TypeError").New("parseISBN wants one string")
	}
	isbn, err := catalog.ParseISBN(args[0].String())
	if errors.Is(err, catalog.ErrInvalidISBN) {
		return map[string]any{"ok": false, "error": err.Error()}
	}
	return map[string]any{"ok": true, "isbn": isbn.String()}
}

func main() {
	js.Global().Set("shelfParseISBN", js.FuncOf(parseISBN))
	fmt.Println("shelf: ready")
	select {} // keep the Go runtime alive so JavaScript can call back in
}

// Host: load wasm_exec.js (from GOROOT/lib/wasm), start the module, call it.
require(process.env.WASM_EXEC);
const fs = require("node:fs");

const go = new Go();
WebAssembly.instantiate(fs.readFileSync("shelf.wasm"), go.importObject).then(({ instance }) => {
  go.run(instance); // returns a promise that settles when main returns
  console.log(shelfParseISBN("978-0-13-468599-1"));
  console.log(shelfParseISBN("978-0-13-468599-2"));
  console.log(shelfParseISBN(42) instanceof TypeError);
  process.exit(0);
});

$ GOOS=js GOARCH=wasm go build -o shelf.wasm ./js
$ WASM_EXEC=$(go env GOROOT)/lib/wasm/wasm_exec.js node js/run.js
shelf: ready
{ ok: true, isbn: '9780134685991' }
{ ok: false, error: 'catalog: invalid ISBN: "978-0-13-468599-2"' }
true

<!doctype html>
<meta charset="utf-8">
<title>shelf wasm</title>
<input id="isbn" value="978-0-13-468599-1">
<button id="check" disabled>Check</button>
<output id="result"></output>
<script src="wasm_exec.js"></script>
<script>
  const go = new Go();
  WebAssembly.instantiateStreaming(fetch("shelf.wasm"), go.importObject).then(({ instance }) => {
    go.run(instance); // do not await: main blocks forever
    const button = document.getElementById("check");
    button.disabled = false;
    button.addEventListener("click", () => {
      const r = shelfParseISBN(document.getElementById("isbn").value);
      document.getElementById("result").textContent = r.ok ? "valid: " + r.isbn : r.error;
    });
  });
</script>

//go:build js && wasm

package main

import (
	"fmt"
	"syscall/js"
)

func main() {
	fmt.Println(js.ValueOf(map[string]any{"n": 1, "s": "x"}).Type(), js.ValueOf([]any{1, "a"}).Length())
	v := js.ValueOf("not a number")
	fmt.Println(v.Type(), js.Undefined().Type(), js.Null().Type(), js.ValueOf(1.5).Type(), js.ValueOf(true).Type())
	fmt.Println(v.Int())
}

object 2
string undefined null number boolean
panic: syscall/js: call of Value.Int on string

goroutine 1 [running]:
syscall/js.Value.float({{}, 0x7ff8000200000016, 0x20e0b8}, {0x6f45, 0x9})
	.../src/syscall/js/js.go:523 +0x10
syscall/js.Value.Int(...)
	.../src/syscall/js/js.go:540
main.main()
	.../js3/main.go:14 +0x2c
exit code: 2

//go:build js && wasm

// Command shelfjs2 shows Go calling JavaScript: a promise-returning lookup,
// a callback, byte-array copying and a call to console.log.
package main

import (
	"fmt"
	"syscall/js"
	"time"

	"example.com/shelf/catalog"
)

var store = catalog.NewMemStore()

// lookup returns a Promise. The Go work runs in its own goroutine, because
// a js.Func callback must not block waiting on the JavaScript event loop.
func lookup(this js.Value, args []js.Value) any {
	isbn := catalog.ISBN(args[0].String())
	handler := js.FuncOf(func(_ js.Value, p []js.Value) any {
		resolve, reject := p[0], p[1]
		go func() {
			time.Sleep(10 * time.Millisecond) // pretend to wait for I/O
			b, ok := store.Get(isbn)
			if !ok {
				reject.Invoke(js.Global().Get("Error").New("not found: " + string(isbn)))
				return
			}
			resolve.Invoke(b.Title)
		}()
		return nil
	})
	// The executor has already run by the time New returns, so release it.
	defer handler.Release()
	return js.Global().Get("Promise").New(handler)
}

// checksum copies a Uint8Array into Go memory and back out again.
func checksum(this js.Value, args []js.Value) any {
	buf := make([]byte, args[0].Get("length").Int())
	n := js.CopyBytesToGo(buf, args[0])
	var sum byte
	for _, b := range buf[:n] {
		sum += b
	}
	return int(sum)
}

func main() {
	store.Put(catalog.Book{ISBN: "9780134685991", Title: "Effective Java"})
	js.Global().Set("shelfLookup", js.FuncOf(lookup))
	js.Global().Set("shelfChecksum", js.FuncOf(checksum))
	console := js.Global().Get("console")
	console.Call("log", "hello from Go:", fmt.Sprintf("%d books", len(store.All())))
	select {}
}

require(process.env.WASM_EXEC);
const fs = require("node:fs");

const go = new Go();
WebAssembly.instantiate(fs.readFileSync("shelf2.wasm"), go.importObject).then(async ({ instance }) => {
  go.run(instance);
  console.log(await shelfLookup("9780134685991"));
  await shelfLookup("0000000000000").catch((e) => console.log("rejected:", e.message));
  console.log(shelfChecksum(new Uint8Array([1, 2, 3, 200])));
  process.exit(0);
});

hello from Go: 1 books
Effective Java
rejected: not found: 0000000000000
206

//go:build js && wasm

package main

import "syscall/js"

func main() {
	js.Global().Set("hi", js.FuncOf(func(this js.Value, args []js.Value) any { return "hi" }))
	// main returns: the Go program has exited.
}

require(process.env.WASM_EXEC);
const fs = require("node:fs");
const go = new Go();
WebAssembly.instantiate(fs.readFileSync("js4.wasm"), go.importObject).then(async ({ instance }) => {
  await go.run(instance);
  console.log("exit code:", go.exited);
  try { console.log(hi()); } catch (e) { console.log("error:", e.message); }
});

exit code: true
error: Go program has already exited

//go:build js && wasm

// Command shelffetch uses net/http inside WebAssembly: in a browser the
// default transport is implemented with the host's fetch function.
package main

import (
	"context"
	"encoding/json"
	"fmt"
	"net/http"
	"os"
	"syscall/js"
	"time"
)

func main() {
	// Ask the page where it was loaded from; a relative URL would be rejected.
	origin := js.Global().Get("location").Get("origin").String()

	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
	defer cancel()

	req, err := http.NewRequestWithContext(ctx, http.MethodGet, origin+"/books/9780134685991", nil)
	if err != nil {
		fmt.Println(err)
		os.Exit(1)
	}

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		fmt.Println("request:", err)
		os.Exit(1)
	}
	defer resp.Body.Close()

	var book struct {
		ISBN  string `json:"isbn"`
		Title string `json:"title"`
	}
	if err := json.NewDecoder(resp.Body).Decode(&book); err != nil {
		fmt.Println("decode:", err)
		os.Exit(1)
	}
	fmt.Println(resp.Status, book.ISBN, book.Title)
}

200 OK 9780134685991 Effective Java
done

// Command isbncheck validates ISBNs read from standard input. It is an
// ordinary Go program: it also builds for wasip1/wasm with no changes.
package main

import (
	"bufio"
	"fmt"
	"os"
	"path/filepath"
	"runtime"

	"example.com/shelf/catalog"
)

func main() {
	fmt.Printf("platform: %s/%s, args: %q\n", runtime.GOOS, runtime.GOARCH, os.Args[1:])

	valid, invalid := 0, 0
	sc := bufio.NewScanner(os.Stdin)
	for sc.Scan() {
		if _, err := catalog.ParseISBN(sc.Text()); err != nil {
			invalid++
			fmt.Fprintln(os.Stderr, "invalid:", err)
			continue
		}
		valid++
	}
	if err := sc.Err(); err != nil {
		fmt.Fprintln(os.Stderr, err)
		os.Exit(1)
	}

	// The WASI host decides which directories exist at all.
	dir := os.Getenv("SHELF_DATA")
	if dir == "" {
		dir = os.TempDir()
	}
	report := fmt.Sprintf("valid=%d invalid=%d\n", valid, invalid)
	if err := os.WriteFile(filepath.Join(dir, "report.txt"), []byte(report), 0o644); err != nil {
		fmt.Fprintln(os.Stderr, "write report:", err)
		os.Exit(2)
	}
	fmt.Print(report)
}

// Minimal WASI host for a Go wasip1 command, using Node's built-in node:wasi.
import { readFileSync } from "node:fs";
import { WASI } from "node:wasi";

const [, , file, ...args] = process.argv;
const wasi = new WASI({
  version: "preview1",
  args: [file, ...args],
  env: { SHELF_DATA: process.env.GUEST_DIR ?? "/data" },
  preopens: { "/data": process.env.DATA_DIR },
});
const { instance } = await WebAssembly.instantiate(readFileSync(file), wasi.getImportObject());
process.exitCode = wasi.start(instance);

$ GOOS=wasip1 GOARCH=wasm go build -o isbncheck.wasm ./cmdwasi
$ printf '978-0-13-468599-1\n978-0-13-468599-2\n' | DATA_DIR=$PWD/data node --no-warnings wasi/run.mjs isbncheck.wasm a b
platform: wasip1/wasm, args: ["a" "b"]
invalid: catalog: invalid ISBN: "978-0-13-468599-2"
valid=1 invalid=1
$ cat data/report.txt
valid=1 invalid=1

$ printf '9780134685991\n' | DATA_DIR=$PWD/data GUEST_DIR=/nope node --no-warnings wasi/run.mjs isbncheck.wasm
platform: wasip1/wasm, args: []
write report: open /nope/report.txt: Invalid argument
$ echo $?
2

$ GOOS=wasip1 GOARCH=wasm go run -exec="$(go env GOROOT)/lib/wasm/go_wasip1_wasm_exec" ./hello
/Users/.../sdk/go1.27.2/lib/wasm/go_wasip1_wasm_exec: line 17: exec: wasmtime: not found
exit status 127

#!/usr/bin/env node
// A go test -exec wrapper: run the test binary with Node's WASI host.
import { readFileSync } from "node:fs";
import { WASI } from "node:wasi";

const [, , file, ...args] = process.argv;
const wasi = new WASI({
  version: "preview1",
  args: [file, ...args],
  env: process.env,
  preopens: { "/": "/" },
  returnOnExit: true,
});
const { instance } = await WebAssembly.instantiate(readFileSync(file), wasi.getImportObject());
process.exitCode = wasi.start(instance);

$ GOOS=wasip1 GOARCH=wasm go run -exec="$PWD/wasi/node_wasi_exec.sh" ./hello
hello from wasip1/wasm
$ GOOS=wasip1 GOARCH=wasm go test -exec="$PWD/wasi/node_wasi_exec.sh" ./catalog
ok  	example.com/shelf/catalog	0.096s

//go:build wasip1

package main

import (
	"structs"
	"unsafe"
)

// Loan has a layout the host can rely on: fields in order, C-style padding.
type Loan struct {
	_    structs.HostLayout
	Days int32   // offset 0
	Rate float32 // offset 4
}

// Fine computes the overdue fine for a loan the host wrote into our memory.
//
//go:wasmexport fine
func Fine(l *Loan) float32 { return float32(l.Days) * l.Rate }

// Layout lets the host check its assumptions at run time.
//
//go:wasmexport sizeof_int
func SizeofInt() int32 { return int32(unsafe.Sizeof(int(0))) }

//go:wasmexport sizeof_loan
func SizeofLoan() int32 { return int32(unsafe.Sizeof(Loan{})) }

//go:wasmexport new_loan
func NewLoan() *Loan { l := new(Loan); keep = l; return l }

var keep *Loan

func main() {}

import { readFileSync } from "node:fs";
import { WASI } from "node:wasi";

const wasi = new WASI({ version: "preview1" });
const { instance } = await WebAssembly.instantiate(readFileSync("layout.wasm"), wasi.getImportObject());
wasi.initialize(instance);
const { memory, new_loan, fine, sizeof_int, sizeof_loan } = instance.exports;

console.log("sizeof(int) in the module:", sizeof_int(), "bytes");
console.log("sizeof(Loan):", sizeof_loan(), "bytes");

const ptr = new_loan(); // an i32 offset into linear memory
const view = new DataView(memory.buffer, ptr, sizeof_loan());
view.setInt32(0, 12, true); // Days (wasm is little-endian)
view.setFloat32(4, 0.25, true); // Rate
console.log("fine:", fine(ptr));

$ GOOS=wasip1 GOARCH=wasm go build -buildmode=c-shared -o layout.wasm ./layout
$ node --no-warnings layout/host.mjs
sizeof(int) in the module: 8 bytes
sizeof(Loan): 8 bytes
fine: 3

t1/main.go:11:6: go:wasmexport: unsupported parameter type *Loan