분산 컨텍스트의 전파 형식: 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 명세는 브라우저 안에서 실행되는 웹 애플리케이션을 포함하여 애플리케이션과 서비스에 의한 구현을 대상으로 한다. 웹 브라우저 또는 사용자 에이전트는 현재 대상 구현 범위에 포함되지 않는다.

이 문서의 상태

이 절은 이 문서가 발행된 시점의 상태를 설명한다. 현재 W3C 발행물 목록과 이 기술 보고서의 최신 개정판은 https://www.w3.org/TR/의 W3C 기술 보고서 색인에서 확인할 수 있다.

후보 권고안 단계 동안 워킹 그룹은 다음을 감사할 것이다.

이 문서는 분산 추적 워킹 그룹이 권고안 트랙을 사용하여 후보 권고안 스냅샷으로 발행했다.

후보 권고안으로 발행되었다고 해서 W3C와 그 회원들의 승인을 의미하지는 않는다. 후보 권고안 스냅샷은 광범위한 검토를 받았고, 구현 경험을 수집하기 위한 것이며, 구현에 대해 워킹 그룹 구성원들로부터 로열티 없는 라이선스 약속을 받았다.

이 후보 권고안은 2024년 8월 30일보다 이른 시점에 제안 권고안으로 진행될 것으로 예상되지 않는다.

이 문서는 W3C 특허 정책에 따라 운영되는 그룹에서 작성했다. W3C는 이 그룹의 산출물과 관련하여 이루어진 모든 특허 공개의 공개 목록을 유지하며, 해당 페이지에는 특허 공개 지침도 포함되어 있다. 개인이 그 개인이 필수 청구항을 포함한다고 믿는 특허에 대해 실제로 알고 있는 경우, 그 개인은 W3C 특허 정책 제6절에 따라 해당 정보를 공개해야 한다.

이 문서는 2023년 11월 3일 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]의 확장 배커스-나우어 형식(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 사이에서 키의 고유성은 보장되지 않는다. 목록을 변경할 때 중복 항목의 순서는 보존되어야 SHOULD 한다. 생산자는 다른 목록 멤버의 key를 중복하는 list-member가 없는 baggage-string을 생성하도록 노력해야 SHOULD 한다.

3.3.1.2 key

baggage 안의 value를 식별하는 token이다. token은 RFC7230, Section 3.2.6에 정의되어 있다. 선행 및 후행 공백(OWS)은 허용되며 키의 일부로 간주되지 않는다.

참고
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.

값을 디코딩할 때 UTF-8 인코딩 스킴과 일치하지 않는 퍼센트 인코딩된 옥텟 시퀀스는 대체 코드 포인트 (U+FFFD)로 대체되어야 MUST 한다.

선행 및 후행 공백(OWS)은 허용되며 값의 일부로 간주되지 않는다.

value는 임의 개수의 등호 (U+003D) 코드 포인트를 포함할 수 MAY 있음에 유의하라. 파서는 등호가 key와 value를 구분하는 데에만 사용된다고 가정해서는 안 된다 MUST NOT.

참고
3.3.1.4 property

추가 메타데이터는 property 집합의 형태로 값에 덧붙일 수 MAY 있으며, 이는 세미콜론 ;으로 구분된 키 및/또는 키-값 쌍의 목록으로 표현된다. 예: ;k1=v1;k2;k3=v3. 이 명세는 property 키와 값에 특정 의미를 부여하지 않는다. 선행 및 후행 OWS는 허용되며 property 키 또는 값의 일부로 간주되지 않는다.

3.3.2 제한

플랫폼은 다음 두 조건이 모두 충족될 때마다, 플랫폼이 추가한 list-member를 포함한 모든 list-member를 전파해야 MUST 한다.

  • 조건 1: 결과 baggage-string이 list-member 64개 이하를 포함한다.
  • 조건 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 범위 밖의 문자를 가진 값이 퍼센트 인코딩되는 또 다른 예이다. 다음 항목을 고려하라. 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 항목 수가 위의 제한 절에 정의된 제한을 초과한다고 판단하면, 구현이 선택한 임의의 순서로 특정 baggage 항목을 삭제하거나 잘라낼 수 MAY 있다.

시스템이 baggage 항목의 값이 이 명세에 정의된 형식이 아니라고 판단하면, 나가는 요청의 일부로 baggage 헤더를 전파하기 전에 그 항목을 제거할 수 MAY 있다.

4. 보안 고려 사항

baggage 헤더에 의존하는 시스템은 헤더 길이와 헤더 값의 내용을 확인하는 것을 포함하여, 잠재적으로 악의적인 데이터를 파싱하기 위한 모든 모범 사례도 따라야 한다. 이러한 사례는 버퍼 오버플로, HTML 삽입 및 다른 유형의 공격을 피하는 데 도움이 된다.

4.1 정보 노출

개인정보 보호 절에서 언급했듯이, baggage는 민감한 정보를 전달할 수 있다. 애플리케이션 소유자는 독점 정보나 기밀 정보가 baggage에 저장되지 않도록 보장하거나, 신뢰 경계를 넘는 요청에 baggage가 존재하지 않도록 보장해야 한다.

4.2 기타 위험

애플리케이션 소유자는 baggage 헤더 전송으로 이어지는 모든 코드 경로를 테스트해야 한다. 예를 들어 JavaScript로 작성된 웹 애플리케이션에서는 교차 출처 요청을 하는 것이 일반적이다. 이러한 코드 경로 중 하나가 Access-Control-Allow-Headers [FETCH]를 사용하여 제한되는 교차 출처 호출에 의해 baggage 헤더가 전송되도록 하면, 실패할 수 있다.

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. 현행표준. URL: https://fetch.spec.whatwg.org/
[RFC2119]
요구 수준을 나타내기 위해 RFC에서 사용하는 핵심어. S. Bradner. IETF. 1997년 3월. 최신 모범 사례. URL: https://www.rfc-editor.org/rfc/rfc2119
[RFC3986]
Uniform Resource Identifier (URI): 일반 구문. T. Berners-Lee; R. Fielding; L. Masinter. IETF. 2005년 1월. 인터넷 표준. URL: https://www.rfc-editor.org/rfc/rfc3986
[RFC5234]
구문 명세를 위한 확장 BNF: ABNF. D. Crocker, Ed.; P. Overell. IETF. 2008년 1월. 인터넷 표준. URL: https://www.rfc-editor.org/rfc/rfc5234
[RFC7230]
Hypertext Transfer Protocol (HTTP/1.1): 메시지 구문 및 라우팅. R. Fielding, Ed.; J. Reschke, Ed.. IETF. 2014년 6월. 제안 표준. URL: https://httpwg.org/specs/rfc7230.html
[RFC8174]
RFC 2119 핵심어에서 대문자와 소문자의 모호성. B. Leiba. IETF. 2017년 5월. 최신 모범 사례. 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. 2003년 11월. 인터넷 표준. URL: https://www.rfc-editor.org/rfc/rfc3629

B.2 정보 참고 문헌

[infra]
Infra 표준. Anne van Kesteren; Domenic Denicola. WHATWG. 현행표준. URL: https://infra.spec.whatwg.org/