计算压力等级 1

摘要

计算压力 API 提供了一种让网站对目标设备 CPU 压力变化做出响应的方法，从而使网站能够在资源和优化用户体验之间进行权衡。

Compute Pressure API 使开发者能够了解系统资源（如 CPU）的压力情况。

WebIDLcallback PressureUpdateCallback = undefined (
  sequence<PressureRecord> changes,
  PressureObserver observer
);

当压力状态发生变化时，将调用此回调。

PressureObserver 可用于观察压力状态的变化。

WebIDL[Exposed=(DedicatedWorker,SharedWorker,Window), SecureContext]
interface PressureObserver {
  constructor(PressureUpdateCallback callback);

  Promise<undefined> observe(PressureSource source, optional PressureObserverOptions options = {});
  undefined unobserve(PressureSource source);
  undefined disconnect();
  sequence<PressureRecord> takeRecords();

  [SameObject] static readonly attribute FrozenArray<PressureSource> knownSources;
};

PressureObserver 接口表示一个 PressureObserver。

new PressureObserver(callback) 构造器的步骤如下：

将 this.[[Callback]] 设为 callback。

observe(source, options) 方法的步骤如下：

令 relevantGlobal 为 this 的相关全局对象。
对 relevantGlobal 的所属文档集合中的每个document：
1. 如果 document 没有被允许使用策略控制特性 token "compute-pressure"，则返回以 NotAllowedError 拒绝的 promise。
注意

Worker 有自己的策略容器，可通过 HTTP 头设置。参见6. 策略控制中的示例。
将 this.[[SampleIntervalMap]][source] 设为 options 的 sampleInterval。
令 promise 为一个新的 promise。
令 pendingPromiseTuple 为（source，promise）。
将 pendingPromiseTuple 追加到 this.[[PendingObservePromises]]。
对 promise 进行反应：
- 如果 promise 已兑现或拒绝，则：
  1. 从 this.[[PendingObservePromises]] 中移除 tuple。
并行运行以下步骤：
1. 令 platformCollector 为 null。
2. 如果 relevantGlobal 的平台收集器映射包含 source：
  1. 将 platformCollector 设为 relevantGlobal 的平台收集器映射[source]。
3. 否则：
  1. 令 newCollector 为一个新的平台收集器，其关联压力源为 null。
  2. 令 virtualPressureSource 为以 source 和 relevantGlobal 调用获取虚拟压力源的结果。
  3. 如果 virtualPressureSource 不为 null：
    1. 如果 virtualPressureSource 的可以提供样本为 true：
      1. 将 newCollector 的关联压力源设为 virtualPressureSource。
      2. 将 newCollector 追加到 virtualPressureSource 的已连接平台收集器中。
  4. 否则：
    1. 令 realPressureSource 为一个实现定义的压力源，其提供关于 source 的遥测数据；若不存在则为 null。
    2. 将 newCollector 的关联压力源设为 realPressureSource。
  5. 如果 newCollector 的关联压力源不为 null：
    1. 将 platformCollector 设为 newCollector。
    2. 将 relevantGlobal 的平台收集器映射[source] 设为 platformCollector。
4. 如果 platformCollector 为 null，则在给定 relevantGlobal 的情况下，使用队列一个全局任务，在PressureObserver 任务源上以NotSupportedError 拒绝 promise 并中止这些步骤。
5. 使用 source 和 relevantGlobal 调用激活数据收集。
6. 在给定 relevantGlobal 的情况下，在PressureObserver 任务源上队列一个全局任务以运行以下步骤：
  1. 如果 promise 已被拒绝，则运行以下子步骤：
    1. 如果 relevantGlobal 针对 source 的已注册观察者列表为空，则以 source 与 relevantGlobal 调用停用数据收集。
    2. 返回。
  2. 将一个新的已注册观察者（其观察者为this）追加到 relevantGlobal 针对 source 的已注册观察者列表中。
  3. 兑现 promise。
返回 promise。

unobserve(source) 方法的步骤如下：

如果 source 不是一个支持的源类型，则抛出 "NotSupportedError"。
从 this.[[QueuedRecords]] 中移除所有与 source 关联的 records。
移除 this.[[SampleIntervalMap]][source]。
移除 this.[[LastRecordMap]][source]。
移除 this.[[AfterPenaltyRecordMap]][source]。
对 this.[[PendingObservePromises]] 中的每个（promiseSource，pendingPromise），若 source 等于 promiseSource，则以 AbortError 拒绝 pendingPromise。
令 relevantGlobal 为 this 的相关全局对象。
令 registeredObserverList 为 relevantGlobal 针对 source 的已注册观察者列表。
从 registeredObserverList 中移除任意已注册观察者，其观察者为this。
如果 registeredObserverList 为空：
1. 使用 source 与 relevantGlobal 调用停用数据收集。
2. 移除 relevantGlobal 的平台收集器映射[source]。

disconnect() 方法的步骤如下：

清空 observer.[[QueuedRecords]]。
清除 this.[[SampleIntervalMap]]。
清除 this.[[LastRecordMap]]。
清除 this.[[AfterPenaltyRecordMap]]。
对 this.[[PendingObservePromises]] 中的每个（promiseSource，pendingPromise），以AbortError 拒绝 pendingPromise。
令 relevantGlobal 为 this 的相关全局对象。
对 relevantGlobal 的已注册观察者列表有序映射中的每个 source → registeredObserverList：
1. 从 registeredObserverList 中移除任意已注册观察者，其观察者为this。
2. 如果 registeredObserverList 为空：
  1. 使用 source 与 relevantGlobal 调用停用数据收集。
  2. 移除 relevantGlobal 的平台收集器映射[source]。

注意

takeRecords() 方法的步骤如下：

令 records 为 observer.[[QueuedRecords]] 的一个克隆。
清空 observer.[[QueuedRecords]]。
返回 records。

knownSources getter 的步骤如下：

以字母顺序返回用户代理的支持的源类型。

注意

WebIDL[Exposed=(DedicatedWorker,SharedWorker,Window), SecureContext]
interface PressureRecord {
  readonly attribute PressureSource source;
  readonly attribute PressureState state;
  readonly attribute DOMHighResTimeStamp time;
  [Default] object toJSON();
};

一个已构造的PressureRecord对象具有以下内部插槽：

一个 [[Source]] 值，类型为 PressureSource，表示当前源类型。
一个 [[State]] 值，类型为 PressureState，表示当前压力状态。
一个 [[Time]] 值，类型为 DOMHighResTimeStamp，对应该数据从系统获取的时间，相对于与生成该通知的PressureObserver实例相关联的全局对象的时间原点。

source 的getter 步骤是返回其[[Source]]内部插槽。

state 的getter 步骤是返回其[[State]]内部插槽。

time 的getter 步骤是返回其[[Time]]内部插槽。

当调用 PressureRecord.toJSON 时，运行Web IDL Standard中的默认 toJSON 步骤。

WebIDLdictionary PressureObserverOptions {
  [EnforceRange] unsigned long sampleInterval = 0;
};

sampleInterval 成员表示以毫秒表示的请求采样间隔。当该值设为 0 时，系统仅会在PressureState发生变化时调用PressureUpdateCallback。

注意

每个全局对象都会对其已注册观察者（每个 source 一个）所在的已注册观察者列表保持强引用。

注意

当某个PressureObserver 存在于已注册观察者列表中时，它就在观察某个source；该列表可通过调用 observe()、 unobserve() 和 disconnect() 来修改。

这意味着 PressureObserver 对象 observer 将保持存活（因此不会被垃圾回收），直到同时满足以下两个条件：

没有脚本引用指向 observer。
observer 未观察任何 source。

Example 2 包含一个示例，展示如何在观察者回调中调用 disconnect() （或任何其它PressureObserver 方法）。

本节概述了用户代理在实现本规范时必须执行的步骤。

给定参数 observer 的重置观测窗口步骤如下：

将 observer.[[ObservationWindow]] 设为在某个实现定义范围内、以毫秒计的实现定义随机整数值。
将 observer.[[MaxChangesThreshold]] 设为在某个实现定义范围内、observationWindow 内允许的最大变更次数的实现定义随机整数值。
将 observer.[[PenaltyDuration]] 设为在某个实现定义范围内、以毫秒计的实现定义随机整数值。
清空 observer.[[ChangesCountMap]] 映射。

运行重置观测窗口步骤，并启动一个定时器，在 observer.[[ObservationWindow]] 时间过去时重新运行这些步骤，并使用不同的随机值。

注意

要确定一个相关全局对象 relevantGlobal 的所属文档集合：

令 owningDocumentSet 为一个空的集合。
如果 relevantGlobal 是 Window，则将 relevantGlobal 的关联文档追加到 owningDocumentSet。
否则，对WorkerGlobalScope relevantGlobal 的拥有者集合中的每个 owner：
1. 如果 owner 是 Document，则将 owner追加到 owningDocumentSet。
2. 如果 owner 是 WorkerGlobalScope，则将 owningDocumentSet 设为 owningDocumentSet 与 owner 的所属文档集合的并集。
返回 owningDocumentSet。

给定参数 document 的文档具有隐式焦点步骤如下：

如果 document 不是完全激活的，返回 false。
令 relevantGlobal 为 document 的相关全局对象。
对活跃的画中画会话的发起方中的每个 origin：
1. 如果 relevantGlobal 的相关设置对象的源与 origin同源，返回 true。
如果 relevantGlobal 的浏览上下文正在捕获，返回 true。
令 topLevelBC 为 relevantGlobal 的浏览上下文的顶级浏览上下文。
如果 topLevelBC 不具有系统焦点，返回 false。
令 focusedDocument 为 topLevelBC 的当前获得焦点的区域的节点文档。
如果 relevantGlobal 的相关设置对象的源与 focusedDocument 的源同源，返回 true。
否则，返回 false。

给定参数 observer 的可以接收数据步骤如下：

令 relevantGlobal 为 observer 的相关全局对象。
如果 relevantGlobal 是 Window 对象：
1. 返回以 relevantGlobal 的关联 Document运行文档具有隐式焦点的结果。
如果 relevantGlobal 是 WorkerGlobalScope 对象：
1. 令 owningDocuments 为 relevantGlobal 的所属文档集合。
2. 对 owningDocuments 中的每个document：
  1. 如果以 document 运行文档具有隐式焦点的结果为 true，则返回 true。
  2. 否则，继续。
返回 false。

注意

通过速率测试步骤（给定参数 observer、source 和 timestamp）如下：

如果 observer.[[LastRecordMap]][source] 不存在，返回 true。
令 record 为 observer.[[LastRecordMap]][source]。
令 sampleInterval 为 observer.[[SampleIntervalMap]][source]。
令 timeDeltaMilliseconds = timestamp - record.[[Time]]。
如果 timeDeltaMilliseconds ≥ sampleInterval，返回 true，否则返回 false。

应当派发步骤（给定参数 observer、source 和 state）如下：

如果 observer.[[SampleIntervalMap]][source] > 0，返回 true。
如果 observer.[[LastRecordMap]][source] 不存在，返回 true。
令 record 为 observer.[[LastRecordMap]][source]。
如果 record.[[State]] 不等于 state，返回 true。
返回 false。

通过速率混淆测试步骤（给定参数 observer 和 source）如下：

将 observer.[[ChangesCountMap]][source] 加 1。
返回 observer.[[ChangesCountMap]][source] ≤ observer.[[MaxChangesThreshold]]。

给定源类型 source 和 relevantGlobal，要获取虚拟压力源，执行以下步骤。它们返回一个虚拟压力源或 null。

令 topLevelTraversable 为 null。
如果 relevantGlobal 是 Window 对象：
1. 将 topLevelTraversable 设为 relevantGlobal 的可导航对象的顶级可遍历对象。
如果 relevantGlobal 是 DedicatedWorkerGlobalScope 对象：
1. 令 owningDocuments 为 relevantGlobal 的所属文档集合。
2. 如果 owningDocuments 为空，返回 null。
3. 断言：owningDocuments 的大小为 1。
4. 将 topLevelTraversable 设为 owningDocuments[0] 的节点可导航对象的顶级可遍历对象。
如果 topLevelTraversable 为 null，返回 null。
令 topLevelVirtualPressureSourceMapping 为 topLevelTraversable 的虚拟压力源映射。
令 virtualPressureSource 为 null。
如果 topLevelVirtualPressureSourceMapping 包含 source：
1. 将 virtualPressureSource 设为 topLevelVirtualPressureSourceMapping[source]。
返回 virtualPressureSource。

给定源类型 source 和 relevantGlobal，要激活数据收集，执行以下步骤：

如果 relevantGlobal 的平台收集器映射不包含 source，中止这些步骤。
令 platformCollector 为 relevantGlobal 的平台收集器映射[source]。
如果 platformCollector 的已激活为 true，中止这些步骤。
将 platformCollector 的已激活设为 true。
以实现定义的方式，开始使用 relevantGlobal、source 和 platformCollector 运行数据收集步骤。

注意

此步骤给予实现通过轮询或订阅平台/操作系统特定通知来收集遥测数据的自由度。

给定源类型 source 和 relevantGlobal，要停用数据收集，执行以下步骤：

如果 relevantGlobal 的平台收集器映射不包含 source，中止这些步骤。
令 platformCollector 为 relevantGlobal 的平台收集器映射[source]。
如果 platformCollector 的已激活为 false，中止这些步骤。
以实现定义的方式，停止使用 relevantGlobal、source 和 platformCollector 运行数据收集步骤。
将 platformCollector 的已激活设为 false。
如果 platformCollector 的关联压力源是一个虚拟压力源：
1. 从其关联压力源的已连接平台收集器中移除 platformCollector。
否则，执行任何实现定义步骤，以通知 platformCollector 的关联压力源停止检索遥测数据。

给定 relevantGlobal、source 和 platformCollector 的数据收集步骤如下：

令 pressureSource 为 platformCollector 的关联压力源。
如果 pressureSource 为 null，中止这些步骤。
令 sample 为 pressureSource 的最新样本。
如果 sample 为 null，中止这些步骤。
令 state 为 null。
如果 pressureSource 是一个虚拟压力源：
1. 将 state 设为存储在 sample 的data中的PressureState。
否则：
1. 如果影响因素变化显著为 false，中止这些步骤。
2. 将 state 设为由 source 与 sample 的data计算出的调整后压力状态。
  
  注意
  
  sample 的data 与压力状态之间的映射是实现定义的，并且可能使用许多不同的度量指标。例如，对于 CPU，它可能会考虑处理器频率、利用率以及热条件等。
断言：state 不为 null。
令 rawTimestamp 为 sample 的timestamp。
令 timeValue 为基于 rawTimestamp 与 relevantGlobal 的相对高分辨率时间。
对 relevantGlobal 针对 source 的已注册观察者列表中的每个observer：
1. 如果以 observer 运行可以接收数据返回 false，继续。
2. 如果以 observer、source 和 timeValue 运行通过速率测试返回 false，继续。
3. 如果以 observer、source 与 state 运行应当派发返回 false，继续。
4. 令 record 为一个新的PressureRecord 对象，其[[Source]] 设为 source， [[State]] 设为 state，并将[[Time]] 设为 timeValue。
5. 如果 observer.[[AfterPenaltyRecordMap]][source] 存在：
  1. 将 observer.[[AfterPenaltyRecordMap]][source] 设为 record。
  2. 继续。
6. 如果以 observer 和 source 运行通过速率混淆测试返回 false：
  1. 将 observer.[[AfterPenaltyRecordMap]][source] 设为 record。
  2. 将 observer.[[ChangesCountMap]][source] 设为 0。
  3. 创建一个持续 observer.[[PenaltyDuration]] 的定时器，回调如下：
    1. 如果 observer.[[AfterPenaltyRecordMap]][source] 存在：
      1. 令 record 为 observer.[[AfterPenaltyRecordMap]][source]。
      2. 移除 observer.[[AfterPenaltyRecordMap]][source]。
      3. 以 observer、source 和 record 运行入队一条记录。
  4. 继续。
7. 以 observer、source 和 record 运行入队一条记录。

给定参数 observer、 source、record，要入队一条记录，运行以下步骤：

如果 observer.[[QueuedRecords]] 的大小大于最大排队记录数，则移除第一个项。
将 record追加到 observer.[[QueuedRecords]]。
将 observer.[[LastRecordMap]][source] 设为 record。
使用 observer 的相关全局对象运行入队一个压力观察任务。

PressureObserver 任务源是一个任务源，用于安排任务以执行10.6.5 通知压力观察者。

给定 relevantGlobal 作为输入，要入队一个压力观察任务，运行以下步骤：

如果 relevantGlobal 的压力观察任务已入队为 true，则返回。
将 relevantGlobal 的压力观察任务已入队设为 true。
在以 relevantGlobal 为目标的情况下，于PressureObserver 任务源上队列一个全局任务以通知压力观察者。

给定 relevantGlobal 作为输入，要通知压力观察者，运行以下步骤：

将 relevantGlobal 的压力观察任务已入队设为 false。
令 notifySet 为一个新的集合，包含 relevantGlobal 的已注册观察者列表中的所有观察者。
对 notifySet 中的每个observer：
1. 令 records 为 observer.[[QueuedRecords]] 的一个克隆。
2. 清空 observer.[[QueuedRecords]]。
3. 如果 records 不为空，则调用 observer.[[Callback]] ，参数为 « records、observer »，以及 "report"。

本规范定义了给定Document document 的以下卸载文档清理步骤：

令 relevantGlobal 为 document 的相关全局对象。
对 relevantGlobal 的已注册观察者列表有序映射的每个 source键：
1. 使用 source 与 relevantGlobal 调用停用数据收集。
2. 移除 relevantGlobal 的平台收集器映射[source]。

Issue 275：正确确定 bfcache 集成策略

本规范此前包含了覆盖以下情况的步骤：一个Document再次变为完全激活（即与Document的reactivate步骤集成）时的情形。在讨论预期行为期间，这些步骤已被移除。

注意

每当某个WorkerGlobalScope relevantGlobal的 closing 标志被设为 true 时，执行以下步骤：

对 relevantGlobal 的已注册观察者列表有序映射的每个 source键：
1. 使用 source 与 relevantGlobal 调用停用数据收集。
2. 移除 relevantGlobal 的平台收集器映射[source]。

注意

本工作组将在本节列出任何已知的攻击向量，包括理论与现实世界的。

如果不共享同源的网站能够在同一时间访问到唯一或非常精确的数值，那么可能会在跨非同源站点识别用户。此类攻击可通过11.2.1 数据最小化、11.2.2 速率混淆，以及11.2.7 同源限制进行缓解。

在计算机安全中，隐蔽信道是一种在本不应被允许通信的进程之间传递信息的能力。在现代多进程 Web 引擎中，通用情况下每个窗口或标签页都驻留在自己的进程中（具有同源的文档或具有同站点的站点通常共享同一进程）。使用此 API，站点 A 可以在一个标签页中先操纵 CPU 的状态后向信道 C 进行广播，从而可能创建跨站隐蔽信道 C。接着另一个标签页中的站点 B（与站点 A 不同站点）通过使用此 API 读取来自信道 C 的广播数据，以获知 CPU 状态何时发生变化。只要站点 A 和 B 上的脚本都在运行，该过程就会重复。

此类攻击可通过11.2.2 速率混淆和11.2.5 中断校准进行缓解。建议实现者对于长时间运行的脚本综合考虑这些缓解措施。

注意

脚本运行时间越长，利用所提议的跨站隐蔽信道能传输的信息就越多。例如，用户同时在视频会议站点与另一个长时间运行的站点上，相较于常规浏览情形，允许传输更多信息。另一方面，视频会议这类工作负载通常会对 CPU 施加持续压力，使得以可预测的方式操控压力状态更加困难。

定向去匿名化攻击是危及用户匿名性的一类关键威胁。这类攻击允许一个恶意或部分被攻陷的网站（下称“恶意站点”）判断访客是否拥有某个特定的公共标识符，例如电子邮件地址或社交媒体账号。

虽然匿名对部分人而言或许是一种奢侈，但对某些人来说远不止于此——它关系到生存。例如参与政治抗议、报道敏感话题的记者等。

举例来说，攻击者可以将某个资源私下分享给目标（例如使用公共资源分享服务，“受害站点”），然后通过侧信道在加载该资源时测量副作用（表明访问成功）。如果已登录的访客能够成功访问嵌入的资源，这就表明当前访问确实是预期目标。

具体而言，若暴露关于整体 CPU 压力的可靠信息，攻击站点就能理解跨源导航的目标（例如来自另一个站点的 iframe 或弹出窗口）是否执行了 CPU 密集型操作。

下置弹窗（pop-under）以及下置标签（tab-under）等技术可用于对用户隐藏加载过程。

一种可能的攻击是恶意网站打开一个指向受害站点资源的弹窗，例如视频流媒体站点或在线文档编辑器，其中该资源仅分享给特定用户，而用户当前已登录。

假设加载该资源会增加 CPU 压力，这将创建一个侧信道，向攻击站点揭示用户是否登录了具有访问该资源权限的账户，从而使用户去匿名化。

鉴于现代 CPU 能够快速从高压力状态恢复，一种可能的缓解策略是在加载弹窗和 iframe 内容后，临时禁用读数数秒。

注意

本节提供适用于本规范的缓解策略的高层视图。这些缓解的规范性定义已整合到本规范相应算法之中。实现者在落实本规范定义的缓解措施时，建议参考 TAG 关于隐私浏览模式的指导。

本规范遵循通用的数据最小化原则，以将与底层平台低层细节相关的数据暴露限制在满足高价值用例所需的最小范围之内。这包括考虑限制暴露设备识别信息。

在本规范语境中应用数据最小化原则的具体做法，见11.2.2 速率混淆和11.2.7 同源限制。

本规范要求实现速率混淆缓解措施，用于在一个实现定义的滑动观测窗口内跟踪压力变更次数，并在超过关于压力变更次数的实现定义阈值时设置标志。同样，建议实现也观察任何异常活动，如跨多个状态的压力状态高频变更，并以类似方式设置该标志。

若该标志被设置，建议实现给予压力观察器一个惩罚期，在此期间它不能像正常那样向脚本通知其压力状态的变更。惩罚期的时长为实现定义，并建议进行随机化。当通知压力观察者在惩罚结束后恢复运行时，它仅报告最新的压力状态，忽略该惩罚期间从平台收集器接收到的任何中间状态信息。

基于实现经验，实施者必须使用：

对 PressureObserver 的 [[MaxChangesThreshold]] 内部插槽，使用 50 到 100 次变更之间的范围。
对 PressureObserver 的 [[PenaltyDuration]] 内部插槽，使用 5000 毫秒到 10000 毫秒之间的范围。

注意

本节为非规范性。

基于实现经验，建议实施者使用：

对 PressureObserver 的 [[ObservationWindow]] 内部插槽，使用 300000 毫秒（5 分钟）到 600000 毫秒（10 分钟）之间的范围。

注意

在校准过程中，攻击者尝试操控 CPU，使得该 API 会以最高概率在其构造的工作负载施压后报告进入某个特定压力状态。此中断校准缓解方案可通过在运行时对促成这些压力状态转换的实现定义低层硬件度量进行轻微变动，从而减慢或阻止该校准过程成功。即便初始校准成功，在该缓解持续运行时其结果也会在运行时失效。任何重新校准的尝试也将被同样缓解。

注意

本节为非规范性。

基于实现经验，建议实施者将缓解应用于一个随机化的时间值，其范围在 120000 毫秒（2 分钟）到 240000 毫秒（4 分钟）之间。

注意

默认情况下，数据传递仅限于与活跃画中画会话发起方同源的文档，处于捕获状态的文档，或具有系统焦点的文档（如有）。

符合上述规则的数据传递资格的文档，可将其数据传递委派给子可导航对象中的文档。

该功能仅可通过声明的策略扩展至第三方上下文，如 iframe。

共享 worker 可以在文档之间共享，例如顶层文档及其关联的 iframe。若拥有者集合中的某个文档满足上述数据传递要求，则该共享 worker 将具备数据传递资格。这意味着嵌入的 iframe 能够将数据传递给嵌入它的文档。

Compute Pressure API 对测试作者提出了挑战，因为要完全测试接口需要能以可预测方式响应的物理硬件设备。

为了解决这一挑战，本文件定义了 [WEBDRIVER2] 扩展命令，允许定义和控制行为像真实来源的虚拟压力源，这些虚拟压力源可具有特定属性，其读数可以由用户完全定义。

A virtual pressure source 是一种以可控方式模拟真实压力源行为的 pressure source。它会向连接到它的零个或多个 platform collectors 报告压力变化。

然而，与真实的 pressure source 相反，它直接报告 pressure state 值，而不是必须由 implementation-defined 值再由 platform collector 处理成 pressure states。换言之，virtual pressure source 的 pressure source sample 的 data 是一个 PressureState。

除了与所有 pressure sources 关联的数据（例如 pressure source sample）之外，每个 virtual pressure source 具有：

一个 can provide samples 布尔值。
一个 connected platform collectors 的集合，包含 platform collectors。

每个 top-level traversable 都有一个 virtual pressure source mapping，它是一个将 source types 映射到 virtual pressure source 的有序映射（ordered map）。

注意

如当前规范所述，virtual pressure sources 仅当其 platform collector mapping 对该 source type 没有条目时，才会对 Window 或 DedicatedWorkerGlobalScope 产生影响。

换言之，为某个 source type 创建虚拟压力源，而该 observe() 已被调用，将不会影响任何现有实例，直到对它们调用 disconnect() 或 unobserve() 为止。新的实例只有在现有观察者被断开后再次调用 observe() 时才会使用新的 virtual pressure source。

同样，如果某个 virtual pressure source 正被一个或多个 PressureObserver 实例使用并且该虚拟压力源被移除，则所有实例必须停止观察，之后对 observe() 的调用将尝试连接到真实的 pressure source。

HTTP Method	URI Template
POST	/session/{session id}/pressuresource

此扩展命令创建一个指定源类型的新的虚拟压力源。来自同一源类型的 PressureObserver 实例调用 observe() 后，将使用此虚拟压力源作为其底层压力源，直到执行 13.1.1.2 删除虚拟压力源。

此算法使用的 parameters 参数的属性
参数名	值类型	是否必需
type	String	yes
supported	Boolean	no

给定 session、URL variables 和 parameters 的远端步骤为：

令 virtualPressureSourceType 为从 parameters 中调用 get a property "type" 的结果。
如果 user agent 的 supported source types 不包含 virtualPressureSourceType，则返回带有 WebDriver 错误代码 invalid argument 的错误。
令 topLevelTraversable 为当前浏览上下文的 top-level traversable。
令 topLevelVirtualPressureSourceMapping 为 topLevelTraversable 的 virtual pressure source mapping。
如果 topLevelVirtualPressureSourceMapping 包含 virtualPressureSourceType，则返回带有 WebDriver 错误代码 invalid argument 的错误。
令 supported 为从 parameters 使用 get a property with default 获取 "supported" 且默认值为 true 的结果。
令 virtualPressureSource 为一个新的 virtual pressure source。
将 virtualPressureSource 的 can provide samples 设置为 supported。
将 topLevelVirtualPressureSourceMapping[virtualPressureSourceType] 设置为 virtualPressureSource。
返回成功，数据为 null。

HTTP Method	URI Template
DELETE	/session/{session id}/pressuresource/{type}

该扩展命令删除给定的虚拟压力源，这意味着如果可用，针对给定 source type 的数据将以常规方式由非虚拟手段传递。

给定 session、URL variables 和 parameters 的远端步骤为：

令 virtualPressureSourceType 为 URL variables["type"] 的值。
如果 user agent 的 supported source types 不包含 virtualPressureSourceType，则返回带有 WebDriver 错误代码 invalid argument 的错误。
令 topLevelTraversable 为当前浏览上下文的 top-level traversable。
令 topLevelVirtualPressureSourceMapping 为 topLevelTraversable 的 virtual pressure source mapping。
令 pressureSource 为 topLevelVirtualPressureSourceMapping[virtualPressureSourceType]。
对于 pressureSource 的 connected platform collectors 中的每个 platformCollector：
1. 将 platformCollector 的 associated pressure source 设为 null。
移除 topLevelVirtualPressureSourceMapping[virtualPressureSourceType]。
返回成功，数据为 null。

HTTP Method	URI Template
POST	/session/{session id}/pressuresource/{type}

该扩展命令允许通过推送新的 pressure source sample 来更新虚拟压力源的状态。

注意

此算法使用的 parameters 参数的属性
参数名	值类型	是否必需
sample	`PressureState`	yes

给定 session、URL variables 和 parameters 的远端步骤为：

令 virtualPressureSourceType 为 URL variables["type"] 的值。
如果 user agent 的 supported source types 不包含 virtualPressureSourceType，则返回带有 WebDriver 错误代码 invalid argument 的错误。
令 topLevelTraversable 为当前浏览上下文的 top-level traversable。
令 topLevelVirtualPressureSourceMapping 为 topLevelTraversable 的 virtual pressure source mapping。
如果 topLevelVirtualPressureSourceMapping 不包含 virtualPressureSource，则返回带有 WebDriver 错误代码的错误，错误类型为 unsupported operation。
令 virtualPressureSource 为 topLevelVirtualPressureSourceMapping[virtualPressureSourceType]。
令 sample 为从 parameters 中调用 get a property "sample" 的结果。
如果 sample 的类型不是 PressureState，则返回带有 WebDriver 错误代码错误，错误类型为 invalid argument。
将 virtualPressureSource 的 latest sample 设置为一个新的 pressure source sample，其 data 为 sample 且 timestamp 为 unsafe shared current time。
以实现定义的方式，使 virtualPressureSource 的 latest sample 对 virtualPressureSource 的 connected platform collectors 可用。
返回成功，数据为 null。

本节为非规范性内容。

Example 2: 如何从回调访问 observer

const samples = [];

function pressureChange(records, observer) {
  for (const record of records) {
    samples.push(record.state);

    // We only want 20 samples.
    if (samples.length == 20) {
      observer.disconnect();
      return;
    }
  }
}

const observer = new PressureObserver(pressureChange);
observer.observe("cpu");

在下例中，当压力变为 critical 时，我们希望减少并发的视频流数量。为简化起见，我们只考虑这一种状态。

由于降低流数量可能不会立即使系统退出 critical 状态（或根本不能），我们采用一种策略：在仍处于 critical 状态时，每 30 秒逐次减少一个流。

我们通过确保回调至少每 30 秒被调用一次（或者在状态实际变化时被调用）来实现这一点。当状态变化时，我们会重置定时器。

Example 3: 根据 CPU 压力调整视频流数量

let timerId = -1;
function pressureChange(records) {
  // Clear timer every time we are called, either by an actual state change,
  // or when called by setTimeout (see below).
  if (timerId > 0) {
    clearTimeout(timerId);
  }

  // When entering critical state, we want to recheck every 30sec if we are
  // still in critical state and if so, further reduce our concurrent streams.
  // For this reason we create a timer for 30 seconds that will call us back
  // with the last result in there were no change.
  const lastRecordArray = [records.at(records.length - 1)];
  timerId = setTimeout(pressureChange.bind(this, lastRecordArray), 30_000);

  for (const record of records) {
    if (record.state == "critical") {
      let streamsCount = getStreamsCount();
      setStreamsCount(streamsCount--);
    }
  }
}

const observer = new PressureObserver(pressureChange);
observer.observe("cpu");

在下例中，我们演示如何使用 takeRecords()，以检索自上次回调以来累积的剩余 records。

建议在调用 disconnect() 之前这样做，否则 disconnect() 会清除它们，从而永远丢失。

例如，我们可能想在基准测试工作负载期间测量压力，因此希望获得该工作负载的精确时长内的压力遥测数据。这意味着在任务完成时立即断开所有观察者，并手动请求此时点之前可能尚未作为事件循环一部分交付的任何待处理压力遥测。

Example 4: 在断开连接之前处理所有状态变化

function logWorkloadStatistics(records) {
  // do something with records.
}

const observer = new PressureObserver(logWorkloadStatistics);
observer.observe("cpu");

// Read pending state change records, otherwise they will be cleared
// when we disconnect.
const records = observer.takeRecords();
logWorkloadStatistics(records);

observer.disconnect();

在下例中，我们展示如何通过对带有 source 的 unobserve() 的调用来告诉观察者停止监视特定源的状态变化。

注意

Example 5: 如何告诉观察者停止监视特定源的状态变化

const observer = new PressureObserver(records => { /* do something with records. */ });

observer.observe("cpu");
observer.observe("gpu");

// Callback now gets called whenever the pressure state changes for 'cpu' or 'gpu'.

observer.unobserve("gpu");

// Callback now only gets called whenever the pressure state changes for 'cpu'.

在下例中，我们展示如何通过调用 disconnect() 来告诉观察者停止监视任何状态变化。调用 disconnect() 将停止观察之前通过 observe() 调用所观察的所有源。

此外，它还会清除自上次回调被调用以来收集的所有待处理记录。

Example 6: 如何告诉观察者停止监视任何状态变化

const observer = new PressureObserver(records => { // do something with records. });
observer.observe("cpu");
observer.observe("gpu");

// some time later...

observer.disconnect();

// records will be an empty array, because of the previous disconnect().
const records = observer.takeRecords();

本节为非规范性内容。

激活数据收集 §10.6.2
已激活 §4.
调整后的压力状态 §9.
[[AfterPenaltyRecordMap]] （ PressureObserver 的内部槽 §7.
关联的压力源 §4.
断开校准 §11.2.5
[[Callback]] PressureObserver 的内部槽 §7.
可以提供样本 §13.1
促成因素的变化是实质性的 §9.
[[ChangesCountMap]] PressureObserver 的内部槽 §7.
连接的 platform collectors §13.1
constructor() 用于 PressureObserver §10.2.1
促成因素 §9.
"cpu" PressureSource 的枚举值 §3.2
"critical" PressureState 的枚举值 §8.
数据 §4.
数据收集 §10.6.2
停用数据收集 §10.6.2
disconnect() PressureObserver 的方法 §10.2.4
文档具有隐式焦点 §10.6.1
"fair" PressureState 的枚举值 §8.
获取虚拟压力源 §10.6.1
knownSources PressureObserver 的属性 §10.2.6
[[LastRecordMap]] PressureObserver 的内部槽 §7.
最新样本 §4.
最大排队记录数 §7.
[[MaxChangesThreshold]] PressureObserver 的内部槽 §7.
可能接收数据 §10.6.1
"nominal" PressureState 的枚举值 §8.
通知压力观察者 §10.6.5
[[ObservationWindow]] PressureObserver 的内部槽 §7.
observe() PressureObserver 的方法 §10.2.2
观察者 §7.
所属文档集合 §10.6.1
通过速率混淆测试 §10.6.1
通过速率测试 §10.6.1
[[PenaltyDuration]] PressureObserver 的内部槽 §7.
[[PendingObservePromises]] PressureObserver 的内部槽 §7.
platform collector §4.
platform collector 映射 §7.
压力观察者任务已入队 §7.
压力源 §4.
压力源样本 §4.
压力状态 §8.
PressureObserver 接口 §10.2
PressureObserver 任务来源 §10.6.4
PressureObserverOptions 字典 §10.4
PressureRecord 接口 §10.3
PressureSource 枚举 §3.2
PressureState 枚举 §8.
PressureUpdateCallback §10.1
处理单元 §3.1
排队一个压力观察者任务 §10.6.4
排队一条记录 §10.6.3
[[QueuedRecords]] PressureObserver 的内部槽 §7.
速率混淆 §11.2.2
已注册的观察者 §7.
已注册观察者列表 §7.
报告速率 §3.3
请求的采样间隔 §3.3
请求的采样率 §3.3
重置观察窗口 §10.6.1
sampleInterval 成员，用于 PressureObserverOptions §10.4.1
[[SampleIntervalMap]] §7.
采样率 §3.3
"serious" PressureState 的枚举值 §8.
应当派发 §10.6.1
source PressureRecord 的属性 §10.3.1
源类型 §4.
[[Source]] PressureRecord 的内部槽 §10.3
state PressureRecord 的属性 §10.3.2
[[State]] PressureRecord 的内部槽 §10.3
受支持的源类型 §7.
takeRecords() PressureObserver 的方法 §10.2.5
time PressureRecord 的属性 §10.3.3
[[Time]] PressureRecord 的内部槽 §10.3
时间戳 §4.
toJSON PressureRecord 的方法 §10.3.4
unobserve() PressureObserver 的方法 §10.2.3
用户代理 §15.
有效的源类型 §3.2
虚拟压力源 §13.1
虚拟压力源映射 §13.1

[DOM] 定义了以下项：
- Document 接口
- 文档
- 节点
- 节点文档（用于 Node）
[ECMASCRIPT] 定义了以下项：
- agent（针对 ECMAScript）
- globalThis 属性（针对 globalThis）
[HR-TIME] 定义了以下项：
- DOMHighResTimeStamp
- 相对高分辨率时间
- 不安全的当前时间（用于单调时钟）
- 不安全的共享当前时间
[HTML] 定义了以下项：
- 允许使用
- 关联文档
- 浏览上下文
- 子可导航项
- closing（针对 WorkerGlobalScope）
- DedicatedWorkerGlobalScope 接口
- fully active（针对 Document）
- 全局对象
- iframes 元素
- 并行
- 可导航（针对 Window）
- 节点可导航
- 源（origin）
- owner set（针对 WorkerGlobalScope）
- policy container（针对 WorkerGlobalScope）
- 排队一个全局任务
- 重新激活（针对 Document）
- 相关全局对象
- 相关设置对象
- 同源（same origin）
- 同站点（same site）
- 系统焦点（针对顶层可遍历对象）
- 任务来源
- 时间原点（针对环境设置对象）
- 顶层浏览上下文
- 顶层可遍历对象
- 顶层可遍历对象（针对浏览上下文）
- 卸载文档清理步骤
- Window 接口
- WorkerGlobalScope 接口
[INFRA] 定义了以下项：
- 追加（针对 list）
- 追加（针对 set）
- 断言（Assert）
- 清除（针对 map）
- 克隆（针对 list）
- 包含（针对 list）
- 包含（针对 map）
- 继续（针对迭代）
- 空（针对 list）
- 对每一项（针对 list）
- 对每一项（针对 map）
- 实现定义（implementation-defined）
- 项（针对 list）
- 项（针对 struct）
- 键定（针对 map）
- 列表（list）
- 有序映射（ordered map）
- 队列（queue）
- 移除（针对 list）
- 移除（针对 map）
- 集合（set）
- 大小（针对 list）
- 结构体（struct）
- 元组（tuples）
- 并集（针对 set）
- 值（针对 map）
[MEDIACAPTURE-STREAMS] 定义了以下项：
- 上下文正在捕获
[PERMISSIONS-POLICY] 定义了以下项：
- 默认允许列表（针对策略控制的功能）
- 策略控制的功能
[WEBDRIVER2] 定义了以下项：
- 当前浏览上下文
- 错误
- 错误代码
- 扩展命令 URI 模板
- 扩展命令
- 获取属性
- 获取具有默认值的属性
- 无效参数
- 远端步骤
- 成功
- 不受支持的操作
[WEBIDL] 定义了以下项：
- 一个新的 Promise
- 以某值被拒绝的 Promise
- AbortError 异常
- [Default] 扩展属性
- 默认 toJSON 步骤
- [EnforceRange] 扩展属性
- [Exposed] 扩展属性
- FrozenArray 接口
- getter 步骤
- 调用（invoke）
- NotAllowedError 异常
- NotSupportedError 异常
- object 类型
- Promise 接口
- 在 Promise 定结后执行步骤（React）
- 已拒绝
- 已解析
- [SameObject] 扩展属性
- [SecureContext] 扩展属性
- 序列（sequence）
- this
- TypeError 异常
- undefined 类型
- unsigned long 类型

WebIDLenum PressureSource { "cpu" };

enum PressureState { "nominal", "fair", "serious", "critical" };

callback PressureUpdateCallback = undefined (
  sequence<PressureRecord> changes,
  PressureObserver observer
);

[Exposed=(DedicatedWorker,SharedWorker,Window), SecureContext]
interface PressureObserver {
  constructor(PressureUpdateCallback callback);

  Promise<undefined> observe(PressureSource source, optional PressureObserverOptions options = {});
  undefined unobserve(PressureSource source);
  undefined disconnect();
  sequence<PressureRecord> takeRecords();

  [SameObject] static readonly attribute FrozenArray<PressureSource> knownSources;
};

[Exposed=(DedicatedWorker,SharedWorker,Window), SecureContext]
interface PressureRecord {
  readonly attribute PressureSource source;
  readonly attribute PressureState state;
  readonly attribute DOMHighResTimeStamp time;
  [Default] object toJSON();
};

dictionary PressureObserverOptions {
  [EnforceRange] unsigned long sampleInterval = 0;
};

计算压力等级 1

摘要

文档状态

1. 介绍

2. 特性检测说明

3. 基本概念

3.1 处理单元

3.2 压力来源

3.3 采样与报告速率

4. 平台原语

5. 用户通知

6. 策略控制

7. 内部插槽定义

8. 压力状态

9. 影响因素

10. 压力观察器

10.1 PressureUpdateCallback 回调

10.2 PressureObserver 对象

10.2.1 constructor() 方法

10.2.2 observe() 方法

10.2.3 unobserve() 方法

10.2.4 disconnect() 方法

10.2.5 takeRecords() 方法

10.2.6 knownSources 属性

10.3 PressureRecord 接口

10.3.1 source 属性

10.3.2 state 属性

10.3.3 time 属性

10.3.4 toJSON 成员

10.4 PressureObserverOptions 字典

10.4.1 sampleInterval 成员

10.5 生命周期与垃圾回收

10.6 处理模型

10.6.1 支持算法

10.6.2 数据收集与传递

10.6.3 入队 PressureRecord

10.6.4 入队压力观察任务

10.6.5 通知压力观察者

10.6.6 处理完全激活状态的变化

10.6.7 处理 worker 状态变化

11. 安全与隐私注意事项

11.1 隐私与安全威胁类型

11.1.1 计时攻击

11.1.2 跨站隐蔽信道

11.1.3 定向去匿名化攻击

11.2 缓解策略

11.2.1 数据最小化

11.2.2 速率混淆

11.2.3 速率混淆规范性参数

11.2.4 速率混淆非规范性参数

11.2.5 中断校准

11.2.6 中断校准参数

11.2.7 同源限制

12. 可访问性 注意事项

13. 自动化

13.1 虚拟压力源

13.1.1 扩展命令

13.1.1.1 创建虚拟压力源

13.1.1.2 删除虚拟压力源

13.1.1.3 更新虚拟压力源

14. 示例

15. 符合性

A. 致谢

B. 实质性更改摘要

B.1 自 首次公开工作草案 (2022/12/20) 以来的更改

B.2 索引

B.2.1 本规范定义的术语

B.2.2 引用中定义的术语

B.3 IDL 索引

C. 参考文献

C.1 规范性参考文献

C.2 信息性参考文献

10.1 `PressureUpdateCallback` 回调

10.2 `PressureObserver` 对象

10.2.1 `constructor()` 方法

10.2.2 `observe()` 方法

10.2.3 `unobserve()` 方法

10.2.4 `disconnect()` 方法

10.2.5 `takeRecords()` 方法

10.2.6 `knownSources` 属性

10.3 `PressureRecord` 接口

10.3.1 `source` 属性

10.3.2 `state` 属性

10.3.3 `time` 属性

10.3.4 `toJSON` 成员

10.4 `PressureObserverOptions` 字典

10.4.1 `sampleInterval` 成员

12. 可访问性注意事项

B.1 自首次公开工作草案 (2022/12/20) 以来的更改