资源计时

3.2. 包含在 PerformanceResourceTiming 接口中的资源

本节为非规范性内容。

由非空 client 发起的资源 Request 的 fetch， 会作为 PerformanceResourceTiming 对象包含在该 client 的 全局对象 的 性能时间线（Performance Timeline），除非在 fetch 过程中被从时间线中排除。来自 HTTP 缓存的资源会作为 PerformanceResourceTiming 对象包含在 性能时间线 中。那些已发起 fetch 但随后被中止（例如因网络错误）的资源，也会作为 PerformanceResourceTiming 对象包含在 性能时间线 中，并带有它们的开始和结束时间。

示例：

• 如果两个 HTML IMG 元素使用相同的规范化 URL 作为 src 属性，则由第一个 HTML IMG 元素发起的该资源的 fetch 会作为一个 PerformanceResourceTiming 对象包含在 性能时间线 中。用户代理可能不会为第二个 HTML IMG 元素重新请求该 URL，而是使用为第一个 HTML IMG 元素已启动的现有下载。在这种情况下，由第一个 IMG 元素发起的该资源的 fetch 将是 性能时间线 中的唯一条目。
• 如果通过脚本更改了 HTML IMG 元素的 src 属性， 则原始资源的 fetch 以及新 URL 的 fetch 都会作为 PerformanceResourceTiming 对象包含在 性能时间线 中。
• 如果通过标记添加了一个 HTML IFRAME 元素且未指定 src 属性，用户代理可能会为该 IFRAME 加载 about:blank 文档。如果稍后通过脚本动态更改了 src 属性，用户代理可能会为该 IFRAME 的新 URL 发起 fetch。在这种情况下，只有该新 URL 的 fetch 会作为一个 PerformanceResourceTiming 对象包含在 性能时间线 中。
• 如果同一规范化 URL 的 XMLHttpRequest 被生成两次，则该资源的两次 fetch 都会作为一个 PerformanceResourceTiming 对象包含在 性能时间线 中。这是因为第二个 XMLHttpRequest 的该资源的 fetch 不能重用为第一个 XMLHttpRequest 发起的下载。
• 如果页面上包含一个 HTML IFRAME 元素，则只有由该 IFRAME 的 src 属性请求的资源会作为 PerformanceResourceTiming 对象包含在父文档的 性能时间线 中。该 IFRAME 文档请求的子资源会包含在该 IFRAME 文档的 性能时间线 中，而不是父文档的 性能时间线 中。
• 如果 HTML IMG 元素的源是一个 data: URI（参见 [RFC2397]），则该资源不会作为 PerformanceResourceTiming 对象包含在 性能时间线 中。PerformanceResourceTiming 条目仅针对 http(s) 资源报告。
• 如果某个资源的 fetch 因网络错误（例如 DNS、TCP 或 TLS 错误）而被中止，则该 fetch 会作为一个 PerformanceResourceTiming 对象包含在 性能时间线 中，并且仅设置 startTime、 fetchStart、duration 和 responseEnd。
• 如果某个资源的 fetch 因不满足 fetch 前提（例如 混合内容、CORS 限制、CSP 策略等）而被中止，则该资源不会作为一个 PerformanceResourceTiming 对象包含在 性能时间线 中。

3.3. PerformanceResourceTiming 接口

[Exposed=(Window,Worker)]
interface PerformanceResourceTiming : PerformanceEntry {
    readonly attribute DOMString initiatorType;
    readonly attribute DOMString deliveryType;
    readonly attribute ByteString 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 finalResponseHeadersStart;
    readonly attribute DOMHighResTimeStamp firstInterimResponseStart;
    readonly attribute DOMHighResTimeStamp responseStart;
    readonly attribute DOMHighResTimeStamp responseEnd;
    readonly attribute DOMHighResTimeStamp workerRouterEvaluationStart;
    readonly attribute DOMHighResTimeStamp workerCacheLookupStart;
    readonly attribute DOMString workerMatchedRouterSource;
    readonly attribute DOMString workerFinalRouterSource;
    readonly attribute unsigned long long  transferSize;
    readonly attribute unsigned long long  encodedBodySize;
    readonly attribute unsigned long long  decodedBodySize;
    readonly attribute unsigned short responseStatus;
    readonly attribute RenderBlockingStatusType renderBlockingStatus;
    readonly attribute DOMString contentType;
    readonly attribute DOMString contentEncoding;
    [Default] object toJSON();
};

一个 PerformanceResourceTiming 具有一个关联的 DOMString initiator type。

一个 PerformanceResourceTiming 具有一个关联的 DOMString delivery type。

一个 PerformanceResourceTiming 具有一个关联的 DOMString 请求的 URL。

一个 PerformanceResourceTiming 具有一个关联的 DOMString 缓存模式 （空字符串、"local"，或 "validated"）。

一个 PerformanceResourceTiming 具有关联的 fetch timing info，该项 计时信息。

一个 PerformanceResourceTiming 具有关联的 响应正文信息，该项 资源信息。

一个 PerformanceResourceTiming 具有关联的 状态 响应状态。

一个 PerformanceResourceTiming 具有关联的 RenderBlockingStatusType 阻塞渲染状态（render-blocking status）。

当调用 toJSON 时，应为 PerformanceResourceTiming 运行 默认的 toJSON 步骤。

initiatorType 的 getter 步骤应返回 该条目的 initiator type，即对于 this。

initiatorType 的设置是在报告资源计时条目的不同位置完成的，例如在 fetch 规范中。

deliveryType 的 getter 步骤应返回 该条目的 delivery type，即对于 this。

workerStart 的 getter 步骤为：对 转换 fetch 时间戳，作用于 this 的 timing info 的 final service worker start time，以及 相关全局对象 for this。详见 HTTP fetch 以获取更多信息。

redirectStart 的 getter 步骤为： 转换 fetch 时间戳，作用于 this 的 timing info 的 redirect start time 及 相关全局对象 for this。详见 HTTP-redirect fetch 以获取更多信息。

redirectEnd 的 getter 步骤为 转换 fetch 时间戳，作用于 this 的 timing info 的 redirect end time 及 相关全局对象 for this。详见 HTTP-redirect fetch 以获取更多信息。

fetchStart 的 getter 步骤为 转换 fetch 时间戳，作用于 this 的 timing info 的 post-redirect start time 及 相关全局对象 for this。 详见 HTTP fetch 以获取更多信息。

domainLookupStart 的 getter 步骤为 转换 fetch 时间戳，作用于 this 的 timing info 的 final connection timing info 的 domain lookup start time 及 相关全局对象 for this。 详见 Recording connection timing info 以获取更多信息。

domainLookupEnd 的 getter 步骤 为 转换 fetch 时间戳，作用于 this 的 timing info 的 final connection timing info 的 domain lookup end time 及 相关全局对象 for this。 详见 Recording connection timing info 以获取更多信息。

connectStart 的 getter 步骤为 转换 fetch 时间戳，作用于 this 的 timing info 的 final connection timing info 的 connection start time 及 相关全局对象 for this。详见 Recording connection timing info 以获取更多信息。

connectEnd 的 getter 步骤为 转换 fetch 时间戳，作用于 this 的 timing info 的 final connection timing info 的 connection end time 及 相关全局对象 for this。 详见 Recording connection timing info 以获取更多信息。

secureConnectionStart 的 getter 步骤为 转换 fetch 时间戳，作用于 this 的 timing info 的 final connection timing info 的 secure connection start time 及 相关全局对象 for this。 详见 Recording connection timing info 以获取更多信息。

nextHopProtocol 的 getter 步骤 为对 isomorphic decode this 的 timing info 的 final connection timing info 的 ALPN 协议协商 进行解码。详见 Recording connection timing info 以获取更多信息。

Issue 221 建议 移除 nextHopProtocol 的支持，因为它可能暴露用户的网络配置信息。

requestStart 的 getter 步骤为 转换 fetch 时间戳，作用于 this 的 timing info 的 final network-request start time 及 相关全局对象 for this。详见 HTTP fetch 以获取更多信息。

firstInterimResponseStart 的 getter 步骤为 转换 fetch 时间戳，作用于 this 的 timing info 的 first interim network-response start time，以及 相关 全局对象 for this。详见 HTTP fetch 以获取更多信息。

finalResponseHeadersStart 的 getter 步骤为 转换 fetch 时间戳，作用于 this 的 timing info 的 final network-response start time 及 相关全局对象 for this。详见 HTTP fetch 以获取更多信息。

responseStart 的 getter 步骤为 返回 this 的 firstInterimResponseStart 如果该值不为 0；否则返回 this 的 finalResponseHeadersStart。

responseEnd 的 getter 步骤为 转换 fetch 时间戳，作用于 this 的 timing info 的 end time，以及 相关全局对象 for this。详见 fetch 以获取更多信息。

encodedBodySize 的 getter 步骤 为返回 this 的 resource info 的 encoded size。

decodedBodySize 的 getter 步骤 为返回 this 的 resource info 的 decoded size。

transferSize 的 getter 步骤为：

1. 如果 this 的 cache mode 为 "local"，则返回 0。

2. 如果 this 的 cache mode 为 "validated"，则返回 300。

3. 返回 this 的 资源信息 的 编码大小 加上 300。

   加到 transferSize 的常数用于替代暴露 HTTP 头的总字节大小，因为那可能泄露某些 cookie 的存在。参见 该问题。

responseStatus 的 getter 步骤是 返回 this 的 响应状态。

responseStatus 由 Fetch 决定。对于跨域的 no-cors 请求，响应状态将为 0，因为响应将是一个 不透明的过滤响应。

contentType 的 getter 步骤是返回 this 的 资源信息 中的 内容类型。

contentEncoding 的 getter 步骤 是返回 this 的 资源信息 中的 内容编码。

renderBlockingStatus 的 getter 步骤是：如果 blocking 条件成立（即 this 的 timing info 中的 render-blocking 为 true），则返回 blocking；否则返回 non-blocking。

workerRouterEvaluationStart 的 getter 步骤是返回 this 的 timing info 中的 service worker 计时信息 的 worker 路由评估开始时间。

workerCacheLookupStart 的 getter 步骤是返回 this 的 timing info 中的 service worker 计时信息 的 worker 缓存查找开始时间。

workerMatchedRouterSource 的 getter 步骤是返回 this 的 timing info 中的 service worker 计时信息 的 worker 匹配的路由源。

workerFinalRouterSource 的 getter 步骤是返回 this 的 timing info 中的 service worker 计时信息 的 worker 最终的路由源。

实现 PerformanceResourceTiming 的用户代理需要在 supportedEntryTypes 中包含 "resource"。这允许开发者检测对资源计时的支持。

enum RenderBlockingStatusType {
    "blocking",
    "non-blocking"
};

3.4. 对 Performance 接口的扩展

用户代理可以选择限制包含为 PerformanceResourceTiming 对象在 性能时间线（Performance Timeline） 中的数量 [PERFORMANCE-TIMELINE-2]。本节扩展了 Performance 接口，以允许控制所存储的 PerformanceResourceTiming 对象的数量。

推荐的 PerformanceResourceTiming 对象的最小数量为 250，但用户代理可对其进行更改。 可调用 setResourceTimingBufferSize 请求更改此限制。

每个 ECMAScript 全局环境 具有：

• 一个 资源计时缓冲区大小限制， 初始应为 250 或更大。
• 一个 资源计时缓冲区当前大小， 初始为 0。
• 一个 资源计时缓冲区已满事件待定标志， 初始为 false。
• 一个 资源计时二级缓冲区当前大小， 初始为 0。
• 一个 资源计时二级缓冲区 用于存放 PerformanceResourceTiming 对象，初始为空。

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

Performance 接口在 [HR-TIME] 中定义。

方法 clearResourceTimings 运行以下步骤：

1. 从 PerformanceResourceTiming 对象中删除性能条目缓冲区（performance entry buffer）中的所有条目。
2. 将 资源计时缓冲区当前大小 设为 0。

方法 setResourceTimingBufferSize 运行以下步骤：

1. 将 资源计时缓冲区大小限制 设为 maxSize 参数。如果 maxSize 参数小于 资源计时缓冲区当前大小，则不应从 PerformanceResourceTiming 对象中移除任何条目以缩减缓冲区。

属性 onresourcetimingbufferfull 是下文描述的 resourcetimingbufferfull 事件的事件处理器。

要检查 是否可以添加资源计时条目，按如下步骤执行：

1. 如果 资源计时缓冲区当前大小 小于 资源计时缓冲区大小限制，则返回 true。
2. 返回 false。

要将 PerformanceResourceTiming 条目 new entry 添加到 性能条目缓冲区，按如下步骤执行：

1. 如果 是否可以添加资源计时条目 返回 true 且 资源计时缓冲区已满事件挂起标志 为 false，执行下列子步骤：
   1. 将 new entry 添加到 性能条目缓冲区。
   2. 将 资源计时缓冲区当前大小 增加 1。
   3. 返回。
2. 如果 资源计时缓冲区已满事件挂起标志 为 false，执行下列子步骤：
   1. 将 资源计时缓冲区已满事件挂起标志 设为 true。
   2. 在 performance timeline 任务源 上 排队一个任务 ，以运行 触发缓冲区已满事件。
3. 将 new entry 添加到 资源计时二级缓冲区。
4. 将 资源计时二级缓冲区当前大小 增加 1。

要 复制二级缓冲区，按如下步骤执行：

1. 当 资源计时二级缓冲区 不为空且 是否可以添加资源计时条目 返回 true 时，执行下列子步骤：
   1. 令 entry 为 资源计时二级缓冲区 中最早的 PerformanceResourceTiming 。
   2. 将 entry 添加到 性能条目缓冲区 的末尾。
   3. 将 资源计时缓冲区当前大小 增加 1。
   4. 从 资源计时二级缓冲区 移除 entry。
   5. 将 资源计时二级缓冲区当前大小 减 1。

要 触发缓冲区已满事件，按如下步骤执行：

1. 当 资源计时二级缓冲区 不为空时，执行下列子步骤：
   1. 令 number of excess entries before 等于 资源计时二级缓冲区当前大小。
   2. 如果 是否可以添加资源计时条目 返回 false， 则 触发名为 resourcetimingbufferfull 的事件， 目标为 Performance 对象。
   3. 执行 复制二级缓冲区。
   4. 令 number of excess entries after 为 资源计时二级缓冲区当前大小。
   5. 如果 number of excess entries before 小于等于 number of excess entries after，则移除 资源计时二级缓冲区 中的所有条目， 将 资源计时二级缓冲区当前大小 设为 0，并 中止这些步骤。
2. 将 资源计时缓冲区已满事件挂起标志 设为 false。

   这意味着如果 resourcetimingbufferfull 事件处理器新增缓冲区空间 小于或等于它新增的资源条目，则部分溢出条目会从缓冲区被丢弃。 开发者需确保 resourcetimingbufferfull 事件处理器调用 clearResourceTimings 或 通过调用 setResourceTimingBufferSize 适当扩展缓冲区。

3.5. 跨域资源

3.6. 资源计时属性

本节为非规范性内容。

下图说明了 PerformanceResourceTiming 接口定义的计时属性。括号内的属性可能在对跨域资源进行 fetch 时不可用。用户代理可能会在计时之间进行内部处理，从而允许非规范性的计时间隔。