alchemrest 3.1.0

data/lib/alchemrest/data/capture_configuration.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Alchemrest
+  class Data
+    # This class has two purposes. First it provides the DSL that allows developers to mark fields on a
+    # Alchemrest::Data class as safe or omitted. Second, it walks the entire object graph of nested
+    # objects to build up full path definitions for all the safe an omitted fields defined on child
+    # objects as well.
+    #
+    # @example Using `Alchemrest::Data::CaptureConfiguration` to delete define some safe and omitted fields
+    # CaptureConfiguration.new(BankApi::Data::User) do
+    #  safe :name
+    #  omitted :age
+    # end
+    #
+    # The attribute `path_to_payload` allows us to deal with situations where the domain data defined
+    # by the host class is nested inside a larger payload. For example `{ data: { user: { user data } } }`
+    class CaptureConfiguration
+      attr_reader :safe_keys, :omitted_keys, :path_to_payload
+
+      def initialize(host_class:, path_to_payload: nil, omitted_keys: [], safe_keys: [], &block)
+        raise ArgumentError, "Must be a sub class of Alchemrest::Data" unless host_class < Alchemrest::Data
+
+        @host = host_class
+        @path_to_payload = path_to_payload
+        @safe_keys = safe_keys
+        @omitted_keys = omitted_keys
+        instance_eval(&block) unless block.nil?
+      end
+
+      def with_path_to_payload(path_to_payload)
+        self.class.new(
+          host_class: @host,
+          path_to_payload:,
+          safe_keys:,
+          omitted_keys:,
+        )
+      end
+
+      def safe_paths
+        paths = @safe_keys.dup
+
+        paths.concat(get_child_paths(:safe_paths))
+        paths.map { |path| prefix_with_path_to_payload_nodes(path) }
+      end
+
+      def omitted_paths
+        paths = @omitted_keys.dup
+
+        paths.concat(get_child_paths(:omitted_paths))
+        paths.map { |path| prefix_with_path_to_payload_nodes(path) }
+      end
+
+      def safe(*keys)
+        @safe_keys = keys
+      end
+
+      def omitted(*keys)
+        @omitted_keys = keys
+      end
+
+      private
+
+      def get_child_paths(type)
+        paths = []
+        @host.graph.sub_graphs.each do |key, child|
+          paths << { key => child.type.capture_configuration.public_send(type) }
+        end
+        paths
+      end
+
+      def prefix_with_path_to_payload_nodes(path)
+        Array(path_to_payload).reverse.reduce(path) { |child, key| { key => child } }
+      end
+    end
+  end
+end

data/lib/alchemrest/data/field.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Alchemrest
+  class Data
+    class Field
+      include Anima.new(:transform, :name, :required)
+
+      def initialize(transform:, name:, required: false)
+        unless transform.is_a?(Morpher::Transform) || transform.is_a?(Data)
+          raise ArgumentError, "transform must be an instance of Morpher::Transform or Alchemrest::Data, not #{transform.class}"
+        end
+        raise ArgumentError, "must provide name" unless name
+        raise ArgumentError, "must provide non-empty name" if name.to_s.strip.empty?
+
+        @transform = transform
+        @name = name.to_s
+        @required = required && !transform.instance_of?(Morpher::Transform::Maybe)
+      end
+
+      def output_type
+        base_type = transform.output_type if transform.respond_to?(:output_type)
+        return unless base_type
+
+        if required
+          base_type
+        else
+          base_type.with(sorbet_type: T.nilable(base_type.sorbet_type))
+        end
+      end
+
+      def constraints
+        output_type&.constraints || []
+      end
+    end
+  end
+end

data/lib/alchemrest/data/graph.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Alchemrest
+  class Data
+    # A simple data structure to hold a graph of all the objects in a schema.
+    class Graph
+      include Anima.new(:type, :sub_graphs, :fields)
+
+      def initialize(type:, sub_graphs: nil, fields: nil)
+        unless type < Data
+          raise ArgumentError, "Graph types must be branching Alchemrest::Data class"
+        end
+        unless sub_graphs.nil? || sub_graph_hash_has_correct_types?(sub_graphs:)
+          raise ArgumentError, "sub_graphs must be a hash of graphs"
+        end
+        unless fields.nil? || fields_hash_has_correct_types?(fields:)
+          raise ArgumentError, "fields must be a hash of fields"
+        end
+
+        @type = type
+        @fields = fields
+        @sub_graphs = sub_graphs
+      end
+
+      def children
+        sub_graphs
+      end
+
+      private
+
+      def sub_graph_hash_has_correct_types?(sub_graphs:)
+        sub_graphs.instance_of?(Hash) && sub_graphs.values.all? { |graph| graph.instance_of?(Graph) }
+      end
+
+      def fields_hash_has_correct_types?(fields:)
+        fields.instance_of?(Hash) && fields.values.all? { |graph| graph.instance_of?(Field) }
+      end
+    end
+  end
+end

data/lib/alchemrest/data/record.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Alchemrest
+  class Data
+    class Record < Module
+      DEFAULTS = {
+        required: Morpher::EMPTY_HASH,
+        optional: Morpher::EMPTY_HASH,
+        allow_additional_properties: true,
+      }.freeze
+
+      include Anima.new(:required, :optional, :allow_additional_properties)
+
+      def self.new(**attributes)
+        super(**DEFAULTS.merge(attributes))
+      end
+
+      # rubocop:disable Metrics/AbcSize
+      def included(host)
+        optional           = optional()
+        optional_transform = transform(optional)
+        required           = required()
+        required_transform = transform(required)
+        additional_properties_allowed = allow_additional_properties
+
+        host.class_eval do
+          include Anima.new(*(required.keys + optional.keys))
+
+          const_set(
+            :TRANSFORM,
+            Transforms::Typed.new(
+              transform: Morpher::Transform::Sequence.new(
+                [
+                  Morpher::Transform::Primitive.new(Hash),
+                  Morpher::Transform::Hash::Symbolize.new,
+                  Transforms::LooseHash.new(
+                    required: required_transform,
+                    optional: optional_transform,
+                    allow_additional_properties: additional_properties_allowed,
+                  ),
+                  Morpher::Transform::Success.new(public_method(:new)),
+                ],
+              ),
+              output_type: Transforms::OutputType.simple(host),
+            ),
+          )
+        end
+      end
+      # rubocop:enable Metrics/AbcSize
+
+      private
+
+      def transform(attributes)
+        attributes.map do |name, transform|
+          Morpher::Transform::Hash::Key.new(name, transform)
+        end
+      end
+    end
+  end
+end

data/lib/alchemrest/data/schema.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module Alchemrest
+  class Data
+    class Schema < Alchemrest::Data::Record
+      def included(host)
+        super
+
+        host.extend(ClassMethods)
+
+        host.const_set(
+          :Collection,
+          Class.new(host) do
+            const_set :TRANSFORM, superclass::TRANSFORM.array
+
+            def self.capture_configuration
+              superclass.capture_configuration
+            end
+          end,
+        )
+
+        # Store the graph as a constant for easy access from other classes
+        host.const_set(:GRAPH, extract_graph(host))
+      end
+
+      private
+
+      def extract_graph(host)
+        Graph.new(
+          type: host,
+          sub_graphs: extract_sub_graphs,
+          fields: extract_fields,
+        )
+      end
+
+      def extract_sub_graphs
+        required.merge(optional)
+          .filter { |_k, v| v.respond_to?(:output_type) && v.output_type.graph }
+          .transform_values { |v| v.output_type.graph }
+      end
+
+      def extract_fields
+        required_fields = required.map { |k, v| [k, Field.new(transform: v, name: k, required: true)] }
+        optional_fields = optional.map { |k, v| [k, Field.new(transform: v, name: k)] }
+        (required_fields + optional_fields).to_h
+      end
+
+      module ClassMethods
+        def capture_configuration
+          @capture_configuration ||= CaptureConfiguration.new(host_class: self)
+        end
+
+        def response_transformer
+          Alchemrest::ResponseTransformers::Morpher.new(self::TRANSFORM)
+        end
+
+        def from_hash(hash)
+          transform_prelude = self::TRANSFORM.call(hash.deep_stringify_keys)
+          if transform_prelude.right?
+            transform_prelude.from_right
+          else
+            raise MorpherTransformError, transform_prelude.from_left
+          end
+        end
+
+        def []
+          self::Collection
+        end
+
+        def graph
+          self::GRAPH
+        end
+
+        def configure_response_capture(&)
+          @capture_configuration = CaptureConfiguration.new(host_class: self, &)
+        end
+      end
+    end
+  end
+end

data/lib/alchemrest/data.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Alchemrest
+  class Data
+    def self.schema
+      include Alchemrest::Data::Schema.new(**(yield Alchemrest::Transforms))
+    end
+  end
+end

data/lib/alchemrest/endpoint_definition.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Alchemrest
+  class EndpointDefinition
+    VALID_HTTP_METHODS = IceNine.deep_freeze(%w(get post put delete head patch options trace).to_set)
+    private_constant(:VALID_HTTP_METHODS)
+
+    include Anima.new(:template, :http_method, :builder_block)
+
+    def initialize(template:, http_method:, builder_block:)
+      super
+      raise ArgumentError, "template must be string" unless template.instance_of?(String)
+
+      raise ArgumentError, "missing template" if template.empty?
+
+      downcased_http_method = http_method.downcase
+      raise ArgumentError, "must provide a valid HTTP method" unless VALID_HTTP_METHODS.include?(downcased_http_method)
+    end
+
+    def url_for(context)
+      build_for(context).url
+    end
+
+    def params_for(context)
+      builder = build_for(context)
+      if builder.params
+        builder.params
+      elsif builder.values || builder.query
+        (builder.values || {}).merge(builder.query || {}).transform_values { |v| CGI.escape(v.to_s) }
+      end
+    end
+
+    private
+
+    def build_for(context)
+      options = UrlBuilder::Options.new
+      if builder_block&.arity&.zero?
+        Alchemrest.deprecator.warn HASH_RETURNING_BLOCK_MESSAGE
+        options.params = context.instance_exec(&builder_block)
+      elsif builder_block
+        context.instance_exec(options, &builder_block)
+      end
+
+      options.create_builder(template:)
+    end
+  end
+end

data/lib/alchemrest/error.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+module Alchemrest
+  class Error < StandardError
+    def deconstruct
+      [to_s]
+    end
+
+    def deconstruct_keys(_keys)
+      { error: to_s }
+    end
+  end
+
+  class ResponseError < Error
+    attr_reader :response
+
+    def initialize(response)
+      super
+      @response = response
+    end
+
+    def to_s
+      method = response.env.method
+      url = response.env.url
+      [
+        "HTTP #{response.status} for #{method.upcase} #{url}",
+        response.error_details.to_s,
+      ].compact.join(" - ")
+    end
+
+    def deconstruct
+      [response.status, response.error_details]
+    end
+
+    def deconstruct_keys(_keys)
+      { status: response.status, error: response.error_details }
+    end
+  end
+
+  class ServerError < ResponseError
+    attr_reader :response, :cause
+
+    def initialize(response, cause = nil)
+      @response = response
+      @cause = cause
+      super(response)
+    end
+
+    def to_s
+      if response.circuit_open?
+        "CIRCUIT OPEN"
+      elsif response.timeout?
+        "#{response.status} timeout"
+      else
+        error_message
+      end
+    end
+
+    private
+
+    def error_message
+      method = response.env.method
+      url = response.env.url
+      [
+        "HTTP #{response.status} for #{method.upcase} #{url}",
+        response.error_details.to_s,
+        cause,
+      ].compact.join(" - ")
+    end
+  end
+
+  class ClientError < ResponseError; end
+
+  class AuthError < ClientError; end
+
+  class NotFoundError < ClientError; end
+
+  class UndefinedClientError < Error; end
+
+  class RequestFailedError < Error; end
+
+  class TimeoutError < RequestFailedError; end
+
+  class TransformError < Error; end
+
+  class ResultRescued < Error; end
+
+  class CircuitOpenError < Error; end
+
+  class MorpherTransformError < Error
+    attr_reader :error
+
+    def initialize(error)
+      @error = error
+      super()
+    end
+
+    def to_s
+      "Response does not match expected schema - #{error.compact_message}"
+    end
+  end
+
+  class ResponsePipelineError < Error; end
+
+  class InvalidConfigurationError < Error; end
+
+  class ConfigurationNotReadyError < Error; end
+
+  class KillSwitchEnabledError < Error; end
+
+  class NoRegisteredTransformError < Error
+    def initialize(from:, to:)
+      super("No registered transform for #{from.output_type_name} -> #{to}")
+    end
+  end
+
+  class NoTransformOptionForNameError < Error
+    def initialize(from:, to:, name:, options:)
+      super("No transform named #{name} for #{from.output_type_name} -> #{to}. Available options: #{options.keys.join(', ')}")
+    end
+  end
+end

data/lib/alchemrest/factory_bot.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Alchemrest
+  module FactoryBot
+    def self.enable!
+      ::FactoryBot.register_strategy(:alchemrest_record_for, Alchemrest::FactoryBot::AlchemrestStrategy)
+      ::FactoryBot.register_strategy(:alchemrest_hash_for, Alchemrest::FactoryBot::HashStrategy)
+
+      ::FactoryBot::Syntax::Default::DSL.class_eval do
+        include Alchemrest::FactoryBot::Mixins
+      end
+    end
+
+    class OmitKey
+      include Singleton
+    end
+
+    module Mixins
+      def alchemrest_factory(name, options = {}, &block)
+        raise ArgumentError, "You must specify a class" unless options[:class]
+        raise ArgumentError, "You must specify a block" unless block
+
+        factory(name, options) do
+          skip_create
+
+          initialize_with do
+            provided_attributes = attributes.reject { |_, v| v.is_a?(Alchemrest::FactoryBot::OmitKey) }
+            options[:class].constantize.from_hash(provided_attributes)
+          end
+
+          instance_eval(&block)
+        end
+      end
+    end
+
+    class AlchemrestStrategy
+      def association(runner)
+        runner.run(:alchemrest_hash_for)
+      end
+
+      def result(evaluation)
+        evaluation.object
+      end
+
+      def to_sym
+        :alchemrest_record_for
+      end
+    end
+
+    class HashStrategy
+      def association(runner)
+        runner.run(:alchemrest_hash_for)
+      end
+
+      def result(evaluation)
+        evaluation.hash.reject { |_, v| v.is_a?(Alchemrest::FactoryBot::OmitKey) }
+      end
+
+      def to_sym
+        :alchemrest_hash_for
+      end
+    end
+  end
+end

data/lib/alchemrest/faraday_middleware/external_api_instrumentation.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Alchemrest
+  module FaradayMiddleware
+    class ExternalApiInstrumentation < Faraday::Middleware
+      attr_reader :external_service
+
+      def initialize(app, options = {})
+        super(app)
+        @external_service = options.fetch(:external_service)
+      end
+
+      def call(env)
+        ::ActiveSupport::Notifications.instrument(name, env: env, external_service: external_service) do
+          @app.call(env)
+        end
+      end
+
+      def name
+        "#{external_service}_api_request"
+      end
+    end
+  end
+end

data/lib/alchemrest/faraday_middleware/json_parser.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Alchemrest
+  module FaradayMiddleware
+    class JsonParser < Faraday::Middleware
+      DEFAULT_RESPONSE = '{}'
+
+      def on_complete(env)
+        # stash the body for debugging
+        env[:raw_body] = env.body
+
+        env.body = if env.parse_body?
+                     parse_body(env.body)
+                   else
+                     {}
+                   end
+      rescue MultiJson::ParseError
+        env.body = {}
+      end
+
+      def parse_body(raw_body)
+        MultiJson.load(parseable_body(raw_body))
+      end
+
+      def parseable_body(raw_body)
+        raw_body.presence || DEFAULT_RESPONSE
+      end
+    end
+  end
+end

data/lib/alchemrest/faraday_middleware/kill_switch.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Alchemrest
+  module FaradayMiddleware
+    class KillSwitch < Faraday::Middleware
+      attr_reader :service_name
+
+      def initialize(app, options = {})
+        @service_name = options.fetch(:service_name)
+        super(app)
+      end
+
+      def call(env)
+        kill_switch = Alchemrest::KillSwitch.new(service_name:)
+
+        raise KillSwitchEnabledError if kill_switch.active?
+
+        app.call(env)
+      end
+    end
+  end
+end

data/lib/alchemrest/faraday_middleware/underscore_response.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Alchemrest
+  module FaradayMiddleware
+    class UnderScoreResponse < Faraday::Middleware
+      def on_complete(env)
+        env.body = deep_transform_keys!(env.body)
+      end
+
+      private
+
+      def deep_transform_keys!(object)
+        case object
+          when Array
+            object.each { |item| deep_transform_keys!(item) }
+          when Hash
+            object.deep_transform_keys! { |k| k.to_s.underscore }
+          else
+            object
+        end
+      end
+    end
+  end
+end