├── README.md └── code-reuse.svg /README.md: -------------------------------------------------------------------------------- 1 | # System Essentials for WebAsssembly 2 | 3 | ## Introduction 4 | 5 | WebAssembly is sandboxed by design and does not have access to functionality other than what is supported by its instruction set or provided to it via imports. So typically, if there is functionality the host supports but WebAssembly doesn't, one would provide an appropriate import. On the Web, one would import a Web API, while off the Web, one would utilize an import namespace like WASI. 6 | 7 | However, some system features like obtaining the current time are essential to run basic (portable) WebAssembly modules both on and off the Web, and being able to access these features in a uniform way would help to battle fragmentation on an essential level that would otherwise require recompiling for different import namespaces or utilizing polyfills, which is generally good to avoid. 8 | 9 | Hence, this document explores a new set of essential `system.*` instructions, also addressing related concerns raised in discussions like [[1](https://github.com/WebAssembly/WASI/issues/401)] and [[2](https://github.com/WebAssembly/design/issues/1407)]. 10 | 11 | ## Motivation 12 | 13 | Code reuse on and off the Web is desirable for the long-term success of the broader WebAssembly ecosystem, and even though different environments may impose different requirements on system APIs, some system APIs are essential and already common among the Web and Non-Web, so providing these in a portable way makes individual components reusable across ecosystems: 14 | 15 |

16 | Code reuse 17 |

18 | 19 | In the diagram above, the example image encoder and cryptographic library only depend on core WebAssembly with System Essentials, so can be reused across ecosystems, in turn improving not only library consumer ergonomics, but also providing essential building blocks compiler and standard library authors can rely on. 20 | 21 | ## Instructions 22 | 23 | * `system.time_local` obtains the current local time in milliseconds since Unix epoch. 24 | * `system.time_local : [] -> [i64]` 25 | 26 | * `system.time_utc` obtains the current universal time in milliseconds since Unix epoch. 27 | * `system.time_utc : [] -> [i64]` 28 | 29 | * `system.timezoneoffset` obtains the timezone offset between local and universal time in minutes. 30 | * `system.timezoneoffset : [] -> [i32]` 31 | 32 | * `system.hrtime` obtains the system's monotonic high resolution time in nanoseconds since an arbitrary time in the past. 33 | * `system.hrtime : [] -> [i64]` 34 | 35 | * `system.random` obtains cryptographically secure random bytes and stores them to memory. 36 | * `system.random : [i32, i32] -> []` 37 | 38 | ## Potential extensions 39 | 40 | The following extensions are not feasible yet because they depend on future features such as Interface Types or may require further evaluation, but may become useful eventually: 41 | 42 | * `system.log` logs a message to the system console. 43 | * `system.log : [string] -> []` 44 | 45 | * Access to the system's IANA timezone database. 46 | 47 | ## Considerations 48 | 49 | The list of instructions is not exhaustive and does not imply that instructions not yet mentioned aren't desirable. However, all `system.*` instructions must be safe, as in not negatively affecting the host, other applications or their data. 50 | 51 | ## Use cases 52 | 53 | * Programs or libraries not specifically requiring Web or WASI APIs would not need additional non-portable imports in general, but are reusable by design. 54 | * Time(ing)-aware utility 55 | * Cryptographic utility 56 | * Debugging by printing to console 57 | * ... 58 | * Compilers and standard libraries could replace custom solutions with System Essentials / would not have to choose between Web and WASI APIs. 59 | * WASI applications could utilize System Essentials, reducing non-portable API surface, while also reducing polyfill overhead on the Web. For example, may only need to polyfill a file system. 60 | * Web applications could utilize System Essentials, reducing the need for separate glue code. For example, `system.timezoneoffset` cannot trivially be imported (requires `new`ing a `Date` object). 61 | -------------------------------------------------------------------------------- /code-reuse.svg: -------------------------------------------------------------------------------- 1 | 2 | 3 | --------------------------------------------------------------------------------