Support content types following structured syntax suffixes

[dan-j]

See #990, this adds support for encoding/decoding cloudevent data which is defined by a content-type following the Structured Syntax Suffixes standard.

This enables the encoding/decoding of custom content types which use the +json or +xml suffix to indicate that their encoding is JSON or XML respectively. Users can also add their own suffixes to the registry in a similar fashion to how datacodec.AddDecoder() and dataodec.AddEncoder() work, but via the AddStructuredSuffixDecoder and AddStructuredSuffixEncoder functions.

Fixes #990

[yanmxa]

Hi @dan-j @duglin ! I'm a little bit confused by the naming AddStructuredSuffixDecoder or AddStructuredSuffixEncoder with the structured(or binary) mode based on the content-type format.

So what's the relationship between the AddStructuredSuffixDecoder and the structured mode? It seems they are describing two kinds of different things, if so, I suggest using another name that won't cause any ambiguity to register the encoder and decoder.

Thanks!

[dan-j]

Hi @yanmxa, the datacodec package isn't concerned with how an event is encoded (whether structured/binary mode), which is what I think you're referring to?

The datacodec package is concerned with marshalling/unmarshalling an event's data attribute, and is determined by the event's datacontenttype attribute. So for example if you have a cloudevent.Event where datacontenttype=application/vnd.github+json like so, it would use the github.com/cloudevents/sdk-go/v2/event/datacodec/json package to unmarshal.

var e cloudevent.Event

var target MyStruct
_ = e.DataAs(&target)

"Structure Syntax Suffix" is the formal name for this technique, as documented here: https://www.iana.org/assignments/media-type-structured-suffix/media-type-structured-suffix.xhtml. We could rename the functions AddStructuredSyntaxSuffixEncoder/Decoder but I feel this wouldn't really help the confusion, it's just a longer name.

I've also tried to explain this in the GoDoc for the functions, if you have a way to better word this then I'm happy for some feedback.

[yanmxa]

Hi @yanmxa, the datacodec package isn't concerned with how an event is encoded (whether structured/binary mode), which is what I think you're referring to?

The datacodec package is concerned with marshalling/unmarshalling an event's data attribute, and is determined by the event's datacontenttype attribute. So for example if you have a cloudevent.Event where datacontenttype=application/vnd.github+json like so, it would use the github.com/cloudevents/sdk-go/v2/event/datacodec/json package to unmarshal.

var e cloudevent.Event

var target MyStruct
_ = e.DataAs(&target)

"Structure Syntax Suffix" is the formal name for this technique, as documented here: https://www.iana.org/assignments/media-type-structured-suffix/media-type-structured-suffix.xhtml. We could rename the functions AddStructuredSyntaxSuffixEncoder/Decoder but I feel this wouldn't really help the confusion, it's just a longer name.

I've also tried to explain this in the GoDoc for the functions, if you have a way to better word this then I'm happy for some feedback.

Since "Structure Syntax Suffix" is a conventional formal name for it. Using any other name seems to break the original meaning, and I agree with you that we can clarify it in the comments on the methods.

@dan-j Thanks for your clarification!