Web Embedding

Unsurprisingly, one of WebAssembly’s primary purposes is to run on the Web, for example embedded in Web browsers (though this is not its only purpose).

This means integrating with the Web ecosystem, leveraging Web APIs, supporting the Web’s security model, preserving the Web’s portability, and designing in room for evolutionary development. Many of these goals are clearly reflected in WebAssembly’s high-level goals. In particular, WebAssembly MVP will be no looser from a security point of view than if the module was JavaScript.

More concretely, the following is a list of points of contact between WebAssembly and the rest of the Web platform that have been considered:

JavaScript API

A JavaScript API is provided which allows JavaScript to compile WebAssembly modules, perform limited reflection on compiled modules, store and retrieve compiled modules from offline storage, instantiate compiled modules with JavaScript imports, call the exported functions of instantiated modules, alias the exported memory of instantiated modules, etc.

The Web embedding includes additional methods useful in that context. In non-web embeddings, these APIs may not be present.

Additional Web Embedding API

In Web embeddings, the following methods are added.

Note that it is expected that compileStreaming and instantiateStreaming be either both present or both absent.

WebAssembly.compileStreaming

:cyclone: Added for milestone 2, developers must feature detect.

Promise<WebAssembly.Module> compileStreaming(source)

This function accepts a Response object, or a promise for one, and compiles 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 fails, the returned promise will be rejected with a WebAssembly.CompileError.

  1. Return the result of processing a potential WebAssembly response, given source, with the following steps:
    • Processing steps, given bytes:
      1. Compile bytes, in the same fashion as specified for the WebAssembly.Module constructor.
      2. If compilation completes successfully, return a success with the validated Ast.module compilation result.
      3. Otherwise, if compilation fails, return a failure with the failure reason.
    • Success steps, given module
      1. Return a new WebAssembly.Module instance, with its [[Module]] set to module.
    • Failure steps, given reason
      1. Return a new WebAssembly.CompileError containing the compilation failure information stored in reason.

WebAssembly.instantiateStreaming

:cyclone: Added for milestone 2, developers must feature detect.

dictionary WebAssemblyInstantiatedSource {
   required WebAssembly.Module module;
   required WebAssembly.Instance instance;
};

Promise<InstantiatedSource> instantiateStreaming(source [, importObject])

This function 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 WebAssembly.CompileError, WebAssembly.LinkError, or WebAssembly.RuntimeError depending on the cause of failure.

  1. Return the result of processing a potential WebAssembly response, given source, with the following steps:
    • Processing steps, given bytes:
      1. Compile bytes, in the same fashion as specified for the WebAssembly.Module constructor.
      2. If compilation completes successfully:
        1. Let module be the Ast.module compilation result.
        2. Instantiate module in the in the same fashion as specified for the WebAssembly.Instance constructor.
        3. If instantiation completes successfully, return a success with a tuple containing module, the resulting instance, and the resulting exports.
        4. Otherwise, if instantiation fails, return a failure with the failure reason.
      3. Otherwise, if compilation fails, return a failure with the failure reason.
    • Success steps, given a tuple (module, instance, exports)
      1. Create exportsObject from exports, in the same fashion as specified for the WebAssembly.Instance constructor.
      2. Create instanceObject from exportsObject and instance, in the same fashion as specified for the WebAssembly.Instance constructor.
      3. Let moduleObject be a new WebAssembly.Module instance, with its [[Module]] set to module.
      4. Let result be ObjectCreate(%ObjectPrototype%).
      5. Perform CreateDataProperty(result, “module”, moduleObject).
      6. Perform CreateDataProperty(result, “instance”, instanceObject).
      7. Return result.
    • Failure steps, given reason
      1. Return a new WebAssembly.CompileError, WebAssembly.LinkError, or WebAssembly.RuntimeError as appropriate for the failure information stored in reason.

Process a potential WebAssembly response

The above two functions both reuse much of the same infrastructure for extracting bytes from an appropriate Response object, differing only in what they do with those bytes in the end. As such we define the following shared spec-level procedure:

Process a potential WebAssembly response accepts an input argument and three sets of steps processingSteps, successSteps, and failureSteps:

  • argument is an arbitrary author-supplied JavaScript value.
  • processingSteps will occur in parallel (i.e. “off the main thread”), accepts a byte sequence, and must return a Realm-agnostic success or failure value.
  • successSteps and failureSteps will occur in tasks posted back to the main event loop; they accept the Realm-agnostic values returned from processingSteps, and must transform them into JavaScript objects that can be used to appropriately fulfill or reject the returned promise.

Given these values, to process a potential WebAssembly response:

  1. Let returnValue be a new promise.
  2. Let sourceAsPromise be a promise resolved with argument.
  3. Upon fulfillment of sourceAsPromise with value unwrappedSource:
    1. If unwrappedSource is not a Response object, reject returnValue with a TypeError exception and abort these substeps.
    2. Let response be unwrappedSource’s response.
    3. Let mimeType be the result of extracting a MIME type from response’s header list.
    4. 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;`.)
    5. If response is not CORS-same-origin, reject returnValue with a TypeError and abort these substeps.
    6. If response’s status is not an ok status, reject returnValue with a TypeError and abort these substeps.
    7. 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 processingSteps 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.)
    8. Upon fulfillment of bodyPromise with value bodyArrayBuffer:
      1. Let bytes be the byte sequence underlying bodyArrayBuffer.
      2. In parallel, perform processingSteps, given bytes.
      3. If processingSteps succeeds with value processingSuccessValue, queue a task on the networking task source to run successSteps given processingSuccessValue, and let successResult be the result of those steps. Resolve returnValue with successResult.
      4. Otherwise, if processingSteps fails with reason processingFailureReason, queue a task on the networking task source to run failureSteps given processingFailureReason, and let failureResult be the result of those steps. Reject returnValue with failureResult.
    9. Upon rejection of bodyPromise with reason reason:
      1. Reject returnValue with reason.
  4. Upon rejection of sourceAsPromise with reason reason:
    1. Reject returnValue with reason.
  5. Return returnValue.

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 Error.stack 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

  • ${url} is the URL associated with the module, if applicable (see notes).
  • ${funcIndex} is an index in the function index space.
  • ${pcOffset} is the offset in the module binary of the first byte of the instruction, printed in hexadecimal with lower-case digits, with a leading 0x prefix.

Notes:

  • The URL field may be interpreted differently depending on the context. When the response-based instantiation API is used in a browser, the associated URL should be used; or when the ArrayBuffer-based instantiation API is used, the browser should represent the location of the API call. This kind of instantiation is analagous to executing JavaScript using eval; therefore if the browser has an existing method to represent the location of the eval call it can use a similar one for WebAssembly.instantiate. For example if the browser uses foo.js line 10 > eval or eval at bar (foo.js:10:3) for eval, it could use foo.js line 10 > WebAssembly.instantiate or WebAssembly.instantiate at bar (foo.js:10:3), respectively. Offline tools may use a filename instead.
  • Using hexadecimal for module offsets matches common conventions in native tools such as objdump (where addresses are printed in hex) and makes them visually distinct from JavaScript line numbers. Other numbers are represented in decimal.

While the name property of exported WebAssembly functions is specified by the JS API, synthesized function names are also displayed in other contexts like devtool callstacks and Error.stack. If a WebAssembly module contains a “name” section, these names should be used to synthesize a function name as follows:

  • If a function name subsection is present, the displayed name should be ${module_name}.${function_name} or ${function_name}, depending on whether the module name is present.
  • Otherwise, the output can be context-dependent:
    • If the function name is shown alongside its location in a stack trace, then just the module name (if present) or an empty string can be used (because the function index is already in the location).
    • Otherwise, ${module_name}.wasm-function[${funcIndex}] or wasm-function[${funcIndex}] should be used to convey the function index.

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.

Modules

WebAssembly’s modules allow for natural integration with the ES6 module system.

Names

A WebAssembly module can have imports and exports, which are identified using UTF-8 byte sequences. The most natural Web representation of a mapping of export names to exports is a JS object in which each export is a property with a name encoded in UTF-16. A WebAssembly module fails validation on the Web if it has imports or exports whose names do not transcode cleanly to UTF-16 according to the following conversion algorithm, assuming that the WebAssembly name is in a Uint8Array called array:

function convertToJSString(array)
{
  var string = "";
  for (var i = 0; i < array.length; ++i)
    string += String.fromCharCode(array[i]);
  return decodeURIComponent(escape(string));
}

This performs the UTF8 decoding (decodeURIComponent(escape(string))) using a common JS idiom. Transcoding failure is detected by decodeURIComponent, which may throw URIError. If it does, the WebAssembly module will not validate. This validation rule is only mandatory for Web embedding.

Security

WebAssembly’s security model should depend on the same-origin policy, with cross-origin resource sharing (CORS) and subresource integrity to enable distribution through content distribution networks and to implement dynamic linking.

SIMD

Once SIMD is supported WebAssembly would:

  • Be statically typed analogous to SIMD.js-in-asm.js;
  • Reuse specification of operation semantics (with TC39);
  • Reuse backend implementation (same IR nodes).

GC

Once GC is supported, WebAssembly code would be able to reference and access JavaScript, DOM, and general WebIDL-defined objects.

Documentation