proposal: all: add wasip3/wasm port

[dicej]

Proposal Details

This proposes to add support for WASIp3, the next milestone of the WebAssembly System Interface (WASI), which is expected to be released in early 2026.

Background and Motivation

As of this writing, Go supports two GOOS values for GOARCH=wasm: js and wasip1. The former is meant for use in web browsers and standalone JS runtimes, while the latter is meant for standalone WebAssembly runtimes such as Wasmtime (although it can also be used in web browsers via a JS shim). GOOS=wasip1 targets the first milestone of WASI (known as Preview 1 or P1). Since that milestone was released, a second milestone, P2, has been released, and P3 is expected to arrive within the next few months. Here's a high-level summary of those milestones:

• P1: A shared-memory, POSIX-style interface based on the WITX IDL, with support for stdio, filesystem access, system clocks, environment variables, etc., plus extremely limited networking support.
• P2: A "shared-nothing"-style interface based on the WebAssembly Component Model, with support for all P1 features, plus complete TCP and UDP networking support, as well as high-level APIs for HTTP client and server applications.
• P3: A refinement of P2 designed around recently added concurrency support in the Component Model.

The Component Model foundation of P2 and P3 is notable for a few reasons:

• It provides a lightweight, "shared-nothing" mode of composition such that an application may be composed of multiple subcomponents, each with its own memory and capabilities, and each incapable of directly accessing the memory or capabilities of the others. This can be used to improve supply chain security by isolating third-party code from trusted first-party code.
• It makes polyglot composition much easier, allowing the developer to define custom, high-level APIs using WIT and generate bindings for a variety of programming languages -- similar to e.g. gRPC, but optimized for local invocations (and without the burden of dealing with distributed system concerns such as partial failures and network errors).
• P3 provides a composable concurrency model, allowing e.g. goroutines to call Python async functions and vice-versa, each using their native concurrency idioms to suspend and resume as appropriate.
• P2 and P3 components can be run in web browsers and standalone JS runtimes via jco. The P3 implemention in jco uses JSPI to provide concurrency without requiring an expensive CPS transformation such as the one Go currently uses to support goroutines and panics on Wasm targets.
• P3's concurrency support means it's the first WASI milestone to support idiomatic use of goroutines. Unlike with P1 and P2, a given goroutine can block on I/O, sleep, etc. without blocking other goroutines. This is possible with or without the CPS transformation mentioned above.

I and others have collaborated to develop a tool for generating Go bindings from WIT interfaces, plus a CLI utility which uses the former to generate bindings, run go build, and output a component which may be run on a P2- or P3-capable runtime such as Wasmtime or jco. Behind the scenes, that tool uses GOOS=wasip1 when compiling and then uses an adapter to transform the compiler output into component that targets P2.

However, that adapter has no way to interact with the Go scheduler, so if any goroutine calls a function in the Go standard library which bottoms out in a call to a P1 import such as poll_oneoff, it will block all goroutines. For the time being (i.e. until GOOS=wasip3 is supported), the only way to allow other goroutines to keep running is to generate and use P3 bindings directly, bypassing the standard library.

Proposal Details

I propose to add preliminary WASIp3 support in two steps:

Step 0

To start with, I propose to add a temporary runtime.wasiOnIdle function to allow the aforementioned wit-bindgen-go tool to bridge the concurrency support in the Component Model with the Go scheduler. This makes it possible to generate concurrency-aware import bindings so that a goroutine can e.g. block on I/O or sleep without blocking other goroutines. It also allows us to experiment with, gather feedback on, and refine Go WASIp3 support outside the Go project in preparation for Step 1, described below.

Note that we could skip this step if desired, in which case we can experiment using a temporary fork of the Go runtime which provides the extra function.

Step 1

Here we would add support for GOOS=wasip3 and make -buildmode=default produce a module which targets the wasi:cli/command world. This would include concurrency support such that e.g. I/O operations only block the calling goroutine, as well as full TCP/UDP networking support. This would be built around the current CPS transform used by the Go compiler to target Wasm, unwinding the Go stack and yielding control to the host as necessary to await I/O. Note that this would require a custom handling of the main function in the compiler and runtime in order to target the Component Model ABI for async function exports.

Future Steps

wasi:http

Here we would add a new implementation of the net/http client APIs which uses the high-level wasi:http interface instead of the low-level wasi:sockets interface, analogous to how js/wasm uses the JS fetch function.

At this point, we could also implement the relevant subset of the net/http server APIs in terms of the wasi:http/service world. Note that this would require a different mode of compilation than for the wasi:cli/command world since wasi:http/service exports a function which accepts an already-parsed HTTP request and returns a not-yet-serialized response, leaving the details of socket I/O, parsing, and serialization to the host.

Native stack switching

At some point, we'll want to ditch the compiler's CPS transform in favor of native host stack switching. This would simplify the compiler and dramatically improve performance.

The Component Model defines intrinsics for creating, yielding from, and resuming cooperative threads, which eliminates the need for a CPS transform. It also anticipates the WebAssembly stack-switching proposal by providing a subset of its features which can be implemented in today's web browsers using JSPI, whereas the stack-switching proposal itself is not yet widely implemented.

Once the compiler has been updated, we'll need to change how the GOOS=wasip3 port bridges Component Model concurrency with the Go scheduler, but this should a be fairly mechanical update and transparent to users.

WASI 1.0

Following WASIp3, the next expected release will be WASI 1.0, a stable release based on a correspondingly stable edition of the Component Model. The current plan is that 1.0 will be a subset of WASIp3, with certain redundant or obsolete features removed. That release would likely be supported in Go as GOOS=wasi, which could simply be an alias for GOOS=wasip3 once we've removed any use of features not in 1.0.

Fun Example

This example demonstrates how to target the wasi:http@0.3.0-rc-2025-09-16 interface in Go using wit-bindgen-go and a lightly patched version of the Go runtime. It exports a function which may be called concurrently by the host, accepting requests and making one or more concurrent outgoing requests. Note that it uses the wasi:http interface directly since net/http has not yet been ported.

[gabyhelp]

Related Issues

• all: add GOOS=wasip1 GOARCH=wasm port #58141 (closed)
• all: add GOOS=wasip2 port #65333
• wasm: support new WASI interface #31105 (closed)
• wasi: net implement sockets #67673 (closed)
• cmd/compile: replace CallImport with go:wasmimport directive #38248 (closed)
• cmd/compile: allow the use of go:wasmimport globally #59149 (closed)
• cmd/compile: create GOARCH=wasm32 #63131

Related Code Changes

• runtime: add a runtime.wasiOnIdle function

Related Documentation

• WASI support in Go > The WebAssembly System Interface

_{(Emoji vote if this was helpful or unhelpful; more detailed feedback welcome in this discussion.)}

[prattmic]

cc @golang/wasm @golang/runtime

[johanbrandhorst]

Thanks for creating this proposal! I'm really excited about WASI 0.3 (AKA wasip3). I appreciate all the thought that went into this proposal. Something we identified with the wasip2 proposal is that there appears to be something of a lack of appetite from the Wasm runtime ecosystem at large to adopt WASI 0.2 and the component model. Do you expect this to change with WASI 0.3? Do you know of any runtimes than Wasmtime that are working on implementing support for WASI 0.2 or 0.3? As much as wasip1 is a bit of a sad state, at least there is almost universal runtime support for it.

Another question is how this relates to the accepted proposal to create a wasm32 architecture. One of the major goals of wasm32 is the performance advantage offered by 32bit binaries. In my head we'd want to get that done before we implement any new GOOS's, but the effort has stalled in implementation. How do you see this relating to wasm32? How are you currently dealing with the 64 bit pointers?

[dicej]

Great questions, @johanbrandhorst. Regarding runtime adoption of p2, p3, and the component model, here are the projects I'm aware of currently:

• Wasmtime: full p1, p2, and p3 support
• JCO: full p1 (via an adapter) and p2 support on NodeJS
  • can also be used in all modern browsers, modulo awkward stuff like emulating certain network features
  • p3 support is mostly complete and should wrap up soon
• WasmEdge tracking issue for p2
• Mozilla's most recent CG presentation indicates they're looking into native CM support (i.e. without requiring JCO) for Firefox
• Chrome recently filed an issue to evaluate CM support which recommends JCO
• Arcjet's Gravity allows running components on wazero today by adapting the JCO approach to Go
• Folks working on WAMR are actively talking about adapting the JCO/Gravity approach to run components on WAMR, and possibly starting a common shared tool to make this easy to do this more generically on top of any core wasm engine

So momentum is looking pretty good so far. I expect that we'll see the same pattern for p2 and p3 as we did for p1: as more runtimes support them, more developer tools (e.g. compilers, interpreters, and runtimes) will gain support, which will encourage more runtime support, etc.

As I mentioned above, 0.3 is the last 0.x release. 1.0 will be subset of 0.3, with only incremental, non-breaking improvements coming afterward. It will provide a stable target for runtimes, toolchains, and libraries to support long-term, without the rather severe limitations of 0.1. Also note that nothing in this proposal removes or replaces GOOS=wasip1; that can stick around for as long as it remains relevant.

Regarding GOARCH=wasm32: I agree that's a worthwhile effort and will definitely reduce memory usage and improve locality-of-reference for pointer-heavy data structures. It will also simplify and speed up the conversion between Go objects and their CM representations. However, I also expect that eliminating the compiler's CPS transform will improve performance to a much greater degree. The good news is that GOOS=wasip3 support will benefit from -- but need not rely on -- either or both of those things.

For the time being, the conversion between Go data types and their CM equivalents involves zero-extending or truncating pointers, respectively, which we can rely on being lossless since wasm32 modules can't have memories larger than 4GiB. Eliminating that step will be great, but it's not a huge cost to pay in the meantime. Also note that, even once we have GOARCH=wasm32, there will still be per-pointer overhead when converting between Go and CM representations, given that each pointer we pass across a component boundary must be pinned using runtime.Pinner for GC safety in most cases, just like when doing any other kind of FFI.

[johanbrandhorst]

Thanks for the comprehensive response. It is very interesting to see that the ecosystem is evaulating components, but I do think we'll want to see at least one independent implementation other than Wasmtime before it would be appropriate to include this in Go. I don't know exactly the relationship between Wasmtime and WAMR, but they appear to both be part of Bytecode Alliance? If either Chrome or Firefox decide to ship something WASI-based (not necessarily stable) that would also be a great step forward.

That said, there's still lots of experimentation we can do, and please do continue to iterate on these ideas. Personally I'd prefer we view the milestones from the point of view of the user. I'm a little confused by the idea of supporting a "wasip3" with feature parity of "wasip1". Do we expect the implementation of wasip3 to be as extensive as to take longer than 6 months (from freeze to freeze)? I'd prefer we implement the full wasip3 interface than ship something half-finished, but if this is something commonly done with the component model I could be convinced.

I'm also a little concerned by the idea of adding support for wasip3 with a future view to removing API. Should we just wait for WASI 1.0 in that case? On the one hand, it would be annoying to have to support a wasip3 API that is more extensive than most users need, but on the other hand, it would be bad to break users by removing API after shipping.

[tschneidereit]

I don't know exactly the relationship between Wasmtime and WAMR, but they appear to both be part of Bytecode Alliance?

While that is correct, the implementations are nevertheless fully independent of each other, and share neither code nor implementers (nor even the implementation language.)

What's more, in addition to the approach Joel described, there's an independent effort underway at Airbus Defence and Space, which will to my understanding not use the JCO approach, but provide a full alternative implementation.

I'd prefer we implement the full wasip3 interface than ship something half-finished

I agree with this, to the degree a "full" implementation is meaningful. WASI is structured as a collection of APIs, none of which are required to be available in a conforming host environment—they just need to be implemented in a compliant manner if they are available. To still give toolchain vendors and content authors useful environments to target, WASI (or the component model, rather) introduces the concept of "worlds" as a defined collection of APIs. A conforming implementation advertising itself as implementing a specific world must implement all contained APIs.

I think what Joel was getting at with p1 parity is, roughly speaking, to target the CLI world. We could however merge steps 1 and 2, I think, but listen to Joel over me on that :)

I'm also a little concerned by the idea of adding support for wasip3 with a future view to removing API. Should we just wait for WASI 1.0 in that case? On the one hand, it would be annoying to have to support a wasip3 API that is more extensive than most users need, but on the other hand, it would be bad to break users by removing API after shipping.

Ideally, all toolchains would be able to just hold off until WASI 1.0 is done and published, yes. Unfortunately that would leave us in a bit of a pickle, where we couldn't get a 1.0 that would have thorough real-world vetting and can be trusted to stay stable for years and decades to come—which is what we think is fundamentally needed.

The way we're aiming to square that circle is, at a very high level, by eventually "carving" 1.0 out of p3: we're at a point where we're very confident that p3 is the right basis for incremental, and purely additive, improvements to both the ABI and the API. (Where "additive" on the ABI level means making use of the existing Canonical Options mechanism to introduce ABI changes that can coexist with the current ABI.) Working with the ecosystem and in particular toolchain vendors and runtime implementers such as browser vendors, the aim is to eventually identify which of these options should be included in 1.0, and which ones should be left behind. All the while, runtime vendors can continue working on a single implementation that will eventually be able to run both p3 and 1.0 content. Toolchain vendors will be able to incrementally make use of more features as target environments deploy them.

A final important consideration is that the kind of feature removal that's even on the table shouldn't really affect higher-level APIs as provided by Go's standard library. @dicej please correct me if you disagree, but I think we can be confident in being able to maintain source compatibility at that level through the eventual migration from p3 to 1.0.

And speaking for Wasmtime and JCO, we're committed to maintain p3 support indefinitely and for as long as required. We are comfortable with making this commitment because we don't anticipate it being a major maintenance burden.

I appreciate that none of this directly answers your question of what Go should do here, but I hope it provides useful context. I know that there is demand for a Go toolchain targeting components, and on the runtime side we think we're able to provide the right stability now, and can make the right maintenance commitments. Whether that combination outweighs the downside of probably eventually (years in the future) wanting to remove the p3 target is of course a different question that I can't really answer. But we're move than happy to engage on any and all of this and can look into changing aspects that would block this proposal!

[dicej]

Just to add a bit more context to what Till said:

I think what Joel was getting at with p1 parity is, roughly speaking, to target the CLI world. We could however merge steps 1 and 2, I think, but listen to Joel over me on that :)

Yes, combining steps 1 and 2 would be totally fine. I separated them as a way to break things up into incremental milestones, but I'm always open to combining steps or splitting them differently as appropriate.

A final important consideration is that the kind of feature removal that's even on the table shouldn't really affect higher-level APIs as provided by Go's standard library. @dicej please correct me if you disagree, but I think we can be confident in being able to maintain source compatibility at that level through the eventual migration from p3 to 1.0.

Yes, exactly. Our approach to p3 has been to add new ABI and API features (based on implementation experience and feedback) which sometimes overlap partly or entirely with existing features, but keep those existing features intact to avoid breaking existing binaries and forcing developers to rebuild them using a newer toolchain. That means there will sometimes be more than one way to express the same thing in p3.

For 1.0, we plan to prune the redundant ABI and (syscall-level) API features from p3. Consequently, developers who are content to stick with p3 need not do anything, and developers looking to migrate from p3 to 1.0 should at most need to rebuild their binaries from source using a newer toolchain -- no source code changes required. Alternatively, they might not even need to rebuild from source, since we plan to provide a binary shim that emulates p3 features in terms of the 1.0 features.

[johanbrandhorst]

Thanks for that additional context Joel and Till, that is really helpful. It sounds like from a users point of view the "removal" of API is should have minimal, if any, impact, which is good enough for me. Regarding implementing the "CLI world" that sounds like a reasonable target for phase 1 too. What that in mind, what "world(s)" are we talking about with phase 2? Building support for the Go HTTP stack (at least client side?) on top of "wasi:http" sounds very interesting too, similar to how js/wasm uses the fetch API for its client HTTP side. If we're talking a phased implementation in terms of "worlds" that we can support for users, could you update the proposal to reflect that? While the under-the-hood details are important for the implementation, the biggest impact to our users will be in what we can allow them to do throug the APIs. Thanks! We can still have a phase 3 that's essentially "no user impact except better performance", but it could also maybe be a separate proposal?

[dicej]

What that in mind, what "world(s)" are we talking about with phase 2? Building support for the Go HTTP stack (at least client side?) on top of "wasi:http" sounds very interesting too, similar to how js/wasm uses the fetch API for its client HTTP side.

Yeah, that's the idea. I did the same thing for .NET's System.Net.Http.Client, and it was pretty easy since they already had a nice internal abstraction which supported both a TCP-socket-based implementation and a fetch-based implementation. I added a third, wasi:http-based implementation and made that the default, but also verified that the socket-based implementation worked on WASI in case the app developer wanted to use that instead.

Regarding the server APIs in net/http: the existing sockets-based implementation should work fine when targeting wasi:cli/command world, which matches the usual Go execution model where the guest picks a port to listen on, accepts connections, parses requests, serializes responses, etc. The wasi:http/service world operates at a higher level of abstraction, leaving the host to bind, listen, accept, parse, and serialize, only invoking the guest on a per-request basis. In both cases, the app developer would use e.g. http.Handle to initialize http.DefaultServeMux, but e.g. http.ListenAndServe would only be relevant when targeting the wasi:cli/command world. I'm not sure how the user would specify which of those worlds to target; perhaps we could add e.g. a -buildmode=wasi-http option?

More generally, a user might want to target a non-WASI world, e.g. one they defined themselves or one specified by a third party (e.g. a plugin system API). That works today using wit-bindgen-go, but we could also consider teaching the Go compiler to do the same thing itself, e.g. expanding the capabilities of //go:wasmimport and //go:wasmexport to marshaling high-level data types like structs, lists, strings, etc., as well as handle the details of bridging the Go and CM concurrency models. That would presumably be a separate phase (or separate proposal), though.

If we're talking a phased implementation in terms of "worlds" that we can support for users, could you update the proposal to reflect that?

I wasn't originally thinking of it that way, but I agree that could make sense. Does the -buildmode=wasi-http idea I mentioned above sound reasonable? If so I can update the proposal and say e.g. stage 1 covers -buildmode=exe, (i.e. wasi:cli/command, including full networking support), while stage 2 covers -buildmode=wasi-http (i.e. wasi:http/service), plus wasi:http-based net/http client support in addition to the was:socket-based net/http support enabled by stage 1.

We can still have a phase 3 that's essentially "no user impact except better performance", but it could also maybe be a separate proposal?

Sounds good to me.

[johanbrandhorst]

I'm not sure about the use of buildmode flags to switch behavior of the compiler, generally that has not been the approach where possible (e.g. we reused buildmode=c-shared for go:wasmexport, and that was only because it changes the normal func main-based application execution and runtime initialization flow entirely). I'm not yet sure what the best way to allow a user to switch between wasi:cli and wasi:http would be, but fortunately it sounds like we don't need to answer that question if we're just targeting wasi:cli to start with. If the default behavior for wasip3/wasm is to target wasi:cli (which sounds pretty similar to the syscall interface we have for other OSs), we can figure out what compile time options we have when/if we want to add support for targeting wasi:http in the future. Does that make sense?

[dicej]

Sounds good to me. I've updated the proposal to move step 3 to the Future Steps section and reworded steps 1 and 2 based on this discussion. Please let me know what you think.

[johanbrandhorst]

Thanks for the update, do you mind moving step 2 to Future Work as well for now? The user impact from the progression from wasip3-on-cli to wasip3-on-cli-and-http is not clear to me yet and I think we could speed up this proposal by narrowing it to just "support the wasi:cli/command world and component model under wasip3/wasm". What do you think?