Add support for a new ReadableStream "transfer" type.

Author: youennf

index.bs

@@ -19,6 +19,7 @@ spec:infra; type:dfn; text:list
 spec:html; type:dfn; text:entangle
 spec:html; type:dfn; text:message port post message steps
 spec:html; type:dfn; text:port message queue
+spec:html; type:dfn; text:transferable objects
 </pre>
 
 <pre class="anchors">
@@ -571,7 +572,7 @@ callback UnderlyingSourceStartCallback = any (ReadableStreamController controlle
 callback UnderlyingSourcePullCallback = Promise<undefined> (ReadableStreamController controller);
 callback UnderlyingSourceCancelCallback = Promise<undefined> (optional any reason);
 
-enum ReadableStreamType { "bytes" };
+enum ReadableStreamType { "bytes", "transfer" };
 </xmp>
 
 <dl>
@@ -639,8 +640,7 @@ enum ReadableStreamType { "bytes" };
    something more persistently wrong.
   </div>
 
- <dt><dfn dict-member for="UnderlyingSource" lt="type"><code>type</code></dfn> (byte streams
- only)</dt>
+ <dt><dfn dict-member for="UnderlyingSource" lt="type"><code>type</code></dfn></dt>
  <dd>
   <p>Can be set to "<dfn enum-value for="ReadableStreamType">bytes</dfn>" to signal that the
   constructed {{ReadableStream}} is a <a>readable byte stream</a>. This ensures that the resulting
@@ -651,6 +651,14 @@ enum ReadableStreamType { "bytes" };
   <p>For an example of how to set up a readable byte stream, including using the different
   controller interface, see [[#example-rbs-push]].
 
+  <p>Can be set to "<dfn enum-value for="ReadableStreamType">transfer</dfn>" to signal that the
+  constructed {{ReadableStream}} will transfer or serialize chunks before enqueuing them.
+  This ensures that enqueued chunks are not mutable by the source.
+  Transferred or serialized chunks may have <dfn>closing steps</dfn> which are executed if
+  enqueued chunks are dequeued without being provided to the application, for instance when
+  a {{ReadableStream}} is errored.
+  </p>
+
   <p>Setting any value other than "{{ReadableStreamType/bytes}}" or undefined will cause the
   {{ReadableStream()}} constructor to throw an exception.
 
@@ -801,7 +809,8 @@ option. If {{UnderlyingSource/type}} is set to undefined (including via omission
   1. Perform ? [$SetUpReadableByteStreamControllerFromUnderlyingSource$]([=this=],
      |underlyingSource|, |underlyingSourceDict|, |highWaterMark|).
  1. Otherwise,
-  1. Assert: |underlyingSourceDict|["{{UnderlyingSource/type}}"] does not [=map/exist=].
+  1. Assert: |underlyingSourceDict|["{{UnderlyingSource/type}}"] does not [=map/exist=] or
+     is "{{ReadableStreamType/transfer}}".
   1. Let |sizeAlgorithm| be ! [$ExtractSizeAlgorithm$](|strategy|).
   1. Let |highWaterMark| be ? [$ExtractHighWaterMark$](|strategy|, 1).
   1. Perform ? [$SetUpReadableStreamDefaultControllerFromUnderlyingSource$]([=this=],
@@ -1523,6 +1532,9 @@ the following table:
   <tr>
    <td><dfn>\[[stream]]</dfn>
    <td class="non-normative">The {{ReadableStream}} instance controlled
+  <tr>
+   <td><dfn>\[[isTransferring]]</dfn>
+   <td class="non-normative">A boolean flag indicating whether to transfer enqueued chunks
 </table>
 
 <h4 id="rs-default-controller-prototype">Methods and properties</h4>
@@ -2235,8 +2247,8 @@ create them does not matter.
  objects|transferring=] their [=chunks=]. However, it does introduce a noticeable asymmetry between
  the two branches, and limits the possible [=chunks=] to serializable ones. [[!HTML]]
 
- If |stream| is a [=readable byte stream=], then |cloneForBranch2| is ignored and chunks are cloned
- unconditionally.
+ If |stream| is a [=readable byte stream=], or if |stream| type is "{{ReadableStreamType/transfer}}",
+ then |cloneForBranch2| is ignored and chunks are cloned unconditionally.
 
  <p class="note">In this standard ReadableStreamTee is always called with |cloneForBranch2| set to
  false; other specifications pass true via the [=ReadableStream/tee=] wrapper algorithm.
@@ -2247,6 +2259,8 @@ create them does not matter.
  1. Assert: |cloneForBranch2| is a boolean.
  1. If |stream|.[=ReadableStream/[[controller]]=] [=implements=] {{ReadableByteStreamController}},
     return ? [$ReadableByteStreamTee$](|stream|).
+ 1. If |stream|.[=ReadableStream/[[controller]]=].[=ReadableStreamDefaultController/[[isTransferring]]=]
+    is true, return ? [$ReadableStreamDefaultTee$](|stream|, true).
  1. Return ? [$ReadableStreamDefaultTee$](|stream|, |cloneForBranch2|).
 </div>
 
@@ -2955,8 +2969,12 @@ The following abstract operations support the implementation of the
  1. If ! [$ReadableStreamDefaultControllerCanCloseOrEnqueue$](|controller|) is false, return.
  1. Let |stream| be |controller|.[=ReadableStreamDefaultController/[[stream]]=].
  1. If ! [$IsReadableStreamLocked$](|stream|) is true and !
-    [$ReadableStreamGetNumReadRequests$](|stream|) > 0, perform !
-    [$ReadableStreamFulfillReadRequest$](|stream|, |chunk|, false).
+    [$ReadableStreamGetNumReadRequests$](|stream|) > 0, perform the following steps:
+    1. Let |internalChunk| be |chunk|.
+    1. If |controller|.[=ReadableStreamDefaultController/[[isTransferring]]=] is true, perform the following steps:
+       1. Set |internalChunk| to [$StructuredTransferOrSerialize$](|chunk|).
+       1. If |internalChunk| is an abrupt completion, return.
+    1. ![$ReadableStreamFulfillReadRequest$](|stream|, |internalChunk|, false).
  1. Otherwise,
   1. Let |result| be the result of performing
      |controller|.[=ReadableStreamDefaultController/[[strategySizeAlgorithm]]=], passing in |chunk|,
@@ -3029,7 +3047,7 @@ The following abstract operations support the implementation of the
  <dfn abstract-op lt="SetUpReadableStreamDefaultController"
  id="set-up-readable-stream-default-controller">SetUpReadableStreamDefaultController(|stream|,
  |controller|, |startAlgorithm|, |pullAlgorithm|, |cancelAlgorithm|, |highWaterMark|,
- |sizeAlgorithm|)</dfn> performs the following steps:
+ |sizeAlgorithm|, |isTransferring|)</dfn> performs the following steps:
 
  1. Assert: |stream|.[=ReadableStream/[[controller]]=] is undefined.
  1. Set |controller|.[=ReadableStreamDefaultController/[[stream]]=] to |stream|.
@@ -3039,8 +3057,9 @@ The following abstract operations support the implementation of the
     |controller|.[=ReadableStreamDefaultController/[[pullAgain]]=], and
     |controller|.[=ReadableStreamDefaultController/[[pulling]]=] to false.
  1. Set |controller|.[=ReadableStreamDefaultController/[[strategySizeAlgorithm]]=] to
-    |sizeAlgorithm| and |controller|.[=ReadableStreamDefaultController/[[strategyHWM]]=] to
-    |highWaterMark|.
+    |sizeAlgorithm|, |controller|.[=ReadableStreamDefaultController/[[strategyHWM]]=] to
+    |highWaterMark| and |controller|.[=ReadableStreamDefaultController/[[isTransferring]]=] to
+    |isTransferring|.
  1. Set |controller|.[=ReadableStreamDefaultController/[[pullAlgorithm]]=] to |pullAlgorithm|.
  1. Set |controller|.[=ReadableStreamDefaultController/[[cancelAlgorithm]]=] to |cancelAlgorithm|.
  1. Set |stream|.[=ReadableStream/[[controller]]=] to |controller|.
@@ -3065,6 +3084,9 @@ The following abstract operations support the implementation of the
  1. Let |startAlgorithm| be an algorithm that returns undefined.
  1. Let |pullAlgorithm| be an algorithm that returns [=a promise resolved with=] undefined.
  1. Let |cancelAlgorithm| be an algorithm that returns [=a promise resolved with=] undefined.
+ 1. Let |cancelAlgorithm| be an algorithm that returns [=a promise resolved with=] undefined.
+ 1. Let |isTransferring| be true if |underlyingSourceDict|["{{UnderlyingSource/pull}}"] is
+    "{{ReadableStreamType/transfer}}" and false otherwise.
  1. If |underlyingSourceDict|["{{UnderlyingSource/start}}"] [=map/exists=], then set
     |startAlgorithm| to an algorithm which returns the result of [=invoking=]
     |underlyingSourceDict|["{{UnderlyingSource/start}}"] with argument list
@@ -3078,7 +3100,7 @@ The following abstract operations support the implementation of the
     [=invoking=] |underlyingSourceDict|["{{UnderlyingSource/cancel}}"] with argument list
     «&nbsp;|reason|&nbsp;» and [=callback this value=] |underlyingSource|.
  1. Perform ? [$SetUpReadableStreamDefaultController$](|stream|, |controller|, |startAlgorithm|,
-    |pullAlgorithm|, |cancelAlgorithm|, |highWaterMark|, |sizeAlgorithm|).
+    |pullAlgorithm|, |cancelAlgorithm|, |highWaterMark|, |sizeAlgorithm|, |isTransferring|).
 </div>
 
 <h4 id="rbs-controller-abstract-ops">Byte stream controllers</h4>
@@ -6346,8 +6368,8 @@ In what follows, a <dfn>value-with-size</dfn> is a [=struct=] with the two [=str
 for="value-with-size">value</dfn> and <dfn for="value-with-size">size</dfn>.
 
 <div algorithm>
- <dfn abstract-op lt="DequeueValue" id="dequeue-value">DequeueValue(|container|)</dfn> performs the
- following steps:
+ <dfn abstract-op lt="DequeueValue" id="dequeue-value">DequeueValue(|container|)</dfn> performs
+ the following steps:
 
  1. Assert: |container| has \[[queue]] and \[[queueTotalSize]] internal slots.
  1. Assert: |container|.\[[queue]] is not [=list/is empty|empty=].
@@ -6368,7 +6390,11 @@ for="value-with-size">value</dfn> and <dfn for="value-with-size">size</dfn>.
  1. Assert: |container| has \[[queue]] and \[[queueTotalSize]] internal slots.
  1. If ! [$IsNonNegativeNumber$](|size|) is false, throw a {{RangeError}} exception.
  1. If |size| is +∞, throw a {{RangeError}} exception.
- 1. [=list/Append=] a new [=value-with-size=] with [=value-with-size/value=] |value| and
+ 1. Let |enqueuedValue| be |value|.
+ 1. If |container|.\[[isTransferring]] is true, perform the following steps:
+    1. Set |enqueuedValue| to [$StructuredTransferOrSerialize$](|value|).
+    1. If |enqueuedValue| is an abrupt completion, return.
+ 1. [=list/Append=] a new [=value-with-size=] with [=value-with-size/value=] |enqueuedValue| and
     [=value-with-size/size=] |size| to |container|.\[[queue]].
  1. Set |container|.\[[queueTotalSize]] to |container|.\[[queueTotalSize]] + |size|.
 </div>
@@ -6388,6 +6414,10 @@ for="value-with-size">value</dfn> and <dfn for="value-with-size">size</dfn>.
  performs the following steps:
 
  1. Assert: |container| has \[[queue]] and \[[queueTotalSize]] internal slots.
+ 1. If |container|.\[[isTransferring]] is true, perform the following steps until |container|.\[[queue]]
+    is [=list/is empty|empty=]:
+    1. Let |chunk| be ! [$DequeueValue$]([=this=]).
+    1. If |chunk| has [=closing steps=], perform the [=closing steps=] given |chunk|.
  1. Set |container|.\[[queue]] to a new empty [=list=].
  1. Set |container|.\[[queueTotalSize]] to 0.
 </div>
@@ -6596,6 +6626,18 @@ The following abstract operations are a grab-bag of utilities.
  1. Return ? [$StructuredDeserialize$](|serialized|, [=the current Realm=]).
 </div>
 
+<div algorithm>
+ <dfn abstract-op lt="StructuredTransferOrSerialize">StructuredTransferOrSerialize(|value|)</dfn>
+    performs the following steps:
+ 1. If |value| is [=transferable objects|transferable=], perform the following steps:
+    // FIXME: We should probably handle other transferable types like ArrayBuffers.
+    1. Let |serialized| be ! [$StructuredSerializeWithTransfer$](|value|, « |value| »).
+    1. Let |deserialized| be ! [$StructuredDeserializeWithTransfer$](|serialized|,
+       [=the current Realm=]).
+    1. return |deserialized|.\[[Deserialized]].
+ 1. return [$StructuredClone$](|value|).
+</div>
+
 <h2 id="other-specs">Using streams in other specifications</h2>
 
 Much of this standard concerns itself with the internal machinery of streams. Other specifications