first version of correlation context header (#21)

* first version of correlation context header

* addredssed PR feedback

* added rationale

* stripped out the types. We can add it later as many people against it now

* reserved semicolon for properties

* added considerations for case sensitivitiveness of tha names

* added rationale for Vary and multiple headers approach

* addressed Yuri's feedback

* make examples more explicit regarding spaces

CORRELATION_CONTEXT_HTTP_HEADER_FORMAT.md

@@ -0,0 +1,56 @@
+# Correlation Context HTTP Header Format
+
+A correlation context header is used to pass the name-value context properties for the trace. This is a companion header for the `Trace-Context`. The values should be passed along to any child requests. Note that uniqueness of the key within the `Correlation-Context` is not guaranteed. Context received from upstream service may be altered before passing it along.
+
+*See [rationale document](CORRELATION_CONTEXT_HTTP_HEADER_FORMAT_RATIONALE.md) for details of decisions made for this format.*
+
+# Format
+
+## Header name
+
+`Correlation-Context`
+
+Multiple correlation context headers are allowed. Values can be combined in a single header according to the [RFC 7230](https://tools.ietf.org/html/rfc7230#page-24).
+
+## Header value
+
+`name1=value1[;properties1],name2=value2[;properties2]`
+
+**Limits:**
+1. Maximum number of name-value pairs: `180`.
+2. Maximum number of bytes per a single name-value pair: `4096`.
+3. Maximum total length of all name-value pairs: `8192`.
+
+## Name format
+
+Url encoded string. Spaces should be trimmed from beginning and the end of the name. Names are case sensitive.
+
+## Value format
+
+All spaces should be trimmed from the beginning and the end of the value. Value ends with the special character `;`, separator `,` or end of string. Value represents a url encoded string and case sensitive. 
+
+## Properties
+
+Properties are expected to be in a format of keys & key-value pairs `;` delimited list `;k1=v1;k2;k3=v3`. All unknown property names and name-value pairs should be skipped.
+
+# Examples of HTTP headers
+
+Single header: 
+
+```
+Correlation-Context: component=Frontend,flightName=DF:28,IsAuthenticated=true
+```
+
+Context might be split into multiple headers:
+
+```
+Correlation-Context: component=Frontend
+Correlation-Context: flight%3DName=DF28,ExposurePercentage=33.33
+```
+
+Values and names might begin and end with spaces:
+
+```
+Correlation-Context: component =   Frontend
+Correlation-Context: flight%3DName = DF28, ExposurePercentage = 33.33
+```

CORRELATION_CONTEXT_HTTP_HEADER_FORMAT_RATIONALE.md

@@ -0,0 +1,55 @@
+# Rationale for Correlation Context HTTP Header Format
+
+This document provides rationale for the decisions made for the `Correlation-Context` header format.
+
+## Purpose of a header
+
+Correlation context header is used to propagate properties not defined in `Trace-Context`. There are two common use cases. First is to define a context on trace initiation. Such context will have customer's identity, high-level operation name and other properties like a flight name. Second use case is to pass the caller's name to the next component. This name-value pair will be overridden by every service to it's own name.
+
+## General considerations
+
+- Should be human readable. Cryptic header will hide the fact of potential information disclosure.
+- Should be appende-able (comma-separated) https://tools.ietf.org/html/rfc7230#page-24 so nodes can add context properties without parsing an existing headers.
+- It is expected that the typical name will be a single word in latin and the value will be a short string in latin or a derivative of an url.
+
+## Why a single header?
+
+Another option is to use prefixed headers, such as `trace-context-X` where `X` is a propagated field name. This could reduce the size of the data, particularly in http/2 where header compression can apply.
+
+Generally speaking `Correlation-Context` header may be split into multiple headers and compression may be at the same ballpark as repeating values will be converted into a single value in HPAC's dynamic collection. That's said there were no profiling made to make this decision.
+
+The approach with multiple headers has the following problems:
+- Name values limitation is much more pressing when the context name is used a part of a header name.
+- The comma-separated format similar to the proposed still needs to be supported in every individual header. This makes parsing harder.
+- Single header is easier to configure for tracing by many app servers.
+
+## Why not Vary-style?
+
+The [Vary](https://tools.ietf.org/html/rfc7231#section-7.1.4) approach is another alternative, which could be used to accomplish the same. For example, `Correlation-Context: x-b3-parentid;ttl=1` could tell the propagation to look at and forward the parent ID header, but only to the next hop. This has an advantage of http header compression (hpack) and also weave-in with legacy tracing headers.
+
+Vary approach may be implemented as a new "header reference" value type `ref`. `Correlation-Context: x-b3-parentid;type=ref;ttl=1` if proven needed.
+
+## Trimming of spaces
+
+Header should be human readable and editable. Thus spaces are allowed before and after the comma separator.
+
+## Case sensitivity of names
+
+There are few considerations why the names should be case sensitive:
+- some keys may be a url query string parameters which are case sensitive
+- forcing lower case will decrease readability of the names written in camel case
+
+## Strings encoding
+
+Url encoding is low-overhead way to encode unicode characters for non-latin characters in the values. Url encoding keeps a single words in latin unchanged and easy readable.
+
+## Limits
+
+The idea behind limits is to provide trace vendors common safeguards so the content of the `Correlation-Context` header can be stored with the request. Thus the limits are defined on the number of keys, max pair length and the total size. The last limit is the most important in many scenarios as it allows to plan for the data storage limits.
+
+Another consideration was that HTTP cookies provide a similar way to pass custom data via HTTP headers. So the limits should make the correlation context name-value pairs fit the typical cookie limits.
+
+- *Maximum number of name-value pairs* - this limit was taken as a number of cookies allowed by Chrome.
+- *Maximum number of bytes per a single name-value pair* - the limit allows to store URL as a value with some extra details as a single context name-value pair. It is also a typical cookie size limitation.
+- *Maximum total length of all name-value pairs* - TODO: LOOKING FOR SUGGESTIONS HERE
+