私有聚合 API

[Exposed=(InterestGroupScriptRunnerGlobalScope,SharedStorageWorklet),
 SecureContext]
interface PrivateAggregation {
  undefined contributeToHistogram(PAHistogramContribution contribution);
  undefined contributeToHistogramOnEvent(DOMString event,
                                         record<DOMString, any> contribution);
  undefined enableDebugMode(optional PADebugModeOptions options = {});
};

dictionary PAHistogramContribution {
  required bigint bucket;
  required long value;
  bigint filteringId = 0;
};

dictionary PADebugModeOptions {
  required bigint debugKey;
};

contributeToHistogram(PAHistogramContribution contribution) 方法步骤 为：

1. 令 validationResult 为在给定 contribution 和 this 的 作用域细节 的情况下，验证直方图贡献 的结果。

2. 如果 validationResult 是一个 异常，则 抛出 validationResult。

3. 断言：validationResult 是一个 贡献缓存 条目。

4. 将 validationResult 追加到 贡献缓存。

考虑接受 贡献数组。[议题 #44]

contributeToHistogramOnEvent(event, contribution) 方法步骤为：

1. 令 defaultProcessingResult 为运行 this 的 应 执行默认的 contributeToHistogramOnEvent() 处理 的结果，给定 this、event 和 contribution。

2. 如果 defaultProcessingResult 是一个 异常，则 抛出 defaultProcessingResult。

3. 如果 defaultProcessingResult 为 false，则返回。

4. 将 contribution 设为把 contribution 的 JavaScript 值 转换为 IDL 类型 PAHistogramContribution 的结果。

   注： 如果 contribution 不兼容，这会抛出 TypeError。

5. 令 validationResult 为在给定 contribution 和 this 的 作用域细节 的情况下，验证直方图贡献 的结果。

6. 如果 validationResult 是一个 异常，则 抛出 validationResult。

7. 断言：validationResult 是一个 贡献缓存 条目。

8. 如果 event 不是以 "reserved." 开头，则 抛出一个 TypeError。

9. 令 unprefixedEvent 为 event 中从 "reserved." 的 长度 到 event 的 长度 的 代码单元子串。

10. 如果 unprefixedEvent 是任何 内部 错误事件：

    1. 令 maybeContributionCacheEntry 的 错误事件 为 unprefixedEvent。

    2. 将 maybeContributionCacheEntry 追加到 贡献缓存。

注： 为了向前兼容，我们不会对 以 "reserved." 开头的无法识别的 事件抛出错误。

enableDebugMode(optional PADebugModeOptions options) 方法步骤为：

1. 令 scopingDetails 为 this 的 作用域细节。

2. 令 debugScope 为运行 scopingDetails 的 获取调试作用域步骤 的结果。

3. 如果 调试作用域 映射[debugScope] 存在，则 抛出一个 "DataError" DOMException。

   注： 如果已经为此 调试作用域运行过 enableDebugMode()，就会发生这种情况。

4. 令 debugKey 为 null。

5. 如果给出了 options：

   1. 如果 options["debugKey"] 不 包含在 0 到 2⁶⁴ 的范围内（不含端点），则 抛出一个 "DataError" DOMException。

   2. 将 debugKey 设为 options["debugKey"]。

6. 令 debugDetails 为一个新的 调试细节，其项目为：

   enabled

   true

   key

   debugKey

7. 可选地，将 debugDetails 设为一个新的 调试细节。

   注： 这允许用户代理在全局范围内 或仅对某些调用者使调试模式不可用。

8. 设置 调试作用域映射[debugScope] 为 debugDetails。

确保错误属于 适当的类型，例如 InvalidAccessError 已 废弃。

class ExampleOperation {
  async run(data) {
    privateAggregation.contributeToHistogram(...)  // 这是允许的。
  }
}
register('example-operation', ExampleOperation);

privateAggregation.contributeToHistogram(...)  // 这会导致错误。

要在给定 PrivateAggregation this 时获取 privateAggregation：

1. 令 scopingDetails 为 this 的 作用域细节。

2. 如果 scopingDetails 为 null，则 抛出一个 "NotAllowedError" DOMException。

   注： 这表示 API 尚不可用， 例如，因为脚本加载后的 初始执行尚未完成。

   考虑 改进此处的开发者易用性（例如提供一种检测 此情况的方式）。

3. 如果 this 的 允许使用 为 false，则 抛出一个 "InvalidAccessError" DOMException。

4. 返回 this。

确保错误属于 适当的类型，例如 InvalidAccessError 已 废弃。

要在给定一个 贡献 缓存条目 entry 时，向贡献缓存追加条目：

1. 将 entry 追加到 贡献缓存。

要在给定 调试 作用域 debugScope 时，获取调试 细节，执行以下步骤。它们返回一个 调试细节。

1. 如果 调试作用域 映射[debugScope] 存在，返回 调试作用域 映射[debugScope]。

2. 否则，返回一个新的 调试细节。

要在给定 调试 作用域 debugScope 和一个可选的 调试细节或 null debugDetailsOverride（默认 null）时，标记调试 作用域完成：

1. 令 debugDetails 为 debugDetailsOverride。

2. 如果 调试作用域 映射[debugScope] 存在：

   1. 断言：debugDetailsOverride 为 null。

      注： 如果尚未以其他方式 设置调试细节，则可以提供覆盖。

   2. 将 debugDetails 设为 调试作用域映射[debugScope]。

   3. 移除 调试作用域映射[debugScope]。

   4. 如果 debugDetails 的 key 不为 null，则 断言： debugDetails 的 enabled 为 true。

3. 如果 debugDetails 为 null，则将 debugDetails 设为一个新的 调试细节。

4. 对于 贡献缓存中的每个 entry：

   1. 如果 entry 的 调试作用域为 debugScope， 则将 entry 的 调试细节设为 debugDetails。

要在给定 预先指定的报告参数 preSpecifiedParams 和 上下文类型 api 时，确定报告是否应被确定性地发送，执行以下步骤。它们返回一个 布尔值：

1. 如果 preSpecifiedParams 的 context ID 不为 null，则返回 true。

2. 如果 preSpecifiedParams 的 filtering ID max bytes 不是 default filtering ID max bytes，则返回 true。

3. 令 effectiveMaxContributions 为使用 api 和 preSpecifiedParams 的 max contributions 确定 max contributions 的结果。

4. 令 defaultMaxContributions 为 default maxContributions by API[api]。

5. 如果 effectiveMaxContributions 不是 defaultMaxContributions，则返回 true。

6. 返回 false。

注： 有时必须发送一个“null report”以隐藏没有贡献这一事实。例如，预算本身就是 跨站点数据，它可能不足以满足所请求的 贡献。或者，调用者可能在读取跨站点数据后选择不做任何 贡献。在这些场景中，缺少报告可能会向报告端点泄露跨站点数据。见 防止通过报告数量造成 泄露。

要在给定一个 批处理作用域 batchingScope、一个 源 reportingOrigin、一个 上下文类型 contextType 和一个 时刻或 null timeout 时，处理批处理作用域的贡献：

注： 嵌入 API 预计在报告不是 确定性的情况下，或 超时已经到达（即如果超时导致此调用被 触发）的情况下，将 timeout 设为 null。（对于 确定性报告，总是必须设置超时。）

1. 令 batchEntries 为一个新的 列表。

2. 对于 贡献缓存中的每个 entry：

   1. 如果 entry 的 批处理作用域为 batchingScope：

      1. 断言：entry 的 调试细节 不为 null。

         注： 这断言 标记调试作用域完成 步骤 在 处理 批处理作用域的贡献步骤之前运行。

      2. 将 entry 追加到 batchEntries。

3. 令 aggregationCoordinator 为 默认 聚合协调器。

4. 如果 聚合协调器 映射[batchingScope] 存在：

   1. 将 aggregationCoordinator 设为 聚合协调器 映射[batchingScope]。

   2. 移除 聚合协调器 映射[batchingScope]。

5. 令 preSpecifiedParams 为一个新的 预先指定的报告参数。

6. 如果 预先指定的报告参数 映射[batchingScope] 存在：

   1. 将 preSpecifiedParams 设为 预先指定的报告参数 映射[batchingScope]。

   2. 移除 预先指定的报告参数 映射[batchingScope]。

7. 令 isDeterministicReport 为在给定 preSpecifiedParams 和 contextType 时 确定报告 是否应被确定性地发送的结果。

8. 如果 isDeterministicReport 为 false，则 断言： timeout 为 null。

   注： 超时只能用于 确定性报告。

9. 如果 batchEntries 为空 且 isDeterministicReport 为 false， 则返回。

10. 令 batchedContributions 为一个新的 有序映射。

11. 对于 batchEntries 中的每个 entry：

    1. 从 贡献缓存移除 entry。

    2. 令 debugDetails 为 entry 的 调试细节。

    3. 如果 batchedContributions[debugDetails] 不 存在，则将 batchedContributions[debugDetails] 设置 为一个新的 待处理贡献。

    4. 如果 entry 的 错误事件为 null：

       1. 将 entry 的 contribution 追加到 batchedContributions[debugDetails] 的 unconditional contributions。

    5. 否则：

       1. 令 conditionalContributions 为 batchedContributions[debugDetails] 的 conditional contributions。

       2. 如果 conditionalContributions[errorEvent] 不 存在，则将 conditionalContributions[errorEvent] 设置 为一个新的 列表。

       3. 将 entry 的 contribution 追加到 conditionalContributions[errorEvent]。

12. 如果 batchedContributions 为空：

    1. 令 debugDetails 为一个新的 调试细节。

    2. 将 batchedContributions[debugDetails] 设为一个新的 待处理贡献。

13. 对于 batchedContributions 的每个 debugDetails → pendingContributions：

    1. 使用 reportingOrigin、contextType、 pendingContributions、debugDetails、 aggregationCoordinator、preSpecifiedParams 和 timeout 执行 报告创建和调度 步骤。

注： 这些步骤根据贡献的 调试细节 拆分贡献，因为每个报告只能拥有一组元数据。

要在给定 一个 源 origin 时，确定源是否为聚合 协调器，执行以下步骤。它们返回一个 布尔值。

1. 返回 origin 是否为 聚合协调器。

要在给定一个 USVString originString 时，获取 Private Aggregation 协调器，执行以下步骤。它们返回一个 聚合协调器 或一个 DOMException。

1. 令 url 为对 originString 运行 URL 解析器的结果。

2. 如果 url 是 failure 或 null，则返回一个名称为 "SyntaxError" 的新 DOMException。

   考虑 在路径非空时抛出错误。

3. 令 origin 为 url 的 源。

4. 如果在给定 origin 时，确定源 是否为聚合协调器的结果为 false，则返回一个名称为 "DataError" 的新 DOMException。

5. 返回 origin。

要在给定 一个 源 origin 和一个 批处理作用域 batchingScope 时，设置批处理 作用域的聚合协调器：

1. 断言：origin 是一个 聚合 协调器。

2. 设置 聚合协调器 映射[batchingScope] 为 origin。

要在给定一个 预先指定的报告参数 params 和 一个 批处理作用域 batchingScope 时，设置批处理 作用域的预先指定报告 参数：

1. 令 contextId 为 params 的 context ID。

2. 断言：contextId 为 null，或 contextId 的 长度不 大于 64。

3. 令 filteringIdMaxBytes 为 params 的 filtering ID max bytes。

4. 断言：filteringIdMaxBytes 被 有效的 filtering ID 最大字节数范围包含

5. 令 maxContributions 为 params 的 max contributions。

6. 断言：maxContributions 为 null 或大于零。

7. 设置 预先指定的报告参数 映射[batchingScope] 为 params。

要在给定一个 PAHistogramContribution contribution 和一个 作用域细节 scopingDetails 时，验证 直方图贡献，执行以下 步骤。它们返回一个 贡献缓存条目或一个 异常。

1. 如果 contribution["bucket"] 不 包含在 0 到 2¹²⁸ 的 范围内（不含端点）， 则返回一个 RangeError。

2. 如果 contribution["value"] 为负，则返回一个 RangeError。

3. 令 batchingScope 为运行 scopingDetails 的 获取批处理作用域步骤的结果。

4. 令 filteringIdMaxBytes 为 默认 filtering ID 最大字节数。

5. 如果 预先指定的报告参数 映射[batchingScope] 存在：

   1. 将 filteringIdMaxBytes 设为 预先指定的报告参数 映射[batchingScope] 的 filtering ID max bytes。

6. 如果 contribution["filteringId"] 不 包含在 0 到 256^{filteringIdMaxBytes} 的 范围内（不含端点），则返回一个 RangeError。

7. 返回一个新的 贡献缓存条目，其项目为：

   contribution

   contribution

   batching scope

   batchingScope

   debug scope

   运行 scopingDetails 的 获取调试作用域步骤的结果。

确保错误属于 适当的类型，例如 InvalidAccessError 已 废弃。

要使用一个 源 reportingOrigin、一个 上下文类型 api、一个 待处理 贡献 pendingContributions、一个 调试细节 debugDetails、一个 聚合协调器 aggregationCoordinator、一个 预先指定的报告参数 preSpecifiedParams 和一个 时刻或 null timeout，执行 报告创建和调度步骤：

1. 断言：reportingOrigin 是一个 潜在可信源。

2. 可选地，返回。

   注： 此 实现定义的条件旨在 允许 用户代理基于若干原因丢弃报告，例如用户 选择退出、源未被登记，或 达到待处理报告数量限制。

3. 令 currentWallTime 为 当前墙上时间。

4. 令 allUnmergedContributions 为在给定 reportingOrigin、api、pendingContributions、 preSpecifiedParams、timeout 和 currentWallTime 时，编译所有未合并贡献的结果。

5. 令 isDeterministicReport 为在给定 preSpecifiedParams 和 api 时，确定报告 是否应被确定性地发送的结果。

6. 令 effectiveMaxContributions 为使用 api 和 preSpecifiedParams 的 max contributions 确定 max contributions 的结果。

7. 令 keptMergeKeys 为一个新的 集合。

8. 对于 allUnmergedContributions 中的每个 contribution：

   1. 令 mergeKey 为 contribution 的 合并键。

   2. 如果 keptMergeKeys 的 大小为 effectiveMaxContributions 且 keptMergeKeys 不 包含 mergeKey，则 继续。

   3. 否则，将 mergeKey 追加到 keptMergeKeys。

9. 从 allUnmergedContributions 中移除所有其 合并键未被 keptMergeKeys 包含 的项目。

10. 令 finalBudgetResults 为在给定 allUnmergedContributions、reportingOrigin、api、 currentWallTime 和 true 时，查询预算的结果。

11. 断言：finalBudgetResults 的 大小等于 allUnmergedContributions 的 大小。

12. 对于从 0 到 finalBudgetResults 的 大小的范围中的每个 i（不含端点）：

    1. 如果 finalBudgetResults[i] 为 false，则将 allUnmergedContributions[i] 的 value 设为 0。

13. 从 allUnmergedContributions 中移除所有 value 为 0 的项目。

14. 令 mergedContributionsMap 为一个新的 有序映射。

15. 对于 allUnmergedContributions 中的每个 contribution：

    1. 令 mergeKey 为 contribution 的 合并键。

    2. 如果 mergedContributionsMap[mergeKey] 存在，则将 contribution 的 value 加到 mergedContributionsMap[mergeKey] 的 value。

    3. 否则，将 mergedContributionsMap[mergeKey] 设置为 contribution。

16. 令 mergedContributions 为 mergedContributionsMap 的 值。

17. 断言：mergedContributions 的 大小小于或等于 effectiveMaxContributions，

18. 如果 mergedContributions 为空 且 isDeterministicReport 为 false，则返回。

19. 令 report 为在给定 reportingOrigin、api、 mergedContributions、debugDetails、aggregationCoordinator、 preSpecifiedParams、timeout 和 currentWallTime 时，获取 可聚合报告的结果。

20. 将 report 追加到用户代理的 可聚合报告缓存。

要在给定一个 源 reportingOrigin、一个 上下文类型 api、一个 待处理 贡献 pendingContributions、一个 预先指定的 报告参数 preSpecifiedParams、一个 时刻或 null timeout，以及一个 时刻 currentWallTime 时，编译所有未合并贡献，执行以下步骤。它们返回一个由 PAHistogramContribution 组成的 列表。

1. 令 wasTimeoutReached 为一个 布尔值，表示 isDeterministicReport 为 true 且 timeout 为 null 是否同时成立。

   更新从 Shared Storage 发送的 timeout 以保持一致。

2. 在给定 pendingContributions、 "contribution-timeout-reached" 和 wasTimeoutReached 时，记录内部错误事件 结果。

3. 令 provisionalBudgetResults 为在给定 pendingContributions 的 unconditional contributions、reportingOrigin、api、currentWallTime 和 false 时，查询预算的结果。

4. 断言：provisionalBudgetResults 的 大小等于 pendingContributions 的 unconditional contributions 的 大小。

5. 对于从 0 到 provisionalBudgetResults 的 大小的范围中的每个 i（不含端点）：

   1. 如果 provisionalBudgetResults[i] 为 false，则将 pendingContributions 的 unconditional contributions[i] 的 value 设为 0。

6. 从 pendingContributions 的 unconditional contributions 中移除所有 value 为 0 的项目。

7. 令 insufficientBudget 为一个 布尔值，表示 provisionalBudgetResults 中是否有任何值为 false。

8. 在给定 pendingContributions、 "insufficient-budget" 和 insufficientBudget 时，记录内部错误事件 结果。

9. 令 pendingReportLimitReached 为一个由 实现定义的算法确定的 布尔值。

   注： 这旨在表示同时挂起在预算查询上的报告数量限制 已达到（但未超出）的情况。

10. 在给定 pendingContributions、 "pending-report-limit-reached" 和 pendingReportLimitReached 时，记录内部错误事件 结果。

11. 令 isEmptyAndWouldBeDropped 为一个 布尔值，表示 isDeterministicReport 为 false 且 pendingContributions 的 unconditional contributions 为空 是否同时成立。

12. 在给定 pendingContributions、 "empty-report-dropped" 和 isEmptyAndWouldBeDropped 时，记录内部错误事件 结果。

13. 令 effectiveMaxContributions 为使用 api 和 preSpecifiedParams 的 max contributions 确定 max contributions 的结果。

14. 令 tooManyContributions 为 false。

15. 令 provisionallyApprovedMergeKeys 为一个新的 集合。

16. 对于 pendingContributions 的 unconditional contributions中的每个 contribution：

    1. 令 mergeKey 为 contribution 的 合并键。

    2. 如果 provisionallyApprovedMergeKeys 的 大小为 effectiveMaxContributions，且 provisionallyApprovedMergeKeys 不 包含 mergeKey，则将 tooManyContributions 设为 true。

    3. 否则，将 mergeKey 追加到 provisionallyApprovedMergeKeys。

17. 在给定 pendingContributions、 "too-many-contributions" 和 tooManyContributions 时，记录内部错误事件 结果。

18. 从 pendingContributions 的 unconditional contributions 中移除所有其 合并键未被 provisionallyApprovedMergeKeys 包含 的项目。

19. 令 reportSuccess 为一个 布尔值，表示 以下各项中没有一项为 true：isEmptyAndWouldBeDropped、tooManyContributions、 insufficientBudget、pendingReportLimitReached。

20. 在给定 pendingContributions、 "report-success" 和 reportSuccess 时，记录内部错误事件 结果。

21. 令 allUnmergedContributions 为一个新的 列表。

22. 对于 所有错误事件中的每个 errorEvent：

    1. 如果 pendingContributions 的 conditional contributions[errorEvent] 不 存在， 则 继续。

    2. 断言：pendingContributions 的 triggered error events 包含 errorEvent 或 errorEvent 为 "already triggered external error"。

       注： 当某个内部错误事件 被确定为未触发时， 其条件贡献会由 记录内部错误事件 结果移除

    3. 用 pendingContributions 的 conditional contributions[errorEvent] 扩展 allUnmergedContributions。

23. 用 pendingContributions 的 unconditional contributions 扩展 allUnmergedContributions。

    注： 无条件贡献放在最后， 以优先确保错误的成功测量。

24. 返回 allUnmergedContributions。

每个 PAHistogramContribution contribution 都有一个 合并键， 它是以下 元组：(contribution 的 bucket, contribution 的 filteringId)。

注： 同一报告中的两个 PAHistogramContribution 当且仅当具有相同的合并键时，才能被合并。

要在给定由 PAHistogramContribution 组成的 列表 contributions、一个 源 origin、一个 上下文类型 api、一个 时刻 currentTime 和一个 布尔值 consumeIfPermitted 时，查询预算，执行以下步骤。它们返回一个与 contributions 具有相同 大小的 布尔值列表。

1. 令 resultForEachContribution 为一个新的由 布尔值组成的 列表。

2. 令 approvedValueSum 为 0。

3. 对于 contributions 中的每个 contribution：

   1. 令 valueToRequest 为 approvedValueSum + contribution 的 value。

      注： 这确保每个贡献的结果都会 考虑来自此次调用的任何先前已批准贡献（即使 consumeIfPermitted 为 false）。

   2. 令 sufficientBudget 为一个 布尔值， 由一个在给定 valueToRequest、origin、api 和 currentTime 时的 实现定义的算法确定。 该算法应将预算限制在一段时间内的使用量之内， 例如过去 24 小时内的贡献总和。

   3. 如果 sufficientBudget 为 true，则将 contribution 的 value 加到 approvedValueSum。

   4. 将 sufficientBudget 追加到 resultForEachContribution。

      注： 返回值中的第 i 个元素 表示是否有足够的剩余预算来发送 contributions[i] 的 value。

4. 如果 consumeIfPermitted 为 true，则使用一个在给定 approvedValueSum、origin、api 和 currentTime 时的 实现定义的算法消耗预算。

5. 返回 resultForEachContribution。

要在给定一个 待处理 贡献 pendingContributions、一个 内部错误事件 errorEvent 和一个 布尔值 wasTriggered 时，记录内部错误事件结果，执行以下步骤：

1. 如果 wasTriggered 为 true，则将 errorEvent 追加到 pendingContributions 的 triggered error events。

2. 否则，移除 pendingContributions 的 conditional contributions[errorEvent]。

要在给定一个 源 reportingOrigin、一个 上下文类型 api、一个由 PAHistogramContribution 组成的 列表 contributions、一个 调试 细节 debugDetails、一个 聚合协调器 aggregationCoordinator、一个 预先指定的报告参数 preSpecifiedParams、一个 时刻或 null timeout 以及一个 时刻 currentTime 时， 获取 可聚合报告，执行以下步骤。它们返回一个 可聚合报告。

1. 断言：reportingOrigin 是一个 潜在可信源。

2. 令 reportTime 为在给定 currentTime 和 timeout 时运行 获取 报告交付时间的结果。

3. 令 report 为一个新的 可聚合报告，其项目为：

   reporting origin

   reportingOrigin

   original report time

   reportTime

   report time

   reportTime

   contributions

   contributions

   api

   api

   report ID

   生成随机 UUID的结果。

   debug details

   debugDetails

   aggregation coordinator

   aggregationCoordinator

   context ID

   preSpecifiedParams 的 context ID

   filtering ID max bytes

   preSpecifiedParams 的 filtering ID max bytes

   max contributions

   使用 api 和 preSpecifiedParams 的 max contributions 确定 max contributions 的结果。

   queued

   false

4. 返回 report。

要在给定一个 时刻 currentTime 和一个 时刻或 null timeout 时，获取 报告交付时间，执行以下步骤。 它们返回一个 时刻。

1. 如果 timeout 不为 null：

   1. 返回 timeout。

2. 如果 自动化本地测试模式已启用 为 true，则返回 currentTime。

3. 令 r 为一个介于 0（含）和 1（不含）之间、具有 均匀概率的随机双精度数。

4. 返回 currentTime + 最小报告延迟 + r * 随机化报告延迟。

要在给定一个 上下文类型 api 和 一个正整数或 null maxContributions 时，确定 max contributions，执行以下步骤。它们 返回一个正整数。

1. 如果 maxContributions 为 null，则返回 default maxContributions by API[api]。

2. 如果 maxContributions 大于 maximum maxContributions，则返回 maximum maxContributions。

3. 返回 maxContributions。

要在给定一个由 可聚合 报告组成的 列表 reports 时，尝试将报告排队以便发送：

1. 对于 reports 中的每个 report，并行运行这些 步骤：

   1. 运行这些步骤，但在 用户 代理关闭时中止：

      1. 如果 report 的 queued 值为 true，则返回。

      2. 将 report 的 queued 值设为 true。

      3. 令 currentWallTime 为 当前墙上时间。

      4. 如果 report 的 report time 早于 currentWallTime，则将 report 的 report time 设为 currentWallTime 加上一个 实现定义的随机 非负 持续时间。

         注： 启动时， 用户代理可能需要发送 许多在浏览器关闭期间已过报告时间的报告。 添加随机延迟可防止报告在时间上被关联。

      5. 等待直到 当前墙上时间等于或 晚于 report 的 report time。

      6. 可选地，再等待一个 实现定义的非负 持续时间。

         注： 这旨在 允许用户代理优化设备 资源使用，并等待用户代理上线。

      7. 使用 report 运行 尝试交付报告。

   2. 如果中止，则将 report 的 queued 值设为 false。

      注： 在 用户 代理下次启动时执行此步骤可能更实际。

要在给定一个 可聚合报告 report 时，尝试 交付报告：

1. 令 url 为在给定 report 的 reporting origin 和 report 的 api 时，获取报告端点的结果。

2. 令 data 为在给定 report 时，序列化可聚合报告的结果。

3. 如果 data 是错误，则从 可聚合报告缓存中移除 report。

   我们需要 将此任务排队吗？

4. 令 request 为在给定 url 和 data 时，创建报告请求的结果。

5. 排队一个任务，以 fetch request，并将 processResponse 设为 以下步骤：

   1. 令 shouldRetry 为一个 实现定义的 布尔值。如果未发生错误，其值 应为 false。

   2. 如果 shouldRetry 为 true：

      1. 将 report 的 report time 设为 当前墙上时间加上一个 实现定义的非负 持续时间。

      2. 将 report 的 queued 值设为 false。

   3. 否则，从 可聚合报告缓存中移除 report。

要在给定一个 源 reportingOrigin 和 上下文类型 api 时，获取 报告端点，执行以下 步骤。它们返回一个 URL。

1. 断言：reportingOrigin 是一个 潜在可信源。

2. 令 path 为以下项的 拼接： «".well-known/private-aggregation/report-", api»。

   注册此 well-known 目录。[议题 #67]

3. 令 base 为对 reportingOrigin 的 序列化运行 URL 解析器的结果。

4. 断言：base 不是 failure。

5. 令 result 为以 base 对 path 运行 URL 解析器的结果。

6. 断言：result 不是 failure。

7. 返回 result。

要在给定一个 URL url 和一个 字节序列 body 时，创建报告 请求：

1. 令 request 为一个新的 请求，其属性如下：

   method

   "POST"

   URL

   url

   header list

   «("Content-Type", "application/json")»

   unsafe-request flag

   set

   body

   body

   client

   null

   service-workers mode

   "none"

   initiator

   ""

   referrer

   "no-referrer"

   mode

   "cors"

   credentials mode

   "omit"

   cache mode

   "no-store"

2. 返回 request。

要在给定一个 可聚合 报告 report 时，序列化可聚合报告，执行以下步骤。它们返回一个 字节序列或一个 错误。

1. 令 aggregationServicePayloads 为在给定 report 时，获取聚合服务 载荷的结果。

2. 如果 aggregationServicePayloads 是一个错误，则返回 aggregationServicePayloads。

3. 令 data 为一个由以下键/值对组成的 有序映射：

   "aggregation_coordinator_origin"

   report 的 aggregation coordinator，已序列化。

   "aggregation_service_payloads"

   aggregationServicePayloads

   "shared_info"

   在给定 report 时，获取报告 shared info 的结果。

4. 令 debugKey 为 report 的 debug details 的 key。

5. 如果 debugKey 不为 null，则将 data["debug_key"] 设置为 debugKey。

6. 令 contextId 为 report 的 context ID。

7. 如果 contextId 不为 null，则将 data["context_id"] 设置为 contextId。

8. 返回对 data 执行 将 infra 值序列化为 JSON 字节所得的 字节序列。

要在给定一个 可聚合 报告 report 时，获取聚合服务载荷，执行以下步骤。它们返回一个由 映射组成的 列表或一个错误。

1. 令 publicKeyTuple 为在给定 report 的 aggregation coordinator 时，获取用于 加密的公钥的结果。

2. 如果 publicKeyTuple 是一个错误，则返回 publicKeyTuple。

3. 令 (pkR, keyId) 为 publicKeyTuple。

4. 令 plaintextPayload 为在给定 report 时，获取 明文载荷的结果。

5. 令 sharedInfo 为在给定 report 时，获取 报告 shared info 的结果。

6. 令 encryptedPayload 为在给定 plaintextPayload、pkR 和 sharedInfo 时，加密载荷 的结果。

7. 如果 encryptedPayload 是一个错误，则返回 encryptedPayload。

8. 令 aggregationServicePayloads 为一个新的 列表。

9. 令 aggregationServicePayload 为一个由以下 键/值对组成的 有序映射：

   "key_id"

   keyId

   "payload"

   encryptedPayload，base64 编码

10. 如果 report 的 debug details 的 enabled 字段为 true：

    1. 设置 aggregationServicePayload[debug_cleartext_payload] 为 plaintextPayload，base64 编码。

11. 将 aggregationServicePayload 追加到 aggregationServicePayloads。

12. 返回 aggregationServicePayloads。

要在给定一个 聚合 协调器 aggregationCoordinator 时，获取用于加密的公钥，执行以下步骤。它们返回 一个由公钥和一个 字符串组成的 元组， 或一个错误。

1. 令 url 为一个新的 URL 记录。

2. 将 url 的 scheme 设为 aggregationCoordinator 的 scheme。

3. 将 url 的 host 设为 aggregationCoordinator 的 host。

4. 将 url 的 port 设为 aggregationCoordinator 的 port。

5. 将 url 的 path 设为 «".well-known", "aggregation-service", "v1", "public-keys"»。

6. 返回一个 实现定义的 元组，它由来自 url 的 公钥 和一个应唯一标识该公钥的 字符串组成；或者， 如果用户代理未能从 url 获取公钥， 则返回错误。此步骤可以是异步的。

以 fetch 的形式指定此内容。添加有关使用哪些加密 标准、长度要求等的细节。

注： 鼓励用户代理强制执行 定期密钥轮换。如果存在 多个密钥，用户代理可以为每次加密操作独立地均匀随机选择 一个密钥。

要在给定一个 可聚合报告 report 时，获取 明文载荷，执行以下 步骤。它们返回一个 字节序列。

1. 令 payloadData 为一个新的 列表。

2. 令 contributions 为 report 的 contributions。

3. 令 maxContributions 为 report 的 max contributions。

4. 断言：contributions 的 大小不 大于 maxContributions。

5. 当 contributions 的 大小小于 maxContributions 时，循环：

   1. 令 nullContribution 为一个新的 PAHistogramContribution， 其 项目为：

      bucket

      0

      value

      0

      filteringId

      0

   2. 将 nullContribution 追加到 contributions。

   注： 此填充可防止 贡献数量通过加密载荷大小 泄露，见下方讨论。

6. 对于 report 的 contributions 中的每个 contribution：

   1. 令 filteringIdMaxBytes 为 report 的 filtering id max bytes。

   2. 断言：contribution["filteringId"] 被 包含在 0 到 256^{filteringIdMaxBytes} 的 范围内（不含端点）。

   3. 令 contributionData 为由以下键/值 对组成的 有序 映射：

      "bucket"

      在给定 contribution["bucket"] 和 16 时，为载荷编码整数的结果。

      "value"

      在给定 contribution["value"] 和 4 时，为载荷编码整数的结果。

      "id"

      在给定 contribution["filteringId"] 和 filteringIdMaxBytes 时，为载荷编码整数的结果。

   4. 将 contributionData 追加到 payloadData。

7. 令 payload 为由以下键/值对组成的 有序映射：

   "data"

   payloadData

   "operation"

   "histogram"

8. 返回对 payload 进行 CBOR 编码所得的 字节序列。

要在给定一个 字节序列 plaintextPayload、 公钥 pkR 和一个 字符串 sharedInfo 时，加密 载荷，执行以下步骤。 它们返回一个 字节序列或一个错误。

1. 令 info 为对 « "aggregation_service", sharedInfo » 的 拼接进行 UTF-8 编码的结果。

2. 令 (kem_id, kdf_id, aead_id) 为 (0x0020, 0x0001, 0x0003)。

   注： 上述密码套件三元组 由 HPKE 算法 标识符组成，指定 KEM 为 DHKEM(X25519, HKDF-SHA256)，KDF 函数为 HKDF-SHA256，AEAD 函数为 ChaCha20Poly1305。

3. 令 (enc, hpkeContext) 为通过使用公钥 pkR、 应用提供的信息 info、KEM kem_id、KDF kdf_id 和 AEAD aead_id 调用 SetupBaseS() 来设置 HPKE 发送方 上下文所得的结果。如果此操作 失败，则返回错误。

   注： 为清楚起见，我们在上文中显式传入了 KEM、KDF 和 AEAD 标识符 给 SetupBaseS()，即使 RFC9180 在其 伪代码中省略了这些参数。

4. 令 aad 为 ``（一个空的 字节 序列）。

5. 令 ciphertext 为在 hpkeContext 对象上使用 附加认证数据 aad 和明文 plaintextPayload 调用 ContextS.Seal() 来封装 载荷的结果。如果此操作失败，则返回 错误。

6. 令 encryptedPayload 为 字节 序列 « enc, ciphertext » 的拼接。

   注： 由我们选择的 KEM 生成的封装 对称密钥 enc 的长度正好是 32 字节，如 RFC9180 的 KEM ID表中所示。

7. 返回 字节序列 encryptedPayload。

要在给定一个整数 intToEncode 和一个整数 byteLength 时，为载荷编码整数，返回 intToEncode 的表示形式，即一个长度为 byteLength 的 大端 字节序列，并在必要时用零进行左填充。

要在给定一个 可聚合报告 report 时，获取 报告的 shared info，执行以下 步骤。它们返回一个 字符串。

1. 令 scheduledReportTime 为从 UNIX 纪元到 report 的 original report time 的 持续时间。

2. 令 sharedInfo 为一个由以下键/值对组成的 有序映射：

   "api"

   report 的 api

   "report_id"

   report 的 report ID

   "reporting_origin"

   report 的 reporting origin 的 序列化

   "scheduled_report_time"

   scheduledReportTime 中的秒数，向下舍入到 最接近的整秒数并序列化

   "version"

   "1.0"

3. 返回在给定 sharedInfo 时，将 infra 值序列化为 json 字符串的结果。

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

1. 如果 parameters 不是 JSON 格式的 Object， 则返回一个 WebDriver 错误，其 错误 代码为 invalid argument。

2. 令 enabled 为从 parameters 获取名为 "enabled" 的属性所得的 获取属性结果。

3. 如果 enabled 为 undefined 或者不是布尔值，则返回一个 WebDriver 错误，其 错误 代码为 invalid argument。

4. 将 自动化本地测试模式 已启用设为 enabled。

5. 返回带有数据 null 的 success。

注： 如果没有此功能，可聚合报告会 受到延迟影响，从而使 测试变得困难。