Describe headers using ABNF format

[codefromthecrypt]

from @AloisReitbauer

Honestly, I find it weird to describe the header format in plain English. We should use EBNF syntax to describe it. As an example look at the grammar for the HTTP Cookie header

...
cookie-date = *delimiter date-token-list delimiter
date-token-list = date-token ( 1delimiter date-token )
date-token = 1non-delimiter

delimiter = %x09 / %x20-2F / %x3B-40 / %x5B-60 / %x7B-7E
non-delimiter = %x00-08 / %x0A-1F / DIGIT / ":" / ALPHA / %x7F-FF
non-digit = %x00-2F / %x3A-FF

day-of-month = 1*2DIGIT ( non-digit *OCTET )
month = ( "jan" / "feb" / "mar" / "apr" /
"may" / "jun" / "jul" / "aug" /
"sep" / "oct" / "nov" / "dec" ) OCTET
year = 24DIGIT ( non-digit *OCTET )
time = hms-time ( non-digit OCTET )
hms-time = time-field ":" time-field ":" time-field
time-field = 12DIGIT

[AloisReitbauer]

Talked to Mark Nottingham today. He pointed me to http://httpwg.org/http-extensions/draft-ietf-httpbis-header-structure.html for header formats.

[AloisReitbauer]

Renaming issue to use "structured headers"

[AloisReitbauer]

I think the structured headers can be most easily used for Trace-State. We need to decide on which format we want to use:

• Dictionary - Which are basically unique name/value pairs. Example: Example-DictHeader: foo=1.23, en="Applepie", da=w4ZibGV0w6ZydGUK
• Lists - Which is basciall an array of items Example-StrListHeader: "foo", "bar", "It was the best of times."
• Parameterized Lists. Which are a combination of both approaches. (Honestly, I find them confusing)

I think for our purpose dictionary is the best approach.

I am, however, not sure how to represent Trace-Parent

[SergeyKanzhelev]

I added #96 for traceparent.

I like how this document http://httpwg.org/http-extensions/draft-ietf-httpbis-header-structure.html explains parsing algorithm. Would it be valuable to have the same for traceparent?

[SergeyKanzhelev]

Regarding tracestate I think Parameterized Lists is the best choice. It will allow tc without duplicating of entire traceparent if we will decide to go with this option. Agree?

[SergeyKanzhelev]

Just to update this issue - we agreed on Dictionary during today's sync up. See meeting notes

Need to copy boilerplate text from that spec to refer to tracestate as a dictionary. I promised to do it, but than @nikmd23 who sat in the same room said he wants to do it.

[yurishkuro]

Just to update this issue - we agreed on Dictionary during today's sync up. See meeting notes

Sorry, I was not able to dial to the first half, and the notes do not provide a good explanation on that decision. I am not against it, but it creates two issues that the spec should address:

1. how does the current node know that the previous node used the same or different tracer
2. if the tracestate header grows too long and the current node must drop some of the other vendor entries, how does it choose which ones to drop?

Note that the positional format had very good answers to these questions.

[SergeyKanzhelev]

@yurishkuro the main concern with Parametrized List was items with the key without any value. The idea was to simplify the format. We haven't discussed ordering as mentioned in #80

You are correct. Dictionary implies unordered mapping:

Let dictionary be an empty, unordered mapping.

So perhaps we can revisit that decision and agree on parametrized list

[codefromthecrypt]

Just to update this issue - we agreed on Dictionary during today's sync up. See meeting notes <https://github.com/w3c/distributed-tracing/blob/master/meeting_notes/2018-04-10.md>

who attended this meeting? this is a standard. Considering the days of text on the positional thing it is abysmal to obviate it with a one sentence note. @nicmunroe I should have made a bet that as soon as I stepped away positional would return...though not sure anyone would have bet the other side.

[SergeyKanzhelev]

who attended this meeting? this is a standard. Considering the days of text on the positional thing it is abysmal to obviate it with a one sentence note.

Just to give a context - it wasn't long discussion as we mostly looked at format, not at parsing. So with parametrized list as was suggested earlier in this issue the confusion was around example Example-ParamListHeader: abc_123;a=1;b=2; c, def_456, ghi;q="19";r=foo with the mix of ;-delimited and ','-delimited arguments (basically the format of correlation-context header).

We (at least I did) missed the keys positioning implication of the decision. As we follow the process with PRs approvals - it's great that @yurishkuro and you pointed that out. In any case we had an issue #80 opened for discussion and waiting for it's resolution.

If we want ParametrizedList, but without ; - we will need to write our own spec for it. We can merge existing PR with the switch to Dictionary as it doesn't change the spec. And then by resolving issue #80 switch to ParametrizedList or custom definition of structured header.

Preferences?

[codefromthecrypt]

Preference is to stop changing things when no one has even implemented current. Then your PRs to change things can come attached to N PRs of impact. It is well past due to have implementations and changing anything not cemented by implementation is careless. While I might be missing something, I have only seen one person ask to do an impl (a volunteer to zipkin4net). Why are people holding meetings and still not cementing it in reality? Is the draft really a draft or should we just consider it skippable as folks holding meetings arent implementing it.

…

On Sat, 14 Apr 2018, 07:49 Sergey Kanzhelev, ***@***.***> wrote: who attended this meeting? this is a standard. Considering the days of text on the positional thing it is abysmal to obviate it with a one sentence note. Just to give a context - it wasn't long discussion as we mostly looked at format, not at parsing. So with parametrized list as was suggested earlier in this issue the confusion was around example Example-ParamListHeader: abc_123;a=1;b=2; c, def_456, ghi;q="19";r=foo with the mix of ;-delimited and ','-delimited arguments (basically the format of correlation-context header). We (at least I did) missed the keys positioning implication of the decision. As we follow the process with PRs approvals - it's great that @yurishkuro <https://github.com/yurishkuro> and you pointed that out. In any case we had an issue #80 <#80> opened for discussion and waiting for it's resolution. If we want ParametrizedList, but without ; - we will need to write our own spec for it. We can merge existing PR with the switch to Dictionary as it doesn't change the spec. And then by resolving issue #80 <#80> switch to ParametrizedList or custom definition of structured header. Preferences? — You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub <#81 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AAD614Y2dFWWraLDERKX2eIaARNfDVoqks5toTl8gaJpZM4Sl9k6> .