Add support for named imports to WASI implementations - #14275
Open
alexcrichton wants to merge 2 commits into
Open
Add support for named imports to WASI implementations#14275alexcrichton wants to merge 2 commits into
alexcrichton wants to merge 2 commits into
Conversation
This commit is at least an initial stab at making the `wasmtime-wasi` and `wasmtime-wasi-http` crates compatible with "named imports" or the `implements` field in the component model. This field enables importing an interface under a kebab-name while annotating that it's additionally to be considered an import of another interface's name. One example use case for this feature is [dependency isolation][diso] when composing two components together -- if they both import the filesystem the final component will import the filesystem twice under two different kebab names which means both components can have a different view of the filesystem. Wasmtime previously gained support for named imports and `implements` in `bindgen!` as part of bytecodealliance#13513 where the `named_imports` option can be specified at `bindgen!`-time which generates traits that take an extra id-style parameter. This runtime parameter indicates which kebab-name is being invoked through which the runtime can then dispatch on. The goal here is to actually wire all this up in a way that's usable for embedders. Specifically `named_imports` bindings generation is now available for all WASIp2 and WASIp3 interfaces. Additionally all implementations of these `id`-carrying traits are routed through the previous implementations after locating the correct context to operate over. All implementations of WASI functionality are already modeled more-or-less as methods on `Wasi*CtxView`-style types which internally have a borrow to the actual state and the resource table to operate on. This fits quite cleanly with named imports where conceptually what we want is the ability to configure the context-per-kebab-name. This in theory will keep the maintenance burden managable as there's still largely one source of truth for the implementation. This neatly works for all `Host`-style traits which are literally methods on `Wasi*CtxView` types, meaning the `id`-carrying versions actually do just acquire a `Wasi*CtxView` and then delegate the method. This requires more finesse for `*WithStore` traits which work with `Access` and `Accessor`, however. The `id` parameter cannot be threaded into the `fn(..)` within the `Accessor`, so refactoring is performed where appropriate to make the implementation of each interface a one-liner to reduce duplication. The end result of all of this is that this is a very large commit but it's written in such a way that the Rust compiler in theory should catch all mistakes. In other words we're heavily relying on the type system and type checking here and don't ever rely on duplication of methods that hopefully-won't-change. There's a lot of traits and a lot of interfaces, hence the size of the commit, but conceptually everything is intended to be pretty simple. Some design decisions as part of this commit, in no particular order: * IDs are represented by `wasmtime_wasi::NamedId` which is a newtype-wrapper around `usize`. The goal here is to enable an efficient implementation of dealing with ids. This notably forces the embedder to derive some sort of string-to-id (and perhaps back) map when adding items to a linker. * All of this is opt-in and nothing is changed by default. For example the `wasmtime` CLI does not support any of this yet -- in theory that would require the ability to configure `-S` flags per-named-import as opposed to all-at-once. * Mapping a `NamedId` to a context is abstracted behind a trait rather than dictating that a `Vec` or `HashMap` or similar is required. This increases the cognitive load when reading code (more generics), but avoids making this design decision within these crates and leaves exact representations up to embedders. * The `HasData` implementation can't reuse the preexisting `WasiCli`, and this uses a new `WasiCliNamed<T>` instead. This enables threading this trait-to-find-a-context to the right location for `*WithStore` trait impls. * Some miscellaneous `bindgen!` issues have been fixed during this commit to ensure that this compiles and works correctly. * An attempt has been made at documenting all the new primitives/structs/etc here. These are sort of difficult to align correctly unless you know what you're doing, so the documentation and examples are intended to serve as a way of spreading this knowledge. * One possible alternative I ended up deciding not to do was to put some sort of map-to-context storage within each preexisting context type. For example commit would be simpler for the `*WithStore` and infrastructure if it reused the exact same `Self` type as all other impls do. My thinking though is that this requires dictating the use of a `HashMap` or something else which I was hoping to avoid. Additionally the preexisting context structures are already minimal enough that they're basically what you already want as the source for each implementation, so I wanted to lean on them as much as possible. * The main wrinkle in the new implementation is that `Accessor` carries `fn(..)` to project out it's `D::Data<'_>` which means that it can't close over any information. This feature needs to in theory close over an `id: NamedId`, however, and there's no easy way to put this square peg into a round hole. To work around this internal implementations within `wasmtime-wasi{,-http}` now have a generic `F` parameter which is a closure which projects data, but this closure is typically only ever on the stack and doesn't make its way to the heap. This was one of the more awkward things to work around in this commit. * The design here is intentionally done to help ensure that this commit is correct with minimal testing. It's not really feasible to duplicate the entire test suite just for named imports but these are duplicate trait impls which otherwise shouldn't be wrong. By ensuring that there's either strict delegation or each-function-is-at-least-one-line that the light amount of testing here is sufficient for keeping this working over time. [diso]: spinframework/spin#3708
alexcrichton
requested review from
pchickey and
rvolosatovs
and removed request for
a team
September 3, 2026 21:44
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This commit is at least an initial stab at making the
wasmtime-wasiandwasmtime-wasi-httpcrates compatible with "named imports" or theimplementsfield in the component model. This field enables importing an interface under a kebab-name while annotating that it's additionally to be considered an import of another interface's name. One example use case for this feature is dependency isolation when composing two components together -- if they both import the filesystem the final component will import the filesystem twice under two different kebab names which means both components can have a different view of the filesystem.Wasmtime previously gained support for named imports and
implementsinbindgen!as part of #13513 where thenamed_importsoption can be specified atbindgen!-time which generates traits that take an extra id-style parameter. This runtime parameter indicates which kebab-name is being invoked through which the runtime can then dispatch on.The goal here is to actually wire all this up in a way that's usable for embedders. Specifically
named_importsbindings generation is now available for all WASIp2 and WASIp3 interfaces. Additionally all implementations of theseid-carrying traits are routed through the previous implementations after locating the correct context to operate over.All implementations of WASI functionality are already modeled more-or-less as methods on
Wasi*CtxView-style types which internally have a borrow to the actual state and the resource table to operate on. This fits quite cleanly with named imports where conceptually what we want is the ability to configure the context-per-kebab-name. This in theory will keep the maintenance burden managable as there's still largely one source of truth for the implementation. This neatly works for allHost-style traits which are literally methods onWasi*CtxViewtypes, meaning theid-carrying versions actually do just acquire aWasi*CtxViewand then delegate the method. This requires more finesse for*WithStoretraits which work withAccessandAccessor, however. Theidparameter cannot be threaded into thefn(..)within theAccessor, so refactoring is performed where appropriate to make the implementation of each interface a one-liner to reduce duplication.The end result of all of this is that this is a very large commit but it's written in such a way that the Rust compiler in theory should catch all mistakes. In other words we're heavily relying on the type system and type checking here and don't ever rely on duplication of methods that hopefully-won't-change. There's a lot of traits and a lot of interfaces, hence the size of the commit, but conceptually everything is intended to be pretty simple.
Some design decisions as part of this commit, in no particular order:
IDs are represented by
wasmtime_wasi::NamedIdwhich is a newtype-wrapper aroundusize. The goal here is to enable an efficient implementation of dealing with ids. This notably forces the embedder to derive some sort of string-to-id (and perhaps back) map when adding items to a linker.All of this is opt-in and nothing is changed by default. For example the
wasmtimeCLI does not support any of this yet -- in theory that would require the ability to configure-Sflags per-named-import as opposed to all-at-once.Mapping a
NamedIdto a context is abstracted behind a trait rather than dictating that aVecorHashMapor similar is required. This increases the cognitive load when reading code (more generics), but avoids making this design decision within these crates and leaves exact representations up to embedders.The
HasDataimplementation can't reuse the preexistingWasiCli, and this uses a newWasiCliNamed<T>instead. This enables threading this trait-to-find-a-context to the right location for*WithStoretrait impls.Some miscellaneous
bindgen!issues have been fixed during this commit to ensure that this compiles and works correctly.An attempt has been made at documenting all the new primitives/structs/etc here. These are sort of difficult to align correctly unless you know what you're doing, so the documentation and examples are intended to serve as a way of spreading this knowledge.
One possible alternative I ended up deciding not to do was to put some sort of map-to-context storage within each preexisting context type. For example commit would be simpler for the
*WithStoreand infrastructure if it reused the exact sameSelftype as all other impls do. My thinking though is that this requires dictating the use of aHashMapor something else which I was hoping to avoid. Additionally the preexisting context structures are already minimal enough that they're basically what you already want as the source for each implementation, so I wanted to lean on them as much as possible.The main wrinkle in the new implementation is that
Accessorcarriesfn(..)to project out it'sD::Data<'_>which means that it can't close over any information. This feature needs to in theory close over anid: NamedId, however, and there's no easy way to put this square peg into a round hole. To work around this internal implementations withinwasmtime-wasi{,-http}now have a genericFparameter which is a closure which projects data, but this closure is typically only ever on the stack and doesn't make its way to the heap. This was one of the more awkward things to work around in this commit.The design here is intentionally done to help ensure that this commit is correct with minimal testing. It's not really feasible to duplicate the entire test suite just for named imports but these are duplicate trait impls which otherwise shouldn't be wrong. By ensuring that there's either strict delegation or each-function-is-at-least-one-line that the light amount of testing here is sufficient for keeping this working over time.