hoodoo 1.0.2

data/lib/hoodoo/logger/slow_writer.rb

@@ -0,0 +1,49 @@
+########################################################################
+# File::    slow_writer.rb
+# (C)::     Loyalty New Zealand 2014
+#
+# Purpose:: Base class for slow log writers.
+# ----------------------------------------------------------------------
+#           16-Dec-2014 (ADH): Created.
+########################################################################
+
+module Hoodoo
+  class Logger
+
+    # Log writer classes are used through the Hoodoo::Logger class.
+    #
+    # Subclass SlowWriter if you are writing a log data output mechanism which
+    # does not respond very quickly. File output might fall into this category
+    # depending upon target deployment infrastructure; exporting logs to a
+    # remote logging service over the network would certainly qualify.
+    #
+    # The subclass only needs to implement
+    # Hoodoo::Logger::WriterMixin#report.
+    #
+    # If a slow writer cannot keep up with a high rate of log messages, some
+    # may be dropped. A +:warn+ level message is reported automatically for
+    # such cases, describing the number of dropped messages, once the slow
+    # writer has caught up.
+    #
+    # *IMPORTANT*: If you use ActiveRecord in a slow writer class, beware that
+    # your writer runs in a ruby Thread. Unless you take steps to prevent it,
+    # ActiveRecord will implicitly check out a connection which stays with
+    # your Thread forever. This steals a connection from the pool. To prevent
+    # this issue, you must use the following pattern:
+    #
+    #     def report( log_level, component, code, data )
+    #       ActiveRecord::Base.connection_pool.with_connection do
+    #         # ...Any AciveRecord code goes here...
+    #       end
+    #     end
+    #
+    # Code within the +with_connection+ block uses a temporary connection from
+    # the pool which is returned once the block has finished processing. Even
+    # if exceptions occur within your ActiveRecord code, the connection is
+    # still correctly returned to the pool using the above approach.
+    #
+    class SlowWriter
+      include Hoodoo::Logger::WriterMixin
+    end
+  end
+end

data/lib/hoodoo/logger/writer_mixin.rb

@@ -0,0 +1,52 @@
+########################################################################
+# File::    writer_mixin.rb
+# (C)::     Loyalty New Zealand 2014
+#
+# Purpose:: Common code for fast and slow log writer base classes.
+# ----------------------------------------------------------------------
+#           16-Dec-2014 (ADH): Created.
+########################################################################
+
+module Hoodoo
+  class Logger
+
+    # This mixin is used by Hoodoo::Logger::FastWriter and
+    # Hoodoo::Logger::SlowWriter. See those two classes for details.
+    #
+    module WriterMixin
+
+      # Hoodoo::Logger::FastWriter and Hoodoo::Logger::SlowWriter
+      # subclasses implement this method.
+      #
+      # Write a structured log message. Writers sending data somewhere with no
+      # structure support will need to serialize/flatten the message; others
+      # should retain data structures like hashes or arrays.
+      #
+      # The #report method is only invoked if the logging threshold level of
+      # the owning logger is set to an equal or lower level. Implementations
+      # do not, therefore, need to check this themselves.
+      #
+      # +log_level+:: Log level as a symbol - one of, from most trivial to most
+      #               severe, +:debug+, +:info+, +:warn+ or +:error+.
+      #
+      # +component+:: Component - for example, a resource name for a specific
+      #               service implementation, 'Middleware' for Hoodoo itself,
+      #               or some other name you think is useful. String or Symbol.
+      #
+      # +code+::      Component-defined code. Think of this in a manner similar
+      #               to platform error codes, appearing after the "."; messages
+      #               related to the same thing should share the same code. The
+      #               intent is to produce log data that someone can filter on
+      #               code to get useful information about that specific aspect
+      #               of a service implementation's behaviour.
+      #
+      # +data+::      A Hash containing the level, component and code-dependent
+      #               payload data to be logged. Converted to a string with
+      #               +inspect+ for flat output use in an unstructured context.
+      #
+      def report( log_level, component, code, data )
+        raise( 'Subclasses must implement #report' )
+      end
+    end
+  end
+end

data/lib/hoodoo/logger/writers/file_writer.rb

@@ -0,0 +1,45 @@
+########################################################################
+# File::    file_writer.rb
+# (C)::     Loyalty New Zealand 2014
+#
+# Purpose:: Write flat log messages to a file.
+# ----------------------------------------------------------------------
+#           16-Dec-2014 (ADH): Created.
+########################################################################
+
+module Hoodoo
+  class Logger
+
+    # Writes unstructured messages to a file. Hoodoo::Logger::SlowWriter
+    # subclass. See also Hoodoo::Logger.
+    #
+    class FileWriter < Hoodoo::Logger::SlowWriter
+
+      include Hoodoo::Logger::FlattenerMixin
+
+      # Create a file writer instance. Files are written by opening,
+      # adding a log message and closing again, to provide reliability.
+      # For this reason, this is a Hoodoo::Logger::SlowWriter subclass.
+      #
+      # If you want faster file access at the expense of immediate updates
+      # / reliability due to buffering, open a file externally to create an
+      # I/O stream and pass this persistently-open file's stream to an
+      # Hoodoo::Logger::StreamWriter class instead.
+      #
+      # +pathname+:: Full pathname of a file that can be opened in "ab"
+      #              (append for writing at end-of-file) mode.
+      #
+      def initialize( pathname )
+        @pathname = pathname
+      end
+
+      # See Hoodoo::Logger::WriterMixin#report.
+      #
+      def report( log_level, component, code, data )
+        File.open( @pathname, 'ab' ) do | file |
+          file.puts( flatten( log_level, component, code, data ) )
+        end
+      end
+    end
+  end
+end

data/lib/hoodoo/logger/writers/log_entries_dot_com_writer.rb

@@ -0,0 +1,64 @@
+########################################################################
+# File::    log_entries_dot_com_writer.rb
+# (C)::     Loyalty New Zealand 2014
+#
+# Purpose:: Write structured log messages logentries.com.
+# ----------------------------------------------------------------------
+#           08-Jan-2015 (ADH): Created.
+########################################################################
+
+require 'json'
+
+module Hoodoo
+  class Logger
+
+    begin          # Exception handler as 'le' gem inclusion is optional.
+      require 'le' # Might raise LoadError; that's allowed.
+
+      # Writes structured messages to logentries.com via the "le" gem,
+      # which uses its own asynchronous worker thread for network data.
+      # Thus, a Hoodoo::Logger::FastWriter subclass. See also
+      # Hoodoo::Logger.
+      #
+      class LogEntriesDotComWriter < Hoodoo::Logger::FastWriter
+
+        # Create a log writer instance.
+        #
+        # +token+:: Your logentries.com API token.
+        #
+        def initialize( token )
+          @@logger ||= Le.new( token, :ssl => true )
+        end
+
+        # See Hoodoo::Logger::WriterMixin#report.
+        #
+        def report( log_level, component, code, data )
+          method = case log_level
+            when :debug, :info, :warn, :error
+              log_level
+            else
+              :unknown
+          end
+
+          message = {
+            :level     => log_level,
+            :component => component,
+            :code      => code,
+            :data      => data
+          }
+
+          # This method is only called if the log level set elsewhere
+          # is already appropriate; always make sure that the 'LE' class
+          # logging level is as low as possible so it doesn't filter any
+          # additional messages accidentally.
+
+          @@logger.level = ::Logger::DEBUG
+          @@logger.send( method, ::JSON.generate( message ) )
+        end
+      end
+
+    rescue LoadError # From "require 'le'"
+    end
+
+  end
+end

data/lib/hoodoo/logger/writers/stream_writer.rb

@@ -0,0 +1,43 @@
+########################################################################
+# File::    file_writer.rb
+# (C)::     Loyalty New Zealand 2014
+#
+# Purpose:: Write flat log messages to an I/O stream - STDOUT by
+#           default.
+# ----------------------------------------------------------------------
+#           16-Dec-2014 (ADH): Created.
+########################################################################
+
+module Hoodoo
+  class Logger
+
+    # Writes unstructured messages to (presumed) fast output streams such as
+    # <tt>$stdout</tt>. Hoodoo::Logger::FastWriter subclass. See also
+    # Hoodoo::Logger.
+    #
+    class StreamWriter < Hoodoo::Logger::FastWriter
+
+      include Hoodoo::Logger::FlattenerMixin
+
+      # Create a stream writer instance. Although you could initialize this
+      # class with a slow output stream, they're expected to be fast (e.g.
+      # terminal output) as this is a Hoodoo::Logger::FastWriter subclass.
+      #
+      # For reliable file writing, use the Hoodoo::Logger::FileWriter class
+      # instead.
+      #
+      # +output_stream+:: Optional I/O stream instance; default is +$stdout+.
+      #                   The instance must provide a +puts+ implementation.
+      #
+      def initialize( output_stream = $stdout )
+        @output_stream = output_stream
+      end
+
+      # See Hoodoo::Logger::WriterMixin#report.
+      #
+      def report( log_level, component, code, data )
+        @output_stream.puts( flatten( log_level, component, code, data ) )
+      end
+    end
+  end
+end

data/lib/hoodoo/middleware.rb

@@ -0,0 +1,33 @@
+########################################################################
+# File::    middleware.rb
+# (C)::     Loyalty New Zealand 2014
+#
+# Purpose:: Include code implementing the Rack service middleware.
+# ----------------------------------------------------------------------
+#           26-Jan-2015 (ADH): Split from top-level inclusion file.
+########################################################################
+
+# Dependencies
+
+require 'hoodoo/utilities'
+require 'hoodoo/errors'
+require 'hoodoo/communicators'
+require 'hoodoo/logger'
+require 'hoodoo/discovery'
+require 'hoodoo/client'
+require 'hoodoo/presenters'
+
+# Middleware
+
+require 'hoodoo/services/middleware/rack_monkey_patch'
+require 'hoodoo/services/middleware/amqp_log_message'
+require 'hoodoo/services/middleware/amqp_log_writer'
+require 'hoodoo/services/middleware/interaction'
+require 'hoodoo/services/middleware/endpoints/inter_resource_remote'
+require 'hoodoo/services/middleware/endpoints/inter_resource_local'
+require 'hoodoo/services/middleware/middleware'
+
+require 'hoodoo/services/middleware/exception_reporting/exception_reporting'
+require 'hoodoo/services/middleware/exception_reporting/base_reporter'
+require 'hoodoo/services/middleware/exception_reporting/reporters/airbrake_reporter'
+require 'hoodoo/services/middleware/exception_reporting/reporters/raygun_reporter'

data/lib/hoodoo/presenters.rb

@@ -0,0 +1,45 @@
+########################################################################
+# File::    presenters.rb
+# (C)::     Loyalty New Zealand 2014
+#
+# Purpose:: Include the schema based data validation and rendering code.
+# ----------------------------------------------------------------------
+#           26-Jan-2015 (ADH): Split from top-level inclusion file.
+########################################################################
+
+module Hoodoo
+
+  # Module providing a namespace for schema-based data rendering and
+  # validation code.
+  #
+  module Presenters
+  end
+end
+
+# Dependencies
+
+require 'hoodoo/utilities'
+
+# Presenters
+
+require 'hoodoo/presenters/base'
+require 'hoodoo/presenters/base_dsl'
+require 'hoodoo/presenters/embedding'
+
+require 'hoodoo/presenters/types/field'
+require 'hoodoo/presenters/types/object'
+require 'hoodoo/presenters/types/array'
+require 'hoodoo/presenters/types/hash'
+require 'hoodoo/presenters/types/string'
+require 'hoodoo/presenters/types/text'
+require 'hoodoo/presenters/types/enum'
+require 'hoodoo/presenters/types/boolean'
+require 'hoodoo/presenters/types/float'
+require 'hoodoo/presenters/types/integer'
+require 'hoodoo/presenters/types/decimal'
+require 'hoodoo/presenters/types/date'
+require 'hoodoo/presenters/types/date_time'
+require 'hoodoo/presenters/types/tags'
+require 'hoodoo/presenters/types/uuid'
+
+require 'hoodoo/presenters/common_resource_fields'

data/lib/hoodoo/presenters/base.rb

@@ -0,0 +1,281 @@
+########################################################################
+# File::    base_presenter.rb
+# (C)::     Loyalty New Zealand 2014
+#
+# Purpose:: Schema-based data rendering and validation.
+# ----------------------------------------------------------------------
+#           02-Dec-2014 (ADH): Merge of DocumentedPresenter code into
+#                              Base.
+########################################################################
+
+module Hoodoo
+  module Presenters
+
+    # Base functionality for JSON validation and presenter (rendering) layers.
+    # Subclass this to define a schema against which validation of inbound data
+    # or rendering of outbound data can be performed. Call #schema in the
+    # subclass to declare, via the DSL, the shape of the schema.
+    #
+    class Base
+
+      # Define the JSON schema for validation.
+      #
+      # &block:: Block that makes calls to the DSL defined in
+      #          Hoodoo::Presenters::BaseDSL in order to define the schema.
+      #
+      def self.schema( &block )
+        @schema = Hoodoo::Presenters::Object.new
+        @schema.instance_eval( &block )
+        @schema_definition = block
+      end
+
+      # Given some data that should conform to the subclass presenter's schema,
+      # render it to go from the input Ruby Hash, to an output Ruby Hash which
+      # will include default values - if any - present in the schema and will
+      # drop input fields not present in that schema. In essence, this takes
+      # data which may have been programatically generated and sanitises it to
+      # produce valid, with-defaults guaranteed valid output.
+      #
+      # Field +kind+ is taken from the class name. If concerned about clashes
+      # between resource names and ActiveRecord model names, put your resource
+      # classes inside a module for namespacing - for example:
+      #
+      #     module Resources
+      #       class Product < Hoodoo::Presenters::Base
+      #         schema do
+      #           ...
+      #         end
+      #       end
+      #     end
+      #
+      # Only the class "leaf" name is used to infer the resource kind - in the
+      # above case, that's +Product+.
+      #
+      # Any field with a schema giving a default value will only appear should
+      # a value for that field be _omitted_ in the input data. If the data
+      # provides, for example, an explicit +nil+ value then a corresponding
+      # explicit +nil+ will be rendered, regardless of defaults.
+      #
+      # For belt-and-braces, unless subsequent profiling shows performance
+      # issues, callers should call #validate first to self-check their internal
+      # data against the schema prior to rendering. That way, coding errors
+      # will be discovered immediately, rather than hidden / obscured by the
+      # rendered sanitisation.
+      #
+      # Since rendering top-level +nil+ is not valid JSON, should +nil+ be
+      # provided as input, it'll be treated as an empty hash ("{}") instead.
+      #
+      # This is quite a low-level call. For a higher level renderer which
+      # Hoodoo service resource implementations will probably want to use for
+      # returning resource representations in responses, see ::render_in.
+      #
+      # +data+::       Hash to be represented. Data within this is compared
+      #                against the schema being called to ensure that correct
+      #                information is returned and unknown data is ignored.
+      #
+      # +uuid+::       Unique ID of the resource instance that is to be
+      #                represented. If nil / omitted, this is assumed to be
+      #                a rendering of a type or other non-resource like item.
+      #                Otherwise the field is mandatory.
+      #
+      # +created_at+:: Date/Time of instance creation. Only required if UUID
+      #                has been provided. This is a Ruby DateTime instance or
+      #                similar, _NOT_ a string!
+      #
+      # +language+::   Optional language. If the type/resource being rendered
+      #                is internationalised but this is omitted, then a value
+      #                of "en-nz" is used as a default.
+      #
+      def self.render( data, uuid = nil, created_at = nil, language = 'en-nz' )
+        target = {}
+        data   = data || {}
+
+        @schema.render( data, target )
+
+        # Common fields are added after rendering the data in case there are
+        # any same-named field collisions - platform defaults should take
+        # precedence, overwriting previous definitions intentionally.
+
+        unless ( uuid.nil? )
+
+          raise "Can't render a Resource with a nil 'created_at'" if created_at.nil?
+
+          # Field "kind" is taken from the class name; this is a class method
+          # so "self.name" yields "Hoodoo::Data::Resources::..." or similar.
+          # We could just use "split", but that creates an intermediate Array
+          # which uses more RAM and is about half the speed (or worse) of the
+          # following alternative (it turns out ActiveSupport 4's #demodulize
+          # uses much the same approach).
+
+          name  = self.name
+          index = ( name.rindex( '::' ) || -2 ) + 2
+          kind  = name[ index .. -1 ]
+
+          target.merge!( {
+            'id'         => uuid,
+            'kind'       => kind,
+            'created_at' => Time.parse( created_at.to_s ).utc.iso8601
+          } )
+
+          target[ 'language' ] = language if self.is_internationalised?()
+
+        end
+
+        return target
+      end
+
+      # A higher level version of ::render, typically called from Hoodoo
+      # services in their resource implementation code.
+      #
+      # As with ::render, data is rendered according to the schema of the
+      # object the ::render_in message is sent to. Options specify things like
+      # UUID and created-at date. Language information for internationalised
+      # fields can be given, but if omitted comes from the given request
+      # context data.
+      #
+      # Additional facilites exist over and above ::render - security scoping
+      # information in the resource via its +secured_with+ field is made
+      # available through options (see below), along with support for embedded
+      # or referenced resource information.
+      #
+      # +context+:: A Hoodoo::Services::Context instance, which is usually the
+      #             value passed to a service implementation in calls like
+      #             Hoodoo::Services::Implementation#list or
+      #             Hoodoo::Services::Implementation#show.
+      #
+      # +data+::    Hash to be represented. Data within this is compared
+      #             against the schema being called to ensure that correct
+      #             information is returned and unknown data is ignored.
+      #
+      # +options+:: Options hash, see below.
+      #
+      # The options keys are Symbols, used as follows:
+      #
+      # +uuid+::         Same as the +uuid+ parameter to ::render, except
+      #                  mandatory.
+      #
+      # +created_at+::   Same as the +created_at+ parameter to ::render, except
+      #                  mandatory.
+      #
+      # +language+::     Optional value for resource's +language+ field; taken
+      #                  from the +context+ parameter if omitted.
+      #
+      # +embeds+::       A Hoodoo::Presenters::Embedding::Embeds instance that
+      #                  contains (fully rendered) resources which are to be
+      #                  embedded in this rendered representation. Optional.
+      #
+      # +references+::   A Hoodoo::Presenters::Embedding::References instance
+      #                  that contains UUIDs which are to be embedded in this
+      #                  rendered representation as references. Optional.
+      #
+      # +secured_with+:: An ActiveRecord::Base subclass instance where the
+      #                  model class includes a +secure_with+ declaration. As
+      #                  per documentation for
+      #                  Hoodoo::ActiveRecord::Secure::ClassMethods#secure and
+      #                  Hoodoo::ActiveRecord::Secure::ClassMethods#secure_with,
+      #                  this leads (potentially) to the generation of the
+      #                  +secured_with+ field and object value in the rendered
+      #                  resource data.
+      #
+      def self.render_in( context, data, options = {} )
+        uuid         = options[ :uuid         ]
+        created_at   = options[ :created_at   ]
+        language     = options[ :language     ] || context.request.locale
+        secured_with = options[ :secured_with ]
+        embeds       = options[ :embeds       ]
+        references   = options[ :references   ]
+
+        target = self.render( data, uuid, created_at, language )
+
+        if secured_with.is_a?( ::ActiveRecord::Base )
+          result_hash     = {}
+          extra_scope_map = secured_with.class.secured_with()
+
+          extra_scope_map.each do | model_field_name, key_or_options |
+            resource_field = if key_or_options.is_a?( ::Hash )
+              next if key_or_options[ :hide_from_resource ] == true
+              key_or_options[ :resource_field_name ] || model_field_name
+            else
+              model_field_name
+            end
+
+            result_hash[ resource_field.to_s ] = secured_with.send( model_field_name )
+          end unless extra_scope_map.nil?
+
+          target[ 'secured_with' ] = result_hash unless result_hash.empty?
+        end
+
+        target[ '_embed'     ] = embeds.retrieve()     unless embeds.nil?
+        target[ '_reference' ] = references.retrieve() unless references.nil?
+
+        return target
+      end
+
+      # Is the given rendering of a resource valid? Returns an array of
+      # Error Primitive types (as hashes); this will be empty if the data
+      # given is valid.
+      #
+      # +data+:: Ruby Hash representation of JSON data that is to be validated
+      #          against 'this' schema. Keys must be Strings, not Symbols.
+      #
+      # +as_resource+:: Check Resource common fields - +id+, +kind+,
+      #                 +created_at+ and (for an internationalised resource)
+      #                 +language+. Otherwise, only basic data schema is
+      #                 examined. Optional; default is +false+.
+      #
+      def self.validate( data, as_resource = false )
+        errors = @schema.validate( data )
+
+        if as_resource
+          common_fields = {
+            'id'         => data[ :id         ],
+            'created_at' => data[ :created_at ],
+            'kind'       => data[ :kind       ]
+          }
+
+          if self.is_internationalised?
+            common_fields[ 'internationalised' ] = data[ 'internationalised' ]
+            Hoodoo::Presenters::CommonResourceFields.get_schema.properties[ 'language' ].required = true
+          end
+
+          errors.merge!( Hoodoo::Presenters::CommonResourceFields.validate( data, false ) )
+
+          Hoodoo::Presenters::CommonResourceFields.get_schema.properties[ 'language' ].required = false
+        end
+
+        return errors
+      end
+
+      # Walk the schema graph and invoke the given block on each field within
+      # it, passing the field instances to the block for each call.
+      #
+      # All fields including the top-level "root" property (which has an empty
+      # string for a name) will be passed to the block in order of definition,
+      # recursing into nested objects, arrays and so-on as each is encountered.
+      #
+      def self.walk( &block )
+        @schema.walk( &block )
+      end
+
+      # Does this presenter use internationalisation? Returns +true+ if so,
+      # else +false+.
+      #
+      def self.is_internationalised?
+        @schema.is_internationalised?
+      end
+
+      # Return the schema graph. See also #get_schema_definition.
+      #
+      def self.get_schema
+        @schema
+      end
+
+      # Read back the block that defined the schema graph. See also
+      # #get_schema.
+      #
+      def self.get_schema_definition
+        @schema_definition
+      end
+    end
+  end
+end