weasel_diesel 1.0.0

data/lib/params_verification.rb

@@ -0,0 +1,268 @@
+# ParamsVerification module.
+# Written to verify a service params without creating new objects.
+# This module is used on all requests requiring validation and therefore performance
+# security and maintainability are critical.
+#
+# @api public
+module ParamsVerification
+  
+  class ParamError        < StandardError; end #:nodoc
+  class NoParamsDefined   < ParamError; end #:nodoc
+  class MissingParam      < ParamError; end #:nodoc
+  class UnexpectedParam   < ParamError; end #:nodoc
+  class InvalidParamType  < ParamError; end #:nodoc
+  class InvalidParamValue < ParamError; end #:nodoc
+  
+  # An array of validation regular expressions.
+  # The array gets cached but can be accessed via the symbol key.
+  #
+  # @return [Hash] An array with all the validation types as keys and regexps as values.
+  # @api public
+  def self.type_validations
+    @type_validations ||= { :integer  => /^-?\d+$/,
+                            :float    => /^-?(\d*\.\d+|\d+)$/,
+                            :decimal  => /^-?(\d*\.\d+|\d+)$/,
+                            :datetime => /^[-\d:T\s\+]+$/,  # "T" is for ISO date format
+                            :boolean  => /^(1|true|TRUE|T|Y|0|false|FALSE|F|N)$/,
+                            #:array    => /,/
+                          }
+  end
+  
+  # Validation against each required WeaselDiesel::Params::Rule
+  # and returns the potentially modified params (with default values)
+  # 
+  # @param [Hash] params The params to verify (incoming request params)
+  # @param [WeaselDiesel::Params] service_params A Playco service param compatible object listing required and optional params 
+  # @param [Boolean] ignore_unexpected Flag letting the validation know if unexpected params should be ignored
+  #
+  # @return [Hash]
+  #   The passed params potentially modified by the default rules defined in the service.
+  #
+  # @example Validate request params against a service's defined param rules
+  #   ParamsVerification.validate!(request.params, @service.defined_params)
+  # 
+  # @api public
+  def self.validate!(params, service_params, ignore_unexpected=false)
+    
+    # Verify that no garbage params are passed, if they are, an exception is raised.
+    # only the first level is checked at this point
+    unless ignore_unexpected
+      unexpected_params?(params, service_params.param_names)
+    end
+    
+    # dupe the params so we don't modify the passed value
+    updated_params = params.dup
+    # Required param verification
+    service_params.list_required.each do |rule|
+      updated_params = validate_required_rule(rule, updated_params)
+    end
+    
+    # Set optional defaults if any optional
+    service_params.list_optional.each do |rule|
+      updated_params = run_optional_rule(rule, updated_params)
+    end
+    
+    # check the namespaced params
+    service_params.namespaced_params.each do |param|
+      param.list_required.each do |rule|
+        updated_params = validate_required_rule(rule, updated_params, param.space_name.to_s)
+      end
+      param.list_optional.each do |rule|
+        updated_params = run_optional_rule(rule, updated_params, param.space_name.to_s)
+      end
+
+    end
+    
+    # verify nested params, only 1 level deep tho
+    params.each_pair do |key, value|
+      if value.is_a?(Hash)
+        namespaced = service_params.namespaced_params.find{|np| np.space_name.to_s == key.to_s}
+        raise UnexpectedParam, "Request included unexpected parameter: #{key}" if namespaced.nil?
+        unexpected_params?(params[key], namespaced.param_names)
+      end
+    end
+    
+    updated_params
+  end
+  
+  
+  private
+  
+  # Validate a required rule against a list of params passed.
+  #
+  #
+  # @param [WeaselDiesel::Params::Rule] rule The required rule to check against.
+  # @param [Hash] params The request params.
+  # @param [String] namespace Optional param namespace to check the rule against.
+  #
+  # @return [Hash]
+  #   A hash representing the potentially modified params after going through the filter.
+  #
+  # @api private
+  def self.validate_required_rule(rule, params, namespace=nil)
+    param_name  = rule.name.to_s
+    
+    param_value, namespaced_params = extract_param_values(params, param_name, namespace)
+    # puts "verify #{param_name} params, current value: #{param_value}"
+    
+    #This is disabled since required params shouldn't have a default, otherwise, why are they required?
+    #if param_value.nil? && rule.options && rule.options[:default]
+      #param_value = rule.options[:default]
+    #end
+
+    # Checks presence
+    if !(namespaced_params || params).keys.include?(param_name)
+      raise MissingParam, "'#{rule.name}' is missing - passed params: #{params.inspect}."
+    # checks null
+    elsif param_value.nil? && !rule.options[:null]
+      raise  InvalidParamValue, "Value for parameter '#{param_name}' is missing - passed params: #{params.inspect}."
+    # checks type
+    elsif rule.options[:type]
+      verify_cast(param_name, param_value, rule.options[:type])
+    end
+
+    if rule.options[:options] || rule.options[:in]
+      choices = rule.options[:options] || rule.options[:in]
+      if rule.options[:type]
+        # Force the cast so we can compare properly
+        param_value = params[param_name] = type_cast_value(rule.options[:type], param_value)
+      end
+      raise InvalidParamValue, "Value for parameter '#{param_name}' (#{param_value}) is not in the allowed set of values." unless choices.include?(param_value)
+    # You can have a "in" rule that also applies a min value since they are mutually exclusive
+    elsif rule.options[:minvalue]
+      min = rule.options[:minvalue]
+      raise InvalidParamValue, "Value for parameter '#{param_name}' is lower than the min accepted value (#{min})." if param_value.to_i < min
+    end
+    # Returns the updated params
+    
+    # cast the type if a type is defined and if a range of options isn't defined since the casting should have been done already
+    if rule.options[:type] && !(rule.options[:options] || rule.options[:in])
+      # puts "casting #{param_value} into type: #{rule.options[:type]}"
+      params[param_name] = type_cast_value(rule.options[:type], param_value)
+    end
+    params
+  end
+
+
+  # Extract the param valie and the namespaced params
+  # based on a passed namespace and params
+  #
+  # @param [Hash] params The passed params to extract info from.
+  # @param [String] param_name The param name to find the value.
+  # @param [NilClass, String] namespace the params' namespace.
+  # @return [Arrays<Object, String>]
+  #
+  # @api private
+  def self.extract_param_values(params, param_name, namespace=nil)
+    # Namespace check
+    if namespace == '' || namespace.nil?
+      [params[param_name], nil]
+    else
+      # puts "namespace: #{namespace} - params #{params[namespace].inspect}"
+      namespaced_params = params[namespace]
+      if namespaced_params
+        [namespaced_params[param_name], namespaced_params]
+      else
+        [nil, namespaced_params]
+      end
+    end
+  end
+  
+  # @param [#WeaselDiesel::Params::Rule] rule The optional rule
+  # @param [Hash] params The request params
+  # @param [String] namespace An optional namespace
+  # @return [Hash] The potentially modified params
+  # 
+  # @api private
+  def self.run_optional_rule(rule, params, namespace=nil)
+    param_name  = rule.name.to_s
+
+    param_value, namespaced_params = extract_param_values(params, param_name, namespace)
+
+    if param_value.nil? && rule.options[:default]
+      if namespace
+        params[namespace][param_name] = param_value = rule.options[:default]
+      else
+        params[param_name] = param_value = rule.options[:default]
+      end
+    end
+    
+    # cast the type if a type is defined and if a range of options isn't defined since the casting should have been done already
+    if rule.options[:type] && !param_value.nil?
+      if namespace
+        params[namespace][param_name] = param_value = type_cast_value(rule.options[:type], param_value)
+      else
+        params[param_name] = param_value = type_cast_value(rule.options[:type], param_value)
+      end
+    end
+
+    choices = rule.options[:options] || rule.options[:in]
+    if choices && param_value && !choices.include?(param_value)
+      raise InvalidParamValue, "Value for parameter '#{param_name}' (#{param_value}) is not in the allowed set of values."
+    end
+    
+    params
+  end
+  
+  def self.unexpected_params?(params, param_names)
+    # Raise an exception unless no unexpected params were found
+    unexpected_keys = (params.keys - param_names)
+    unless unexpected_keys.empty?
+      raise UnexpectedParam, "Request included unexpected parameter(s): #{unexpected_keys.join(', ')}"
+    end
+  end
+  
+  
+  def self.type_cast_value(type, value)
+    case type
+    when :integer
+      value.to_i
+    when :float, :decimal
+      value.to_f
+    when :string
+      value.to_s
+    when :boolean
+      if value.is_a? TrueClass
+        true
+      elsif value.is_a? FalseClass
+        false
+      else
+        case value.to_s
+        when /^(1|true|TRUE|T|Y)$/
+          true
+        when /^(0|false|FALSE|F|N)$/
+          false
+        else
+          raise InvalidParamValue, "Could not typecast boolean to appropriate value"
+        end
+      end
+    # An array type is a comma delimited string, we need to cast the passed strings.
+    when :array
+      value.respond_to?(:split) ? value.split(',') : value
+    when :binary, :array, :file
+      value
+    else
+      value
+    end
+  end
+  
+  # Checks that the value's type matches the expected type for a given param
+  #
+  # @param [Symbol, String] Param name used if the verification fails and that an error is raised.
+  # @param [#to_s] The value to validate.
+  # @param [Symbol] The expected type, such as :boolean, :integer etc...
+  # @raise [InvalidParamType] Custom exception raised when the validation isn't found or the value doesn't match.
+  #
+  # @return [Nil]
+  # @api public
+  # TODO raising an exception really isn't a good idea since it forces the stack to unwind.
+  # More than likely developers are using exceptions to control the code flow and a different approach should be used.
+  # Catch/throw is a bit more efficient but is still the wrong approach for this specific problem.
+  def self.verify_cast(name, value, expected_type)
+    validation = ParamsVerification.type_validations[expected_type.to_sym]
+    unless validation.nil? || value.to_s =~ validation
+      raise InvalidParamType, "Value for parameter '#{name}' (#{value}) is of the wrong type (expected #{expected_type})"
+    end
+  end
+  
+end

data/lib/response.rb

@@ -0,0 +1,457 @@
+require 'json'
+
+class WeaselDiesel
+  # Response DSL class
+  # @api public
+  class Response
+
+    # The list of all the elements inside the response
+    #
+    # @return [Array<WeaselDiesel::Response::Element>]
+    # @api public
+    attr_reader :elements
+
+    # The list of all the arays inside the response
+    #
+    # @return [Array<WeaselDiesel::Response::Array>]
+    attr_reader :arrays
+
+    def initialize
+      @elements = []
+      @arrays  = []
+    end
+
+    # Lists all top level simple elements and array elements.
+    #
+    # @return [Array<WeaselDiesel::Response::Element, WeaselDiesel::Response::Array>]
+    def nodes 
+      elements + arrays
+    end
+
+    # Shortcut to automatically create a node of array type.
+    # Useful when describing a JSON response.
+    #
+    # @param [String, Symbol] name the name of the element.
+    # @param [Hash] opts the element options.
+    # @see Vector#initialize
+    def array(name, type=nil)
+      vector = Vector.new(name, type)
+      yield(vector) if block_given?
+      @arrays << vector
+    end
+
+    # Defines a new element and yields the content of an optional block
+    # Each new element is then stored in the elements array.
+    #
+    # @param [Hash] opts Options used to define the element
+    # @option opts [String, Symbol] :name The element name
+    # @option opts [String, Symbol] :type The optional type
+    #
+    # @yield [WeaselDiesel::Response::Element] the newly created element
+    # @example create an element called 'my_stats'.
+    #   service.response do |response|
+    #    response.element(:name => "my_stats", :type => 'Leaderboard')
+    #   end
+    #
+    # @return [WeaselDiesel::Response::Element]
+    # @api public
+    def element(opts={})
+      el = Element.new(opts[:name], opts[:type])
+      yield(el) if block_given?
+      @elements << el
+      el
+    end
+
+    # Defines an anonymous element
+    # Useful for JSON response description
+    #
+    # @return [WeaselDiesel::Response::Element]
+    def object
+      yield element
+    end
+
+    # Returns a response element object based on its name
+    # @param [String, Symbol] The element name we want to match
+    #
+    # @return [WeaselDiesel::Response::Element]
+    # @api public
+    def element_named(name)
+      @elements.find{|e| e.name.to_s == name.to_s}
+    end
+
+
+    # Converts the object into a JSON representation
+    # @return [String] JSON representation of the response
+    def to_json(*args)
+      if nodes.size > 1
+        nodes.to_json(*args)
+      else
+        nodes.first.to_json(*args)
+      end
+    end
+
+
+    class Params
+      class Rule
+        def to_hash
+          {:name => name, :options => options}
+        end
+      end
+    end
+
+    # The Response element class describing each element of a service response.
+    # Instances are usually not instiated directly but via the Response#element accessor.
+    #
+    # @see WeaselDiesel::Response#element
+    # @api public
+    class Element
+
+      # @return [String, #to_s] The name of the element
+      # @api public
+      attr_reader :name
+
+      # @api public
+      attr_reader :type
+
+      # The optional lookup key of an object
+      attr_reader :key
+
+      # @return [Array<WeaselDiesel::Response::Element::Attribute>] An array of attributes
+      # @api public
+      attr_reader :attributes
+
+      # @return [Array<WeaselDiesel::Response::Element::MetaAttribute>] An array of meta attributes
+      # @api public
+      attr_reader :meta_attributes
+
+      # @return [Array] An array of vectors/arrays
+      # @api public
+      attr_reader :vectors
+
+      # @return [WeaselDiesel::Documentation::ElementDoc] Response element documentation
+      # @api public
+      attr_reader :doc
+
+      # @return [NilClass, Array<WeaselDiesel::Response::Element>] The optional nested elements
+      attr_reader :elements
+
+      # Alias to use a JSON/JS jargon instead of XML.
+      alias :properties :attributes
+
+      # Alias to use a JSON/JS jargon instead of XML.
+      alias :objects :elements
+
+      # param [String, Symbol] name The name of the element
+      # param [String, Symbol] type The optional type of the element
+      # @api public
+      def initialize(name, type=nil)
+        # sets a documentation placeholder since the response doc is defined at the same time
+        # the response is defined.
+        @doc        = Documentation::ElementDoc.new(name)
+        @name       = name
+        @type       = type
+        @attributes = []
+        @meta_attributes = []
+        @vectors    = []
+        @key        = nil
+        # we don't need to initialize the nested elements, by default they should be nil
+      end
+
+      # sets a new attribute and returns the entire list of attributes
+      #
+      # @param [Hash] opts An element's attribute options
+      # @option opts [String, Symbol] attribute_name The name of the attribute, the value being the type
+      # @option opts [String, Symbol] :doc The attribute documentation
+      # @option opts [String, Symbol] :mock An optional mock value used by service related tools
+      # 
+      # @example Creation of a response attribute called 'best_lap_time'
+      #   service.response do |response|
+      #    response.element(:name => "my_stats", :type => 'Leaderboard') do |e|
+      #      e.attribute "best_lap_time"       => :float,    :doc => "Best lap time in seconds."
+      #    end
+      #   end
+      #
+      # @return [Array<WeaselDiesel::Response::Attribute>]
+      # @api public
+      def attribute(opts, extra_opts={})
+        raise ArgumentError unless opts.is_a?(Hash) && extra_opts.is_a?(Hash)
+        new_attribute = Attribute.new(opts, extra_opts)
+        @attributes << new_attribute
+        # document the attribute if description available
+        # we might want to have a placeholder message when a response attribute isn't defined
+        if opts.merge!(extra_opts).has_key?(:doc)
+          @doc.attribute(new_attribute.name, opts[:doc])
+        end
+        @attributes
+      end
+
+      # sets a new meta attribute and returns the entire list of meta attributes
+      #
+      # @param [Hash] opts An element's attribute options
+      # @option opts [String, Symbol] attribute_name The name of the attribute, the value being the type
+      # @option opts [String, Symbol] :mock An optional mock value used by service related tools
+      # 
+      # @example Creation of a response attribute called 'best_lap_time'
+      #   service.response do |response|
+      #    response.element(:name => "my_stats", :type => 'Leaderboard') do |e|
+      #      e.meta_attribute "id"       => :key
+      #    end
+      #   end
+      #
+      # @return [Array<WeaselDiesel::Response::MetaAttribute>]
+      # @api public
+      def meta_attribute(opts)
+        raise ArgumentError unless opts.is_a?(Hash)
+        # extract the documentation part and add it where it belongs
+        new_attribute = MetaAttribute.new(opts)
+        @meta_attributes << new_attribute
+        @meta_attributes
+      end
+
+      # Defines an array aka vector of elements.
+      #
+      # @param [String, Symbol] name The name of the array element.
+      # @param [String, Symbol] type Optional type information, useful to store the represented 
+      #        object types for instance.
+      #
+      # @param [Proc] &block
+      #   A block to execute against the newly created array.
+      # 
+      # @example Defining an element array called 'player_creation_rating'
+      #   element.array 'player_creation_rating', 'PlayerCreationRating' do |a|
+      #     a.attribute :comments  => :string
+      #     a.attribute :player_id => :integer
+      #     a.attribute :rating    => :integer
+      #     a.attribute :username  => :string
+      #   end
+      # @yield [Vector] the newly created array/vector instance
+      # @see Element#initialize
+      # 
+      # @return [Array<WeaselDiesel::Response::Vector>]
+      # @api public
+      def array(name, type=nil)
+        vector = Vector.new(name, type)
+        yield(vector) if block_given?
+        @vectors << vector
+      end
+
+      # Returns the arrays/vectors contained in the response.
+      # This is an alias to access @vectors
+      # @see @vectors
+      #
+      # @return [Array<WeaselDiesel::Response::Vector>]
+      # @api public
+      def arrays
+        @vectors
+      end
+
+      # Defines a new element and yields the content of an optional block
+      # Each new element is then stored in the elements array.
+      #
+      # @param [Hash] opts Options used to define the element
+      # @option opts [String, Symbol] :name The element name
+      # @option opts [String, Symbol] :type The optional type
+      #
+      # @yield [WeaselDiesel::Response::Element] the newly created element
+      # @example create an element called 'my_stats'.
+      #   service.response do |response|
+      #    response.element(:name => "my_stats", :type => 'Leaderboard')
+      #   end
+      #
+      # @return [Array<WeaselDiesel::Response::Element>]
+      # @api public
+      def element(opts={})
+        el = Element.new(opts[:name], opts[:type])
+        yield(el) if block_given?
+        @elements ||= []
+        @elements << el
+        el
+      end
+
+      # Shortcut to create a new element.
+      #
+      # @param [Symbol, String] name the name of the element.
+      # @param [Hash] opts the options for the newly created element.
+      def object(name, opts={}, &block)
+        element(opts.merge(:name => name), &block)
+      end
+
+      # Getter/setter for the key meta attribute.
+      # A key name can be used to lookup an object by a primary key for instance.
+      #
+      # @param [Symbol, String] name the name of the key attribute.
+      # @param [Hash] opts the options attached with the key.
+      def key(name=nil, opts={})
+        meta_attribute_getter_setter(:key, name, opts)
+      end
+
+      # Getter/setter for the type meta attribute.
+      #
+      # @param [Symbol, String] name the name of the type attribute.
+      # @param [Hash] opts the options attached with the key.
+      def type(name=nil, opts={})
+        meta_attribute_getter_setter(:type, name, opts)
+      end
+
+      # Shortcut to create a string attribute
+      #
+      # @param [Symbol, String] name the name of the attribute.
+      # @param [Hash] opts the attribute options.
+      def string(name=nil, opts={})
+        attribute({name => :string}, opts)
+      end
+
+      # Shortcut to create a string attribute
+      #
+      # @param [Symbol, String] name the name of the attribute.
+      # @param [Hash] opts the attribute options.
+      def integer(name=nil, opts={})
+        attribute({name => :integer}, opts)
+      end
+
+      # Shortcut to create a string attribute
+      #
+      # @param [Symbol, String] name the name of the attribute.
+      # @param [Hash] opts the attribute options.
+      def float(name=nil, opts={})
+        attribute({name => :float}, opts)
+      end
+
+      # Shortcut to create a string attribute
+      #
+      # @param [Symbol, String] name the name of the attribute.
+      # @param [Hash] opts the attribute options.
+      def boolean(name=nil, opts={})
+        attribute({name => :boolean}, opts)
+      end
+
+      # Shortcut to create a string attribute
+      #
+      # @param [Symbol, String] name the name of the attribute.
+      # @param [Hash] opts the attribute options.
+      def datetime(name=nil, opts={})
+        attribute({name => :datetime}, opts)
+      end
+
+      # Converts an element into a hash representation
+      #
+      # @return [Hash] the element attributes formated in a hash
+      def to_hash
+        attrs = {}
+        attributes.each{ |attr| attrs[attr.name] = attr.type }
+        elements.each{ |el| attrs[el.name] = el.to_hash } if elements
+        if self.class == Vector
+          name ? {name => [attrs]} : [attrs]
+        else
+          name ? {name => attrs} : attrs
+        end
+      end
+
+      def to_html
+        output = ""
+        if name
+          output << "<li>"
+          output << "<span class='label notice'>#{name}</span> of type <span class='label success'>#{self.is_a?(Vector) ? 'Array' : 'Object'}</span>"
+        end
+        if self.is_a? Vector
+          output << "<h6>Properties of each array item:</h6>"
+        else
+          output << "<h6>Properties:</h6>"
+        end
+        output << "<ul>"
+        properties.each do |prop|
+          output << "<li><span class='label notice'>#{prop.name}</span> of type <span class='label success'>#{prop.type}</span> #{'(Can be blank or missing) ' if prop.opts && prop.opts.respond_to?(:[]) && prop.opts[:null]} "
+          output <<  prop.doc unless prop.doc.blank?
+          output << "</li>"
+        end
+        arrays.each{ |arr| output << arr.html }
+        elements.each {|el| output << el.to_html } if elements
+        output << "</ul>"
+        output << "</li>" if name
+        output
+      end
+
+      private
+
+      # Create a meta element attribute
+      def meta_attribute_getter_setter(type, name, opts)
+        if name
+          meta_attribute({name => type}.merge(opts))
+        else
+          # with a fallback to the @type ivar
+          meta = meta_attributes.find{|att| att.type == type}
+          if meta
+            meta.value
+          else
+            instance_variable_get("@#{type}")
+          end
+        end
+      end
+
+      # Response element's attribute class
+      # @api public
+      class Attribute
+
+        # @return [String, #to_s] The attribute's name.
+        # @api public
+        attr_reader :name
+        alias :value :name
+
+        # @return [Symbol, String, #to_s] The attribute's type such as boolean, string etc..
+        # @api public
+        attr_reader :type
+
+        # @return [String] The documentation associated with this attribute.
+        # @api public
+        attr_reader :doc
+
+        # @see {Attribute#new}
+        # @return [Hash, Nil, Object] Could be a hash, nil or any object depending on how the attribute is created.
+        # @api public
+        attr_reader :opts
+
+        # Takes a Hash or an Array and extract the attribute name, type
+        # doc and extra options.
+        # If the passed objects is a Hash, the name will be extract from
+        # the first key and the type for the first value.
+        # An entry keyed by :doc will be used for the doc and the rest will go
+        # as extra options.
+        #
+        # If an Array is passed, the elements will be 'shifted' in this order:
+        # name, type, doc, type
+        #
+        # @param [Hash, Array] o_params
+        # @param [Hash] o_extra_params A hash with extra params passed, needed to support Ruby 1.8 :(
+        #
+        # @api public
+        def initialize(o_params, o_extra_params={})
+          params = o_params.dup
+          extra_params = o_extra_params.dup
+          if params.is_a?(Hash)
+            @name, @type = params.shift
+            @doc  = params.delete(:doc) if params.has_key?(:doc)
+            @doc  ||= extra_params.delete(:doc) if extra_params.has_key?(:doc)
+            @opts = params.merge!(extra_params)
+          elsif params.is_a?(Array)
+            @name = params.shift
+            @type = params.shift
+            @doc  = params.shift
+            @opts = params
+          end
+        end
+      end
+
+      # Response's meta attribute meant to set some extra
+      # attributes which are not part of the response per se.
+      class MetaAttribute < Attribute
+      end
+
+    end # of Element
+
+    # Array of objects
+    # @api public
+    class Vector < Element
+    end # of Vector
+
+  end # of Response
+end