4.2 Resources Included in the PerformanceResourceTiming Interface

All resources fetched by the current browsing [HTML5] or worker [WORKERS] context's MUST be included as PerformanceResourceTiming objects in the Performance Timeline of the relevant context. Resources that are retrieved from relevant application caches or local resources MUST be included as PerformanceResourceTiming objects in the Performance Timeline ([PERFORMANCE-TIMELINE-2]). Resources for which the fetch was initiated, but was later aborted (e.g. due to a network error) MUST be included as PerformanceResourceTiming objects in the Performance Timeline and MUST contain initialized attribute values for processed substeps of the processing model.

The rest of this section is non-normative.

Examples:

• If the same canonical URL is used as the src attribute of two HTML IMG elements, the fetch of the resource initiated by the first HTML IMG element SHOULD be included as a PerformanceResourceTiming object in the Performance Timeline. The user agent might not re-request the URL for the second HTML IMG element, instead using the existing download it initiated for the first HTML IMG element. In this case, the fetch of the resource by the first IMG element would be the only occurrence in the Performance Timeline.
• If the src attribute of a HTML IMG element is changed via script, both the fetch of the original resource as well as the fetch of the new URL would be included as PerformanceResourceTiming objects in the Performance Timeline.
• If an HTML IFRAME element is added via markup without specifying a src attribute, the user agent may load the about:blank document for the IFRAME. If at a later time the src attribute is changed dynamically via script, the user agent may fetch the new URL resource for the IFRAME. In this case, only the fetch of the new URL would be included as a PerformanceResourceTiming object in the Performance Timeline.
• If an XMLHttpRequest is generated twice for the same canonical URL, both fetches of the resource would be included as a PerformanceResourceTiming object in the Performance Timeline. This is because the fetch of the resource for the second XMLHttpRequest cannot reuse the download issued for the first XMLHttpRequest.
• If an HTML IFRAME element is included on the page, then only the resource requested by IFRAME src attribute is included as a PerformanceResourceTiming object in the Performance Timeline. Sub-resources requested by the IFRAME document will be included in the IFRAME document's Performance Timeline and not the parent document's Performance Timeline.
• If an HTML IMG element has a data: URI as its source [RFC2397], then this resource will not be included as a PerformanceResourceTiming object in the Performance Timeline. By definition data: URI contains embedded data and does not require a fetch.
• If a resource fetch was aborted due to a networking error (e.g. DNS, TCP, or TLS error), then the fetch would be included as a PerformanceResourceTiming object in the Performance Timeline with initialized attribute values up to the point of failure - e.g. a TCP handshake error should report DNS timestamps for the request, and so on.
• If a resource fetch is aborted because it failed a fetch precondition (e.g. mixed content, CORS restriction, CSP policy, etc), then this resource will not be included as a PerformanceResourceTiming object in the Performance Timeline.

The user agent MAY choose to limit how many resources are included as PerformanceResourceTiming objects in the Performance Timeline. The recommended minimum number of PerformanceResourceTiming objects is 150, though this may be changed by the user agent. setResourceTimingBufferSize can be called to request a change to this limit.

4.3 The PerformanceResourceTiming Interface

The PerformanceResourceTiming interface participates in the Performance Timeline and extends the following attributes of the 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.

entryType

The entryType attribute MUST return 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 all the redirects or equivalent are from the same origin as the current document or 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.

[Exposed=(Window,Worker)]
interface PerformanceResourceTiming : PerformanceEntry {
    readonly        attribute DOMString           initiatorType;
    readonly        attribute DOMString           nextHopProtocol;
    readonly        attribute DOMHighResTimeStamp workerStart;
    readonly        attribute DOMHighResTimeStamp redirectStart;
    readonly        attribute DOMHighResTimeStamp redirectEnd;
    readonly        attribute DOMHighResTimeStamp fetchStart;
    readonly        attribute DOMHighResTimeStamp domainLookupStart;
    readonly        attribute DOMHighResTimeStamp domainLookupEnd;
    readonly        attribute DOMHighResTimeStamp connectStart;
    readonly        attribute DOMHighResTimeStamp connectEnd;
    readonly        attribute DOMHighResTimeStamp secureConnectionStart;
    readonly        attribute DOMHighResTimeStamp requestStart;
    readonly        attribute DOMHighResTimeStamp responseStart;
    readonly        attribute DOMHighResTimeStamp responseEnd;
    readonly        attribute unsigned long long  transferSize;
    readonly        attribute unsigned long long  encodedBodySize;
    readonly        attribute unsigned long long  decodedBodySize;
    serializer = {inherit, attribute};
};

4.4 Extensions to the Performance Interface

Each ECMAScript global environment has:

• a resource timing buffer size limit which should initially be 150 or greater.
• a resource timing buffer current size which is initially 0.
• a resource timing buffer full flag which is initially false.

partial interface Performance {
    void clearResourceTimings();
    void setResourceTimingBufferSize(unsigned long maxSize);
    attribute EventHandler onresourcetimingbufferfull;
};

The method clearResourceTimings runs the following steps:

1. remove all PerformanceResourceTiming objects in the performance entry buffer.
2. set resource timing buffer current size to 0.
3. set resource timing buffer full flag to false.

The setResourceTimingBufferSize method runs the following steps:

1. Set resource timing buffer size limit to the maxSize parameter. If the maxSize parameter is less than resource timing buffer current size, no PerformanceResourceTiming objects are to be removed from the performance entry buffer.
2. Set resource timing buffer full flag to false.

The attribute onresourcetimingbufferfull is the event handler for the resourcetimingbufferfull event.

To add a PerformanceResourceTiming entry (new entry) in the performance entry buffer, run the following steps:

1. If resource timing buffer current size is less than resource timing buffer size limit, run the following substeps:
   1. Add new entry to the performance entry buffer.
   2. increase resource timing buffer current size by 1.
2. If resource timing buffer current size is equal to resource timing buffer size limit and resource timing buffer full flag is false, run the following substeps:
   1. fire a simple event named resourcetimingbufferfull at the Document, with its bubbles attribute initialized to true, and has no default action.
   2. set the resource timing buffer full flag to true.

4.5 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 cross-origin resource, these attributes of its PerformanceResourceTiming object MUST be set to zero: redirectStart, redirectEnd, domainLookupStart, domainLookupEnd, connectStart, connectEnd, requestStart, responseStart and secureConnectionStart.

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.

5.1 Processing Model

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

For each resource fetched by the current browsing context, excluding resources fetched by cross-origin stylesheets fetched with no-cors policy, perform the following steps:

1. Create a new PerformanceResourceTiming object and set entryType to the DOMString resource.
2. 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.
3. Record the initiator of the resource in initiatorType.
4. Record the resolved URL of the requested resource in name. If there is an active worker ([SERVICE-WORKERS]) 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.
5. 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.
6. If the user agent is to reuse the data from another existing or completed fetch initiated from the current document, abort the remaining steps.
7. If fetching the resource is aborted for any reason, abort the remaining steps.
8. If the last non-redirected fetch of the resource is not the same origin as the current document and the timing allow check algorithm fails, the user agent MUST set redirectStart, redirectEnd, domainLookupStart, domainLookupEnd, connectStart, connectEnd, requestStart, responseStart and secureConnectionStart to zero and go to step 3.17.
9. Let domainLookupStart, domainLookupEnd, connectStart and connectEnd be the same value as fetchStart.
10. If the resource is fetched from the relevant application cache or local resources, including the HTTP cache [RFC7234], go to step 3.15.
11. If no domain lookup is required, go to step 3.13. Otherwise, immediately before a user agent starts the domain name lookup, record the time as domainLookupStart.
12. 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 lookup fails, abort the remaining steps.
13. 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 the connection to the server and record the time as connectEnd immediately after the connection to the server or the proxy is established. A user agent may need multiple retries before this time. Once connection is established set the value of nextHopProtocol to the ALPN ID used by the connection. If a connection can not be established, abort the remaining steps.
14. 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. When a secure transport is not used, the user agent MUST set the value of secureConnectionStart to 0.
15. Immediately before a user agent starts sending the request for the resource, record the current time as requestStart.
16. Record the time as responseStart immediately after the user agent receives the first byte of the response.
17. Record the time as responseEnd immediately after receiving the last byte of the response.
    1. Return to step 3.13 if the user agent fails to send the request or receive the entire response, and needs to reopen the connection.
       EXAMPLE

       When persistent connection [RFC7230] is enabled, a user agent may first try to re-use an open connect to send the request while the connection can be asynchronously closed. In such case, connectStart, connectEnd and requestStart SHOULD represent timing information collected over the re-open connection.

    2. Set the value of transferSize, encodedBodySize, decodedBodySize to corresponding values, subject to timing allow check algorithm.
18. Record the difference between responseEnd and startTime in duration.
19. If the fetched resource results in an HTTP redirect or equivalent, then
    1. If the current resource and the redirected resource are not from the same origin as the current document, and the timing allow check algorithm fails for either resource, set redirectStart and redirectEnd to 0. Then, return to step 3.5 with the new resource.
    2. If the value of redirectStart is not set, let it be the value of fetchStart.
    3. Let redirectEnd be the value of responseEnd.
    4. Set all the attributes in the PerformanceResourceTiming object to 0 except startTime, redirectStart, redirectEnd, and initiatorType.
    5. Return to step 3.5 with the new resource.
20. Queue the PerformanceResourceTiming object.
21. Add the PerformanceResourceTiming object.

5.2 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.