Header values in HTTP Binary Content Mode

[Harwayne]

When serializing string valued CloudEvent attributes in HTTP Binary Content Mode, is the value surrounded by double quotes?

I.e., I want to serialize a cloud event of type com.example.someevent in HTTP Binary Content mode. What does its HTTP headers look like?

Spec

The existing spec states: "The value for each HTTP header is constructed from the respective attribute's JSON value representation, compliant with the JSON event format specification."

This means that every string value MUST to be surrounded by double quotes. And implies that when a compliant program parses the HTTP request, they MUST JSON unmarshal the header's value to obtain the Cloud Event's value.

This is supported by the examples in the spec:

POST /someresource HTTP/1.1
Host: webhook.example.com
ce-specversion: "0.2"
ce-type: "com.example.someevent"
ce-time: "2018-04-05T03:56:24Z"
ce-id: "1234-1234-1234"
ce-source: "/mycontext/subcontext"
    .... further attributes ...
Content-Type: application/json; charset=utf-8
Content-Length: nnnn

{
    ... application data ...
}

Note that the ce-type header's value is "com.example.someevent", not com.example.someevent. This is the example from the Structured Content Mode:

PUT /myresource HTTP/1.1
Host: webhook.example.com
Content-Type: application/cloudevents+json; charset=utf-8
Content-Length: nnnn

{
    "specversion" : "0.2",
    "type" : "com.example.someevent",

    ... further attributes omitted ...

    "data" : {
        ... application data ...
    }
}

This example unambiguously states the type as com.example.someevent (note that lack of quotes). Assuming that the two examples are supposed to show the same Cloud Event serialized in two different ways (albeit omitting some fields), then it seems that in Binary Content Mode, the value MUST be surrounded by double quotes.

Implementations

However, every implementation I have come across not only doesn't emit the quotes, it also doesn't handle them when parsing a request. They all treat the double quotes as part of the value. E.g. the type is "com.example.someevent".

• CloudEvents SDK-go
• Knative Eventing Message Receiver

Possible Solutions

1. Redefine the spec to not have double quotes around string values.
   • Note that this makes it difficult/impossible to distinguish between strings that happen to look like valid JSON, and that JSON itself. E.g. if the HTTP header is ce-foo: {}, is the value the string {} or the empty JSON object?
   • Would this be only on 0.3 and newer? Or retroactively changed for 0.1 and 0.2? If not retroactive, then we likely need the next solution in addition to this one.
2. Change the implementations to follow the spec.

[duglin]

I think we need to fix this - including the quotes for simple types like string, time, numbers is just odd and will cause people to jump thru more hoops than should be necessary.

@clemensv any comments on this?

[n3wscott]

Thinking about this a little more, I don't think the case of the {} is a big issue because the consumer of the extension should understand the attribute type that it is looking for. This really does not help middleware and it would have to be left as a string.

The double quotes issue is real and I always assumed it was a defect in the example, not a real requirement. It would be nice to fix the example.

[duglin]

On last week's call @clemensv took an AI to come up with a proposed solution

[clemensv]

My position is that the spec is right. Implementations that don’t follow it need fixing. String values are quoted.

Reason is twofold:

• we only get type inference from JSON if we stick to the JSON encoding model
• JSON encoding defines escape characters and sequences for non-printable and control characters that are illegal for HTTP header values. What do you do with an extension attribute that contains CRLF? Percent encoding? Now you’ve got another encoding you throw at that string.

The quotes might be an eyesore, but we don’t get around encoding the user supplied string and JSON is already required.

[n3wscott]

we only get type inference from JSON if we stick to the JSON encoding model

We only need type inference if we do not know the type. All the spec value types are well understood.

JSON encoding defines escape characters and sequences for non-printable and control characters that are illegal for HTTP header values. What do you do with an extension attribute that contains CRLF? Percent encoding? Now you’ve got another encoding you throw at that string.

This is handled with url encoding and the quotes would not be needed. The quotes confuse the matter.

[clemensv]

@n3wscott Maps (aka JSON Objects) are also valid types for extension attributes, and not all extension attributes are well-understood.

[kaminzo]

Hi @duglin, based in this issue and the associated PRs, should Kafka Protocol Binding also be updated to remove the double quotes from the Binary Protocol header?

https://github.com/cloudevents/spec/blob/main/cloudevents/bindings/kafka-protocol-binding.md#32-binary-content-mode