alchemrest 3.1.0

data/lib/alchemrest/response/pipeline/transform.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Alchemrest
+  class Response
+    class Pipeline
+      # This base class simply ensures that if
+      # a transform returns an alchemrest error that
+      # was created but not raised, then we'll set the
+      # backtrace so it can be traced to the transform
+      # that generated it. Only really relevant for
+      # implementors creating custom transforms.
+      class Transform < Morpher::Transform
+        def failure(error)
+          if error.respond_to?(:backtrace) && error.backtrace.nil?
+            error.set_backtrace(caller)
+          end
+          super
+        end
+
+        def final(value)
+          success(Final.new(value))
+        end
+      end
+    end
+  end
+end

data/lib/alchemrest/response/pipeline/was_successful.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Alchemrest
+  class Response
+    class Pipeline
+      # A transform that checks to see if a response was successful, as defined by `response.success?`.
+      # If the response is successful, it just returns itself. If not it calls `response.error`.
+      # Can be used as the first step in any pipeline's where you want to short circuit execution
+      # if the response has an http error code.
+      class WasSuccessful < Alchemrest::Response::Pipeline::Transform
+        def eql?(other)
+          instance_of?(other.class)
+        end
+
+        def ==(other)
+          instance_of?(other.class)
+        end
+
+        def call(response)
+          if response.success?
+            success(response)
+          else
+            failure(response.error)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/alchemrest/response/pipeline.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Alchemrest
+  class Response
+    # The `Alchemrest::Result::Pipeline` is a class that orchestrates running a sequence of
+    # `Morpher::Transform` instances starting with an `Alchemrest::Response` instance and ending
+    # with an `Alchemrest::Result`. The pipeline is responsible for feeding the output of one
+    # transform into the input of the next when a transform succeeds, and wrapping errors in
+    # an `Alchemrest::Result::Error` when a transform fails. Transform steps must meet the following
+    # criteria
+    # 1. Implement a call method
+    # 2. Return a `Either::Right` prelude if the transform is successful
+    # 3. Return a `Either::Left` prelude that wraps either a `Morpher::Transform::Error` or
+    #    one of our `Alchemrest.rescuable_exceptions if the transform is unsuccessful
+    class Pipeline
+      include Concord::Public.new(:steps)
+
+      def initialize(*steps)
+        super(steps)
+      end
+
+      def call(response)
+        final = steps.reduce(response) do |current, step|
+          either = step.call(current)
+          return build_error_result(either.from_left) if either.left?
+          break either.from_right.value if either.from_right.instance_of?(Final)
+
+          either.from_right
+        end
+
+        Result::Ok(final)
+      end
+
+      def insert_after(step_class, step)
+        index = steps.index { |s| s.instance_of?(step_class) }
+        raise ArgumentError, "Step #{step_class} not found" if index.nil?
+
+        self.class.new(*steps.insert(index + 1, step))
+      end
+
+      def append(step)
+        self.class.new(*steps.append(step))
+      end
+
+      def replace_with(step_class, step)
+        index = steps.index { |s| s.instance_of?(step_class) }
+        raise ArgumentError, "Step #{step_class} not found" if index.nil?
+
+        new_steps = steps.dup
+        new_steps[index] = step
+
+        self.class.new(*new_steps)
+      end
+
+      private
+
+      def build_error_result(error)
+        case error
+          when Morpher::Transform::Error
+            wrapped_error = Alchemrest::MorpherTransformError.new(error)
+            wrapped_error.set_backtrace(caller)
+            Alchemrest::Result::Error(wrapped_error)
+          when *Alchemrest.rescuable_exceptions
+            Alchemrest::Result::Error(error)
+          else
+            raise "Invalid error object #{error}"
+        end
+      end
+    end
+  end
+end

data/lib/alchemrest/response.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require 'delegate'
+require 'memosa'
+
+module Alchemrest
+  class Response < SimpleDelegator
+    extend Memosa
+
+    def data
+      body
+    end
+
+    def to_result
+      if success?
+        Result.Ok(self)
+      else
+        error.set_backtrace(caller)
+        Result.Error(error)
+      end
+    end
+
+    def error_details
+      "Error with HTTP status: #{status}" unless success?
+    end
+
+    def server_error?
+      (500..599).cover?(status)
+    end
+
+    def client_error?
+      (400..499).cover?(status)
+    end
+
+    def auth_error?
+      [401, 403].include?(status)
+    end
+
+    def not_found_error?
+      status == 404
+    end
+
+    def no_content_response?
+      status == 204
+    end
+
+    def request_failed?
+      status >= 500 && status <= 599
+    end
+
+    def timeout?
+      false
+    end
+
+    def circuit_open?
+      false
+    end
+
+    memoize def error
+      if server_error?
+        ServerError.new(self)
+      elsif auth_error?
+        AuthError.new(self)
+      elsif not_found_error?
+        NotFoundError.new(self)
+      elsif client_error?
+        ClientError.new(self)
+      else
+        ResponseError.new(self)
+      end
+    end
+  end
+end

data/lib/alchemrest/response_captured_handler.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Alchemrest
+  class ResponseCapturedHandler
+    LEGACY_ON_RESPONSE_CAPTURED_METHOD_DEFINITION_MESSAGE = <<~MSG
+      Defining Alchemrest.on_response_captured like
+
+      `Alchemrest.on_response_captured { |data, response, request| ... }` is deprecated.
+
+      Going forward, method defintions should take the form
+
+      `Alchemrest.on_response_captured { |identifier:, result:| ... }`
+
+      where identifier is a string that identifies the http method and endpoint the request was made to
+      and result is an `Alchemrest::Result` object that contains the captured response data, or an Error
+      instance.
+    MSG
+
+    include Anima.new(:request, :response)
+
+    def call
+      return unless request.response_capture_enabled
+
+      unless Alchemrest.on_response_captured
+        default_capture_method
+        return
+      end
+
+      case Alchemrest.on_response_captured.arity
+        in 3
+          legacy_capture_handler
+        in 1
+          Alchemrest.on_response_captured.call(identifier:, result: capture_pipeline_result)
+      end
+    end
+
+    private
+
+    def capture_pipeline_result
+      request.capture_transformer.call(response)
+    end
+
+    def identifier
+      request.identifier
+    end
+
+    def legacy_capture_handler
+      Alchemrest.deprecator.warn LEGACY_ON_RESPONSE_CAPTURED_METHOD_DEFINITION_MESSAGE
+      data = case capture_pipeline_result
+               in Result::Ok(value)
+                 value
+               in Result::Error(e)
+                 "Error transforming captured response data: #{e}"
+             end
+
+      Alchemrest.on_response_captured.call(data, response, request)
+    end
+
+    def default_capture_method
+      case capture_pipeline_result
+        in Result::Ok(value: data)
+          Alchemrest.logger.info("Captured Alchemrest response for '#{identifier}': '#{data}'")
+        in Result::Error({error:})
+          Alchemrest.logger.error("Failed to capture Alchemrest response for '#{identifier}': '#{error}'")
+      end
+    end
+  end
+end

data/lib/alchemrest/result/halt.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Alchemrest
+  class Result
+    class Halt < StandardError
+      attr_reader :error
+
+      def initialize(original_error)
+        "Must be an Alchemrest::Result:Error object" unless original_error.is_a? Result::Error
+        @error = original_error
+        super(original_error.to_s)
+      end
+    end
+  end
+end

data/lib/alchemrest/result/try_helpers.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Alchemrest
+  class Result
+    module TryHelpers
+      def self.unwrap(result)
+        case result
+          in Result::Ok(value)
+            value
+          else
+            raise Result::Halt, result
+        end
+      end
+    end
+  end
+end

data/lib/alchemrest/result.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+module Alchemrest
+  class Result
+    # Allow support for sorbet runtime type checking
+    def self.[](*_types)
+      self
+    end
+
+    class Ok < self
+      def initialize(value) # rubocop:disable Lint/MissingSuper
+        self.value = value
+      end
+
+      def ==(other)
+        other.is_a?(Ok) && other.value == value
+      end
+
+      def ok?
+        true
+      end
+
+      def deconstruct
+        [value]
+      end
+
+      def deconstruct_keys(_keys)
+        { value: }
+      end
+    end
+
+    class Error < self
+      def initialize(error) # rubocop:disable Lint/MissingSuper
+        case error
+          when String
+            self.error = Alchemrest::Error.new(error)
+          when *Alchemrest.rescuable_exceptions
+            self.error = error
+          else
+            raise ArgumentError, "Error must be a string or one of the types defined in Alchemrest.rescuable_exceptions"
+        end
+      end
+
+      def ==(other)
+        other.is_a?(Error) && other.error == error
+      end
+
+      def ok?
+        false
+      end
+
+      def deconstruct
+        [error]
+      end
+
+      def deconstruct_keys(_keys)
+        { error: }
+      end
+    end
+
+    def self.Ok(value)
+      Ok.new(value)
+    end
+
+    def self.Error(error)
+      Error.new(error)
+    end
+
+    def self.for
+      block_return_value = yield Alchemrest::Result::TryHelpers
+
+      case block_return_value
+        in Alchemrest::Result => result
+          result
+        else
+          Alchemrest::Result::Ok.new(block_return_value)
+      end
+    rescue Alchemrest::Result::Halt => e
+      e.error
+    end
+
+    def initialize(*)
+      raise 'Cannot create an instance of Alchemrest::Result. Use Alchemrest::Result::Ok or Alchemrest::Result::Error instead.'
+    end
+
+    def transform
+      raise ArgumentError, 'no block given' unless block_given?
+
+      if ok?
+        self.class::Ok(yield value)
+      else
+        self
+      end
+    end
+
+    # The pattern of raising, rescuing, re-raising, rescuing again, and then handling looks
+    # a little weird, but it's necessary to ensure our final result is an Alchemrest::ResultResecued
+    # error where `error.cause` contains the original exception. This way we have information on both
+    # the stack trace where the api error originated, and the stack trace of where we tried to
+    # rescue it.
+    def unwrap_or_rescue
+      raise ArgumentError, 'no error handler given' unless block_given?
+
+      unwrap_or_raise!
+    rescue *Alchemrest.rescuable_exceptions => e
+      begin
+        raise Alchemrest::ResultRescued, "Alchemrest rescued an unexpected result of type #{error.class}", cause: e
+      rescue Alchemrest::ResultRescued => rescued_error
+        Alchemrest.handle_rescued_result(rescued_error)
+        yield
+      end
+    end
+
+    def unwrap_or_raise!
+      raise error unless ok?
+
+      value
+    end
+
+    protected
+
+    attr_reader :value, :error
+
+    private
+
+    attr_writer :value, :error
+  end
+end

data/lib/alchemrest/root.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Alchemrest
+  class Root
+    @@default_params = -> { {} } # rubocop:disable Style/ClassVars
+
+    def self.use_client(client_class)
+      client = client_class.new
+      define_method(:client) { client }
+    end
+
+    def self.request_definitions
+      @request_definitions ||= superclass.respond_to?(:request_definitions) ? superclass.request_definitions.dup : {}
+    end
+
+    def self.define_request(name, request_class, &block) # rubocop:disable Style/ArgumentsForwarding
+      request_definitions[name] = RequestDefinition.new(name, request_class, &block) # rubocop:disable Style/ArgumentsForwarding
+
+      define_method(name) do |params = {}|
+        result = build_request(name, params).execute!
+
+        case result
+          in Alchemrest::Result::Error[error]
+            if self.class.error_handler
+              instance_exec(error, &self.class.error_handler)
+            end
+          else
+            nil
+        end
+
+        result
+      end
+    end
+
+    def self.error_handler
+      if superclass.respond_to?(:error_handler)
+        @error_handler ||= superclass.error_handler
+      end
+    end
+
+    def self.reset_error_handler!
+      @error_handler = nil
+    end
+
+    def self.on_alchemrest_error(&block)
+      @error_handler = block
+    end
+
+    def build_request(name, params = {})
+      request_definition = self.class.request_definitions[name]
+
+      raise "No request definition found for #{name}. Did you call `define_request :#{name} in your root class?" unless request_definition
+
+      request = request_definition.build_request(self, params)
+      client.build_http_request(request)
+    end
+
+    # @abstract Use `.use_client` or override `#client`
+    def client
+      raise Alchemrest::UndefinedClientError, <<~MSG
+        You forgot to specify a client. You can simply use `use_client` like this:
+
+          class #{self.class} < #{self.class.superclass}
+            use_client YourClient
+          end
+
+        Or, you can define your client at the instance level:
+
+          class #{self.class} < #{self.class.superclass}
+            def client
+              YourClient.new
+            end
+          end
+      MSG
+    end
+  end
+end

data/lib/alchemrest/transforms/base_to_type_transform_registry.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Alchemrest
+  module Transforms
+    class BaseToTypeTransformRegistry
+      include AbstractType
+      include Concord.new(:from)
+
+      abstract_method :build_transforms
+
+      def initialize(*args)
+        super
+        @registry_hash = build_internal_registry_hash(build_transforms)
+      end
+
+      def resolve(type)
+        if @registry_hash.key?(type)
+          @registry_hash.fetch(type)
+        else
+          raise NoRegisteredTransformError.new(from:, to: type)
+        end
+      end
+
+      private
+
+      def build_internal_registry_hash(transforms)
+        transforms.to_h do |type, value|
+          new_value = if value.instance_of?(Array)
+                        ToType.new(from:, to: type, use: value)
+                      elsif value.instance_of?(Hash)
+                        ToType::TransformsSelector.new(from, type, value)
+                      elsif value.is_a?(ToType::TransformsSelector)
+                        value
+                      else
+                        raise "Not a valid implementation of `def build_transforms`"
+                      end
+          [type, new_value]
+        end
+      end
+    end
+  end
+end

data/lib/alchemrest/transforms/constrainable.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Alchemrest
+  module Transforms
+    # Calling Constrainable.with_additional_attributes(...) will return a module that
+    # can be included in a `Morpher::Transform` class to allow adding validation constraints
+    # using the `#where` method. We do this in both `ToType` and `FromType`
+    class Constrainable < Anima
+      def initialize(args = {})
+        additional_attributes = args[:additional_attributes]
+        super(*additional_attributes, :constraints)
+      end
+
+      def included(base)
+        base.include(InstanceMethods)
+        super
+      end
+
+      module InstanceMethods
+        def where(constraint_or_description, &block)
+          constraint = if block
+                         Constraint::Block.new(constraint_or_description, &block)
+                       elsif constraint_or_description.is_a?(Constraint)
+                         constraint_or_description
+                       else
+                         raise ArgumentError, "Must provide an instance of Alchemrest::Transform::Constraint"
+                       end
+
+          with(constraints: [*constraints, constraint])
+        end
+
+        private
+
+        def validate_constraints
+          constraints.map { |constraint| WithConstraint.new(constraint) }
+            .inject(Morpher::Transform::Sequence.new([])) { |sequence, transform| sequence.seq(transform) }
+        end
+      end
+    end
+  end
+end

data/lib/alchemrest/transforms/constraint/block.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Alchemrest
+  module Transforms
+    class Constraint
+      class Block < self
+        include Concord.new(:description, :block)
+        public :description
+
+        def initialize(description, &block)
+          raise ArgumentError, "Must include a predicate block" unless block
+
+          super(description, block)
+        end
+
+        def meets_conditions?(input)
+          block.call(input)
+        end
+      end
+    end
+  end
+end

data/lib/alchemrest/transforms/constraint/greater_than.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Alchemrest
+  module Transforms
+    class Constraint
+      class GreaterThan < self
+        include Concord.new(:value)
+
+        def meets_conditions?(input)
+          input > value
+        end
+
+        def description
+          "greater than #{value}"
+        end
+      end
+    end
+  end
+end

data/lib/alchemrest/transforms/constraint/greater_than_or_eq.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Alchemrest
+  module Transforms
+    class Constraint
+      class GreaterThanOrEq < self
+        include Concord.new(:value)
+
+        def meets_conditions?(input)
+          input >= value
+        end
+
+        def description
+          "greater than or equal to #{value}"
+        end
+      end
+    end
+  end
+end

data/lib/alchemrest/transforms/constraint/in_list.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Alchemrest
+  module Transforms
+    class Constraint
+      class InList < self
+        include Concord.new(:list)
+
+        def meets_conditions?(input)
+          list.include?(input)
+        end
+
+        def description
+          "in list #{list}"
+        end
+      end
+    end
+  end
+end

data/lib/alchemrest/transforms/constraint/is_instance_of.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Alchemrest
+  module Transforms
+    class Constraint
+      class IsInstanceOf < self
+        include Concord::Public.new(:klass)
+
+        def meets_conditions?(input)
+          input.instance_of?(klass)
+        end
+
+        def description
+          "is an #{klass}"
+        end
+      end
+    end
+  end
+end