Class: CloudEvents::JsonFormat

Inherits:
Object
  • Object
show all
Defined in:
lib/cloud_events/json_format.rb

Overview

An implementation of JSON format and JSON batch format.

Supports the CloudEvents 0.3 and CloudEvents 1.0 variants of this format. See https://github.com/cloudevents/spec/blob/v0.3/json-format.md and https://github.com/cloudevents/spec/blob/v1.0/json-format.md.

Instance Method Summary collapse

Instance Method Details

#decode_data(spec_version: nil, content: nil, content_type: nil, **_other_kwargs) ⇒ Hash?

Decode an event data object from a JSON formatted string. See Format#decode_data for a general description.

Expects :spec_version, :content and :content_type arguments, and will decline the request unless all three are provided.

If decoding succeeded, returns a hash with the following keys:

  • :data (Object) The payload object to set as the data attribute.
  • :content_type (ContentType) The content type to be set as the datacontenttype attribute.

Parameters:

  • content (String) (defaults to: nil) —

    Serialized content to decode.

  • content_type (CloudEvents::ContentType) (defaults to: nil) —

    The input content type.

Returns:

  • (Hash) —

    if accepting the request.

  • (nil) —

    if declining the request.

Raises:



122
123
124
125
126
127
128
129
130
131
132
133
 
# File 'lib/cloud_events/json_format.rb', line 122

def decode_data(spec_version: nil, content: nil, content_type: nil, **_other_kwargs)
  return nil unless spec_version
  return nil unless content
  return nil unless json_content_type?(content_type)
  unless spec_version =~ /^0\.3|1(\.|$)/
    raise(SpecVersionError, "Unrecognized specversion: #{spec_version}")
  end
  data = ::JSON.parse(content)
  { data: data, content_type: content_type }
rescue ::JSON::JSONError
  raise(FormatSyntaxError, "JSON syntax error")
end

#decode_event(content: nil, content_type: nil, data_decoder: nil, **_other_kwargs) ⇒ Hash?

Decode an event or batch from the given input JSON string. See Format#decode_event for a general description.

Expects :content and :content_type arguments, and will decline the request unless both are provided.

If decoding succeeded, returns a hash with one of the following keys:

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

Parameters:

  • content (String) (defaults to: nil) —

    Serialized content to decode.

  • content_type (CloudEvents::ContentType) (defaults to: nil) —

    The input content type.

  • data_decoder (#decode_data) (defaults to: nil) —

    Optional data field decoder, used for non-JSON content types.

Returns:

  • (Hash) —

    if accepting the request.

  • (nil) —

    if declining the request.

Raises:



40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
 
# File 'lib/cloud_events/json_format.rb', line 40

def decode_event(content: nil, content_type: nil, data_decoder: nil, **_other_kwargs)
  return nil unless content && content_type&.media_type == "application" && content_type&.subtype_format == "json"
  case content_type.subtype_base
  when "cloudevents"
    event = decode_hash_structure(::JSON.parse(content), charset: charset_of(content), data_decoder: data_decoder)
    { event: event }
  when "cloudevents-batch"
    charset = charset_of(content)
    batch = Array(::JSON.parse(content)).map do |structure|
      decode_hash_structure(structure, charset: charset, data_decoder: data_decoder)
    end
    { event_batch: batch }
  end
rescue ::JSON::JSONError
  raise(FormatSyntaxError, "JSON syntax error")
end

#decode_hash_structure(structure, charset: nil, data_decoder: nil) ⇒ CloudEvents::Event

Decode a single event from a hash data structure with keys and types conforming to the JSON envelope.

Parameters:

  • structure (Hash) —

    An input hash.

  • charset (String) (defaults to: nil) —

    The charset of the original encoded JSON document if known. Used to provide default content types.

  • data_decoder (#decode_data) (defaults to: nil) —

    Optional data field decoder, used for non-JSON content types.

Returns:



180
181
182
183
184
185
186
187
188
189
190
 
# File 'lib/cloud_events/json_format.rb', line 180

def decode_hash_structure(structure, charset: nil, data_decoder: nil)
  spec_version = structure["specversion"].to_s
  case spec_version
  when "0.3"
    decode_hash_structure_v0(structure, charset)
  when /^1(\.|$)/
    decode_hash_structure_v1(structure, charset, spec_version, data_decoder)
  else
    raise(SpecVersionError, "Unrecognized specversion: #{spec_version}")
  end
end

#encode_data(spec_version: nil, data: UNSPECIFIED, content_type: nil, sort: false, **_other_kwargs) ⇒ Hash?

Encode an event data object to a JSON formatted string. See Format#encode_data for a general description.

Expects :spec_version, :data and :content_type arguments, and will decline the request unless all three are provided. The :data object can be any Ruby object that can be interpreted as JSON. Most Ruby objects will work, but normally it will be a JSON value type comprising hashes, arrays, strings, numbers, booleans, or nil.

If decoding succeeded, returns a hash with the following keys:

  • :content (String) The serialized form of the data.
  • :content_type (ContentType) The content type for the output.

Parameters:

  • data (Object) (defaults to: UNSPECIFIED) —

    A data object to encode.

  • content_type (CloudEvents::ContentType) (defaults to: nil) —

    The input content type

  • sort (boolean) (defaults to: false) —

    Whether to sort keys of the JSON output.

Returns:

  • (Hash) —

    if accepting the request.

  • (nil) —

    if declining the request.



157
158
159
160
161
162
163
164
165
166
167
 
# File 'lib/cloud_events/json_format.rb', line 157

def encode_data(spec_version: nil, data: UNSPECIFIED, content_type: nil, sort: false, **_other_kwargs)
  return nil unless spec_version
  return nil if data == UNSPECIFIED
  return nil unless json_content_type?(content_type)
  unless spec_version =~ /^0\.3|1(\.|$)/
    raise(SpecVersionError, "Unrecognized specversion: #{spec_version}")
  end
  data = sort_keys(data) if sort
  content = ::JSON.dump(data)
  { content: content, content_type: content_type }
end

#encode_event(event: nil, event_batch: nil, data_encoder: nil, sort: false, **_other_kwargs) ⇒ Hash?

Encode an event or batch to a JSON string. This formatter should be able to handle any event. See Format#decode_event for a general description.

Expects either the :event or the :event_batch argument, but not both, and will decline the request unless exactly one is provided.

If encoding succeeded, returns a hash with the following keys:

  • :content (String) The serialized form of the event or batch.
  • :content_type (ContentType) The content type for the output.

Parameters:

  • event (CloudEvents::Event) (defaults to: nil) —

    An event to encode.

  • event_batch (Array<CloudEvents::Event>) (defaults to: nil) —

    An event batch to encode.

  • data_encoder (#encode_data) (defaults to: nil) —

    Optional data field encoder, used for non-JSON content types.

  • sort (boolean) (defaults to: false) —

    Whether to sort keys of the JSON output.

Returns:

  • (Hash) —

    if accepting the request.

  • (nil) —

    if declining the request.

Raises:



80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
 
# File 'lib/cloud_events/json_format.rb', line 80

def encode_event(event: nil, event_batch: nil, data_encoder: nil, sort: false, **_other_kwargs)
  if event && !event_batch
    structure = encode_hash_structure(event, data_encoder: data_encoder)
    structure = sort_keys(structure) if sort
    subtype = "cloudevents"
  elsif event_batch && !event
    structure = event_batch.map do |elem|
      structure_elem = encode_hash_structure(elem, data_encoder: data_encoder)
      sort ? sort_keys(structure_elem) : structure_elem
    end
    subtype = "cloudevents-batch"
  else
    return nil
  end
  content = ::JSON.dump(structure)
  content_type = ContentType.new("application/#{subtype}+json; charset=#{charset_of(content)}")
  { content: content, content_type: content_type }
rescue ::JSON::JSONError
  raise(FormatSyntaxError, "JSON syntax error")
end

#encode_hash_structure(event, data_encoder: nil) ⇒ String

Encode a single event to a hash data structure with keys and types conforming to the JSON envelope.

Parameters:

  • event (CloudEvents::Event) —

    An input event.

  • data_encoder (#encode_data) (defaults to: nil) —

    Optional data field encoder, used for non-JSON content types.

Returns:

  • (String) —

    The hash structure.



201
202
203
204
205
206
207
208
209
210
 
# File 'lib/cloud_events/json_format.rb', line 201

def encode_hash_structure(event, data_encoder: nil)
  case event
  when Event::V0
    encode_hash_structure_v0(event)
  when Event::V1
    encode_hash_structure_v1(event, data_encoder)
  else
    raise(SpecVersionError, "Unrecognized event type: #{event.class}")
  end
end