分散コンテキストの伝播形式: 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 と [ASCII] の両方で同一にエンコードされる、 Basic Latin Unicode Block の符号位置のみを使用する。

3.3 ヘッダー内容

この節では、[RFC5234] の Augmented Backus-Naur Form (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] Section 3.2.6 で定義される: https://tools.ietf.org/html/rfc7230#section-3.2.6

OWS の定義は、[RFC7230] Section 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 間での key の一意性は 保証されない。 リストを変更する場合、重複エントリーの順序は保持されるべきである (SHOULD)。 生成者は、別の list member の key と重複する list-member を含まない baggage-string を生成するよう 試みるべきである (SHOULD)。

3.3.1.2 key

baggage 内の value を識別する token。 token は RFC7230, Section 3.2.6 で定義される。 先頭および末尾の空白 (OWS) は許可され、key の一部とは みなされない。

注記
3.3.1.3 value

key によって識別される値を含む文字列。 baggage-octet 範囲外の任意の符号位置は、パーセントエンコードされなければならない (MUST)。 パーセント符号位置 (U+0025) はパーセントエンコードされなければならない (MUST)。 パーセントエンコードを必要としない符号位置は、 パーセントエンコードされてもよい (MAY)。 パーセントエンコードは [RFC3986] Section 2.1 で定義される: https://datatracker.ietf.org/doc/html/rfc3986#section-2.1.

value をデコードする際、UTF-8 エンコーディングスキームと一致しないパーセントエンコードされたオクテット列は、 置換符号位置 (U+FFFD) に置換されなければならない (MUST)。

先頭および末尾の空白 (OWS) は許可され、value の一部とは みなされない。

注記: value は、等号 (U+003D) 符号位置を任意の数だけ含んでもよい (MAY)。パーサーは、 等号が key と value を分離するためだけに使用されると 仮定してはならない (MUST NOT)。

注記
3.3.1.4 property

追加のメタデータは property set の形式で value に付加してもよく (MAY)、セミコロン ; で区切られた key および/または key-value ペアのリストとして表される。 例: ;k1=v1;k2;k3=v3。 property の key および value には、この仕様によって特定の意味は与えられない。 先頭および末尾の OWS は許可され、property key または value の一部とは みなされない。

3.3.2 制限

プラットフォームは、次の両方の条件が満たされる場合は常に、プラットフォームによって追加された list-member を含むすべての list-member を伝播しなければならない (MUST):

  • 条件 1: 結果として得られる baggage-string が 64 個以下の list-member を含む。
  • 条件 2: 結果として得られる baggage-string のサイズが 8192 バイト以下である。

上記の条件のいずれかが満たされない場合、プラットフォームは、両方の条件が満たされるまで list-member を削除してもよい (MAY)。 どの list-member を削除するか、およびその順序の選択は指定されず、 実装者に委ねられる。 上記の制限は、仕様に適合するための最小要件であることに注意する。 実装者またはプラットフォームは、より高い制限を定義してもよく (MAY)、 その要件内で合理的な範囲でできるだけ多くの baggage 情報を伝播すべきである (SHOULD)。 プラットフォームがすべての baggage を伝播できない場合、部分的な list-member を伝播してはならない (MUST NOT)。 複数の 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 範囲外の文字を含む値が パーセントエンコードされるもう 1 つの例を示す。次のエントリーを考える: 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 ユースケース例

たとえば、すべてのデータを単一ノードに送信する必要がある場合、それを示す property を 伝播できる。

baggage: serverNode=DF%2028

たとえば、リクエスト固有の情報でログに注釈を付ける必要がある場合、baggage ヘッダーを使用して property を伝播できる。

baggage: userId=alice

たとえば、本番リクエストと同じサービスを通過する非本番リクエストがある場合。

baggage: isProduction=false

3.5 baggage の変更

baggage リクエストヘッダーを受信したシステムは、それを 送信リクエストに送信すべきである (SHOULD)。 システムは、渡す前にこのヘッダーの値を変更してもよい (MAY)。

baggage エントリーの key、value、およびメタデータはここでは指定されないため、生成者および消費者は、 仕様に違反しない任意の変更規則セットについて合意してもよい (MAY)。 たとえば、最初のエントリーを保持する、最後のエントリーを保持する、または 値を連結することにより、key を重複排除してもよい。

次の変更が許可される:

baggage リクエストヘッダーを受信または更新するシステムが、baggage エントリー数が 上記の制限の節で定義された制限を超えると判断した場合、実装によって選ばれる任意の順序で 特定の baggage エントリーを削除または切り詰めてもよい (MAY)。

baggage エントリーの値がこの 仕様で定義される形式ではないとシステムが判断した場合、そのシステムは送信リクエストの一部として baggage ヘッダーを 伝播する前に、そのエントリーを削除してもよい (MAY)。

4. セキュリティに関する考慮事項

baggage ヘッダーに依存するシステムは、ヘッダー長およびヘッダー値の内容の確認を含む、 潜在的に悪意のあるデータを解析するためのすべてのベストプラクティスにも従うべきである。 これらのプラクティスは、バッファオーバーフロー、HTML インジェクション、およびその他の種類の攻撃を避けるのに役立つ。

4.1 情報露出

プライバシーの節で述べたように、baggage は機微情報を運ぶ可能性がある。 アプリケーション所有者は、独自情報または機密情報が baggage に保存されていないことを保証するか、または信頼境界を越えるリクエストに baggage が存在しないことを保証すべきである。

4.2 その他のリスク

アプリケーション所有者は、 baggage ヘッダーの送信に至るすべてのコードパスをテストするようにしなければならない。 たとえば、JavaScript で書かれた Web アプリケーションでは、クロスオリジンリクエストを行うことが一般的である。 これらのコードパスの 1 つが、 Access-Control-Allow-Headers [FETCH] を使用して制限されるクロスオリジン呼び出しによって baggage ヘッダーが送信されることにつながる場合、 失敗する可能性がある。

5. プライバシーに関する考慮事項

下流サービスにヘッダーを伝播する要件、およびこれらのヘッダーの値を保存することは、 潜在的なプライバシー上の懸念を生じさせる。 独自のコンテキスト伝播方法を使用すれば、ベンダーおよびアプリケーション開発者は、ユーザー識別可能データを含む 情報を常にエンコードできる。 この標準は、信頼境界を越える際に baggage 内の機微データの 伝播を制限するために、既知の標準化されたヘッダーに対してシステムが操作できるようにする。

システムは、ヘッダー悪用のリスクを評価しなければならない (MUST)。この節は、 このヘッダーの保存および伝播に関連するリスクについて、いくつかの 考慮事項および初期評価を提供する。 システムは、受信データを処理または伝播する前に、フィールドから機微情報を検査および削除することを 選択できる。ただし、すべての変更は、 この仕様で定義される変更の一覧に適合すべきである。

5.1 baggage ヘッダーのプライバシー

このヘッダーの主な目的は、同じ信頼境界内の他のシステムに 追加のシステム固有情報を提供することである。 baggage ヘッダーは、いずれの key にも任意の値を含む可能性がある。 したがって、baggage ヘッダーはユーザー識別可能データを含むことができる。ただし、この仕様では key、その値、 または property に意味論的意味は与えられない。 baggage を使用するアプリケーションは、key および value が他のシステムへ伝播される可能性があることを認識すべきである。 したがって、他のシステムへ伝播されたくない任意の個人情報を削除すべきである。

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]
Uniform Resource Identifier (URI): Generic Syntax. T. Berners-Lee; R. Fielding; L. Masinter. IETF. January 2005. Internet Standard. URL: https://www.rfc-editor.org/rfc/rfc3986
[RFC5234]
構文仕様のための Augmented BNF: ABNF. D. Crocker, Ed.; P. Overell. IETF. January 2008. Internet Standard. URL: https://www.rfc-editor.org/rfc/rfc5234
[RFC7230]
Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing. 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/