scorpio 0.2.3 → 0.3.0

data/lib/scorpio/openapi/document.rb

@@ -0,0 +1,167 @@
+module Scorpio
+  module OpenAPI
+    module Document
+      class << self
+        def from_instance(instance)
+          if instance.is_a?(Hash)
+            instance = JSI::JSON::Node.new_doc(instance)
+          end
+          if instance.is_a?(JSI::JSON::Node)
+            if instance['swagger'] =~ /\A2(\.|\z)/
+              instance = Scorpio::OpenAPI::V2::Document.new(instance)
+            elsif instance['openapi'] =~ /\A3(\.|\z)/
+              instance = Scorpio::OpenAPI::V3::Document.new(instance)
+            else
+              raise(ArgumentError, "instance does not look like a recognized openapi document")
+            end
+          end
+          if instance.is_a?(Scorpio::OpenAPI::Document)
+            instance
+          elsif instance.is_a?(JSI::Base)
+            raise(TypeError, "instance is unexpected JSI type: #{instance.class.inspect}")
+          elsif instance.respond_to?(:to_hash)
+            from_instance(instance.to_hash)
+          else
+            raise(TypeError, "instance does not look like a hash (json object)")
+          end
+        end
+      end
+
+      module Configurables
+        attr_writer :request_headers
+        def request_headers
+          return @request_headers if instance_variable_defined?(:@request_headers)
+          {}.freeze
+        end
+
+        attr_writer :user_agent
+        def user_agent
+          return @user_agent if instance_variable_defined?(:@user_agent)
+          "Scorpio/#{Scorpio::VERSION} (https://github.com/notEthan/scorpio) Faraday/#{Faraday::VERSION} Ruby/#{RUBY_VERSION}"
+        end
+
+        attr_writer :faraday_builder
+        def faraday_builder
+          return @faraday_builder if instance_variable_defined?(:@faraday_builder)
+          -> (_) { }
+        end
+
+        attr_writer :faraday_adapter
+        def faraday_adapter
+          return @faraday_adapter if instance_variable_defined?(:@faraday_adapter)
+          [Faraday.default_adapter]
+        end
+
+        attr_writer :logger
+        def logger
+          return @logger if instance_variable_defined?(:@logger)
+          (Object.const_defined?(:Rails) && ::Rails.respond_to?(:logger) ? ::Rails.logger : nil)
+        end
+      end
+      include Configurables
+
+      def v2?
+        is_a?(V2::Document)
+      end
+
+      def v3?
+        is_a?(V3::Document)
+      end
+
+      def operations
+        return @operations if instance_variable_defined?(:@operations)
+        @operations = OperationsScope.new(self)
+      end
+    end
+
+    module V3
+      raise(Bug) unless const_defined?(:Document)
+      class Document
+        module Configurables
+          def scheme
+            nil
+          end
+          attr_writer :server
+          def server
+            return @server if instance_variable_defined?(:@server)
+            if servers.respond_to?(:to_ary) && servers.size == 1
+              servers.first
+            else
+              nil
+            end
+          end
+          attr_writer :server_variables
+          def server_variables
+            return @server_variables if instance_variable_defined?(:@server_variables)
+            {}.freeze
+          end
+          attr_writer :base_url
+          def base_url(scheme: nil, server: self.server, server_variables: self.server_variables)
+            return @base_url if instance_variable_defined?(:@base_url)
+            if server
+              server.expanded_url(server_variables)
+            end
+          end
+
+          attr_writer :request_media_type
+          def request_media_type
+            return @request_media_type if instance_variable_defined?(:@request_media_type)
+            nil
+          end
+        end
+        include Configurables
+      end
+    end
+
+    module V2
+      raise(Bug) unless const_defined?(:Document)
+      class Document
+        module Configurables
+          attr_writer :scheme
+          def scheme
+            return @scheme if instance_variable_defined?(:@scheme)
+            if schemes.nil?
+              'https'
+            elsif schemes.respond_to?(:to_ary)
+              # prefer https, then http, then anything else since we probably don't support.
+              schemes.sort_by { |s| ['https', 'http'].index(s) || (1.0 / 0) }.first
+            end
+          end
+
+          def server
+            nil
+          end
+          def server_variables
+            nil
+          end
+
+          attr_writer :base_url
+          # the base url to which paths are appended.
+          # by default this looks at the openapi document's schemes, picking https or http first.
+          # it looks at the openapi_document's host and basePath.
+          def base_url(scheme: self.scheme, server: nil, server_variables: nil)
+            return @base_url if instance_variable_defined?(:@base_url)
+            if host && scheme
+              Addressable::URI.new(
+                scheme: scheme,
+                host: host,
+                path: basePath,
+              ).to_s
+            end
+          end
+
+          attr_writer :request_media_type
+          def request_media_type
+            return @request_media_type if instance_variable_defined?(:@request_media_type)
+            if consumes.respond_to?(:to_ary)
+              Request.best_media_type(consumes)
+            else
+              nil
+            end
+          end
+        end
+        include Configurables
+      end
+    end
+  end
+end

data/lib/scorpio/openapi/operation.rb

@@ -0,0 +1,208 @@
+module Scorpio
+  module OpenAPI
+    module Operation
+      module Configurables
+        attr_writer :base_url
+        def base_url(scheme: self.scheme, server: self.server, server_variables: self.server_variables)
+          return @base_url if instance_variable_defined?(:@base_url)
+          openapi_document.base_url(scheme: scheme, server: server, server_variables: server_variables)
+        end
+
+        attr_writer :request_headers
+        def request_headers
+          return @request_headers if instance_variable_defined?(:@request_headers)
+          openapi_document.request_headers
+        end
+
+        attr_writer :user_agent
+        def user_agent
+          return @user_agent if instance_variable_defined?(:@user_agent)
+          openapi_document.user_agent
+        end
+
+        attr_writer :faraday_builder
+        def faraday_builder
+          return @faraday_builder if instance_variable_defined?(:@faraday_builder)
+          openapi_document.faraday_builder
+        end
+
+        attr_writer :faraday_adapter
+        def faraday_adapter
+          return @faraday_adapter if instance_variable_defined?(:@faraday_adapter)
+          openapi_document.faraday_adapter
+        end
+
+        attr_writer :logger
+        def logger
+          return @logger if instance_variable_defined?(:@logger)
+          openapi_document.logger
+        end
+      end
+      include Configurables
+
+      def openapi_document
+        parents.detect { |p| p.is_a?(Scorpio::OpenAPI::Document) }
+      end
+
+      def path
+        return @path if instance_variable_defined?(:@path)
+        @path = begin
+          parent_is_pathitem = parent.is_a?(Scorpio::OpenAPI::V2::PathItem) || parent.is_a?(Scorpio::OpenAPI::V3::PathItem)
+          parent_parent_is_paths = parent.parent.is_a?(Scorpio::OpenAPI::V2::Paths) || parent.parent.is_a?(Scorpio::OpenAPI::V3::Paths)
+          if parent_is_pathitem && parent_parent_is_paths
+            parent.instance.path.last
+          end
+        end
+      end
+
+      def http_method
+        return @http_method if instance_variable_defined?(:@http_method)
+        @http_method = begin
+          parent_is_pathitem = parent.is_a?(Scorpio::OpenAPI::V2::PathItem) || parent.is_a?(Scorpio::OpenAPI::V3::PathItem)
+          if parent_is_pathitem
+            instance.path.last
+          end
+        end
+      end
+
+      def build_request(*a, &b)
+        request = Scorpio::Request.new(self, *a, &b)
+      end
+
+      def run_ur(*a, &b)
+        build_request(*a, &b).run_ur
+      end
+
+      def run(*a, &b)
+        build_request(*a, &b).run
+      end
+    end
+
+    module V3
+      raise(Bug) unless const_defined?(:Operation)
+      class Operation
+        module Configurables
+          def scheme
+            nil
+          end
+
+          attr_writer :server
+          def server
+            return @server if instance_variable_defined?(:@server)
+            openapi_document.server
+          end
+
+          attr_writer :server_variables
+          def server_variables
+            return @server_variables if instance_variable_defined?(:@server_variables)
+            openapi_document.server_variables
+          end
+
+          attr_writer :request_media_type
+          def request_media_type
+            return @request_media_type if instance_variable_defined?(:@request_media_type)
+            if requestBody && requestBody['content']
+              Request.best_media_type(requestBody['content'].keys)
+            else
+              openapi_document.request_media_type
+            end
+          end
+        end
+        include Configurables
+
+        def request_schema(media_type: self.request_media_type)
+          # TODO typechecking on requestBody & children
+          requestBody &&
+            requestBody['content'] &&
+            requestBody['content'][media_type] &&
+            requestBody['content'][media_type]['schema'] &&
+            requestBody['content'][media_type]['schema'].deref
+        end
+
+        def request_schemas
+          if requestBody && requestBody['content']
+            # oamt is for Scorpio::OpenAPI::V3::MediaType
+            requestBody['content'].values.map { |oamt| oamt['schema'] }.compact.map(&:deref)
+          end
+        end
+
+        # @return JSI::Schema
+        def response_schema(status: , media_type: )
+          status = status.to_s if status.is_a?(Numeric)
+          if self.responses
+            # Scorpio::OpenAPI::V3::Response
+            _, oa_response = self.responses.detect { |k, v| k.to_s == status }
+            oa_response ||= self.responses['default']
+          end
+          oa_media_types = oa_response ? oa_response['content'] : nil # Scorpio::OpenAPI::V3::MediaTypes
+          oa_media_type = oa_media_types ? oa_media_types[media_type] : nil # Scorpio::OpenAPI::V3::MediaType
+          oa_schema = oa_media_type ? oa_media_type['schema'] : nil # Scorpio::OpenAPI::V3::Schema
+          oa_schema ? JSI::Schema.new(oa_schema) : nil
+        end
+      end
+    end
+    module V2
+      raise(Bug) unless const_defined?(:Operation)
+      class Operation
+        module Configurables
+          attr_writer :scheme
+          def scheme
+            return @scheme if instance_variable_defined?(:@scheme)
+            openapi_document.scheme
+          end
+          def server
+            nil
+          end
+          def server_variables
+            nil
+          end
+
+          attr_writer :request_media_type
+          def request_media_type
+            return @request_media_type if instance_variable_defined?(:@request_media_type)
+            if key?('consumes')
+              Request.best_media_type(consumes)
+            else
+              openapi_document.request_media_type
+            end
+          end
+        end
+        include Configurables
+
+        # there should only be one body parameter; this returns it
+        def body_parameter
+          body_parameters = (parameters || []).select { |parameter| parameter['in'] == 'body' }
+          if body_parameters.size == 0
+            nil
+          elsif body_parameters.size == 1
+            body_parameters.first
+          else
+            raise(Bug) # TODO BLAME
+          end
+        end
+
+        def request_schema(media_type: nil)
+          if body_parameter && body_parameter['schema']
+            JSI::Schema.new(body_parameter['schema'])
+          end
+        end
+
+        def request_schemas
+          [request_schema]
+        end
+
+        # @return JSI::Schema
+        def response_schema(status: , media_type: nil)
+          status = status.to_s if status.is_a?(Numeric)
+          if self.responses
+            # Scorpio::OpenAPI::V2::Response
+            _, oa_response = self.responses.detect { |k, v| k.to_s == status }
+            oa_response ||= self.responses['default']
+          end
+          oa_response_schema = oa_response ? oa_response['schema'] : nil # Scorpio::OpenAPI::V2::Schema
+          oa_response_schema ? JSI::Schema.new(oa_response_schema) : nil
+        end
+      end
+    end
+  end
+end

data/lib/scorpio/openapi/operations_scope.rb

@@ -0,0 +1,29 @@
+module Scorpio
+  module OpenAPI
+    class OperationsScope
+      include JSI::Memoize
+
+      def initialize(openapi_document)
+        @openapi_document = openapi_document
+      end
+      attr_reader :openapi_document
+
+      def each
+        openapi_document.paths.each do |path, path_item|
+          path_item.each do |http_method, operation|
+            if operation.is_a?(Scorpio::OpenAPI::Operation)
+              yield operation
+            end
+          end
+        end
+      end
+      include Enumerable
+
+      def [](operationId_)
+        memoize(:[], operationId_) do |operationId|
+          detect { |operation| operation.operationId == operationId }
+        end
+      end
+    end
+  end
+end

data/lib/scorpio/openapi/v3/server.rb

@@ -0,0 +1,32 @@
+module Scorpio
+  module OpenAPI
+    module V3
+      raise(Bug) unless const_defined?(:Server)
+      class Server
+        def expanded_url(given_server_variables)
+          if variables
+            server_variables = (given_server_variables.keys | variables.keys).map do |key|
+              server_variable = variables[key]
+              if server_variable && server_variable.enum
+                unless server_variable.enum.include?(given_server_variables[key])
+                  warn # TODO BLAME
+                end
+              end
+              if given_server_variables.key?(key)
+                {key => given_server_variables[key]}
+              elsif server_variable.key?('default')
+                {key => server_variable.default}
+              else
+                {}
+              end
+            end.inject({}, &:update)
+          else
+            server_variables = given_server_variables
+          end
+          template = Addressable::Template.new(url)
+          template.expand(server_variables)
+        end
+      end
+    end
+  end
+end

data/lib/scorpio/request.rb

@@ -0,0 +1,227 @@
+module Scorpio
+  class Request
+    SUPPORTED_REQUEST_MEDIA_TYPES = ['application/json', 'application/x-www-form-urlencoded']
+    def self.best_media_type(media_types)
+      if media_types.size == 1
+        media_types.first
+      else
+        SUPPORTED_REQUEST_MEDIA_TYPES.detect { |mt| media_types.include?(mt) }
+      end
+    end
+
+    module Configurables
+      attr_writer :path_params
+      def path_params
+        return @path_params if instance_variable_defined?(:@path_params)
+        {}.freeze
+      end
+
+      attr_writer :query_params
+      def query_params
+        return @query_params if instance_variable_defined?(:@query_params)
+        nil
+      end
+
+      attr_writer :scheme
+      def scheme
+        return @scheme if instance_variable_defined?(:@scheme)
+        operation.scheme
+      end
+
+      attr_writer :server
+      def server
+        return @server if instance_variable_defined?(:@server)
+        operation.server
+      end
+
+      attr_writer :server_variables
+      def server_variables
+        return @server_variables if instance_variable_defined?(:@server_variables)
+        operation.server_variables
+      end
+
+      attr_writer :base_url
+      def base_url
+        return @base_url if instance_variable_defined?(:@base_url)
+        operation.base_url(scheme: scheme, server: server, server_variables: server_variables)
+      end
+
+      attr_writer :body
+      def body
+        return @body if instance_variable_defined?(:@body)
+        if instance_variable_defined?(:@body_object)
+          # TODO handle media types like `application/schema-instance+json`
+          if media_type == 'application/json'
+            JSON.pretty_generate(JSI::Typelike.as_json(body_object))
+          elsif media_type == "application/x-www-form-urlencoded"
+            URI.encode_www_form(body_object)
+
+          # NOTE: the supported media types above should correspond to Request::SUPPORTED_REQUEST_MEDIA_TYPES
+
+          else
+            if body_object.respond_to?(:to_str)
+              body_object
+            else
+              raise(NotImplementedError)
+            end
+          end
+        else
+          nil
+        end
+      end
+
+      attr_accessor :body_object
+
+      attr_writer :headers
+      def headers
+        return @headers if instance_variable_defined?(:@headers)
+        operation.request_headers
+      end
+
+      attr_writer :media_type
+      def media_type
+        return @media_type if instance_variable_defined?(:@media_type)
+        content_type_header ? content_type_attrs.media_type : operation.request_media_type
+      end
+
+      attr_writer :user_agent
+      def user_agent
+        return @user_agent if instance_variable_defined?(:@user_agent)
+        operation.user_agent
+      end
+
+      attr_writer :faraday_builder
+      def faraday_builder
+        return @faraday_builder if instance_variable_defined?(:@faraday_builder)
+        operation.faraday_builder
+      end
+
+      attr_writer :faraday_adapter
+      def faraday_adapter
+        return @faraday_adapter if instance_variable_defined?(:@faraday_adapter)
+        operation.faraday_adapter
+      end
+
+      attr_writer :logger
+      def logger
+        return @logger if instance_variable_defined?(:@logger)
+        operation.logger
+      end
+    end
+    include Configurables
+
+    def initialize(operation, **configuration, &b)
+      configuration.each do |k, v|
+        settername = "#{k}="
+        if Configurables.public_method_defined?(settername)
+          Configurables.instance_method(settername).bind(self).call(v)
+        else
+          raise(ArgumentError, "unsupported configuration value passed: #{k.inspect} => #{v.inspect}")
+        end
+      end
+
+      @operation = operation
+      if block_given?
+        yield self
+      end
+    end
+
+    attr_reader :operation
+
+    def openapi_document
+      operation.openapi_document
+    end
+
+    def http_method
+      operation.http_method.downcase.to_sym
+    end
+
+    def path_template
+      Addressable::Template.new(operation.path)
+    end
+
+    def path
+      missing_variables = path_template.variables - path_params.keys
+      if missing_variables.any?
+        raise(ArgumentError, "path #{operation.path} for operation #{operation.operationId} requires path_params " +
+          "which were missing: #{missing_variables.inspect}")
+      end
+      empty_variables = path_template.variables.select { |v| path_params[v].to_s.empty? }
+      if empty_variables.any?
+        raise(ArgumentError, "path #{operation.path} for operation #{operation.operationId} requires path_params " +
+          "which were empty: #{empty_variables.inspect}")
+      end
+
+      path_template.expand(path_params).tap do |path|
+        if query_params
+          path.query_values = query_params
+        end
+      end
+    end
+
+    def url
+      unless base_url
+        raise(ArgumentError, "no base_url has been specified for request")
+      end
+      # we do not use Addressable::URI#join as the paths should just be concatenated, not resolved.
+      # we use File.join just to deal with consecutive slashes.
+      url = File.join(base_url, path)
+      url = Addressable::URI.parse(url)
+    end
+
+    def content_type_attrs
+      Ur::ContentTypeAttrs.new(content_type)
+    end
+
+    def content_type_header
+      headers.each do |k, v|
+        return v if k =~ /\Acontent[-_]type\z/i
+      end
+      nil
+    end
+
+    def content_type
+      content_type_header || media_type
+    end
+
+    def request_schema(media_type: self.media_type)
+      operation.request_schema(media_type: media_type)
+    end
+
+    def request_schema_class(media_type: self.media_type)
+      JSI.class_for_schema(request_schema(media_type: media_type))
+    end
+
+    def faraday_connection(yield_ur)
+      Faraday.new do |faraday_connection|
+        faraday_builder.call(faraday_connection)
+        ::Ur::Faraday # autoload trigger
+        faraday_connection.response(:yield_ur, ur_class: Scorpio::Ur, logger: self.logger, &yield_ur)
+        faraday_connection.adapter(*faraday_adapter)
+      end
+    end
+
+    def run_ur
+      headers = {}
+      if user_agent
+        headers['User-Agent'] = user_agent
+      end
+      if media_type && !content_type_header
+        headers['Content-Type'] = media_type
+      end
+      if self.headers
+        headers.update(self.headers)
+      end
+      ur = nil
+      faraday_connection(-> (yur) { ur = yur }).run_request(http_method, url, body, headers)
+      ur.scorpio_request = self
+      ur
+    end
+
+    def run
+      ur = run_ur
+      ur.raise_on_http_error
+      ur.response.body_object
+    end
+  end
+end