108 lines
5.2 KiB
Markdown
108 lines
5.2 KiB
Markdown
# Implementing an event formatter
|
|
|
|
The `CloudEventFormatter` abstract type in the C# SDK is an
|
|
augmentation of the [Event
|
|
Format](https://github.com/cloudevents/spec/blob/v1.0.1/spec.md#event-format)
|
|
concept in the specification.
|
|
|
|
Strictly speaking, CloudEvent data is simply a sequence of bytes. In
|
|
practical terms, it's useful to be able to store any object
|
|
reference in the `CloudEvent.Data` property, leaving a
|
|
`CloudEventFormatter` to perform serialization and deserialization
|
|
when requested.
|
|
|
|
This means that `CloudEventFormatter` implementations need to be
|
|
aware of all content modes (binary, structured and batch) and
|
|
document how they handle data of various types. A
|
|
`CloudEventFormatter` implementation *may* implement only a subset
|
|
of content modes, but should document this very clearly. (Note:
|
|
batch content mode is not currently implemented in the SDK.)
|
|
|
|
## Data serialization and deserialization
|
|
|
|
When serializing data in binary mode messages, general purpose formatters
|
|
should handle data provided as a `byte[]`, serializing it without any
|
|
modification. Formatters are also encouraged to support serializing
|
|
strings in the obvious way (obeying any character encoding indicated
|
|
in the `datacontenttype` attribute).
|
|
|
|
When deserializing data in binary mode messages, event formatters
|
|
may use the content type to determine the in-memory object type to
|
|
deserialize to. For example, a JSON formatter may decode data in a
|
|
message with a content type of "application/json" to a JSON API type
|
|
(such as `Newtonsoft.Json.Linq.JToken`). Formatters are encouraged
|
|
to deserialize data with a content type beginning `text/` (and which
|
|
don't otherwise have a special meaning to the formatter) as
|
|
strings, obeying any character encoding indicated in the content
|
|
type. If the content type is unknown to the formatter, the data
|
|
should be populated in the `CloudEvent` as a simple byte array.
|
|
|
|
When serializing and deserializing data in a structured mode
|
|
message, an event formatter should follow the rules of the event
|
|
format it is implementing. The event formatter should be as
|
|
consistent as is reasonably possible in terms of its handling of
|
|
binary mode data and structured mode data, however. In particular, a
|
|
well-designed event format should usually not be restricted to any
|
|
specific data type, so any data that can be serialized in a binary
|
|
mode message should be serializable in a structured mode message
|
|
too.
|
|
|
|
Inconsistencies may still arise, when the structured message
|
|
contains more information about the original data than the
|
|
corresponding binary message. For example, an event format may use a
|
|
different serialization format for text and binary data, allowing
|
|
string and byte arrays to be serialized and then deserialized
|
|
seamlessly even if the content type is unknown to the formatter.
|
|
However, a binary mode messages serialized from the same data string may
|
|
lose that distinction, resulting in a `Data` property with a byte
|
|
array reference rather than a string, if nothing within the content
|
|
type indicates that the data is text.
|
|
|
|
Event formatters should document their behavior clearly. While this
|
|
doesn't allow `CloudEventFormatter` instances to be used
|
|
interchangably, it at least provides consumers with some certainty
|
|
around what they can expect for a specific formatter.
|
|
|
|
### General purpose vs single-type event formatters
|
|
|
|
The above description of data handling is designed as guidance for
|
|
general purpose event formatters, which should be able to handle any
|
|
kind of CloudEvent data with some reasonable (and well-documented)
|
|
behavior.
|
|
|
|
CloudEvent formatters can also be designed to be "single-type",
|
|
explicitly only handling a single type of CloudEvent data, known
|
|
as the *target type* of the formatter. These are typically generic
|
|
types, where the target type is expressed as the type argument. For
|
|
example, both of the built-in JSON formatters have a general purpose
|
|
formatter (`JsonEventFormatter`) and a single-type formatter
|
|
(`JsonEventFormatter<T>`).
|
|
|
|
Single-type formatters should still support CloudEvents *without*
|
|
any data (omitting any data when serializing, and deserializing to a
|
|
CloudEvent with a null `Data` property) but may expect that any data
|
|
that *is* provided is expected to be of their target type, and
|
|
expressed in an appropriate format, without taking note of the data
|
|
content type. For example, `JsonEventFormatter<PubSubMessage>` would
|
|
throw an `IllegalCastException` if it is asked to serialize a
|
|
CloudEvent with a `Data` property referring to an instance of
|
|
`StorageEvent`.
|
|
|
|
## Validation
|
|
|
|
Formatter implementations should validate references documented as
|
|
being non-null, and additionally perform CloudEvent validation on:
|
|
|
|
- Any `CloudEvent`s returned by the formatter from
|
|
`DecodeStructuredModeMessage` or `DecodeStructuredModeMessageAsync`
|
|
- The `CloudEvent` accepted in `EncodeBinaryModeEventData` or
|
|
`EncodeStructuredModeMessage`
|
|
|
|
Validation should be performed using the `Validation.CheckCloudEventArgument`
|
|
method, so that an appropriate `ArgumentException` is thrown.
|
|
|
|
The formatter should *not* perform validation on the `CloudEvent`
|
|
accepted in `DecodeBinaryModeEventData`, beyond asserting that the
|
|
argument is not null. This is typically called by a protocol binding
|
|
which should perform validation itself later.
|