From f29bcf98d862b67a60720312fcfab7c69bcbbcb7 Mon Sep 17 00:00:00 2001 From: Noam Rosenthal Date: Wed, 17 Mar 2021 15:23:09 +0200 Subject: [PATCH] WIP: Prepare for FETCH integration - Remove duplicates that are moved to FETCH - Add an exported algorithm to mark resource timing --- index.html | 783 ++++++++--------------------------------------------- 1 file changed, 109 insertions(+), 674 deletions(-) diff --git a/index.html b/index.html index 1411cd8..c6880c8 100644 --- a/index.html +++ b/index.html @@ -61,7 +61,7 @@ subjectPrefix: "[ResourceTiming]", github: "https://github.com/w3c/resource-timing/", caniuse: "resource-timing", - xref: ["html", "hr-time-2", "performance-timeline-2"], + xref: ["html", "hr-time-3", "performance-timeline-2"], }; @@ -254,7 +254,7 @@

Resources Included in the PerformanceResourceTiming Performance Timeline, unless excluded from the timeline as part of the processing model. +href="FETCH#concept-fetch">fetching process. Resources that are retrieved from relevant application caches or local resources MUST be included as @@ -362,28 +362,16 @@

The PerformanceResourceTiming Interface

"PERFORMANCE-TIMELINE-2#the-performanceentry-interface">PerformanceEntry interface:

-
name
-
This attribute MUST return the resolved URL of the requested resource. -This attribute MUST NOT change even if the fetch redirected to a different URL.
+
name +
On getting, the name attribute returns the name of therequested URL
entryType
-
The entryType attribute MUST return the DOMString +
On getting, the entryType attribute returns the DOMString "resource".
startTime
-
The startTime attribute MUST return a {{DOMHighResTimeStamp}} -[[HR-TIME-2]] with the time immediately before the user agent -starts to queue the resource for fetching. If there are HTTP redirects or -equivalent when fetching the -resource, and if the timing allow check algorithm passes, this -attribute MUST return the same value as redirectStart. -Otherwise, this attribute MUST return the same value as -fetchStart.
-
duration
-
The duration attribute MUST return a {{DOMHighResTimeStamp}} equal -to the difference between responseEnd and startTime, -respectively.
+

On getting, the startTime attribute +returns the result of calling convert fetch timestamp given this's +timing info's +start time and the relevant global object for this.

DOMHighResTimeStamp is defined in [[HR-TIME-2]]. @@ -411,385 +399,85 @@

The PerformanceResourceTiming Interface

[Default] object toJSON(); }; -

When toJSON -is called, run [[WEBIDL]]'s default toJSON operation.

-

On getting, the -initiatorType attribute MUST return one of the following -DOMString values:

- -

On getting, the -attribute nextHopProtocol returns the network protocol -used to fetch the resource, as identified by the ALPN Protocol ID -[[RFC7301]]; resources retrieved from relevant application caches -or local resources, return an empty string. 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. In order to have precisely one way to -represent any ALPN protocol ID, the following additional -constraints apply: 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.

-

Formally registered ALPN protocol IDs are documented by -IANA. 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.

-

The "h3" ALPN ID is defined for the final version -of the HTTP/3 protocol in the HTTP/3 Internet Draft.

-

Note that the nextHopProtocol attribute 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 ID's to indicate the protocol in use.

-

On getting, the -workerStart attribute MUST return as follows:

-
    -
  1. -

    If the active -service worker of the context object's -relevant settings object is not -null and if the resource passes the timing allow check algorithm or the -resource Request's destination does not equal -"document":

    -
      -
    1. the time immediately before the user agent fires an event named -`fetch` at the active worker if the -worker is available.
      2. -
    2. the time immediately before the user agent runs the worker -required to service the request.
      3. -
    -
    2. -
  2. zero, otherwise.
    3. -
-

Note that according to the definition of time origin in workers, it is -possible that some attributes of -navigation preload requests will have negative {{DOMHighResTimeStamp}} -values.

-

On getting, the -redirectStart attribute MUST return as follows:

-
    -
  1. The time immediately before the user agent starts to -fetch the resource that -initiates the redirect, if there are HTTP redirects or -equivalent when fetching the resource and -the resource passes the timing allow check algorithm.
    2. -
  2. zero, otherwise.
    3. -
-

On getting, the -redirectEnd attribute MUST return as follows:

-
    -
  1. The time immediately after receiving the last byte of the -response of the last redirect, if there are HTTP redirects or -equivalent when fetching the resource and -the resource passes the timing allow check algorithm.
    2. -
  2. zero, otherwise.
    3. -
-

On getting, the -fetchStart attribute MUST return as follows:

-
    -
  1. The time immediately before the user agent starts to -fetch the final -resource in the redirection, if there are HTTP redirects or -equivalent.
    2. -
  2. The time immediately before the user agent starts to -fetch the resource -otherwise.
    3. -
-

On getting, the -domainLookupStart attribute MUST return as follows:

-
    -
  1. Zero, if the resource fails the timing allow check -algorithm.
    2. -
  2. The same value as fetchStart, if no domain lookup was -required to fetch the resources (e.g. if a persistent -connection [[RFC7230]] was used or in case the resource was -retrieved from relevant -application caches or local resources).
    3. -
  3. The time immediately after the user agent starts the domain -data retrieval from the domain information cache, if the user agent -has the domain information in cache.
    4. -
  4. The time immediately before the user agent starts the domain -name lookup for the resource, otherwise.
    5. -
-

On getting, the -domainLookupEnd attribute MUST return as follows:

-
    -
  1. Zero, if the resource fails the timing allow check -algorithm.
    2. -
  2. The same value as fetchStart, if no domain lookup was -required to fetch the resources (e.g. if a persistent -connection [[RFC7230]] was used or in case the resource was -retrieved from relevant -application caches or local resources).
    3. -
  3. The time immediately after the user agent ends the domain data -retrieval from the domain information cache, if the user agent has -the domain information in cache.
    4. -
  4. The time immediately after the user agent finishes the domain -name lookup for the resource, otherwise.
    5. -
-

On getting, the -connectStart attribute MUST return as follows:

-
    -
  1. Zero, if the resource fails the timing allow check -algorithm.
    2. -
  2. The same value as fetchStart, if a persistent connection [[RFC7230]] is used -or the resource is retrieved from relevant application caches or -local resources.
    3. -
  3. The time immediately before the user agent start establishing -the connection to the server to retrieve the resource, otherwise. -

    If the transport connection fails and the user agent reopens a -connection, connectStart SHOULD return the -corresponding value of the new connection.

    -
    4. -
-

On getting, the -connectEnd attribute MUST return as follows:

-
    -
  1. Zero, if the resource fails the timing allow check -algorithm.
    2. -
  2. The same value as fetchStart, if a persistent connection [[RFC7230]] is used -or the resource is retrieved from relevant application caches -or local resources.
    3. -
  3. The time immediately after the user agent finish establishing -the connection to the server to retrieve the resource, otherwise. - +

    A PerformanceResourceTiming has an associated +DOMString initiator type. -

      -
    • 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.
      • -
    • 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.
      • -
    • 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.
      • -
    • 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 this connection.
      • -
    +

    A PerformanceResourceTiming has an associated DOMstring +requested URL. -

    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 t1 and then sends the GET request with early data. The -POST request is not safe [[RFC7231]] (section 4.2.1), so the user agent waits -to complete the handshake at time t2 before sending it. Although -both requests used the same connection, the GET request reports a connectEnd -value of t1, while the POST request reports a connectEnd value for -t2.

    +

    A PerformanceResourceTiming has an associated +fetch timing info +timing info. -

    If the transport connection fails and the user agent reopens a -connection, connectEnd SHOULD return the -corresponding value of the new connection.

    -
    4. -
-

On getting, the -secureConnectionStart attribute MUST return as -follows:

-
    -
  1. Zero, if a secure transport is not used or if the resource fails -the timing allow check algorithm.
    2. -
  2. The same value as fetchStart, if a persistent connection [[RFC7230]] is used -or the resource is retrieved from relevant application caches -or local resources.
    3. -
  3. The time immediately before the user agent starts the handshake -process to secure the current connection, otherwise.
    4. -
-

On getting, the -requestStart attribute MUST return as follows:

-
    -
  1. The time immediately before the user agent starts requesting -the resource from the server, or from relevant application caches -or from local resources, if the resource passes the timing allow -check algorithm. -

    If the transport connection fails after a request is sent and -the user agent reopens a connection and resend the request, -requestStart MUST -return the corresponding values of the new request.

    -
    2. -
  2. zero, otherwise.
    3. -
- -

On getting, the -responseStart attribute MUST return as follows:

-
    -
  1. The time 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) from -relevant application -caches, or from local resources or from the server, if the -resource passes the timing allow check algorithm.
    2. -
  2. zero, otherwise.
    3. -
- -

On getting, the -responseEnd attribute MUST return the result of running -the algorithm to get response end time.

- -

When requested to run the get response end time -algorithm, the user agent must run the following steps:

-
    -
  1. If the fetch was aborted due to a network error, return the time -immediately before the user agent aborts the fetch.
    2. -
  2. Otherwise, return the time immediately after the user agent -receives the last byte of the response or immediately before the -transport connection is closed, whichever comes first. The resource -here can be received either from relevant application -caches, local resources, or from the server.
    3. -
-

On getting, the -transferSize attribute MUST return as follows:

-
    -
  1. the size, in octets received from a HTTP-network fetch, consumed by the -response header fields and the response payload body [[RFC7230]], if the -resource passes the timing allow check algorithm. -

    If there are HTTP redirects or equivalent when -navigating and if all the redirects or equivalent are same origin, this attribute SHOULD -include the HTTP overhead of incurred redirects.

    -

    This attribute SHOULD include HTTP overhead (such as HTTP/1.1 -chunked encoding and whitespace around header fields, including -newlines, and HTTP/2 -frame overhead, along with other server-to-client frames on the -same stream), but SHOULD NOT include lower-layer protocol overhead -(such as TLS [[RFC5246]]or TCP).

    - -
    2. -
  2. zero otherwise, including for resources retrieved from -relevant application -caches or from local resources.
    3. -
-

On getting, the -encodedBodySize attribute MUST return as follows:

-
    -
  1. The size, in octets, received from a HTTP-network-or-cache -fetch, of the payload body -[[RFC7230]], prior to removing any applied content-codings [[RFC7231]], if the -resource passes the timing allow check algorithm.
    2. -
  2. The size, in octets, of the payload body prior to removing any -applied content-codings -if the resource is retrieved from relevant application caches -or from local resources.
    3. -
  3. zero, otherwise.
    4. -
- +

When toJSON +is called, run [[WEBIDL]]'s default toJSON operation.

On getting, the -decodedBodySize attribute MUST return as follows:

-
    -
  1. The size, in octets, received from a HTTP-network-or-cache -fetch, of the message body -[[RFC7230]], after removing any applied content-codings [[RFC7231]], if the -resource passes the timing allow check algorithm.
    2. -
  2. The size, in octets, of the payload after removing any applied -content-codings, if the -resource is retrieved from relevant application caches -or from local resources.
    3. -
  3. zero, otherwise.
    4. +initiatorType attribute returns the initiator +type for this. +

    On getting, the duration attribute +returns the result of calling convert fetch timestamp given this's +timing info's +response end time minus this's +

    On getting, the nextHopProtocol attribute +returns the result of calling convert fetch timestamp given this's +timing info's +connection info's +alpn negotiated protocol and the relevant global object +for this. +

    On getting, the workerStart attribute +returns the result of calling convert fetch timestamp given this's +timing info's +worker start time and the relevant global object for this. +

    On getting, the redirectStart attribute +returns the result of calling convert fetch timestamp given this's +timing info's +worker start time and the relevant global object for this. +

    On getting, the redirectEnd attribute +returns the result of calling convert fetch timestamp given this's +timing info's +worker start time and the relevant global object for this. +

    On getting, the fetchStart attribute +returns the result of calling convert fetch timestamp given this's +timing info's +worker start time and the relevant global object for this. +

    On getting, the domainLookupStart attribute +returns the result of calling convert fetch timestamp given this's +timing info's +connection info's domain lookup start time and the +relevant global object for this. +

    On getting, the domainLookupEnd attribute +returns the result of calling convert fetch timestamp given this's +timing info's +connection info's domain lookup end time and the +relevant global object for this. +

    On getting, the connectStart attribute +returns the result of calling convert fetch timestamp given this's +timing info's +connection info's connection start time and the +relevant global object for this. +

    On getting, the connectEnd attribute +returns the result of calling convert fetch timestamp given this's +timing info's +connection info's connection end time and the +relevant global object for this. +

    On getting, the secureConnectionStart attribute +returns the result of calling convert fetch timestamp given this's +timing info's +connection info's secure connection start time and the +relevant global object for this. +

    On getting, the requestStart attribute +returns the result of calling convert fetch timestamp given this's +timing info's +request start time and the relevant global object for this. +

    On getting, the responseStart attribute +returns the result of calling convert fetch timestamp given this's +timing info's +response start time and the relevant global object for this. +

    On getting, the responseEnd attribute +returns the result of calling convert fetch timestamp given this's +timing info's +response end time and the relevant global object for this.

A user agent implementing PerformanceResourceTiming would need to include "resource" in Extensions to the Performance Interface -

-

Cross-origin Resources

-

Cross-origin resources -MUST be included as PerformanceResourceTiming objects in the -Performance -Timeline. If the timing allow check algorithm fails for -a resource, these attributes of its PerformanceResourceTiming -object MUST be set to zero: -redirectStart, redirectEnd, domainLookupStart, -domainLookupEnd, connectStart, connectEnd, -requestStart, responseStart, -secureConnectionStart, transferSize, -encodedBodySize and decodedBodySize.

-

Server-side applications may return the -Timing-Allow-Origin HTTP response header to allow the User -Agent to fully expose, to the document origin(s) specified, the -values of attributes that would have been zero due to the -cross-origin restrictions previously specified in this -section.

-
-

Timing-Allow-Origin Response Header

-

The Timing-Allow-Origin HTTP response header field -can be used to communicate a policy indicating origin(s) that are -allowed to see values of attributes that would have been zero due -to the cross-origin restrictions. The header's value is represented -by the following ABNF [[RFC5234]] (using List Extension, [[RFC7230]]):

-
-      Timing-Allow-Origin = 1#( origin-or-null / wildcard )
-
-

The sender MAY generate multiple Timing-Allow-Origin -header fields. The recipient MAY combine multiple -Timing-Allow-Origin header fields by appending each -subsequent field value to the combined field value in order, -separated by a comma.

-

The timing allow check algorithm, which checks -whether a resource's timing information can be shared with the -current document, is as follows:

+
+

Creating a resource timing entry

+

To mark resource timing given a +response |response|, a global object |global| and +a DOMString |initiatorType|, perform the following steps:

    -
  1. Let response be the resource's Response.
    2. -
  2. Return response's - timing allow passed flag.
    3. -
-

The Timing-Allow-Origin header may arrive as part of a cached -response. In case of cache revalidation, according to -RFC 7234, -the header's value may come from the revalidation response, or if not present -there, from the original cached resource.

-
-
-

IANA Considerations

-

This section registers Timing-Allow-Origin as a Provisional Message Header.

-
-
Header field name:
Timing-Allow-Origin
-
Applicable protocol:
http
-
Status:
provisional
-
Author/Change controller:
W3C
-
Specification document:
-
-
-
-
-

Process

-
-

Processing Model

-

The following graph illustrates the timing attributes defined by -the PerformanceResourceTiming interface. Attributes in parenthesis -may not be available when fetching cross-origin resources. User agents may -perform internal processing in between timings, which allow for non-normative -intervals between timings.

-
-
This figure illustrates the timing attributes defined -by the PerformanceResourceTiming interface. Attributes in -parenthesis indicate that they may not be available if the resource -fails the timing allow check algorithm.
- -Resource Timing attributes
- -

For each resource whose Request has a non-null client, perform -the following steps:

-
    -
  1. If the resource is fetched by a -cross-origin stylesheet which was fetched with no-cors policy, -abort the remaining steps. -

    Above cross-origin exclusion should be defined via -Fetch registry: CSS needs to be defined in terms of Fetch and set -some kind of "opaque request flag" for no-CORS CSS subresources. In -turn, Resource Timing should interface with Fetch registry to -surface resource fetch events.

    -

    The above resource exclusion is at risk as currently only one -implementation passes the related test.

    -
    2. -
  2. If the resource's Request's -destination equals to -"document", and the Request was not triggered by -process the iframe attributes or -process the frame attributes, -abort the remaining steps.
    3. -
  3. Create a new -PerformanceResourceTiming object and set -entryType to the DOMString resource.
    4. -
  4. Immediately before the user agent starts to queue the resource -for retrieval, record the current time in startTime, -and set nextHopProtocol to the empty DOMString.
    5. -
  5. Record the initiator of the resource in -initiatorType.
    6. -
  6. Record the resolved URL - of the requested resource in name.
    7. -
  7. Fetch start: Immediately before a -user agent starts the fetching process, record the current time -as fetchStart. Let domainLookupStart, -domainLookupEnd, connectStart and connectEnd -be the same value as fetchStart.
    8. -
  8. If the user agent is to -reuse the data from another existing or completed fetch initiated from the current -document, abort the remaining steps.
    9. -
  9. If there is an active -worker ([[service-workers-1]]) matching the current browsing or -worker context's, immediately before the user agent runs the worker -record the time as workerStart, or if the worker is already -available, immediately before the event named `fetch` -is fired at the active worker record the time as -workerStart. Otherwise, if there is no matching -service -worker registration, set workerStart value to zero.
    10. -
  10. If the resource fails the timing allow check algorithm, the user -agent MUST run the following substeps: -
      -
    1. If the resource's Request's - destination equals to - "document", set workerStart to zero. -
    2. Set redirectStart, redirectEnd, - domainLookupStart, domainLookupEnd, connectStart, - connectEnd, requestStart, responseStart and - secureConnectionStart to zero. -
    3. Go to the step labeled response - end.
      4. -
    -
  11. Let domainLookupStart, domainLookupEnd, -connectStart and connectEnd be the same value as -fetchStart.
    12. -
  12. If the resource is fetched from the relevant application cache or -local resources, including the HTTP cache [[RFC7234]], -go to the step labeled request -start.
    13. -
  13. If no domain lookup is required, go to the step labeled connect start. Otherwise, immediately -before a user agent starts the domain name lookup, record the time as -domainLookupStart.
    14. -
  14. Record the time as domainLookupEnd immediately after the -domain name lookup is successfully done. A user agent may need -multiple retries before that. If the domain name lookup fails and -resource passes the timing allow check record the time as -domainLookupEnd and go to the step labeledfinal record.
    15. -
  15. Connect start: If a persistent transport -connection is used to fetch -the resource, let connectStart and connectEnd -be the same value of domainLookupEnd. Otherwise, record the -time as connectStart immediately before initiating a successful -connection to the server and record the time as connectEnd -immediately after the successful connection to the server or proxy is -established. A user agent may need multiple retries to establish a -successful connection and should reflect the timestamps for the -successful connection only. -Once connection is established set the value of nextHopProtocol -to the ALPN ID used by the connection. If a connection can not be -established, record the time up to the connection failure as -connectEnd and go to the step labeled final record.
    16. -
  16. The user agent MUST set the secureConnectionStart -attribute as follows: -
      -
    1. When a secure transport is used, the user agent MUST record the -time as secureConnectionStart immediately before the -handshake process to secure the connection.
      2. -
    2. When a secure transport is not used, the user agent MUST set -the value of secureConnectionStart to 0.
      3. -
    -
    17. -
  17. Request start: Immediately before a user agent starts -sending the request for the resource, record the -current time as requestStart. If a user agent needed -multiple retries to send the request, record the current time -of the last attempt. -

    Network protocols may not perform the connection -establishment, secure connection establishment and request sending in a -sequential manner. Therefore, developers should not expect these values -to always be in a particular order.

    -
    18. -
  18. Record the time as responseStart immediately after the user agent receives the -first byte of the response.
    19. -
  19. Response end: Record the time as responseEnd immediately after receiving the last byte of -the response. -
      -
    1. Return to the step labeled connect start if the -user agent fails to send the request or receive the entire -response, and needs to reopen the connection. - -
      2. -
    2. Set the value of transferSize, encodedBodySize, -decodedBodySize to corresponding values, subject to -timing allow check algorithm.
      3. -
    -
    20. -
  20. Final record: If responseEnd -is not set, set it to the current time. Record the difference between -responseEnd and startTime in -duration.
    21. -
  21. If the fetched resource results in an HTTP redirect or -equivalent, then +
  22. Let |timingInfo| be the result of calling +retrieve timing info for |response|. +
  23. Let |urlList| be |response|'s +URL list. +
  24. If |timingInfo| is null or |urlList| is null or empty, then return. +
  25. Queue a global task on the networking task source with +|global| and the following steps:
      -
    1. If the current resource fails the timing allow check -algorithm, set redirectStart and redirectEnd to 0. -Then, return to the step labeled Fetch start with the redirected -resource.
      2. -
    2. If the value of redirectStart is not set, let it be the value -of fetchStart.
      3. -
    3. Let redirectEnd be the value of responseEnd.
      4. -
    4. Set all the attributes in the PerformanceResourceTiming -object to 0 except startTime, redirectStart, -redirectEnd, and initiatorType.
      5. -
    5. Return to the step labeled Fetch -start with the redirected resource.
      6. -
    -
    26. +
  26. Create a PerformanceResourceTiming object, with its +initiator type set to |initiatorType|, its +requested URL set to |urlList|'s first item, and its +timing info set to |timingInfo|.
  27. Queue the PerformanceResourceTiming object.
  28. Add the -PerformanceResourceTiming object to the Request's client's global object's +PerformanceResourceTiming object to |global|'s performance entry buffer.
-

This specification does not specify whether steps -20 and 21 should run before or after the load event of -the resource—see issue 82 for -related discussion.

-
-
-
-

Monotonic Clock

-

The value of the timing attributes MUST monotonically increase -to ensure timing attributes are not skewed by adjustments to the -system clock while fetching the resource. The difference between any two -chronologically recorded timing attributes MUST never be negative. -For all resources, including subdocument resources, the user agent -MUST record the system clock at the beginning of the root document -navigation and define subsequent timing attributes in terms of a -monotonic clock measuring time elapsed from the beginning of the -navigation.

-
+ +

To convert fetch timestamp given DOMHighResTimeStamp |ts| and +global object |global|, do the following: +

    +
  1. If |ts| is zero, return zero. +
  2. Otherwise, return the relative high resolution time given |ts| and |global|. +

Privacy and Security

@@ -1242,7 +677,7 @@

Privacy and Security

and certain attributes are set to zero, as described in . Resource providers can explicitly allow all timing information to be collected for a -resource by adding the Timing-Allow-Origin HTTP response +resource by adding the Timing-Allow-Origin HTTP response header, which specifies the domains that are allowed to access the timing information.

Statistical fingerprinting is a privacy concern where a