[worklets] Move worklets to using modules. \o/

bfgeek · bfgeek · commit 62beb3b7fa0b · 2016-01-29T10:35:25.000+11:00
diff --git a/worklets/Overview.bs b/worklets/Overview.bs
@@ -10,20 +10,10 @@ Editor: Ian Kilpatrick, ikilpatrick@chromium.org
 </pre>
 
 <pre class="anchors">
-urlPrefix: https://fetch.spec.whatwg.org/; type: dfn;
-    text: ok status
-    urlPrefix: #concept-response-;
-        text: body
-        text: status
 urlPrefix: https://html.spec.whatwg.org/multipage/browsers.html; type: dfn;
     text: effective script origin
     url: #origin-2; text: origin
 urlPrefix: https://html.spec.whatwg.org/multipage/workers.html; type: dfn;
-    text: get a fetch result
-    text: import scripts into worker global scope
-    text: importing scripts and libraries
-    text: postprocess the fetch result
-    text: validate the state
     text: web workers
     urlPrefix: #dom-workerglobalscope-;
         text: self
@@ -32,39 +22,38 @@ urlPrefix: https://html.spec.whatwg.org/multipage/webappapis.html; type: dfn;
     text: api url character encoding
     text: browsing context
     text: code entry-point
-    text: create a script
     text: creation url
     text: document environment
+    text: entry settings object
     text: environment settings object
     text: event loop
+    text: fetch a module script tree
     text: global object
     text: https state
     text: incumbent settings object
     text: microtask queue
+    text: module script
     text: realm execution context
     text: responsible browsing context
     text: responsible document
     text: responsible event loop
+    text: run a module script
     text: script execution environment
     text: task queues
 urlPrefix: https://html.spec.whatwg.org/multipage/infrastructure.html; type: dfn;
+    text: cors setting attribute
     text: in parallel
     text: javascript global environment
-    text: unsafe response
-    text: utf-8 decode
     urlPrefix: #js-;
         text: syntaxerror;
     url: resolve-a-url; text: resolve;
 urlPrefix: https://www.w3.org/2001/tag/doc/promises-guide; type: dfn;
     text: a new promise
 urlPrefix: http://www.ecma-international.org/ecma-262/6.0/#sec-; type: dfn;
     text: Construct
-    text: FunctionCreate
     text: InitializeHostDefinedRealm
     text: Invoke
-    text: NewObjectEnvironment
     text: strict mode code
-    url: function-definitions; text: FunctionBody;
 </pre>
 
 Introduction {#intro}
@@ -121,9 +110,9 @@ on a class should produce the same output given a particular input.
 The following techniques should be used in order to encourage authors to write code in an idempotent
 way:
  - No reference to the global object, e.g. <a>self</a> on a {{DedicatedWorkerGlobalScope}}.
- - Code is loaded similar to how ES6 Modules are loaded, in <a>strict mode code</a> inside an
-    anonymous function. This prevents two different scripts sharing state by referencing shared
-    objects on the global scope.
+ - Code is loaded as a <a>module script</a> which resulting in the code being executed in <a>strict
+     mode code</a> without a shared this. This prevents two different module scripts sharing
+     state be referencing shared objects on the global scope.
  - User agents may choose to always have at least two {{WorkletGlobalScope}}s per {{Worklet}} and
     randomly assign a method or set of methods on a class to a particular global scope.
  - User agents may create and destroy {{WorkletGlobalScope}}s at any time.
@@ -179,8 +168,15 @@ and |worklet|, it <em>must</em> run the following steps:
 
     2. Associate the |settingsObject| with |workletGlobalScope|.
 
-    3. For each |script| in the given |worklet|'s <b>worklet's loaded scripts</b> run the |script|
-        in the |workletGlobalScope|.
+    3. For each |resolvedModuleURL| in the given |worklet|'s <b>worklet's resolved module URLs</b>,
+        run the following substeps:
+        1. Let |script| be the result of <a>fetch a module script tree</a> given
+            |resolvedModuleURL|, "anonymous" for the <a>CORS setting attribute</a>, and
+            |settingsObject|.
+
+        Issue: Decide if "use-credientials" should be valid for worklets.
+
+        2. <a>Run a module script</a> given |script|.
 
 ### Script settings for worklets ### {#script-settings-for-worklets}
 
@@ -238,60 +234,56 @@ Issue: Merge this with https://html.spec.whatwg.org/multipage/workers.html#set-u
 Worklet {#worklet-section}
 --------------------------
 
-The {{Worklet}} object provides the capability to import scripts into its associated {{WorkletGlobalScope}}s. The user agent can then create classes registered
-on the {{WorkletGlobalScope}}s and invoke their methods.
+The {{Worklet}} object provides the capability to import module scripts into its associated
+{{WorkletGlobalScope}}s. The user agent can then create classes registered on the
+{{WorkletGlobalScope}}s and invoke their methods.
 
 <pre class='idl'>
 interface Worklet {
-    [NewObject] Promise&lt;void&gt; importScripts(DOMString... urls);
+    [NewObject] Promise&lt;void> import(DOMString moduleURL);
 };
 </pre>
 
-A {{Worklet}} has a list of the <b>worklet's {{WorkletGlobalScope}}s</b>. Initially this list is empty; it is populated when the user agent chooses to create its {{WorkletGlobalScope}}.
+A {{Worklet}} has a list of the <b>worklet's WorkletGlobalScopes</b>. Initially this list is empty;
+it is populated when the user agent chooses to create its {{WorkletGlobalScope}}.
 
-A {{Worklet}} has a list of the <b>worklet's loaded scripts</b>. Initially this list is empty; it is populated when scripts are fetched and parsed.
+A {{Worklet}} has a list of the <b>worklet's resolved module URLs</b>. Initially this list is empty; it is
+populated when module scripts resolved.
 
-When the <dfn method for=Worklet>importScripts(urls)</dfn> method is called on a {{Worklet}} object, the user agent <em>must</em> run the following steps:
+When the <dfn method for=Worklet>import(moduleURL)</dfn> method is called on a {{Worklet}} object,
+the user agent <em>must</em> run the following steps:
  1. Let |promise| be <a>a new promise</a>.
+
  2. Run the following steps <a>in parallel</a>:
-    1. Let |settingsObject| be the <a>incumbent settings object</a>.
-    2. If there are no arguments, return without doing anything. Abort these steps.
-    3. <a>Resolve</a> each argument relative to settings object's <a>API base URL</a>.
-    4. If any fail, throw a SyntaxError</a> exception and abort these steps.
-    5. For each URL in the resulting absolute URLs, run these substeps:
-        1. Let response be the result of <a>get a fetch result</a>, given |url| and |settingsObject|.
-        2. Let |source| be the result of running the <a>UTF-8 decode</a> algorithm on response's <a>unsafe response</a>'s <a>body</a>.
-        3. Let |script| be the result of running <a>create an isolated script</a> using |source| as the script source, the <a>URL</a> from which source was obtained, and |settingsObject| as the environment settings object.
-
-            Parse the newly created |script|. If it failed to parse, then reject the |promise| and abort all these steps.
-
-        4. Add |script| to the list of the <b>worklet's loaded scripts</b>.
-    6. For each {{WorkletGlobalScope}} in the <b>worklet's {{WorkletGlobalScope}}s</b>, run these substeps.
-        1. For each newly created |script| in <b>worklet's loaded scripts</b> run the script in the {{WorkletGlobalScope}}.
-    7. If <em>all</em> the steps above succeeded (in particular, if all of the scripts parsed and loaded into the global scopes), resolve |promise|
-        <br>Otherwise, reject |promise|.
- 3. Return |promise|.
+    1. If there are no arguments, return without doing anything. Abort these steps.
 
-Issue(w3c/css-houdini-drafts#51): What should happen when a script throws an exception while executing for the first time?
+    2. Let |resolvedModuleURL| be the result of <a>resolving</a> the |moduleURL| relative to the
+        <a>API base URL</a> specified by the <a>entry settings object</a> when the method was
+        invoked.
+
+    3. If this fails, reject |promise| with a <a>SyntaxError</a> exception and abort these steps.
 
-Issue(w3c/css-houdini-drafts#52): Is importScripts the right API call? Should it be singular instead?
+    4. Add |resolvedModuleURL| to the list of <b>worklet's resolved module URLs</b>.
 
-When a user agent is to <dfn>create an isolated script</dfn> given some |scriptSource|, an <a>environment settings object</a>,
-it must run the following steps:
-    1. Let |script| be a new script that this algorithm will subsequently initialise.
-    2. Obtain the appropriate <a>script execution environment</a> for the given scripting language from the <a>environment settings object</a> provided.
-    3. Let |kind| be Normal.
+    5. For each {{WorkletGlobalScope}} in the <b>worklet's WorkletGlobalScopes</b>, run these
+        substeps:
+        1. Let |settings| be the {{WorkletGlobalScope}}'s associated
+            <a>environment settings object</a>.
 
-        Let |parameterList| be an empty list.
+        2. Let |script| be the result of <a>fetch a module script tree</a> given
+            |resolvedModuleURL|, "anonymous" for the <a>CORS setting attribute</a>, and |settings|.
 
-        Let |parsedBodySource| be the result of parsing |scriptSource| as a <a>FunctionBody</a> using the <a>script execution environment</a>.
+        Issue: Decide if "use-credientials" should be valid for worklets.
 
-        Let |strict| be true.
+        3. <a>Run a module script</a> given |script|.
 
-        Let |scope| be the result of <a>NewObjectEnvironment</a>(O=<em>null</em>, E=<em>the global environment</em>).
-    4. Let |function| be the result of <a>FunctionCreate</a>(kind=|kind|, ParameterList=|parameterList|, Body=|parsedBodySource|, Scope=|scope|, Strict=|strict|).
-    5. Let |script|'s <a>code entry-point</a> be |function|.
-    6. Return |script|.
+    6. If <em>all</em> the steps above succeeded (in particular, if all of the scripts parsed and
+            loaded into the global scopes), resolve |promise|
+            <br>Otherwise, reject |promise|.
+
+ 3. Return |promise|.
+
+Issue(w3c/css-houdini-drafts#51): What should happen when a script throws an exception while executing for the first time?
 
 Issue(w3c/css-houdini-drafts#47): Need ability to load code into {{WorkletGlobalScope}} declaratively.
 
@@ -302,16 +294,20 @@ Lifetime of the Worklet {#lifetime-of-the-worklet}
 
 The lifetime of a {{Worklet}} is tied to the object it belongs to, for example the {{Window}}.
 
-The lifetime of a {{WorkletGlobalScope}} is tied to the execution lifetime of a method or set of methods on a class, not to the lifetime of the {{Worklet}} object.
+The lifetime of a {{WorkletGlobalScope}} is tied to the execution lifetime of a method or set of
+methods on a class, not to the lifetime of the {{Worklet}} object.
 
-The user agent <em>may</em> terminate a {{WorkletGlobalScope}} at any time it has no callbacks to handle or detects abnormal operation such as infinite loops and
-callbacks exceeding imposed time limits.
+The user agent <em>may</em> terminate a {{WorkletGlobalScope}} at any time it has no callbacks to
+handle or detects abnormal operation such as infinite loops and callbacks exceeding imposed time
+limits.
 
 Issue(w3c/css-houdini-drafts#53): Worth adding dispose to classes to allow clean-up?
 
 Processing Model {#processing-model}
 ------------------------------------
 
+Issue: Split this up.
+
 The <a>invoke a method on a class inside a Worklet</a> has two hooks for algorithm steps that may be customized by any callers:
     - <dfn export>lookup a class instance on a worklet global scope</dfn>
 
@@ -381,21 +377,21 @@ Loading scripts into a worklet. {#example-single}
 -------------------------------------------------
 
 <pre class='lang-javascript'>
-window.fakeWorklet1.importScripts('script1.js');
-window.fakeWorklet1.importScripts('script2.js', 'script3.js');
+window.fakeWorklet1.import('script1.js');
+window.fakeWorklet1.import('script2.js');
 
 // Assuming no other calls to fakeWorklet1 valid script loading orderings are:
-// 1. 'script1.js', 'script2.js', 'script3.js'
-// 2. 'script2.js', 'script3.js', 'script1.js'
+// 1. 'script1.js', 'script2.js'
+// 2. 'script2.js', 'script1.js'
 </pre>
 
 Loading scripts into multiple worklets. {#example-multiple}
 -----------------------------------------------------------
 
 <pre class='lang-javascript'>
 Promise.all([
-    window.fakeWorklet1.importScripts('script1.js'),
-    window.fakeWorklet2.importScripts('script2.js')
+    window.fakeWorklet1.import('script1.js'),
+    window.fakeWorklet2.import('script2.js')
 ]).then(function() {
     // Both scripts now have loaded code, can do a task which relies on this.
 });
@@ -414,7 +410,7 @@ registerAnArbitaryClass('foo', class FooClass {
 </pre>
 
 When the user agent wants to invoke <b>process</b> on an instance of class with key <b>foo</b> it will:
-    1. Call <a>invoke a method on a class inside a {{Worklet}}</a> given <b>process</b> as the
+    1. Call <a>invoke a method on a class inside a Worklet</a> given <b>process</b> as the
         |methodPropertyKey|, FakeWorkletGlobalScope as |workletGlobalScopeType| and some |arguments| with the following options:
             - To <a>lookup a class instance on a worklet global scope</a> given a |workletGlobalScope|, the user agent will:
                 1. Let |classConstructor| be the result of looking up <b>foo</b> on the |workletGlobalScope|'s map of <b>registered class constructors</b>.
