Module: CloudEvents::Format

Defined in:

lib/cloud_events/format.rb

Overview

This module documents the method signatures that may be implemented by formatters.

A formatter is an object that implements "structured" event encoding and decoding strategies for a particular format (such as JSON). In general, this includes four operations:

• Decoding an entire event or batch of events from a input source. This is implemented by the #decode_event method.
• Encoding an entire event or batch of events to an output sink. This is implemented by the #encode_event method.
• Decoding an event payload (i.e. the data attribute) Ruby object from a serialized representation. This is implemented by the #decode_data method.
• Encoding an event payload (i.e. the data attribute) Ruby object to a serialized representation. This is implemented by the #encode_data method.

Each method takes a set of keyword arguments, and returns either a Hash or nil. A Hash indicates that the formatter understands the request and is returning its response. A return value of nil means the formatter does not understand the request and is declining to perform the operation. In such a case, it is possible that a different formatter should handle it.

Both the keyword arguments recognized and the returned hash members may vary from formatter to formatter; similarly, the keyword arguments provided and the resturned hash members recognized may also vary for different callers. This interface will define a set of common argument and result key names, but both callers and formatters must gracefully handle the case of missing or extra information. For example, if a formatter expects a certain argument but does not receive it, it can assume the caller does not have the required information, and it may respond by returning nil to decline the request. Similarly, if a caller expects a response key but does not receive it, it can assume the formatter does not provide it, and it may respond by trying a different formatter.

Additionally, any particular formatter need not implement all methods. For example, an event formatter would generally implement #decode_event and #encode_event, but might not implement #decode_data or #encode_data.

Finally, this module itself is present primarily for documentation, and need not be directly included by formatter implementations.

Defined Under Namespace

Classes: Multi

Instance Method Summary

• #decode_data(**_kwargs) ⇒ Hash^?

  Decode an event data object from string format.

• #decode_event(**_kwargs) ⇒ Hash^?

  Decode an event or batch from the given serialized input.

• #encode_data(**_kwargs) ⇒ Hash^?

  Encode an event data object to string format.

• #encode_event(**_kwargs) ⇒ Hash^?

  Encode an event or batch to a string.

Instance Method Details

#decode_data(**_kwargs) ⇒ Hash^?

Decode an event data object from string format. This is typically called by a protocol binding to deserialize the payload (i.e. data attribute) of an event as part of "binary content mode" decoding.

Common arguments include:

• :spec_version (String) The specversion of the event.
• :content (String) Serialized payload to decode. For example, it could be from an HTTP request body.
• :content_type (ContentType) The content type. For example, it could be from the Content-Type header of an HTTP request.

The formatter must first determine whether it is able to interpret the given input. Typically, this is done by inspecting the content_type. If the formatter determines that it is unable to interpret the input, it should return nil. Otherwise, if the formatter determines it can decode the input, it should return a Hash. Common hash keys include:

• :data (Object) The payload object to be set as the data attribute in a Event object.
• :content_type (ContentType) The content type to be set as the datacontenttype attribute in a Event object. In many cases, this may simply be copied from the :content_type argument, but a formatter could modify it to provide corrections or additional information.

The formatter may also raise a CloudEventsError subclass if it understood the request but determines that the input source is malformed.

Parameters:

• _kwargs (keywords) —

  Arguments

Returns:

• (Hash) —

  if accepting the request and returning a result

• (nil) —

  if declining the request.

# File 'lib/cloud_events/format.rb', line 159

def decode_data **_kwargs
  nil
end

#decode_event(**_kwargs) ⇒ Hash^?

Decode an event or batch from the given serialized input. This is typically called by a protocol binding to deserialize event data from an input stream.

Common arguments include:

• :content (String) Serialized content to decode. For example, it could be from an HTTP request body.
• :content_type (ContentType) The content type. For example, it could be from the Content-Type header of an HTTP request.

The formatter must first determine whether it is able to interpret the given input. Typically, this is done by inspecting the content_type. If the formatter determines that it is unable to interpret the input, it should return nil. Otherwise, if the formatter determines it can decode the input, it should return a Hash. Common hash keys include:

• :event (Event) A single event decoded from the input.
• :event_batch (Array of Event) A batch of events decoded from the input.

The formatter may also raise a CloudEventsError subclass if it understood the request but determines that the input source is malformed.

Parameters:

• _kwargs (keywords) —

  Arguments

Returns:

• (Hash) —

  if accepting the request and returning a result

• (nil) —

  if declining the request.

# File 'lib/cloud_events/format.rb', line 83

def decode_event **_kwargs
  nil
end

#encode_data(**_kwargs) ⇒ Hash^?

Encode an event data object to string format. This is typically called by a protocol binding to serialize the payload (i.e. data attribute and corresponding datacontenttype attribute) of an event as part of "binary content mode" encoding.

Common arguments include:

• :spec_version (String) The specversion of the event.
• :data (Object) The payload object from an event's data attribute.
• :content_type (ContentType) The content type from an event's datacontenttype attribute.

The formatter must first determine whether it is able to interpret the given input. Typically, this is done by inspecting the content_type. If the formatter determines that it is unable to interpret the input, it should return nil. Otherwise, if the formatter determines it can decode the input, it should return a Hash. Common hash keys include:

• :content (String) The serialized form of the data. This might, for example, be written to an HTTP request body. Care should be taken to set the string's encoding properly. In particular, to output binary data, the encoding should generally be set to ASCII_8BIT.
• :content_type (ContentType) The content type for the output. This might, for example, be written to the Content-Type header of an HTTP request.

The formatter may also raise a CloudEventsError subclass if it understood the request but determines that the input source is malformed.

Parameters:

• _kwargs (keywords) —

  Arguments

Returns:

• (Hash) —

  if accepting the request and returning a result

• (nil) —

  if declining the request.

# File 'lib/cloud_events/format.rb', line 198

def encode_data **_kwargs
  nil
end

#encode_event(**_kwargs) ⇒ Hash^?

Encode an event or batch to a string. This is typically called by a protocol binding to serialize event data to an output stream.

Common arguments include:

• :event (Event) A single event to encode.
• :event_batch (Array of Event) A batch of events to encode.

The formatter must first determine whether it is able to interpret the given input. Typically, most formatters should be able to handle any event or event batch, but a specialized formatter that can handle only certain kinds of events may return nil to decline unwanted inputs. Otherwise, if the formatter determines it can encode the input, it should return a Hash. common hash keys include:

• :content (String) The serialized form of the event. This might, for example, be written to an HTTP request body. Care should be taken to set the string's encoding properly. In particular, to output binary data, the encoding should probably be set to ASCII_8BIT.
• :content_type (ContentType) The content type for the output. This might, for example, be written to the Content-Type header of an HTTP request.

The formatter may also raise a CloudEventsError subclass if it understood the request but determines that the input source is malformed.

Parameters:

• _kwargs (keywords) —

  Arguments

Returns:

• (Hash) —

  if accepting the request and returning a result

• (nil) —

  if declining the request.

# File 'lib/cloud_events/format.rb', line 120

def encode_event **_kwargs
  nil
end