hearth 1.0.0.pre1 → 1.0.0.pre3

data/lib/hearth/http.rb

@@ -3,9 +3,13 @@
 require 'cgi'
 require_relative 'http/api_error'
 require_relative 'http/client'
+require_relative 'http/error_inspector'
 require_relative 'http/error_parser'
-require_relative 'http/headers'
-require_relative 'http/middleware/content_length'
+require_relative 'http/field'
+require_relative 'http/fields'
+require_relative 'http/header_list_builder'
+require_relative 'http/header_list_parser'
+require_relative 'http/middleware'
 require_relative 'http/networking_error'
 require_relative 'http/request'
 require_relative 'http/response'
@@ -13,21 +17,28 @@ require_relative 'http/response'
 module Hearth
   # HTTP namespace for HTTP specific functionality. Also includes utility
   # methods for URI escaping.
-  # @api private
   module HTTP
-    # TODO: - do these belong here?
     class << self
       # URI escapes the given value.
       #
-      #   Hearth::_escape("a b/c")
+      #   Hearth.uri_escape("a b/c")
       #   #=> "a%20b%2Fc"
       #
       # @param [String] value
       # @return [String] URI encoded value except for '+' and '~'.
+      # @api private
       def uri_escape(value)
         CGI.escape(value.encode('UTF-8')).gsub('+', '%20').gsub('%7E', '~')
       end
 
+      # URI escapes the given path.
+      #
+      #   Hearth.uri_escape_path("a b/c")
+      #   #=> "a%20b/c"
+      #
+      # @param [String] path
+      # @return [String] URI encoded path except for '+' and '~'.
+      # @api private
       def uri_escape_path(path)
         path.gsub(%r{[^/]+}) { |part| uri_escape(part) }
       end

data/lib/hearth/identities/anonymous.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Hearth
+  module Identities
+    # Anonymous identity.
+    class Anonymous < Identities::Base; end
+  end
+end

data/lib/hearth/identities/http_api_key.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Hearth
+  module Identities
+    # Identity class for API Key authentication.
+    class HTTPApiKey < Identities::Base
+      def initialize(key:, **kwargs)
+        super(**kwargs)
+        @key = key
+      end
+
+      # @return [String]
+      attr_reader :key
+    end
+  end
+end

data/lib/hearth/identities/http_bearer.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Hearth
+  module Identities
+    # Identity class for bearer token authentication.
+    class HTTPBearer < Identities::Base
+      def initialize(token:, **kwargs)
+        super(**kwargs)
+        @token = token
+      end
+
+      # @return [String]
+      attr_reader :token
+    end
+  end
+end

data/lib/hearth/identities/http_login.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Hearth
+  module Identities
+    # Identity class for login authentication.
+    class HTTPLogin < Identities::Base
+      def initialize(username:, password:, **kwargs)
+        super(**kwargs)
+        @username = username
+        @password = password
+      end
+
+      # @return [String]
+      attr_reader :username
+
+      # @return [String]
+      attr_reader :password
+    end
+  end
+end

data/lib/hearth/identities.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Hearth
+  # Namespace for all Identity classes.
+  module Identities
+    # Base class for all Identity classes.
+    class Base
+      def initialize(expiration: nil)
+        @expiration = expiration
+      end
+
+      # @return [Time, nil]
+      attr_reader :expiration
+    end
+  end
+end
+
+require_relative 'identities/anonymous'
+require_relative 'identities/http_api_key'
+require_relative 'identities/http_bearer'
+require_relative 'identities/http_login'

data/lib/hearth/identity_provider.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Hearth
+  # Basic Identity resolver that uses a proc to resolve an Identity.
+  class IdentityProvider
+    # @param [Proc] proc A proc that takes identity properties (Hash)
+    #   and returns a {Hearth::Identities::Base}.
+    def initialize(proc)
+      @proc = proc
+    end
+
+    # @param [Hash] properties
+    def identity(properties = {})
+      @proc.call(properties)
+    end
+  end
+end

data/lib/hearth/interceptor.rb

@@ -0,0 +1,506 @@
+# frozen_string_literal: true
+
+module Hearth
+  # # Interceptors
+  # Interceptors are a generic extension point that allows injecting
+  # logic at specific stages of execution within the SDK. Logic injection
+  # is done with hooks that the interceptor implements.
+  #
+  # Hooks are either read-only or read/write.
+  # Read-only hooks allow an interceptor to read the input,
+  # transport request, transport response or output messages.
+  # Read/write hooks allow an interceptor to modify one of these messages.
+  #
+  # # Creating an Interceptor
+  # To create an Interceptor, you must provide a hash with each key being
+  # a hook name and each value being a callable with arity 1 (context).
+  # For example:
+  #
+  #     callbacks = {
+  #       read_before_execution: proc { |context| puts "Before execution" },
+  #       read_after_execution: proc { |context| puts "After execution" }
+  #     }
+  #     interceptor = Interceptor.new(callbacks)
+  #
+  # More advanced interceptors can be created by implementing the hooks
+  # directly in a class. For example:
+  #
+  #     class MyInterceptor
+  #       def initialize
+  #         # keep state or do other initialization
+  #       end
+  #
+  #       def read_before_execution(context)
+  #         puts "Before execution"
+  #       end
+  #
+  #       def read_after_execution(context)
+  #         puts "After execution"
+  #       end
+  #     end
+  #
+  # # Registering an Interceptor
+  # Interceptors are registered by appending them to an {InterceptorList}
+  # and passing it to the the Client's Config. For example:
+  #
+  #     interceptors = InterceptorList.new([MyInterceptor.new])
+  #     config = Organization::Config.new(interceptors: interceptors)
+  #     client = Organization::Client.new(config: config)
+  #     client.operation
+  #     #=> "Before execution"
+  #     #=> "After execution"
+  #
+  # # Available Hooks
+  # The available hooks can be retrieved by calling {Interceptor.hooks}.
+  #
+  # The following hooks are available:
+  # * :read_before_execution
+  # * :modify_before_serialization
+  # * :read_before_serialization
+  # * :read_after_serialization
+  # * :modify_before_retry_loop
+  # * :read_before_attempt
+  # * :modify_before_signing
+  # * :read_before_signing
+  # * :read_after_signing
+  # * :modify_before_transmit
+  # * :read_before_transmit
+  # * :read_after_transmit
+  # * :modify_before_deserialization
+  # * :read_before_deserialization
+  # * :read_after_deserialization
+  # * :modify_before_attempt_completion
+  # * :read_after_attempt
+  # * :modify_before_completion
+  # * :read_after_execution
+  #
+  # # Hook Details
+  # The following sections describe each hook in detail.
+  #
+  # ## :read_before_execution
+  # A hook called at the start of an execution, before the SDK
+  # does anything else.
+  #
+  # When: This will ALWAYS be called once per execution. The duration
+  # between invocation of this hook and :read_after_execution is very
+  # close to full duration of the execution.
+  #
+  # Available Information: The {InterceptorContext#input} is ALWAYS
+  # available. Other information WILL NOT be available.
+  #
+  # Error Behavior: Errors raised by this hook will be stored
+  # until all interceptors have had their :read_before_execution
+  # invoked. Other hooks will then be skipped and execution will jump to
+  # :modify_before_completion with the raised error as the
+  # {Output#error} in {InterceptorContext#output}. If multiple
+  # :read_before_execution methods raise errors, the latest
+  # will be used and earlier ones will be logged and dropped.
+  #
+  # ## :modify_before_serialization
+  # A hook called before the input message is marshalled into a
+  # transport message. This method has the ability to modify the
+  # input message.
+  #
+  # When: This will ALWAYS be called once per execution, except when a
+  # failure occurs earlier in the request pipeline.
+  #
+  # Available Information: The {InterceptorContext#input} is ALWAYS
+  # available. This input may have been modified by earlier
+  # :modify_before_serialization hooks, and may be modified further by
+  # later hooks. Other information WILL NOT be available.
+  #
+  # Error Behavior: If errors are raised by this hook, execution will
+  # jump to :modify_before_completion with the raised error as the
+  # {Output#error} in {InterceptorContext#output}.
+  #
+  # ## :read_before_serialization
+  # A hook called before the input message is marshalled into a transport
+  # message.
+  #
+  # When: This will ALWAYS be called once per execution, except when a
+  # failure occurs earlier in the request pipeline. The duration
+  # between invocation of this hook and :read_after_serialization is
+  # very close to the amount of time spent marshalling the request.
+  #
+  # Available Information: The {InterceptorContext#input} is
+  # ALWAYS available. Other information WILL NOT be available.
+  #
+  # Error Behavior: If errors are raised by this hook, execution will
+  # jump to :modify_before_completion with the raised error as the
+  # {Output#error} in {InterceptorContext#output}.
+  #
+  # ## :read_after_serialization
+  # A hook called after the input message is marshalled into a transport
+  # message.
+  #
+  # When: This will ALWAYS be called once per execution, except when a
+  # failure occurs earlier in the request pipeline. The duration
+  # between invocation of this hook and :read_before_serialization is
+  # very close to the amount of time spent marshalling the request.
+  #
+  # Available Information: The {InterceptorContext#input},
+  # {InterceptorContext#request} are ALWAYS available. Other
+  # information WILL NOT be available.
+  #
+  # Error Behavior: If errors are raised by this hook, execution will
+  # jump to :modify_before_completion with the raised error as the
+  # {Output#error} in {InterceptorContext#output}.
+  #
+  # ## :modify_before_retry_loop
+  # A hook called before the retry loop is entered. This method
+  # has the ability to modify the transport request message.
+  #
+  # When: This will ALWAYS be called once per execution, except when a
+  # failure occurs earlier in the request pipeline.
+  #
+  # Available Information: The {InterceptorContext#input} and
+  # {InterceptorContext#request} are ALWAYS available. Other
+  # information WILL NOT be available.
+  #
+  # Error Behavior: If errors are raised by this hook, execution will
+  # jump to :modify_before_completion with the raised error as the
+  # {Output#error} in {InterceptorContext#output}.
+  #
+  # ## :read_before_attempt
+  # A hook called before each attempt at sending the transmission
+  # request message to the service.
+  #
+  # When: This will ALWAYS be called once per attempt, except when a
+  # failure occurs earlier in the request pipeline. This method will be
+  # called multiple times in the event of retries.
+  #
+  # Available Information: The {InterceptorContext#input} and
+  # {InterceptorContext#request} are ALWAYS available. Other
+  # information WILL NOT be available. In the event of retries, the
+  # {InterceptorContext} WILL include changes made in previous
+  # attempts (e.g. by other interceptors).
+  #
+  # Error Behavior: Errors raised by this hook will be stored
+  # until all interceptors have had their :read_before_attempt
+  # invoked. Other hooks will then be skipped and execution will jump to
+  # :modify_before_attempt_completion with the raised error as the
+  # {Output#error} in {InterceptorContext#output}. If multiple
+  # :read_before_attempt methods raise errors, the latest will be used
+  # and earlier ones will be logged and dropped.
+  #
+  # ## :modify_before_signing
+  # A hook called before the transport request message is signed. This
+  # method has the ability to modify the transport request message.
+  #
+  # When: This will ALWAYS be called once per attempt, except when a
+  # failure occurs earlier in the request pipeline. This method may be
+  # called multiple times in the event of retries.
+  #
+  # Available Information: The {InterceptorContext#input} and
+  # {InterceptorContext#request} are ALWAYS available. The request may
+  # have been modified by earlier :modify_before_signing hooks, and may
+  # be modified further by later hooks. Other information WILL NOT be
+  # available. In the event of retries, the {InterceptorContext} WILL
+  # include changes made in previous attempts (e.g. by other middleware
+  # or interceptors).
+  #
+  # Error Behavior: If errors are raised by this hook, execution will
+  # jump to :modify_before_attempt_completion with the raised error as
+  # the {Output#error} in {InterceptorContext#output}.
+  #
+  # ## :read_before_signing
+  # A hook called before the transport request message is signed.
+  #
+  # When: This will ALWAYS be called once per attempt, except when a
+  # failure occurs earlier in the request pipeline. This method may be
+  # called multiple times in the event of retries. The duration between
+  # invocation of this hook and :read_after_signing is very close to
+  # the amount of time spent signing the request.
+  #
+  # Available Information: The {InterceptorContext#input} and
+  # {InterceptorContext#request} are ALWAYS available. Other
+  # information WILL NOT be available. In the event of retries, the
+  # {InterceptorContext} WILL include changes made in previous
+  # attempts (e.g. by other interceptors).
+  #
+  # Error Behavior: If errors are raised by this hook, execution will
+  # jump to :modify_before_attempt_completion with the raised error as
+  # the {Output#error} in {InterceptorContext#output}.
+  #
+  # ## :read_after_signing
+  # A hook called after the transport request message is signed.
+  #
+  # When: This will ALWAYS be called once per attempt, except when a
+  # failure occurs earlier in the request pipeline. This method may be
+  # called multiple times in the event of retries. The duration between
+  # invocation of this hook and :read_before_signing is very close to
+  # the amount of time spent signing the request.
+  #
+  # Available Information: The {InterceptorContext#input} and
+  # {InterceptorContext#request} are ALWAYS available. Other
+  # information WILL NOT be available. In the event of retries, the
+  # {InterceptorContext} WILL include changes made in previous
+  # attempts (e.g. by other interceptors).
+  #
+  # Error Behavior: If errors are raised by this hook, execution will
+  # jump to :modify_before_attempt_completion with the raised error as
+  # the {Output#error} in {InterceptorContext#output}.
+  #
+  # ## :modify_before_transmit
+  # A hook called before the transport request message is sent to the
+  # service. This method has the ability to modify the transport request
+  # message.
+  #
+  # When: This will ALWAYS be called once per attempt, except when a
+  # failure occurs earlier in the request pipeline. This method may be
+  # called multiple times in the event of retries.
+  #
+  # Available Information: The {InterceptorContext#input} and
+  # {InterceptorContext#request} are ALWAYS available. The request may
+  # have been modified by earlier :modify_before_transmit hooks, and
+  # may be modified further by later hooks. Other information WILL NOT be
+  # available. In the event of retries, the {InterceptorContext} WILL
+  # include changes made in previous attempts (e.g. by other interceptors).
+  #
+  # Error Behavior: If errors are raised by this hook, execution will
+  # jump to :modify_before_attempt_completion with the raised error as
+  # the {Output#error} in {InterceptorContext#output}.
+  #
+  # ## :read_before_transmit
+  # A hook called before the transport request message is sent to the
+  # service.
+  #
+  # When: This will ALWAYS be called once per attempt, except when a
+  # failure occurs earlier in the request pipeline. This method may be
+  # called multiple times in the event of retries. The duration between
+  # invocation of this hook and :read_after_transmit is very close to
+  # the amount of time spent communicating with the service. Depending on
+  # the protocol, the duration may not include the time spent reading the
+  # response data.
+  #
+  # Available Information: The {InterceptorContext#input} and
+  # {InterceptorContext#request} are ALWAYS available. Other
+  # information WILL NOT be available. In the event of retries, the
+  # {InterceptorContext} WILL include changes made in previous
+  # attempts (e.g. by other interceptors).
+  #
+  # Error Behavior: If errors are raised by this hook, execution will
+  # jump to :modify_before_attempt_completion with the raised error as
+  # the {Output#error} in {InterceptorContext#output}.
+  #
+  # ## :read_after_transmit
+  # A hook called after the transport response message is sent to the
+  # service and a transport response message is received.
+  #
+  # When: This will ALWAYS be called once per attempt, except when a
+  # failure occurs earlier in the request pipeline. This method may be
+  # called multiple times in the event of retries. The duration between
+  # invocation of this hook and :read_before_transmit is very close to
+  # the amount of time spent communicating with the service. Depending on
+  # the protocol, the duration may not include the time spent reading the
+  # response data.
+  #
+  # Available Information: The {InterceptorContext#input},
+  # {InterceptorContext#request}, and {InterceptorContext#response}
+  # are ALWAYS available. Other information WILL NOT be available. In the
+  # event of retries, the {InterceptorContext} WILL include changes
+  # made in previous attempts (e.g. by other interceptors).
+  #
+  # Error Behavior: If errors are raised by this hook, execution will
+  # jump to :modify_before_attempt_completion with the raised error as
+  # the {Output#error} in {InterceptorContext#output}.
+  #
+  # ## :modify_before_deserialization
+  # A hook called before the transport response message is unmarshalled.
+  # This method has the ability to modify the transport response message.
+  #
+  # When: This will ALWAYS be called once per attempt, except when a
+  # failure occurs earlier in the request pipeline. This method may be
+  # called multiple times in the event of retries.
+  #
+  # Available Information: The {InterceptorContext#input},
+  # {InterceptorContext#request}, and {InterceptorContext#response}
+  # are ALWAYS available. The response may have been modified by earlier
+  # :modify_before_deserialization hooks, and may be modified further by
+  # later hooks. Other information WILL NOT be available. In the event of
+  # retries, the {InterceptorContext} WILL include changes made in
+  # previous attempts (e.g. by other interceptors).
+  #
+  # Error Behavior: If errors are raised by this hook, execution will
+  # jump to :modify_before_attempt_completion with the raised error as
+  # the {Output#error} in {InterceptorContext#output}.
+  #
+  # ## :read_before_deserialization
+  # A hook called before the transport response message is unmarshalled.
+  #
+  # When: This will ALWAYS be called once per attempt, except when a
+  # failure occurs earlier in the request pipeline. This method may be
+  # called multiple times in the event of retries. The duration between
+  # invocation of this hook and :read_after_deserialization is very
+  # close to the amount of time spent unmarshalling the service response.
+  # Depending on the protocol and operation, the duration may include the
+  # time spent downloading the response data.
+  #
+  # Available Information: The {InterceptorContext#input},
+  # {InterceptorContext#request}, and {InterceptorContext#response}
+  # are ALWAYS available. Other information WILL NOT be available. In the
+  # event of retries, the {InterceptorContext} WILL include changes
+  # made in previous attempts (e.g. by other interceptors).
+  #
+  # Error Behavior: If errors are raised by this hook, execution will
+  # jump to :modify_before_attempt_completion with the raised error as
+  # the {Output#error} in {InterceptorContext#output}.
+  #
+  # ## :read_after_deserialization
+  # A hook called after the transport response message is unmarshalled.
+  #
+  # When: This will ALWAYS be called once per attempt, except when a
+  # failure occurs earlier in the request pipeline. The duration between
+  # invocation of this hook and :read_before_deserialization is very
+  # close to the amount of time spent unmarshalling the service response.
+  # Depending on the protocol and operation, the duration may include the
+  # time spent downloading the response data.
+  #
+  # Available Information: The {InterceptorContext#input},
+  # {InterceptorContext#request}, {InterceptorContext#response}
+  # and {InterceptorContext#output} are ALWAYS available. In the event
+  # of retries, the {InterceptorContext} WILL include changes made
+  # in previous attempts (e.g. by other interceptors).
+  #
+  # Error Behavior: If errors are raised by this hook, execution will
+  # jump to :modify_before_attempt_completion with the raised error as
+  # the {Output#error} in {InterceptorContext#output}.
+  #
+  # ## :modify_before_attempt_completion
+  # A hook called when an attempt is completed. This method has the
+  # ability to modify the output message or error matching
+  # the currently-executing operation.
+  #
+  # When: This will ALWAYS be called once per attempt, except when a
+  # failure occurs before :read_before_attempt. This method may
+  # be called multiple times in the event of retries.
+  #
+  # Available Information: The {InterceptorContext#input},
+  # {InterceptorContext#request}, {InterceptorContext#response} and
+  # {InterceptorContext#output} are ALWAYS available. In the event
+  # of retries, the {InterceptorContext} WILL include changes made
+  # in previous attempts (e.g. by other interceptors).
+  #
+  # Error Behavior: If errors are raised by this hook, execution will
+  # jump to :read_after_attempt with the raised error as the
+  # {Output#error} in {InterceptorContext#output}.
+  #
+  # ## :read_after_attempt
+  # A hook called when an attempt is completed.
+  #
+  # When: This will ALWAYS be called once per attempt, as long as
+  # :read_before_attempt has been executed.
+  #
+  # Available Information: The {InterceptorContext#input},
+  # {InterceptorContext#request}, {InterceptorContext#response} and
+  # {InterceptorContext#output} are ALWAYS available. The
+  # {InterceptorContext#response} is available if a response
+  # was received by the service for this attempt. In the event of retries,
+  # the {InterceptorContext} WILL include changes made in previous
+  # attempts (e.g. by other interceptors).
+  #
+  # Error Behavior: Errors raised by this hook will be stored
+  # until all interceptors have had their :read_after_attempt invoked.
+  # If multiple :read_after_attempt methods raise errors, the latest
+  # will be used and earlier ones will be logged and dropped. If the retry
+  # strategy determines that {Output#error} is a retryable error, execution
+  # will then jump to :read_before_attempt. Otherwise, execution will jump
+  # to :modify_before_completion.
+  #
+  # ## :modify_before_completion
+  # A hook called when an execution is completed. This method has the
+  # ability to modify the output message or error matching
+  # the currently-executing operation.
+  #
+  # When: This will ALWAYS be called once per execution.
+  #
+  # Available Information: The {InterceptorContext#input} and
+  # {InterceptorContext#output} are ALWAYS available. The
+  # {InterceptorContext#request} and {InterceptorContext#response}
+  # are available if the execution proceeded far enough for them to be
+  # generated.
+  #
+  # Error Behavior: If errors are raised by this hook, execution will
+  # jump to :read_after_execution with the raised error as the
+  # {Output#error} in {InterceptorContext#output}.
+  #
+  # ## :read_after_execution
+  # A hook called when an execution is completed.
+  #
+  # When: This will ALWAYS be called once per execution. The duration
+  # between invocation of this hook and :read_before_execution is very
+  # close to the full duration of the execution.
+  #
+  # Available Information: The {InterceptorContext#input} and
+  # {InterceptorContext#output} are ALWAYS available. The
+  # {InterceptorContext#request} and {InterceptorContext#response}
+  # are available if the execution proceeded far enough for them to be
+  # generated.
+  #
+  # Error Behavior: Errors raised by this hook will be stored until all
+  # interceptors have had their :read_after_execution invoked. The
+  # error will then be treated as the {Output#error} raised by the
+  # operation. If multiple :read_after_execution methods raise
+  # errors, the latest will be used and earlier ones will be logged and
+  # dropped.
+  #
+  class Interceptor
+    # @api private
+    @hooks = [
+      READ_BEFORE_EXECUTION = :read_before_execution,
+      MODIFY_BEFORE_SERIALIZATION = :modify_before_serialization,
+      READ_BEFORE_SERIALIZATION = :read_before_serialization,
+      READ_AFTER_SERIALIZATION = :read_after_serialization,
+      MODIFY_BEFORE_RETRY_LOOP = :modify_before_retry_loop,
+      READ_BEFORE_ATTEMPT = :read_before_attempt,
+      MODIFY_BEFORE_SIGNING = :modify_before_signing,
+      READ_BEFORE_SIGNING = :read_before_signing,
+      READ_AFTER_SIGNING = :read_after_signing,
+      MODIFY_BEFORE_TRANSMIT = :modify_before_transmit,
+      READ_BEFORE_TRANSMIT = :read_before_transmit,
+      READ_AFTER_TRANSMIT = :read_after_transmit,
+      MODIFY_BEFORE_DESERIALIZATION = :modify_before_deserialization,
+      READ_BEFORE_DESERIALIZATION = :read_before_deserialization,
+      READ_AFTER_DESERIALIZATION = :read_after_deserialization,
+      MODIFY_BEFORE_ATTEMPT_COMPLETION = :modify_before_attempt_completion,
+      READ_AFTER_ATTEMPT = :read_after_attempt,
+      MODIFY_BEFORE_COMPLETION = :modify_before_completion,
+      READ_AFTER_EXECUTION = :read_after_execution
+    ]
+
+    # Creates a new Interceptor.
+    #
+    # @param [Hash<Symbol, Proc>] callbacks
+    #   A hash of hook names to callbacks. The callbacks will be invoked
+    #   when the hook is called. The callback will be passed the
+    #   {InterceptorContext} for the current execution.
+    def initialize(callbacks = {})
+      @callbacks = {}
+
+      Interceptor.hooks.each do |hook|
+        next unless callbacks[hook]
+
+        unless valid_callback?(callbacks[hook])
+          raise ArgumentError,
+                "#{hook} must be a callable with arity 1 (context)"
+        end
+
+        @callbacks[hook] = callbacks[hook]
+        define_singleton_method(hook) do |context|
+          @callbacks[hook].call(context)
+        end
+      end
+    end
+
+    class << self
+      # @return [Array<Symbol>] Returns a list of all available hooks.
+      attr_reader :hooks
+    end
+
+    private
+
+    def valid_callback?(callback)
+      callback.respond_to?(:call) && callback.arity == 1
+    end
+  end
+end