docs: add possibility of additional message modes.

[grant]

Mentions the possibility of protocols adding different message modes (such as batched).
Fixes #645.

[cneijenhuis]

Sorry, but I still disagree.

Batching (in the HTTP binding) is one implementation of the structured mode. It is not an additional mode.

It fits the definition:

A "structured-mode message" is one where the event is fully encoded using
a stand-alone event format and stored in the message body.

because in a batch, each event is fully encoded using a stand-alone event format and stored in the message body.

I think what is confusing here is that it's easy to equate the message body with request/response body. That MAY be the case, but it's not a MUST. The protocol binding is free to add more things to the request/response body, and is free to batch multiple events (and therefore message bodies) into a single request/response body.

[grant]

Thanks for the response @cneijenhuis. Here are responses:

Sorry, but I still disagree.

Which specific part do you disagree with?

Batching (in the HTTP binding) is one implementation of the structured mode. It is not an additional mode.

No. Batched mode has a different HTTP Content-Type: application/cloudevents-batch. I think the suggested change doesn't acknowledge the technical Content-Type change.

[cneijenhuis]

I think the misunderstanding is rooted in equating the message mode with the content modes. But they are two different things!

All that the structured message mode is defining is that you need an Event Format.

• The HTTP Content-Type application/cloudevents+avro defines that the (not batched) Avro Event Format has been used.
• The HTTP Content-Type application/cloudevents+json defines that the (not batched) JSON Event Format has been used.
• The HTTP Content-Type application/cloudevents-batch+json defines that the batched JSON Event Format has been used.
  They all have in common that you need to pick the correct Event Format to decode the underlying event.

Both the structured and batched content modes are structured message modes (yes, that is confusing! 😉 ). The difference is that the first one expects an Event Format for a single event, whereas the latter one expects a batched Event Format.

The whole thing would probably be easier to grok if the Content-Type was application/cloudevents+json-batch. Then you'd only need to interpret the suffix (+json-batch) to pick the right Event Format. However, we wanted to stick to the IANA registered suffixes, and therefore the suffix can't indicate whether the Event Format is batched.

---

We could rename the HTTP content mode structured to structured-single and batched to structured-batched. I'm not sure that suggestion will find many fans, but at least it's easier to grok.

---

Hope that helps!

[grant]

Thanks for a bit more clarity.
I don't agree with a couple points such as suggesting application/cloudevents+json-batch or renaming the content mode, but I accepted the suggestion abeit it makes the section longer.

I don't see application/cloudevent as a registered IANA media type in the first place.

[deissnerk]

@grant There is an open issue related to the registration of the media type #557

[duglin]

@grant can you sign all commits? The DCO checker isn't happy

[grant]

Is there a quick way to DCO sign-off?

Can you just add the sign-off in the commit message when squash committing? i.e. add this line:

Signed-off-by: Grant Timmerman <timmerman+devrel@google.com>

[dazuma]

It looks like we're converging on a taxonomy where batched is not a separate mode, but a format under structured mode. I think that makes sense, but it would then be good if we could make corresponding updates to the http protocol spec, section 3 to align with this. Specifically:

• Batched is presented a "mode" throughout the section. We should use a different term.
• Batched is presented as distinct from structured. (e.g. it is covered in a separate section 3.3 in parallel with structured mode in section 3.2). We should consider presenting it instead as a possible feature/variant under structured mode.

[duglin]

@grant did you want to address the comment above ^^^ ?

[duglin]

Also, still need you to sign all commits

[grant]

Right now I'm not able to fix this PR. It seems like there are multiple issues at hand. I'll close it.
I'm currently not too confused about what batched means, although I think the description of it in this spec is not as concrete as the other parts of the spec.

Perhaps we can discuss in a CE call, or someone else can pick up this PR.

[cneijenhuis]

The "message body" is the thing that contains the wrapped/batch data (meaning it's the transport envelope body), so talking about the message body itself being in another structure isn't quite accurate. The final structure goes into the message body.

@duglin Again, this is not the terminology many protocols use! For many protocols, the message is NOT the same as transport envelope body, but a structure within it.

Examples:

• AMQP/RabbitMQ: https://www.rabbitmq.com/tutorials/tutorial-seven-java.html (see Strategy Add initial pass at our governance model #2: Publishing Messages in Batches)
• Googe PubSub: https://cloud.google.com/pubsub/docs/reference/rest/v1/projects.topics/publish#request-body (Probably the best example)
• Kafka calls it a "record", not a "message", but records are again a structure within a single transport body (if the producer batches): https://kafka.apache.org/25/javadoc/index.html?org/apache/kafka/clients/producer/KafkaProducer.html

In the spec we could choose to define that the message body is the same as the transport envelope body, but I don't see any advantage in doing so. It also raises the question why we have the concept of a message at all.

I still think it should be a 3-step process:

CloudEvent --(Format)--> Message --(Transport)--> Transport Envelope Body

The Transport may support batching. In this case (as for RabbitMQ/PubSub/Kafka above), we only need to define how to map a CloudEvent to a Message. The existing Transport takes care of the rest.

[duglin]

@cneijenhuis do you think it's worth trying to tweak the wording at all? If so, do you want to take a stab at it?

[cneijenhuis]

@duglin My first stab was already here: #660 (comment) but I took another one here: #672