Skip to content

Commit

Permalink
[WIP] WebAssembly JavaScript Module integration
Browse files Browse the repository at this point in the history 
For concreteness, this patch specifies how the WebAssembly JavaScript
module integration proposal [1] could work in HTML. It is not yet ready
to merge, as the proposal is still in a relatively early state.

Note that this change depends on the ability for modules to block in the
evaluation phase, to permit WebAssembly module instantiation to yield,
as is necessary on some platforms where compilation work is performed
during the first instantiation. Such an ability to yield is provided by
the JavaScript top-level await proposal [2] and associated HTML
integration patch whatwg#4352.

[1] https://github.com/webassembly/esm-integration
[2] https://github.com/tc39/proposal-top-level-await
  • Loading branch information
@littledan @Ms2ger
littledan authored and Ms2ger committed May 21, 2019
1 parent a40f5b6 commit bf2917b
Showing 1 changed file with 144 additions and 22 deletions.
166 changes: 144 additions & 22 deletions source
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2738,6 +2738,7 @@ a.setAttribute('href', 'https://example.com/'); // change the content attribute
<p>The following terms are defined in the WHATWG MIME Sniffing standard: <ref spec=MIMESNIFF></p>

<ul class="brief">
<li><dfn data-x-href="https://mimesniff.spec.whatwg.org/#mime-type-essence">essence</dfn></li>
<li><dfn data-x-href="https://mimesniff.spec.whatwg.org/#mime-type">MIME type</dfn></li>
<li><dfn data-x-href="https://mimesniff.spec.whatwg.org/#valid-mime-type">valid MIME type string</dfn></li>
<li><dfn data-x-href="https://mimesniff.spec.whatwg.org/#valid-mime-type-with-no-parameters">valid MIME type string with no parameters</dfn></li>
Expand Down Expand Up @@ -2778,6 +2779,7 @@ a.setAttribute('href', 'https://example.com/'); // change the content attribute
<li>the <dfn data-x-href="https://fetch.spec.whatwg.org/#requestcredentials"><code>RequestCredentials</code></dfn> enumeration</li>
<li>the <dfn data-x-href="https://fetch.spec.whatwg.org/#requestdestination"><code>RequestDestination</code></dfn> enumeration</li>
<li>the <dfn data-x-href="https://fetch.spec.whatwg.org/#dom-global-fetch"><code>fetch()</code></dfn> method</li>
<li><dfn data-x-href="https://fetch.spec.whatwg.org/#concept-body-consume-body">consume body</dfn></li>
<li>
<dfn data-x="concept-response"
data-x-href="https://fetch.spec.whatwg.org/#concept-response">response</dfn> and its
Expand Down Expand Up @@ -4202,6 +4204,17 @@ a.setAttribute('href', 'https://example.com/'); // change the content attribute
</ul>
</dd>

<dt>WebAssembly JavaScript Module Integration</dt>

<dd>
<p>The following terms are defined in <cite>WebAssembly JavaScript Module Integration</cite>: <ref spec=WASMESM></p>

<ul class="brief">
<li><dfn data-x-href="https://webassembly.github.io/esm-integration/js-api/index.html#webassembly-module-record">WebAssembly Module Record</dfn></li>
<li><dfn data-x-href="https://webassembly.github.io/esm-integration/js-api/index.html#parse-a-webassembly-module">parse a WebAssembly module</dfn></li>
</ul>
</dd>

</dl>

<hr>
Expand Down Expand Up @@ -87523,6 +87536,9 @@ interface <dfn>ApplicationCache</dfn> : <span>EventTarget</span> {
<li><p>a <span>Source Text Module Record</span>, for <span data-x="JavaScript module
script">JavaScript module scripts</span>;</p></li>

<li><p>a <span>WebAssembly Module Record</span>, for <span data-x="WebAssembly module
script">WebAssembly module scripts</span>;</p></li>

<li><p>a <span>Synthetic Module Record</span>, for <span data-x="JSON module script">JSON
module scripts</span>; or</p></li>

Expand Down Expand Up @@ -87580,13 +87596,17 @@ interface <dfn>ApplicationCache</dfn> : <span>EventTarget</span> {
data-x="concept-script">script</span>. It has no additional <span data-x="struct
item">items</span>.</p>

<p><span data-x="module script">Module scripts</span> can be classified into two types:</p>
<p><span data-x="module script">Module scripts</span> can be classified into three types:</p>

<ul>
<li><p>A <span>module script</span> is a <dfn data-export="">JavaScript module script</dfn> if
its <span data-x="concept-script-record">record</span> is a <span>Source Text Module
Record</span>.</p></li>

<li><p>A <span>module script</span> is a <dfn data-export="">WebAssembly module script</dfn> if
its <span data-x="concept-script-record">record</span> is a <span>WebAssembly Module
Record</span>.</p></li>

<li>
<p>A <span>module script</span> is a <dfn data-export="">JSON module script</dfn> if its <span
data-x="concept-script-record">record</span> is a <span>Synthetic Module Record</span>, and it
Expand Down Expand Up @@ -88283,6 +88303,23 @@ interface <dfn>ApplicationCache</dfn> : <span>EventTarget</span> {
</ol>
</li>

<li>
<p>If <var>type</var>'s <span>essence</span> is "<code>application/wasm</code>", then:</p>

<ol>
<li><p>Let <var>bufferPromise</var> be the result of running <span>consume body</span> on
<var>response</var> with <i>ArrayBuffer</i>.</p></li>

<li><p><span data-x="creating a WebAssembly module script">Create a WebAssembly module
script</span> given <var>bufferPromise</var>, <var>module map settings object</var>,
<var>response</var>'s <span data-x="concept-response-url">url</span>, and
<var>options</var>. Wait until the algorithm asynchronously completes with
<var>result</var>.</p></li>

<li><p>Set <var>module script</var> to <var>result</var>.</p></li>
</ol>
</li>

<li>
<p>If <var>type</var> is a <span>JSON MIME type</span>, then:</p>

Expand Down Expand Up @@ -88551,6 +88588,43 @@ interface <dfn>ApplicationCache</dfn> : <span>EventTarget</span> {
<li><p>Return <var>script</var>.</p></li>
</ol>

<p>To <dfn id="validate-requested-module-specifiers">validate requested module specifiers</dfn>
of a module record <var>record</var> for a script <var>script</var>:</p>

<ol>
<li>
<p><span data-x="list iterate">For each</span> string <var>requested</var> of
<var>record</var>.[[RequestedModules]]:</p>

<ol>
<li><p>Let <var>url</var> be the result of <span data-x="resolve a module specifier">resolving
a module specifier</span> given <var>script</var>'s <span data-x="concept-script-base-url">base
URL</span> and <var>requested</var>.</p></li>

<li>
<p>If <var>url</var> is failure, then:</p>

<ol>
<li><p>Let <var>error</var> be a new <code>TypeError</code> exception.</p></li>

<li><p>Set <var>script</var>'s <span data-x="concept-script-parse-error">parse error</span>
to <var>error</var>.</p></li>

<li><p>Return.</p></li>
</ol>
</li>
</ol>
</li>

<li><p>Set <var>script</var>'s <span data-x="concept-script-record">record</span> to
<var>record</var>.</p></li>
</ol>

<p class="note">This algorithm is essentially validating all of the requested module specifiers. We
treat a module with unresolvable module specifiers the same as one that cannot be parsed; in
both cases, a syntactic issue makes it impossible to ever contemplate instantiating the module
later.</p>

<p>To <dfn data-x="creating a JavaScript module script">create a JavaScript module script</dfn>,
given a <span>JavaScript string</span> <var>source</var>, an <span>environment settings
object</span> <var>settings</var>, a <span>URL</span> <var>baseURL</var>, and some <span>script
Expand Down Expand Up @@ -88595,39 +88669,78 @@ interface <dfn>ApplicationCache</dfn> : <span>EventTarget</span> {
</ol>
</li>

<li id="validate-requested-module-specifiers">
<p><span data-x="list iterate">For each</span> string <var>requested</var> of
<var>result</var>.[[RequestedModules]]:</p>
<li><p><span>Validate requested module specifiers</span> of <var>result</var> with
<var>script</var>.</p></li>

<ol>
<li><p>Let <var>url</var> be the result of <span data-x="resolve a module specifier">resolving
a module specifier</span> given <var>script</var>'s <span data-x="concept-script-base-url">base
URL</span> and <var>requested</var>.</p></li>
<li><p>Return <var>script</var>.</p></li>
</ol>

<p>To <dfn data-x="creating a WebAssembly module script">create a WebAssembly module script</dfn>,
given a promise that will resolve with an <code data-x="idl-ArrayBuffer">ArrayBuffer</code>
<var>bufferPromise</var>, an <span>environment settings object</span> <var>settings</var>, a
<span>URL</span> <var>baseURL</var>, and some <span>script fetch options</span>
<var>options</var>, run these steps. The algorithm will asynchronously complete with a new
<span>WebAssembly module script</span>.</p>

<ol>
<li><p>If <span data-x="concept-bc-noscript">scripting is disabled</span> for
<var>settings</var>'s <span>responsible browsing context</span>, then set
<var>bufferPromise</var> to a promise resolved with an empty
<code data-x="idl-ArrayBuffer">ArrayBuffer</code>.</p></li>
<!-- REVIEW NOTE: this will cause a parse error, because it doesn't have the magic bytes. -->

<li><p>Let <var>script</var> be a new <span>WebAssembly module script</span> that this algorithm
will subsequently initialize.</p></li>

<li><p>Set <var>script</var>'s <span>settings object</span> to <var>settings</var>.</p></li>

<li><p>Set <var>script</var>'s <span data-x="concept-script-base-url">base URL</span> to
<var>baseURL</var>.</p></li>

<li><p>Set <var>script</var>'s <span data-x="concept-script-script-fetch-options">fetch
options</span> to <var>options</var>.</p></li>

<li><p>Set <var>script</var>'s <span data-x="concept-script-parse-error">parse error</span> and
<span data-x="concept-script-error-to-rethrow">error to rethrow</span> to null.</p></li>

<li>
<p>Upon fulfillment of <var>bufferPromise</var> with <var>buffer</var>:</p>

<ol>
<li>
<p>If <var>url</var> is failure, then:</p>
<p>Let <var>module</var> be the result of <span>parse a WebAssembly module</span> given
<var>buffer</var>, <var>settings</var>'s <span data-x="environment settings object's
Realm">Realm</span>, and <var>script</var>.</p>

<ol>
<li><p>Let <var>error</var> be a new <code>TypeError</code> exception.</p></li>
<p class="note">Passing <var>script</var> as the last parameter here ensures
<var>result</var>.[[HostDefined]] will be <var>script</var>.</p>

<li><p>Set <var>script</var>'s <span data-x="concept-script-parse-error">parse error</span>
to <var>error</var>.</p></li>
<p>If this algorithm throws an exception, then catch it and perform the following steps:</p>

<ol>
<li><p>Set <var>script</var>'s <span data-x="concept-script-parse-error">parse error</span> to
the exception.</li>

<li><p>Return <var>script</var>.</p></li>
<li><p>Asynchronously complete this algorithm with <var>script</var>.</p></li>
</ol>
</li>
</ol>

<p class="note">This step is essentially validating all of the requested module specifiers. We
treat a module with unresolvable module specifiers the same as one that cannot be parsed; in
both cases, a syntactic issue makes it impossible to ever contemplate instantiating the module
later.</p>
<li><p><span>Validate requested module specifiers</span> of <var>module</var> with
<var>script</var>.</p></li>

<li><p>Asynchronously complete this algorithm with <var>script</var>.</p></li>
</ol>
</li>

<li><p>Set <var>script</var>'s <span data-x="concept-script-record">record</span> to
<var>result</var>.</p></li>
<li>
<p>Upon rejection of <var>bufferPromise</var> with <var>reason</var>:</p>
<ol>
<li><p>Set <var>script</var>'s <span data-x="concept-script-parse-error">parse error</span> to
<var>reason</var>.</p></li>

<li><p>Return <var>script</var>.</p></li>
<li><p>Asynchronously complete this algorithm with <var>script</var>.</p></li>
</ol>
</li>
</ol>

<p>To <dfn data-x="creating a JSON module script">create a JSON module script</dfn>, given a
Expand Down Expand Up @@ -122664,6 +122777,9 @@ INSERT INTERFACES HERE
<dt><dfn><code>application/xml</code></dfn></dt>
<dd>XML <ref spec=XML> <ref spec=RFC7303></dd>

<dt><dfn><code>application/wasm</code></dfn></dt>
<dd>WebAssembly <ref spec=WASM></dd>

<dt><dfn><code>image/gif</code></dfn></dt>
<dd>GIF images <ref spec=GIF></dd>

Expand Down Expand Up @@ -123269,6 +123385,12 @@ INSERT INTERFACES HERE
<dt id="refsWASMJS">[WASMJS]</dt>
<dd>(Non-normative) <cite><a href="https://webassembly.github.io/spec/js-api/">WebAssembly JavaScript Interface</a></cite>, D. Ehrenberg. W3C.</dd>

<dt id="refsWASM">[WASM]</dt>
<dd><cite><a href="https://webassembly.github.io/spec/core/bikeshed/index.html">WebAssembly Core Specification</a></cite>, A. Rossberg. W3C.</dd>

<dt id="refsWASMESM">[WASMESM]</dt>
<dd><cite><a href="https://webassembly.github.io/esm-integration/js-api/index.html">WebAssembly JavaScript Module Integration</a></cite>, L. Clark, D. Ehrenberg. W3C.</dd>

<dt id="refsWCAG">[WCAG]</dt>
<dd>(Non-normative) <cite><a href="https://www.w3.org/TR/WCAG20/">Web Content Accessibility Guidelines (WCAG) 2.0</a></cite>, B. Caldwell, M. Cooper, L. Reid, G. Vanderheiden. W3C.</dd>

Expand Down

0 comments on commit bf2917b

Please sign in to comment.