jsapi 2.1.2 → 3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1f68753b0fe40a759d233878a9ca2a96d227ba769d8e1d167255f48e538eb075
-  data.tar.gz: e6ba6a151038cf393c099784ce7b3bd358685de018308e3e437af0d54cfcf438
+  metadata.gz: 0ec240995632c56faf46229f425a0fb65a32da97f6aa0b68ee66327a6a17ca3b
+  data.tar.gz: 7c457efa33d29830814b66dc62ac001d813f042890b7e637e265567198251e01
 SHA512:
-  metadata.gz: ef47ff95a63d481af9b7eb169487ad7e05d6a653a5a6d2bdefb8499802a43531e2d729bce9a74701006b59c66f24241d9a9dae7b2a7e0f95e5788e81cc73dacb
-  data.tar.gz: 9cf392df9e3d8bd4913faa8c3594c3e10399c9600a165e96f8f8ae91c2c240f60e7e77518ac018d5d327d6c3bde4aa9e9119babda7ef0959e285a0c5365741ce
+  metadata.gz: 9a7fc689d67fe755b7351a06730ff59b65212a5764e4eeab2d2b03748954e6c635a371bbdab0615542d07e0226c96c81453e0f246f99ef007f94f1b5c6210a54
+  data.tar.gz: 2cbe363c8e5915611b9c3e9a38c2448af1bc0ccb8353b99a6f0595c51a115dce93269b2832a1f18d915f11dd96855249261f7749ba2ca9175685deda51cacbe6

data/lib/jsapi/client/base.rb

@@ -0,0 +1,182 @@
+# frozen_string_literal: true
+
+require 'net/http'
+require 'uri'
+
+module Jsapi
+  module Client
+    # Base class for response errors.
+    class ResponseError < StandardError; end
+
+    # Raised when the response body is invalid.
+    class InvalidResponseBodyError < ResponseError
+
+      # The Response::Body that caused the error.
+      attr_reader :response_body
+
+      def initialize(response_body) # :nodoc:
+        super(Support::Messages.join(*response_body.errors.full_messages))
+        @response_body = response_body
+      end
+    end
+
+    # Raised when no response specification matches the status code returned by the server.
+    class UnexpectedResponseError < ResponseError
+      def initialize(operation, code) # :nodoc:
+        super("Unexpected status code #{code} for operation #{operation.name.inspect}")
+      end
+    end
+
+    # \Base client class.
+    class Base
+      include DSL
+      include Exceptions
+
+      ##
+      # :attr: logger
+      attr_accessor :logger
+
+      ##
+      # :attr_reader: request_headers
+      # The Request::Headers set for every subsequent call.
+      #
+      #   request_headers['User-Agent'] = '...'
+
+      ##
+      # :call-seq:
+      #   new(base_uri, http: nil)
+      #   new(server_name, variables = nil, http: nil)
+      #
+      # Creates a client.
+      #
+      # Raises an +ArgumentError+ if +base_uri+ or +:http+ is invalid.
+      def initialize(arg1, arg2 = nil, http: nil)
+        unless arg1.is_a?(URI)
+          server_url = self.class.api.server(arg1)&.url_for(arg2)
+          arg1 = server_url unless server_url.nil?
+          arg1 = URI(arg1)
+        end
+
+        @base_uri = arg1
+        @host = @base_uri.host
+        @port = @base_uri.port
+
+        http = http&.dup || {}
+        raise ArgumentError, ':http must be a hash' unless http.is_a?(Hash)
+
+        @http_options = http
+        @http_options[:use_ssl] = true if @base_uri.scheme == 'https'
+      rescue URI::InvalidURIError => e
+        raise ArgumentError, e
+      end
+
+      ##
+      # :method: call
+      # :call-seq:
+      #   call(operation_name = nil, body = nil, content_type = nil, **params, &block)
+      #
+      # Calls a remote API operation and returns a Response. Returns +nil+ if no response
+      # specification matches the status code returned by the server.
+      #
+      # If a block is given it is called with a Request as argument.
+      #
+      # Examples:
+      #
+      #   call('foo', id: 1)
+      #
+      #   call('foo') do |request|
+      #     request[:id] = 1
+      #     request.body = foo
+      #   end
+      #
+      # +operation_name+ specifies the operation to be called. It can be omitted if the
+      # remote API exposes a single operation. If the operation does not exist, an
+      # OperationNotFound exception is raised.
+      #
+      # Raises a RequestError if the HTTP request cannot be be built from the given data.
+      #
+      # Raises a Session::Error if a session-level error occurs.
+
+      ##
+      # :method: call!
+      # :call-seq:
+      #   call!(operation_name = nil, body = nil, content_type = nil, **params, &block)
+      #
+      # Like +call+, except it raises a subclass of ResponseError when:
+      #
+      # - InvalidResponseBodyError - raised when the response body is invalid.
+      # - UnexpectedResponseError - raised when no response specification matches the
+      #   status code returned by the server.
+
+      [true, false].each do |bang|
+        define_method(bang ? :call! : :call) \
+        do |operation_name = nil, body = nil, content_type = nil, **params, &block|
+          operation = self.class.api.find_operation!(operation_name)
+
+          request = Request.new(@base_uri, operation, headers: @request_headers, params: params)
+          request.content_type = content_type || 'application/json'
+          request.body = body
+          instance_exec(request, &block) if block
+
+          http_request = request.http_request
+
+          session = @session || Session::SingleRequest.new(@host, @port, @logger, **@http_options)
+          http_response = session.send_request(http_request)
+
+          response_definition = operation.find_response_for(http_response.code)
+          if response_definition.nil?
+            raise UnexpectedResponseError.new(operation, http_response.code) if bang
+
+            return
+          end
+
+          response = Response.new(http_response, response_definition)
+          raise InvalidResponseBodyError.new(response.body) if bang && response.body.invalid?
+
+          error_class = self.class.error_class_for(response.status_code)
+          raise error_class, response.error_message if error_class
+
+          response
+        end
+      end
+
+      # Closes the current session.
+      def finish_session
+        @session&.finish
+        @session = nil
+      end
+
+      def inspect # :nodoc:
+        "#<#{self.class.name} base_uri: #{@base_uri}, http: #{@http_options.inspect}>"
+      end
+
+      def request_headers # :nodoc:
+        @request_headers ||= Request::Headers.new
+      end
+
+      # Starts a session. If a block is given the session is closed automatically
+      # after the block has been executed.
+      #
+      # Returns the value returned by the block or +nil+ if no block is given.
+      #
+      #   start_session do
+      #     call('foo')
+      #     call('bar')
+      #   end
+      #
+      # Raises a Session::Error if a session-level error occurs.
+      def start_session
+        @session&.finish
+        @session = Session::Base.new(@host, @port, @logger, **@http_options)
+
+        if block_given?
+          begin
+            yield
+          ensure
+            finish_session
+          end
+        end
+      end
+    end
+  end
+end

data/lib/jsapi/client/exceptions.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Jsapi
+  module Client
+    module Exceptions
+      module ClassMethods
+        # Registers +error_class+ to be raised when the server responds with a status code
+        # matching +:on+.
+        #
+        # +error_class+ can be +StandardError+ or a subclass of it. +:on+ can be a status
+        # code or a range of status codes.
+        #
+        #   class ServerError < StandardError; end
+        #   class InternalServerError < ServerError; end
+        #
+        #   raises ServerError, on: '5xx'
+        #   raises InternalServerError, on: '500'
+        #
+        # Raises an +ArgumentError+ if +error_class+ or +:on+ is invalid.
+        def raises(error_class, on:)
+          raise ArgumentError, "#{error_class.inspect} isn't a class" \
+          unless error_class.is_a?(Class)
+
+          raise ArgumentError, "#{error_class.inspect} isn't a subclass of StandardError" \
+          unless error_class <= StandardError
+
+          (@_raises ||= {})[Status.from(on)] = error_class
+        end
+
+        def error_class_for(status_code) # :nodoc:
+          status_code = Status::Code.from(status_code)
+
+          @_raises
+            &.sort
+            &.find { |status, _| status.match?(status_code) }
+            &.second || superclass.try(:error_class_for, status_code)
+        end
+      end
+
+      def self.included(base) # :nodoc:
+        base.extend(ClassMethods)
+      end
+    end
+  end
+end

data/lib/jsapi/client/request.rb

@@ -0,0 +1,204 @@
+# frozen_string_literal: true
+
+module Jsapi
+  module Client
+    class RequestError < StandardError; end
+
+    class Request
+      class Headers
+        delegate :each, to: :@headers
+
+        def initialize(headers = nil) # :nodoc:
+          @headers = {}
+          headers&.each { |name, value| self[name] = value }
+        end
+
+        # Returns the value for +name+.
+        def [](name)
+          @headers[name.to_s.downcase]
+        end
+
+        # Sets the value for +name+ to +value+.
+        #
+        # Raises an +ArgumentError+ if name is blank.
+        def []=(name, value)
+          name = name.to_s.downcase
+          raise ArgumentError, "name can't be blank" if name.blank?
+
+          if value.nil?
+            @headers.delete(name)
+          else
+            @headers[name] = value
+          end
+        end
+
+        # Sets the username and password for HTTP Basic Authentication.
+        def http_basic_auth(username = nil, password = nil)
+          auth_param = Base64.strict_encode64("#{username}:#{password}")
+          @headers['authorization'] = "Basic #{auth_param}"
+        end
+
+        def inspect # :nodoc:
+          "#<#{
+            [
+              self.class.name,
+              @headers.map { |name, value| "#{name}: #{value.inspect}" }.sort.join(', ')
+            ].compact_blank.join(' ')
+          }>"
+        end
+      end
+
+      class Parameters
+        def initialize(params = nil)
+          @params = {}
+          params&.each { |name, value| self[name] = value }
+        end
+
+        # Returns the value for +name+.
+        def [](name)
+          @params[name.to_s.underscore]
+        end
+
+        # Sets the value for +name+ to +value+.
+        #
+        # Raises an +ArgumentError+ if name is blank.
+        def []=(name, value)
+          name = name.to_s
+          raise ArgumentError, "name can't be blank" if name.blank?
+
+          @params[name.underscore] = value
+        end
+
+        def inspect # :nodoc:
+          "#<#{
+            [
+              self.class.name,
+              @params.map { |name, value| "#{name}: #{value.inspect}" }.sort.join(', ')
+            ].compact_blank.join(' ')
+          }>"
+        end
+      end
+
+      # The content type.
+      attr_accessor :content_type
+
+      # The body.
+      attr_accessor :body
+
+      # The Headers.
+      attr_reader :headers
+
+      ##
+      # :method: [](name)
+      # Returns the parameter value for +name+.
+
+      ##
+      # :method: []=(name, value)
+      # Sets the parameter value for +name+ to +value+.
+
+      delegate :[], :[]=, to: :@params
+
+      def initialize(base_uri, operation, headers: nil, params: nil) # :nodoc:
+        @base_uri = base_uri
+        @operation = operation
+        @headers = Headers.new(headers)
+        @params = Parameters.new(params)
+      end
+
+      def http_request # :nodoc:
+        create_http_request.tap do |http_request|
+          http_headers.each { |name, value| http_request[name] = value }
+
+          if (request_body_definition = @operation.request_body)
+            media_type = Media::Type.from(content_type || 'application/json')
+
+            http_request.content_type = media_type.to_s
+            http_request.body =
+              if media_type.json?
+                request_body_definition
+                  .content_for(media_type)
+                  .schema
+                  .jsonify(body, context: :request, omit: :empty)
+                  .to_json
+              else
+                body.to_s
+              end
+          end
+        end
+      rescue StandardError => e
+        raise RequestError, e.message
+      end
+
+      def inspect # :nodoc:
+        "#<#{self.class.name} " \
+        "base_uri: #{@base_uri}, " \
+        "operation: #{@operation.name.inspect}, " \
+        "headers: #{@headers.inspect}, " \
+        "parameters: #{@params.inspect}>"
+      end
+
+      private
+
+      def create_http_request
+        http_method = @operation.http_method
+
+        # Try to instantiate a subclass of Net::HTTPRequest
+        http_request_class = "Net::HTTP::#{http_method.camelize}".safe_constantize
+        return http_request_class.new(http_request_uri) if http_request_class
+
+        # Fallback to Net::HTTPGenericRequest even it should not be used directly
+        Net::HTTPGenericRequest.new(
+          http_method,
+          @operation.request_body.present?,
+          @operation.responses.values.lazy.any?(&:content?),
+          http_request_uri
+        )
+      end
+
+      def http_request_uri
+        path = File.join(@base_uri.path, @operation.full_path.to_s)
+
+        # Substitute variables in RFC 6570 format
+        path.gsub!(/\{\w+\}/) do |match|
+          @params[match[1..-2]].tap do |value|
+            # Raise an error as a URI must not contain curly brackets.
+            raise "#{match.inspect} cannot be substituted" if value.nil?
+          end
+        end
+
+        # Merge base URI and path and add query parameters
+        @base_uri.merge(path).tap do |uri|
+          if (querystring_param = @operation.querystring_parameter)
+            querystring = @params[querystring_param.name]
+            uri.query = querystring.to_s unless querystring.nil?
+          elsif (query_params = @operation.query_parameters).any?
+            uri.query = query_params.transform_values do |parameter|
+              parameter.schema.jsonify(
+                @params[parameter.name],
+                context: :request,
+                omit: :empty
+              )
+            rescue Definition::Schema::JsonifyError => e
+              raise e.prepend(parameter.name)
+            end.compact.to_query
+          end
+        end
+      end
+
+      def http_headers
+        Headers.new.tap do |headers|
+          @operation.header_parameters.each do |name, header_definition|
+            value = @params[name] || @headers[name]
+            next if value.nil?
+
+            value = Array(value).join(',') if header_definition.schema.array?
+            headers[name] = value
+          end
+          @headers.each do |name, value|
+            headers[name] ||= value
+          end
+        end
+      end
+    end
+  end
+end

data/lib/jsapi/client/response.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+module Jsapi
+  module Client
+    class Response
+      class Body
+        attr_reader :content, :errors
+
+        def initialize(http_response_body, media_type, schema) # :nodoc:
+          @http_response_body = http_response_body
+          @errors = Model::Errors.new(self)
+          @content =
+            begin
+              body = http_response_body
+              body = ::JSON.parse(body) if media_type.json?
+
+              if schema
+                JSON.wrap(body, schema, context: :response).tap do |json|
+                  json.validate(@errors)
+                end.value
+              else
+                body
+              end
+            rescue ::JSON::ParserError => e
+              @errors.add(:base, :invalid, message: e.message)
+              nil
+            end
+        end
+
+        def inspect # :nodoc:
+          "#<#{self.class.name} #{@http_response_body.inspect}>"
+        end
+
+        def invalid?
+          !valid?
+        end
+
+        def valid?
+          errors.none?
+        end
+      end
+
+      class Headers
+        ##
+        # :method: each
+        delegate :each, to: :@headers
+
+        def initialize(http_response, response_definition) # :nodoc:
+          @headers = http_response.each_header.to_h do |name, value|
+            if (header_definition = response_definition.header_for(name))
+              schema = header_definition.schema
+              value = value.split(',') if schema.array?
+              value = JSON.wrap(value, schema, context: :response).value
+            end
+            [name.downcase, value]
+          end
+        end
+
+        def [](name)
+          @headers[name.downcase]
+        end
+      end
+
+      ##
+      # :attr_reader: body
+      # The body of the response as Body.
+
+      ##
+      # :attr_reader: headers
+      # The headers of the response as Headers.
+
+      ##
+      # :attr_reader: media_type
+      # The media type of the response as Media::Type.
+      attr_reader :media_type
+
+      ##
+      # :attr_reader: status_code
+      # The status code of the response as Status::Code.
+      attr_reader :status_code
+
+      ##
+      # :attr_reader: content
+      # Same as +body.content+.
+      delegate :content, to: :body
+
+      # :nodoc:
+      def initialize(http_response, response_definition)
+        @http_response = http_response
+        @response_definition = response_definition
+        @status_code = Status::Code.from(@http_response.code)
+        @media_type = Media::Type.from(@http_response.content_type)
+      end
+
+      def body
+        @body ||= Body.new(
+          @http_response.body,
+          @media_type,
+          @response_definition.content_for(@media_type).schema
+        )
+      end
+
+      # Builds an error message in the form <code>"{status_code}: {message}"</code>.
+      def error_message
+        message = content
+        message = message.message if message.respond_to?(:message)
+
+        "#{status_code}: #{message}"
+      end
+
+      def headers
+        @headers ||= Headers.new(@http_response, @response_definition)
+      end
+
+      def inspect # :nodoc:
+        "#<#{self.class.name} #{@http_response.inspect}>"
+      end
+    end
+  end
+end

data/lib/jsapi/client/session/base.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Jsapi
+  module Client
+    module Session
+      class Error < StandardError; end
+      class TimeoutError < Error; end
+
+      # \Base session class.
+      class Base
+        include Test
+
+        # Creates and starts a new session.
+        def initialize(host, port = nil, logger = nil, **options)
+          logger = Logger.new(logger) unless logger.nil? || logger.is_a?(Logger)
+          @logger = logger
+
+          @http =
+            begin
+              Net::HTTP.start(host, port, options)
+            rescue StandardError => e
+              raise wrap_error(e)
+            end
+        end
+
+        # Closes the session.
+        def finish
+          @http.finish
+        rescue StandardError => e
+          raise wrap_error(e)
+        end
+
+        # Sends +request+.
+        def send_request(request)
+          @logger&.log_request(request)
+
+          response =
+            begin
+              @http.request(request)
+            rescue StandardError => e
+              raise wrap_error(e)
+            end
+
+          @logger&.log_response(response)
+          response
+        end
+
+        private
+
+        def wrap_error(cause)
+          case cause
+          when Timeout::Error
+            TimeoutError
+          else
+            Error
+          end.new(cause: cause)
+        end
+      end
+    end
+  end
+end

data/lib/jsapi/client/session/logger.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Jsapi
+  module Client
+    module Session
+      class Logger
+        def initialize(logger, **options)
+          @logger = ActiveSupport::TaggedLogging.new(logger)
+          @body = options[:body] == true
+          @level = options[:level] || 0
+        end
+
+        # Logs +http_request+.
+        def log_request(request)
+          return if @logger.level > @level
+
+          tagged('REQ') do
+            log("#{request.method} #{request.path}")
+            log(request.body, truncate_to: 8_192) if body?
+          end
+        end
+
+        # Logs +http_response+.
+        def log_response(response)
+          return if @logger.level > @level
+
+          tagged('RES') do
+            log("HTTP/#{response.http_version} #{response.code}")
+            log(response.body, truncate_to: 8_192) if body?
+          end
+        end
+
+        private
+
+        def body?
+          @body == true
+        end
+
+        def log(message, truncate_to: nil)
+          return if message.nil?
+
+          message = message.truncate(truncate_to) if truncate_to
+          @logger.log(@level, message)
+        end
+
+        def tagged(*args, &block)
+          @logger.tagged('JSAPI CLIENT', *args, &block)
+        end
+      end
+    end
+  end
+end

data/lib/jsapi/client/session/single_request.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Jsapi
+  module Client
+    module Session
+      class SingleRequest < Base
+        # Sends +request+ and closes the session.
+        def send_request(request)
+          super
+        ensure
+          finish
+        end
+      end
+    end
+  end
+end