hoodoo 1.7.0 → 1.8.0

checksums.yaml

@@ -1,7 +1,15 @@
 ---
-SHA1:
-  metadata.gz: 21732b5cd34041936e018495404cb3950ff70b85
-  data.tar.gz: b37d1a9ef5e225653be451d8e775ea07cf5a9690
+!binary "U0hBMQ==":
+  metadata.gz: !binary |-
+    MzkyZDI3OGE3NDg2ZDBiODFkZGZlNzhiZGY0YTgzN2FhZDU5OTg4ZA==
+  data.tar.gz: !binary |-
+    NTQzZGI1NjFhMjU3Y2Y4NTM4MDM0YWJiNGI2MDQyZTQ1NDdmYzIzNQ==
 SHA512:
-  metadata.gz: 39c52f8db587f906e2c377ab9fae3939697b872366c07aace735439538f6412fe12efae8996652b746ab31e8704334329e5d71125ca14c60be978f9352aa0308
-  data.tar.gz: bc4e9624bff7ad092b1ca7e0f86e64c2b8c634ee12649fd22bbb27de26d360dd870dfe4d7644639b5cc30fabbd30294e13c004e9efde77cff07f35fe3879a2eb
+  metadata.gz: !binary |-
+    ZjA5YzEwZmFlYWNhMjU0YjcyZTAzMTMzODA5MDZiMzk3NDc3ODBlYWViMGRh
+    MjQ3MWQ2NTA2NDAxYmUyNzBjYjBhNjIzMzNkMGI2NDZlY2ZlZWU3NDk2MDky
+    ZGI0MDVlZmRhZjM4MWI4ZGY4NDNjOTIwODQwOWM3YmYyOTAyNTg=
+  data.tar.gz: !binary |-
+    MDAyNmY0YzY4MDZiMjY4ZDlkODg3MzRhNzFhNzFjNjEwZjNmZmI3ZDMyM2U3
+    N2E4YWU4YTA3OTM4ZjJlYzhiODM3NWRiYzFlYzgxNWYzZjE3OGY1MTIyOGQ2
+    ZTRlZGUzOTkxNGM3ZmVjNTA3NTQ2NzljNTMwYmNjNDVjZjI0MDM=

data/lib/hoodoo.rb

@@ -25,3 +25,6 @@ require 'hoodoo/services'
 require 'hoodoo/middleware'
 
 require 'hoodoo/version'
+
+require 'hoodoo/monkey'
+

data/lib/hoodoo/client/client.rb

@@ -262,9 +262,13 @@ module Hoodoo
         @discoverer = if discoverer != nil
           discoverer
         elsif @base_uri != nil
-          Hoodoo::Services::Discovery::ByConvention.new(
-            :base_uri => @base_uri
-          )
+          if defined?( Hoodoo::Services::Discovery::ByConvention )
+            Hoodoo::Services::Discovery::ByConvention.new(
+              :base_uri => @base_uri
+            )
+          else
+            raise 'Hoodoo::Client: The constructor parameters indicate the use of a "by convention" discoverer. This discoverer requires ActiveSupport; ensure the ActiveSupport gem is present and "require"-able.'
+          end
         elsif @drb_uri != nil || @drb_port != nil
           Hoodoo::Services::Discovery::ByDRb.new(
             :drb_uri  => @drb_uri,

data/lib/hoodoo/client/endpoint/endpoints/amqp.rb

@@ -113,6 +113,28 @@ module Hoodoo
             return do_amqp( d )
           end
 
+          # Ask Alchemy Flux to send a given HTTP message to a resource.
+          #
+          # This method is available for Hoodoo monkey patching but must not
+          # be called by third party code; it's a private method exposed in
+          # the public <tt>monkey_</tt> namespace for patching only. For more,
+          # see:
+          #
+          # * Hoodoo::Monkey
+          # * Hoodoo::Monkey::Patch::NewRelicTracedAMQP
+          #
+          # +http_message+:: Hash describing the message to send.
+          # +full_uri+::     Equivalent full URI of the request (information
+          #                  only; the +http_message+ tells Alchemy Flux how
+          #                  to route the message; it does not consult this
+          #                  parameter).
+          #
+          # The return value is an Alchemy Flux response object.
+          #
+          def monkey_send_request( http_message, full_uri )
+            self.alchemy().send_request_to_resource( http_message )
+          end
+
         private
 
           # Call Alchemy to make an HTTP simulated request over AMQP to a
@@ -164,7 +186,7 @@ module Hoodoo
               http_message[ 'session_id' ] = self.session_id()
             end
 
-            amqp_response = self.alchemy().send_request_to_resource( http_message )
+            amqp_response = monkey_send_request( http_message, data.full_uri )
 
             description_of_response              = DescriptionOfResponse.new
             description_of_response.action       = action
@@ -193,6 +215,7 @@ module Hoodoo
           end
 
       end
+
     end
   end
 end

data/lib/hoodoo/monkey.rb

@@ -0,0 +1,13 @@
+########################################################################
+# File::    monkey.rb
+# (C)::     Loyalty New Zealand 2016
+#
+# Purpose:: Require the Hoodoo monkey patching engine and any built-in
+#           patches, which will enable themselves (or not) according to
+#           their individual RDoc-documented descriptions.
+# ----------------------------------------------------------------------
+#           12-Apr-2016 (ADH): Created.
+########################################################################
+
+require 'hoodoo/monkey/monkey'
+require 'hoodoo/monkey/patch/newrelic_traced_amqp'

data/lib/hoodoo/monkey/monkey.rb

@@ -0,0 +1,308 @@
+########################################################################
+# File::    monkey.rb
+# (C)::     Loyalty New Zealand 2016
+#
+# Purpose:: Official, reversible monkey patching.
+# ----------------------------------------------------------------------
+#           11-Apr-2016 (ADH): Created.
+########################################################################
+
+module Hoodoo
+
+  # Hoodoo provides monkey patching hook points as first class citizens and
+  # includes a registration, enabling and disabling mechanism through the
+  # Hoodoo::Monkey class.
+  #
+  # You encapsulate monkey patch code inside a module. This module will be
+  # used to patch one or more target other classes or modules. Usually, one
+  # module will only be used to patch one other kind of class or module;
+  # re-use of a patch module usually only makes sense when patching one
+  # or more subclasses from a common ancestor where some, but not all of
+  # the subclass types are to be patched (if you wanted to patch all of them
+  # you'd just patch the base class).
+  #
+  # Inside your module, you write one or two sub-modules. One of these
+  # patches instance methods in the target, the other patches class methods.
+  # The mechanism used to patch instance or class methods is different in
+  # Ruby, thus the distinct module use; it also helps keep your code clear
+  # of distracting syntax and make it very obvious what kind of "thing" is
+  # being replaced.
+  #
+  # Monkey patch methods are sent to the patch target using `prepend`, the
+  # Ruby 2 mechanism which means the original overriden implementation can
+  # be called via +super+, just as if you were writing a subclass.
+  #
+  # For examples, see method Hoodoo::Monkey::register.
+  #
+  # Any public method in the API can be patched, since the public API is by
+  # definition public and stable. Sometimes, normally-private methods are
+  # exposed for monkey patching as public methods with the name prefix of
+  # "<tt>monkey_</tt>" - such methods are *NOT* intended to be called by
+  # client code in general, but can be patched. It is only completely safe to
+  # to patch a method in a wrapper fashion, e.g. to filter inputs or outputs;
+  # thus whenever possible, always call +super+ at some point within your
+  # replacement implementation. If you completely replace an implementation
+  # with a custom version, you risk your code breaking even with patch level
+  # changes to Hoodoo, since only the public _interface_ is guaranteed; the
+  # way in which it is _implemented_ is not.
+  #
+  # You tell the monkey patching system about the outer container module, the
+  # instance and/or class patch modules and the target entity via a call to
+  # Hoodoo::Monkey::register. See this for more details. Use
+  # Hoodoo::Monkey::enable to actually 'switch on' the patch and
+  # Hoodoo::Monkey::disable to 'switch off' the patch again.
+  #
+  # The patch engine is "require'd" by Hoodoo as the very last thing in all of
+  # its other inclusion steps when 'hoodoo.rb' ("everything") is included by
+  # code. If individual sub-modules of Hoodoo are included by client code, it
+  # will be up to them when (and if) the monkey patch engine is brought in.
+  #
+  # Hoodoo authors should note namespaces Hoodoo::Monkey::Patch and
+  # Hoodoo::Monkey::Chaos inside which out-of-the-box Hoodoo patch code should
+  # be defined. Third party patches must use their own namespaces to avoid any
+  # potential for collision with future new Hoodoo patch modules.
+  #
+  module Monkey
+    @@modules = {}
+
+    # Register a set of monkey patch modules with Hoodoo::Monkey - see the
+    # top-level Hoodoo::Monkey documentation for an introduction and some
+    # high level guidelines for monkey patch code.
+    #
+    # _Named_ parameters are:
+    #
+    # +target_unit+::             The Class or Module to be patched.
+    # +extension_module+::        The module that identifies the collection of
+    #                             instance and/or class methods to overwrite
+    #                             inside the targeted unit. This MUST define
+    #                             a nested module called "InstanceExtensions"
+    #                             containing method definitions that will
+    #                             override same-name instance methods in the
+    #                             targeted unit, or a nested module called
+    #                             "ClassExtensions" to override class methods,
+    #                             or both.
+    #
+    # For example, suppose we have this class:
+    #
+    #     class Foo
+    #       def bar
+    #         2 * 2
+    #       end
+    #
+    #       def self.bar
+    #         3 * 3
+    #       end
+    #     end
+    #
+    #     Foo.new.bar
+    #     # => 4
+    #     Foo.bar
+    #     # => 9
+    #
+    # Next define modules which extend/override methods in the above class:
+    #
+    #    module ExtendedFoo
+    #      module InstanceExtensions
+    #        def bar
+    #          5 * 5
+    #        end
+    #      end
+    #
+    #      module ClassExtensions
+    #
+    #        # Even though this module will be used to override class methods
+    #        # in the target, we define the module methods with "def bar", not
+    #        # "def self.bar".
+    #        #
+    #        def bar
+    #          7 * 7
+    #        end
+    #      end
+    #    end
+    #
+    # At this point, the extension is defined, but not registered with Hoodoo
+    # and not yet enabled. Register it with:
+    #
+    #     Hoodoo::Monkey.register(
+    #       target_unit:      Foo,
+    #       extension_module: ExtendedFoo
+    #     )
+    #
+    # The code is now registered so that it can be easily enabled or disabled
+    # via the given +extension_module+ value:
+    #
+    #     Hoodoo::Monkey.enable( ExtendedFoo )
+    #
+    #     Foo.new.bar
+    #     # => 25
+    #     Foo.bar
+    #     # => 49
+    #
+    #     Hoodoo::Monkey.disable( ExtendedFoo )
+    #
+    #     Foo.new.bar
+    #     # => 4
+    #     Foo.bar
+    #     # => 9
+    #
+    # You can register the same extension modules for multiple target units,
+    # but it can only be enabled or disabled all in one go for all targets.
+    #
+    def self.register( target_unit:, extension_module: )
+
+      if extension_module.const_defined?( 'InstanceExtensions', false )
+        instance_methods_module = extension_module.const_get( 'InstanceExtensions' )
+      end
+
+      if extension_module.const_defined?( 'ClassExtensions', false )
+        class_methods_module = extension_module.const_get( 'ClassExtensions' )
+      end
+
+      if instance_methods_module.nil? && class_methods_module.nil?
+        raise "Hoodoo::Monkey::register: You must define either an InstanceExtensions module ClassExtensions module or both inside '#{ extension_module.inspect }'"
+      end
+
+      @@modules[ extension_module ] ||= {}
+      @@modules[ extension_module ][ target_unit ] =
+      [
+        {
+          :patch_module => instance_methods_module,
+          :patch_target => target_unit
+        },
+        {
+          :patch_module => class_methods_module,
+          :patch_target => target_unit.singleton_class
+        }
+      ]
+
+    end
+
+    # Enable a given monkey patch, using the extension module parameter value
+    # given to a prior call to ::register (see there for more information).
+    #
+    # The initial patch installation is done via <tt>Module#prepend</tt>, so
+    # you are able to call +super+ to invoke the original implementation from
+    # the overriding implementation, as if you were writing a subclass.
+    #
+    # Instance and class method monkey patches should try very hard to always
+    # call "super" so that an overridden/patched public API method will still
+    # call back to its original implementation; the wrapper just filters
+    # inputs and outputs or adds additional behaviour. This way, changes to
+    # the Hoodoo implementation will not break the patch.
+    #
+    # Patching is global; it is not lexically scoped. Use Ruby refinements
+    # manually if you want lexically scoped patches.
+    #
+    # _Named_ parameters are:
+    #
+    # +extension_module+:: A module previously passed in the same-named
+    #                      parameter to ::register. The instance and/or class
+    #                      methods defined therein will be applied to the
+    #                      previously registered target.
+    #
+    # Enabling the same extension multiple times has no side effects.
+    #
+    def self.enable( extension_module: )
+      if ( target_units_hash = @@modules[ extension_module ] ).nil?
+        raise "Hoodoo::Monkey::enable: Extension module '#{ extension_module.inspect }' is not registered"
+      end
+
+      target_units_hash.each_value do | target_and_module_array |
+        target_and_module_array.each do | target_and_module_array_entry |
+          patch_module = target_and_module_array_entry[ :patch_module ]
+          patch_target = target_and_module_array_entry[ :patch_target ]
+
+          next if patch_module.nil?
+
+          # If the patch contains a target-based collection of unbound
+          # methods, it was disabled previously (see the 'disable' code).
+          # Re-enable by re-building the module's methods.
+          #
+          if target_and_module_array_entry.has_key?( :unbound_methods )
+
+            target_and_module_array_entry[ :unbound_methods ].each do | method_name, unbound_method |
+              patch_module.send( :define_method, method_name, unbound_method )
+            end
+
+            # Discard the references to the now-unneeded unbound methods.
+            #
+            target_and_module_array_entry.delete( :unbound_methods )
+
+          end
+
+          # *Always* call "prepend". If the same patch modules are being used
+          # against multiple targets, the fact that the code above saw that a
+          # module had been disabled for one particular target doesn't mean
+          # that the module had previously been inserted into the ancestors
+          # for "this" target. It might have been registered later.
+          #
+          # This is safe as repeat calls do nothing; they don't even reorder
+          # the ancestor chain.
+          #
+          patch_target.prepend( patch_module )
+
+        end
+      end
+    end
+
+    # Disable a patch previously enabled with ::enable (see there for more
+    # information).
+    #
+    # A disabled patch will still be present in a target unit's +ancestors+
+    # list, but has no performance impact. Repeated enable/disable cycles
+    # incur no additional runtime performance penalties.
+    #
+    # _Named_ parameters are:
+    #
+    # +extension_module+:: A module previously passed in the same-named
+    #                      parameter to ::register. The instance and/or class
+    #                      methods defined therein will be removed from the
+    #                      previously registered target.
+    #
+    # Disabling the same extension multiple times has no side effects.
+    #
+    def self.disable( target_unit: nil, extension_module: )
+      if ( target_units_hash = @@modules[ extension_module ] ).nil?
+        raise "Hoodoo::Monkey::disable: Extension module '#{ extension_module.inspect }' is not registered"
+      end
+
+      target_units_hash.each_value do | target_and_module_array |
+        target_and_module_array.each do | target_and_module_array_entry |
+          patch_module = target_and_module_array_entry[ :patch_module ]
+          patch_target = target_and_module_array_entry[ :patch_target ]
+
+          next if patch_module.nil? || target_and_module_array_entry.has_key?( :unbound_methods )
+
+          target_and_module_array_entry[ :unbound_methods ] = {}
+
+          # We take unbound method references to every patch module method,
+          # then remove the originals. In the re-enable code, the methods
+          # are redefined in the module. This approach means that any
+          # target unit with the module in its ancestors chain will see the
+          # change immediately. We don't need to iterate over them.
+          #
+          patch_module.instance_methods( false ).each do | method_name |
+            unbound_method = patch_module.instance_method( method_name )
+            target_and_module_array_entry[ :unbound_methods ][ method_name ] = unbound_method
+            patch_module.send( :remove_method, method_name )
+          end
+        end
+      end
+    end
+
+    # Out-of-the-box regular monkey patches (versus chaos monkeys) for Hoodoo.
+    # These typically predictably extend or modify existing Hoodoo behaviour.
+    # See Hoodoo::Monkey for details.
+    #
+    module Patch
+    end
+
+    # Out-of-the-box chaos monkey patches (versus regular monkeys) for Hoodoo.
+    # These typically provoke unpredictable states inside existing Hoodoo
+    # behaviour to exercise "unhappy path" code paths. See Hoodoo::Monkey for
+    # details.
+    #
+    module Chaos
+    end
+  end
+end

data/lib/hoodoo/monkey/patch/newrelic_traced_amqp.rb

@@ -0,0 +1,195 @@
+########################################################################
+# File::    newrelic_traced_amqp.rb
+# (C)::     Loyalty New Zealand 2015
+#
+# Purpose:: Extend the AMQP endpoint to support NewRelic cross-app
+#           transaction tracing. Only defined and registered if the
+#           NewRelic gem is available and Hoodooo Client is in scope.
+#
+#           See Hoodoo::Monkey::Patch::NewRelicTracedAMQP for more.
+# ----------------------------------------------------------------------
+#           08-Apr-2016 (RJS): Created.
+########################################################################
+
+module Hoodoo
+  module Monkey
+    module Patch
+
+      begin
+        require 'newrelic_rpm' # Raises LoadError if NewRelic is absent
+
+        # Wrap Hoodoo::Client::Endpoint::AMQP using NewRelic transaction
+        # tracing so that over-queue inter-resource calls get connected
+        # together in NewRelic's view of the world.
+        #
+        # This module self-registers with Hooodoo::Monkey and, provided
+        # that Hoodoo::Services::Middleware is defined at parse-time and
+        # Hoodoo::Services::Middleware.environment.production? reports
+        # +false+, will be enabled by default.
+        #
+        module NewRelicTracedAMQP
+
+          # Instance methods to patch over Hoodoo::Client::Endpoint::AMQP.
+          #
+          module InstanceExtensions
+
+            # Wrap the request with NewRelic's cross-app transaction tracing.
+            # This adds headers to the request and extracts header data from
+            # the response. It calls the original implementation via +super+.
+            #
+            # +http_message+:: Hash describing the message to send.
+            #
+            # +full_uri+::     URI being sent to. This is somewhat meaningless
+            #                  when using AMQP but NewRelic requires it.
+            #
+            def monkey_send_request( http_message, full_uri )
+              amqp_response    = nil
+              newrelic_request = ::Hoodoo::Monkey::Patch::NewRelicTracedAMQP::AMQPNewRelicRequestWrapper.new(
+                http_message,
+                full_uri
+              )
+
+              ::NewRelic::Agent::CrossAppTracing.tl_trace_http_request( newrelic_request ) do
+
+                # Disable further tracing in request to avoid double counting
+                # if connection wasn't started (which calls request again).
+                #
+                ::NewRelic::Agent.disable_all_tracing do
+
+                  amqp_response = super( http_message, full_uri )
+
+                  # The outer block extracts required information from the
+                  # object returned by this block. Need to wrap it match the
+                  # expected interface.
+                  #
+                  ::Hoodoo::Monkey::Patch::NewRelicTracedAMQP::AMQPNewRelicResponseWrapper.new(
+                    amqp_response
+                  )
+
+                end
+              end
+
+              return amqp_response
+            end
+          end
+
+          # Wrapper class for an AMQP request which conforms to the API that
+          # NewRelic expects.
+          #
+          class AMQPNewRelicRequestWrapper
+
+            # Wrap the Alchemy Flux +http_message+ aimed at the specified
+            # +full_uri+.
+            #
+            # +http_message+:: Hash describing the request for Alchemy Flux.
+            # +full_uri+::     Full target URI, as a String.
+            #
+            def initialize( http_message, full_uri )
+              @http_message = http_message
+              @full_uri     = full_uri
+            end
+
+            # String describing what kind of request this is.
+            #
+            def type
+              self.class.to_s()
+            end
+
+            # String describing this request's intended host.
+            #
+            def host
+              @http_message[ 'host' ]
+            end
+
+            # String describing this request's HTTP verb (GET, POST and
+            # so-on). String case is undefined, so perform case-insensitive
+            # comparisions.
+            #
+            def method
+              @http_message[ 'verb' ]
+            end
+
+            # Key lookup is delegated to the headers Hash per NewRelic's
+            # expectations of how a request behaves.
+            #
+            # +key+:: Hash key to look up.
+            #
+            def []( key )
+              @http_message[ 'headers' ][ key ]
+            end
+
+            # Key setting is delegated to the headers Hash per NewRelic's
+            # expectations of how a request behaves.
+            #
+            # +key+::   Key of Hash entry to modify.
+            # +value+:: New or replacement value for identified Hash entry.
+            #
+            def []=( key, value )
+              @http_message[ 'headers' ][ key ] = value
+            end
+
+            # String describing the full request URI.
+            #
+            def uri
+              @full_uri
+            end
+
+          end
+
+          # Wrapper class for an AMQP request which conforms to the API that
+          # NewRelic expects.
+          #
+          class AMQPNewRelicResponseWrapper
+
+            # The +response_hash+ to be wrapped.
+            #
+            # +response_hash+:: Hash describing the response returned from
+            #                   Alchemy Flux.
+            #
+            def initialize( response_hash )
+              @response_hash = response_hash
+            end
+
+            # If the NewRelic cross-app tracing header is the +key+, return the
+            # value of the header that matches that key. Otherwise look up the
+            # key like normal.
+            #
+            # +key+:: Hash key to look up.
+            #
+            def []( key )
+              if key == ::NewRelic::Agent::CrossAppTracing::NR_APPDATA_HEADER
+                @response_hash[ 'headers' ][ key ]
+              else
+                @response_hash[ key ]
+              end
+            end
+          end
+        end
+
+        # Register this class with the Hoodoo monkey patch engine in any
+        # non-production environment.
+        #
+        if defined?( Hoodoo::Client ) &&
+           defined?( Hoodoo::Client::Endpoint ) &&
+           defined?( Hoodoo::Client::Endpoint::AMQP )
+
+          Hoodoo::Monkey.register(
+            target_unit:      Hoodoo::Client::Endpoint::AMQP,
+            extension_module: Hoodoo::Monkey::Patch::NewRelicTracedAMQP
+          )
+
+          if defined?( Hoodoo::Services ) &&
+             defined?( Hoodoo::Services::Middleware) &&
+             Hoodoo::Services::Middleware.environment.production? != true
+
+            Hoodoo::Monkey.enable( extension_module: Hoodoo::Monkey::Patch::NewRelicTracedAMQP )
+          end
+        end
+
+      rescue LoadError
+        # No NewRelic => do nothing
+      end
+
+    end # module Patch
+  end   # module Monkey
+end     # module Hoodoo