分布式上下文的传播格式：Baggage

W3C 候选推荐快照

关于本文档的更多详细信息
本版本：
https://www.w3.org/TR/2024/CR-baggage-20240530/
最新发布版本：
https://www.w3.org/TR/baggage/
最新编辑草案：
https://w3c.github.io/baggage/
历史：
https://www.w3.org/standards/history/baggage/
提交历史
实现报告：
https://w3c.github.io/baggage/reports/cr-2024-implementations
编辑：
Sergey Kanzhelev（Google）
Yuri Shkuro（Meta）
Daniel Dyla（Dynatrace）
J. Kalyana Sundaram（Microsoft）
曾任编辑：
Alois Reitbauer
Morgan McLean
Daniel Khan
反馈：
GitHub w3c/baggage （拉取请求， 新议题， 未解决议题）
public-trace-context@w3.org，请使用 主题行 baggage（存档）
讨论
我们在 Slack 上。

Copyright © 2024 World Wide Web Consortium. W3C® liability, trademark and permissive document license rules apply.

摘要

本规范定义了一项标准，用于表示和传播与分布式请求或工作流执行相关联的一组由应用定义的 属性。

这独立于 Trace Context 规范。 无论是否使用分布式跟踪，都可以使用 Baggage。本规范标准化了 由应用定义属性的表示和传播。相比之下，Trace Context 规范 标准化了为支持分布式跟踪场景所需元数据的表示和传播。

Baggage 规范的当前版本面向应用和 服务的实现，包括在浏览器中运行的 Web 应用。Web 浏览器或用户代理目前 不在目标实现范围内。

本文档的状态

本节描述的是本文档在发布时的状态。当前 W3C 发布物列表以及本技术报告的最新修订版可在 https://www.w3.org/TR/ 上的 W3C 技术 报告索引中找到。

在候选推荐阶段，工作组将审核：

本文档由分布式 跟踪工作组作为候选推荐快照，使用 推荐标准轨道发布。

作为候选推荐发布并不 意味着得到 W3C 及其成员的认可。候选 推荐快照已经过 广泛审查，旨在 收集 实现经验， 并且已获得工作组成员对实现进行 免版税许可 的承诺。

本候选推荐预计不会早于 2024 年 8 月 30 日推进到拟推荐 阶段。

本文档由一个按照 W3C 专利 政策运作的小组制定。 W3C 维护一份 与该小组交付物相关的任何专利 披露的公开列表， 该页面还包括披露专利的说明。实际 知悉某项专利、且该个人认为该专利包含 必要权利要求的个人， 必须按照 W3C 专利政策第 6 节 披露相关信息。

本文档受 2023 年 11 月 03 日 W3C 流程文档约束。

1. 一致性

除标记为非规范性的各节外，本规范中的所有创作指南、图表、示例和注释均为非规范性内容。 本规范中的其他所有内容均为规范性内容。

本文档中的关键词 MAY、MUST、MUST NOT 和 SHOULD 应按 BCP 14 [RFC2119] [RFC8174] 中所述解释，且仅当它们像这里所示那样以全大写形式出现时才如此解释。

2. 概述

baggage 标头表示与分布式 请求相关联的一组用户定义属性。库和平台 SHOULD 传播该标头。

3. Baggage HTTP 标头格式

baggage 标头用于通过分布式 请求传播用户提供的键-值对。 接收到的标头 MAY 被更改以修改或添加信息，并且它 SHOULD 被传递给所有下游请求。

允许多个 baggage 标头。值可以按照 RFC 7230 合并到单个标头中。

3.1 标头名称

标头名称：baggage

为了提高跨多种协议的互操作性并鼓励成功集成， 实现 SHOULD 保持标头名称为小写。

3.2 标头编码

该标头是一个 [UTF-8] 编码的 [UNICODE] 字符串，不过它只使用 基本拉丁 Unicode 块中的代码点，这些代码点在 Unicode 和 [ASCII] 中的编码完全相同。

3.3 标头内容

本节使用 [RFC5234] 的扩展巴科斯-诺尔范式（ABNF）记法。

3.3.1 定义

baggage-string         =  list-member 0*179( OWS "," OWS list-member )
list-member            =  key OWS "=" OWS value *( OWS ";" OWS property )
property               =  key OWS "=" OWS value
property               =/ key OWS
key                    =  token ; as defined in RFC 7230, Section 3.2.6
value                  =  *baggage-octet
baggage-octet          =  %x21 / %x23-2B / %x2D-3A / %x3C-5B / %x5D-7E
                          ; US-ASCII characters excluding CTLs,
                          ; whitespace, DQUOTE, comma, semicolon,
                          ; and backslash
OWS                    =  *( SP / HTAB ) ; optional white space, as defined in RFC 7230, Section 3.2.3

token 定义于 [RFC7230] 第 3.2.6 节：https://tools.ietf.org/html/rfc7230#section-3.2.6

OWS 的定义取自 [RFC7230] 第 3.2.3 节：https://tools.ietf.org/html/rfc7230#section-3.2.3

3.3.1.1 baggage-string

附带可选属性的 list-member 列表。 一个 baggage-string 中多个 list-member 之间键的唯一性 不作保证。 改变该列表时，重复条目的顺序 SHOULD 被保留。 生产者 SHOULD 尝试生成一个不含任何 与另一列表成员的 key 重复的 list-member 的 baggage-string。

3.3.1.2 key

一个用于标识 baggage 中 value 的 token。 token 定义于 RFC7230 第 3.2.6 节。 允许前导和尾随空白（OWS），并且它们不被认为是 键的一部分。

注
3.3.1.3 value

一个包含由 key 标识的值的字符串。 baggage-octet 范围之外的任何代码点 MUST 进行百分号编码。 百分号代码点（U+0025）MUST 进行百分号编码。 不要求进行百分号编码的代码点 MAY 进行百分号编码。 百分号编码定义于 [RFC3986] 第 2.1 节：https://datatracker.ietf.org/doc/html/rfc3986#section-2.1。

解码值时，与 UTF-8 编码 方案不匹配的百分号编码八位字节序列 MUST 被替换为替换代码点 （U+FFFD）。

允许前导和尾随空白（OWS），并且它们不被认为是 值的一部分。

注意，value MAY 包含任意数量的等号 （U+003D）代码点。解析器 MUST NOT 假定等号只用于分隔 key 和 value。

注
3.3.1.4 property

附加元数据 MAY 以属性集的形式追加到值上， 表示为由分号 ; 分隔的键和/或键-值对列表， 例如 ;k1=v1;k2;k3=v3。 本规范没有赋予属性键和值任何特定含义。 允许前导和尾随 OWS，并且它们不被认为是 属性键或值的一部分。

3.3.2 限制

只要同时满足以下两个条件，平台 MUST 传播所有 list-member，包括由该平台添加的任何 list-member：

  • 条件 1：生成的 baggage-string 包含 64 个 list-member 或更少。
  • 条件 2：生成的 baggage-string 大小为 8192 字节或 更少。

如果上述任一条件不满足，平台 MAY 丢弃 list-member，直到两个条件都满足。 要丢弃哪些 list-member 以及它们的顺序未作规定，留给 实现者决定。 注意，上述限制是符合本规范的最低要求。 实现者或平台 MAY 定义更高的限制，并且 SHOULD 在其要求范围内传播尽可能多的 baggage 信息。 如果平台不能传播所有 baggage，它 MUST NOT 传播任何 部分的 list-member。 如果存在多个 baggage 标头，则所有限制适用于所有 baggage 标头的组合，而不是分别适用于每个标头。

3.3.3 示例

以下示例标头包含 3 个 list-member。 标头中包含的 baggage-string 为 86 字节。 82 字节来自 list-member，4 字节来自逗号和可选 空白。

baggage: key1=value1;property1;property2, key2 = value2, key3=value3; propertyKey=propertyValue
  • key1=value1;property1;property2
    • 31 字节
  • key2 = value2
    • 13 字节
  • key3=value3; propertyKey=propertyValue
    • 38 字节

3.4 HTTP 标头示例

假设我们想要传播这些条目：userId="alice"、serverNode="DF 28"、 isProduction=false，

单个标头：

baggage: userId=alice,serverNode=DF%2028,isProduction=false

下面还有一个示例，其中包含 baggage-octet 范围之外字符的值 会进行百分号编码。考虑条目：userId="Amélie"、serverNode="DF 28"、 isProduction=false： 

baggage: userId=Am%C3%A9lie,serverNode=DF%2028,isProduction=false

上下文可能被拆分到多个标头中：

baggage: userId=alice
baggage: serverNode=DF%2028,isProduction=false

值和名称可能以前后空格开始和结束：

baggage: userId =   alice
baggage: serverNode = DF%2028, isProduction = false

3.4.1 示例用例

例如，如果你的所有数据都需要发送到单个节点，你可以传播一个表示 该情况的属性。

baggage: serverNode=DF%2028

例如，如果你需要用某些请求特定信息来注解日志，你可以使用 baggage 标头传播 一个属性。

baggage: userId=alice

例如，如果你有非生产请求流经与生产 请求相同的服务。

baggage: isProduction=false

3.5 改变 baggage

接收到 baggage 请求标头的系统 SHOULD 将其发送到 出站请求。 系统 MAY 在传递该标头之前改变其值。

由于此处未指定 baggage 条目的键、值和元数据，生产者和消费者 MAY 约定任何不违反本规范的改变规则。 例如，可以通过保留第一个条目、保留最后一个条目或将值连接在一起来对键去重。

允许以下改变：

如果接收或更新 baggage 请求标头的系统确定 baggage 条目的数量超过了上文限制一节中定义的限制，它 MAY 按实现选择的任意顺序丢弃或截断某些 baggage 条目。

如果系统确定某个 baggage 条目的值不符合本 规范中定义的格式，它 MAY 在将 baggage 标头作为出站请求的一部分传播之前 移除该条目。

4. 安全考虑事项

依赖 baggage 标头的系统也应遵循所有 解析潜在恶意数据的最佳实践，包括检查标头长度和标头值的内容。 这些实践有助于避免缓冲区溢出、HTML 注入和其他类型的攻击。

4.1 信息暴露

如隐私一节所述，baggage 可能携带敏感信息。 应用所有者应确保没有专有或机密信息存储在 baggage 中，或者应确保跨越信任边界的请求中不存在 baggage。

4.2 其他风险

应用所有者需要确保测试所有会导致发送 baggage 标头的代码路径。例如，在用 JavaScript 编写的 Web 应用中， 发出跨源请求很常见。如果这些代码路径之一导致 baggage 标头 通过受 Access-Control-Allow-Headers [FETCH] 限制的跨源调用发送，则可能会失败。

5. 隐私考虑事项

将标头传播到下游服务以及存储这些标头的值的要求，会带来 潜在的隐私顾虑。 使用专有的上下文传播方式时，供应商和应用开发者始终可以编码 包含用户可识别数据的信息。 本标准使系统能够在已知、标准化的标头上进行操作，以便在跨越信任边界时限制 baggage 中敏感数据的传播。

系统 MUST 评估标头滥用的风险。本节提供一些 考虑事项以及对存储和传播该标头相关风险的初步评估。 系统可以选择在处理或传播接收到的数据之前 检查并移除字段中的敏感信息。不过，所有改变都应符合本 规范中定义的改变列表。

5.1 baggage 标头的隐私

该标头的主要目的是向同一信任边界内的其他系统提供附加的系统特定信息。 baggage 标头可以在任意键中包含任意值。 因此，baggage 标头可以包含用户可识别数据，不过本规范没有赋予任何键、 其值或属性语义含义。 使用 baggage 的应用应意识到键和值可能被传播到其他系统。 因此，它们应移除不希望传播到其他 系统的任何私有信息。

A. 致谢

感谢 Armin Ruech、Jonathan Mace、Philippe Le Hegaret、Bastian Krol 和 Reiley Yang 对这项工作的 贡献。

B. 参考文献

B.1 规范性参考文献

[ASCII]
ISO/IEC 646:1991，信息技术 -- 信息交换用 ISO 7 位编码字符集。Ecma International. URL: https://www.ecma-international.org/publications-and-standards/standards/ecma-6/
[FETCH]
Fetch 标准。Anne van Kesteren. WHATWG. Living Standard. URL: https://fetch.spec.whatwg.org/
[RFC2119]
用于 RFC 中表示 要求级别的关键词。S. Bradner. IETF. March 1997. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc2119
[RFC3986]
统一资源标识符（URI）：通用 语法。T. Berners-Lee; R. Fielding; L. Masinter. IETF. January 2005. Internet Standard. URL: https://www.rfc-editor.org/rfc/rfc3986
[RFC5234]
语法规范的扩展 BNF： ABNF。D. Crocker, Ed.; P. Overell. IETF. January 2008. Internet Standard. URL: https://www.rfc-editor.org/rfc/rfc5234
[RFC7230]
超文本传输协议（HTTP/1.1）： 消息语法和路由。R. Fielding, Ed.; J. Reschke, Ed.. IETF. June 2014. Proposed Standard. URL: https://httpwg.org/specs/rfc7230.html
[RFC8174]
RFC 2119 关键词中大写与小写的歧义。B. Leiba. IETF. May 2017. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc8174
[UNICODE]
Unicode 标准。Unicode Consortium. URL: https://www.unicode.org/versions/latest/
[UTF-8]
UTF-8，ISO 10646 的一种转换格式。F. Yergeau. IETF. November 2003. Internet Standard. URL: https://www.rfc-editor.org/rfc/rfc3629

B.2 资料性参考文献

[infra]
Infra 标准。Anne van Kesteren; Domenic Denicola. WHATWG. Living Standard. URL: https://infra.spec.whatwg.org/