资源计时

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 的步骤是返回 发起者类型，该类型对应于 this。

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

deliveryType getter 的步骤是返回 交付类型，该类型对应于 this。

workerStart getter 的步骤是 为 this 的 计时信息的 最终 service worker 启动 时间以及 相关全局 对象调用 转换 fetch 时间戳。更多信息请参阅 HTTP 获取。

redirectStart getter 的步骤 是为 this 的 计时信息的 重定向开始时间以及 相关全局对象调用 转换 fetch 时间戳。更多信息请参阅 HTTP 重定向获取。

redirectEnd getter 的步骤 是为 this 的 计时信息的 重定向结束时间以及 相关全局对象调用 转换 fetch 时间戳。更多信息请参阅 HTTP 重定向获取。

fetchStart getter 的步骤是 为 this 的 计时信息的 重定向后开始时间以及 相关全局对象 调用 转换 fetch 时间戳。更多信息请参阅 HTTP 获取。

domainLookupStart getter 的步骤是为 this 的 计时信息的 最终连接计时信息的 域名查找开始时间以及 相关全局对象调用 转换 fetch 时间戳。更多信息请参阅 记录连接计时信息。

domainLookupEnd getter 的步骤是为 this 的 计时信息的 最终连接计时信息的 域名查找结束时间以及 相关全局对象调用 转换 fetch 时间戳。更多信息请参阅 记录连接计时信息。

connectStart getter 的步骤是 为 this 的 计时信息的 最终连接计时信息的 连接开始时间以及 相关全局对象 调用 转换 fetch 时间戳。更多信息请参阅 记录连接计时信息。

connectEnd getter 的步骤是 为 this 的 计时信息的 最终连接计时信息的 连接结束时间以及 相关全局对象调用 转换 fetch 时间戳。更多信息请参阅 记录连接计时信息。

secureConnectionStart getter 的步骤是为 this 的 计时信息的 最终连接计时信息的 安全连接开始 时间以及 相关全局对象调用 转换 fetch 时间戳。更多信息请参阅 记录连接计时信息。

nextHopProtocol getter 的步骤是对 this 的 计时信息的 最终连接计时信息的 ALPN 协商协议进行 同构解码。更多信息请参阅 记录连接 计时信息。

Issue 221 建议 移除对 nextHopProtocol 的支持，因为它可能会泄露有关 用户网络配置的详细信息。

requestStart getter 的步骤是 为 this 的 计时信息的 最终网络请求开始 时间以及 相关全局 对象调用 转换 fetch 时间戳。更多信息请参阅 HTTP 获取。

firstInterimResponseStart getter 的步骤是 为 this 的 计时信息的 第一个临时 网络响应开始时间以及 相关 全局对象调用 转换 fetch 时间戳。更多信息请参阅 HTTP 获取。

finalResponseHeadersStart getter 的步骤是 为 this 的 计时信息的 最终网络响应开始 时间以及 相关全局 对象调用 转换 fetch 时间戳。更多信息请参阅 HTTP 获取。

responseStart getter 的步骤 是如果 this 的 firstInterimResponseStart 不为 0，则返回它；否则返回 this 的 finalResponseHeadersStart。

responseEnd getter 的步骤是 为 this 的 计时信息的 结束时间以及 相关全局对象调用 转换 fetch 时间戳。更多信息请参阅 获取。

encodedBodySize getter 的步骤是返回 this 的 资源 信息的 编码后大小。

decodedBodySize getter 的步骤是返回 this 的 资源 信息的 解码后大小。

transferSize getter 的步骤 如下：

1. 如果 this 的 缓存 模式为 "local"，则返回 0。

2. 如果 this 的 缓存 模式为 "validated"，则返回 300。

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

   添加到 transferSize 的常数用于替代暴露 HTTP 标头的总字节大小，因为这可能会暴露 某些 cookie 的存在。参阅此 issue。

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

responseStatus 在 Fetch 中确定。对于 跨源 no-cors 请求， 其值将为 0，因为响应会是不透明过滤 响应。

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

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

renderBlockingStatus getter 的步骤是，如果 this 的 计时 信息的 渲染阻塞为 true，则返回 阻塞；否则返回 非阻塞。

workerRouterEvaluationStart getter 的步骤是返回 this 的 计时 信息的 service worker 计时信息的 worker 路由器求值 开始时间。

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

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

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

实现 PerformanceResourceTiming 的用户代理需要 在 supportedEntryTypes 中包含 "resource"。 这使开发者能够 检测是否支持 Resource Timing。

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 时不可用。用户代理可能会在计时之间进行内部处理，从而允许非规范性的计时间隔。