This specification defines a standard for representing and propagating a set of user-defined properties associated with a distributed request.
Status of This Document
This section describes the status of this
document at the time of its publication. A list of current W3C
publications and the latest revision of this technical report can be found
in the W3C technical reports index at
https://www.w3.org/TR/.
This is the First Public Working Draft
(FPWD). There are a
few implementations of this protocol available. Experimental interoperability
scenarios were run and have demonstrated promising results. The specification will be
progressed into Candidate Recommendation stage after that, drafts for binary, AMQP and
MQTT protocols will be written to make sure the concepts and structure defined
in this specification can be ported to other protocols.
Publication as a Working Draft does not
imply endorsement by W3C and its Members.
This is a draft document and may be updated, replaced or obsoleted by other
documents at any time. It is inappropriate to cite this document as other
than work in progress.
As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.
The key words MAY, MUST, MUST NOT, and SHOULD in this document
are to be interpreted as described in
BCP 14
[RFC2119] [RFC8174]
when, and only when, they appear in all capitals, as shown here.
2. Overview
The baggage header represents a set of user-defined properties associated with a distributed request. Libraries and platforms SHOULD propagate this header.
3. Baggage HTTP Header Format
The baggage header is used to propagate user-supplied key-value pairs through a distributed request.
A received header MAY be altered to change or add information and it SHOULD be passed on to all downstream requests.
Multiple baggage headers are allowed. Values can be combined in a single header according to RFC 7230.
3.1 Header Name
Header name: baggage
In order to increase interoperability across multiple protocols and encourage successful integration,
implementations SHOULD keep the header name lowercase.
3.2 Header Content
This section uses the Augmented Backus-Naur Form (ABNF) notation of [RFC5234].
3.2.1 Definition
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.6value = *baggage-octet
baggage-octet = %x21 / %x23-2B / %x2D-3A / %x3C-5B / %x5D-7E; US-ASCII characters excluding CTLs,; whitespace, DQUOTE, comma, semicolon,; and backslashOWS = *( SP / HTAB ) ; optional white space, as defined in RFC 7230, Section 3.2.3
List of list-members with optional properties attached.
Uniqueness of keys between multiple list-members in a baggage-string is not guaranteed.
The order of duplicate entries SHOULD be preserved when mutating the list.
Producers SHOULD try to produce a baggage-string without any list-members which duplicate the key of another list member.
3.2.1.2 key
A token which identifies a value in the baggage. token is defined in RFC7230, Section 3.2.6.
Leading and trailing whitespaces (OWS) are allowed but MUST be trimmed when converting the header into a data structure.
3.2.1.3 value
A value contains a URL encoded UTF-8 string.
Leading and trailing whitespaces (OWS) are allowed but MUST be trimmed when converting the header into a data structure.
Note, valueMAY contain any number of the equal sign (=) characters. Parsers
MUST NOT assume that the equal sign is only used to separate key and value.
3.2.1.4 property
Additional metadata MAY be appended to values in the form of property set, represented as semi-colon ; delimited list of keys and/or key-value pairs, e.g. ;k1=v1;k2;k3=v3. The semantic of such properties is opaque to this specification.
Leading and trailing OWS is allowed but MUST be trimmed when converting the header into a data structure.
3.2.2 Limits
Maximum number of list-members: 180.
Maximum number of bytes per list-member: 4096.
Maximum number of bytes per baggage-string: 8192.
3.2.3 Example
The following example header contains 3 list-members.
The baggage-string contained in the header contains 86 bytes.
82 bytes come from the list-members and 4 bytes come from commas and optional whitespace.
For example, if all of your data needs to be sent to a single node, you could propagate a property indicating that.
baggage: serverNode=DF%2028
For example, if you need to annotate logs with some request-specific information, you could propagate a property using the baggage header.
baggage: userId=alice
For example, if you have non-production requests that flow through the same services as production requests.
baggage: isProduction=false
3.4 Mutating baggage
A system receiving a baggage request header SHOULD send it to outgoing requests.
A system MAY mutate the value of this header before passing it on.
Because baggage entry keys, values, and metadata are not specified here, producers and consumers MAY agree on any set of mutation rules that don't violate the specification. For example, keys may be deduplicated by keeping the first entry, keeping the last entry, or concatenating values together.
The following mutations are allowed:
Add a new key/value pair. A key/value pair MAY be added.
Update an existing value. The value for any given key MAY be updated.
Delete a key/value pair. Any key/value pair MAY be deleted.
Deduplicating the list. Duplicate keys MAY be removed.
If a system receiving or updating a baggage request header determines that the number of baggage entries exceeds the limit defined in the limits section above, it MAY drop or truncate certain baggage entries in any order chosen by the implementation.
If a system determines that the value of a baggage entry is not in the format defined in this specification, it MAY remove that entry before propagating the baggage header as part of outgoing requests.
4. Security Considerations
Systems relying on the baggage headers should also follow all best practices for parsing potentially malicious data, including checking for header length and content of header values.
These practices help to avoid buffer overflow, HTML injection, and other types of attacks.
4.1 Information Exposure
As mentioned in the privacy section, baggage may carry sensitive information.
Application owners should either ensure that no proprietary or confidential information is stored in baggage, or they should ensure that baggage isn't present in requests that cross trust-boundaries.
4.2 Other Risks
Application owners need to make sure to test all code paths leading to the sending of the baggage header. For example, in single page browser applications, it is typical to make cross-origin requests. If one of these code paths leads to baggage headers being sent by cross-origin calls that are restricted using Access-Control-Allow-Headers [FETCH], it may fail.
5. Privacy Considerations
Requirements to propagate headers to downstream services, as well as storing values of these headers, open up potential privacy concerns.
Using proprietary ways of context propagation, vendors and application developers could always encode information that contains user identifiable data.
This standard makes it possible for systems to operate on a known, standardized header to restrict propagation of sensitive data in the baggage when crossing trust boundaries.
Systems MUST assess the risk of header abuse. This section provides some considerations and initial assessment of the risk associated with storing and propagating this header. Systems may choose to inspect and remove sensitive information from the fields before processing or propagating the received data. All mutations should, however, conform to the list of mutations defined in this specification.
5.1 Privacy of the baggage header
The main purpose of this header is to provide additional system-specific information to other systems within the same trust-boundary.
The baggage header may contain any opaque value in any of the keys.
As such, the baggage header can contain user-identifiable data.
Systems MUST ensure that the baggage header does not leak beyond defined trust boundaries and they MUST ensure that the channel that is used to transport potentially user-identifiable data is secured.
6. Glossary
This section is non-normative.
Opaque value
An opaque value refers to a payload that may only be understood
or processed in any way by the designated producers and consumers
that share a common semantic understanding of this value.
Any other system or application must treat it as a blob of bytes.