hoodoo 1.0.2

data/lib/hoodoo/services/middleware/exception_reporting/base_reporter.rb

@@ -0,0 +1,105 @@
+########################################################################
+# File::    base.rb
+# (C)::     Loyalty New Zealand 2014
+#
+# Purpose:: Abstracted links to third party error management services.
+# ----------------------------------------------------------------------
+#           08-Dec-2014 (ADH): Created.
+########################################################################
+
+require 'singleton'
+
+module Hoodoo; module Services
+  class Middleware
+
+    class ExceptionReporting
+
+      # Subclass this method to create a custom class used to contact external
+      # exception monitoring / reporting engine. Examples include:
+      #
+      # * Raygun:      https://raygun.io
+      # * Honeybadger: https://www.honeybadger.io
+      # * Exceptional: http://www.exceptional.io
+      # * Airbrake:    https://airbrake.io
+      #
+      # Hoodoo includes some classes for integration which you can choose from
+      # if you want to use the integrated service. Alternatively write your own.
+      # When you do this, name your class *outside* the Hoodoo namespace (the
+      # class's name can be anything you like). Otherwise you will trample upon
+      # Hoodoo' reserved namespace and may cause a naming collision in future
+      # Hoodoo versions.
+      #
+      # "Under the hood" the Hoodoo::Communicators::Pool mechanism is used.
+      # All reporters are assumed to be (comparatively) slow communicators so
+      # are descendants of Hoodoo::Communicators::Slow.
+      #
+      # Add a reporter class to the middleware from any service application by
+      # calling Hoodoo::Services::Middleware::ExceptionReporting.add.
+      #
+      class BaseReporter < Hoodoo::Communicators::Slow
+
+        include ::Singleton
+
+        # Subclasses implement this method. The middleware creates the singleton
+        # instance of the subclass, then calls your implementation of the method
+        # when it catches an exception in its top level handler. The subclass
+        # implementation sends details of the exception to the desired exception
+        # monitoring or reporting service. The return value is ignored.
+        #
+        # The middleware wraps calls to your subclass in a nested exception
+        # handler. If you raise an exception, the middleware logs details with
+        # a +:debug+ level through its logger instance if possible (see
+        # Hoodoo::Services::Middleware::logger) along with printing details to
+        # $stderr, then continues processing.
+        #
+        # If service applications are expecting potential exceptions to occur
+        # and they catch them without re-raising for the middleware to catch,
+        # this reporting method will not be called. If a service author thinks
+        # such an exception ought to be logged, they must re-raise it.
+        #
+        # The middleware runs calls here in a processing Thread to avoid delays
+        # to the calling client. This means your implementation of this method
+        # can use blocking network calls should you so wish; but beware, you are
+        # running in your own Thread on every call and more than one call might
+        # be running concurrently. If your implementation is not threadsafe,
+        # use a Mutex. For example, add a mutex class variable to your class:
+        #
+        #     @@mutex = Mutex.new
+        #
+        # ...then use it inside +report+ with something like:
+        #
+        #     def report( e )
+        #       @@mutex.synchronize do
+        #         # Your reporting service's custom code goes here
+        #       end
+        #     end
+        #
+        # +e+::   Exception (or subclass) instance to be reported.
+        #
+        # +env+:: Optional Rack environment hash for the inbound request, for
+        #         exception reports made in the context of Rack request
+        #         handling.
+        #
+        def report( e, env = nil )
+          raise( 'Subclasses must implement #report' )
+        end
+
+        # Subclasses *MUST* *NOT* override this method, which is part of the
+        # base class implementation and implements
+        # Hoodoo::Communicators::Slow#communicate. It calls through to the
+        # #report method which subclasses do implement, unpacking a payload
+        # used for the internal communicators into the parameters that
+        # #report expects.
+        #
+        # +object+:: Hoodoo::Services::Middleware::ExceptionReporting::Payload
+        #            instance.
+        #
+        def communicate( object )
+          self.report( object.exception, object.rack_env )
+        end
+      end
+
+    end
+
+  end
+end; end

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

@@ -0,0 +1,115 @@
+########################################################################
+# File::    exception_reporting.rb
+# (C)::     Loyalty New Zealand 2014
+#
+# Purpose:: Reporting exceptions to third party error management
+#           services.
+# ----------------------------------------------------------------------
+#           08-Dec-2014 (ADH): Created.
+########################################################################
+
+module Hoodoo; module Services
+  class Middleware
+
+    # Exception reporting / monitoring through external services.
+    #
+    class ExceptionReporting
+
+      # Pool of exception reporters.
+      #
+      @@reporter_pool = Hoodoo::Communicators::Pool.new
+
+      # Add an exception reporter class to the set of reporters. See the
+      # Hoodoo::Services::Middleware::ExceptionReporting::BaseReporter class for an
+      # overview.
+      #
+      # Whenever the middleware's own exception handler catches an exception,
+      # it will run through the set of exception reporters (if any) and call
+      # each one to report exception details.
+      #
+      # Reporters are maintained in a Set. Only one class will ever be
+      # stored and called once per exception; the original order of addition
+      # before duplicates is maintained (so if you add class A, then B, then
+      # A again, then class A is called first and only once, then B once).
+      #
+      # Each reporter is called from its own Ruby Thread so that client API
+      # call response is kept fast. If a call fails, a debug log entry is
+      # made but processing of other reporters continues uninterrupted. It is
+      # up to individual reporter classes to manage thread safety.
+      #
+      # +klass+:: Hoodoo::Services::Middleware::ExceptionReporting::BaseReporter
+      #           subclass (class, not instance) to add.
+      #
+      def self.add( klass )
+        unless klass < Hoodoo::Services::Middleware::ExceptionReporting::BaseReporter
+          raise "Hoodoo::Services::Middleware.add must be called with a Hoodoo::Services::Middleware::ExceptionReporting::BaseReporter subclass"
+        end
+
+        @@reporter_pool.add( klass.instance )
+      end
+
+      # Remove an exception reporter class from the set of reporters. See
+      # ::add for details.
+      #
+      # +klass+:: Hoodoo::Services::Middleware::ExceptionReporting::BaseReporter
+      #           subclass (class, not instance) to remove.
+      #
+      def self.remove( klass )
+        unless klass < Hoodoo::Services::Middleware::ExceptionReporting::BaseReporter
+          raise "Hoodoo::Services::Middleware.remove must be called with a Hoodoo::Services::Middleware::ExceptionReporting::BaseReporter subclass"
+        end
+
+        @@reporter_pool.remove( klass.instance )
+      end
+
+      # Call all added exception reporters (see ::add) to report an exception.
+      #
+      # +exception+:: Exception or Exception subclass instance to report.
+      #
+      # +rack_env+::  Optional Rack environment hash for the inbound request,
+      #               for exception reports made in the context of Rack request
+      #               handling.
+      #
+      def self.report( exception, rack_env = nil )
+        payload = Payload.new( exception: exception, rack_env: rack_env )
+        @@reporter_pool.communicate( payload )
+      end
+
+      # Wait for all executing reporter threads to catch up before continuing.
+      #
+      # +timeout+:: Optional timeout wait delay *for* *each* *thread*. Default
+      #             is 5 seconds.
+      #
+      def self.wait( timeout = 5 )
+        @@reporter_pool.wait( per_instance_timeout: timeout )
+      end
+
+      # Implementation detail of
+      # Hoodoo::Services::Middleware::ExceptionReporting used to carry
+      # multiple parameters describing exception related data through the
+      # Hoodoo::Communicators::Pool#communicate mechanism.
+      #
+      class Payload
+
+        # Exception (or Exception subclass) instance.
+        #
+        attr_accessor :exception
+
+        # Rack environment (the unprocessed, original Hash). May be +nil+.
+        #
+        attr_accessor :rack_env
+
+        # Initialize this instance with named parameters:
+        #
+        # +exception+:: Exception (or Exception subclass) instance. Mandatory.
+        # +rack_env+::  Rack environment hash. Optional.
+        #
+        def initialize( exception:, rack_env: nil )
+          @exception = exception
+          @rack_env  = rack_env
+        end
+      end
+    end
+
+  end
+end; end

data/lib/hoodoo/services/middleware/exception_reporting/reporters/airbrake_reporter.rb

@@ -0,0 +1,64 @@
+########################################################################
+# File::    airbrake_reporter.rb
+# (C)::     Loyalty New Zealand 2014
+#
+# Purpose:: Send exception details to Airbrake.
+# ----------------------------------------------------------------------
+#           08-Dec-2014 (ADH): Created.
+########################################################################
+
+module Hoodoo; module Services
+  class Middleware
+
+    class ExceptionReporting
+
+      # Hoodoo::Services::Middleware::ExceptionReporting::BaseReporter subclass
+      # giving Hoodoo::Services::Middleware::ExceptionReporting access to
+      # Airbrake for error reporting. See https://airbrake.io.
+      #
+      # Your application must include the Airbrake gem 'airbrake' via Gemfile
+      # (+gem 'airbrake'+ / +bundle install) or direct installation (+gem
+      # install airbrake+).
+      #
+      # The API key must be set during your application initialization and the
+      # class must be added to Hoodoo for use as an error reporter, e.g.
+      # through a 'config/initializers' folder, as follows:
+      #
+      #     require 'airbrake'
+      #
+      #     Airbrake.configure do | config |
+      #       config.api_key = 'YOUR_AIRBRAKE_API_KEY'
+      #     end
+      #
+      #     Hoodoo::Services::Middleware::ExceptionReporting.add(
+      #       Hoodoo::Services::Middleware::ExceptionReporting::AirbrakeReporter
+      #     ) unless Service.config.env.test? || Service.config.env.development?
+      #
+      # Services and the Hoodoo middleware do not pass Rails-like params
+      # around in forms or query strings, but do beware of search or filter
+      # query data containing sensitive material or POST bodies in e.g. JSON
+      # encoding containing sensitive data. This comes down to the filtering
+      # ability of the Airbrake gem:
+      #
+      #   https://github.com/airbrake/airbrake/wiki/Customizing-your-airbrake.rb
+      #
+      class AirbrakeReporter < Hoodoo::Services::Middleware::ExceptionReporting::BaseReporter
+
+        # Report an exception to Airbrake.
+        #
+        # +e+::   Exception (or subclass) instance to be reported.
+        #
+        # +env+:: Optional Rack environment hash for the inbound request, for
+        #         exception reports made in the context of Rack request
+        #         handling. In the case of Airbrake, the call may just hang
+        #         unless a Rack environment is provided.
+        #
+        def report( e, env = nil )
+          Airbrake.notify_or_ignore( e, :rack_env => env )
+        end
+      end
+
+    end
+
+  end
+end; end

data/lib/hoodoo/services/middleware/exception_reporting/reporters/raygun_reporter.rb

@@ -0,0 +1,63 @@
+########################################################################
+# File::    raygun_reporter.rb
+# (C)::     Loyalty New Zealand 2014
+#
+# Purpose:: Send exception details to Raygun.
+# ----------------------------------------------------------------------
+#           08-Dec-2014 (ADH): Created.
+########################################################################
+
+module Hoodoo; module Services
+  class Middleware
+
+    class ExceptionReporting
+
+      # Hoodoo::Services::Middleware::ExceptionReporting::BaseReporter subclass
+      # giving Hoodoo::Services::Middleware::ExceptionReporting access to
+      # Raygun for error reporting. See https://raygun.io.
+      #
+      # Your application must include the Raygun gem 'raygun4ruby' via Gemfile
+      # (+gem 'raygun4ruby'+ / +bundle install) or direct installation (+gem
+      # install raygun4ruby+).
+      #
+      # The API key must be set during your application initialization and the
+      # class must be added to Hoodoo for use as an error reporter, e.g.
+      # through a 'config/initializers' folder, as follows:
+      #
+      #     require 'raygun4ruby'
+      #
+      #     Raygun.setup do | config |
+      #       config.api_key = 'YOUR_RAYGUN_API_KEY'
+      #     end
+      #
+      #     Hoodoo::Services::Middleware::ExceptionReporting.add(
+      #       Hoodoo::Services::Middleware::ExceptionReporting::RaygunReporter
+      #     ) unless Service.config.env.test? || Service.config.env.development?
+      #
+      # Services and the Hoodoo middleware do not pass Rails-like params
+      # around in forms or query strings, but do beware of search or filter
+      # query data containing sensitive material or POST bodies in e.g. JSON
+      # encoding containing sensitive data. This comes down to the filtering
+      # ability of the Raygun gem:
+      #
+      #   https://github.com/MindscapeHQ/raygun4ruby
+      #
+      class RaygunReporter < Hoodoo::Services::Middleware::ExceptionReporting::BaseReporter
+
+        # Report an exception to Raygun.
+        #
+        # +e+::   Exception (or subclass) instance to be reported.
+        #
+        # +env+:: Optional Rack environment hash for the inbound request, for
+        #         exception reports made in the context of Rack request
+        #         handling.
+        #
+        def report( e, env = nil )
+          Raygun.track_exception( e, env )
+        end
+      end
+
+    end
+
+  end
+end; end

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

@@ -0,0 +1,127 @@
+########################################################################
+# File::    interaction.rb
+# (C)::     Loyalty New Zealand 2015
+#
+# Purpose:: Encapsulate all data related to an interaction (API call)
+#           inside an object.
+# ----------------------------------------------------------------------
+#           13-Feb-2015 (ADH): Created.
+########################################################################
+
+module Hoodoo; module Services; class Middleware
+
+  # Encapsulate all data related to an interaction (API call) within
+  # one object.
+  #
+  class Interaction
+
+    public
+
+      # API calls are handled by the middleware, so Interactions are
+      # created by Hoodoo::Services::Middleware instances. This is that
+      # creating instance, or the instance that should be treated as if
+      # it were the creator.
+      #
+      attr_reader :owning_middleware_instance
+
+      # The inbound Rack request a Rack::Request instance.
+      #
+      attr_reader :rack_request
+
+      # Every interaction has a UUID passed back in API responses via
+      # the X-Interaction-ID HTTP header. This is that UUID.
+      #
+      attr_reader :interaction_id
+
+      # A Hoodoo::Services::Context instance representing this API call.
+      # May be updated/replaced during processing.
+      #
+      attr_accessor :context
+
+      # The Hoodoo::Services::Interface subclass describing the resource
+      # interface that is the target of the API call.
+      #
+      attr_accessor :target_interface
+
+      # The target Hoodoo::Services::Implementation instance for the
+      # API call. See #target_interface.
+      #
+      attr_accessor :target_implementation
+
+      # The requested action, as a symbol; see
+      # Hoodoo::Services::Middleware::ALLOWED_ACTIONS.
+      #
+      attr_accessor :requested_action
+
+      # The requested content type as a String - e.g. "application/json".
+      #
+      attr_accessor :requested_content_type
+
+      # The requested content encoding as a String - e.g. "utf-8".
+      #
+      attr_accessor :requested_content_encoding
+
+      # Hoodoo middleware calls here to say "I'm using the test session" (or
+      # not), so that this can be enquired about via #using_test_session? if
+      # need be.
+      #
+      def using_test_session
+        @using_test_session = true
+      end
+
+      # Returns +true+ if Hoodoo has previously called #using_test_session.
+      #
+      def using_test_session?
+        @using_test_session === true
+      end
+
+      # Create a new Interaction instance, acquiring a new interaction
+      # ID automatically or picking up one from an X-Interaction-ID
+      # header if available.
+      #
+      # A new context instance (see #context) is generated with a new
+      # empty request and response object attached, along with +nil+
+      # session data or the given session information in the input
+      # parameters:
+      #
+      # +env+:: The raw Rack request Hash. May be "{}" in some test
+      #         scenarios. Converted to a Rack::Request instance. If
+      #         this describes an X-Interaction-ID header then this
+      #         Interaction will use - without validation - whatever
+      #         value the header holds, else a new UUID is generated.
+      #
+      # +owning_middleware_instance+:: See #owning_middleware_instance.
+      #
+      # +session+:: The session data attached to the #context value;
+      #             optional; if omitted, +nil+ is used.
+      #
+      def initialize( env, owning_middleware_instance, session = nil )
+        @rack_request   = ::Rack::Request.new( env )
+        @interaction_id = find_or_generate_interaction_id()
+        @context        = Hoodoo::Services::Context.new(
+          session,
+          Hoodoo::Services::Request.new,
+          Hoodoo::Services::Response.new( @interaction_id ),
+          self
+        )
+
+        @owning_middleware_instance = owning_middleware_instance
+        @context.request.headers    = env.select() do | k,v |
+          k.to_s.start_with?( 'HTTP_' ) || k == 'CONTENT_TYPE' || k == 'CONTENT_LENGTH'
+        end.freeze()
+      end
+
+    private
+
+      # Find the value of an X-Interaction-ID header (if one is already present)
+      # or generate a new Interaction ID.
+      #
+      def find_or_generate_interaction_id
+        iid = self.rack_request.env[ 'HTTP_X_INTERACTION_ID' ]
+        iid = Hoodoo::UUID.generate() if iid.nil? || iid == ''
+        iid
+      end
+
+  end
+
+end; end; end