all: add GOOS=wasip1 GOARCH=wasm port

[johanbrandhorst]

Background

The WebAssembly System Interface (WASI, https://wasi.dev/) is gaining popularity as a compile-once-run-anywhere target for developer and cloud native applications. Many cloud providers are offering services that make it possible to execute WASI directly inside familiar orchestration frameworks like Kubernetes (https://learn.microsoft.com/en-us/azure/aks/use-wasi-node-pools, https://docs.krustlet.dev/howto/), or on edge compute platforms (https://developer.fastly.com/learning/compute/, https://blog.cloudflare.com/announcing-wasi-on-workers/) and the popular developer tool Docker has beta support for executing wasi directly (https://docs.docker.com/desktop/wasm/). For Go to remain relevant in a hypothetical world where this becomes a significant part of software delivery, it must support compiling code to the Wasm binary format and the WASI syscall API.

Proposal

We propose adding a new port, GOOS=wasip1 GOARCH=wasm, that targets the wasi_snapshot_preview1 syscall API. We further propose allowing the use of the go:wasmimport compiler directive in the syscall package, in addition to the currently allowed runtime and syscall/js packages.

Discussion

Go already supports WebAssembly (Wasm) through the existing GOOS=js GOARCH=wasm port, and the implementation of this proposal would reuse the existing Wasm architecture code and change the interface with which the compiled code interacts with the outside world. It builds on the accepted proposal (#38248) for a go:wasmimport compiler directive for defining Wasm host function imports. The compiled code would be a “Command”, executing func main and running until exit, similar to the existing js/wasm port.

Syscall API target

Today, implementing WASI means implementing the wasi_snapshot_preview1 API described in the spec. However, this interface is evolving without the insurance of backward compatibility. A “preview2” version is already being worked on. Should the Go compiler support the old one for now, and switch to the new one in the future, or should we name the new GOOS such that we can add new GOOS’s for new WASI APIs? We propose that we assume the wasi_snapshot_preview1 API for now and that future releases of Go may add support for newer syscall APIs under a different GOOS (e.g. GOOS=wasip2 for wasi_snapshot_preview2).

Maintainers

Since this is a new port and the porting policy requires at least two maintainers, Evan Phoenix (@evanphx), Julien Fabre (@Pryz) and I (@johanbrandhorst) are volunteering to be maintainers of this port.

Testing

The wasi/wasm port will be tested by executing the standard library tests using an established WASI VM, such as Wasmtime. This software has precompiled binaries available for download, which can be used to set up a builder for the trybots, similar to how NodeJS is used for the js/wasm port.

What happens to the js/wasm port?

The existing js/wasm port will remain relevant for the purposes of compiling Go Wasm for running in a JavaScript VM and using the syscall/js interface for interacting with the JS world. Both ports will coexist, and should eventually require minimal differences in compiler and syscall code. See the discussion on rewriting wasm_exec.js for more information.

A note on capabilities

wasi_snapshot_preview1 is limited in ways that may be surprising to users, for example, it is not possible to open a network socket with the APIs defined in the spec. The initial implementation of the wasi target will aim to implement as much of the standard library as possible, but there will be big gaps.

Related issues

This would close #31105, which has mostly been a discussion issue.

Future work

WASI Preview2

As the second snapshot of the WASI standard matures, we will aim to add support for the new standard. This will unlock new functionality such as networking sockets and ensure that Go’s WASI support remains relevant for users. This could be done in any new major release of the Go toolchain, but not in a minor revision.

Considering the upcoming changes in preview 2, it is a legitimate question to ask whether the work to add support for wasi_snapshot_preview1 is worth doing; could we simply wait for the next standard iteration? We believe the work to be useful because at this time, all compilers are targeting preview 1, and preview 2 seems far from being fully completed. We also believe that runtimes will provide polyfills to preview 1 while preview 2 is in the process of being implemented (see this Wasmtime issue). Finally, the next version of the WASI standard is split into multiple components, and it is possible that specifications for each component will be finalized at different times, with preview 1 remaining the de-facto fallback for components that are not yet fully specified or implemented by runtimes yet.

Rewriting wasm_exec.js as WASI and unifying syscall interfaces

The existing js/wasm port has a custom syscall interface implemented by wasm_exec.js and run on any JavaScript VM. Now that a standard is emerging, the js/wasm target should reuse the same syscall interface, allowing parts of the syscall interface between wasi and js to be unified to reduce maintenance burden. This would require implementing a WASI interface shim in wasm_exec.js, which is a significant undertaking, and thus out of scope of this initial WASI work.

WASI Libraries (AKA Reactors)

The WASI concept of libraries allow compiled binaries to expose single functions for consumption from the host. This is not something that will be supported in the initial WASI port, as it requires a concept of marking Go functions as exported (i.e. //go:wasmexport), and somehow facilitating the execution of a single function. For more discussions on why this is complicated, see #42372.

GOOS=none GOARCH=wasm

Binary wasm can run without any particular knowledge of its host, perhaps using something like GOOS=none, similar to Rust’s wasm32-unknown-unknown target. This proposal does not propose any such port be added, but it may be something to consider in the future. The name “none” is, of course, not decided.

Authors

@johanbrandhorst, @Pryz, @evanphx, @achille-roussel

[prattmic]

I like the idea of using GOOS=wasi to distinguish from GOOS=js. It seems like a natural place to select wasi.

The obvious concern here to me is the instability of the API of wasi_snapshot_preview1. Is wasi_snapshot_preview2 planning to be backwards compatible with wasi_snapshot_preview1 binaries? (It sounds like no?). If not, I am concerned by GOOS=wasi changing APIs between versions because I suspect (a) some users will want preview2 ASAP to use new feature, and (b) some users will want to keep preview1 because their wasm runtime doesn't support preview2 yet. These are in direct conflict with one another.

As a workaround, we could have GOWASI=preview1, or something like that, similar to GOARM, GOAMD64, etc.

What is the timeline for a "stable" version of WASI? The other end of the spectrum would be to say that GOOS=wasi is not stable (hidden behind a GOEXPERIMENT maybe?) and will change compatibility arbitrarily from release-to-release until there is a stable version of WASI to target.

[prattmic]

From https://github.com/WebAssembly/WASI: "The WebAssembly System Interface is not a monolithic standard system interface, but is instead a modular collection of standardized APIs. None of the APIs are required to be implemented to have a compliant runtime. Instead, host environments can choose which APIs make sense for their use cases."

Will there be some minimum requirements that the Go runtime will require from the host environment? Or will Go still work even if the host environment provides no APIs?

[codefromthecrypt]

@prattmic while not documented really, the usual way features are disabled is via syscall.ENOSYS errors.

For example, when source is compiled with GOARCH=wasm GOOS=js and let's say wazero is running it, if that code tries to access the filesystem and the filesystem is disabled, the wazero host functions return an ENOSYS error which the compiled code expects and returns an error message like "not implemented in js"

In the case of WASI, and specifically the most implemented version of it (snapshot-01), there are error codes which map to syscall.Errno here https://github.com/WebAssembly/WASI/blob/snapshot-01/phases/snapshot/docs.md#-errno-enumu16

[johanbrandhorst]

The obvious concern here to me is the instability of the API of wasi_snapshot_preview1. Is wasi_snapshot_preview2 planning to be backwards compatible with wasi_snapshot_preview1 binaries? (It sounds like no?). If not, I am concerned by GOOS=wasi changing APIs between versions because I suspect (a) some users will want preview2 ASAP to use new feature, and (b) some users will want to keep preview1 because their wasm runtime doesn't support preview2 yet. These are in direct conflict with one another.

The existing js/wasm port has generally taken a conservative approach to including new features, and we would seek to emulate that. We don't yet know what would be the threshold for switching over to preview2, but it would likely be year(s) in the future. A GOWASI environment variable as suggested may be considered, but it shouldn't be necessary in the near term.

I will note also that the existing js/wasm port is still considered experimental and can introduce breaking changes at any time. The wasi/wasm port would similarly not provide any backwards compatibility guarantees. It would seem appropriate for this to remain the case until a stable WASI API spec is available and implemented in runtimes at least.

Will there be some minimum requirements that the Go runtime will require from the host environment? Or will Go still work even if the host environment provides no APIs?

Go binaries compiled with GOOS=wasi would require the host to provide the full wasi_snapshot_preview1 API. A hypothetical GOOS=none GOARCH=wasm could be introduced to avoid any host dependencies, but it's not currently part of our planning.

[prattmic]

@codefromthecrypt:

@prattmic while not documented really, the usual way features are disabled is via syscall.ENOSYS errors.

@johanbrandhorst:

Go binaries compiled with GOOS=wasi would require the host to provide the full wasi_snapshot_preview1 API.

These seem a bit contradictory?

I'm specifically wondering about APIs which the Go runtime cannot run without at all. e.g., we may require clock_get_time to implement runtime.nanotime, because the runtime more-or-less can't run without a source of time [1]. I'm wondering if there are other cases.

It doesn't seem like we'd need to require all APIs. e.g., fd_sync wouldn't be called by Go unless the program explicitly calls os.File.Sync/syscall.Sync. Those returning an error seems fine to me.

[1] OK, maybe not a perfect example, since technically -tags=faketime doesn't require a time source.

[johanbrandhorst]

I'm not sure what you're asking exactly, the way I see this being implemented is by translating syscalls in the code to the relevant host API calls. Sure you could build a wasi binary that doesn't use all of the API and it'd work fine on a host that only implements the part of the API that's used, but I don't think the implementation should need to do any sort of feature capability negotiation with the host - if the API returns ENOSYS then the function call fails up the stack. Does that sound okay?

For your specific example, I guess if clock_get_time isn't implemented it would fail very quickly at runtime, not try to get by without a clock source.

[ianlancetaylor]

At the very least for documentation purposes I think we want to be able to write down which APIs must be implemented in order to run simple Go programs.

[johanbrandhorst]

At the very least for documentation purposes I think we want to be able to write down which APIs must be implemented in order to run simple Go programs.

Not that I disagree, but I'm a little confused by this inquiry - are we expecting users to implement their own partial implementations of wasi_snapshot_preview1 in the hopes of running simple Go programs? It's tempting to say that any Go compiled wasi binary requires the host to provide the API defined by the spec. What is the purpose of defining a minimal API used by simple Go programs?

[codefromthecrypt]

@ianlancetaylor

At the very least for documentation purposes I think we want to be able to write down which APIs must be implemented in order to run simple Go programs.

I think initially it would look like TinyGo, which implements a subset of wasi. Here's a list of functions that are used and who uses them https://wazero.io/specs/#wasi and here's an example simple cat program. Hope it helps!

$ wasm2wat ./cmd/wazero/testdata/cat/cat-tinygo.wasm|grep 'import "wasi'
  (import "wasi_snapshot_preview1" "fd_write" (func $runtime.fd_write (type 0)))
  (import "wasi_snapshot_preview1" "clock_time_get" (func $runtime.clock_time_get (type 1)))
  (import "wasi_snapshot_preview1" "args_sizes_get" (func $runtime.args_sizes_get (type 2)))
  (import "wasi_snapshot_preview1" "args_get" (func $runtime.args_get (type 2)))
  (import "wasi_snapshot_preview1" "proc_exit" (func $runtime.proc_exit (type 3)))
  (import "wasi_snapshot_preview1" "environ_get" (func $__imported_wasi_snapshot_preview1_environ_get (type 2)))
  (import "wasi_snapshot_preview1" "environ_sizes_get" (func $__imported_wasi_snapshot_preview1_environ_sizes_get (type 2)))
  (import "wasi_snapshot_preview1" "fd_close" (func $__imported_wasi_snapshot_preview1_fd_close (type 4)))
  (import "wasi_snapshot_preview1" "fd_fdstat_get" (func $__imported_wasi_snapshot_preview1_fd_fdstat_get (type 2)))
  (import "wasi_snapshot_preview1" "fd_filestat_get" (func $__imported_wasi_snapshot_preview1_fd_filestat_get (type 2)))
  (import "wasi_snapshot_preview1" "fd_prestat_get" (func $__imported_wasi_snapshot_preview1_fd_prestat_get (type 2)))
  (import "wasi_snapshot_preview1" "fd_prestat_dir_name" (func $__imported_wasi_snapshot_preview1_fd_prestat_dir_name (type 5)))
  (import "wasi_snapshot_preview1" "fd_read" (func $__imported_wasi_snapshot_preview1_fd_read (type 0)))
  (import "wasi_snapshot_preview1" "fd_seek" (func $__imported_wasi_snapshot_preview1_fd_seek (type 6)))
  (import "wasi_snapshot_preview1" "path_open" (func $__imported_wasi_snapshot_preview1_path_open (type 7)))

[dmitshur]

CC @golang/release.

[prattmic]

At the very least for documentation purposes I think we want to be able to write down which APIs must be implemented in order to run simple Go programs.

Not that I disagree, but I'm a little confused by this inquiry - are we expecting users to implement their own partial implementations of wasi_snapshot_preview1 in the hopes of running simple Go programs?

I haven't been following wasm/wasi super closely, so maybe I've misunderstood, but I thought that wasm/wasi was commonly using in "sandboxing"-type scenarios, where presumably the operator wants to limit the APIs that the sandboxed program has access to. Documenting the minimum requirements for the Go runtime itself makes it clear to those building a sandbox what the most restricted set of APIs they can provide is (and if that is still too permissive, maybe Go programs aren't a good sandboxee target).

[johanbrandhorst]

I haven't been following wasm/wasi super closely, so maybe I've misunderstood, but I thought that wasm/wasi was commonly using in "sandboxing"-type scenarios, where presumably the operator wants to limit the APIs that the sandboxed program has access to. Documenting the minimum requirements for the Go runtime itself makes it clear to those building a sandbox what the most restricted set of APIs they can provide is (and if that is still too permissive, maybe Go programs aren't a good sandboxee target).

This is a great point, and I agree. Thank you. Do we have a rough idea of the syscalls required by the runtime today? I expect to get exact information would require an experimental implementation (which we are working on), but I could add a preliminary list to the proposal. The TinyGo information is presumably not going to be representative of the behavior of gc?

[prattmic]

I think it is fine to figure out in prototyping, the list doesn't need to be in the proposal.

FWIW, quickly looking through https://github.com/WebAssembly/WASI/blob/snapshot-01/phases/snapshot/docs.md#modules, the only ones that look really important to me are clock_get_time, and proc_exit. The args and environ ones could be optional, but the implementation will need to be careful to check for errors (it would be easy to assume they wouldn't fail).

Some sort of I/O (fd_read, fd_write) shouldn't technically be required, though in practice almost any program probably wants to use stdin/stdout/stderr.

[prattmic]

Hm, one more problem I see is that https://github.com/WebAssembly/WASI/blob/snapshot-01/phases/snapshot/docs.md#modules does not seem to implement any kind of timer/sleep/wait. Am I missing something? It seems like that will require the Go runtime to spin when there is nothing else to do.

[evanphx]

@prattmic There is poll_oneoff which includes both clock and fd event types, so we'd use that. https://github.com/WebAssembly/WASI/blob/snapshot-01/phases/snapshot/docs.md#-eventtype-enumu8

[johanbrandhorst]

The latest CNCF annual survey describes WebAssembly as "the future", though it is unclear whether that's within a JS runtime environment or WASI.

[Mossaka]

Hey there, I am very excited for this proposal!

We also believe that runtimes will provide polyfills to preview 1 while preview 2 is in the process of being implemented

This is indeed true. Please see this repo where the community is building a polyfill adapter for wasi preview1 modules to call preview2 functions.

[rsc]

This proposal has been added to the active column of the proposals project
and will now be reviewed at the weekly proposal review meetings.
— rsc for the proposal review group

[johanbrandhorst]

I just made a minor change to the proposal. In addition to the previous statement, I added

We further propose allowing the use of the go:wasmimport compiler directive in the syscall package, in addition to the currently allowed runtime and syscall/js packages.

This will be necessary to define the syscall methods used to interact with the WASI host through the go:wasmimport compiler directive.

[aclements]

The compiler/runtime team at Google is generally supportive of WASI support. It seems like a good idea and an important direction for WASM.

Our one big question is how to set things up for preview2 in the future. @prattmic suggested a GOWASI environment variable to parallel GO386/GOAMD64/etc. That would be our first GO$GOOS variable, and it's not "additive" in the way that the GO$GOARCH variables are (e.g., amd64 but with more instructions), but it's certainly worth considering. Another option is that we put it in GOOS itself, like GOOS=wasip1. My impression is that WASI preview1 and WASI preview2 kind of are different operating systems, rather than a base layer with additions in preview2, which suggests using different GOOS values to me.

[rsc]

We already adapt OS implementations based on what's available, like using newer functions on Windows if they are present in the DLL, or falling back to older system calls on Linux when a newer one returns ENOSYS. Do we think preview1 and preview2 will be close enough to make that same approach feasible?

One possibility is to use GOOS=wasi for preview1 and then decide when preview2 is more settled whether that needs to be a separate GOOS or can be incorporated into GOOS=wasi.

[codefromthecrypt]

Do we think preview1 and preview2 will be close enough to make that same approach feasible?

TL;DR; I think they are too different because component model changes things. We should not assume the same approach will be best both for snapshot01 and snapshot02

WASI preview1 was a continuation of CloudABI and preview2 is a complete rewrite.

preview1 has a relatively straightforward, albeit monolithic ABI. All functions are in the same wasi_snapshot_preview1 and only depend on WebAssembly Core 1.0 features.

what's being called preview2 is a complete redo, which is based on the finalizing component model. Component model is a change to the binary format of WebAssembly. Specific to WASI, this splits various modules such as wasi-filesystem. There will be an adapter to forward snapshot01 to this new model.

For what its worth, the wazero team will be implementing component model and WASI snapshot 2 when they are ready, just likely not until the end of the year. As we learn more, we can help advise.

[gedw99]

sone high level integration questions:

Does this change how wasm is setup for the browser ? We will be compiling to wasi ?

The wasm.js file won’t be needed anymore ?

[cherrymui]

It doesn't change how it works for browsers, which is GOOS=js GOARACH=wasm, and it still needs wasm_exec.js.

[jakebailey]

Note that since it's still wasm, you can of course still run it in the browser, but the "OS" side of things shifts from that JS shim to providing an imports object that contains a wasi_snapshot_preview1 property when instantiating the compiled wasm module.

E.g. I've managed to run Go WASI in the browser by using a library that implements all of the calls: https://github.com/jakebailey/esbuild-playground/blob/e7734ada3405ea29225b4d063d76d6d0ff294daf/src/esbuild/wasiWorker.ts#L75

You can also do the same thing in Node, either via similar libraries to wasi-js or @wasmer/wasi, or just https://nodejs.org/api/wasi.html.

As a sidenote, the latter idea of using Node's WASI module would make another interesting builder (cc @johanbrandhorst).

[johanbrandhorst]

Longer term we aim to rewrite wasm_exec.js in terms of the wasi syscall API (as much as possible) to remove differences between the different OS implementations. Would you be interested in contributing this 😄?

Interesting thought Jake, that would indeed be another valuable environment to test against. I don't have any plans on doing this in the short term but contributions are always accepted 😄.

[gedw99]

wasm_exec.js

Would be good as wasm_exec.js is kind of a mess . I am guessing because it had to cope with the evolution of golang and wasm over the years.

Maybe a wasi_exec.js should be used for go 1.21.1 going forward and wasm_exec.js for all previous versions. Just thinking out loud so that there is a clean break. Am speaking in terms of browsers btw.

[gedw99]

Note that since it's still wasm, you can of course still run it in the browser, but the "OS" side of things shifts from that JS shim to providing an imports object that contains a wasi_snapshot_preview1 property when instantiating the compiled wasm module.

E.g. I've managed to run Go WASI in the browser by using a library that implements all of the calls: https://github.com/jakebailey/esbuild-playground/blob/e7734ada3405ea29225b4d063d76d6d0ff294daf/src/esbuild/wasiWorker.ts#L75

You can also do the same thing in Node, either via similar libraries to wasi-js or @wasmer/wasi, or just https://nodejs.org/api/wasi.html.

As a sidenote, the latter idea of using Node's WASI module would make another interesting builder (cc @johanbrandhorst).

I would love to try this @jakebailey
If there is anything I can work on or try out it would be awesome.

[gopherbot]

Change https://go.dev/cl/503756 mentions this issue: internal/releasetargets: regenerate all ports for Go 1.21

[mar1n3r0]

It doesn't change how it works for browsers, which is GOOS=js GOARACH=wasm, and it still needs wasm_exec.js.

Interesting. Can we access the DOM and the local file system of the host at the same time from wasi?

To give more context. I am currently hosting js based wasm on IPFS as means of p2p dapps. The wasm is hosted locally by each peer. Because I don't have access to the local host I can't connect to a CRDT database from within the browser and so had to fork the IPFS daemon which serves as a backend in that case called by the wasm locally.

[johanbrandhorst]

The DOM is not automatically accessible to WASI compiled Wasm binaries (there is no syscall/js for WASI).

[mar1n3r0]

The DOM is not automatically accessible to WASI compiled Wasm binaries (there is no syscall/js for WASI).

So theoretically it would be possible if syscall/js is ported?

[johanbrandhorst]

Wasm runtimes can define any APIs they like, and with go:wasmimport you can write Go wrappers around the APIs (a third party syscall/js, if you will). It seems impractical to me. In any case, this issue is not the right forum for this discussion. Please do not bump it.