hoodoo 1.0.2

data/lib/hoodoo/services/middleware/amqp_log_writer.rb

@@ -0,0 +1,119 @@
+########################################################################
+# File::    amqp_log_writer.rb
+# (C)::     Loyalty New Zealand 2014
+#
+# Purpose:: Structured logging support for the middleware.
+# ----------------------------------------------------------------------
+#           20-Nov-2014 (ADH): Created.
+#           16-Dec-2014 (ADH): Changed into a new Hoodoo::Logger style
+#                              instantiable log writer.
+########################################################################
+
+module Hoodoo; module Services
+  class Middleware
+
+    # Log writer which sends structured messages to an AMQP-based queue via
+    # the AlchemyAMQ gems. A Hoodoo::Logger::FastWriter subclass, since though
+    # talking to the queue might be comparatively slow, Alchemy itself uses an
+    # asynchronous Thread for this so there's no need to add another one for
+    # this logger.
+    #
+    # See also Hoodoo::Logger and Hoodoo::Services::Middleware::AMQPLogMessage.
+    #
+    class AMQPLogWriter < Hoodoo::Logger::FastWriter
+
+      # Create an AMQP logger instance.
+      #
+      # +alchemy+::    The Alchemy endpoint to use for sending messages to the
+      #                AMQP-based queue.
+      #
+      # +queue_name+:: The queue name (as a String) to use. Optional. If
+      #                omitted, reads +ENV[ 'AMQ_LOGGING_ENDPOINT' ]+ or if
+      #                that is unset, defaults to +platform.logging+.
+      #
+      # If you're running with Rack on top of Alchemy, then the +call+ method's
+      # +env+ parameter containing the Rack environment should have a key of
+      # +rack.alchemy+ or +alchemy+ with a value that can be assigned to the
+      # +alchemy+ parameter. The logger will then use the active Alchemy
+      # service to send messages to its configured named queue.
+      #
+      def initialize( alchemy, queue_name = nil )
+        @alchemy    = alchemy
+        @queue_name = queue_name || ENV[ 'AMQ_LOGGING_ENDPOINT' ] || 'platform.logging'
+      end
+
+      # Custom implementation of the Hoodoo::Logger::WriterMixin#report
+      # interface. See that method for parameter details.
+      #
+      # The middleware custom logger has expectations about the data payload.
+      # It expects these optional but recommended (where the information is
+      # available / has been generated) keys/values:
+      #
+      # +:id+::      A UUID (via Hoodoo::UUID::generate) to use for this log
+      #              message - if absent, one is generated automatically.
+      #
+      # +:session+:: Description of the current request session when available;
+      #              a Hoodoo::Services::Session as a Hash (via #to_h; keys as
+      #              Strings). The Caller UUID, identity Participant UUID and
+      #              identity Outlet UUID are sent as independent, searchable
+      #              fields in the log payload.
+      #
+      # +interaction_id+:: The interaction ID for this client's call. This is
+      #                    also sent as an independent, searchable field in
+      #                    the log payload.
+      #
+      def report( level, component, code, data )
+        return if @alchemy.nil? || defined?( Hoodoo::Services::Middleware::AMQPLogMessage ).nil?
+
+        # Take care with Symbol keys in 'data' vs string keys in e.g. 'Session'.
+
+        data[ :id ] ||= Hoodoo::UUID.generate()
+
+        interaction_id = data[ :interaction_id ]
+        session        = data[ :session ] || {}
+
+        caller_id      = session[ 'caller_id' ]
+        identity       = ( session[ 'identity' ] || {} ).to_h
+
+        message = Hoodoo::Services::Middleware::AMQPLogMessage.new(
+          :id             => data[ :id ],
+          :level          => level,
+          :component      => component,
+          :code           => code,
+          :reported_at    => Time.now,
+
+          :data           => data,
+
+          :interaction_id => interaction_id,
+          :caller_id      => caller_id,
+          :identity       => identity,
+
+          :routing_key    => @queue_name,
+        )
+
+        # Broken services can attempt to log invalid datatypes such as
+        # BigDecimal, which Msgpack can't serialize. At the time of writing,
+        # Alchemy AMQ would thus encounter a serialization exception *within
+        # its EventMachine sending loop*, so in a different *native* thread.
+        # This exception could not be caught by Ruby / Hoodoo in "this"
+        # native thread, so instead the uncaught exception kills the service.
+        # Although Alchemy could catch that itself, there is no way for it to
+        # report the failure to Hoodoo in a way that a log reporting caller
+        # could understand; it's async and in the wrong native thread anyway.
+        #
+        # Solution: In non-production environments only (due to the potential
+        # performance hit), manually serialize the message before sending it.
+        # If this call blows up, the Hoodoo exception handler will catch it
+        # and report the result as a properly formed 500, including the
+        # Msgpack (or other exception) details on exactly what was wrong.
+        #
+        unless Hoodoo::Services::Middleware.environment.production?
+          message.serialize()
+        end
+
+        @alchemy.send_message( message )
+      end
+    end
+
+  end
+end; end

data/lib/hoodoo/services/middleware/endpoints/inter_resource_local.rb

@@ -0,0 +1,130 @@
+########################################################################
+# File::    inter_resource_local.rb
+# (C)::     Loyalty New Zealand 2014
+#
+# Purpose:: An endpoint that calls back into a known middleware
+#           instance to communicate with a resource that is available
+#           in the local service application.
+# ----------------------------------------------------------------------
+#           11-Nov-2014 (ADH): Split out from service_middleware.rb
+#           09-Mar-2015 (ADH): Adapted from old endpoint.rb code.
+########################################################################
+
+module Hoodoo; module Services
+  class Middleware
+
+    # This is an endpoint which the middleware uses for inter-resource
+    # calls back calling back to that same middleware instance, for
+    # resources which exist within the same service application. The
+    # middleware manages all the inter-resource preparation and post
+    # processing.
+    #
+    class InterResourceLocal < Hoodoo::Client::Endpoint
+
+      protected
+
+        # See Hoodoo::Client::Endpoint#configure_with.
+        #
+        # It isn't expected that anyone will ever need to use this class
+        # beyond Hoodoo::Services::Middleware, but you never know...
+        #
+        # Configuration option keys which _must_ be supplied are:
+        #
+        # +interaction+::      A Hoodoo::Services::Middleware::Interaction
+        #                      instance which describes the *source*
+        #                      interaction at hand. This is a middleware
+        #                      concept; the middleware is handling some
+        #                      API call which the source interaction data
+        #                      describes, but the resource which is
+        #                      handling the call needs to make a local
+        #                      inter-resource call, which is why this
+        #                      Endpoint subclass instance is needed.
+        #
+        # +discovery_result+:: A Hoodoo::Services::Discovery::ForLocal
+        #                      instance describing the locally available
+        #                      resource endpoint.
+        #
+        def configure_with( resource, version, options )
+          @middleware = self.interaction().owning_middleware_instance
+        end
+
+      public
+
+        # See Hoodoo::Client::Endpoint#list.
+        #
+        def list( query_hash = nil )
+          return @middleware.inter_resource_local(
+            :source_interaction => self.interaction(),
+            :discovery_result   => @discovery_result,
+            :endpoint           => self,
+
+            :action             => :list,
+
+            :query_hash         => query_hash
+          )
+        end
+
+        # See Hoodoo::Client::Endpoint#show.
+        #
+        def show( ident, query_hash = nil )
+          return @middleware.inter_resource_local(
+            :source_interaction => self.interaction(),
+            :discovery_result   => @discovery_result,
+            :endpoint           => self,
+
+            :action             => :show,
+
+            :ident              => ident,
+            :query_hash         => query_hash
+          )
+        end
+
+        # See Hoodoo::Client::Endpoint#create.
+        #
+        def create( body_hash, query_hash = nil )
+          return @middleware.inter_resource_local(
+            :source_interaction => self.interaction(),
+            :discovery_result   => @discovery_result,
+            :endpoint           => self,
+
+            :action             => :create,
+
+            :body_hash          => body_hash,
+            :query_hash         => query_hash
+          )
+        end
+
+        # See Hoodoo::Client::Endpoint#update.
+        #
+        def update( ident, body_hash, query_hash = nil )
+          return @middleware.inter_resource_local(
+            :source_interaction => self.interaction(),
+            :discovery_result   => @discovery_result,
+            :endpoint           => self,
+
+            :action             => :update,
+
+            :ident              => ident,
+            :body_hash          => body_hash,
+            :query_hash         => query_hash
+          )
+        end
+
+        # See Hoodoo::Client::Endpoint#delete.
+        #
+        def delete( ident, query_hash = nil )
+          return @middleware.inter_resource_local(
+            :source_interaction => self.interaction(),
+            :discovery_result   => @discovery_result,
+            :endpoint           => self,
+
+            :action             => :delete,
+
+            :ident              => ident,
+            :query_hash         => query_hash
+          )
+        end
+      end
+
+  end
+end; end

data/lib/hoodoo/services/middleware/endpoints/inter_resource_remote.rb

@@ -0,0 +1,202 @@
+########################################################################
+# File::    inter_resource_remote.rb
+# (C)::     Loyalty New Zealand 2015
+#
+# Purpose:: Resource endpoint definition.
+# ----------------------------------------------------------------------
+#           05-Mar-2015 (ADH): Created.
+########################################################################
+
+module Hoodoo
+  module Services
+    class Middleware # Just used as a namespace here
+
+      # This is an endpoint which the middleware uses for inter-resource
+      # calls over another 'wrapped' endpoint. This endpoint manages all
+      # the inter-resource preparation and post processing, but calls in
+      # to another wrapped endpoint to actually talk to the resource for
+      # which the inter-resource call is being made.
+      #
+      # Since it wraps another endpoint, instantiation requirements are
+      # rather unusual - see #configure_with for details.
+      #
+      class InterResourceRemote < Hoodoo::Client::Endpoint
+
+        protected
+
+          # See Hoodoo::Client::Endpoint#configure_with.
+          #
+          # It isn't expected that anyone will ever need to use this class
+          # beyond Hoodoo::Services::Middleware, but you never know...
+          #
+          # Configuration option keys which _must_ be supplied are:
+          #
+          # +interaction+::      A Hoodoo::Services::Middleware::Interaction
+          #                      instance which describes the *source*
+          #                      interaction at hand. This is a middleware
+          #                      concept; the middleware is handling some
+          #                      API call which the source interaction data
+          #                      describes, but the resource which is
+          #                      handling the call needs to make a remote
+          #                      inter-resource call, which is why this
+          #                      Endpoint subclass instance is needed.
+          #
+          # +discovery_result+:: A Hoodoo::Services::Discovery::ForRemote
+          #                      instance describing the remotely available
+          #                      resource endpoint.
+          #
+          # The pattern for creating and using this instance is:
+          #
+          # * Use the discovery result to build an appropriate Endpoint
+          #   subclass instance, e.g. Hoodoo::Client::Endpoint::HTTP.
+          #
+          # * Create a Hoodoo::Services::Discovery::ForRemote instance
+          #   which describes the above endpoint via the +wrapped_endpoint+
+          #   option.
+          #
+          # * Build an instance of this auto-session Endpoint subclass,
+          #   giving it the above object as the +discovery_result+.
+          #
+          # * Use this endpoint in the normal fashion. All the special
+          #   mechanics of remote inter-resource calling are handled here.
+          #
+          def configure_with( resource, version, options )
+            @wrapped_endpoint = @discovery_result.wrapped_endpoint
+          end
+
+        public
+
+          # See Hoodoo::Client::Endpoint#list.
+          #
+          def list( query_hash = nil )
+            result = preprocess( :list )
+            result = @wrapped_endpoint.list( query_hash ) if result.nil?
+            return postprocess( result )
+          end
+
+          # See Hoodoo::Client::Endpoint#show.
+          #
+          def show( ident, query_hash = nil )
+            result = preprocess( :show )
+            result = @wrapped_endpoint.show( ident, query_hash ) if result.nil?
+            return postprocess( result )
+          end
+
+          # See Hoodoo::Client::Endpoint#create.
+          #
+          def create( body_hash, query_hash = nil )
+            result = preprocess( :create )
+            result = @wrapped_endpoint.create( body_hash, query_hash ) if result.nil?
+            return postprocess( result )
+          end
+
+          # See Hoodoo::Client::Endpoint#update.
+          #
+          def update( ident, body_hash, query_hash = nil )
+            result = preprocess( :update )
+            result = @wrapped_endpoint.update( ident, body_hash, query_hash ) if result.nil?
+            return postprocess( result )
+          end
+
+          # See Hoodoo::Client::Endpoint#delete.
+          #
+          def delete( ident, query_hash = nil )
+            result = preprocess( :delete )
+            result = @wrapped_endpoint.delete( ident, query_hash ) if result.nil?
+            return postprocess( result )
+          end
+
+        private
+
+          # Preprocess the given action. This, for example, includes setting
+          # up a session with extra permissions requested by the *calling*
+          # resource implementation's interface, if necessary.
+          #
+          # +action+:: A Hoodoo::Services::Middleware::ALLOWED_ACTIONS entry.
+          #
+          def preprocess( action )
+
+            copy_updated_options_to( @wrapped_endpoint )
+
+            # Interaction ID comes from Endpoint superclass.
+            #
+            session = self.interaction().context.session
+
+            unless session.nil? || self.interaction().using_test_session?
+              session = session.augment_with_permissions_for( self.interaction() )
+            end
+
+            if session == false
+              data = response_class_for( action ).new
+              data.platform_errors.add_error( 'platform.invalid_session' )
+              return data
+            else
+
+              # We only get away with @wrapping_session as an instance
+              # variable because endpoints are not intended to be thread
+              # safe, so we assume that only one thread at any given time
+              # will be running through "this" instance.
+              #
+              # We only store the full session rather than just the ID so
+              # that we can easily delete it. The inbound session which
+              # may have been augmented, would already have any relevant
+              # configuration data associated with it - so we don't want
+              # to lose that reference by only storing the ID. This would
+              # make it very hard / impossible to delete the session again
+              # in #postprocess, which could represent a security issue as
+              # an elevated permission session could be left kicking
+              # around somewhere.
+
+              @wrapping_session = session
+              @wrapped_endpoint.session_id = session.session_id
+              return nil
+            end
+          end
+
+          # Postprocess the given action. This, for example, includes
+          # removing any session with extra permissions that might have been
+          # set up in #preprocess.
+          #
+          # +action+:: A Hoodoo::Client::AugmentedHash or
+          #            Hoodoo::Client::AugmentedArray containing the result
+          #            of a previous (successful or unsuccessful) call to a
+          #            remote target resource. It may be modified.
+          #
+          def postprocess( result )
+
+            # Interaction ID comes from Endpoint superclass.
+            #
+            if @wrapping_session &&
+               self.interaction().context &&
+               self.interaction().context.session &&
+               @wrapping_session.session_id != self.interaction().context.session.session_id
+
+              # Ignore errors, there's nothing much we can do about them and in
+              # the worst case we just have to wait for this to expire naturally.
+
+              @wrapped_endpoint.session_id = nil
+
+              session = @wrapping_session
+              @wrapping_session = nil
+              session.delete_from_memcached()
+            end
+
+            annotate_errors_from_other_resource_in( result )
+
+            return result
+          end
+
+          # TODO
+          #
+          def annotate_errors_from_other_resource_in( augmented_thing )
+            # TODO - this probably needs to live somewhere else so the
+            # endpoint and middleware local service call can 'reach' it.
+            # Run through errors, if any; prefix messages with target resource
+            # and version; maybe source resource and version too; e.g.:
+            # "In v1 of Bar while handling <action> in v2 of Foo: ..."
+          end
+
+      end
+    end
+  end
+end