WebAssembly Web API

Draft Community Group Report,

This version:
https://webassembly.github.io/spec/web-api/
Issue Tracking:
GitHub
Editor:
WebAssembly Community Group

Abstract

This document describes the integration of WebAssembly with the broader web platform.

This document builds off of the WebAssembly specification [WEBASSEMBLY] and the WebAssembly JavaScript embedding [WASMJS].

1. Streaming Module Compilation and Instantiation

partial namespace WebAssembly {
  Promise<Module> compileStreaming(Promise<Response> source);
  Promise<WebAssemblyInstantiatedSource> instantiateStreaming(
      Promise<Response> source, optional object importObject);
};
The compileStreaming(source) method, when invoked, returns the result of compiling a potential WebAssembly response with source.
The instantiateStreaming(source, importObject) method, when invoked, performs the following steps:
  1. Let promiseOfModule be the result of compiling a potential WebAssembly response with source.

  2. Return the result of instantiating the promise of a module promiseOfModule with imports importObject.

To compile a potential WebAssembly response with a promise of a Response source, perform the following steps:

Note: This algorithm accepts a Response object, or a promise for one, and compiles and instantiates the resulting bytes of the response. This compilation can be performed in the background and in a streaming manner. If the Response is not CORS-same-origin, does not represent an ok status, or does not match the `application/wasm` MIME type, the returned promise will be rejected with a TypeError; if compilation or instantiation fails, the returned promise will be rejected with a CompileError or other relevant error type, depending on the cause of failure.

  1. Let returnValue be a new promise

  2. Upon fulfillment of source with value unwrappedSource:

    1. Let response be unwrappedSource’s response.

    2. Let mimeType be the result of extracting a MIME type from response’s header list.

    3. If mimeType is not `application/wasm`, reject returnValue with a TypeError and abort these substeps.

    Note: extra parameters are not allowed, including the empty `application/wasm;`.

    1. If response is not CORS-same-origin, reject returnValue with a TypeError and abort these substeps.

    2. If response’s status is not an ok status, reject returnValue with a TypeError and abort these substeps.

    3. consume response’s body as an ArrayBuffer, and let bodyPromise be the result.

    Note: Although it is specified here that the response is consumed entirely before compilation proceeds, that is purely for ease of specification; implementations are likely to instead perform processing in a streaming fashion. The different is unobservable, and thus the simpler model is specified.

    1. Upon fulfillment of bodyPromise with value bodyArrayBuffer:

      1. Asynchronously compile the WebAssembly module bodyArrayBuffer with returnValue using the networking task source.

    2. Upon rejection of bodyPromise with reason reason:

      1. Reject returnValue with reason.

  3. Upon rejection of source with reason reason:

    1. Reject returnValue with reason.

  4. Return returnValue.

2. Developer-Facing Display Conventions

Browsers, JavaScript engines, and offline tools have common ways of referring to JavaScript artifacts and language constructs. For example, locations in JavaScript source code are printed in stack traces or error messages, and are represented naturally as decimal-format lines and columns in text files. Names of functions and variables are taken directly from the sources. Therefore (for example) even though the exact format of implementation-dependent stack trace strings does not always match, the locations are easily understandable and the same across browsers.

To achive the same goal of a common representations for WebAssembly constructs, the following conventions are adopted.

A WebAssembly location is a reference to a particular instruction in the binary, and may be displayed by a browser or engine in similar contexts as JavaScript source locations. It has the following format:

${url}:wasm-function[${funcIndex}]:${pcOffset}

Where

Notes:

While the "name" property of an Exported Function instance is specified by the [[WASMJS|JS API]], synthesized function names are also displayed in other contexts like call stacks in debuggers and string representations of stack traces. If a WebAssembly module contains a "name" section, these names should be used to synthesize a function name as follows:

Note that this document does not specify the full format of strings such as stack frame representations; this allows engines to continue using their existing formats for JavaScript (which existing code may already be depending on) while still printing WebAssembly frames in a format consistent with JavaScript.

Conformance

Conformance requirements are expressed with a combination of descriptive assertions and RFC 2119 terminology. The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in the normative parts of this document are to be interpreted as described in RFC 2119. However, for readability, these words do not appear in all uppercase letters in this specification.

All of the text of this specification is normative except sections explicitly marked as non-normative, examples, and notes. [RFC2119]

Examples in this specification are introduced with the words “for example” or are set apart from the normative text with class="example", like this:

This is an example of an informative example.

Informative notes begin with the word “Note” and are set apart from the normative text with class="note", like this:

Note, this is an informative note.

Index

Terms defined by this specification

Terms defined by reference

References

Normative References

[ECMA-262]
ECMAScript® 2018 Language Specification. Current Editor's Draft. URL: https://tc39.github.io/ecma262
[FETCH]
Anne van Kesteren. Fetch Standard. Living Standard. URL: https://fetch.spec.whatwg.org/
[HTML]
Anne van Kesteren; et al. HTML Standard. Living Standard. URL: https://html.spec.whatwg.org/multipage/
[PROMISES-GUIDE]
Domenic Denicola. Writing Promise-Using Specifications. 16 February 2016. Finding of the W3C TAG. URL: https://www.w3.org/2001/tag/doc/promises-guide
[RFC2119]
S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Best Current Practice. URL: https://tools.ietf.org/html/rfc2119
[WASMJS]
WebAssembly JS Integration Specification. Draft. URL: https://webassembly.github.io/spec/document/js-api/
[WEBASSEMBLY]
WebAssembly Specification. Draft. URL: https://webassembly.github.io/spec/
[WebIDL]
Cameron McCormack; Boris Zbarsky; Tobie Langel. Web IDL. 15 December 2016. ED. URL: https://heycam.github.io/webidl/

IDL Index

partial namespace WebAssembly {
  Promise<Module> compileStreaming(Promise<Response> source);
  Promise<WebAssemblyInstantiatedSource> instantiateStreaming(
      Promise<Response> source, optional object importObject);
};