HTTP 3.1.3.2 percent-encoding: two SDKs implement it, two do not (data for #777)

[filipsajdak]

Summary

Two of the four SDKs I measured implement the percent-encoding rule in HTTP Protocol Binding 3.1.3.2 and two do not, so a conformant sender and a non-conformant receiver silently exchange corrupted attribute values today.

This is the data nobody came back with on #777. In that thread @duglin asked:

I'd be curious to know if those decoding libraries would just ignore non-escaped chars and pass them along. Meaning... if people cheated and only % encoded some of what they should if things would just work anyway :-)

and @jskeet replied:

I'm concerned about compatibility with existing CloudEvent providers and consumers.

The answer is that it does not just work, and the incompatibility is silent in the common direction.

Measured, 2026-09-21

SDK	percent-encodes on send	percent-decodes on receive
sdk-csharp (main)	yes	yes
sdk-cpp (cloudevents-sdk-cpp, not an official SDK)	yes	yes
sdk-go v2.15.2	no	no
sdk-java (main)	no	no

sdk-go, run rather than read:

GO WRITES ce-subject = "a b"        // for subject "a b"
GO WRITES ce-pct     = "100%"       // for extension value "100%"
GO READS  "a%20b"    -> "a%20b"
GO READS  "100%25"   -> "100%25"

sdk-csharp/src/CloudNative.CloudEvents/Http/HttpUtilities.cs encodes and decodes space, double quote, percent, non-printable ASCII and non-ASCII, which is 3.1.3.2 exactly. sdk-go/v2/protocol/http/write_request.go and sdk-java/http/basic/.../HttpMessageWriter.java apply no transformation in either direction.

What that costs

Conformant sender to non-conformant receiver, silent:

event	on the wire	receiver's application sees
subject = "a b"	ce-subject: a%20b	a%20b
subject = "100%"	ce-subject: 100%25	100%25

Non-conformant sender to conformant receiver:

event	on the wire	receiver produces
subject = "a b"	ce-subject: a b	a b, correct by luck: no escape present
subject = "100%"	ce-subject: 100%	rejected, malformed escape
subject = "100%41"	ce-subject: 100%41	100A, silent corruption

Only binary mode, and only for values containing space, double quote, percent or a byte outside printable ASCII. In practice that is subject and string extensions; id, type and time are unaffected in normal use, and source tends to agree because URI serialization escapes it anyway. Structured mode is unaffected.

Why I think it went unnoticed

#793 said:

Once this is agreed, we should also document conformance tests, but it's unclear at the moment where they should live.

As far as I can find, they still do not exist. The rule is testable only against another implementation, and the interop testing I have seen between SDKs compares JSON event documents rather than binding header mappings, which is exactly the layer where this lives. My own SDK had the same gap: the format layer was well covered and the binary-mode wire shape was not covered at all, which is why I did not notice either.

What I am asking

Not for a decision from me, and I have no standing to propose one. But this seems worth resolving in one place rather than four:

1. Is 3.1.3.2 still the intended rule? If yes, sdk-go and sdk-java are non-conformant and it is worth saying so plainly.
2. If yes, could the conformance examples from Clarify HTTP header encoding/decoding rules #777 land somewhere the SDKs can consume? A table of (attribute value, on-the-wire header value) would be enough, and is what @jskeet asked for originally.
3. If the rule is not going to be implemented broadly, the spec and the SDKs currently disagree in a way that corrupts data silently, which seems worse than either option on its own.

Happy to contribute the fixture table if that is useful, and to file the corresponding issues on sdk-go and sdk-java once there is a view here.

Context

Found while checking a C++ SDK for cross-SDK interoperability. That SDK stays conformant by default and offers an opt-in policy for talking to Go and Java, which is a workaround, not a fix.

[duglin]

@n3wscott @jskeet do you guys remember why we %-encoded the HTTP header values the way we do? I can understand needing to encode certain chars (like unicode ones) but why do we require encoding spaces? Leading and trailing spaces are supposed to be ignored, but other spaces should be left alone, so I don't think encoding is needed. Quotes are used to group things, but quotes within quoted strings are escaped with \ not %-encoded.

xRegistry adopted the CE language for http headers but I fear this will cause nothing but pain because in the most comment cases people will not need to %-encode stuff but we force them to anyway... and most people receiving those messages will NEVER think to %-decode them, leading to things breaking. So, before we deviate from CE, I'd like to better understand why CE took such a hard stance on this instead of limiting %-encoding to just certain cases?

For example:

xRegistry-name: My Cool Registry

encoded as:

xRegistry-name: My%20Cool%20Registry

will certainly cause untold pain for consumers.

[jskeet]

I don't think I was around when we decided that we should percent-encode HTTP header values - #793 was more about clarifying the details of that than the decision to percent-encode itself.

However, I disagree that limiting percent-encoding to "just certain cases" would simplify things - it would almost certainly mean writing custom encoding routines in each SDK, rather than leaning on existing code. Even though using an existing standard might feel heavy-handed, it at least makes it easy to delegate to implementations of that standard.

[duglin]

I just can't get past the idea that:

xRegistry-name: My%20Cool%20Registry

will EVER be processed correctly the first time - and that's a problem to me.

[jskeet]

For folks using SDKs, I'd expect that it would be handled correctly... although it sounds like my expectation isn't necessarily reality. It would be interesting to figure out how many people produce or consume CloudEvents themselves rather than via SDKs.

[duglin]

Can't say for sure about CE users, tbh I'm surprised how many people DON'T just process the CE headers manually and use the SDKs since it's such a trivial thing. However, for xRegistry while I do expect SDKs to eventually be created, I think we'll have plenty of people who do their own GETs, or do the equivalent of a "curl", and I bet they get annoyed real fast since they now need to add special logic that they don't need to do for other servers.

[jskeet]

So, things we ought to discuss:

• Is this something we should log for a potential change in v2 (if that ever happens)?
• Do we want to change the spec for v1? (Personally I wouldn't want to, but @duglin may differ.)
• Do we want to make a concerted effort to get all SDKs aligned?
  • Perhaps alignment should be phased as a) all SDKs can handle not-fully-escaped headers; b) all SDKs conform with the spec and fully-escape headers (even if we'd prefer the spec didn't say that)