clarity around http headers by duglin · Pull Request #1402 · cloudevents/spec

duglin · 2026-10-15T00:49:28Z

We don't actually say what should happen if the headers are not percent encoded the way the spec mandates. I'd like to suggest that we still allow the headers if they adhere to normal http processing and there are no other errors in them.

related to: #1397

duglin · 2026-10-15T16:10:46Z


+CloudEvent messages that are not encoded per the rules above SHOULD still
+try to be accepted rather than generating an error, assuming no other error is
+encountered during its processing. For clarity, the standard HTTP header


Erik suggests just having the first sentence and dropping everything else (including the stuff below).

duglin · 2026-10-15T16:20:09Z

@jskeet given our spec is silent on what to do if people do not %-encode stuff (as a sender), it seems like we need to provide some level of guidance for receivers. Any thoughts?

jskeet · 2026-10-15T16:25:28Z

Hmm. Personally I've always favoured the approach of "be strict when receiving" as a way of encouraging everyone to do the right thing - I credit that as one reason why there's much less malformed XML in the world than malformed HTML (because XML parsers generally are strict). But I know that's not a popular position.

I think the most practical position is not to particularly require any stance: if you're working in a stack which fails automatically, that's fine, and you don't need to work around it to try to accept non-conformant events. If you're working in a stack which is more lax, then that's fine too. Basically I don't want to put too much work onto SDK owners, given that SDK owner time is pretty scarce.

duglin · 2026-10-15T16:47:38Z

@jskeet if someone produces a CE header that looks like this:

ce-Foo:    "word1    word2"

The spec, today, provides no guidance on what to do. I think it hurts interop (and the spec) to remain silent and then someone chooses to throw an error on this when it's perfectly valid per the HTTP spec. In this respect, I actually think CE has a bug by not allow a "normal" HTTP header value to be used.

What does the C# SDK do on this header?

jskeet · 2026-10-15T16:54:10Z

@jskeet if someone produces a CE header that looks like this:
ce-Foo:    "word1    word2"
The spec, today, provides no guidance on what to do. I think it hurts interop (and the spec) to remain silent and then someone chooses to throw an error on this when it's perfectly valid per the HTTP spec. In this respect, I actually think CE has a bug by not allow a "normal" HTTP header value to be used.

What does the C# SDK do on this header?

I couldn't tell you offhand, to be honest - I'd have to test it. I'm happy to do that, but not right now...

jskeet · 2026-10-17T10:03:45Z

Hmm... this is going to be slightly harder to test than I'd expected, because most tools are going to format the headers themselves. We already have an ASP.NET Core sample project to handle the .NET side of things. I might need to resort to netcat...

jskeet · 2026-10-17T10:26:48Z

Okay, I've now successfully sent a request - and the value of the foo attribute is word1 word2.

duglin · 2026-10-17T10:44:50Z

As expected, and as it should. I think there may be value in telling people this is the correct behavior rather than generating an error due to the lack of %-encoding.

I keep forgetting to mention that I think the spec is ambiguous wrt double-quotes. If they're encoded, are they passed on to the app or not? Are they used for grouping wrt commas? I think our attempt to ensure non-ascii chars are supported has resulted in making the simple cases harder/ambiguous.

jskeet · 2026-10-17T10:48:06Z

I'd expect encoded double quotes to be passed onto the app, but not grouping ones. Not sure about commas.

shiva · 2026-10-17T17:34:46Z

Where are we with this discussion.

1/ it would be useful to take a position on permissible vs non-permissible encoding.
2/ We should get the standard SDKs to conform with the spec. Since I am already looking at the javascript one, we can take this up next, once I get through the backlog of existing PRs.

P.S: I am in favour of allowing % encoding of space, and passing those through, whereas if the SDKs were used, they should encoding per the spec guidance and avoid this style of encoding. Can't prevent folks from using bad habits from the 80s nonetheless :)

duglin · 2026-11-05T10:17:57Z

@jskeet this one has been updated, see what you think

jskeet

This looks good to me, with the suggested typo/hyphenation changes. I'd also be fine with Erik's suggestion.

jskeet · 2026-11-06T08:35:57Z

+encountered during its processing. For clarity, the standard HTTP header
+processing rules apply:
+
+- Character ranges sourrounded by non-percent encoded double-quotes MUST


Suggested change

- Character ranges sourrounded by non-percent encoded double-quotes MUST

- Character ranges surrounded by non-percent-encoded double-quotes MUST

The "sourrounded" bit definitely needs fixing; the additional hyphen is to avoid it sounding like "encoded with something other than a percent".

jskeet · 2026-11-06T08:36:57Z

+
+- Character ranges sourrounded by non-percent encoded double-quotes MUST
+  be excluded from whitespace trimming and commas (`,`), normally
+  interpretted as header value separators, are treated as normal characters.


Suggested change

interpretted as header value separators, are treated as normal characters.

interpreted as header value separators, are treated as normal characters.

jskeet · 2026-11-06T08:38:13Z

+  be treated as separators between a list of values. Headers with multiple
+  values MUST have the same semantic meaning as multiple instances of that
+  header name with those values.
+- Leading and trailing (non-percent encoded) whitespace around individual


Suggested change

- Leading and trailing (non-percent encoded) whitespace around individual

- Leading and trailing (non-percent-encoded) whitespace around individual

jskeet · 2026-11-06T08:38:24Z

+- Leading and trailing (non-percent encoded) whitespace around individual
+  values MUST be removed. All non-leading/trailing whitespace MUST remain
+  as-is.
+- Character ranges that are sourrounded by non-percent encoded double-quoted


Suggested change

- Character ranges that are sourrounded by non-percent encoded double-quoted

- Character ranges that are surrounded by non-percent-encoded double-quoted

Signed-off-by: Doug Davis <duglin@gmail.com>

duglin · 2026-11-11T17:47:59Z

@jskeet made another round of edits - see what you think

jskeet

Lots of nits; generally happy

jskeet · 2026-11-11T17:50:20Z


 All other [CloudEvents][ce] attributes, including extensions, MUST be
-individually mapped to and from distinct HTTP message header.
+individually mapped to and from distinct HTTP message header and follow


Suggested change

individually mapped to and from distinct HTTP message header and follow

individually mapped to and from distinct HTTP message headers and follow

jskeet · 2026-11-11T17:51:07Z

+[HTTP specification](https://www.rfc-editor.org/info/rfc9110),
+[section 5](https://www.rfc-editor.org/info/rfc9110/#section-5.1).


Suggested change

[HTTP specification](https://www.rfc-editor.org/info/rfc9110),

[section 5](https://www.rfc-editor.org/info/rfc9110/#section-5.1).

[HTTP specification section 5](https://www.rfc-editor.org/info/rfc9110/#section-5.1).

(I don't think we need two links to the same document. If anyone wants to see it from the start, they can easily scroll up...)

jskeet · 2026-11-11T17:52:14Z

+CloudEvents implementations MUST use
+[percent-encoding](https://www.rfc-editor.org/info/rfc8187).
+
+Implementations MAY also choose to encode printable US-ASCII characters.


Suggested change

Implementations MAY also choose to encode printable US-ASCII characters.

Implementations MAY choose to percent-encode printable US-ASCII characters in

addition to the characters required to be encoded by RFC 8187.

(To make it clear what encoding is used. We can tweak that further though.)

jskeet · 2026-11-11T17:52:50Z

+
+Implementations MAY also choose to encode printable US-ASCII characters.
+
+CloudEvents HTTP headers SHOULD NOT leverage the "combined field value"


On the grounds that any CloudEvents attribute must be single-valued anyway?

yup - added back in the text that was dropped to explain why...

jskeet · 2026-11-11T17:53:33Z

+case. Instead, per the HTTP specification, only leading or trailing spaces that
+are not meant to be "stripped" MUST be encoded. Note that all spaces that are
+within double-quoted range of characters, or are non-leading/trailing,
+MUST NOT be stripped.


Suggested change

MUST NOT be stripped.

MUST NOT be stripped by receivers.

(Just because most of the rest of this is about clients sending requests. Feel free to change receivers to servers.)

jskeet · 2026-11-11T17:53:42Z

+within double-quoted range of characters, or are non-leading/trailing,
+MUST NOT be stripped.
+
+Processing of double-quotes, MUST adhere to the HTTP specification.


Suggested change

Processing of double-quotes, MUST adhere to the HTTP specification.

Processing of double-quotes MUST adhere to the HTTP specification.

jskeet · 2026-11-11T17:54:30Z

+Processing of double-quotes, MUST adhere to the HTTP specification.
+
+Percent-encoding is performed by considering each non-printable Unicode
+character (ones outside the ASCII range of U+0021-U+007E) within the


Should the double quote character always be percent-encoded too?

And do we have to encode a space, if it's already within a string? So for example does "x y" have to be encoded as "x%20y" or is it okay as-is? As the space isn't leading or trailing, I wouldn't expect it to be trimmed.

No, double quotes should only be encoded if they are part of the actual value. Otherwise, a double-quote is just for grouping purposes. E.g. if I need leading spaces retained then I can encode them or wrap them in double-quotes.

No, you don't need to encode a space that's in a string - so x y can remain x y and it'll work just fine.

jskeet · 2026-11-11T17:55:40Z

+Decoding of an HTTP header value MUST adhere to the HTTP specification.
+For clarity, that includes:
+- removing any non-encoded leading/trailing whitespaces from each value.
+- processing backslashed (`\`) characters within double-quoted ranges.


This isn't mentioned in the encoding part as far as I can see. Should it be?

no it's part of the http spec. I'm trying hard not to duplicate the entire spec - but if you think I should for this I can.... or I can do the other route and remove this "For clarity" section entirely.

jskeet · 2026-11-11T17:55:48Z

+- removing any non-encoded leading/trailing whitespaces from each value.
+- processing backslashed (`\`) characters within double-quoted ranges.
+- removing any non-encoded double-quoted characters from each value.
+- decoded any percent-encoded characters.


Suggested change

- decoded any percent-encoded characters.

- decoding any percent-encoded characters.

jskeet · 2026-11-11T18:02:02Z

-itself.
+and per the
+[HTTP specification](https://www.rfc-editor.org/info/rfc9110/#section-5), any
+non-printable characters from the US-ASCII character set MUST be encoded.


Looking at that RFC, section 5 doesn't actually mention percent-encoding explicitly as far as I can see. I've only skimmed admittedly - should we perhaps clarify exactly which bit of section 5 we're talking about, and maybe link to an additional spec, RFC 3986 perhaps?)

You're correct that it just says that things must be encoded but it leaves it open for people to choose what encoding mechanism they want. So from that perspective, we're talking about ALL of section 5. I added a link to 3986 for %-encoding.

duglin · 2026-11-11T18:02:56Z

@jskeet do you happen to remember which headers were problematic? I looked at #777 but it wasn't clear to me which specific headers cause problems. It seems like it was more just a general concern/confusion factor

jskeet · 2026-11-11T18:29:13Z

@jskeet do you happen to remember which headers were problematic? I looked at #777 but it wasn't clear to me which specific headers cause problems. It seems like it was more just a general concern/confusion factor

I don't - I'd expect it to be any string-valued (or URI-valued) header, really.

duglin · 2026-11-11T18:37:23Z

thanks for the review @jskeet . I'd be curious to know what impact (if any) this will have on the C# SDK - I'm hoping none since I don't think it changes much (if anything), other than make it clear that not everything under the sun needs to be encoded :-)

Signed-off-by: Doug Davis <duglin@gmail.com>

jskeet · 2026-11-11T18:43:21Z

I don't think it would make any difference to the C# SDK as we rely on the underlying HTTP client to encode and decode the HTTP headers, and there's nothing here that violates the HTTP spec. The one exception to that might be the handling of invalid UTF-8-encoded headers; would need to check that (and can't do so right now).

duglin commented Oct 15, 2026

View reviewed changes

jskeet approved these changes Nov 6, 2026

View reviewed changes

duglin added 3 commits November 11, 2026 17:26

clarity around http headers

76cdb35

Signed-off-by: Doug Davis <duglin@gmail.com>

more edits

088432a

Signed-off-by: Doug Davis <duglin@gmail.com>

next round

2ad6f7c

Signed-off-by: Doug Davis <duglin@gmail.com>

duglin force-pushed the headers branch from 1e8e699 to 2ad6f7c Compare November 11, 2026 17:47

jskeet reviewed Nov 11, 2026

View reviewed changes

review comments

08f7e7a

Signed-off-by: Doug Davis <duglin@gmail.com>

duglin force-pushed the headers branch from f5946ab to 08f7e7a Compare November 11, 2026 18:40

duglin mentioned this pull request Nov 12, 2026

add support for %-encoding of headers cloudevents/sdk-go#1356

Open

	- Character ranges sourrounded by non-percent encoded double-quotes MUST
	- Character ranges surrounded by non-percent-encoded double-quotes MUST

	interpretted as header value separators, are treated as normal characters.
	interpreted as header value separators, are treated as normal characters.

	- Leading and trailing (non-percent encoded) whitespace around individual
	- Leading and trailing (non-percent-encoded) whitespace around individual

	- Character ranges that are sourrounded by non-percent encoded double-quoted
	- Character ranges that are surrounded by non-percent-encoded double-quoted

	individually mapped to and from distinct HTTP message header and follow
	individually mapped to and from distinct HTTP message headers and follow

		[HTTP specification](https://www.rfc-editor.org/info/rfc9110),
		[section 5](https://www.rfc-editor.org/info/rfc9110/#section-5.1).

	[HTTP specification](https://www.rfc-editor.org/info/rfc9110),
	[section 5](https://www.rfc-editor.org/info/rfc9110/#section-5.1).
	[HTTP specification section 5](https://www.rfc-editor.org/info/rfc9110/#section-5.1).

	Implementations MAY also choose to encode printable US-ASCII characters.
	Implementations MAY choose to percent-encode printable US-ASCII characters in
	addition to the characters required to be encoded by RFC 8187.


		Implementations MAY also choose to encode printable US-ASCII characters.

		CloudEvents HTTP headers SHOULD NOT leverage the "combined field value"

	Processing of double-quotes, MUST adhere to the HTTP specification.
	Processing of double-quotes MUST adhere to the HTTP specification.

	- decoded any percent-encoded characters.
	- decoding any percent-encoded characters.

Conversation

duglin commented Oct 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

duglin commented Oct 15, 2026

Uh oh!

jskeet commented Oct 15, 2026

Uh oh!

duglin commented Oct 15, 2026

Uh oh!

jskeet commented Oct 15, 2026

Uh oh!

jskeet commented Oct 17, 2026

Uh oh!

jskeet commented Oct 17, 2026

Uh oh!

duglin commented Oct 17, 2026

Uh oh!

jskeet commented Oct 17, 2026

Uh oh!

shiva commented Oct 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

duglin commented Nov 5, 2026

Uh oh!

jskeet left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

duglin commented Nov 11, 2026

Uh oh!

jskeet left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

duglin commented Oct 15, 2026 •

edited

Loading

shiva commented Oct 17, 2026 •

edited

Loading