functions_framework 0.1.0 → 0.3.1

data/lib/functions_framework.rb

@@ -16,6 +16,7 @@ require "logger"
 
 require "functions_framework/cloud_events"
 require "functions_framework/function"
+require "functions_framework/legacy_event_converter"
 require "functions_framework/registry"
 require "functions_framework/version"
 
@@ -36,8 +37,8 @@ require "functions_framework/version"
 # functions framework. Use the {FunctionsFramework.http},
 # {FunctionsFramework.event}, or {FunctionsFramework.cloud_event} methods to
 # define functions. To serve functions via a web service, invoke the
-# `functions-framework` executable, or use the {FunctionsFramework.start} or
-# {FunctionsFramework.run} methods.
+# `functions-framework-ruby` executable, or use the {FunctionsFramework.start}
+# or {FunctionsFramework.run} methods.
 #
 # ## Internal modules
 #
@@ -48,7 +49,7 @@ require "functions_framework/version"
 #     you define an event function, you will receive the event as a
 #     {FunctionsFramework::CloudEvents::Event} object.
 #  *  {FunctionsFramework::CLI} is the implementation of the
-#     `functions-framework` executable. Most apps will not need to interact
+#     `functions-framework-ruby` executable. Most apps will not need to interact
 #     with this class directly.
 #  *  {FunctionsFramework::Function} is the internal representation of a
 #     function, indicating the type of function (http or cloud event), the
@@ -62,7 +63,7 @@ require "functions_framework/version"
 #  *  {FunctionsFramework::Server} is a web server that makes a function
 #     available via HTTP. It wraps the Puma web server and runs a specific
 #     {FunctionsFramework::Function}. Many apps can simply run the
-#     `functions-framework` executable to spin up a server. However, if you
+#     `functions-framework-ruby` executable to spin up a server. However, if you
 #     need closer control over your execution environment, you can use the
 #     {FunctionsFramework::Server} class to run a server. Note that, in most
 #     cases, it is easier to use the {FunctionsFramework.start} or
@@ -139,37 +140,10 @@ module FunctionsFramework
     end
 
     ##
-    # Define a function that responds to CloudEvents.
-    #
-    # You must provide a name for the function, and a block that implemets the
-    # function. The block should take two arguments: the event _data_ and the
-    # event _context_. Any return value is ignored.
-    #
-    # The event data argument will be one of the following types:
-    #  *  A `String` (with encoding `ASCII-8BIT`) if the data is in the form of
-    #     binary data. You may choose to perform additional interpretation of
-    #     the binary data using information in the content type provided by the
-    #     context argument.
-    #  *  Any data type that can be represented in JSON (i.e. `String`,
-    #     `Integer`, `Array`, `Hash`, `true`, `false`, or `nil`) if the event
-    #     came with a JSON payload. The content type may also be set in the
-    #     context if the data is a String.
-    #
-    # The context argument will be of type {FunctionsFramework::CloudEvents::Event},
-    # and will contain CloudEvents context attributes such as `id` and `type`.
-    #
-    # See also {FunctionsFramework.cloud_event} which defines a function that
-    # takes a single argument of type {FunctionsFramework::CloudEvents::Event}.
-    #
-    # ## Example
+    # This is an obsolete interface that defines an event function taking two
+    # arguments (data and context) rather than one.
     #
-    #     FunctionsFramework.event "my-function" do |data, context|
-    #       FunctionsFramework.logger.info "Event data: #{data.inspect}"
-    #     end
-    #
-    # @param name [String] The function name. Defaults to {DEFAULT_TARGET}.
-    # @param block [Proc] The function code as a proc.
-    # @return [self]
+    # @deprecated Use {FunctionsFramework.cloud_event} instead.
     #
     def event name = DEFAULT_TARGET, &block
       global_registry.add_event name, &block
@@ -180,12 +154,9 @@ module FunctionsFramework
     # Define a function that responds to CloudEvents.
     #
     # You must provide a name for the function, and a block that implemets the
-    # function. The block should take _one_ argument: the event object of type
+    # function. The block should take one argument: the event object of type
     # {FunctionsFramework::CloudEvents::Event}. Any return value is ignored.
     #
-    # See also {FunctionsFramework.event} which creates a function that takes
-    # data and context as separate arguments.
-    #
     # ## Example
     #
     #     FunctionsFramework.cloud_event "my-function" do |event|
@@ -205,15 +176,20 @@ module FunctionsFramework
     # Start the functions framework server in the background. The server will
     # look up the given target function name in the global registry.
     #
-    # @param target [String] The name of the function to run
+    # @param target [FunctionsFramework::Function,String] The function to run,
+    #     or the name of the function to look up in the global registry.
     # @yield [FunctionsFramework::Server::Config] A config object that can be
     #     manipulated to configure the server.
     # @return [FunctionsFramework::Server]
     #
     def start target, &block
       require "functions_framework/server"
-      function = global_registry[target]
-      raise ::ArgumentError, "Undefined function: #{target.inspect}" if function.nil?
+      if target.is_a? ::FunctionsFramework::Function
+        function = target
+      else
+        function = global_registry[target]
+        raise ::ArgumentError, "Undefined function: #{target.inspect}" if function.nil?
+      end
       server = Server.new function, &block
       server.respond_to_signals
       server.start
@@ -223,7 +199,8 @@ module FunctionsFramework
     # Run the functions framework server and block until it stops. The server
     # will look up the given target function name in the global registry.
     #
-    # @param target [String] The name of the function to run
+    # @param target [FunctionsFramework::Function,String] The function to run,
+    #     or the name of the function to look up in the global registry.
     # @yield [FunctionsFramework::Server::Config] A config object that can be
     #     manipulated to configure the server.
     # @return [self]

data/lib/functions_framework/cli.rb

@@ -12,15 +12,22 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+require "logger"
 require "optparse"
 
 require "functions_framework"
 
 module FunctionsFramework
   ##
-  # Implementation of the functions-framework executable.
+  # Implementation of the functions-framework-ruby executable.
   #
   class CLI
+    ##
+    # The default logging level, if not given in the environment variable.
+    # @return [Integer]
+    #
+    DEFAULT_LOGGING_LEVEL = ::Logger::Severity::INFO
+
     ##
     # Create a new CLI, setting arguments to their defaults.
     #
@@ -33,6 +40,8 @@ module FunctionsFramework
       @min_threads = nil
       @max_threads = nil
       @detailed_errors = nil
+      @signature_type = ::ENV["FUNCTION_SIGNATURE_TYPE"]
+      @logging_level = init_logging_level
     end
 
     ##
@@ -52,6 +61,11 @@ module FunctionsFramework
               "Set the source file to load (defaults to #{DEFAULT_SOURCE})" do |val|
           @source = val
         end
+        op.on "--signature-type TYPE",
+              "Asserts that the function has the given signature type." \
+              " Supported values are 'http' and 'cloudevent'." do |val|
+          @signature_type = val
+        end
         op.on "-p", "--port PORT", "Set the port to listen to (defaults to 8080)" do |val|
           @port = val.to_i
         end
@@ -71,10 +85,10 @@ module FunctionsFramework
           @detailed_errors = val
         end
         op.on "-v", "--verbose", "Increase log verbosity" do
-          ::FunctionsFramework.logger.level -= 1
+          @logging_level -= 1
         end
         op.on "-q", "--quiet", "Decrease log verbosity" do
-          ::FunctionsFramework.logger.level += 1
+          @logging_level += 1
         end
         op.on "--help", "Display help" do
           puts op
@@ -82,23 +96,51 @@ module FunctionsFramework
         end
       end
       option_parser.parse! argv
-      unless argv.empty?
-        warn "Unrecognized arguments: #{argv}"
-        puts op
-        exit 1
-      end
+      error "Unrecognized arguments: #{argv}\n#{op}" unless argv.empty?
       self
     end
 
     ##
     # Run the configured server, and block until it stops.
+    # If a validation error occurs, print a message and exit.
+    #
     # @return [self]
     #
     def run
-      FunctionsFramework.logger.info \
-        "FunctionsFramework: Loading functions from #{@source.inspect}..."
+      begin
+        server = start_server
+      rescue ::StandardError => e
+        error e.message
+      end
+      server.wait_until_stopped
+      self
+    end
+
+    ##
+    # Start the configured server and return the running server object.
+    # If a validation error occurs, raise an exception.
+    # This is used for testing the CLI.
+    #
+    # @return [FunctionsFramework::Server]
+    #
+    # @private
+    #
+    def start_server
+      ::FunctionsFramework.logger.level = @logging_level
+      ::FunctionsFramework.logger.info "FunctionsFramework v#{VERSION} server starting."
+      ::ENV["FUNCTION_TARGET"] = @target
+      ::ENV["FUNCTION_SOURCE"] = @source
+      ::ENV["FUNCTION_SIGNATURE_TYPE"] = @signature_type
+      ::FunctionsFramework.logger.info "FunctionsFramework: Loading functions from #{@source.inspect}..."
       load @source
-      server = ::FunctionsFramework.start @target do |config|
+      function = ::FunctionsFramework.global_registry[@target]
+      raise "Undefined function: #{@target.inspect}" if function.nil?
+      unless @signature_type.nil? ||
+             @signature_type == "http" && function.type == :http ||
+             ["cloudevent", "event"].include?(@signature_type) && function.type == :cloud_event
+        raise "Function #{@target.inspect} does not match type #{@signature_type}"
+      end
+      ::FunctionsFramework.start function do |config|
         config.rack_env = @env
         config.port = @port
         config.bind_addr = @bind
@@ -106,8 +148,24 @@ module FunctionsFramework
         config.min_threads = @min_threads
         config.max_threads = @max_threads
       end
-      server.wait_until_stopped
-      self
+    end
+
+    private
+
+    def init_logging_level
+      level_name = ::ENV["FUNCTION_LOGGING_LEVEL"].to_s.upcase.to_sym
+      ::Logger::Severity.const_get level_name
+    rescue ::NameError
+      DEFAULT_LOGGING_LEVEL
+    end
+
+    ##
+    # Print the given error message and exit.
+    # @param message [String]
+    #
+    def error message
+      warn message
+      exit 1
     end
   end
 end

data/lib/functions_framework/cloud_events.rb

@@ -12,9 +12,11 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-require "functions_framework/cloud_events/binary_content"
 require "functions_framework/cloud_events/content_type"
+require "functions_framework/cloud_events/errors"
 require "functions_framework/cloud_events/event"
+require "functions_framework/cloud_events/http_binding"
+require "functions_framework/cloud_events/json_format"
 
 module FunctionsFramework
   ##
@@ -22,122 +24,20 @@ module FunctionsFramework
   #
   # This is a Ruby implementation of the [CloudEvents](https://cloudevents.io)
   # [1.0 specification](https://github.com/cloudevents/spec/blob/master/spec.md).
-  # It provides for unmarshaling of events from Rack environment data from
-  # binary (i.e. header-based) format, as well as structured (body-based) and
-  # batch formats. A standard JSON structure parser is included. It is also
-  # possible to register handlers for other formats.
-  #
-  # TODO: Unmarshaling of events is implemented, but marshaling is not.
   #
   module CloudEvents
-    @structured_formats = {}
-    @batched_formats = {}
+    # @private
+    SUPPORTED_SPEC_VERSIONS = ["1.0"].freeze
 
     class << self
       ##
-      # Register a handler for the given structured format.
-      # The handler object must respond to the method
-      # `#decode_structured_content`. See
-      # {FunctionsFramework::CloudEvents::JsonStructure} for an example.
-      #
-      # @param format [String] The subtype format that should be handled by
-      #     this handler
-      # @param handler [#decode_structured_content] The handler object
-      # @return [self]
-      #
-      def register_structured_format format, handler
-        handlers = @structured_formats[format.to_s.strip.downcase] ||= []
-        handlers << handler unless handlers.include? handler
-        self
-      end
-
-      ##
-      # Register a handler for the given batched format.
-      # The handler object must respond to the method
-      # `#decode_batched_content`. See
-      # {FunctionsFramework::CloudEvents::JsonStructure} for an example.
+      # The spec versions supported by this implementation.
       #
-      # @param format [String] The subtype format that should be handled by
-      #     this handler
-      # @param handler [#decode_batched_content] The handler object
-      # @return [self]
+      # @return [Array<String>]
       #
-      def register_batched_format format, handler
-        handlers = @batched_formats[format.to_s.strip.downcase] ||= []
-        handlers << handler unless handlers.include? handler
-        self
-      end
-
-      ##
-      # Decode an event from the given Rack environment hash. Following the
-      # CloudEvents spec, this chooses a handler based on the Content-Type of
-      # the request.
-      #
-      # @param env [Hash] The Rack environment
-      # @return [FunctionsFramework::CloudEvents::Event] if the request
-      #     includes a single structured or binary event
-      # @return [Array<FunctionsFramework::CloudEvents::Event>] if the request
-      #     includes a batch of structured events
-      #
-      def decode_rack_env env
-        content_type_header = env["CONTENT_TYPE"]
-        raise "Missing content-type header" unless content_type_header
-        content_type = ContentType.new content_type_header
-        if content_type.media_type == "application"
-          case content_type.subtype_prefix
-          when "cloudevents"
-            return decode_structured_content env["rack.input"], content_type
-          when "cloudevents-batch"
-            return decode_batched_content env["rack.input"], content_type
-          end
-        end
-        BinaryContent.decode_rack_env env, content_type
-      end
-
-      ##
-      # Decode a single event from the given content data. This should be
-      # passed the request body, if the Content-Type is of the form
-      # `application/cloudevents+format`.
-      #
-      # @param input [IO] An IO-like object providing the content
-      # @param content_type [FunctionsFramework::CloudEvents::ContentType] the
-      #     content type
-      # @return [FunctionsFramework::CloudEvents::Event]
-      #
-      def decode_structured_content input, content_type
-        handlers = @structured_formats[content_type.subtype_format] || []
-        handlers.reverse_each do |handler|
-          event = handler.decode_structured_content input, content_type
-          return event if event
-        end
-        raise "Unknown cloudevents format: #{content_type.subtype_format.inspect}"
-      end
-
-      ##
-      # Decode a batch of events from the given content data. This should be
-      # passed the request body, if the Content-Type is of the form
-      # `application/cloudevents-batch+format`.
-      #
-      # @param input [IO] An IO-like object providing the content
-      # @param content_type [FunctionsFramework::CloudEvents::ContentType] the
-      #     content type
-      # @return [Array<FunctionsFramework::CloudEvents::Event>]
-      #
-      def decode_batched_content input, content_type
-        handlers = @batched_formats[content_type.subtype_format] || []
-        handlers.reverse_each do |handler|
-          events = handler.decode_batched_content input, content_type
-          return events if events
-        end
-        raise "Unknown cloudevents batch format: #{content_type.subtype_format.inspect}"
+      def supported_spec_versions
+        SUPPORTED_SPEC_VERSIONS
       end
     end
   end
 end
-
-require "functions_framework/cloud_events/json_structure"
-
-FunctionsFramework::CloudEvents.register_structured_format \
-  "json", FunctionsFramework::CloudEvents::JsonStructure
-FunctionsFramework::CloudEvents.register_batched_format \
-  "json", FunctionsFramework::CloudEvents::JsonStructure

data/lib/functions_framework/cloud_events/errors.rb

@@ -0,0 +1,42 @@
+# Copyright 2020 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+module FunctionsFramework
+  module CloudEvents
+    ##
+    # Base class for all CloudEvents errors.
+    #
+    class CloudEventsError < ::RuntimeError
+    end
+
+    ##
+    # Errors indicating unsupported or incorrectly formatted HTTP content or
+    # headers.
+    #
+    class HttpContentError < CloudEventsError
+    end
+
+    ##
+    # Errors indicating an unsupported or incorrect spec version.
+    #
+    class SpecVersionError < CloudEventsError
+    end
+
+    ##
+    # Errors related to CloudEvent attributes.
+    #
+    class AttributeError < CloudEventsError
+    end
+  end
+end

data/lib/functions_framework/cloud_events/event.rb

@@ -15,262 +15,64 @@
 require "date"
 require "uri"
 
+require "functions_framework/cloud_events/event/v1"
+
 module FunctionsFramework
   module CloudEvents
     ##
-    # A cloud event data type.
+    # CloudEvent object.
     #
-    # This object represents both the event data and the context attributes.
-    # It 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.
+    # An Event object represents a complete event, including both its data and
+    # its context attributes. The following are true of all event objects:
     #
-    # See https://github.com/cloudevents/spec/blob/master/spec.md for
-    # descriptions of the various attributes.
+    #  *  Event classes are defined within this module. For example, events
+    #     conforming to the CloudEvents 1.0 specification are of type
+    #     {FunctionsFramework::CloudEvents::Event::V1}.
+    #  *  All event classes include this module, so you can use
+    #     `is_a? FunctionsFramework::CloudEvents::Event` to test whether an
+    #     object is an event.
+    #  *  All event objects are immutable. Data and atribute values can be
+    #     retrieved but not modified. To "modify" an event, make a copy with
+    #     the desired changes. Generally, event classes will provide a helper
+    #     method for this purpose.
+    #  *  All event objects have a `spec_version` method that returns the
+    #     version of the CloudEvents spec implemented by that event. (Other
+    #     methods may be different, depending on the spec version.)
     #
-    class Event
-      ##
-      # Create a new cloud event object with the given data and attributes.
-      #
-      # @param id [String] The required `id` field
-      # @param source [String,URI] The required `source` field
-      # @param type [String] The required `type` field
-      # @param spec_version [String] The required `specversion` field
-      # @param data [String,Boolean,Integer,Array,Hash] The optional `data`
-      #     field
-      # @param data_content_type [String,FunctionsFramework::CloudEvents::ContentType]
-      #     The optional `datacontenttype` field
-      # @param data_schema [String,URI] The optional `dataschema` field
-      # @param subject [String] The optional `subject` field
-      # @param time [String,DateTime] The optional `time` field
-      #
-      def initialize \
-          id:,
-          source:,
-          type:,
-          spec_version:,
-          data: nil,
-          data_content_type: nil,
-          data_schema: nil,
-          subject: nil,
-          time: nil
-        @id = interpret_string "id", id, true
-        @source, @source_string = interpret_uri "source", source, true
-        @type = interpret_string "type", type, true
-        @spec_version = interpret_string "spec_version", spec_version, true
-        @data = data
-        @data_content_type, @data_content_type_string =
-          interpret_content_type "data_content_type", data_content_type
-        @data_schema, @data_schema_string = interpret_uri "data_schema", data_schema
-        @subject = interpret_string "subject", subject
-        @time, @time_string = interpret_date_time "time", time
-      end
-
-      ##
-      # Create and return a copy of this event with the given changes. See the
-      # constructor for the parameters that can be passed.
-      #
-      # @param changes [keywords] See {#initialize} for a list of arguments.
-      # @return [FunctionFramework::CloudEvents::Event]
-      #
-      def with **changes
-        params = {
-          id:                id,
-          source:            source,
-          type:              type,
-          spec_version:      spec_version,
-          data:              data,
-          data_content_type: data_content_type,
-          data_schema:       data_schema,
-          subject:           subject,
-          time:              time
-        }
-        params.merge! changes
-        Event.new(**params)
-      end
-
-      ##
-      # The `id` field
-      # @return [String]
-      #
-      attr_reader :id
-
-      ##
-      # The `source` field as a `URI` object
-      # @return [URI]
-      #
-      attr_reader :source
-
-      ##
-      # The string representation of the `source` field
-      # @return [String]
-      #
-      attr_reader :source_string
-
-      ##
-      # The `type` field
-      # @return [String]
-      #
-      attr_reader :type
-
-      ##
-      # The `specversion` field
-      # @return [String]
-      #
-      attr_reader :spec_version
-      alias specversion spec_version
-
-      ##
-      # The event-specific data, or `nil` if there is no data.
-      #
-      # Data may be one of the following types:
-      # * Binary data, represented by a `String` using `ASCII-8BIT` encoding
-      # * A string in some other encoding such as `UTF-8` or `US-ASCII`
-      # * Any JSON data type, such as String, boolean, Integer, Array, or Hash
-      #
-      # @return [Object]
-      #
-      attr_reader :data
-
-      ##
-      # The optional `datacontenttype` field as a
-      # {FunctionsFramework::CloudEvents::ContentType} object, or `nil` if the
-      # field is absent
-      #
-      # @return [FunctionsFramework::CloudEvents::ContentType,nil]
-      #
-      attr_reader :data_content_type
-      alias datacontenttype data_content_type
-
-      ##
-      # The string representation of the optional `datacontenttype` field, or
-      # `nil` if the field is absent
-      #
-      # @return [String,nil]
-      #
-      attr_reader :data_content_type_string
-      alias datacontenttype_string data_content_type_string
-
-      ##
-      # The optional `dataschema` field as a `URI` object, or `nil` if the
-      # field is absent
-      #
-      # @return [URI,nil]
-      #
-      attr_reader :data_schema
-      alias dataschema data_schema
-
-      ##
-      # The string representation of the optional `dataschema` field, or `nil`
-      # if the field is absent
-      #
-      # @return [String,nil]
-      #
-      attr_reader :data_schema_string
-      alias dataschema_string data_schema_string
-
-      ##
-      # The optional `subject` field, or `nil` if the field is absent
-      #
-      # @return [String,nil]
-      #
-      attr_reader :subject
-
-      ##
-      # The optional `time` field as a `DateTime` object, or `nil` if the field
-      # is absent
-      #
-      # @return [DateTime,nil]
-      #
-      attr_reader :time
-
-      ##
-      # The string representation of the optional `time` field, or `nil` if the
-      # field is absent
-      #
-      # @return [String,nil]
-      #
-      attr_reader :time_string
-
-      ## @private
-      def == other
-        other.is_a?(ContentType) &&
-          id == other.id &&
-          source == other.source &&
-          type == other.type &&
-          spec_version == other.spec_version &&
-          data_content_type == other.data_content_type &&
-          data_schema == other.data_schema &&
-          subject == other.subject &&
-          time == other.time &&
-          data == other.data
-      end
-      alias eql? ==
-
-      ## @private
-      def hash
-        @hash ||=
-          [id, source, type, spec_version, data_content_type, data_schema, subject, time, data].hash
-      end
-
-      private
-
-      def interpret_string name, input, required = false
-        case input
-        when ::String
-          raise ::ArgumentError, "The #{name} field cannot be empty" if input.empty?
-          input
-        when nil
-          raise ::ArgumentError, "The #{name} field is required" if required
-          nil
-        else
-          raise ::ArgumentError, "Illegal type for #{name} field: #{input.inspect}"
-        end
-      end
-
-      def interpret_uri name, input, required = false
-        case input
-        when ::String
-          raise ::ArgumentError, "The #{name} field cannot be empty" if input.empty?
-          [::URI.parse(input), input]
-        when ::URI::Generic
-          [input, input.to_s]
-        when nil
-          raise ::ArgumentError, "The #{name} field is required" if required
-          [nil, nil]
-        else
-          raise ::ArgumentError, "Illegal type for #{name} field: #{input.inspect}"
-        end
-      end
-
-      def interpret_date_time name, input, required = false
-        case input
-        when ::String
-          raise ::ArgumentError, "The #{name} field cannot be empty" if input.empty?
-          [::DateTime.rfc3339(input), input]
-        when ::DateTime
-          [input, input.rfc3339]
-        when nil
-          raise ::ArgumentError, "The #{name} field is required" if required
-          [nil, nil]
-        else
-          raise ::ArgumentError, "Illegal type for #{name} field: #{input.inspect}"
-        end
-      end
-
-      def interpret_content_type name, input, required = false
-        case input
-        when ::String
-          raise ::ArgumentError, "The #{name} field cannot be empty" if input.empty?
-          [ContentType.new(input), input]
-        when ContentType
-          [input, input.to_s]
-        when nil
-          raise ::ArgumentError, "The #{name} field is required" if required
-          [nil, nil]
-        else
-          raise ::ArgumentError, "Illegal type for #{name} field: #{input.inspect}"
+    # To create an event, you may either:
+    #
+    #  *  Construct an instance of the event class directly, for example by
+    #     calling {Event::V1.new} and passing a set of attributes.
+    #  *  Call {Event.create} and pass a spec version and a set of attributes.
+    #     This will choose the appropriate event class based on the version.
+    #  *  Decode an event from another representation. For example, use
+    #     {CloudEvents::JsonFormat} to decode an event from JSON, or use
+    #     {CloudEvents::HttpBinding} to decode an event from an HTTP request.
+    #
+    # See https://github.com/cloudevents/spec/blob/master/spec.md for more
+    # information about CloudEvents.
+    #
+    module Event
+      class << self
+        ##
+        # Create a new cloud event object with the given version. Generally,
+        # you must also pass additional keyword arguments providing the event's
+        # data and attributes. For example, if you pass `1.0` as the
+        # `spec_version`, the remaining keyword arguments will be passed
+        # through to the {Event::V1.new} constructor.
+        #
+        # @param spec_version [String] The required `specversion` field.
+        # @param kwargs [keywords] Additional parameters for the event.
+        #
+        def create spec_version:, **kwargs
+          case spec_version
+          when /^1(\.|$)/
+            V1.new spec_version: spec_version, **kwargs
+          else
+            raise SpecVersionError, "Unrecognized specversion: #{spec_version}"
+          end
         end
+        alias new create
       end
     end
   end