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.

[codefromthecrypt]

No problem, and thanks for asking @johanbrandhorst FWIW I don't think you are being dismissive, rather doing the right thing and arguing for less code, or at least a chance of it. I want that, too, just I'm not sure it is realistic to put a near term date on that.

On current vs next features, there are changes are not only in the functions supported, but also what they support as parameters. Also, how concepts like how main works and pre-opens are handled (command world) are very different. To inventory this while the specs change even in format routinely is possible, but I would say from what I've seen the various sub specifications wasi next specifies more functions than wasi 1, except with more constrained parameters.

For example, you can see if a file is readable, but you can't get the posix 755 etc data back. It would really take a paper to go through all the differences, and I won't have time to do that for a month. That said I'm interested in it and will do it eventually for my own sanity.

I guess the part you are concerned about is if feature gaps between the two will be the primary user concern. As hinted above, things have to settle to even know what will be a feature, and I think if I can't figure it out, end users will have a harder time ;)

I think users will be driven by product support, as compiling to wasm only matters where it can be run. There are many existing wasi preview1 products out there, including envoy, various k8s tools, etc. An extremely relevant reason for users to care is to continue using a product which may have no roadmap or plan to support wasi-2 for the next couple years.

This may be due to an explicit support decision or a runtime constraint, or due to not wanting to have multiple cores. For example, some language compilers may choose to never do wasi-2 due to its complexity and incompatibility with the only w3c REC of the core: 1.0. Let's remember that component model literally changes the format of the webassembly binary. Also keep in mind that even component model isn't scheduled for the 2.0 draft of wasm yet!

Anyway, let's say the specs settle and runtimes immediately support it and products and other compilers immediately do also, and it is 2025 all products run both current wasm and component model based wasm, and no one needs to recompile current wasm anymore. As a software maintainer, I would be all for removing that code! I don't know if the year is 2025, but would bet at least $5 it isn't gonna be 2024 ;)

[codefromthecrypt]

I have an idea. the main change in wasi next is that it eventually uses component model, which is a different binary format than wasm 1.0 which is what go supports right now. What if instead of push and pull about the GOOS "wasi" we make this a decision about GOARCH where if the GOARCH is a choice that supports component model (writing 1.0 incompatible wasm), a GOOS "wasi" would be the other codebase. In other words, don't allow wasi 1 if compiling to component model. Does this help?

[codefromthecrypt]

concrete proposal

GOARCH=wasm GOOS=wasi == Wasm core 1.0 with wasi snapshot01
GOARCH=wasm2 GOOS=wasi == Wasm core 2.0 + component model with wasi 2,3,..1.0

[johanbrandhorst]

After speaking with @codefromthecrypt and others it seems clear to me that there is some anxiety around the planned adoption schedule of preview2. I wanted to add to the discussion that I think it's entirely possible (and perhaps likely) that we wouldn't implement preview2 or even preview3 and wait for 1.0, depending on the state of the ecosystem. It seems there is some question around the big changes from preview1 to preview2 which may cause regressions and instability.

Any discussion to move from one syscall interface to the next (i.e. preview1 to preview2) would be carefully considered with community feedback taken into account. We may even produce prototype implementations of these so that we can gauge the impact of switching to the new syscall interface.

Given that, is there still opposition to using GOOS=wasi to mean preview1 now and something else in the future (perhaps not until wasi 1.0), without the need for alternative GOARCH or GOWASI values?

[rsc]

GOOS=wasi would be targeting specific wasi runners (not browsers). Presumably those will have their own compatibility windows where they support, for example, both preview1 and preview2. It seems OK to change the specific target from one Go release to the next as long as we are clear in documentation that this will happen and perhaps also pre-announce the change. It will just mean people need an up-to-date-enough runner to update to a newer Go.

If we decide that GOOS=wasi is going to be a moving target at least through 1.0, have all concerns with this proposal been addressed?

[codefromthecrypt]

If we decide that GOOS=wasi is going to be a moving target at least through 1.0, have all concerns with this proposal been addressed?

@rsc the main concern of a moving target is that it will create some difficulty for people to transition. there will be a large gap (years) between the beginning of preview2 and the end of 1.0, and meanwhile a lot of platforms aren't likely to have the host functions for the interim steps. Also, there will likely be bugs both in compilers and runtimes as people figure out what preview 2..1.0 means in practice.

Given Go's 6 month release schedule the impact I'm most concerned with is people being pinned to an old Go, which will drop out of support before wasi 1.0 completes. In other words at the point a hard swap of GOOS=wasi meaning something less supported or stable than now, users will get pinned to a go compiler that still works with current day wasi.

Having a strict policy of only one operating system usable outside of browsers at a time will cause some problems whenever implemented, as not everything updates, in other words. The other problem is delayed feedback into the next version of wasi. For example, there's a large chance some design concern there goes unnoticed until too late. The chicken-egg problem forced when we have a policy of a single wasm operating system for outside browser use.

If we must do this, and I understand the valid reasons why... I believe the next wasi shouldn't cut over until 1.0 is reliably within year of completion. That won't be this year.

[rsc]

It sounds like maybe we do need to distinguish between the different wasi targets, at least until they get to 1.0. We don't want to have a GO$GOOS, so for now it seems like maybe separate GOOS are the answer. That would mean the initial version is GOOS=wasip1, then preview2 is GOOS=wasip2, and maybe finally 1.0 can be GOOS=wasi.

Do I have that right?

[rsc]

Based on the discussion above, this proposal seems like a likely accept.
— rsc for the proposal review group

[codefromthecrypt]

That would mean the initial version is GOOS=wasip1, then preview2 is GOOS=wasip2, and maybe finally 1.0 can be GOOS=wasi.

These sound reasonable! More notes as you can expect from me ;) hope they help.

---

I'm ok with status quo as wasip1 as opposed to its literal long name wasi_snapshot_preview1. I think people will be able to figure this out.

You will expect wasip1 to stay pretty much the same all the way until wasi, LTS. On the other hand, wasip2, wasip3.. may be incompatible with each other, but as it not LTS you may choose to drop the former tag when the next is out. For example, when preview 3 is released, GOOS=wasip1 works and GOOS=wasip3 works, but not wasip2 anymore as the tracking value would come at a cost, and also there's unlikely any vested interest in runtimes to support wasip2 either.

The wasip2..wasi line will track wasi-cli, which is their evolving entry point that has the same features as wasi_snapshot_preview1. For example, without this, you can't use ENV variables or anything. So I think working back from release notes, wasip2, wasip3.. will be updates around support of wasi-cli.

If any of these notes lead to different names, cool, if not, personally I'm fine and can help explain these to others.

[johanbrandhorst]

I've updated the proposal to use the GOOS=wasip1 name, and clarified that supporting newer syscall API versions would require a new GOOS. Thanks everyone for your input on this proposal.

[rsc]

No change in consensus, so accepted. 🎉
This issue now tracks the work of implementing the proposal.
— rsc for the proposal review group