hoodoo 1.0.2

data/lib/hoodoo/presenters/common_resource_fields.rb

@@ -0,0 +1,31 @@
+########################################################################
+# File::    common_resource_fields.rb
+# (C)::     Loyalty New Zealand 2014
+#
+# Purpose:: Define a schema describing fields common to any schema that
+#           describes an API Resource.
+# ----------------------------------------------------------------------
+#           02-Dec-2014 (ADH): Split from DocumentedPresenter.
+########################################################################
+
+module Hoodoo
+  module Presenters
+
+    # Used internally for additional validation of common Resource fields.
+    # See Hoodoo::Presenters::Base::validate.
+    #
+    class CommonResourceFields < Hoodoo::Presenters::Base
+      schema do
+        uuid     :id,         :required => true
+        datetime :created_at, :required => true
+        text     :kind,       :required => true
+        text     :language
+
+        hash     :secured_with
+
+        hash     :_embed
+        hash     :_reference
+      end
+    end
+  end
+end

data/lib/hoodoo/presenters/embedding.rb

@@ -0,0 +1,232 @@
+########################################################################
+# File::    embedding.rb
+# (C)::     Loyalty New Zealand 2015
+#
+# Purpose:: Light weight, simple support for basic embed and reference
+#           operations that help reduce service reliance on "knowing"
+#           exactly how to structure such data / avoid inconsistency.
+# ----------------------------------------------------------------------
+#           29-Apr-2015 (ADH): Created.
+########################################################################
+
+module Hoodoo
+  module Presenters
+
+    # The Embedding namespace collects classes that assist with rendering
+    # embedded resource data.
+    #
+    module Embedding
+
+      # The Embeddable base class should not be instantiated directly.
+      # It provides common functionality for
+      # Hoodoo::Presenters::Embedding::Embeds and
+      # Hoodoo::Presenters::Embedding::References - use those instead.
+      #
+      class Embeddable
+
+        # Create an instance.
+        #
+        def initialize
+          @hash = {}
+        end
+
+        # Add a singlular resource (for embedding) or UUID (for referencing)
+        # to an embed or reference assembly.
+        #
+        # +key+:: The key to use in the resource representation leading to
+        #         the embedded resource object or UUID string. Typically
+        #         follows a singular name convention in your resource API
+        #         field language of choice, e.g. "member" (an API where the
+        #         resource names and fields are in English), "mitglied" (an
+        #         API described in German).
+        #
+        #         This key must match the value specified in the query string
+        #         of a request in order to ask for the thing in question to
+        #         be embedded / referenced.
+        #
+        # +rendered_resource_or_uuid+:: A rendered resource representation
+        #                               in full, or a resource UUID String.
+        #
+        def add_one( key, rendered_resource_or_uuid )
+          validate_one( rendered_resource_or_uuid )
+          @hash[ key ] = rendered_resource_or_uuid
+        end
+
+        # Add a collection of resources (for embedding) or UUIDs (for
+        # referencing) to an embed or reference assembly.
+        #
+        # +key+:: The key to use in the resource representation leading to
+        #         the embedded resource object or UUID string array. Typically
+        #         follows a plural name convention in your resource API field
+        #         language of choice, e.g. "members" (an API where the
+        #         resource names and fields are in English), "mitglieder" (an
+        #         API described in German).
+        #
+        #         This key must match the value specified in the query string
+        #         of a request in order to ask for the things in question to
+        #         be embedded / referenced.
+        #
+        # +array_of_rendered_resources_or_uuids+::
+        #         An Array of rendered resource representations in full, or an
+        #         Array of resource UUID Strings.
+        #
+        def add_many( key, array_of_rendered_resources_or_uuids )
+          validate_many( array_of_rendered_resources_or_uuids )
+          @hash[ key ] = array_of_rendered_resources_or_uuids
+        end
+
+        # Delete all data associated with the given key.
+        #
+        # +key+:: As provided to a prior call to #add_one or #add_many. Has no
+        #         side effects if the key has not been previously used in such
+        #         a call; no error is raised in this case either.
+        #
+        def remove( key )
+          @hash.delete( key )
+        end
+
+        # Returns a Hash where keys are the keys provided in calls to #add_one
+        # or #add_many and values are the values provided to those same
+        # corresponding calls. Returns an empty Hash if no such calls have
+        # been made or if all the keys were subsequently removed with #remove.
+        #
+        def retrieve
+          @hash
+        end
+      end
+
+      # Instantiate this class and add one, or an Array of fully rendered
+      # resource objects to it via the API described in the base class,
+      # Hoodoo::Presenters::Embedding::Embeddable. You can then pass it to
+      # the likes of Hoodoo::Presenters::Base.render_in via the +options+
+      # parameter to have the embed data included in the fully rendered end
+      # result.
+      #
+      # When a request arrives to embed data for a particular resource or
+      # list of resources (in which case, do the following for each item in
+      # that list):
+      #
+      # * Render the embedded resource(s)
+      # * Create an instance of this class
+      # * Add the rendered resource representations using this class's API
+      # * Use Hoodoo::Presenters::Base.render_in to render the final, target
+      #   resource, passing in the embed collection via the +options+ Hash.
+      #
+      # Simple example:
+      #
+      #     embeds = Hoodoo::Presenters::Embedding::Embeds.new
+      #     embeds.add_one( 'balance', rendered_balance )
+      #     embeds.add_many( 'vouchers', rendered_voucher_array )
+      #
+      class Embeds < Embeddable
+
+        public
+
+          # Returns the top-level resource key used for reference data, as per
+          # the API documentation - which is the String +_embed+.
+          #
+          def resource_key
+            '_embed'
+          end
+
+        protected
+
+          # Called from #add_one in the base class to make sure the right data
+          # is being supplied. Raises an exception if it gets worried.
+          #
+          # +thing+:: The value that'll be stored; should be a Hash.
+          #
+          def validate_one( thing )
+            unless thing.is_a?( ::Hash )
+              raise "Hoodoo::Presenters::Embedding::Embeds\#add_one requires a rendered resource Hash, but was given an instance of #{ thing.class }"
+            end
+          end
+
+          # Called from #add_many in the base class to make sure the right data
+          # is being supplied. Raises an exception if it gets worried.
+          #
+          # +thing+:: The value that'll be stored; should be an Array of Hashes
+          #           but only the first array entry is checked, for speed.
+          #
+          def validate_many( thing )
+            unless thing.is_a?( ::Array )
+              raise "Hoodoo::Presenters::Embedding::Embeds\#add_many requires an Array, but was given an instance of #{ thing.class }"
+            end
+
+            unless thing[ 0 ].nil? || thing[ 0 ].is_a?( ::Hash )
+              raise "Hoodoo::Presenters::Embedding::Embeds\#add_many requires an Array of rendered resource Hashes, but the first Array entry is an instance of #{ thing[ 0 ].class }"
+            end
+          end
+
+      end
+
+      # Instantiate this class and add one, or an Array of UUID strings via
+      # the API described in the base class,
+      # Hoodoo::Presenters::Embedding::Embeddable. You can then pass it to
+      # the likes of Hoodoo::Presenters::Base.render_in via the +options+
+      # parameter to have the reference data included in the fully rendered
+      # end result.
+      #
+      # When a request arrives to reference UUID data for a particular
+      # resource or list of resources (in which case, do the following for
+      # each item in that list):
+      #
+      # * Obtain the referenced resource UUID(s)
+      # * Create an instance of this class
+      # * Add the UUIDs using this class's API
+      # * Use Hoodoo::Presenters::Base.render_in to render the final, target
+      #   resource, passing in the reference collection via the +options+
+      #   Hash.
+      #
+      # Simple example:
+      #
+      #     references = Hoodoo::Presenters::Embedding::References.new
+      #     references.add_one( 'member', member_uuid )
+      #     references.add_many( 'memberships', array_of_membership_uuids )
+      #
+      class References < Embeddable
+
+        public
+
+          # Returns the top-level resource key used for reference data, as per
+          # the API documentation - which is the String +_reference+.
+          #
+          def resource_key
+            '_reference'
+          end
+
+        protected
+
+          # Called from #add_one in the base class to make sure the right data
+          # is being supplied. Raises an exception if it gets worried.
+          #
+          # +thing+:: The value that'll be stored; should be a valid UUID.
+          #
+          def validate_one( thing )
+            unless Hoodoo::UUID.valid?( thing )
+              raise 'Hoodoo::Presenters::Embedding::References#add_one requires a valid UUID String, but the given value is invalid'
+            end
+          end
+
+          # Called from #add_many in the base class to make sure the right data
+          # is being supplied. Raises an exception if it gets worried.
+          #
+          # +thing+:: The value that'll be stored; should be an Array of valid
+          #           UUIDs, but only the first array entry is checked, for
+          #           speed.
+          #
+          def validate_many( thing )
+            unless thing.is_a?( ::Array )
+              raise "Hoodoo::Presenters::Embedding::References\#add_many requires an Array, but was given an instance of #{ thing.class }"
+            end
+
+            unless thing[ 0 ].nil? || Hoodoo::UUID.valid?( thing[ 0 ] )
+              raise 'Hoodoo::Presenters::Embedding::References#add_many requires an Array of valid UUID strings, but the first Array entry is invalid'
+            end
+          end
+
+      end
+
+    end
+  end
+end

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

@@ -0,0 +1,118 @@
+module Hoodoo
+  module Presenters
+
+    # A JSON Array schema member.
+    #
+    class Array < Hoodoo::Presenters::Field
+
+      include Hoodoo::Presenters::BaseDSL
+
+      # The properties of this object, an +array+ of +Field+ instances.
+      #
+      attr_accessor :properties
+
+      # Check if data is a valid Array 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?( ::Array )
+          # No array entry schema? No array entry validation, then.
+          unless @properties.nil?
+            data.each_with_index do | item, index |
+              @properties.each do | name, property |
+                rdata = ( item.is_a?( ::Hash ) && item.has_key?( name ) ) ? item[ name ] : nil
+                indexed_path = "#{ full_path( path ) }[#{ index }]"
+                errors.merge!( property.validate( rdata, indexed_path ) )
+              end
+            end
+          end
+        else
+          errors.add_error(
+            'generic.invalid_array',
+            :message   => "Field `#{ full_path( path ) }` is an invalid array",
+            :reference => { :field_name => full_path( path ) }
+          )
+        end
+
+        errors
+      end
+
+      # Render an array into the target hash based on the internal state that
+      # describes this instance's current path (position in the heirarchy of
+      # nested schema entities).
+      #
+      # +data+::   The Array to render.
+      # +target+:: The Hash that we render into. A "path" of keys leading to
+      #            nested Hashes is built via +super()+, with the final
+      #            key entry yielding the rendered array.
+      #
+      def render( data, target )
+
+        # Data provided is explicitly nil or not an array? Don't need to render
+        # anything beyond 'nil' at the field (the not-array case covers nil and
+        # covers invalid input, which is treated as nil).
+
+        return super( nil, target ) if ! data.is_a?( ::Array )
+
+        # Otherwise, start looking at rendering array contents (even if the
+        # input array is empty). This relies on pass-by-reference; we'll update
+        # this specific instance of 'array' later. Call 'super' to render the
+        # 'array' instance in place in 'target' straight away...
+
+        array = []
+        path  = super( array, target )
+
+        # ...then look at rendering the input entries of 'data' into 'array'.
+
+        if @properties.nil?
+          # Must modify existing instance of 'array', so use 'push()'
+          array.push( *data )
+
+        else
+          data.each do | item |
+
+            # We have properties defined so array values (in "item") must be
+            # Hashes. If non-Hash, treat as if nil; explicit-nil-means-nil.
+
+            unless item.is_a?( ::Hash )
+              # Must modify existing instance of 'array', so use 'push()'
+              array.push( nil )
+              next
+            end
+
+            subtarget = {}
+
+            @properties.each do | name, property |
+              name    = name.to_s
+              has_key = item.has_key?( name )
+
+              next unless has_key || property.has_default?()
+
+              property.render( has_key ? item[ name ] : property.default, subtarget )
+            end
+
+            rendered = subtarget.empty? ? {} : read_at_path( subtarget, path )
+
+            # Must modify existing instance of 'array', so use 'push()'
+            array.push( rendered )
+          end
+        end
+      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/boolean.rb

@@ -0,0 +1,26 @@
+module Hoodoo
+  module Presenters
+
+    # A JSON Boolean schema member.
+    #
+    class Boolean < Hoodoo::Presenters::Field
+
+      # Check if data is a valid Boolean 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 == data
+          errors.add_error(
+            'generic.invalid_boolean',
+            :message   => "Field `#{ full_path( path ) }` is an invalid boolean",
+            :reference => { :field_name => full_path( path ) }
+          )
+        end
+
+        errors
+      end
+    end
+  end
+end

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

@@ -0,0 +1,26 @@
+module Hoodoo
+  module Presenters
+
+    # A JSON Date schema member.
+    #
+    class Date < Hoodoo::Presenters::Field
+
+      # Check if data is a valid Date 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::Utilities.valid_iso8601_subset_date?( data )
+          errors.add_error(
+            'generic.invalid_date',
+            :message   => "Field `#{ full_path( path ) }` is an invalid ISO8601 date",
+            :reference => { :field_name => full_path( path ) }
+          )
+        end
+
+        errors
+      end
+    end
+  end
+end

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

@@ -0,0 +1,26 @@
+module Hoodoo
+  module Presenters
+
+    # A JSON DateTime schema member.
+    #
+    class DateTime < Hoodoo::Presenters::Field
+
+      # Check if data is a valid DateTime 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::Utilities.valid_iso8601_subset_datetime?( data )
+          errors.add_error(
+            'generic.invalid_datetime',
+            :message   => "Field `#{ full_path( path ) }` is an invalid ISO8601 datetime",
+            :reference => { :field_name => full_path( path ) }
+          )
+        end
+
+        errors
+      end
+    end
+  end
+end