killbill 4.0.0 → 4.1.0

data/lib/killbill/helpers/active_merchant/gateway.rb

@@ -4,15 +4,16 @@ module Killbill
       require 'active_merchant'
 
       class Gateway
-        def self.wrap(gateway_builder, config)
-          Gateway.new(config, gateway_builder.call(config))
+        def self.wrap(gateway_builder, config, logger)
+          Gateway.new(config, gateway_builder.call(config), logger)
         end
 
         attr_reader :config
 
-        def initialize(config, am_gateway)
+        def initialize(config, am_gateway, logger)
           @config = config
           @gateway = am_gateway
+          @logger = logger
 
           # Override urls if needed (there is no easy way to do it earlier, because AM uses class_attribute)
           @gateway.class.test_url = @config[:test_url] unless @config[:test_url].nil?
@@ -57,19 +58,89 @@ module Killbill
         end
 
         def method_missing(m, *args, &block)
+          options = {}
+
           # The options hash should be the last argument, iterate through all to be safe
           args.reverse.each do |arg|
-            if arg.respond_to?(:has_key?) && Utils.normalized(arg, :skip_gw)
-              return ::ActiveMerchant::Billing::Response.new(true, 'Skipped Gateway call')
+            if arg.respond_to?(:has_key?)
+              options = arg
+              return ::ActiveMerchant::Billing::Response.new(true, 'Skipped Gateway call') if Utils.normalized(arg, :skip_gw)
             end
           end
 
           @gateway.send(m, *args, &block)
+        rescue ::ActiveMerchant::ConnectionError => e
+          # Need to unwrap it
+          until e.triggering_exception.nil?
+            e = e.triggering_exception
+            break unless e.is_a?(::ActiveMerchant::ConnectionError)
+          end
+          handle_exception(e, options)
+        rescue => e
+          handle_exception(e, options)
         end
 
         def respond_to?(method, include_private=false)
           @gateway.respond_to?(method, include_private) || super
         end
+
+        private
+
+        UNKNOWN_CONNECTION_ERRORS = [
+            # Corrupted stream (e.g. Zlib::BufError)
+            ::ActiveMerchant::InvalidResponseError,
+            # We attempted a payment, but the gateway replied >= 300. This is gateway specific, hopefully the individual
+            # gateway implementation knows how to rescue from it and this is not risen
+            ::ActiveMerchant::ResponseError,
+            # Should not be risen directly
+            ::ActiveMerchant::RetriableConnectionError,
+            ::ActiveMerchant::ActiveMerchantError
+        ]
+
+        PROBABLY_UNKNOWN_CONNECTION_ERRORS = [
+            EOFError,
+            Errno::ECONNRESET,
+            Timeout::Error,
+            Errno::ETIMEDOUT
+        ]
+
+        SAFE_CONNECTION_ERRORS = [
+            SocketError,
+            Errno::EHOSTUNREACH,
+            Errno::ECONNREFUSED,
+            ::OpenSSL::SSL::SSLError,
+            # Invalid certificate (e.g. OpenSSL::X509::CertificateError)
+            ::ActiveMerchant::ClientCertificateError
+        ]
+
+        # See https://github.com/killbill/killbill-plugin-framework-ruby/issues/44
+        def handle_exception(e, options = {})
+          message = "#{e.class} #{e.message}"
+
+          if SAFE_CONNECTION_ERRORS.include?(e.class)
+            # Easy case: we didn't attempt the payment
+            @logger.warn("Connection error with the gateway: #{message}")
+            payment_plugin_status = :CANCELED
+          else
+            # For anything else, tell Kill Bill we don't know. If the gateway supports retrieving a payment status,
+            # the plugin should implement get_payment_info accordingly for the Janitor.
+            # Otherwise, the transaction will need to be fixed manually using the admin APIs.
+
+            # Note that PROBABLY_UNKNOWN_CONNECTION_ERRORS/UNKNOWN_CONNECTION_ERRORS are a bit _better_, as they can be expected and we don't have any control over them.
+            # Any other exception might be caused by a bug in our code!
+            if PROBABLY_UNKNOWN_CONNECTION_ERRORS.include?(e.class) || UNKNOWN_CONNECTION_ERRORS.include?(e.class)
+              @logger.warn("Unstable connection with the gateway: #{message}")
+            else
+              @logger.warn("Unexpected exception: #{message}")
+            end
+
+            # Allow clients to force a PLUGIN_FAILURE instead of UNKNOWN (the default is a conservative behavior)
+            payment_plugin_status = Utils.normalized(options, :connection_errors_safe) ? :CANCELED : :UNDEFINED
+          end
+
+          response_message = { :exception_class => e.class.to_s, :exception_message => e.message, :payment_plugin_status => payment_plugin_status }.to_json
+          ::ActiveMerchant::Billing::Response.new(false, response_message)
+        end
       end
     end
   end

data/lib/killbill/helpers/active_merchant/payment_plugin.rb

@@ -406,7 +406,7 @@ module Killbill
           end
 
           # Filter before all gateways call
-          before_gateways(kb_transaction, last_transaction, payment_source, amount_in_cents, currency, options)
+          before_gateways(kb_transaction, last_transaction, payment_source, amount_in_cents, currency, options, context)
 
           # Dispatch to the gateways. In most cases (non split settlements), we only dispatch to a single gateway account
           gw_responses                  = []
@@ -424,14 +424,14 @@ module Killbill
             gateway = lookup_gateway(payment_processor_account_id, context.tenant_id)
 
             # Filter before each gateway call
-            before_gateway(gateway, kb_transaction, last_transaction, payment_source, amount_in_cents, currency, options)
+            before_gateway(gateway, kb_transaction, last_transaction, payment_source, amount_in_cents, currency, options, context)
 
             # Perform the operation in the gateway
             gw_response           = gateway_call_proc.call(gateway, linked_transaction, payment_source, amount_in_cents, options)
             response, transaction = save_response_and_transaction(gw_response, operation, kb_account_id, context.tenant_id, payment_processor_account_id, kb_payment_id, kb_payment_transaction_id, operation.upcase, amount_in_cents, currency)
 
             # Filter after each gateway call
-            after_gateway(response, transaction, gw_response)
+            after_gateway(response, transaction, gw_response, context)
 
             gw_responses << gw_response
             responses << response
@@ -439,7 +439,7 @@ module Killbill
           end
 
           # Filter after all gateways call
-          after_gateways(responses, transactions, gw_responses)
+          after_gateways(responses, transactions, gw_responses, context)
 
           # Merge data
           merge_transaction_info_plugins(payment_processor_account_ids, responses, transactions)
@@ -453,18 +453,22 @@ module Killbill
           kb_transaction
         end
 
-        def before_gateways(kb_transaction, last_transaction, payment_source, amount_in_cents, currency, options)
+        # Default nil value for context only for backward compatibility (Kill Bill 0.14.0)
+        def before_gateways(kb_transaction, last_transaction, payment_source, amount_in_cents, currency, options, context = nil)
         end
 
-        def after_gateways(response, transaction, gw_response)
+        # Default nil value for context only for backward compatibility (Kill Bill 0.14.0)
+        def after_gateways(response, transaction, gw_response, context = nil)
         end
 
-        def before_gateway(gateway, kb_transaction, last_transaction, payment_source, amount_in_cents, currency, options)
+        # Default nil value for context only for backward compatibility (Kill Bill 0.14.0)
+        def before_gateway(gateway, kb_transaction, last_transaction, payment_source, amount_in_cents, currency, options, context = nil)
           # Can be used to implement idempotency for example: lookup the payment in the gateway
           # and pass options[:skip_gw] if the payment has already been through
         end
 
-        def after_gateway(response, transaction, gw_response)
+        # Default nil value for context only for backward compatibility (Kill Bill 0.14.0)
+        def after_gateway(response, transaction, gw_response, context = nil)
         end
 
         def to_cents(amount, currency)

data/lib/killbill/helpers/catalog.rb

@@ -0,0 +1,15 @@
+require 'killbill/plugin'
+
+module Killbill
+  module Plugin
+    class CatalogPluginApi < Notification
+
+      class OperationUnsupported < NotImplementedError
+      end
+
+      def get_versioned_plugin_catalog(properties, context)
+        raise OperationUnsupported
+      end
+    end
+  end
+end

data/lib/killbill/payment_control.rb

@@ -0,0 +1,23 @@
+require 'killbill/plugin'
+
+module Killbill
+  module Plugin
+    class PaymentRoutingPluginApi < Notification
+
+      class OperationUnsupportedByGatewayError < NotImplementedError
+      end
+
+      def prior_call(routing_context, properties)
+        raise OperationUnsupportedByGatewayError
+      end
+
+      def on_success_call(routing_context, properties)
+        raise OperationUnsupportedByGatewayError
+      end
+
+      def on_failure_call(routing_context, properties)
+        raise OperationUnsupportedByGatewayError
+      end
+    end
+  end
+end

data/lib/killbill/version.rb

@@ -0,0 +1,3 @@
+module Killbill
+  VERSION = '4.1.0'
+end

data/spec/killbill/helpers/configuration_spec.rb

@@ -19,6 +19,16 @@ describe Killbill::Plugin::ActiveMerchant do
     do_initialize_with_config_path!(nil)
   end
 
+  # See https://github.com/killbill/killbill-plugin-framework-ruby/issues/46
+  it 'handles gracefully mis-configurations' do
+    do_initialize_without_config(Proc.new { |config| config[:login] })
+
+    do_common_checks
+
+    gw = ::Killbill::Plugin::ActiveMerchant.gateways(call_context.tenant_id)
+    gw.should be_empty
+  end
+
   it 'should support multi-tenancy configurations' do
     do_initialize!(<<-eos)
   :login: admin
@@ -211,17 +221,21 @@ describe Killbill::Plugin::ActiveMerchant do
     end
   end
 
-  def do_initialize_with_config_path!(path = nil, gw_builder = Proc.new { |config| config })
+  def do_initialize_without_config(gw_builder = Proc.new { |config| config })
+    do_initialize_with_config_path!(nil, gw_builder, svcs_with_per_tenant_config(':nothing:'))
+  end
+
+  def do_initialize_with_config_path!(path = nil, gw_builder = Proc.new { |config| config }, per_tenant_config = svcs_with_per_tenant_config)
     ::Killbill::Plugin::ActiveMerchant.initialize!(gw_builder,
                                                    :test,
                                                    logger,
                                                    :KEY,
                                                    path,
-                                                   ::Killbill::Plugin::KillbillApi.new('test', svcs_with_per_tenant_config))
+                                                   ::Killbill::Plugin::KillbillApi.new('test', per_tenant_config))
   end
 
-  def svcs_with_per_tenant_config
-    per_tenant_config =<<-oes
+  def svcs_with_per_tenant_config(per_tenant_config = nil)
+    per_tenant_config ||=<<-oes
 :test:
   :login: admin2
   :password: password2

data/spec/killbill/helpers/payment_plugin_spec.rb

@@ -311,16 +311,14 @@ describe Killbill::Plugin::ActiveMerchant::PaymentPlugin do
   end
 
   context 'with a dummy gateway' do
-    let(:gateway) { DummyRecordingGateway.new }
+    let(:gateway) { plugin.lookup_gateway(:default, @call_context.tenant_id) }
 
     let(:plugin) do
-      plugin = ::Killbill::Plugin::ActiveMerchant::PaymentPlugin.new(Proc.new { |config| gateway },
-                                                                     :test,
-                                                                     ::Killbill::Test::TestPaymentMethod,
-                                                                     ::Killbill::Test::TestTransaction,
-                                                                     ::Killbill::Test::TestResponse)
-      plugin.kb_apis = kb_apis
-      plugin.logger = logger
+      jplugin.delegate_plugin
+    end
+
+    let(:jplugin) do
+      ze_jplugin = nil
 
       plugin_config = {
           :test => [
@@ -328,14 +326,20 @@ describe Killbill::Plugin::ActiveMerchant::PaymentPlugin do
           ]
       }
       with_plugin_yaml_config('test.yml', plugin_config) do |file|
-        plugin.conf_dir = File.dirname(file)
-        plugin.root = File.dirname(file)
+        ze_jplugin = ::Killbill::Plugin::Api::PaymentPluginApi.new('DummyRecordingGatewayPlugin',
+                                                                   {
+                                                                       'payment_api' => payment_api,
+                                                                       'tenant_user_api' => tenant_api,
+                                                                       'logger' => logger,
+                                                                       'conf_dir' => File.dirname(file),
+                                                                       'root' => File.dirname(file)
+                                                                   })
 
         # Start the plugin here - since the config file will be deleted
-        plugin.start_plugin
+        ze_jplugin.start_plugin
       end
 
-      plugin
+      ze_jplugin
     end
 
     after(:each) do
@@ -347,51 +351,46 @@ describe Killbill::Plugin::ActiveMerchant::PaymentPlugin do
     end
 
     it 'sets the kb_payment_transaction_id as order_id by default' do
-      plugin.add_payment_method(@kb_account_id, @kb_payment_method_id, @payment_method_props, true, [], @call_context)
-
-      kb_payment_transaction_id = SecureRandom.uuid
-      plugin.purchase_payment(@kb_account_id, @kb_payment_id, kb_payment_transaction_id, @kb_payment_method_id, @amount_in_cents, @currency, [], @call_context)
+      ptip = trigger_purchase
 
       sent_options = gateway.call_stack[-1][:options]
       sent_options.size.should == 11
       sent_options[:currency].should == @currency
-      sent_options[:description].should == "Kill Bill purchase for #{kb_payment_transaction_id}"
-      sent_options[:order_id].should == kb_payment_transaction_id
+      sent_options[:description].should == "Kill Bill purchase for #{ptip.kb_transaction_payment_id}"
+      sent_options[:order_id].should == ptip.kb_transaction_payment_id
     end
 
     it 'sets the kb_payment_transaction_id as order_id if specified' do
-      plugin.add_payment_method(@kb_account_id, @kb_payment_method_id, @payment_method_props, true, [], @call_context)
-
       property = ::Killbill::Plugin::Model::PluginProperty.new
       property.key = 'external_key_as_order_id'
       property.value = 'false'
+      properties = [property]
 
-      kb_payment_transaction_id = SecureRandom.uuid
-      plugin.purchase_payment(@kb_account_id, @kb_payment_id, kb_payment_transaction_id, @kb_payment_method_id, @amount_in_cents, @currency, [property], @call_context)
+      ptip = trigger_purchase(properties)
 
       sent_options = gateway.call_stack[-1][:options]
       sent_options.size.should == 12
       sent_options[:currency].should == @currency
-      sent_options[:description].should == "Kill Bill purchase for #{kb_payment_transaction_id}"
-      sent_options[:order_id].should == kb_payment_transaction_id
+      sent_options[:description].should == "Kill Bill purchase for #{ptip.kb_transaction_payment_id}"
+      sent_options[:order_id].should == ptip.kb_transaction_payment_id
     end
 
     it 'sets the payment transaction external key as order_id if specified' do
-      plugin.add_payment_method(@kb_account_id, @kb_payment_method_id, @payment_method_props, true, [], @call_context)
-
       property = ::Killbill::Plugin::Model::PluginProperty.new
       property.key = 'external_key_as_order_id'
       property.value = 'true'
+      properties = [property]
 
       kb_payment_transaction_id = SecureRandom.uuid
       kb_payment_transaction_external_key = SecureRandom.uuid
-      payment_api.add_payment(@kb_payment_id,  kb_payment_transaction_id, kb_payment_transaction_external_key, :PURCHASE)
-      plugin.purchase_payment(@kb_account_id, @kb_payment_id, kb_payment_transaction_id, @kb_payment_method_id, @amount_in_cents, @currency, [property], @call_context)
+      payment_api.add_payment(@kb_payment_id, kb_payment_transaction_id, kb_payment_transaction_external_key, :PURCHASE)
+
+      ptip = trigger_purchase(properties, kb_payment_transaction_id)
 
       sent_options = gateway.call_stack[-1][:options]
       sent_options.size.should == 12
       sent_options[:currency].should == @currency
-      sent_options[:description].should == "Kill Bill purchase for #{kb_payment_transaction_id}"
+      sent_options[:description].should == "Kill Bill purchase for #{ptip.kb_transaction_payment_id}"
       sent_options[:order_id].should == kb_payment_transaction_external_key
     end
 
@@ -403,47 +402,152 @@ describe Killbill::Plugin::ActiveMerchant::PaymentPlugin do
 
       ::ActiveRecord::Base.connection_pool.active_connection?.should == false
     end
+
+    # Regression tests for the Kill Bill API conventions
+    # TODO Go through Java generated code
+
+    it 'returns ERROR if the payment transaction went through but failed' do
+      gateway.next_success = false
+
+      # Verify the purchase call for the Kill Bill payment state machine and the get_payment_info call for the Janitor
+      ptip = trigger_purchase
+      verify_purchase_status(ptip, :ERROR)
+
+      # Check debugging fields
+      ptip.gateway_error.should == 'false'
+    end
+
+    it 'returns UNDEFINED for plugin bugs' do
+      gateway.next_exception = NoMethodError.new("undefined method `split' for 12:Fixnum")
+
+      # Verify the purchase call for the Kill Bill payment state machine and the get_payment_info call for the Janitor
+      ptip = trigger_purchase
+      verify_purchase_status(ptip, :UNDEFINED)
+
+      # Check debugging fields
+      ptip.gateway_error.should == "undefined method `split' for 12:Fixnum"
+    end
+
+    # Specific ActiveMerchant errors handling
+    # See https://github.com/Shopify/active_merchant/blob/2e7eebe38020db4d262b91778797910ede2f31be/lib/active_merchant/network_connection_retries.rb#L21-L34
+
+    it 'returns CANCELED if the payment was not attempted' do
+      {
+          Errno::ECONNREFUSED => 'The remote server refused the connection',
+          SocketError => 'The connection to the remote server could not be established',
+          Errno::EHOSTUNREACH => 'The connection to the remote server could not be established',
+          OpenSSL::SSL::SSLError => 'The SSL connection to the remote server could not be established',
+          ::ActiveMerchant::ClientCertificateError => 'The remote server did not accept the provided SSL certificate'
+      }.each do |ek, msg|
+        gateway.next_exception = ::ActiveMerchant::ConnectionError.new(msg, ek.new(msg))
+
+        # Verify the purchase call for the Kill Bill payment state machine and the get_payment_info call for the Janitor
+        ptip = trigger_purchase
+        verify_purchase_status(ptip, :CANCELED)
+
+        # Check debugging fields
+        ptip.gateway_error.ends_with?(msg).should be_true
+        ptip.gateway_error_code.should == ek.to_s
+      end
+    end
+
+    it 'returns UNDEFINED if we are not sure' do
+      {
+          EOFError => 'The remote server dropped the connection',
+          Errno::ECONNRESET => 'The remote server reset the connection',
+          Timeout::Error => 'The connection to the remote server timed out',
+          Errno::ETIMEDOUT => 'The connection to the remote server timed out',
+          ::ActiveMerchant::InvalidResponseError => 'The remote server replied with an invalid response'
+      }.each do |ek, msg|
+        gateway.next_exception = ::ActiveMerchant::ConnectionError.new(msg, ek.new(msg))
+
+        # Verify the purchase call for the Kill Bill payment state machine and the get_payment_info call for the Janitor
+        ptip = trigger_purchase
+        verify_purchase_status(ptip, :UNDEFINED)
+
+        # Check debugging fields
+        ptip.gateway_error.ends_with?(msg).should be_true
+        ptip.gateway_error_code.should == ek.to_s
+      end
+    end
   end
 
   private
 
-  def verify_transaction_info_plugin(t_info_plugin, kb_transaction_id, type, transaction_nb, payment_processor_account_id='default')
+  def trigger_purchase(purchase_properties=[], kb_payment_transaction_id=SecureRandom.uuid)
+    plugin.get_payment_method_detail(@kb_account_id, @kb_payment_method_id, [], @call_context) rescue plugin.add_payment_method(@kb_account_id, @kb_payment_method_id, @payment_method_props, true, [], @call_context)
+    plugin.purchase_payment(@kb_account_id, @kb_payment_id, kb_payment_transaction_id, @kb_payment_method_id, @amount_in_cents, @currency, purchase_properties, @call_context)
+  end
+
+  def verify_purchase_status(t_info_plugin, status)
+    verify_transaction_info_plugin(t_info_plugin, t_info_plugin.kb_transaction_payment_id, :PURCHASE, nil, 'default', status)
+  end
+
+  def verify_transaction_info_plugin(t_info_plugin, kb_transaction_id, type, transaction_nb, payment_processor_account_id='default', status=:PROCESSED)
     t_info_plugin.kb_payment_id.should == @kb_payment_id
     t_info_plugin.kb_transaction_payment_id.should == kb_transaction_id
     t_info_plugin.transaction_type.should == type
-    if type == :VOID
+    if type == :VOID || status != :PROCESSED
       t_info_plugin.amount.should be_nil
       t_info_plugin.currency.should be_nil
     else
       t_info_plugin.amount.should == @amount_in_cents
       t_info_plugin.currency.should == @currency
     end
-    t_info_plugin.status.should == :PROCESSED
+    t_info_plugin.status.should == status
 
     # Verify we routed to the right gateway
     (t_info_plugin.properties.find { |kv| kv.key.to_s == 'payment_processor_account_id' }).value.to_s.should == payment_processor_account_id
 
     transactions = plugin.get_payment_info(@kb_account_id, @kb_payment_id, [], @call_context)
-    transactions.size.should == transaction_nb
-    transactions[transaction_nb - 1].to_json.should == t_info_plugin.to_json
+    transactions.size.should == transaction_nb unless transaction_nb.nil?
+    transactions[-1].to_json.should == t_info_plugin.to_json
+  end
+
+  class DummyRecordingGatewayPlugin < ::Killbill::Plugin::ActiveMerchant::PaymentPlugin
+
+    def initialize
+      super(Proc.new { |config| DummyRecordingGateway.new },
+            :test,
+            ::Killbill::Test::TestPaymentMethod,
+            ::Killbill::Test::TestTransaction,
+            ::Killbill::Test::TestResponse)
+    end
   end
 
   class DummyRecordingGateway < ::ActiveMerchant::Billing::Gateway
 
     attr_reader :call_stack
+    attr_writer :next_success, :next_exception
 
     def initialize
       @call_stack = []
+      @next_success = true
+      @next_exception = nil
     end
 
     def purchase(money, paysource, options = {})
+      success = before_purchase
       @call_stack << {:money => money, :source => paysource, :options => options}
-      ::ActiveMerchant::Billing::Response.new(true, 'Success!', {:authorized_amount => money}, :test => true, :authorization => 12345)
+      ::ActiveMerchant::Billing::Response.new(success, success.to_s, {:authorized_amount => money}, :test => true, :authorization => '12345')
     end
 
     def store(paysource, options = {})
       @call_stack << {:source => paysource, :options => options}
-      ::ActiveMerchant::Billing::Response.new(true, 'Success!', {:billingid => '1'}, :test => true, :authorization => 12345)
+      ::ActiveMerchant::Billing::Response.new(true, 'Success!', {:billingid => '1'}, :test => true, :authorization => '12345')
+    end
+
+    # Testing helpers
+
+    def before_purchase
+      unless @next_exception.nil?
+        e = @next_exception
+        @next_exception = nil
+        raise e
+      end
+      s = @next_success
+      @next_success = true
+      s
     end
   end
 end