hearth 1.0.0.pre1 → 1.0.0.pre3

data/lib/hearth/interceptor_context.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Hearth
+  # Context provided to interceptor hook methods. Interceptors can use this
+  # context to read and modify the input, request, response, and output.
+  # Attributes can be used to pass additional data between interceptors.
+  class InterceptorContext
+    # @param [Hearth::Structure] input
+    # @param [Hearth::Request] request
+    # @param [Hearth::Response] response
+    # @param [Hearth::Output] output
+    # @param [Logger] logger
+    def initialize(input:, request:, response:, output:, logger:)
+      @input = input
+      @request = request
+      @response = response
+      @output = output
+      @logger = logger
+      @attributes = {}
+    end
+
+    # @return [Struct] Modeled input, i.e. Types::<Operation>Input
+    attr_reader :input
+
+    # @return [Hearth::Request]
+    attr_reader :request
+
+    # @return [Hearth::Response]
+    attr_reader :response
+
+    # @return [Hearth::Output] Operation output
+    attr_reader :output
+
+    # @return [Logger] logger
+    attr_reader :logger
+
+    # @return [Hash] attributes Additional interceptor data
+    attr_reader :attributes
+  end
+end

data/lib/hearth/interceptor_list.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Hearth
+  # A list of {Hearth::Interceptor}s or classes that respond to Interceptor
+  # hook methods.
+  class InterceptorList
+    include Enumerable
+
+    # @param [Array<Interceptor>] interceptors ([])
+    def initialize(interceptors = [])
+      unless interceptors.respond_to?(:each)
+        raise ArgumentError, 'Interceptors must be an enumerable'
+      end
+
+      @interceptors = []
+      interceptors.each { |i| append(i) }
+    end
+
+    # @param [Interceptor] interceptor
+    def append(interceptor)
+      unless valid_interceptor?(interceptor)
+        raise ArgumentError,
+              'Invalid interceptor - must respond to any of: ' \
+              "#{Interceptor.hooks.join(', ')}"
+      end
+
+      @interceptors << interceptor
+    end
+    alias << append
+
+    # @param [InterceptorList] other
+    # @return [InterceptorList] self
+    def concat(other)
+      other.each { |i| append(i) }
+      self
+    end
+
+    def each(&block)
+      @interceptors.each(&block)
+    end
+
+    private
+
+    def valid_interceptor?(interceptor)
+      !(interceptor.methods & Interceptor.hooks).empty?
+    end
+  end
+end

data/lib/hearth/interceptors.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module Hearth
+  # @api private
+  module Interceptors
+    # Invoke all interceptors.
+    #
+    # @param [Symbol] hook The specific hook to invoke.
+    # @param input [Hearth::Structure] input
+    # @param [Hearth::Context] context
+    # @param [Hearth::Output] output
+    # @param [Boolean] aggregate_errors (false) When true, all interceptors are
+    #   run and only the last error is returned. When false, returns immediately
+    #   if an error is encountered.
+    # @return [nil, StandardError] nil if successful, a standard error otherwise
+    def self.invoke(hook:, input:, context:, output:, aggregate_errors: false)
+      i_ctx = interceptor_context(input, context, output)
+      last_error = nil
+
+      context.interceptors.each do |i|
+        next unless i.respond_to?(hook)
+
+        log_debug(context, i, "Invoking #{hook}")
+        i.send(hook, i_ctx)
+        log_debug(context, i, "Finished #{hook}")
+      rescue StandardError => e
+        log_debug(context, i, "Error in #{hook}: #{e} (#{e.class})")
+        log_last_interceptor_error(last_error, i, context)
+        last_error = e
+        break unless aggregate_errors
+      end
+
+      log_last_output_error(last_error, context, output)
+      last_error
+    end
+
+    class << self
+      private
+
+      def interceptor_context(input, context, output)
+        Hearth::InterceptorContext.new(
+          input: input,
+          request: context.request,
+          response: context.response,
+          output: output,
+          logger: context.logger
+        )
+      end
+
+      def log_last_interceptor_error(last_error, interceptor, context)
+        return unless last_error
+
+        message = "Dropping last error: #{last_error} (#{last_error.class})"
+        context.logger.error(
+          "[#{context.invocation_id}] [#{interceptor.class}] #{message}"
+        )
+      end
+
+      def log_last_output_error(last_error, context, output)
+        return unless last_error && output
+        return unless output.error
+
+        message = "Dropping last error: #{output.error} (#{output.error.class})"
+        context.logger.error(
+          "[#{context.invocation_id}] [Interceptors] #{message}"
+        )
+      end
+
+      def log_debug(context, interceptor, message)
+        context.logger.debug(
+          "[#{context.invocation_id}] [#{interceptor.class}] #{message}"
+        )
+      end
+    end
+  end
+end

data/lib/hearth/json.rb

@@ -12,10 +12,10 @@ module Hearth
     class << self
       # @param [String] json
       # @return [Hash]
-      def load(json)
-        # rubocop:disable Security/JSONLoad
-        ::JSON.load(json)
-        # rubocop:enable Security/JSONLoad
+      def parse(json)
+        return nil if json.empty?
+
+        ::JSON.parse(json)
       rescue ::JSON::ParserError => e
         raise ParseError, e
       end

data/lib/hearth/middleware/auth.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module Hearth
+  module Middleware
+    # A middleware that resolves identities for signing requests.
+    class Auth
+      include Middleware::Logging
+
+      # @param [Class] app The next middleware in the stack.
+      # @param [#resolve(auth_params)] auth_resolver A class that responds to a
+      #  `resolve(auth_params)` method where `auth_params` is a struct with an
+      #  operation_name. For a given operation_name, the method must return an
+      #  ordered list of {Hearth::AuthOption} objects to be considered for
+      #  authentication.
+      # @param [Struct] auth_params A struct with an operation_name and other
+      #  parameters that may be used to resolve auth options.
+      # @param [Array<Hearth::AuthScheme::Base>] auth_schemes A list of
+      #  auth schemes to consider for authentication.
+      def initialize(app, auth_resolver:, auth_params:, auth_schemes:, **kwargs)
+        @app = app
+        @auth_resolver = auth_resolver
+        @auth_params = auth_params
+        @auth_schemes = auth_schemes.to_h { |s| [s.scheme_id, s] }
+
+        @identity_providers = {}
+        kwargs.each do |key, value|
+          next unless key.superclass == Hearth::Identities::Base
+
+          @identity_providers[key] = value
+        end
+      end
+
+      # @param input
+      # @param context
+      # @return [Output]
+      def call(input, context)
+        log_debug(context, 'Resolving auth')
+        auth_options = @auth_resolver.resolve(@auth_params)
+        log_debug(context, "Resolved auth options: #{auth_options}")
+        context.auth = resolve_auth(auth_options)
+        log_debug(context, "Resolved auth: #{context.auth}")
+        @app.call(input, context)
+      end
+
+      private
+
+      ResolvedAuth = Struct.new(
+        :scheme_id,
+        :signer,
+        :signer_properties,
+        :identity,
+        :identity_properties,
+        keyword_init: true
+      )
+
+      def resolve_auth(auth_options)
+        failures = []
+
+        raise 'No auth options were resolved' if auth_options.empty?
+
+        auth_options.each do |auth_option|
+          auth_scheme = @auth_schemes[auth_option.scheme_id]
+          resolved_auth = try_load_auth_scheme(
+            auth_option,
+            auth_scheme,
+            failures
+          )
+
+          return resolved_auth if resolved_auth
+        end
+
+        raise failures.join("\n")
+      end
+
+      def try_load_auth_scheme(auth_option, auth_scheme, failures)
+        scheme_id = auth_option.scheme_id
+        unless auth_scheme
+          failures << "Auth scheme #{scheme_id} was not enabled " \
+                      'for this request'
+          return
+        end
+
+        identity_provider = auth_scheme.identity_provider(@identity_providers)
+        unless identity_provider
+          failures << "Auth scheme #{scheme_id} did not have an " \
+                      'identity resolver configured'
+          return
+        end
+
+        identity_properties = auth_option.identity_properties
+        identity = identity_provider.identity(identity_properties)
+
+        ResolvedAuth.new(
+          scheme_id: scheme_id,
+          identity: identity,
+          identity_properties: auth_option.identity_properties,
+          signer: auth_scheme.signer,
+          signer_properties: auth_option.signer_properties
+        )
+      end
+    end
+  end
+end

data/lib/hearth/middleware/build.rb

@@ -3,8 +3,9 @@
 module Hearth
   module Middleware
     # A middleware that builds a request object.
-    # @api private
     class Build
+      include Middleware::Logging
+
       # @param [Class] app The next middleware in the stack.
       # @param [Class] builder A builder object responsible for building the
       #  request. It must respond to #build and take the request and input as
@@ -18,7 +19,37 @@ module Hearth
       # @param context
       # @return [Output]
       def call(input, context)
+        interceptor_error = Interceptors.invoke(
+          hook: Interceptor::MODIFY_BEFORE_SERIALIZATION,
+          input: input,
+          context: context,
+          output: nil,
+          aggregate_errors: false
+        )
+        return Hearth::Output.new(error: interceptor_error) if interceptor_error
+
+        interceptor_error = Interceptors.invoke(
+          hook: Interceptor::READ_BEFORE_SERIALIZATION,
+          input: input,
+          context: context,
+          output: nil,
+          aggregate_errors: false
+        )
+        return Hearth::Output.new(error: interceptor_error) if interceptor_error
+
+        log_debug(context, "Building request with: #{input}")
         @builder.build(context.request, input: input)
+        log_debug(context, "Built request: #{context.request.inspect}")
+
+        interceptor_error = Interceptors.invoke(
+          hook: Interceptor::READ_AFTER_SERIALIZATION,
+          input: input,
+          context: context,
+          output: nil,
+          aggregate_errors: false
+        )
+        return Hearth::Output.new(error: interceptor_error) if interceptor_error
+
         @app.call(input, context)
       end
     end

data/lib/hearth/middleware/endpoint.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+# in Hearth middleware
+module Hearth
+  module Middleware
+    # Resolves endpoints from endpoint parameters and modifies
+    # the request with resolved endpoint, headers and auth schemes.
+    class Endpoint
+      include Middleware::Logging
+
+      # @param [Class] app The next middleware in the stack.
+      # @param [#resolve(endpoint_params)] endpoint_resolver An object
+      #   that responds to a `resolve(endpoint_params)` method
+      #   where `endpoint_params` is a service specific struct.
+      #   The method must return an {Hearth::Endpoints::Endpoint} object.
+      # @param [#build(config, input, context)] param_builder An object that
+      #   responds to a `build(config, input, context)` method and returns
+      #   an endpoint_params object.
+      def initialize(
+        app, endpoint_resolver:, param_builder:, **kwargs
+      )
+        @app = app
+        @param_builder = param_builder
+        @endpoint_resolver = endpoint_resolver
+        @config = kwargs
+      end
+
+      def call(input, context)
+        params = @param_builder.build(@config, input, context)
+        log_debug(context, "Endpoint params: #{params}")
+        endpoint = @endpoint_resolver.resolve(params)
+        log_debug(context, "Resolved endpoint: #{endpoint}")
+        update_request(context, endpoint)
+        log_debug(context, "Updated request: #{context.request}")
+        update_auth_properties(context, endpoint.auth_schemes)
+        log_debug(context, "Updated auth properties: #{context.auth}")
+
+        @app.call(input, context)
+      end
+
+      private
+
+      # apply the resolved endpoint to the request
+      def update_request(context, endpoint)
+        context.request.uri = merge_endpoints(
+          URI(endpoint.uri), context.request.uri
+        )
+        endpoint.headers.each do |key, val|
+          context.request.headers[key] = val
+        end
+      end
+
+      # merge the path and query parameters from serialization
+      # URIs from endpoint resolution MUST contain port and hostname
+      # and MAY contain port and base path.
+      def merge_endpoints(resolved_uri, request_uri)
+        merged = URI(resolved_uri)
+        merged.path = resolved_uri.path + request_uri.path
+        merged.query = request_uri.query
+        merged
+      end
+
+      # merge properties from the endpoint resolved auth schemes onto
+      # the auth scheme resolved by the auth resolver.
+      def update_auth_properties(context, auth_schemes)
+        context[:endpoint_auth_schemes] = auth_schemes
+        return unless context.auth
+
+        matching = auth_schemes.find do |a|
+          context.auth.scheme_id == a.scheme_id
+        end
+
+        return unless matching
+
+        context.auth.signer_properties.merge!(matching.properties)
+      end
+    end
+  end
+end

data/lib/hearth/middleware/host_prefix.rb

@@ -3,8 +3,9 @@
 module Hearth
   module Middleware
     # A middleware that prefixes the host.
-    # @api private
     class HostPrefix
+      include Middleware::Logging
+
       # @param [Class] app The next middleware in the stack.
       # @param [Boolean] disable_host_prefix If true, this option will not
       #  modify the host url.
@@ -21,25 +22,27 @@ module Hearth
       # @param context
       # @return [Output]
       def call(input, context)
-        unless @disable_host_prefix
-          prefix = apply_labels(@host_prefix, input)
-          context.request.prefix_host(prefix)
-        end
+        prefix_host(input, context) unless @disable_host_prefix
         @app.call(input, context)
       end
 
       private
 
+      def prefix_host(input, context)
+        log_debug(context, "Prefixing host with #{@host_prefix}")
+        prefix = apply_labels(@host_prefix, input)
+        context.request.prefix_host(prefix)
+        log_debug(context, "Prefixed host: #{context.request.uri.host}")
+      end
+
       def apply_labels(host_prefix, input)
-        host_prefix.gsub(/\{.+?\}/) do |host_label|
+        host_prefix.gsub(/\{.+?}/) do |host_label|
           key = host_label.delete('{}')
           value = input[key.to_sym]
-
           if value.nil? || value.empty?
             raise ArgumentError,
                   "Host label #{key} cannot be nil or empty."
           end
-
           value
         end
       end

data/lib/hearth/middleware/initialize.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Hearth
+  module Middleware
+    # A middleware used to initialize the request, called first in the stack
+    class Initialize
+      include Middleware::Logging
+
+      # @param [Class] app The next middleware in the stack.
+      def initialize(app)
+        @app = app
+      end
+
+      # @param input
+      # @param context
+      # @return [Output]
+      def call(input, context)
+        interceptor_error = Interceptors.invoke(
+          hook: Interceptor::READ_BEFORE_EXECUTION,
+          input: input,
+          context: context,
+          output: nil,
+          aggregate_errors: true
+        )
+
+        output =
+          if interceptor_error
+            Hearth::Output.new(error: interceptor_error)
+          else
+            log_debug(context, "Initializing request with #{input}")
+            @app.call(input, context)
+          end
+        log_debug(context, 'Finished request')
+
+        interceptor_error = Interceptors.invoke(
+          hook: Interceptor::MODIFY_BEFORE_COMPLETION,
+          input: input,
+          context: context,
+          output: output,
+          aggregate_errors: false
+        )
+        output.error = interceptor_error if interceptor_error
+
+        interceptor_error = Interceptors.invoke(
+          hook: Interceptor::READ_AFTER_EXECUTION,
+          input: input,
+          context: context,
+          output: output,
+          aggregate_errors: true
+        )
+        output.error = interceptor_error if interceptor_error
+
+        output
+      end
+    end
+  end
+end

data/lib/hearth/middleware/parse.rb

@@ -3,8 +3,9 @@
 module Hearth
   module Middleware
     # A middleware that parses a response object.
-    # @api private
     class Parse
+      include Middleware::Logging
+
       # @param [Class] app The next middleware in the stack.
       # @param [Class] error_parser A parser object responsible for parsing the
       #  response if there is an error. It must respond to #parse and take the
@@ -23,19 +24,56 @@ module Hearth
       # @return [Output]
       def call(input, context)
         output = @app.call(input, context)
-        parse_error(context.response, output) unless output.error
-        parse_data(context.response, output) unless output.error
+
+        interceptor_error = Interceptors.invoke(
+          hook: Interceptor::MODIFY_BEFORE_DESERIALIZATION,
+          input: input,
+          context: context,
+          output: output,
+          aggregate_errors: false
+        )
+        if interceptor_error
+          output.error = interceptor_error
+          return output
+        end
+
+        interceptor_error = Interceptors.invoke(
+          hook: Interceptor::READ_BEFORE_DESERIALIZATION,
+          input: input,
+          context: context,
+          output: output,
+          aggregate_errors: false
+        )
+        if interceptor_error
+          output.error = interceptor_error
+          return output
+        end
+
+        parse_error(context, output) unless output.error
+        parse_data(context, output) unless output.error
+
+        interceptor_error = Interceptors.invoke(
+          hook: Interceptor::READ_AFTER_DESERIALIZATION,
+          input: input,
+          context: context,
+          output: output,
+          aggregate_errors: false
+        )
+        output.error = interceptor_error if interceptor_error
+
         output
       end
 
       private
 
-      def parse_error(response, output)
-        output.error = @error_parser.parse(response)
+      def parse_error(context, output)
+        output.error = @error_parser.parse(context.response, output.metadata)
+        log_debug(context, "Parsed error: #{output.error}") if output.error
       end
 
-      def parse_data(response, output)
-        output.data = @data_parser.parse(response)
+      def parse_data(context, output)
+        output.data = @data_parser.parse(context.response)
+        log_debug(context, "Parsed data: #{output.data}") if output.data
       end
     end
   end