Add <link> rel="modulepreload"

This allows preloading module scripts, and optionally their descendants.
The processing model for this turns out to be different enough that
simply extending rel="preload" is not a good option.

Closes whatwg/fetch#486.

Author: domenic

images/ircfog-modules.svg

@@ -2804,6 +2804,7 @@ a.setAttribute('href', 'https://example.com/'); // change the content attribute
        <li><dfn data-x="concept-request-destination" data-x-href="https://fetch.spec.whatwg.org/#concept-request-destination">destination</dfn></li>
        <li><dfn data-x="concept-potential-destination" data-x-href="https://fetch.spec.whatwg.org/#concept-potential-destination">potential destination</dfn></li>
        <li><dfn data-x="concept-potential-destination-translate" data-x-href="https://fetch.spec.whatwg.org/#concept-potential-destination-translate">translating</dfn> a <span data-x="concept-potential-destination">potential destination</span></li>
+       <li><dfn data-x="concept-script-like-destination" data-x-href="https://fetch.spec.whatwg.org/#request-destination-script-like">script-like</dfn> <span data-x="concept-request-destination">destinations</span></li>
        <li><dfn data-x="concept-request-priority" data-x-href="https://fetch.spec.whatwg.org/#concept-request-priority">priority</dfn></li>
        <li><dfn data-dfn-for="request" data-x="concept-request-origin" data-x-href="https://fetch.spec.whatwg.org/#concept-request-origin">origin</dfn></li>
        <li><dfn data-x="concept-request-referrer" data-x-href="https://fetch.spec.whatwg.org/#concept-request-referrer">referrer</dfn></li>
@@ -6960,6 +6961,28 @@ a.setAttribute('href', 'https://example.com/'); // change the content attribute
   data-x="attr-crossorigin-anonymous-keyword">anonymous</code> keyword. The <i data-x="missing value default">missing value default</i>, used when the attribute is omitted, is the <dfn data-x="attr-crossorigin-none">No
   CORS</dfn> state.</p>
 
+  <p>The majority of fetches governed by <span data-x="CORS settings attribute">CORS settings
+  attributes</span> will be done via the <span>create a potential-CORS request</span> algorithm.</p>
+
+  <p>For <span data-x="module script">module scripts</span>, certain <span data-x="CORS settings
+  attribute">CORS settings attributes</span> have been repurposed to have a slightly different
+  meaning, wherein they only impact the <span data-x="concept-request">request</span>'s <span
+  data-x="concept-request-credentials-mode">credentials mode</span> (since the <span
+  data-x="concept-request-mode">mode</span> is always "<code data-x="">cors</code>"). To perform
+  this translation, we define the <dfn>module script credentials mode</dfn> for a given <span>CORS
+  settings attribute</span> to be determined by switching on the attribute's state:</p>
+
+  <dl class="switch">
+   <dt><span data-x="attr-crossorigin-none">No CORS</span></dt>
+   <dd>"<code data-x="">omit</code>"</dd>
+
+   <dt><span data-x="attr-crossorigin-anonymous">Anonymous</span></dt>
+   <dd>"<code data-x="">same-origin</code>"</dd>
+
+   <dt><span data-x="attr-crossorigin-none">Use Credentials</span></dt>
+   <dd>"<code data-x="">include</code>"</dd>
+  </dl>
+
 
   <h4>Referrer policy attributes</h4>
 
@@ -13120,6 +13143,7 @@ interface <dfn>HTMLLinkElement</dfn> : <span>HTMLElement</span> {
   <code data-x="rel-alternate">alternate</code>,
   <code data-x="rel-dns-prefetch">dns-prefetch</code>,
   <code data-x="rel-icon">icon</code>,
+  <code data-x="rel-modulepreload">modulepreload</code>,
   <code data-x="rel-next">next</code>,
   <code data-x="rel-pingback">pingback</code>,
   <code data-x="rel-preconnect">preconnect</code>,
@@ -13273,15 +13297,24 @@ interface <dfn>HTMLLinkElement</dfn> : <span>HTMLElement</span> {
   destination</span> is a keyword for this attribute, mapping to a state of the same name. The
   attribute must be specified on <code>link</code> elements that have a <code
   data-x="attr-link-rel">rel</code> attribute that contains the <code
-  data-x="rel-preload">preload</code> keyword, but must not be specified on <code>link</code>
-  elements which do not. <span w-nodev>The processing model for how the <code
-  data-x="attr-link-as">as</code> attribute is used is given in the <span
-  data-x="concept-link-obtain">steps to obtain the resource</span>.</span></p>
+  data-x="rel-preload">preload</code> keyword. It may be specified on <code>link</code> elements
+  that have a <code data-x="attr-link-rel">rel</code> attribute that contains the <code
+  data-x="rel-modulepreload">modulepreload</code> keyword; in such cases it must have a value which
+  is a <span data-x="concept-script-like-destination">script-like destination</span>. For other
+  <code>link</code> elements, it must not be specified.</p>
+
+  <p w-nodev>The processing model for how the <code data-x="attr-link-as">as</code> attribute is
+  used is given in the steps to obtain the resource, for <span data-x="concept-link-obtain">for
+  <code data-x="rel-preload">preload</code> links</span> and <a
+  href="#modulepreload-obtain-steps">for <code data-x="rel-modulepreload">modulepreload</code>
+  links</a>, respectively.</p>
 
   <p class="note">The attribute does not have a <i data-x="missing value default">missing value
   default</i> or <i data-x="invalid value default">invalid value default</i>, meaning that invalid
   or missing values for the attribute map to no state. This is accounted for in the processing
-  model.</p>
+  model. For <code data-x="rel-preload">preload</code> links, both conditions are an error; for
+  <code data-x="rel-modulepreload">modulepreload</code> links, a missing value will be treated as
+  "<code data-x="">script</code>".</p>
 
   <hr>
 
@@ -23426,6 +23459,7 @@ interface <dfn>HTMLHyperlinkElementUtils</dfn> {
   <span>allowed in the body</span>. The <span>body-ok</span> keywords defined by this specification
   are
   <code data-x="rel-dns-prefetch">dns-prefetch</code>,
+  <code data-x="rel-modulepreload">modulepreload</code>,
   <code data-x="rel-pingback">pingback</code>,
   <code data-x="rel-preconnect">preconnect</code>,
   <code data-x="rel-prefetch">prefetch</code>,
@@ -23516,6 +23550,16 @@ interface <dfn>HTMLHyperlinkElementUtils</dfn> {
      <td>Imports an icon to represent the current document.</td>
     </tr>
 
+    <tr>
+     <td><code data-x="rel-modulepreload">modulepreload</code></td>
+     <td><span data-x="external resource link">External Resource</span></td>
+     <td><em>not allowed</em></td>
+     <td class="yes"> Yes </td>
+     <td>Specifies that the user agent must preemptively <span data-x="fetch a single module script">fetch the module
+     script</span> and store it in the document's <span data-x="concept-document-module-map">module map</span> for later
+     evaluation. Optionally, the module's dependencies can be fetched as well.</td>
+    </tr>
+
     <tr>
      <td><code data-x="rel-license">license</code></td> <!-- seventh most used <a rel> value -->
      <td><span>Hyperlink</span></td>
@@ -24117,6 +24161,176 @@ interface <dfn>HTMLHyperlinkElementUtils</dfn> {
   </div>
 
 
+  <h5>Link type "<dfn><code data-x="rel-modulepreload">modulepreload</code></dfn>"</h5>
+
+  <p>The <code data-x="rel-modulepreload">modulepreload</code> keyword may be used with
+  <code>link</code> elements. This keyword creates an <span>external resource link</span>. This
+  keyword is <span>body-ok</span>.</p>
+
+  <p>The <code data-x="rel-modulepreload">modulepreload</code> keyword is a specialized alternative
+  to the <code data-x="rel-preload">preload</code> keyword, with a processing model geared toward
+  preloading <span data-x="module script">module scripts</span>. In particular, it uses the specific
+  fetch behavior for module scripts (including, e.g., a different interpretation of the <code
+  data-x="attr-link-crossorigin">crossorigin</code> attribute), and places the result into the
+  appropriate <span data-x="concept-document-module-map">module map</span> for later evaluation. In
+  contrast, a similar <span>external resource link</span> using the <code
+  data-x="rel-preload">preload</code> keyword would place the result in the preload cache, without
+  affecting the document's <span data-x="concept-document-module-map">module map</span>.</p>
+
+  <p>Additionally, implementations can take advantage of the fact that <span data-x="module
+  script">module scripts</span> declare their dependencies in order to fetch the specified module's
+  dependency as well. This is intended as an optimization opportunity, since the user agent knows
+  that, in all likelihood, those dependencies will also be needed later. It will not generally be
+  observable without using technology such as service workers, or monitoring on the server side.
+  Notably, the appropriate <code data-x="event-load">load</code> or <code
+  data-x="event-error">error</code> events will occur after the specified module is fetched, and
+  will not wait for any dependencies.</p>
+
+  <div w-nodev>
+
+  <p>The appropriate times to fetch the resource for such a link are:</p>
+
+  <ul>
+   <li><p>When the <span>external resource link</span> is created on a <code>link</code> element
+   that is already <span>browsing-context connected</span>.</p></li>
+
+   <li><p>When the <span>external resource link</span>'s <code>link</code> element <span>becomes
+   browsing-context connected</span>.</p></li>
+
+   <li><p>When the <code data-x="attr-link-href">href</code> attribute of the <code>link</code>
+   element of an <span>external resource link</span> that is already <span>browsing-context
+   connected</span> is changed.</p></li>
+  </ul>
+
+  </div>
+
+  <p class="note">Unlike some other link relations, changing the relevant attributes (such as <code
+  data-x="attr-link-as">as</code>, <code data-x="attr-link-crossorigin">crossorigin</code>, and
+  <code data-x="attr-link-referrerpolicy">referrerpolicy</code>) of such a <code>link</code>
+  attribute does not trigger a new fetch. This is because the document's <span
+  data-x="concept-document-module-map">module map</span> has already been populated by a previous
+  fetch, and so re-fetching would be pointless.</p>
+
+  <div w-nodev>
+
+  <p id="modulepreload-obtain-steps">To obtain the resource for such a link:</p>
+
+  <ol>
+   <li><p>If the <code data-x="attr-link-href">href</code> attribute's value is the empty string,
+   then return.</p></li>
+
+   <li><p>Let <var>destination</var> be the current state of the <code
+   data-x="attr-link-as">as</code> attribute (a <span
+   data-x="concept-request-destination">destination</span>), or "<code data-x="">script</code>" if
+   it is in no state.</p></li>
+
+   <li><p>If <var>destination</var> is not <span
+   data-x="concept-script-like-destination">script-like</span>, then <span>queue a task</span> on
+   the <span>networking task source</span> to <span data-x="concept-event-fire">fire an event</span>
+   named <code data-x="event-error">error</code> at the <code>link</code> element, and
+   return.</p></li>
+
+   <li><p><span data-x="parse a url">Parse</span> the <span>URL</span> given by the <code
+   data-x="attr-link-href">href</code> attribute, relative to the element's <span>node
+   document</span>. If that fails, then return. Otherwise, let <var>url</var> be the <span>resulting
+   URL record</span>.</p></li>
+
+   <li><p>Let <var>settings object</var> be the <code>link</code> element's <span>node
+   document</span>'s <span>relevant settings object</span>.</p></li>
+
+   <li><p>Let <var>credentials mode</var> be the <span>module script credentials mode</span> for the
+   <code data-x="attr-link-crossorigin">crossorigin</code> attribute.</p></li>
+
+   <li><p>Let <var>cryptographic nonce</var> be the value of the <code
+   data-x="attr-link-nonce">nonce</code> attribute, if it is specified, or the empty string
+   otherwise.</p></li>
+
+   <li><p>Let <var>integrity metadata</var> be the value of the <code
+   data-x="attr-link-integrity">integrity</code> attribute, if it is specified, or the empty string
+   otherwise.</p></li>
+
+   <li><p>Let <var>options</var> be a <span>script fetch options</span> whose <span
+   data-x="concept-script-fetch-options-nonce">cryptographic nonce</span> is <var>cryptographic
+   nonce</var>, <span data-x="concept-script-fetch-options-integrity">integrity metadata</span> is
+   <var>integrity metadata</var>, <span data-x="concept-script-fetch-options-parser">parser
+   metadata</span> is "<code data-x="">not-parser-inserted</code>", and <span
+   data-x="concept-script-fetch-options-credentials">credentials mode</span> is <var>credentials
+   mode</var>.</p></li>
+
+   <li><p><span>Fetch a single module script</span> given <var>url</var>, <var>settings
+   object</var>, <var>destination</var>, <var>options</var>, <var>settings object</var>, "<code
+   data-x="">client</code>", and with the <var>top-level module fetch</var> flag set. Wait until
+   algorithm asynchronously completes with <var>result</var>.</p></li>
+
+   <li><p>If <var>result</var> is null, <span data-x="concept-event-fire">fire an event</span>
+   named <code data-x="event-error">error</code> at the <code>link</code> element, and
+   return.</p></li>
+
+   <li><p><span data-x="concept-event-fire">Fire an event</span> named <code
+   data-x="event-load">load</code> at the <code>link</code> element.</p></li>
+
+   <li>
+    <p>Optionally, perform the following steps:</p>
+
+    <ol>
+     <li><p>Let <var>visited set</var> be « <var>url</var> ».</p></li>
+
+     <li><p><span data-x="fetch the descendants of and instantiate a module script">Fetch the
+     descendants of and instantiate</span> <var>result</var> given <var>destination</var> and
+     <var>visited set</var>.</p></li>
+    </ol>
+
+    <p class="note">Generally, performing these steps will be beneficial for performance, as it
+    allows pre-loading the modules that will invariably be requested later, when <span>fetch a
+    module script graph</span> is called. However, user agents might wish to skip them in
+    bandwidth-constrained situations, or situations where the relevant fetches are already in
+    flight.</p>
+   </li>
+  </ol>
+
+  </div>
+
+  <div class="example" id="example-modulepreload-manifest">
+   <p>The following snippet shows the top part of an application with several modules preloaded:</p>
+
+   <pre>&lt;!DOCTYPE html>
+&lt;html lang="en">
+&lt;title>IRCFog&lt;/title>
+
+&lt;link rel="modulepreload" href="app.mjs">
+&lt;link rel="modulepreload" href="helpers.mjs">
+&lt;link rel="modulepreload" href="irc.mjs">
+&lt;link rel="modulepreload" href="fog-machine.mjs">
+
+&lt;script type="module" src="app.mjs">
+...</pre>
+
+   <p>Assume that the module graph for the application is as follows:</p>
+
+   <img src="images/ircfog-modules.svg" width="301" height="151" alt="The module graph is rooted at app.mjs, which depends on irc.mjs and fog-machine.mjs. In turn, irc.mjs depends on helpers.mjs.">
+
+   <p>Here we see the application developer has used <code
+   data-x="rel-modulepreload">modulepreload</code> all of the modules in their module graph,
+   ensuring that the user agent initiates fetches for them all. Without such preloading, the user
+   agent might need to go through multiple network roundtrips before discovering <code
+   data-x="">helpers.mjs</code>, if technologies such as HTTP/2 Server Push are not in play. In
+   this way, <code data-x="rel-modulepreload">modulepreload</code> <code>link</code> elements can be
+   used as a sort of "manifest" of the application's modules.</p>
+  </div>
+
+  <div class="example" id="example-modulepreload-dynamic-import">
+   <p>The following code shows how <code data-x="rel-modulepreload">modulepreload</code> links can
+   be used in conjunction with <code>import()</code> to ensure network fetching is done ahead of
+   time, so that when <code>import()</code> is called, the module is already ready (but not
+   evaluated) in the <span>module map</span>:</p>
+
+   <pre>&lt;link rel="modulepreload" href="awesome-viewer.js">
+
+&lt;button onclick="import('./awesome-viewer.js').then(m => m.view())">
+  View awesome thing
+&lt;/button></pre>
+  </div>
+
   <h5>Link type "<dfn><code data-x="rel-nofollow">nofollow</code></dfn>"</h5>
 
   <p>The <code data-x="rel-nofollow">nofollow</code> keyword may be used with <code>a</code> and
@@ -57839,24 +58053,12 @@ o............A....e
 
    </li>
 
-   <li><p>Let <var>CORS setting</var> be the current state of the element's <code
+   <li><p>Let <var>classic script CORS setting</var> be the current state of the element's <code
    data-x="attr-script-crossorigin">crossorigin</code> content attribute.</p></li>
 
-   <li>
-    <p>Let <var>module script credentials mode</var> be determined by switching on <var>CORS
-    setting</var>:</p>
-
-    <dl class="switch">
-     <dt><span data-x="attr-crossorigin-none">No CORS</span></dt>
-     <dd>"<code data-x="">omit</code>"</dd>
-
-     <dt><span data-x="attr-crossorigin-anonymous">Anonymous</span></dt>
-     <dd>"<code data-x="">same-origin</code>"</dd>
-
-     <dt><span data-x="attr-crossorigin-none">Use Credentials</span></dt>
-     <dd>"<code data-x="">include</code>"</dd>
-    </dl>
-   </li>
+   <li><p>Let <var>module script credentials mode</var> be the <span>module script credentials
+   mode</span> for the element's <code data-x="attr-script-crossorigin">crossorigin</code> content
+   attribute.</p>
 
    <li>
 
@@ -57923,7 +58125,7 @@ o............A....e
        <dt>"<code data-x="">classic</code>"</dt>
        <dd>
         <p><span>Fetch a classic script</span> given <var>url</var>, <var>settings object</var>,
-        <var>options</var>, <var>CORS setting</var>, and <var>encoding</var>.</p>
+        <var>options</var>, <var>classic script CORS setting</var>, and <var>encoding</var>.</p>
        </dd>
 
        <dt>"<code data-x="">module</code>"</dt>
@@ -117348,8 +117550,8 @@ interface <dfn>External</dfn> {
     <tr>
      <th> <code data-x="">as</code>
      <td> <code data-x="attr-link-as">link</code>
-     <td> <span data-x="concept-potential-destination">Potential destination</span> for a preload request (for <code data-x="attr-link-rel">rel</code>="<code data-x="rel-preload">preload</code>")
-     <td> <span data-x="concept-potential-destination">Potential destination</span>
+     <td> <span data-x="concept-potential-destination">Potential destination</span> for a preload request (for <code data-x="attr-link-rel">rel</code>="<code data-x="rel-preload">preload</code>" and <code data-x="attr-link-rel">rel</code>="<code data-x="rel-modulepreload">modulepreload</code>")
+     <td> <span data-x="concept-potential-destination">Potential destination</span>, for <code data-x="attr-link-rel">rel</code>="<code data-x="rel-preload">preload</code>"; <span data-x="concept-script-like-destination">script-like destination</span>, for <code data-x="attr-link-rel">rel</code>="<code data-x="rel-modulepreload">modulepreload</code>"
     <tr>
      <th> <code data-x="">async</code>
      <td> <code data-x="attr-script-async">script</code>