connect-sdk-ruby 1.0.0

data/lib/ingenico/connect/sdk/connection.rb

@@ -0,0 +1,31 @@
+module Ingenico::Connect::SDK
+
+  # Class used to communicate using the HTTP (or HTTPS) protocol.
+  # Performs GET, DELETE, POST and PUT requests given a target uri and request headers.
+  # @see Ingenico::Connect::SDK::DefaultImpl::DefaultConnection
+  class Connection
+    include Ingenico::Connect::SDK::Logging::LoggingCapable
+
+    # Performs a GET request to _uri_ using _request_headers_ and returns the response as a {Ingenico::Connect::SDK::Response} object
+    def get(uri, request_headers)
+      raise NotImplementedError
+    end
+
+    # Performs a DELETE request to _uri_ using _request_headers_ and returns the response as a {Ingenico::Connect::SDK::Response} object
+    def delete(uri, request_headers)
+      raise NotImplementedError
+    end
+
+    # Performs a POST request to _uri_ using _request_headers_ and _body_.
+    # Returns the response as a {Ingenico::Connect::SDK::Response} object
+    def post(uri, request_headers, body)
+      raise NotImplementedError
+    end
+
+    # Performs a PUT request to _uri_ using _request_headers_ and _body_.
+    # Returns the response as a {Ingenico::Connect::SDK::Response} object
+    def put(uri, request_headers, body)
+      raise NotImplementedError
+    end
+  end
+end

data/lib/ingenico/connect/sdk/data_object.rb

@@ -0,0 +1,43 @@
+require 'json'
+
+module Ingenico::Connect::SDK
+
+  # Base class for all SDK data objects, supports marshalling and unmarshalling the data object to and from JSON.
+  class DataObject
+
+    # Returns a hash representation of the DataObject.
+    # The hash contains camelCase representations of the variables, and their values.
+    # Should be overridden to add all instance variables of the object.
+    def to_h
+      {}
+    end
+
+    # Create a new instance of this object (DataObject or descendant)
+    # from a hash containing attribute values in camelCase.
+    # Note that the hash contains Strings as keys instead of more commonly used tokens.
+    def self.new_from_hash(hash)
+      obj = self.new
+      obj.from_hash(hash)
+      obj
+    end
+
+    # Set attributes from values in parameter hash.
+    # Should be overridden by descendants in order to properly restore their attributes from the hash.
+    # Note that the hash contains Strings as keys instead of more commonly used tokens.
+    def from_hash(hash)
+    end
+
+    private
+
+    # Adds a serializable hash or array representation of _value_ to _hash_ keyed under _key_
+    def add_to_hash(hash, key, value)
+      if value.is_a?(Array)  # For arrays, convert the elements to hash representations
+        hash[key] = value.collect{|val| if val.is_a?(DataObject); val.to_h else val end}
+      elsif value.is_a?(DataObject)
+        hash[key] = value.to_h
+      elsif !value.nil?
+        hash[key] = value
+      end
+    end
+  end
+end

data/lib/ingenico/connect/sdk/declined_payment_exception.rb

@@ -0,0 +1,44 @@
+module Ingenico::Connect::SDK
+
+  # Indicates that a payment is declined by the GlobalCollect platform or one of its downstream partners/acquirers.
+  class DeclinedPaymentException < DeclinedTransactionException
+
+    # Create a new DeclinedPaymentException.
+    # @see ApiException#initialize
+    def initialize(status_code, response_body, errors)
+      if errors.nil?
+        super(status_code, response_body, nil, nil, build_message(errors))
+      else
+        super(status_code, response_body, errors.error_id, errors.errors,
+              build_message(errors))
+      end
+      @errors = errors
+    end
+
+    # The declined payment result returned by the GlobalCollect platform.
+    # Given as a {Ingenico::Connect::SDK::Domain::Payment::CreatePaymentResult} object.
+    def payment_result
+      if @errors.nil?
+        nil
+      else
+        @errors.payment_result
+      end
+    end
+
+    private
+
+    def build_message(errors)
+      if !errors.nil? && !errors.payment_result.nil?
+        payment = errors.payment_result.payment
+      else
+        payment = nil
+      end
+      if payment.nil?
+        'the GlobalCollect platform returned a declined payment response'
+      else
+        "declined payment '" + payment.id + "' with status '" +
+            payment.status + "'"
+      end
+    end
+  end
+end

data/lib/ingenico/connect/sdk/declined_payout_exception.rb

@@ -0,0 +1,44 @@
+module Ingenico::Connect::SDK
+
+  # Indicates that a payout is declined by the GlobalCollect platform or one of its downstream partners/acquirers.
+  class DeclinedPayoutException < DeclinedTransactionException
+
+    # Create a new DeclinedPayoutException.
+    # @see ApiException#initialize
+    def initialize(status_code, response_body, errors)
+      if errors.nil?
+        super(status_code, response_body, nil, nil, build_message(errors))
+      else
+        super(status_code, response_body, errors.error_id, errors.errors,
+              build_message(errors))
+      end
+      @errors = errors
+    end
+
+    # The declined payout result as returned by the GlobalCollect platform.
+    # Given as a {Ingenico::Connect::SDK::Domain::Payout::PayoutResult} object.
+    def payout_result
+      if @errors.nil?
+        nil
+      else
+        @errors.payout_result
+      end
+    end
+
+    private
+
+    def build_message(errors)
+      if !errors.nil?
+        payout = errors.payout_result
+      else
+        payout = nil
+      end
+      if payout.nil?
+        'the GlobalCollect platform returned a declined payout response'
+      else
+        "declined payment '" + payout.id + "' with status '" +
+            payout.status + "'"
+      end
+    end
+  end
+end

data/lib/ingenico/connect/sdk/declined_refund_exception.rb

@@ -0,0 +1,46 @@
+require 'ingenico/connect/sdk/declined_transaction_exception'
+
+module Ingenico::Connect::SDK
+
+  # Indicates that a refund is declined by the GlobalCollect platform or one of its downstream partners/acquirers.
+  class DeclinedRefundException < DeclinedTransactionException
+
+    # Create a new DeclinedRefundException
+    # @see ApiException#initialize
+    def initialize(status_code, response_body, errors)
+      if errors.nil?
+        super(status_code, response_body, nil, nil, build_message(errors))
+      else
+        super(status_code, response_body, errors.error_id, errors.errors,
+              build_message(errors))
+      end
+      @errors = errors
+    end
+
+    # The declined refund result as returned by the GlobalCollect platform.
+    # Given as a {Ingenico::Connect::SDK::Domain::Refund::RefundResult} object.
+    def refund_result
+      if @errors.nil?
+        nil
+      else
+        @errors.refund_result
+      end
+    end
+
+    private
+
+    def build_message(errors)
+      if !errors.nil?
+        refund = errors.refund_result
+      else
+        refund = nil
+      end
+      if refund.nil?
+        'the GlobalCollect platform returned a declined refund response'
+      else
+        "declined refund '" + refund.id + "' with status '" +
+            refund.status + "'"
+      end
+    end
+  end
+end

data/lib/ingenico/connect/sdk/declined_transaction_exception.rb

@@ -0,0 +1,16 @@
+module Ingenico::Connect::SDK
+
+  # Indicates that a transaction is declined by the GlobalCollect platform or one of its downstream partners/acquirers.
+  class DeclinedTransactionException < ApiException
+
+    # Create a new DeclinedTransactionException.
+    # @see ApiException#initialize
+    def initialize(status_code, response_body, error_id, errors, message=FALSE)
+      if message == FALSE
+        super(status_code, response_body, error_id, errors)
+      else
+        super(status_code, response_body, error_id, errors, message)
+      end
+    end
+  end
+end

data/lib/ingenico/connect/sdk/defaultimpl.rb

@@ -0,0 +1,6 @@
+prefix = 'ingenico/connect/sdk/defaultimpl/'
+
+require prefix + 'authorization_type'
+require prefix + 'default_marshaller'
+require prefix + 'default_connection'
+require prefix + 'default_authenticator'

data/lib/ingenico/connect/sdk/defaultimpl/authorization_type.rb

@@ -0,0 +1,18 @@
+module Ingenico::Connect::SDK
+  module DefaultImpl
+
+    # Contains all authentication schemes supported by the GlobabCollect platform.
+    class AuthorizationType
+      V1HMAC = 'v1HMAC'
+
+      # Returns the authorization string that belongs to the parameter _authorization_, or _nil_ if not found.
+      def self.get_authorization(authorization)
+        authorization if authorization == 'v1HMAC'
+      end
+
+      def self.get_signature_string
+        V1HMAC
+      end
+    end
+  end
+end

data/lib/ingenico/connect/sdk/defaultimpl/default_authenticator.rb

@@ -0,0 +1,106 @@
+require 'openssl' # for HMAC-SHA256
+require 'base64'
+
+module Ingenico::Connect::SDK
+  module DefaultImpl
+
+    # Authenticates requests made to the GlobalCollect platform using the HMAC algorithm.
+    class DefaultAuthenticator < Authenticator
+      # HMAC algorithm used to generate the signature
+      HMAC_ALGOR = 'SHA256'
+      CONTENT_TYPE = 'Content-Type'
+      DATE = 'Date'
+      XGCS = 'x-gcs'
+
+      # Construct a new DefaultAuthenticator instance that can sign requests
+      # with the provided _api_key_id_ and _secret_api_key_.
+      # authorization_type::  The authorization protocol to use for authentication.
+      # api_key_id::          Identifier for the secret key used in authentication.
+      # secret_api_key::      The secret key that is used to generate the authentication signature.
+      def initialize(authorization_type, api_key_id, secret_api_key)
+        raise ArgumentError unless authorization_type
+        raise ArgumentError unless api_key_id and not api_key_id.strip.empty?
+        raise ArgumentError unless secret_api_key and not secret_api_key.strip.empty?
+
+        @authorization_type = authorization_type
+        @api_key_id = api_key_id
+        @secret_api_key = secret_api_key
+      end
+
+      # Creates a signature to authenticate a request.
+      # Uses the following parameters:
+      # http_method::     'GET', 'PUT', 'POST' or 'DELETE' indicating which HTTP method will be used with the request
+      # resource_uri::    URI object that includes #path and #query of the url that will be used, #query may be *nil*
+      # request_headers:: {Ingenico::Connect::SDK::RequestHeader} list that contains all headers used by the request
+      def create_simple_authentication_signature(http_method, resource_uri, http_headers)
+        raise ArgumentError unless http_method and not http_method.strip.empty?
+        raise ArgumentError unless resource_uri
+
+        data_to_sign = to_data_to_sign(http_method, resource_uri, http_headers)
+        "GCS #{@authorization_type}:#{@api_key_id}:#{create_auth_signature(data_to_sign)}"
+      end
+
+      protected
+
+      # Canonizes the _http_method_, _resource_uri_ and _http_headers_ so a unique signature can be generated.
+      # Canonical form is as follows:
+      # * _http_method_ in upper case
+      # * Content-Type
+      # * Date header
+      # * X-GCS headers sorted alphabetically. Names are in lowercase and values are stripped of excess whitespace
+      # * path and query portion of the uri, separated by a question mark
+      def to_data_to_sign(http_method, resource_uri, http_headers)
+        content_type = ''
+        date = ''
+        canonical_resource = to_canonical_resource(resource_uri)
+        xgc_http_headers = []
+
+        http_headers.each do |header|
+          name, value = header.name, header.value
+          case
+          when name.casecmp(CONTENT_TYPE) == 0
+            content_type = value
+          when name.casecmp(DATE) == 0
+            date = value
+          when to_canonical_header_name(name).start_with?(XGCS)
+            xgc_http_headers << [ to_canonical_header_name(name), to_canonical_header_value(value) ]
+          end
+        end if http_headers
+
+        xgc_http_headers.sort! { |(h1, v1), (h2, v2)| h1 <=> h2 } unless xgc_http_headers.empty?
+
+        data = http_method.upcase + "\n" +
+            content_type + "\n" + date + "\n"
+        data += xgc_http_headers.inject('') { |s, (k, v)| s + k + ':' + v + "\n" } unless xgc_http_headers.empty?
+        data += canonical_resource + "\n" unless canonical_resource.nil?
+        data
+      end
+
+      # Applies the HMAC algorithm to the canonicalized data to obtain an HMAC digest.
+      # Afterwards the HMAC digest is encoded using base64 encoding.
+      def create_auth_signature(data_to_sign)
+        digest = OpenSSL::Digest.new(HMAC_ALGOR)
+        hmac = OpenSSL::HMAC.digest(digest, @secret_api_key, data_to_sign)
+        Base64.strict_encode64(hmac).strip
+      end
+
+      private
+
+      # Returns the encoded URI path without the HTTP method and including all decoded query parameters.
+      def to_canonical_resource(resource_uri)
+        return resource_uri.path + '?' + resource_uri.query if resource_uri.query
+        return resource_uri.path
+      end
+
+      def to_canonical_header_name(original_name)
+        original_name ? original_name.downcase : original_name
+      end
+
+      # Strips a header value of excess whitespace to produce a canonical value
+      def to_canonical_header_value(original_value)
+        return '' unless original_value
+        original_value.gsub(/\r?\n[\s&&[^\r\n]]*/, ' ').strip
+      end
+    end
+  end
+end

data/lib/ingenico/connect/sdk/defaultimpl/default_connection.rb

@@ -0,0 +1,242 @@
+require 'securerandom'
+require 'uri'
+require 'httpclient'
+
+# @private :nodoc: this is not our class
+class HTTPClient
+  # (monkey) patch to gain access to the session pool size in HTTPClient
+  def session_count
+    sess_pool = @session_manager.instance_variable_get(:@sess_pool)
+    sess_pool.size
+  end
+end
+
+module Ingenico::Connect::SDK
+  module DefaultImpl
+
+    class DefaultConnection < PooledConnection
+
+      CONTENT_TYPE = 'Content-Type'
+      JSON_CONTENT_TYPE = 'application/json'
+
+      # Initialized using a hash containing the following parameters:
+      # connect_timeout::     Connection timeout in seconds.
+      # socket_timeout::      Socket timeout in seconds.
+      # max_connections::     Number of connections kept alive in the thread pool.
+      #                       Uses {Ingenico::Connect::SDK::CommunicatorConfiguration.DEFAULT_MAX_CONNECTIONS} if not given.
+      # proxy_configuration:: {Ingenico::Connect::SDK::ProxyConfiguration} object that stores the proxy to use.
+      #                       If not given the system default proxy is used;
+      #                       if there is no system default proxy set either, no proxy is used.
+      def initialize(args)
+        raise ArgumentError unless args.is_a? Hash
+        # Set timeouts to nil if they are negative
+        @connect_timeout = args[:connect_timeout]
+        @connect_timeout = nil unless @connect_timeout.nil? || @connect_timeout > 0
+        @socket_timeout = args[:socket_timeout]
+        @socket_timeout = nil unless @socket_timeout.nil? || @socket_timeout > 0
+        @max_connections = args[:max_connections] || CommunicatorConfiguration.DEFAULT_MAX_CONNECTIONS
+        @proxy_configuration = args[:proxy_configuration]
+
+        # HTTPClient provides the following features:
+        # 1) thread safe, an instance can be used by multiple threads without
+        # explicit synchronization
+        # 2) use persistent connection if HTTP 1.1 is supported. The connection
+        # will be left open until explicitly closed or keep_alive_timeout
+        # 3) a built-in connection pool with no limit for max connections
+        @http_client = create_http_client
+        @http_client.connect_timeout = @connect_timeout
+        @http_client.send_timeout = @socket_timeout
+        @http_client.receive_timeout = @socket_timeout
+      end
+
+      private
+
+      # Create a HTTPClient instance that uses @proxy_configuration or the system proxy if @proxy_configuration is not set
+      def create_http_client
+        if @proxy_configuration
+          httpclient = HTTPClient.new(@proxy_configuration.proxy_uri)
+          httpclient.set_proxy_auth(@proxy_configuration.username, @proxy_configuration.password)
+          httpclient
+        else # use system settings
+          proxy_string = ENV['https_proxy'] || ENV['http_proxy']
+          # proxy string format = 'http://username:password@hostname:port'
+          proxy_string =~ %r(https?//(?<username>[^:]):(?<password>[^@])@.*)
+          username = $1
+          password = $2
+          httpclient = HTTPClient.new(proxy_string)
+          httpclient.set_proxy_auth(username, password) unless username.nil? || password.nil?
+          httpclient
+        end
+      end
+
+      public
+
+      # Closes all connections idle for longer than _idle_time_ seconds.
+      # In addition, the keep_alive_timeout is set to _idle_time_
+      # so any future connections idle for longer than _idle_time_ seconds will also be closed.
+      def close_idle_connections(idle_time) # in sec
+        @http_client.keep_alive_timeout = idle_time # set timeout value
+        close_expired_connections
+      end
+
+      # HTTPClient automatically closes expired connections so _close_expired_connections_ is a no-operation.
+      def close_expired_connections
+        # By default the keep alive timeout is 15 sec, which is the HTTP 1.1
+        # standard. To change the value, use keep_alive_timeout= method
+        # do nothing, handled by HTTPClient
+      end
+
+      # Frees all networking resources used.
+      def close
+        @http_client.reset_all
+      end
+
+      # Returns the number of open connections
+      def session_count
+        @http_client.session_count
+      end
+
+      # Performs a GET request to the GlobalCollect platform
+      # @see request
+      def get(uri, request_headers)
+        request('get', uri, request_headers)
+      end
+
+      # Performs a DELETE request to the GlobalCollect platform
+      # @see request
+      def delete(uri, request_headers)
+        request('delete', uri, request_headers)
+      end
+
+      # Performs a POST request to the GlobalCollect platform
+      # @see request
+      def post(uri, request_headers, body)
+        request('post', uri, request_headers, body)
+      end
+
+      # Performs a PUT request to the GlobalCollect platform
+      # @see request
+      def put(uri, request_headers, body)
+        request('put', uri, request_headers, body)
+      end
+
+      # performs a HTTP request and returns the response as an {Ingenico::Connect::SDK::Response} object.
+      # Also ensures the request is logged when sent and its response is logged when received.
+      # Raises {Ingenico::Connect::SDK::CommunicationException} when communication with the GlobalCollect platform was not successful.
+      # method::          'GET', 'DELETE', 'POST' or 'PUT' depending on the HTTP method being used.
+      # uri::             Full URI of the location the request is targeted at, including query parameters.
+      # request_headers:: {Ingenico::Connect::SDK::RequestHeader} list of headers that should be used as HTTP headers in the request.
+      # body::            Request body as a String.
+      def request(method, uri, request_headers, body=nil)
+        request_headers = convert_from_sdk_headers(request_headers)
+        request_id = SecureRandom.uuid
+        request_headers[CONTENT_TYPE] = JSON_CONTENT_TYPE if body
+        content_type = request_headers[CONTENT_TYPE]
+        info = { headers: request_headers, content_type: content_type }
+        info[:body] = body unless body.nil?
+        log_request(request_id, method.upcase, uri, info)
+
+        start_time = Time.now
+        begin
+          response = if body
+                       @http_client.send(method, uri, header: request_headers, body: body)
+                     else
+                       @http_client.send(method, uri, header: request_headers)
+                     end
+        rescue HTTPClient::TimeoutError => e
+          log_error(request_id, start_time, e)
+          raise Ingenico::Connect::SDK::CommunicationException.new(e)
+        rescue HTTPClient::KeepAliveDisconnected, HTTPClient::RetryableResponse => e  # retry these?
+          log_error(request_id, start_time, e)
+          raise Ingenico::Connect::SDK::CommunicationException.new(e)
+        rescue => e
+          log_error(request_id, start_time, e)
+          raise Ingenico::Connect::SDK::CommunicationException.new(e)
+        end
+
+        log_response(request_id, response.status, start_time,
+                     headers: response.headers, body: response.body,
+                     content_type: response.content_type)
+        convert_to_sdk_response(response)
+      end
+
+      # logging code
+
+      # Enables logging outgoing requests and incoming responses by registering the _communicator_logger_.
+      # Note that only one logger can be registered at a time and calling _enable_logging_
+      # a second time will override the old logger instance with the new one.
+      #
+      # communicator_logger:: The {Ingenico::Connect::SDK::Logging::CommunicatorLogger} the requests and responses are logged to
+      #
+      def enable_logging(communicator_logger)
+        raise ArgumentError.new('communicatorLogger is required') unless communicator_logger
+        @communicator_logger = communicator_logger
+      end
+
+      # Disables logging by unregistering any previous logger that might be registered.
+      def disable_logging
+        @communicator_logger = nil
+      end
+
+      private
+
+      # Converts a {Ingenico::Connect::SDK::RequestHeader} list headers to a hash
+      def convert_from_sdk_headers(headers)
+        hash = {}
+        headers.each { |h| hash[h.name] =  h.value }
+        hash
+      end
+
+      # Converts a hash to a {Ingenico::Connect::SDK::ResponseHeader} list
+      def convert_to_sdk_headers(headers)
+        arr = []
+        headers.each { |k, v| arr << Ingenico::Connect::SDK::ResponseHeader.new(k, v) }
+        arr
+      end
+
+      # converts a HTTPClient response to a {Ingenico::Connect::SDK::Response}
+      def convert_to_sdk_response(response)
+        Ingenico::Connect::SDK::Response.new(response.status,
+                         response.body,
+                         convert_to_sdk_headers(response.headers))
+      end
+
+      def log_request(requestId, method, uri, args={})
+        return unless @communicator_logger
+
+        headers, body, content_type = args[:headers], args[:body], args[:content_type]
+        log_msg_builder = Ingenico::Connect::SDK::Logging::RequestLogMessageBuilder.new(requestId, method, uri)
+        headers.each { |k, v| log_msg_builder.add_headers(k, v) } if headers
+        log_msg_builder.set_body(body, content_type)
+
+        begin
+          @communicator_logger.log(log_msg_builder.get_message)
+        rescue => e
+          @communicator_logger.log("An error occurred trying to log request #{requestId}", e)
+        end
+      end
+
+      def log_response(requestId, status_code, start_time, args={})
+        return unless @communicator_logger
+
+        duration = (Time.now - start_time) * 1000 # in millisecs
+        headers, body, content_type = args[:headers], args[:body], args[:content_type]
+        log_msg_builder = Ingenico::Connect::SDK::Logging::ResponseLogMessageBuilder.new(requestId, status_code, duration)
+        headers.each { |k, v| log_msg_builder.add_headers(k, v) } if headers
+        log_msg_builder.set_body(body, content_type)
+
+        begin
+          @communicator_logger.log(log_msg_builder.get_message)
+        rescue => e
+          @communicator_logger.log("An error occurred trying to log response #{requestId}", e)
+        end
+      end
+
+      def log_error(requestId, start_time, thrown)
+        return unless @communicator_logger
+        duration = (Time.now - start_time) * 1000 # in millisecs
+        @communicator_logger.log("Error occurred for outgoing request (requestId='#{requestId}', #{duration} ms)", thrown)
+      end
+    end
+  end
+end