|
4 | 4 |
|
5 | 5 |  |
6 | 6 |
|
7 | | -This repository is for the WebAssembly System Interface (WASI) Subgroup of the |
8 | | -[WebAssembly Community Group]. It includes: |
9 | | - - [charter]: describes the goals, scope and deliverables of the group |
10 | | - - [docs]: learn more about WASI |
11 | | - - [meetings]: schedules and agendas for video conference and in-person meetings |
12 | | - - [phases]: the current WASI specifications |
13 | | - - [proposals]: the status of each new specification proposal |
14 | | - |
15 | | -[charter]: Charter.md |
16 | | -[docs]: docs/README.md |
17 | | -[meetings]: https://github.com/WebAssembly/meetings/tree/master/wasi |
18 | | -[phases]: phases/README.md |
19 | | -[proposals]: docs/Proposals.md |
20 | | -[WebAssembly Community Group]: https://www.w3.org/community/webassembly/ |
21 | | - |
22 | | -### Contributing |
23 | | - |
24 | | -The [issue tracker] is the place to ask questions, make suggestions, and start discussions. |
25 | | - |
26 | | -[issue tracker]: https://github.com/WebAssembly/WASI/issues |
| 7 | +The WebAssembly System Interface is not a monolithic standard system interface, |
| 8 | +but is instead a modular collection of standardized APIs. None of the APIs are |
| 9 | +required to be implemented to have a compliant runtime. Instead, host |
| 10 | +environments can choose which APIs make sense for their use cases. |
| 11 | + |
| 12 | +--- |
| 13 | +## Important Note: WASI is in transition |
| 14 | + |
| 15 | +WASI is transitioning away from the `witx` format and its early experimental ABI. We are transitioning to Interface Types using the `wit` format and the canonical ABI. |
| 16 | + |
| 17 | +All new API proposals should use the new format and the new repo structure that is shown in the [proposal template](https://github.com/WebAssembly/wasi-proposal-template). |
| 18 | + |
| 19 | +Some APIs can not yet be supported in the `wit` format. The advancement of these proposals will be unblocked with work that is ongoing: |
| 20 | + |
| 21 | +- Proposals that require async/streams are expected to be unblocked in early Q2 2022 |
| 22 | +- Proposals that depend on libc are expected to be unblocked by work in `wasi-libc` and elsewhere. Until then, implementers of these APIs should continue to use the snapshots in this repo, which use the `witx` format. We will provide updates on the progress of this work in the bi-weekly meetings. |
| 23 | + |
| 24 | +--- |
| 25 | + |
| 26 | +## Find the APIs |
| 27 | + |
| 28 | +Development of each API happens in its own repo, which you can access |
| 29 | +from the [proposals list](Proposals.md). |
| 30 | + |
| 31 | +This repo is for general discussion, as well as documenting how we work |
| 32 | +and high-level goals. |
| 33 | + |
| 34 | +## Propose a new API |
| 35 | + |
| 36 | +If you would like to create a new proposal, get started with our |
| 37 | +[Contributing guide](Contributing.md). |
| 38 | + |
| 39 | +## WASI High Level Goals |
| 40 | + |
| 41 | +(In the spirit of [WebAssembly's High-Level Goals] |
| 42 | +(https://github.com/WebAssembly/design/blob/master/HighLevelGoals.md).) |
| 43 | + |
| 44 | +1. Define a set of portable, modular, runtime-independent, and |
| 45 | + WebAssembly-native APIs which can be used by WebAssembly code to interact |
| 46 | + with the outside world. These APIs preserve essential sandboxed nature of |
| 47 | + WebAssembly through a [Capability-based] API design. |
| 48 | +2. Specify and implement incrementally. Start with a Minimum Viable Product |
| 49 | + (MVP), then adding additional features, prioritized by feedback and |
| 50 | + experience. |
| 51 | +3. Supplement API designs with documentation and tests, and, when feasible, |
| 52 | + reference implementations which can be shared between wasm engines. |
| 53 | +4. Make a great platform: |
| 54 | + * Work with WebAssembly tool and library authors to help them provide |
| 55 | + WASI support for their users. |
| 56 | + * When being WebAssembly-native means the platform isn't directly |
| 57 | + compatible with existing applications written for other platforms, |
| 58 | + design to enable compatibility to be provided by tools and libraries. |
| 59 | + * Allow the overall API to evolve over time; to make changes to API |
| 60 | + modules that have been standardized, build implementations of them |
| 61 | + using libraries on top of new API modules to provide compatibility. |
| 62 | + |
| 63 | +[Capability-based]: https://en.wikipedia.org/wiki/Capability-based_security |
| 64 | + |
| 65 | +## WASI Design Principles |
| 66 | + |
| 67 | +### Capability-based security |
| 68 | + |
| 69 | +WASI is built using capability-based security principles. Access to |
| 70 | +external resources is always represented by *handles*, which are special |
| 71 | +values that are *unforgeable*, meaning there's no way to coerce an |
| 72 | +arbitrary integer or other type of value into a handle. WASI is also |
| 73 | +aiming to have no *ambient authorities*, meaning that there should |
| 74 | +be no way to request a handle purely by providing a string or other |
| 75 | +user-controlled identifier providing the name of a resource. With these |
| 76 | +two properties, the only ways to obtain access to resources are to be |
| 77 | +explicitly given handles, or to perform operations on handles which |
| 78 | +return new handles. |
| 79 | + |
| 80 | +Note that this is a different sense of "capability" than [Linux |
| 81 | +capabilities](http://man7.org/linux/man-pages/man7/capabilities.7.html) |
| 82 | +or the withdrawn [POSIX |
| 83 | +capabilities](https://archive.org/details/posix_1003.1e-990310), which |
| 84 | +are per-process rather than per-resource. |
| 85 | + |
| 86 | +The simplest representation of handles are values of [reference |
| 87 | +type](https://github.com/WebAssembly/reference-types). References in |
| 88 | +wasm are inherently unforgeable, so they can represent handles directly. |
| 89 | + |
| 90 | +Some programming languages operate primarily within linear memory, |
| 91 | +such as C, C++, and Rust, and there currently is no easy way for |
| 92 | +these languages to use references in normal code. And even if it does |
| 93 | +become possible, it's likely that source code will still require |
| 94 | +annotations to fully opt into references, so it won't always be |
| 95 | +feasible to use. For these languages, references are stored in a |
| 96 | +[table](https://webassembly.github.io/spec/core/bikeshed/index.html#tables%E2%91%A0) |
| 97 | +called a *c-list*. Integer indices into the table then identify |
| 98 | +resources, which can be easily passed around or stored in memory. In |
| 99 | +some contexts, these indices are called *file descriptors* since they're |
| 100 | +similar to what POSIX uses that term for. There are even some tools, |
| 101 | +such as wasm-bindgen, which make this fairly easy. (Internally, tools |
| 102 | +and engines don't always use actual WebAssembly tables to do this, |
| 103 | +however those are implementation details. Conceptually, they work as if |
| 104 | +they had tables.) |
| 105 | + |
| 106 | +Integer indices are themselves forgeable, however a program can only |
| 107 | +access handles within the c-list it has access to, so isolation can still |
| 108 | +be achieved, even between libraries which internally use integer indices, |
| 109 | +by witholding access to each library's c-list to the other libraries. |
| 110 | +Instances can be given access to some c-lists and not others, or even |
| 111 | +no c-lists at all, so it's still possible to establish isolation between |
| 112 | +instances. |
| 113 | + |
| 114 | +Witx-specified APIs use a special `handle` keyword to mark parameters |
| 115 | +and return values which are handles. In the short term, these are |
| 116 | +lowered to integer indices, with an implied table, so that the APIs |
| 117 | +can be easily used from C and similar languages today. Once [interface |
| 118 | +types](https://github.com/WebAssembly/interface-types) is |
| 119 | +ready, we expect to make use of them to provide APIs which can be used |
| 120 | +either from languages using references or from languages using integer |
| 121 | +indices, with tables being used and managed automatically. |
| 122 | + |
| 123 | +### Interposition |
| 124 | + |
| 125 | +Interposition in the context of WASI interfaces is the ability for a |
| 126 | +Webassembly instance to implement a given WASI interface, and for a |
| 127 | +consumer WebAssembly instance to be able to use this implementation |
| 128 | +transparently. This can be used to adapt or attenuate the functionality |
| 129 | +of a WASI API without changing the code using it. |
| 130 | + |
| 131 | +In WASI, we envision interposition will primarily be configured |
| 132 | +through the mechanisms in the module linking' [link-time virtualization |
| 133 | +](https://github.com/WebAssembly/module-linking/blob/master/proposals/module-linking/Explainer.md#link-time-virtualization). |
| 134 | +Imports are resolved when a module is instantiated, which may happen |
| 135 | +during the runtime of a larger logical application, so we can support |
| 136 | +interposition of WASI APIs without defining them in terms of explicit |
| 137 | +dynamic dispatch mechanisms. |
| 138 | + |
| 139 | +Interposition is sometimes referred to as "virtualization", however we |
| 140 | +use "interposition" here because the word "virtualization" has several |
| 141 | +related meanings. |
| 142 | + |
| 143 | +### Compatibility |
| 144 | + |
| 145 | +Compatibility with existing applications and libraries, as well as |
| 146 | +existing host platforms, is important, but will sometimes be in conflict |
| 147 | +with overall API cleanliness, safety, performance, or portability. |
| 148 | +Where practical, WASI seeks to keep the WASI API itself free of |
| 149 | +compatibility concerns, and provides compatibility through libraries, |
| 150 | +such as WASI libc, and tools. This way, applications which don't require |
| 151 | +compatibility for compatibility' sake aren't burdened by it. |
| 152 | + |
| 153 | +### Portability |
| 154 | + |
| 155 | +Portability is important to WASI, however the meaning of portability |
| 156 | +will be specific to each API. |
| 157 | + |
| 158 | +WASI's modular nature means that engines don't need to implement every |
| 159 | +API in WASI, so we don't need to exclude APIs just because some host |
| 160 | +environments can't implement them. We prefer APIs which can run across |
| 161 | +a wide variety of engines when feasible, but we'll ultimately decide |
| 162 | +whether something is "portable enough" on an API-by-API basis. |
0 commit comments