Initial resource timing integration.

Created a "fetch timing info" struct to hold the bookkeeping
necessary for resource timing.

Populated it with some of the required values, leaving some of
them for later patches as this is a big undertaking.

See w3c/resource-timing#252

Author: noamr

fetch.bs

@@ -194,8 +194,76 @@ lt="authentication entry">authentication entries</a> (for HTTP authentication).
 
  <dt><dfn for="fetch params">task destination</dfn> (default null)
  <dd>Null, a <a for=/>global object</a>, or a <a for=/>parallel queue</a>.
+ <dt><dfn for="fetch params">timing info</dfn>
+ <dd>A <a for=/>fetch timing info</a>.
+ <dt><dfn for="fetch params">redirect timing info list</dfn>(default an empty list)
+ <dd>A list of <a for=/>redirect timing info</a>
 </dl>
 
+<p>A <dfn export>fetch timing info</dfn> is a <a for=/>struct</a> used to maintain timing
+information later required by the resource timing and navigation timing specs. It has the following
+<a for=struct>items</a>:
+<dl>
+  <dt><dfn export for="fetch timing info">fetch start time</dfn> (default zero)
+  <dt><dfn export for="fetch timing info">worker start time</dfn> (default zero)
+  <dt><dfn export for="fetch timing info">request start time</dfn> (default zero)
+  <dt><dfn export for="fetch timing info">response start time</dfn> (default zero)
+  <dt><dfn export for="fetch timing info">response end time</dfn> (default zero)
+  <dd>A <a for=/>DOMHighResTimeStamp</a>.
+  <dt><dfn export for="fetch timing info">encoded body size</dfn> (default zero)
+  <dt><dfn export for="fetch timing info">decoded body size</dfn> (default zero)
+  <dd>A number.
+  <dt><dfn export for="fetch timing info">connection timing info</dfn> (default null)
+  <dd>Null or a <a for=/>connection timing info</a>.
+</dl>
+
+<p>A <dfn export>redirect timing info</dfn> is a <a for=/>struct</a> used to maintain timing
+information about a redirect.
+<a for=struct>items</a>:
+<dl>
+  <dt><dfn export for="redirect timing info">redirect location URL</dfn>
+  <dd>A URL.
+  <dt><dfn export for="redirect timing info">timing info</dfn>
+  <dd>A <a for=/>fetch timing info</a>.
+</dl>
+
+<p>A <dfn export>connection timing info</dfn> is a <a for=/>struct</a> used to maintain timing
+information pertaining to the process of obtaining a connection. It has the following
+<a for=struct>items</a>:
+<dl>
+  <dt><dfn export for="connection timing info">domain lookup start time</dfn> (default zero)
+  <dt><dfn export for="connection timing info">domain lookup end time</dfn> (default zero)
+  <dt><dfn export for="connection timing info">connection start time</dfn> (default zero)
+  <dt><dfn export for="connection timing info">connection end time</dfn> (default zero)
+  <dt><dfn export for="connection timing info">secure connection start time</dfn> (default zero)
+  <dd>A <a for=/>DOMHighResTimeStamp</a>
+  <dt><dfn export for="connection timing info">alpn negotiated protocol</dfn> (default empty string)
+  <dd>A string.
+</dl>
+
+<p><dfn data-cite="hr-time-2#dom-domhighrestimestamp">DOMHighResTimeStamp</dfn> and
+<dfn data-cite="hr-time-2#dfn-unsafe-shared-current-time">unsafe shared current time</dfn> </code>
+are defined in [[HR-TIME]].
+
+<p class=note>Note that timestamps in this spec are usually unsafe, and are meant to be coarsened
+and normalized to a <a for=/>global object</a> prior to being exposed.
+
+<p>To <dfn>clamp connection timing to fetch timing</dfn>, given <a for=/>connection timing info</a>
+<var>timingInfo</var> and <a for=/>DOMHighResTimeStamp</a> <var>defaultStartTime</var>, run these
+steps:
+<ol>
+ <li><p>If <var>timingInfo</var>'s <a for="connection timing info">connection start time</a> is
+ greater than <var>defaultStartTime</var>, then return <var>timingInfo</var>.
+
+ <li><p>Otherwise, return a new <a for=/>connection timing info</a>, with
+ <a for="connection timing info">domain lookup start time</a> set to <var>defaultStartTime</var>,
+ <a for="connection timing info">domain lookup end time</a> set to <var>defaultStartTime</var>,
+ <a for="connection timing info">connection start time</a> set to <var>defaultStartTime</var>,
+ <a for="connection timing info">connection end time</a> set to <var>defaultStartTime</var>,
+ <a for="connection timing info">secure connection start time</a> set to
+ <var>defaultStartTime</var>, and <a for="connection timing info">alpn negotiated protocol</a>
+ set to <var>timingInfo</var>'s <a for="connection timing info">alpn negotiated protocol</a>.
+
 <p>To <dfn>queue a fetch task</dfn>, given an algorithm <var>algorithm</var>, a
 <a for=/>global object</a> or a <a for=/>parallel queue</a> <var>taskDestination</var>, run these
 steps:
@@ -1926,6 +1994,14 @@ description of the attack.
 <dfn for=response id=concept-response-timing-allow-passed>timing allow passed flag</dfn>, which is
 initially unset.
 
+<p>A <a for=/>response</a> can have an associated
+<dfn export for=response id=concept-response-timing-info>timing info</dfn>, which is Null or a
+<a for=/>fetch timing info</a>, initially set to null.
+
+<p>A <a for=/>response</a> has an associated
+<dfn export for=response id=concept-response-redirect-timing-info-list>redirect timing info list</dfn>,
+which is initially set to an empty <a for=/>list</a>.
+
 <p class=note>This is used so that the caller to a fetch can determine if sensitive timing data is
 allowed on the resource fetched by looking at the flag of the response returned. Because the flag on
 the response of a redirect has to be set if it was set for previous responses in the redirect chain,
@@ -2148,6 +2224,9 @@ unset or <a for=request>keepalive</a> is false, <a lt=terminated for=fetch>termi
 identified by a <b>key</b> (a <a>network partition key</a>), an <b>origin</b> (an
 <a for=/>origin</a>), and <b>credentials</b> (a boolean).
 
+<p>Each <a>connection</a> has an associated <a for=/>connection timing info</a>
+<dfn for=connection>timingInfo</dfn>.
+
 <p>To <dfn export id=concept-connection-obtain>obtain a connection</dfn>, given a <var>key</var>,
 <var>origin</var>, <var>credentials</var>, an optional boolean <var>forceNew</var> (default false),
 an optional boolean <dfn export for="obtain a connection"><var>http3Only</var></dfn> (default
@@ -2179,8 +2258,9 @@ false), and an optional boolean <dfn export for="obtain a connection"><var>dedic
   <ol>
    <li>
     <p>Set <var>connection</var> to the result of establishing an HTTP connection to
-    <var>origin</var>. [[!HTTP]] [[!HTTP-SEMANTICS]] [[!HTTP-COND]] [[!HTTP-CACHING]] [[!HTTP-AUTH]]
-    [[!TLS]]
+    <var>origin</var>, following the requirements for
+    <a>recording <var>connection</var> timing info</a>.
+    [[!HTTP]] [[!HTTP-SEMANTICS]] [[!HTTP-COND]] [[!HTTP-CACHING]] [[!HTTP-AUTH]] [[!TLS]]
 
     <p>If <var>http3Only</var> is true, then establish an HTTP/3 connection. [[!HTTP3]]
 
@@ -2219,6 +2299,88 @@ clearly stipulates that <a>connections</a> are keyed on
 <!-- See https://github.com/whatwg/fetch/issues/114#issuecomment-143500095 for when we make
      WebSocket saner -->
 
+<p>The requirements for <dfn>recording connection timing info</dfn> given a <var>connection</var>
+and its <a for=/>connection timing info</a> <var>timingInfo</var>, are as follows:
+<ul>
+ <li><p><var>timingInfo</var>'s <a for="connection timing info">domain lookup start time</a>
+ SHOULD be the <a for=/>unsafe shared current time</a> immediately before starting the domain
+ lookup, or beginning retrieval of the information from cache.
+
+ <li><p><var>timingInfo</var>'s <a for="connection timing info">domain lookup end time</a> SHOULD
+ be the <a for=/>unsafe shared current time</a> immediately after finishing the domain lookup, or
+ retrieving the information from cache.
+
+ <li><p><var>timingInfo</var>'s <a for="connection timing info">connection start time</a> SHOULD
+ be the <a for=/>unsafe shared current time</a> immediately before establishing the connection to
+ the server or proxy.
+
+ <li><p><var>timingInfo</var>'s <a for="connection timing info">connection end time</a> SHOULD be
+ the <a for=/>unsafe shared current time</a> immediately after establishing the connection to the
+ server or proxy, as follows:
+ <ul>
+  <li><p>The returned time MUST include the time interval to establish the transport
+  connection, as well as other time intervals such as SOCKS authentication. It
+  MUST include the time interval to complete enough of the TLS handshake to
+  request the resource.
+
+  <li><p>If the user agent used TLS False Start [[RFC7918]] for this connection,
+  this interval MUST NOT include the time needed to receive the server's
+  Finished message.
+
+  <li><p>If the user agent sends the request with early data [[RFC8470]] without
+  waiting for the full handshare to complete, this interval MUST NOT include
+  the time needed to receive the server's ServerHello message.
+
+  <li><p>If the user agent waits for full handshake completion to send the
+  request, this interval includes the full TLS handshake even if other
+  requests were sent using early data on <var>connection</var>.
+ </ul>
+
+ <p class=note>Example: Suppose the user agent establishes an HTTP/2 connection
+ over TLS 1.3 to send a GET request and a POST request. It sends the ClientHello
+ at time <code>t1</code> and then sends the GET request with early data. The
+ POST request is not safe [[HTTP-SEMANTICS]] (section 4.2.1), so the user agent waits
+ to complete the handshake at time <code>t2</code> before sending it.  Although
+ both requests used the same connection, the GET request reports a connectEnd
+ value of <code>t1</code>, while the POST request reports a connectEnd value for
+ <code>t2</code>.
+
+  <li><p>If a secure transport is used, set <var>timingInfo</var>'s
+  <a for="connection timing info">secure connection start time</a> to the result of calling
+  <a for=/>unsafe shared current time</a> immmediately before starting the handshake process to
+  secure <var>connection</var>. [[!TLS]]
+
+  <li><p>Set <var>timingInfo</var>'s <a for="connection timing info">alpn negotiated protocol</a>
+  to the <var>connection</var>'s ALPN Protocol ID as specified in [[RFC7301]], with the
+  following caveats:
+  <ul>
+   <li><p>When a proxy is configured, if a tunnel connection is established then this attribute
+   MUST return the ALPN Protocol ID of the tunneled protocol, otherwise it MUST return the ALPN
+   Protocol ID of the first hop to the proxy.
+
+   <li><p>Octets in the ALPN protocol MUST NOT be percent-encoded if they are valid token
+   characters except "%", and when using percent-encoding, uppercase hex digits MUST be used.
+
+   <li><p>Formally registered ALPN protocol IDs are documented by <a href=
+   "https://www.iana.org/assignments/tls-extensiontype-values/tls-extensiontype-values.xhtml#alpn-protocol-ids">
+   IANA</a>.
+
+   <li><p>In case the user agent is using an experimental, non-registered protocol, the user
+   agent MUST use the ALPN negotiated value if any. If ALPN was not used for protocol
+   negotiations, the user agent MAY use another descriptive string.
+
+   <p class="note">The "h3" ALPN ID is defined for the final version
+   of the HTTP/3 protocol in the
+   <a href="https://tools.ietf.org/html/draft-ietf-quic-http-17#section-10.1">HTTP/3
+   Internet Draft</a>.
+
+   <p class="note">Note that <a for="connection timing info">alpn negotiated protocol</a> is
+   intended to identify the network protocol in use for the fetch regardless of how it was
+   actually negotiated; that is, even if ALPN is not used to negotiate the network protocol,
+   this attribute still uses the ALPN Protocol IDs to indicate the protocol in use.
+  </ul>
+ </ul>
+</ol>
 
 <h3 id=network-partition-keys>Network partition keys</h3>
 
@@ -3362,6 +3524,7 @@ the request.
 
  <li><p>Let <var>fetchParams</var> be a new <a for=/>fetch params</a> whose
  <a for="fetch params">request</a> is <var>request</var>,
+ <a for="fetch params">timing info</a> is a new <a for=/>fetch timing info</a>,
  <a for="fetch params">process request body</a> is <var>processRequestBody</var>,
  <a for="fetch params">process request end-of-body</a> is <var>processRequestEndOfBody</var>,
  <a for="fetch params">process response</a> is <var>processResponse</var>,
@@ -3450,6 +3613,10 @@ steps:
 
  <li><p>Let <var>response</var> be null.
 
+ <li><p>Set <var>fetchParams</var>'s <a for="fetch params">timing info</a> be a new
+ <a for=/>fetch timing info</a> with its <a for="fetch timing info">fetch start time</a> set to the
+ <a for=/>unsafe shared current time</a>.
+
  <li><p>If <var>request</var>'s <a>local-URLs-only flag</a> is set and <var>request</var>'s
  <a for=request>current URL</a> is not <a lt="is local">local</a>, then set <var>response</var> to a
  <a>network error</a>.
@@ -3746,6 +3913,8 @@ steps:
 <a for=/>response</a> <var>response</var>, run these steps:
 
 <ol>
+ <li><p><a for=/>Finalize timing info</a> with <var>fetchParams</var> and <var>response</var>.
+
  <li><p>If <var>fetchParams</var>'s <a for="fetch params">process response</a> is non-null, then
  <a>queue a fetch task</a> to run <var>fetchParams</var>'s
  <a for="fetch params">process response</a> given <var>response</var>, with <var>fetchParams</var>'s
@@ -3779,6 +3948,32 @@ steps:
  <!-- This is really bad and needs to be handled differently at some point. -->
 </ol>
 
+<p>To <dfn>finalize timing info</dfn>, given <a for=/>fetch params</a> <var>fetchParams</var> and
+<a for=/>response</a> <var>response</var>, perform the following steps:
+<ol>
+  <li><p>Let <var>timingInfo</var> be <var>fetchParams</var>'s
+  <a for="fetch params">timing info</a>.
+
+  <li><p>Let <var>startTime</var> be <var>timingInfo</var>'s
+  <a for="fetch timing info">fetch start time</a>.
+
+  <li><p>Let <var>redirectTimings</var> be <var>fetchParams</var>'s
+  <a for="fetch params">redirect timing info list</a>.
+
+  <li><p>If <var>redirectTimings</var> is not empty, then set <var>startTime</var> to
+  <a for="fetch params">redirect timing info list</a> first item's
+  <a for="redirect timing info">timing info</a>'s <A for="fetch timing info">fetch start time</a>.
+
+  <li><p>If <var>response</var>'s <a for=response>timing allow passed flag</a> is set, then set
+  <var>response</var>'s <a for=response>timing info</a> to <var>fetchParams</var>'s
+  <a for="fetch params">timing info</a> to <var>timingInfo</var> and <var>response</var>'s
+  <a for=response>redirect timing info list</a> to <var>redirectTimings</var>.
+
+  <li><p>Otherwise, set <var>response</var>'s <a for=response>timing info</a> to a new
+  <a for=/>fetch timing info</a>, with its <a for="fetch timing info">fetch start time</a>
+  set to <var>startTime</var>.
+</ol>
+
 
 <h3 id=scheme-fetch oldids=basic-fetch>Scheme fetch</h3>
 
@@ -3902,20 +4097,28 @@ these steps:
 
  <li><p>Let <var>actualResponse</var> be null.
 
+ <li><p>Let <var>timingInfo</var> be <var>fetchParams</var>'s <a for="fetch params">timing info</a>
+
  <li>
   <p>If <var>request</var>'s <a>service-workers mode</a> is "<code>all</code>", then:
 
   <ol>
    <li><p>Let <var>requestForServiceWorker</var> be a <a for=request>clone</a> of
    <var>request</var>.
 
+   <li><p>Set <var>fetchParams</var>'s <a for="fetch params">timing info</a>'s
+   <a for="fetch timing info">worker start time</a> to the <a for=/>unsafe shared current time</a>.
+
    <li><p>Set <var>response</var> to the result of invoking <a for=/>handle fetch</a> for
    <var>requestForServiceWorker</var>. [[!HTML]] [[!SW]]
 
    <li>
     <p>If <var>response</var> is not null, then:
 
     <ol>
+     <li><p>Set <var>fetchParams</var>'s <a for="fetch params">timing info</a>'s
+     <a for="fetch timing info">response start time</a> to the <a for=/>unsafe shared current time</a>.
+
      <li>If <var>request</var>'s <a for=request>body</a> is non-null, then
      <a for=ReadableStream>cancel</a> <var>request</var>'s <a for=request>body</a> with undefined.
 
@@ -3946,6 +4149,9 @@ these steps:
     </ol>
   </ol>
 
+  <p>Otheriwse, set <var>fetchParams</var>'s <a for="fetch params">timing info</a>'s
+  <a for="fetch timing info">worker start time</a> to the zero.
+
  <li>
   <p>If <var>response</var> is null, then:
 
@@ -4133,6 +4339,14 @@ run these steps:
   <p class="note no-backref"><var>request</var>'s <a for=request>body</a>'s <a for=body>source</a>'s
   nullity has already been checked.
 
+ <li><p>Let <var>redirectInfo</var> be a new <a for=/>redirect timing info</a> with its
+ <a for="redirect timing info">redirect location URL</a> set to <var>locationURL</var> and its
+ <a for="redirect timing info">timing info</a> set to <var>fetchParams</var>'s
+ <a for="fetch params">timing info</a>.
+
+ <li><p>Append <var>redirectInfo</var> to <var>fetchParams</var>'s
+ <a for="fetch params">redirect timing info list</a>.
+
  <li><p><a for=list>Append</a> <var>locationURL</var> to <var>request</var>'s
  <a for=request>URL list</a>.
 
@@ -4720,6 +4934,8 @@ optional boolean <var>forceNewConnection</var> (default false), run these steps:
 
  <li><p>Let <var>response</var> be null.
 
+ <li><p>Let <var>timingInfo</var> be <var>fetchParams</var>'s <a for="fetch params">timing info</a>.
+
  <li><p>Let <var>httpCache</var> be the result of <a>determining the HTTP cache partition</a>, given
  <var>httpRequest</var>.
 
@@ -4745,6 +4961,11 @@ optional boolean <var>forceNewConnection</var> (default false), run these steps:
    <var>includeCredentials</var>, and <var>forceNewConnection</var>.
   </dl>
 
+ <li>Set <var>timingInfo</var>'s <a for="fetch timing info">connection timing info</a> to the
+ result of calling <a>clamp connection timing to fetch timing</a> with <var>connection</var>'s
+ <a for=connection>timingInfo</a> and <var>timingInfo</var>'s
+ <a for="fetch timing info">fetch start time</a>.
+
  <li>
   <p>Run these steps, but <a>abort when</a> the ongoing fetch is <a for=fetch>terminated</a>:
 
@@ -4758,13 +4979,21 @@ optional boolean <var>forceNewConnection</var> (default false), run these steps:
    `<code>Transfer-Encoding</code>`/`<code>chunked</code>` to <var>request</var>'s
    <a for=request>header list</a>.
 
+   <li>Set <var>timingInfo</var>'s <a for="fetch timing info">request start time</a> to
+   <a for=/>unsafe shared current time</a>.
+
    <li>
     <p>Set <var>response</var> to the result of making an HTTP request over <var>connection</var>
     using <var>request</var> with the following caveats:
 
     <ul>
      <li><p>Follow the relevant requirements from HTTP. [[!HTTP]] [[!HTTP-SEMANTICS]] [[!HTTP-COND]] [[!HTTP-CACHING]] [[!HTTP-AUTH]]
 
+     <li><p>Set <var>timingInfo</var>'s <a for="fetch timing info">response start time</a> to
+     the <a for=/>unsafe shared current time</a>immediately after the user agent's HTTP parser
+     receives the first byte of the response (e.g. frame header bytes for HTTP/2, or response
+     status line for HTTP/1.x).
+
      <li><p>Wait until all the <a for=/>headers</a> are transmitted.
 
      <li>
@@ -4943,13 +5172,19 @@ optional boolean <var>forceNewConnection</var> (default false), run these steps:
          <li><p>Let <var>codings</var> be the result of <a>extracting header list values</a> given
          `<code>Content-Encoding</code>` and <var>response</var>'s <a for=response>header list</a>.
 
+         <li><p>Increase <var>timingInfo</var>'s <a for="fetch timing info">encoded body size</a>
+         by <var>bytes</var>'s <a for="byte sequence">length</a>.
+
          <li>
           <p>Set <var>bytes</var> to the result of <a lt="handle content codings">handling content
           codings</a> given <var>codings</var> and <var>bytes</var>.
 
           <p class="note no-backref">This makes the `<code>Content-Length</code>` <a for=/>header</a>
           unreliable to the extent that it was reliable to begin with.
 
+         <li><p>Increase <var>timingInfo</var>'s <a for="fetch timing info">decoded body size</a> by
+         <var>bytes</var>'s <a for="byte sequence">length</a>.
+
          <li><p>If <var>bytes</var> is failure, then <a lt=terminated for=fetch>terminate</a> the
          ongoing fetch.
 
@@ -4965,7 +5200,7 @@ optional boolean <var>forceNewConnection</var> (default false), run these steps:
 
        <li><p>Otherwise, if the bytes transmission for <var>response</var>'s message body is done
        normally and <var>stream</var> is <a for=ReadableStream>readable</a>, then
-       <a for=ReadableStream>close</a> <var>stream</var> and abort these in-parallel steps.
+       <a for=ReadableStream>close</a> <var>stream</var>, and abort these in-parallel steps.
       </ol>
     </ol>