Clarifications on the HTTP transport binding

[evankanderson]

Update based on feedback from #456

1. Define Context-Encoding header mapping based on datacontentencoding

2. More clearly define percent-encoding (and particularly percent-decoding) rules.

[evankanderson]

Question: this PR suggests encoding the : and / characters in attribute values when sending via HTTP binary mode.

Do we want to relax this and allow those characters to be written directly? The HTTP Location header (for example) allows this, so the current language is probably more restrictive than necessary.

[duglin]

link checker errors look real

[clemensv]

Based on the discussion in the last call, @duglin asked me to add a note here, @evankanderson

a) The PR #492 obsoletes the Content-Encoding discussion because it eliminates the attribute. The attribute was never meant to map to Content-Encoding. An HTTP implementation can nevertheless still use encodings like compression, but that's orthogonal to CloudEvents.

b) For strings, we need a hybrid of your clarification and the text it replaces. Tim's clarification for the String type in the core spec now makes it clear that we must be able to handle Unicode. That means the step "that the string MUST first be encoded according to UTF-8" from the prior text is indeed vital, but the following step in that text is unclear. The result of UTF-8 encoding is a sequence of characters of which the ASCII7 characters are unchanged and should show up as such (a pure plain ASCII string should just be plain ASCII in effect), but all further characters are percent encoded. That composes with your rule about the "token" set but we need to get both under one roof.

[evankanderson]

Thanks for pointing out #490. I'll try to rework the text in 3.1.4.2 (will be 3.1.3.2 after removing datacontentencoding) to square the circle between what we allow in String and what's allowed in an HTTP header.

For example, HTTP headers dictate that leading and trailing whitespace are permitted around the header value -- section 3.2; similarly, multiple header values for the same field name should generally be combined into a single line using the , character -- section 3.2.2.

[evankanderson]

I think I got what Clemens was suggesting; I suggested a two step encoding process:

1. Convert to ASCII using percent-encoding
2. Convert to HTTP header using header escaping

I also ran the prettier.io markdown formatter and rationalized some of the header formatting and end-matter links.

[evankanderson]

This should be compatible with #492 now.

[evankanderson]

Updated, this got lost between git commit and git push.

[duglin]

we agreed on the call yesterday to remove the which contain Unicode characters outside the ASCII range text.

[duglin]

s/optional/OPTIONAL/

[duglin]

We approved this on the 9/5 call with the agreement to remove "which contain Unicode characters outside the ASCII range" from line 212

[duglin]

@evankanderson thanks!! Merging per our approval on the call yesterday.