hoodoo 1.0.2

data/lib/hoodoo/presenters/types/integer.rb

@@ -0,0 +1,26 @@
+module Hoodoo
+  module Presenters
+
+    # A JSON Integer schema member.
+    #
+    class Integer < Hoodoo::Presenters::Field
+
+      # Check if data is a valid Integer and return a Hoodoo::Errors instance.
+      #
+      def validate( data, path = '' )
+        errors = super( data, path )
+        return errors if errors.has_errors? || ( ! @required && data.nil? )
+
+        unless data.is_a?( ::Integer )
+          errors.add_error(
+            'generic.invalid_integer',
+            :message   => "Field `#{ full_path( path ) }` is an invalid integer",
+            :reference => { :field_name => full_path( path ) }
+          )
+        end
+
+        errors
+      end
+    end
+  end
+end

data/lib/hoodoo/presenters/types/object.rb

@@ -0,0 +1,117 @@
+module Hoodoo
+  module Presenters
+
+    # A JSON Object schema member.
+    #
+    class Object < Hoodoo::Presenters::Field
+
+      include Hoodoo::Presenters::BaseDSL
+
+      # The properties of this object; a Hash of +Field+ instances keyed by
+      # field name.
+      #
+      attr_accessor :properties
+
+      # Initialize an Object instance with the appropriate name and options.
+      #
+      # +name+::    The JSON key.
+      # +options+:: A +Hash+ of options, e.g. :required => true.
+      #
+      def initialize( name = nil, options = {} )
+        super( name, options )
+
+        @properties        = {}
+        @internationalised = false
+      end
+
+      # Check if data is a valid Object and return a Hoodoo::Errors instance
+      # with zero (valid) or more (has validation problems) errors inside.
+      #
+      # +data+:: Data to check (and check nested properties therein). Expected
+      #          to be nil (unless field is required) or a Hash.
+      #
+      # +path+:: For internal callers only in theory - the human-readable
+      #          nesting path to this "level", as an array. Omitted at the top
+      #          level. In :errors => { :foo => { ... } }, validation of ":foo"
+      #          would be at path "[ :errors ]". Validation of the contents of
+      #          the object at ":foo" would be under "[ :errors, :foo ]".
+      #
+      def validate( data, path = '' )
+        errors = super( data, path )
+        return errors if !@required and data.nil? # If there are existing errors, we carry on and validate internally too
+
+        if ! data.nil? && ! data.is_a?( ::Hash )
+          errors.add_error(
+            'generic.invalid_object',
+            :message   => "Field `#{ full_path( path ) }` is an invalid object",
+            :reference => { :field_name => full_path( path ) }
+          )
+        end
+
+        @properties.each do | name, property |
+          rdata = ( data.is_a?( ::Hash ) && data.has_key?( name ) ) ? data[ name ] : nil
+          errors.merge!( property.validate( rdata, full_path( path ) ) )
+        end
+
+        errors
+      end
+
+      # Render inbound data into a target hash according to the schema,
+      # applying defaults where defined for fields with no value supplied
+      # in the inbound data.
+      #
+      # +data+::   Inbound data to render.
+      #
+      # +target+:: For internal callers only in theory. The target hash into
+      #            which rendering should occur. This may then be merged into
+      #            outer level hashes as part of nested items defined in the
+      #            schema.
+      #
+      def render( data, target )
+
+        # In an simple field, e.g. a text field, then whether or not it has
+        # a default, should someone give a value of "nil" we expect that field
+        # to be rendered in output with the explicitly provided "nil" value.
+        # We thus apply the same to objects. A field with an associated object,
+        # if rendered with an explicit "nil", renders as just that.
+        #
+        return super( nil, target ) unless data.is_a?( ::Hash ) # nil or invalid
+
+        have_rendered_something = false
+
+        @properties.each do | name, property |
+          name    = name.to_s
+          has_key = data.has_key?( name )
+
+          next unless has_key || property.has_default?()
+
+          have_rendered_something = true
+          property.render( has_key ? data[ name ] : property.default, target )
+        end
+
+        # If someone passes an empty object for a field and the object schema
+        # includes no default values, then the above code would render nothing
+        # as no properties have associated keys in the input data, and none of
+        # them have default values either. Make sure we render the field for
+        # this object with the associated empty object given by the input data
+        # in such cases.
+        #
+        super( {}, target ) unless have_rendered_something
+
+      end
+
+      # Invoke a given block, passing this item; call recursively for any
+      # defined sub-fields too. See Hoodoo::Presenters::Base#walk for why.
+      #
+      # &block:: Mandatory block, which is passed 'self' when called.
+      #
+      def walk( &block )
+        block.call( self )
+
+        @properties.each do | name, property |
+          property.walk( &block )
+        end unless @properties.nil?
+      end
+    end
+  end
+end

data/lib/hoodoo/presenters/types/string.rb

@@ -0,0 +1,53 @@
+module Hoodoo
+  module Presenters
+
+    # A JSON String schema member.
+    #
+    class String < Hoodoo::Presenters::Field
+
+      # The maximum length of the String.
+      #
+      attr_accessor :length
+
+      # Initialize a String instance with the appropriate name and options.
+      #
+      # +name+::    The JSON key.
+      # +options+:: A +Hash+ of options, e.g. :required => true, :length => 10.
+      #
+      def initialize( name, options = {} )
+        super( name, options )
+
+        unless options.has_key?( :length )
+          raise ArgumentError.new( 'Hoodoo::Presenters::String must have a :length' )
+        end
+
+        @length = options[ :length ]
+      end
+
+      # Check if data is a valid String and return a Hoodoo::Errors instance.
+      #
+      def validate( data, path = '' )
+        errors = super( data, path )
+        return errors if errors.has_errors? || ( ! @required && data.nil? )
+
+        if data.is_a?( ::String )
+          if data.size > @length
+            errors.add_error(
+              'generic.invalid_string',
+              :message   => "Field `#{ full_path( path ) }` is longer than maximum length `#{ @length }`",
+              :reference => { :field_name => full_path( path ) }
+            )
+          end
+        else
+          errors.add_error(
+            'generic.invalid_string',
+            :message   => "Field `#{ full_path( path ) }` is an invalid string",
+            :reference => { :field_name => full_path( path ) }
+          )
+        end
+
+        errors
+      end
+    end
+  end
+end

data/lib/hoodoo/presenters/types/tags.rb

@@ -0,0 +1,24 @@
+########################################################################
+# File::    tags.rb
+# (C)::     Loyalty New Zealand 2014
+#
+# Purpose:: Hoodoo::Presenters::BaseDSL field implementation
+#           which supports a field defined to contain a string of
+#           comma separated tags.
+# ----------------------------------------------------------------------
+#           30-Sep-2014 (ADH): Created.
+#           31-Oct-2014 (ADH): Moved to generic presenter layer from
+#                              documented data layer.
+########################################################################
+
+module Hoodoo
+  module Presenters
+
+    # A JSON string-like schema member intended to hold tag data.
+    #
+    class Tags < Hoodoo::Presenters::Text
+      # TODO: Note inheritance from "...::Text" not "...::Field"
+      # TODO: Future validations to ensure string looks tag-like?
+    end
+  end
+end

data/lib/hoodoo/presenters/types/text.rb

@@ -0,0 +1,26 @@
+module Hoodoo
+  module Presenters
+
+    # A JSON String schema member - unlimited length String.
+    #
+    class Text < Hoodoo::Presenters::Field
+
+      # Check if data is a valid String and return a Hoodoo::Errors instance.
+      #
+      def validate( data, path = '' )
+        errors = super( data, path )
+        return errors if errors.has_errors? || ( ! @required && data.nil? )
+
+        unless data.is_a?( ::String )
+          errors.add_error(
+            'generic.invalid_string',
+            :message   => "Field `#{ full_path( path ) }` is an invalid string",
+            :reference => { :field_name => full_path( path ) }
+          )
+        end
+
+        errors
+      end
+    end
+  end
+end

data/lib/hoodoo/presenters/types/uuid.rb

@@ -0,0 +1,54 @@
+########################################################################
+# File::    documented_uuid.rb
+# (C)::     Loyalty New Zealand 2014
+#
+# Purpose:: Hoodoo::Presenters::BaseDSL field implementation
+#           which supports a field defined to contain a UUID that
+#           (optionally) can be verified as referring to a specific
+#           other Resource.
+# ----------------------------------------------------------------------
+#           22-Sep-2014 (ADH): Created.
+#           31-Oct-2014 (ADH): Moved to generic presenter layer from
+#                              documented data layer.
+########################################################################
+
+module Hoodoo
+  module Presenters
+
+    # A JSON UUID schema member.
+    #
+    class UUID < Hoodoo::Presenters::Field
+
+      # The optional associated resource kind, as a symbol (e.g. ':Product').
+      #
+      attr_accessor :resource
+
+      # Initialize a UUID instance with the appropriate name and options.
+      #
+      # +name+::    The JSON key.
+      # +options+:: A +Hash+ of options, e.g. :resource => :Product, :required => true.
+      #
+      def initialize( name, options = {} )
+        @resource = options.delete( :resource )
+        super name, options
+      end
+
+      # Check if data is a valid UUID and return a Hoodoo::Errors instance.
+      #
+      def validate( data, path = '' )
+        errors = super( data, path )
+        return errors if errors.has_errors? || ( ! @required && data.nil? )
+
+        unless Hoodoo::UUID.valid?( data )
+          errors.add_error(
+            'generic.invalid_uuid',
+            :message   => "Field `#{ full_path( path ) }` is an invalid UUID",
+            :reference => { :field_name => full_path( path ) }
+          )
+        end
+
+        errors
+      end
+    end
+  end
+end

data/lib/hoodoo/services.rb

@@ -0,0 +1,34 @@
+########################################################################
+# File::    services.rb
+# (C)::     Loyalty New Zealand 2014
+#
+# Purpose:: Include code useful to client service applications.
+# ----------------------------------------------------------------------
+#           26-Jan-2015 (ADH): Split from top-level inclusion file.
+########################################################################
+
+module Hoodoo
+
+  # Module providing a namespace for code useful to client service
+  # applications and the supporting middleware.
+  #
+  module Services
+  end
+end
+
+# Dependencies
+
+require 'hoodoo/utilities'
+require 'hoodoo/logger'
+
+# Services
+
+require 'hoodoo/services/services/permissions'
+require 'hoodoo/services/services/session'
+require 'hoodoo/services/services/session'
+require 'hoodoo/services/services/request'
+require 'hoodoo/services/services/response'
+require 'hoodoo/services/services/context'
+require 'hoodoo/services/services/interface'
+require 'hoodoo/services/services/implementation'
+require 'hoodoo/services/services/service'

data/lib/hoodoo/services/discovery/discoverers/by_consul.rb

@@ -0,0 +1,66 @@
+########################################################################
+# File::    by_consul.rb
+# (C)::     Loyalty New Zealand 2015
+#
+# Purpose:: Discover resource endpoint locations via a registry held in
+#           Consul. For AMQP-based endpoints; maps paths to queue names.
+#           PLACEHOLDER: NOT YET IMPLEMENTED.
+# ----------------------------------------------------------------------
+#           03-Mar-2015 (ADH): Created.
+########################################################################
+
+module Hoodoo
+  module Services
+    class Discovery # Just used as a namespace here
+
+      # Discover resource endpoint locations via a registry held in
+      # Consul. For AMQP-based endpoints; maps paths to queue names.
+      #
+      class ByConsul < Hoodoo::Services::Discovery
+
+        protected
+
+          # Announce the location of an instance to Consul.
+          #
+          # Call via Hoodoo::Services::Discovery::Base#announce.
+          #
+          # TODO: NOT YET IMPLEMENTED. Placeholder only.
+          #
+          # +resource+:: Passed to #discover_remote.
+          # +version+::  Passed to #discover_remote.
+          # +options+::  Ignored. TODO: Queue name, equivalent path.
+          #
+          def announce_remote( resource, version, options = {} )
+            return discover_remote( resource, version ) # TODO: Replace
+          end
+
+          # Discover the location of an instance using Consul.
+          #
+          # TODO: This currently doesn't use Consul at all! It has a
+          # TODO: hard-coded mapping.
+          #
+          # Returns a Hoodoo::Services::Discovery::ForAMQP instance if
+          # the endpoint is found, else +nil+.
+          #
+          # Call via Hoodoo::Services::Discovery::Base#announce.
+          #
+          # +resource+:: Passed to #discover_remote.
+          # +version+::  Passed to #discover_remote.
+          #
+          def discover_remote( resource, version )
+
+            queue = "service.#{ resource.to_s.downcase }"
+            path  = "/v#{ version }/#{ resource.to_s.downcase.pluralize }"
+
+            return Hoodoo::Services::Discovery::ForAMQP.new(
+              resource:        resource,
+              version:         version,
+              queue_name:      queue,
+              equivalent_path: path
+            )
+          end
+
+      end
+    end
+  end
+end

data/lib/hoodoo/services/discovery/discoverers/by_convention.rb

@@ -0,0 +1,173 @@
+########################################################################
+# File::    by_convention.rb
+# (C)::     Loyalty New Zealand 2015
+#
+# Purpose:: Discover - after a fashion - resource endpoint locations
+#           by convention, based on Rails-like pluralisation rules. For
+#           HTTP-based endpoints. Requires ActiveSupport.
+# ----------------------------------------------------------------------
+#           03-Mar-2015 (ADH): Created.
+########################################################################
+
+module Hoodoo
+  module Services
+    class Discovery # Just used as a namespace here
+
+      begin
+        require 'active_support/inflector'
+
+        # Discover - after a fashion - resource endpoint locations
+        # by convention, based on Rails-like pluralisation rules. For
+        # HTTP-based endpoints. Requires ActiveSupport.
+        #
+        # https://rubygems.org/gems/activesupport
+        #
+        # See #configure_with for details of required instantiation
+        # options. See #discover_remote for the returned data type.
+        #
+        class ByConvention < Hoodoo::Services::Discovery
+
+          protected
+
+            # Configure an instance. Call via
+            # Hoodoo::Services::Discovery::Base#new. Parameters:
+            #
+            # +options+:: Options hash as described below.
+            #
+            # Options are:
+            #
+            # +base_uri+::     A String giving the base URI at which resource
+            #                  endpoint implementations can be found. The
+            #                  protocol (HTTP or HTTPS), host and port are of
+            #                  interest. The path will be overwritten with
+            #                  by-convention values for individual resources.
+            #
+            # +proxy_uri+::    An optional full URI of an HTTP proxy to use if
+            #                  the base URI commands use of HTTP or HTTPS. Ruby
+            #                  will itself read <tt>ENV['HTTP_PROXY']</tt> if
+            #                  set; this option will _override_ that variable.
+            #                  Set as a String, as with +base_uri+.
+            #
+            # +ca_file+::      An optional String indicating a relative or
+            #                  absolute file path to the location of a +.pem+
+            #                  format Certificate Authority file (trust store),
+            #                  which may include multliple certificates. The
+            #                  certificates in the file will be used by
+            #                  Net::HTTP to validate the SSL ceritificate
+            #                  chain presented by remote servers, when calling
+            #                  endpoints over HTTPS with Hoodoo::Client.
+            #
+            #                  Default +nil+ value should be used in nearly all
+            #                  cases and uses Ruby OpenSSL defaults which are
+            #                  generally Operating System provided.
+            #
+            # +http_timeout+:: Optional Float indicating the Net::HTTP read
+            #                  timeout value. This operates at the HTTP
+            #                  transport level and is independent of any
+            #                  timeouts set within the API providing server.
+            #
+            # +routing+::      An optional parameter which gives custom routing
+            #                  for exception cases where the by-convention map
+            #                  doesn't work. This is usually because there is a
+            #                  resource singleton which lives logically at a
+            #                  singular named route rather than plural route,
+            #                  e.g. "/v1/health" rather than "/v1/healths".
+            #
+            # The +routing+ parameter is a Hash of Resource names _as_
+            # _Symbols_, then values which are Hash of API Version _as_
+            # _Integers_ with values that are the Strings giving the
+            # full alternative routing path.
+            #
+            # For example, by convention API version 2 of a Health resource
+            # would be routed to "/v2/healths". You would override this to a
+            # singular route with this +routing+ parameter Hash:
+            #
+            #     {
+            #       :Health => {
+            #         2 => '/v2/health'
+            #       }
+            #     }
+            #
+            # This would leave version 1 of the endpoint (or any other version
+            # for that matter) still at the by-convention "v<x>/healths" path.
+            #
+            # Changing the "v<x>" convention for the version part of the path
+            # will break Hoodoo compatibility, but this is still allowed in
+            # the override in case you have unusual configurations or HTTP
+            # layer rewrites that redirect requests to paths that do map down
+            # to Hoodoo, or perhaps map to a Hoodoo-like system that's not
+            # actually Hoodoo itself but implemented in a compatible fashion.
+            #
+            def configure_with( options )
+              @base_uri     = URI.parse( options[ :base_uri  ] )
+              @proxy_uri    = URI.parse( options[ :proxy_uri ] ) unless options[ :proxy_uri ].nil?
+              @ca_file      = options[ :ca_file ]
+              @http_timeout = options[ :http_timeout ]
+              @routing      = options[ :routing ] || {}
+            end
+
+            # Announce the location of an instance. This is really a no-op
+            # that runs through and returns the result of #discover_remote.
+            #
+            # Call via Hoodoo::Services::Discovery::Base#announce.
+            #
+            # +resource+:: Passed to #discover_remote.
+            # +version+::  Passed to #discover_remote.
+            # +options+::  Ignored.
+            #
+            def announce_remote( resource, version, options = {} )
+              return discover_remote( resource, version )
+            end
+
+            # Using the base URI string from the options in configure_with,
+            # underscore and pluralize the resource name with ActiveSupport
+            # to produce a path. For example:
+            #
+            # * Version 3 of resource Member results in
+            #   <tt>/v3/members</tt>
+            #
+            # * Version 2 of resource FarmAnimal results in
+            #   <tt>/v2/farm_animals</tt>
+            #
+            # Returns a Hoodoo::Services::Discovery::ForHTTP instance.
+            #
+            # The use of ActiveSupport means that pluralisation is subject to
+            # the well known Rails limitations and quirks. The behaviour can
+            # be overridden using the optional +routing+ parameter in the
+            # constructor.
+            #
+            # Call via Hoodoo::Services::Discovery::Base#discover.
+            #
+            # +resource+:: Resource name as a _String_.
+            # +version+::  Endpoint version as an Integer.
+            #
+            def discover_remote( resource, version )
+              custom_routes = @routing[ resource.to_sym ]
+
+              path = unless custom_routes.nil?
+                custom_routes[ version ]
+              end
+
+              path ||= "/v#{ version }/#{ resource.to_s.underscore.pluralize }"
+
+              endpoint_uri      = @base_uri.dup
+              endpoint_uri.path = path
+
+              return Hoodoo::Services::Discovery::ForHTTP.new(
+                resource:     resource,
+                version:      version,
+                endpoint_uri: endpoint_uri,
+                proxy_uri:    @proxy_uri,
+                ca_file:      @ca_file,
+                http_timeout: @http_timeout
+              )
+            end
+
+        end
+
+      rescue LoadError
+      end
+
+    end
+  end
+end