From 4ea1b0f115c7d7a411d8b02bad4d2995f99640a5 Mon Sep 17 00:00:00 2001 From: Yuri Shkuro Date: Thu, 21 Dec 2023 11:49:46 -0500 Subject: [PATCH 1/9] Specify allowed characters for Baggage keys and values Signed-off-by: Yuri Shkuro --- CHANGELOG.md | 4 +++- specification/baggage/api.md | 10 ++++++++++ 2 files changed, 13 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index a6490bbbe1f..54c8e485deb 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,7 +7,9 @@ release. ## Unreleased -### Context +### Context & Baggage + +- Specify allowed characters for Baggage keys and values. ### Traces diff --git a/specification/baggage/api.md b/specification/baggage/api.md index fb6cb392ede..4c7aefc86ca 100644 --- a/specification/baggage/api.md +++ b/specification/baggage/api.md @@ -29,6 +29,16 @@ metrics, traces, and logs. It is a set of name/value pairs describing user-defined properties. Each name in `Baggage` MUST be associated with exactly one value. +Baggage **names** are strings that satisfy the `token` definition from +[RFC7230, Section 3.2.6](https://tools.ietf.org/html/rfc7230#section-3.2.6). +Alpha-numeric names are strongly recommended. Language API MAY return +an error when given a baggage name that is not a `token`. + +Baggage **values** are any valid UTF-8 strings. Language API MUST accept +any valid UTF-8 string as baggage value. Language API MUST guarantee that +`Get` and `Set` operations are symmetrical with respect to name and value, +i.e. `Get` MUST return the same **value** string as received in `Set`. + The Baggage API consists of: - the `Baggage` From 53233df84183cec887f08bf889a1dbfc2aed60d3 Mon Sep 17 00:00:00 2001 From: Yuri Shkuro Date: Thu, 21 Dec 2023 13:15:37 -0500 Subject: [PATCH 2/9] Update CHANGELOG.md Co-authored-by: Reiley Yang --- CHANGELOG.md | 1 + 1 file changed, 1 insertion(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 54c8e485deb..fe732f855a8 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -10,6 +10,7 @@ release. ### Context & Baggage - Specify allowed characters for Baggage keys and values. + ([#3801](https://github.com/open-telemetry/opentelemetry-specification/pull/3801)) ### Traces From 271f23f91659aa481b5cc31ebc36c91784699ee3 Mon Sep 17 00:00:00 2001 From: Yuri Shkuro Date: Thu, 21 Dec 2023 22:34:16 -0500 Subject: [PATCH 3/9] case sensitive Signed-off-by: Yuri Shkuro --- specification/baggage/api.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/specification/baggage/api.md b/specification/baggage/api.md index 4c7aefc86ca..140a3188e24 100644 --- a/specification/baggage/api.md +++ b/specification/baggage/api.md @@ -39,6 +39,9 @@ any valid UTF-8 string as baggage value. Language API MUST guarantee that `Get` and `Set` operations are symmetrical with respect to name and value, i.e. `Get` MUST return the same **value** string as received in `Set`. +Language API MUST treat both baggage names and values as case sensitive. +See also [W3C Baggage -- Case sensitivity of keys](https://github.com/w3c/baggage/blob/main/baggage/HTTP_HEADER_FORMAT_RATIONALE.md#case-sensitivity-of-keys). + The Baggage API consists of: - the `Baggage` From 4bbcf899aa892f01f937fddd8a085ebe9531e1f2 Mon Sep 17 00:00:00 2001 From: Yuri Shkuro Date: Sat, 6 Jan 2024 00:54:37 -0500 Subject: [PATCH 4/9] s/MAY/SHOULD MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Robert Pająk --- specification/baggage/api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/baggage/api.md b/specification/baggage/api.md index 140a3188e24..dced44eb942 100644 --- a/specification/baggage/api.md +++ b/specification/baggage/api.md @@ -31,7 +31,7 @@ exactly one value. Baggage **names** are strings that satisfy the `token` definition from [RFC7230, Section 3.2.6](https://tools.ietf.org/html/rfc7230#section-3.2.6). -Alpha-numeric names are strongly recommended. Language API MAY return +Alpha-numeric names are strongly recommended. Language API SHOULD return an error when given a baggage name that is not a `token`. Baggage **values** are any valid UTF-8 strings. Language API MUST accept From dd465916fd62845c6b65a85b0eced960d405277e Mon Sep 17 00:00:00 2001 From: Yuri Shkuro Date: Wed, 10 Jan 2024 20:15:23 -0500 Subject: [PATCH 5/9] reword and show example Signed-off-by: Yuri Shkuro --- specification/baggage/api.md | 13 ++++++++++--- 1 file changed, 10 insertions(+), 3 deletions(-) diff --git a/specification/baggage/api.md b/specification/baggage/api.md index 2d0912500f8..d51b59a9d00 100644 --- a/specification/baggage/api.md +++ b/specification/baggage/api.md @@ -41,13 +41,20 @@ Alpha-numeric names are strongly recommended. Language API SHOULD return an error when given a baggage name that is not a `token`. Baggage **values** are any valid UTF-8 strings. Language API MUST accept -any valid UTF-8 string as baggage value. Language API MUST guarantee that -`Get` and `Set` operations are symmetrical with respect to name and value, -i.e. `Get` MUST return the same **value** string as received in `Set`. +any valid UTF-8 string as baggage **value** in `Set` and return the same +value from `Get`. Language API MUST treat both baggage names and values as case sensitive. See also [W3C Baggage -- Case sensitivity of keys](https://github.com/w3c/baggage/blob/main/baggage/HTTP_HEADER_FORMAT_RATIONALE.md#case-sensitivity-of-keys). +Example: +``` +baggage.Set('a', 'B% 💼'); +baggage.Set('A', 'c'); +baggage.Get('a'); // returns "B% 💼" +baggage.Get('A'); // returns "c" +``` + The Baggage API consists of: - the `Baggage` as a logical container From 7b92b235af4427c4c9f03e77852af84021103a41 Mon Sep 17 00:00:00 2001 From: Yuri Shkuro Date: Wed, 10 Jan 2024 20:30:43 -0500 Subject: [PATCH 6/9] delint Signed-off-by: Yuri Shkuro --- specification/baggage/api.md | 1 + 1 file changed, 1 insertion(+) diff --git a/specification/baggage/api.md b/specification/baggage/api.md index d51b59a9d00..3943b17f10d 100644 --- a/specification/baggage/api.md +++ b/specification/baggage/api.md @@ -48,6 +48,7 @@ Language API MUST treat both baggage names and values as case sensitive. See also [W3C Baggage -- Case sensitivity of keys](https://github.com/w3c/baggage/blob/main/baggage/HTTP_HEADER_FORMAT_RATIONALE.md#case-sensitivity-of-keys). Example: + ``` baggage.Set('a', 'B% 💼'); baggage.Set('A', 'c'); From 5d324e4c3739d230f193019d2b85ff75ba558a75 Mon Sep 17 00:00:00 2001 From: Yuri Shkuro Date: Wed, 7 Feb 2024 01:16:47 -0500 Subject: [PATCH 7/9] update Signed-off-by: Yuri Shkuro --- specification/baggage/api.md | 13 +++++++++---- 1 file changed, 9 insertions(+), 4 deletions(-) diff --git a/specification/baggage/api.md b/specification/baggage/api.md index 3943b17f10d..06f03fe48eb 100644 --- a/specification/baggage/api.md +++ b/specification/baggage/api.md @@ -35,10 +35,15 @@ with _exactly one value_. This is more restrictive than the [W3C Baggage Specification, § 3.2.1.1](https://www.w3.org/TR/baggage/#baggage-string) which allows duplicate entries for a given name. -Baggage **names** are strings that satisfy the `token` definition from -[RFC7230, Section 3.2.6](https://tools.ietf.org/html/rfc7230#section-3.2.6). -Alpha-numeric names are strongly recommended. Language API SHOULD return -an error when given a baggage name that is not a `token`. +Baggage **names** are any valid UTF-8 strings. Language API SHOULD NOT +restrict which strings are used as baggage **names**. However, the +specific `Propagator`s that are used to transmit baggage entries across +component boundaries may impost their own restrictions on baggage names. +For example, the [W3C Baggage specification](https://github.com/w3c/baggage/blob/main/baggage/HTTP_HEADER_FORMAT.md#key) +restricts the baggage keys to strings that satisfy the `token` definition +from [RFC7230, Section 3.2.6](https://tools.ietf.org/html/rfc7230#section-3.2.6). +For maximum compatibility, alpha-numeric names are strongly recommended +to be used as baggage names. Baggage **values** are any valid UTF-8 strings. Language API MUST accept any valid UTF-8 string as baggage **value** in `Set` and return the same From 5fd188212eef5d219108dc19b74108366e66fd74 Mon Sep 17 00:00:00 2001 From: Yuri Shkuro Date: Wed, 7 Feb 2024 01:21:23 -0500 Subject: [PATCH 8/9] typo --- specification/baggage/api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/baggage/api.md b/specification/baggage/api.md index 06f03fe48eb..199158be93c 100644 --- a/specification/baggage/api.md +++ b/specification/baggage/api.md @@ -38,7 +38,7 @@ which allows duplicate entries for a given name. Baggage **names** are any valid UTF-8 strings. Language API SHOULD NOT restrict which strings are used as baggage **names**. However, the specific `Propagator`s that are used to transmit baggage entries across -component boundaries may impost their own restrictions on baggage names. +component boundaries may impose their own restrictions on baggage names. For example, the [W3C Baggage specification](https://github.com/w3c/baggage/blob/main/baggage/HTTP_HEADER_FORMAT.md#key) restricts the baggage keys to strings that satisfy the `token` definition from [RFC7230, Section 3.2.6](https://tools.ietf.org/html/rfc7230#section-3.2.6). From 9fadece1824e5d880f263b4067091ab6c3af8709 Mon Sep 17 00:00:00 2001 From: Yuri Shkuro Date: Wed, 7 Feb 2024 20:47:10 -0500 Subject: [PATCH 9/9] Apply suggestions from code review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Robert Pająk --- specification/baggage/api.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/specification/baggage/api.md b/specification/baggage/api.md index 199158be93c..928ba2609c8 100644 --- a/specification/baggage/api.md +++ b/specification/baggage/api.md @@ -39,7 +39,7 @@ Baggage **names** are any valid UTF-8 strings. Language API SHOULD NOT restrict which strings are used as baggage **names**. However, the specific `Propagator`s that are used to transmit baggage entries across component boundaries may impose their own restrictions on baggage names. -For example, the [W3C Baggage specification](https://github.com/w3c/baggage/blob/main/baggage/HTTP_HEADER_FORMAT.md#key) +For example, the [W3C Baggage specification](https://www.w3.org/TR/baggage/#key) restricts the baggage keys to strings that satisfy the `token` definition from [RFC7230, Section 3.2.6](https://tools.ietf.org/html/rfc7230#section-3.2.6). For maximum compatibility, alpha-numeric names are strongly recommended @@ -50,7 +50,7 @@ any valid UTF-8 string as baggage **value** in `Set` and return the same value from `Get`. Language API MUST treat both baggage names and values as case sensitive. -See also [W3C Baggage -- Case sensitivity of keys](https://github.com/w3c/baggage/blob/main/baggage/HTTP_HEADER_FORMAT_RATIONALE.md#case-sensitivity-of-keys). +See also [W3C Baggage Rationale](https://github.com/w3c/baggage/blob/main/baggage/HTTP_HEADER_FORMAT_RATIONALE.md#case-sensitivity-of-keys). Example: