direct-sdk-ruby 1.0.0

data/lib/ingenico/direct/sdk/exceptions.rb

@@ -0,0 +1,8 @@
+prefix = 'ingenico/direct/sdk/'
+suffix = '_exception'
+exception_types = %w[api authorization communication declined_transaction
+                    declined_payment declined_refund
+                    direct idempotence marshaller_syntax not_found
+                    reference response validation]
+
+exception_types.each { |type| require prefix + type + suffix }

data/lib/ingenico/direct/sdk/factory.rb

@@ -0,0 +1,136 @@
+require 'yaml'
+
+module Ingenico::Direct::SDK
+
+  # Convenience class that constructs instances of several other classes in the SDK.
+  # Provides methods to construct
+  # {Ingenico::Direct::SDK::CommunicatorConfiguration}, {Ingenico::Direct::SDK::Communicator} and {Ingenico::Direct::SDK::Client} instances.
+  class Factory
+
+    # Creates and returns a {Ingenico::Direct::SDK::CommunicatorConfiguration} based on the configuration in the file located at _configuration_file_name_.
+    #
+    # @param config_file_name [String] Path to the configuration file to use, should be in YAML format.
+    # @param api_key_id       [String] Key id for the GlobalCollect service.
+    # @param secret_api_key   [String] Secret key used for authentication to the GlobalCollect service.
+    # @return [Ingenico::Direct::SDK::CommunicatorConfiguration] The created communicator configuration
+    def self.create_configuration(config_file_name, api_key_id, secret_api_key)
+      properties = YAML::load_file(config_file_name)
+      CommunicatorConfiguration.new(properties: properties,
+                                    api_key_id: api_key_id,
+                                    secret_api_key: secret_api_key)
+    end
+
+    # Creates and returns an {Ingenico::Direct::SDK::Communicator} that can be used for communication with the GlobalCollect service.
+    #
+    # @param configuration      [Ingenico::Direct::SDK::CommunicatorConfiguration] contains configuration settings to be used by the client.
+    # @param meta_data_provider [Ingenico::Direct::SDK::MetaDataProvider,nil] stores the metadata for the communicating client.
+    # @param connection         [Ingenico::Direct::SDK::Connection,nil] connection that can be used to communicate with the Ingenico Direct platform.
+    # @param authenticator      [Ingenico::Direct::SDK::Authenticator,nil] authenticator that can authenticate messages sent to the Ingenico Direct platform.
+    # @param marshaller         [Ingenico::Direct::SDK::Marshaller,nil] marshaller that marshalls and unmarshalls messages sent to the Ingenico Direct platform.
+    # @return [Ingenico::Direct::SDK::Communicator] The created communicator
+    def self.create_communicator_from_configuration(configuration, meta_data_provider: nil, connection: nil, authenticator: nil, marshaller: DefaultImpl::DefaultMarshaller.INSTANCE)
+      meta_data_provider ||= MetaDataProvider.new(configuration.integrator, shopping_cart_extension: configuration.shopping_cart_extension)
+      connection ||= DefaultImpl::DefaultConnection.new({ connect_timeout: configuration.connect_timeout,
+                                                          socket_timeout: configuration.socket_timeout,
+                                                          max_connections: configuration.max_connections,
+                                                          proxy_configuration: configuration.proxy_configuration })
+      authenticator ||= DefaultImpl::DefaultAuthenticator.new(configuration.api_key_id,
+                                                              configuration.secret_api_key,
+                                                              configuration.authorization_type)
+      Communicator.new(configuration.api_endpoint, connection, authenticator, meta_data_provider, marshaller)
+    end
+
+    # Creates and returns an {Ingenico::Direct::SDK::Communicator} that is used for communication with the GlobalCollect service.
+    #
+    # @param config_file_name   [String] Path to the configuration file to use, should be in YAML format.
+    # @param api_key_id         [String] Key id for the GlobalCollect service.
+    # @param secret_api_key     [String] Secret key used for authentication to the GlobalCollect service.
+    # @param meta_data_provider [Ingenico::Direct::SDK::MetaDataProvider,nil] stores the metadata for the communicating client.
+    # @param connection         [Ingenico::Direct::SDK::Connection,nil] connection that can be used to communicate with the Ingenico Direct platform.
+    # @param authenticator      [Ingenico::Direct::SDK::Authenticator,nil] authenticator that can authenticate messages sent to the Ingenico Direct platform.
+    # @return [Ingenico::Direct::SDK::Communicator] The created communicator
+    def self.create_communicator_from_file(config_file_name, api_key_id, secret_api_key,
+                                           meta_data_provider: nil, connection: nil, authenticator: nil,
+                                           marshaller: DefaultImpl::DefaultMarshaller.INSTANCE)
+      configuration = create_configuration(config_file_name, api_key_id, secret_api_key)
+      create_communicator_from_configuration(configuration, meta_data_provider: meta_data_provider, connection: connection,
+                                             authenticator: authenticator, marshaller: marshaller)
+    end
+
+    # Creates and returns an {Ingenico::Direct::SDK::Client} that provides the a high-level interface with the GlobalCollect service.
+    # If a code block is given, the created client is returned to the code block and closed afterwards.
+    #
+    # @example Providing a code block
+    #           Factory.create_client_from_configuration(configuration) do |client|
+    #             client.merchant(merchant_id).services.testconnection
+    #           end
+    #           # client is closed here
+    #
+    # @param configuration [Ingenico::Direct::SDK::CommunicatorConfiguration] contains configuration settings to be used by the client.
+    # @return [Ingenico::Direct::SDK::Client] The created client
+    def self.create_client_from_configuration(configuration)
+      communicator = create_communicator_from_configuration(configuration)
+      client = Client.new(communicator)
+      if block_given?
+        begin
+          yield client
+        ensure
+          client.close
+        end
+      else
+        return client
+      end
+    end
+
+    # Creates and returns an {Ingenico::Direct::SDK::Client} that provides the a high-level interface with the GlobalCollect service.
+    # If a code block is given, the created client is returned to the code block and closed afterwards.
+    #
+    # @example Providing a code block
+    #           Factory.create_client_from_communicator(communicator) do |client|
+    #             client.merchant(merchant_id).services.testconnection
+    #           end
+    #           # client is closed here
+    #
+    # @param communicator [Ingenico::Direct::SDK::Communicator] provides network communication service for the Client
+    # @return [Ingenico::Direct::SDK::Client] The created client
+    def self.create_client_from_communicator(communicator)
+      client = Client.new(communicator)
+      if block_given?
+        begin
+          yield client
+        ensure
+          client.close
+        end
+      else
+        return client
+      end
+    end
+
+    # Creates and returns an {Ingenico::Direct::SDK::Client} that provides the a high-level interface with the GlobalCollect service.
+    # If a code block is given, the created client is returned to the code block and closed afterwards.
+    #
+    # @example Providing a code block
+    #           Factory.create_client_from_file(config_file_name, api_key_id, secret_api_key) do |client|
+    #             client.merchant(merchant_id).services.testconnection
+    #           end
+    #           # client is closed here
+    #
+    # @param config_file_name [String] Path to the configuration file to use, should be in YAML format.
+    # @param api_key_id       [String] Key id for the GlobalCollect service.
+    # @param secret_api_key   [String] Secret key used for authentication to the GlobalCollect service.
+    # @return [Ingenico::Direct::SDK::Client] The created client
+    def self.create_client_from_file(config_file_name, api_key_id, secret_api_key)
+      communicator = create_communicator_from_file(config_file_name, api_key_id, secret_api_key)
+      client = Client.new(communicator)
+      if block_given?
+        begin
+          yield client
+        ensure
+          client.close
+        end
+      else
+        return client
+      end
+    end
+  end
+end

data/lib/ingenico/direct/sdk/idempotence_exception.rb

@@ -0,0 +1,24 @@
+module Ingenico::Direct::SDK
+
+  # This exception is thrown when a response from the Ingenico ePayments platform indicates
+  # a request with the same _idempotence_key_ was received earlier.
+  # The _idempotence_request_timestamp_ indicates the time when the first request with this _idempotence_key_ arrived.
+  #
+  # @attr_reader [String] idempotence_key                The idempotence key used in the request.
+  # @attr_reader [Integer] idempotence_request_timestamp A timestamp indicating the arrival time of the request that conflicts with the request just sent.
+  class IdempotenceException < ApiException
+
+    # Create a new IdempotenceException
+    # @see ApiException#initialize
+    def initialize(status_code, response_body, error_id, errors, idempotence_key,
+                   idempotence_request_timestamp,
+                   message='the Ingenico ePayments platform returned a duplicate request error response')
+      super(status_code, response_body, error_id, errors, message)
+      @idempotence_key = idempotence_key
+      @idempotence_request_timestamp = idempotence_request_timestamp
+    end
+
+    attr_reader :idempotence_key
+    attr_reader :idempotence_request_timestamp
+  end
+end

data/lib/ingenico/direct/sdk/logging.rb

@@ -0,0 +1,10 @@
+prefix = 'ingenico/direct/sdk/logging'
+
+require "#{prefix}/logging_capable"
+require "#{prefix}/log_message_builder"
+require "#{prefix}/request_log_message_builder"
+require "#{prefix}/response_log_message_builder"
+require "#{prefix}/logging_util"
+require "#{prefix}/communicator_logger"
+require "#{prefix}/ruby_communicator_logger"
+require "#{prefix}/stdout_communicator_logger"

data/lib/ingenico/direct/sdk/logging/communicator_logger.rb

@@ -0,0 +1,22 @@
+module Ingenico::Direct::SDK
+  module Logging
+
+    # Base logger class used in this SDK. This class is an interface and cannot be instantiated.
+    class CommunicatorLogger
+      # Interface, no instantiation
+      # @see Ingenico::Direct::SDK::Logging::StdoutCommunicatorLogger
+      # @see Ingenico::Direct::SDK::Logging::RubyCommunicatorLogger
+      def initialize
+        raise NotImplementedError, "#{self.class.name} is not implemented."
+      end
+
+      # Logs a message with or without exception
+      #
+      # @param message [String] the message to log
+      # @param thrown  [Exception, false] the exception to log, or false to log no exception
+      def log(message, thrown = false)
+        raise NotImplementedError, "#{self.class.name}#log() is not implemented."
+      end
+    end
+  end
+end

data/lib/ingenico/direct/sdk/logging/log_message_builder.rb

@@ -0,0 +1,56 @@
+module Ingenico::Direct::SDK
+  module Logging
+
+    # Abstract class used to construct a message describing a request or response.
+    #
+    # @attr_reader [String] request_id   An identifier assigned to the request and response
+    # @attr_reader [String] headers      Request or response headers in string form
+    # @attr_reader [String] body         Request or response body as a string
+    # @attr_reader [String] content_type Content type of the body, generally 'application/json' or 'text/html'
+    class LogMessageBuilder
+
+      attr_reader :request_id
+      attr_reader :headers
+      attr_reader :body
+      attr_reader :content_type
+
+      # Create a new LogMessageBuilder
+      def initialize(request_id)
+        raise ArgumentError if request_id.nil? || request_id.empty?
+        @request_id = request_id
+        @headers = ''
+      end
+
+      # Adds a single header to the #headers string
+      def add_headers(name, value)
+        @headers += ', ' unless @headers.empty?
+        @headers += "#{name}='#{LoggingUtil.obfuscate_header(name, value)}'"
+      end
+
+      # Sets the body of this message to the parameter body.
+
+      # @param body         [String] the message body
+      # @param content_type [String] the content type of the body
+      def set_body(body, content_type)
+        @body = LoggingUtil.obfuscate_body(body)
+        @content_type = content_type
+      end
+
+      # Constructs and returns the log message as a string.
+      def get_message
+        raise NotImplementedError, "#{self.class.name}#get_message() is not implemented."
+      end
+
+      def to_s
+        self.class == LogMessageBuilder ?
+            super.to_s :
+            get_message
+      end
+
+      # Returns an empty string if the parameter is nil, and returns the parameter itself otherwise
+      protected def empty_if_null(value)
+        value.nil? ? '' : value
+      end
+    end
+  end
+end

data/lib/ingenico/direct/sdk/logging/logging_capable.rb

@@ -0,0 +1,19 @@
+module Ingenico
+  module Direct
+    module SDK
+      module Logging
+
+        # Abstract mixin module that allows loggers to be registered to an object.
+        module LoggingCapable
+          def enable_logging(communicator_logger)
+            raise NotImplementedError
+          end
+
+          def disable_logging
+            raise NotImplementedError
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ingenico/direct/sdk/logging/logging_util.rb

@@ -0,0 +1,271 @@
+module Ingenico::Direct::SDK
+  module Logging
+
+    # Class responsible for obfuscating sensitive data in a message body.
+    class ValueObfuscator
+
+      class << self
+
+        alias_method :private_new, :new
+
+        protected :private_new, :new
+      end
+
+      public
+
+      def self.INSTANCE
+        # use lazy instantiation
+        @@INSTANCE ||= ValueObfuscator.new
+      end
+
+      # Obfuscates the parameter value.
+      def obfuscate_value(value)
+        (value.nil? or value.empty?) ? value : "*#{value.length}"
+      end
+    end # end of ValueObfuscator
+
+    # Class responsible for obfuscating sensitive data.
+    class SensitiveValueObfuscator
+
+      class << self
+
+        alias_method :private_new, :new
+
+        protected :private_new, :new
+      end
+      public
+
+      def self.INSTANCE
+        # use lazy instantiation
+        @@INSTANCE ||= SensitiveValueObfuscator.new
+      end
+
+      # @return an arbitrary number of '*', or null/empty if the value is null/empty.
+      def obfuscate_value(value)
+        value.nil? or value.empty? ? value : "***"
+      end
+    end # end of SensitiveValueObfuscator
+
+    class Obfuscator
+      def initialize(obfuscators, case_insensitive)
+        raise ArgumentError unless obfuscators.is_a? Hash
+        @obfuscators = copy(obfuscators, case_insensitive)
+      end
+
+      private
+
+      # case insensitive hash
+      # @private
+      class HashClod < Hash
+
+        def initialize(other)
+          other.each { |k, v| self.[]=(k, v) }
+        end
+
+        def [](key)
+          super _insensitive(key)
+        end
+
+        def []=(key, value)
+          super _insensitive(key), value
+        end
+
+        protected
+
+        def _insensitive(key)
+          key.respond_to?(:upcase) ? key.upcase : key
+        end
+      end # end of HashClod
+
+      def copy(obfuscators, case_insensitive)
+        cp = case_insensitive ? HashClod.new(obfuscators) : obfuscators
+        Marshal.load(Marshal.dump(cp)) # deep copy
+      end
+
+      public
+
+      def obfuscate_value(key, value)
+        obfuscator = @obfuscators[key]
+        if obfuscator.nil?
+            value
+        else
+          obfuscator.obfuscate_value(value)
+        end
+      end
+
+      # A convenient wrapper to build obfuscators
+      class Builder
+        attr_accessor :obfuscators
+
+        def initialize
+          raise NotImplementedError, "#{self.class.name} is not implemented."
+        end
+
+        def with_field(key)
+          @obfuscators[key] = ValueObfuscator.INSTANCE
+          self
+        end
+
+        def with_sensitive_field(key)
+          @obfuscators[key] = SensitiveValueObfuscator.INSTANCE
+          self
+        end
+
+        def build
+          raise NotImplementedError, "#{self.class.name}#build() is not implemented."
+        end
+      end # Builder
+    end # Obfuscator
+
+    # Class that obfuscates headers of a message
+    class HeaderObfuscator < Obfuscator
+      def initialize(obfuscators)
+        # case insensitive
+        super(obfuscators, true)
+      end
+
+      def self.builder
+        Builder.new
+      end
+
+      class Builder < Obfuscator::Builder
+        def initialize
+          @obfuscators = {}
+        end
+
+        def with_field(name)
+          raise ArgumentError unless name.is_a? String
+          super(name)
+        end
+
+        def with_sensitive_field(name)
+          raise ArgumentError unless name.is_a? String
+          super(name)
+        end
+
+        def build
+          HeaderObfuscator.new(obfuscators)
+        end
+      end
+    end # end of HeadObfuscator
+
+    # Class that obfuscates properties in the JSON body of a message
+    class PropertyObfuscator < Obfuscator
+      def initialize(obfuscators)
+        # case sensitive
+        super(obfuscators, false)
+        @property_pattern = build_property_pattern(obfuscators.keys)
+      end
+
+      private
+
+      def build_property_pattern(pn)
+        return /$^/ if pn.empty? # no possible match
+        # Regex to create:
+        # (["'])(X|Y|Z)\1\s*:\s*(?:(["'])(.*?)(?<!\\)\3|([^"'\s\[\{]\S*))
+        # Groups:
+        # 1: opening " or ' for the property name
+        # 2: property name
+        # 3: opening " or ' for the value
+        # 4: quoted value
+        # 5: non-quoted-value
+        # The negative lookbehind is to allow escaped quotes to be part of
+        # the value. What this does not allow currently is having values end
+        # with a \ (which would be escaped to \\).
+        regex = pn.inject("([\"'])(") { |r, p| "#{r}#{Regexp.quote(p)}|"}.chop <<
+          ")\\1\\s*:\\s*(?:([\"'])(.*?)(?<!\\\\)\\3|([^\"'\\s\\[\\{]((?!,)\\S)*))"
+        /#{regex}/m # dotall mode
+      end
+
+      public
+
+      def obfuscate(body)
+        return nil if body.nil?
+        return "" if body.empty?
+
+        body.gsub(@property_pattern) do
+          m = Regexp.last_match
+          property_name = m[2]
+          value = m[4] || m[5]
+          # copy value 'cause it's part of m[0]
+          m[0].sub(value, obfuscate_value(property_name, value.dup))
+        end
+      end
+
+      def self.builder
+        Builder.new
+      end
+
+      class Builder < Obfuscator::Builder
+        def initialize
+          @obfuscators = {}
+        end
+
+        def with_field(property)
+          raise ArgumentError unless property.is_a? String
+          super(property)
+        end
+
+        def with_sensitive_field(property)
+          raise ArgumentError unless property.is_a? String
+          super(property)
+        end
+
+        def build
+          PropertyObfuscator.new(obfuscators)
+        end
+      end
+    end # end of property obfuscator
+
+    module LoggingUtil
+      @@PROPERTY_OBFUSCATOR = PropertyObfuscator.builder
+        .with_field("cardNumber")
+        .with_field("expiryDate")
+        .with_field("cvv")
+        .with_field("iban")
+        .with_field("accountNumber")
+        .with_field("reformattedAccountNumber")
+        .with_field("additionalInfo")
+        .with_field("cardholderName")
+        .with_field("dateOfBirth")
+        .with_field("emailAddress")
+        .with_field("faxNumber")
+        .with_field("firstName")
+        .with_field("houseNumber")
+        .with_field("mobilePhoneNumber")
+        .with_field("passengerName")
+        .with_field("phoneNumber")
+        .with_field("street")
+        .with_field("surname")
+        .with_field("workPhoneNumber")
+        .with_field("zip")
+        .with_field("bin")
+        .with_field("value")
+        .with_sensitive_field("keyId")
+        .with_sensitive_field("secretKey")
+        .with_sensitive_field("publicKey")
+        .with_sensitive_field("userAuthenticationToken")
+        .with_sensitive_field("encryptedPayload")
+        .with_sensitive_field("decryptedPayload")
+        .with_sensitive_field("encryptedCustomerInput")
+        .build
+
+      @@HEADER_OBFUSCATOR = HeaderObfuscator.builder
+        .with_sensitive_field("Authorization")
+        .with_sensitive_field("WWW-Authenticate")
+        .with_sensitive_field("Proxy-Authenticate")
+        .with_sensitive_field("Proxy-Authorization")
+        .with_sensitive_field("X-GCS-Authentication-Token")
+        .with_sensitive_field("X-GCS-CallerPassword")
+        .build
+
+      def self.obfuscate_body(body)
+        @@PROPERTY_OBFUSCATOR.obfuscate(body)
+      end
+
+      def self.obfuscate_header(name, value)
+        @@HEADER_OBFUSCATOR.obfuscate_value(name, value)
+      end
+    end # end of LoggingUtil
+  end
+end