cloud_events 0.1.2 → 0.5.1

data/lib/cloud_events.rb

@@ -3,6 +3,7 @@
 require "cloud_events/content_type"
 require "cloud_events/errors"
 require "cloud_events/event"
+require "cloud_events/format"
 require "cloud_events/http_binding"
 require "cloud_events/json_format"
 

data/lib/cloud_events/content_type.rb

@@ -14,23 +14,28 @@ module CloudEvents
   # can, and fill the rest with defaults as recommended in RFC 2045 sec 5.2.
   # In case of a parsing error, the {#error_message} field will be set.
   #
+  # This object is immutable, and Ractor-shareable on Ruby 3.
+  #
   class ContentType
     ##
     # Parse the given header value.
     #
     # @param string [String] Content-Type header value in RFC 2045 format
+    # @param default_charset [String] Optional. The charset to use if none is
+    #     specified. Defaults to `us-ascii`.
     #
-    def initialize string
-      @string = string
+    def initialize string, default_charset: nil
+      @string = string.to_s
       @media_type = "text"
       @subtype_base = @subtype = "plain"
       @subtype_format = nil
       @params = []
-      @charset = "us-ascii"
+      @charset = default_charset || "us-ascii"
       @error_message = nil
       parse consume_comments string.strip
       @canonical_string = "#{@media_type}/#{@subtype}" +
                           @params.map { |k, v| "; #{k}=#{maybe_quote v}" }.join
+      full_freeze
     end
 
     ##
@@ -137,7 +142,7 @@ module CloudEvents
     end
 
     def consume_token str, downcase: false, error_message: nil
-      match = /^([\w!#\$%&'\*\+\.\^`\{\|\}-]+)(.*)$/.match str
+      match = /^([\w!#$%&'*+.\^`{|}-]+)(.*)$/.match str
       raise ParseError, error_message || "Expected token" unless match
       token = match[1]
       token.downcase! if downcase
@@ -200,9 +205,21 @@ module CloudEvents
     end
 
     def maybe_quote str
-      return str if /^[\w!#\$%&'\*\+\.\^`\{\|\}-]+$/ =~ str
+      return str if /^[\w!#$%&'*+.\^`{|}-]+$/ =~ str
       str = str.gsub("\\", "\\\\\\\\").gsub("\"", "\\\\\"")
       "\"#{str}\""
     end
+
+    def full_freeze
+      instance_variables.each do |iv|
+        instance_variable_get(iv).freeze
+      end
+      @params.each do |name_val|
+        name_val[0].freeze
+        name_val[1].freeze
+        name_val.freeze
+      end
+      freeze
+    end
   end
 end

data/lib/cloud_events/errors.rb

@@ -8,21 +8,53 @@ module CloudEvents
   end
 
   ##
-  # Errors indicating unsupported or incorrectly formatted HTTP content or
-  # headers.
+  # An error raised when a protocol binding was asked to decode a CloudEvent
+  # from input data, but does not believe that the data was intended to be a
+  # CloudEvent. For example, the HttpBinding might raise this exception if
+  # given a request that has neither the requisite headers for binary content
+  # mode, nor an appropriate content-type for structured content mode.
   #
-  class HttpContentError < CloudEventsError
+  class NotCloudEventError < CloudEventsError
   end
 
   ##
-  # Errors indicating an unsupported or incorrect spec version.
+  # An error raised when a protocol binding was asked to decode a CloudEvent
+  # from input data, and the data appears to be a CloudEvent, but was encoded
+  # in a format that is not supported. Some protocol bindings can be configured
+  # to return a {CloudEvents::Event::Opaque} object instead of raising this
+  # error.
+  #
+  class UnsupportedFormatError < CloudEventsError
+  end
+
+  ##
+  # An error raised when a protocol binding was asked to decode a CloudEvent
+  # from input data, and the data appears to be intended as a CloudEvent, but
+  # has unrecoverable format or syntax errors. This error _may_ have a `cause`
+  # such as a `JSON::ParserError` with additional information.
+  #
+  class FormatSyntaxError < CloudEventsError
+  end
+
+  ##
+  # An error raised when a `specversion` is set to a value not recognized or
+  # supported by the SDK.
   #
   class SpecVersionError < CloudEventsError
   end
 
   ##
-  # Errors related to CloudEvent attributes.
+  # An error raised when a malformed CloudEvents attribute is encountered,
+  # often because a required attribute is missing, or a value does not match
+  # the attribute's type specification.
   #
   class AttributeError < CloudEventsError
   end
+
+  ##
+  # Alias of UnsupportedFormatError, for backward compatibility.
+  #
+  # @deprecated Will be removed in version 1.0. Use {UnsupportedFormatError}.
+  #
+  HttpContentError = UnsupportedFormatError
 end

data/lib/cloud_events/event.rb

@@ -3,7 +3,7 @@
 require "date"
 require "uri"
 
-require "cloud_events/event/field_interpreter"
+require "cloud_events/event/opaque"
 require "cloud_events/event/v0"
 require "cloud_events/event/v1"
 
@@ -50,6 +50,11 @@ module CloudEvents
       # `spec_version`, the remaining keyword arguments will be passed
       # through to the {CloudEvents::Event::V1} constructor.
       #
+      # Note that argument objects passed in may get deep-frozen if they are
+      # used in the final event object. This is particularly important for the
+      # `:data` field, for example if you pass a structured hash. If this is an
+      # issue, make a deep copy of objects before passing them to this method.
+      #
       # @param spec_version [String] The required `specversion` field.
       # @param kwargs [keywords] Additional parameters for the event.
       #

data/lib/cloud_events/event/field_interpreter.rb

@@ -1,24 +1,25 @@
 # frozen_string_literal: true
 
+require "cloud_events/event/utils"
+
 module CloudEvents
   module Event
     ##
     # A helper that extracts and interprets event fields from an input hash.
-    #
     # @private
     #
     class FieldInterpreter
       def initialize args
-        @args = keys_to_strings args
+        @args = Utils.keys_to_strings args
         @attributes = {}
       end
 
       def finish_attributes
         @args.each do |key, value|
-          @attributes[key] = value.to_s unless value.nil?
+          @attributes[key.freeze] = value.to_s.freeze unless value.nil?
         end
         @args = {}
-        @attributes
+        @attributes.freeze
       end
 
       def string keys, required: false
@@ -26,6 +27,7 @@ module CloudEvents
           case value
           when ::String
             raise AttributeError, "The #{keys.first} field cannot be empty" if value.empty?
+            value.freeze
             [value, value]
           else
             raise AttributeError, "Illegal type for #{keys.first}:" \
@@ -40,12 +42,12 @@ module CloudEvents
           when ::String
             raise AttributeError, "The #{keys.first} field cannot be empty" if value.empty?
             begin
-              [::URI.parse(value), value]
+              [Utils.deep_freeze(::URI.parse(value)), value.freeze]
             rescue ::URI::InvalidURIError => e
               raise AttributeError, "Illegal format for #{keys.first}: #{e.message}"
             end
           when ::URI::Generic
-            [value, value.to_s]
+            [Utils.deep_freeze(value), value.to_s.freeze]
           else
             raise AttributeError, "Illegal type for #{keys.first}:" \
                                   " String or URI expected but #{value.class} found"
@@ -58,15 +60,15 @@ module CloudEvents
           case value
           when ::String
             begin
-              [::DateTime.rfc3339(value), value]
+              [Utils.deep_freeze(::DateTime.rfc3339(value)), value.freeze]
             rescue ::Date::Error => e
               raise AttributeError, "Illegal format for #{keys.first}: #{e.message}"
             end
           when ::DateTime
-            [value, value.rfc3339]
+            [Utils.deep_freeze(value), value.rfc3339.freeze]
           when ::Time
             value = value.to_datetime
-            [value, value.rfc3339]
+            [Utils.deep_freeze(value), value.rfc3339.freeze]
           else
             raise AttributeError, "Illegal type for #{keys.first}:" \
                                   " String, Time, or DateTime expected but #{value.class} found"
@@ -79,7 +81,7 @@ module CloudEvents
           case value
           when ::String
             raise AttributeError, "The #{keys.first} field cannot be empty" if value.empty?
-            [ContentType.new(value), value]
+            [ContentType.new(value), value.freeze]
           when ContentType
             [value, value.to_s]
           else
@@ -94,6 +96,7 @@ module CloudEvents
           case value
           when ::String
             raise SpecVersionError, "Unrecognized specversion: #{value}" unless accept =~ value
+            value.freeze
             [value, value]
           else
             raise AttributeError, "Illegal type for #{keys.first}:" \
@@ -102,7 +105,16 @@ module CloudEvents
         end
       end
 
-      UNDEFINED = ::Object.new
+      def data_object keys, required: false
+        object keys, required: required, allow_nil: true do |value|
+          Utils.deep_freeze value
+          [value, value]
+        end
+      end
+
+      UNDEFINED = ::Object.new.freeze
+
+      private
 
       def object keys, required: false, allow_nil: false
         value = UNDEFINED
@@ -115,24 +127,10 @@ module CloudEvents
           raise AttributeError, "The #{keys.first} field is required" if required
           return nil
         end
-        if block_given?
-          converted, raw = yield value
-        else
-          converted = raw = value
-        end
-        @attributes[keys.first] = raw
+        converted, raw = yield value
+        @attributes[keys.first.freeze] = raw
         converted
       end
-
-      private
-
-      def keys_to_strings hash
-        result = {}
-        hash.each do |key, val|
-          result[key.to_s] = val
-        end
-        result
-      end
     end
   end
 end

data/lib/cloud_events/event/opaque.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module CloudEvents
+  module Event
+    ##
+    # This object represents opaque event data that arrived in structured
+    # content mode but was not in a recognized format. It may represent a
+    # single event or a batch of events.
+    #
+    # The event data is retained in a form that can be reserialized (in a
+    # structured cotent mode in the same format) but cannot otherwise be
+    # inspected.
+    #
+    # This object is immutable, and Ractor-shareable on Ruby 3.
+    #
+    class Opaque
+      ##
+      # Create an opaque object wrapping the given content and a content type.
+      #
+      # @param content [String] The opaque serialized event data.
+      # @param content_type [CloudEvents::ContentType,nil] The content type,
+      #     or `nil` if there is no content type.
+      # @param batch [boolean] Whether this represents a batch. If set to `nil`
+      #     or not provided, the value will be inferred from the content type
+      #     if possible, or otherwise set to `nil` indicating not known.
+      #
+      def initialize content, content_type, batch: nil
+        @content = content.freeze
+        @content_type = content_type
+        if batch.nil? && content_type&.media_type == "application"
+          case content_type.subtype_base
+          when "cloudevents"
+            batch = false
+          when "cloudevents-batch"
+            batch = true
+          end
+        end
+        @batch = batch
+        freeze
+      end
+
+      ##
+      # The opaque serialized event data
+      #
+      # @return [String]
+      #
+      attr_reader :content
+
+      ##
+      # The content type, or `nil` if there is no content type.
+      #
+      # @return [CloudEvents::ContentType,nil]
+      #
+      attr_reader :content_type
+
+      ##
+      # Whether this represents a batch, or `nil` if not known.
+      #
+      # @return [boolean,nil]
+      #
+      def batch?
+        @batch
+      end
+
+      ## @private
+      def == other
+        Opaque === other &&
+          @content == other.content &&
+          @content_type == other.content_type &&
+          @batch == other.batch?
+      end
+      alias eql? ==
+
+      ## @private
+      def hash
+        @content.hash ^ @content_type.hash ^ @batch.hash
+      end
+    end
+  end
+end

data/lib/cloud_events/event/utils.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module CloudEvents
+  module Event
+    ##
+    # A variety of helper methods.
+    # @private
+    #
+    module Utils
+      class << self
+        def deep_freeze obj
+          case obj
+          when ::Hash
+            obj.each do |key, val|
+              deep_freeze key
+              deep_freeze val
+            end
+          when ::Array
+            obj.each do |val|
+              deep_freeze val
+            end
+          else
+            obj.instance_variables.each do |iv|
+              deep_freeze obj.instance_variable_get iv
+            end
+          end
+          obj.freeze
+        end
+
+        def deep_dup obj
+          case obj
+          when ::Hash
+            obj.each_with_object({}) { |(key, val), hash| hash[deep_dup key] = deep_dup val }
+          when ::Array
+            obj.map { |val| deep_dup val }
+          else
+            obj.dup
+          end
+        end
+
+        def keys_to_strings hash
+          result = {}
+          hash.each do |key, val|
+            result[key.to_s] = val
+          end
+          result
+        end
+      end
+    end
+  end
+end

data/lib/cloud_events/event/v0.rb

@@ -3,6 +3,9 @@
 require "date"
 require "uri"
 
+require "cloud_events/event/field_interpreter"
+require "cloud_events/event/utils"
+
 module CloudEvents
   module Event
     ##
@@ -16,9 +19,10 @@ module CloudEvents
     # their own accessor methods that may return typed objects (such as
     # `DateTime` for the `time` attribute).
     #
-    # This object is immutable. The data and attribute values can be
-    # retrieved but not modified. To obtain an event with modifications, use
-    # the {#with} method to create a copy with the desired changes.
+    # This object is immutable, and Ractor-shareable on Ruby 3. The data and
+    # attribute values can be retrieved but not modified. To obtain an event
+    # with modifications, use the {#with} method to create a copy with the
+    # desired changes.
     #
     # See https://github.com/cloudevents/spec/blob/v0.3/spec.md for
     # descriptions of the standard attributes.
@@ -42,7 +46,7 @@ module CloudEvents
       #     field.
       #  *  **:type** [`String`] - _required_ - The event `type` field.
       #  *  **:data** [`Object`] - _optional_ - The data associated with the
-      #     event (i.e. the `data` field.)
+      #     event (i.e. the `data` field).
       #  *  **:data_content_encoding** (or **:datacontentencoding**)
       #     [`String`] - _optional_ - The content-encoding for the data (i.e.
       #     the `datacontentencoding` field.)
@@ -59,6 +63,11 @@ module CloudEvents
       # They are not available as separate methods, but can be accessed via
       # the {Event::V1#[]} operator.
       #
+      # Note that attribute objects passed in may get deep-frozen if they are
+      # used in the final event object. This is particularly important for the
+      # `:data` field, for example if you pass a structured hash. If this is an
+      # issue, make a deep copy of objects before passing to this constructor.
+      #
       # @param attributes [Hash] The data and attributes, as a hash.
       # @param args [keywords] The data and attributes, as keyword arguments.
       #
@@ -68,13 +77,14 @@ module CloudEvents
         @id = interpreter.string ["id"], required: true
         @source = interpreter.uri ["source"], required: true
         @type = interpreter.string ["type"], required: true
-        @data = interpreter.object ["data"], allow_nil: true
+        @data = interpreter.data_object ["data"]
         @data_content_encoding = interpreter.string ["datacontentencoding", "data_content_encoding"]
         @data_content_type = interpreter.content_type ["datacontenttype", "data_content_type"]
         @schema_url = interpreter.uri ["schemaurl", "schema_url"]
         @subject = interpreter.string ["subject"]
         @time = interpreter.rfc3339_date_time ["time"]
         @attributes = interpreter.finish_attributes
+        freeze
       end
 
       ##
@@ -105,6 +115,8 @@ module CloudEvents
       #     event["time"]     # => String rfc3339 representation
       #     event.time        # => DateTime object
       #
+      # Results are also always frozen and cannot be modified in place.
+      #
       # @param key [String,Symbol] The attribute name.
       # @return [String,nil]
       #
@@ -113,12 +125,13 @@ module CloudEvents
       end
 
       ##
-      # Return a hash representation of this event.
+      # Return a hash representation of this event. The returned hash is an
+      # unfrozen deep copy. Modifications do not affect the original event.
       #
       # @return [Hash]
       #
       def to_h
-        @attributes.dup
+        Utils.deep_dup @attributes
       end
 
       ##
@@ -208,13 +221,13 @@ module CloudEvents
 
       ## @private
       def == other
-        other.is_a?(V1) && @attributes == other.instance_variable_get(:@attributes)
+        other.is_a?(V0) && @attributes == other.instance_variable_get(:@attributes)
       end
       alias eql? ==
 
       ## @private
       def hash
-        @hash ||= @attributes.hash
+        @attributes.hash
       end
     end
   end