param_guard 0.0.1

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2012 Levente Bagi
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.rdoc

@@ -0,0 +1,82 @@
+= Param Guard
+
+Simple utility to check the format of request params, e.g. in a Rails controller, but it can be used on any hash-like Ruby structure.
+
+== Installation
+
+In Gemfile:
+
+    gem 'param_guard'
+
+== Example
+
+For example, in your controller, you could do:
+
+    def create
+      @user = User.new(user_params)
+      # ...
+    end
+
+    def user_params
+      ParamGuard.filter(
+        params,
+        {
+          user:                   [:required, :hash, {
+            email:                  [:permitted, :scalar],
+            password:               [:permitted, :scalar],
+            password_confirmation:  [:permitted, :scalar],
+            profile_attributes:     [:required, :hash, {
+              date_of_birth:          [:permitted, [:scalar, :multi]],
+              country_id:             [:permitted, [:scalar]],
+              terms_ok:               [:permitted, [:scalar]],
+            }]
+          }]
+        }
+      )[:user]
+    end
+
+== Definition format
+
+The definition should be a hash. The key represents a key in the params hash the value is an array of 2 or 3 values.
+
+[1st item]
+  <code>:required</code> or <code>:permitted</code>.
+
+[2nd item]
+  The 2nd item: the expected format of the value
+
+  - <code>:string</code>
+  - <code>:integer</code>
+  - <code>:float</code>
+  - <code>:hash</code>
+  - <code>:scalar</code> - non-structured types
+  - <code>:array</code>
+  - <code>:multi</code> - multi-parameter values handled by Rails, typically dates and times
+
+  The required type can also be an array, if any of these matches the value the value will be accepted.
+
+[3rd item]
+
+  If the type is a hash, these will be the definition for the nested hash.
+
+See the tests for examples.
+
+== Return values
+
+This will return a duplicate of params, from which parameters that are not mentioned, will be removed.
+
+== Exceptions
+
+If a key is required, but is not specified, a <code>ParamGuard::ParameterMissing</code> exception will be raised.
+
+If the type is not right, <code>ParamGuard::ParameterOfInvalidType</code> will be raised.
+
+Both are a sublass of <code>ParamGuard::InvalidParameters</code>.
+
+You should catch these in the controller and respond with HTTP 400 Bad Request. E.g. in you +ApplicationController+:
+
+    rescue_from ParamGuard::InvalidParameters do |exception|
+      Rails.logger.info "Bad Request: #{exception.message}"
+      render :text => exception.message, :status => :bad_request
+    end
+

data/Rakefile

@@ -0,0 +1,28 @@
+#!/usr/bin/env rake
+begin
+  require 'bundler/setup'
+  require 'bundler/gem_tasks'
+rescue LoadError
+  raise 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+
+require 'rdoc/task'
+
+RDoc::Task.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'ParamGuard'
+  rdoc.options << '--line-numbers'
+  rdoc.rdoc_files.include('README.rdoc')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+require 'rake/testtask'
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = false
+end
+
+task :default => :test

data/lib/param_guard.rb

@@ -0,0 +1,90 @@
+module ParamGuard
+  InvalidParameters = Class.new(StandardError)
+  ParameterMissing = Class.new(InvalidParameters)
+  ParameterOfInvalidType = Class.new(InvalidParameters)
+
+  autoload :ParamDefinition, 'param_guard/param_definition'
+
+  class << self
+
+    # Sanitiize params based on rules in defs.
+    # Returns a duplicate of params, from which all non-declared fields are deleted.
+    # Raises errors ParameterMissing or ParameterOfInvalidType.
+    def filter(params, defs, parent_keys = [])
+      return params if defs.nil?
+      keys_to_keep = []
+      defs.each do |key, key_def|
+        definition = ParamDefinition.new(*key_def)
+        structure, value, params_to_keep = get_param(params, key)
+        if value
+          if definition.types.any?
+            unless definition.types.any?{|t| is_of_type?(t, value, structure)}
+              raise ParameterOfInvalidType.new(
+                "param '#{keys_to_s(parent_keys + [key])}' must be #{definition.types_for_sentence}"
+              )
+            end
+          end
+          keys_to_keep.concat params_to_keep.keys.map(&:to_s)
+          if structure == :normal && value.kind_of?(Hash)
+            params[key] = filter(value, definition.subdef, parent_keys + [key])
+          end
+        elsif definition.required?
+          raise ParameterMissing.new(
+            "param '#{keys_to_s(parent_keys + [key])}' is missing"
+          )
+        end
+      end
+      filtered = params.dup
+      filtered.delete_if{|key, value| ! keys_to_keep.include? key.to_s }
+      filtered
+    end
+
+    private
+
+    def get_param(params, key)
+      key, value = if v = params[key.to_sym]
+                     [key.to_sym, v]
+                   elsif v = params[key.to_s]
+                     [key.to_s, v]
+                   else
+                     [key, nil]
+                   end
+      if value
+        return :normal, value, { key => value }
+      elsif (keys = params.keys.grep(/\A#{Regexp.escape(key.to_s)}\(\d+[if]?\)\z/)).any?
+        values = keys.sort.map{|k| params[k]}
+        return :multi, values, Hash[keys.map{|k| [k, params[k]]}]
+      else
+        return :none, nil, {}
+      end
+    end
+
+    def is_of_type?(type, value, structure)
+      case type.to_sym
+      when :string
+        value.kind_of? String
+      when :integer
+        value.kind_of? Fixnum
+      when :float
+        value.kind_of? Float
+      when :hash
+        value.kind_of? Hash
+      when :scalar
+        [String, Fixnum, Float, NilClass, FalseClass, TrueClass].any?{|klass| value.kind_of? klass}
+      when :array
+        value.kind_of? Array
+      when :multi
+        structure == :multi
+      else
+        raise "Unknown type: #{type.inspect}"
+      end
+    end
+
+    def keys_to_s(keys)
+      "#{keys.first}#{keys[1..-1].map{|k| "[#{k}]"}.join}"
+    end
+
+  end
+end
+
+

data/lib/param_guard/param_definition.rb

@@ -0,0 +1,21 @@
+module ParamGuard
+
+  # Rules describing the requirements for a parameter.
+  class ParamDefinition < Struct.new(:presence, :type_or_types, :subdef)
+    def required?
+      presence == :required
+    end
+
+    def types
+      Array(type_or_types)
+    end
+
+    def types_for_sentence
+      a = types.map(&:to_s)
+      return nil if a.empty?
+      [a[0..-3] + [a.last(2).join(' or ')]].compact.join(', ')
+    end
+  end
+
+end
+

data/lib/param_guard/version.rb

@@ -0,0 +1,3 @@
+module ParamGuard
+  VERSION = "0.0.1"
+end

data/test/param_definition_test.rb

@@ -0,0 +1,21 @@
+$: << File.expand_path("../../lib", __FILE__)
+require 'test/unit'
+require 'param_guard/param_definition'
+
+class ParamGuardParamDefinitionTest < Test::Unit::TestCase
+  def test_types_for_sentence_no_types
+    assert_equal nil, ParamGuard::ParamDefinition.new.types_for_sentence
+  end
+
+  def test_types_for_sentence_one_type
+    assert_equal 'string', ParamGuard::ParamDefinition.new(nil, :string).types_for_sentence
+  end
+
+  def test_types_for_sentence_two_types
+    assert_equal 'string or integer', ParamGuard::ParamDefinition.new(nil, [:string, :integer]).types_for_sentence
+  end
+
+  def test_types_for_sentence_three_types
+    assert_equal 'hash, string or integer', ParamGuard::ParamDefinition.new(nil, [:hash, :string, :integer]).types_for_sentence
+  end
+end

data/test/param_guard_test.rb

@@ -0,0 +1,121 @@
+$: << File.expand_path("../../lib", __FILE__)
+require 'test/unit'
+require 'param_guard'
+
+class ParamGuardTest < Test::Unit::TestCase
+
+  def test_filter_returns_only_required_and_permitted_params
+    defs = { :a => [:required], :b => [:permitted] }
+    params = { :a => 1, :b => 2, :c => 3 }
+    filtered = ParamGuard.filter(params, defs)
+    assert_equal({ :a => 1, :b => 2 }, filtered)
+  end
+
+  def test_filter_raises_error_if_required_param_missing
+    defs = { :a => [:required], :b => [:permitted] }
+    params = { :b => 2, :c => 3 }
+    assert_raise ParamGuard::ParameterMissing do
+      filtered = ParamGuard.filter(params, defs)
+    end
+  end
+
+  def test_filter_raises_error_if_param_of_wrong_type
+    defs = { :a => [:required, :string] }
+    params = { :a => 1 }
+    assert_raise ParamGuard::ParameterOfInvalidType do
+      filtered = ParamGuard.filter(params, defs)
+    end
+  end
+
+  def test_filter_raises_error_if_param_of_wrong_type_multiple_types_allowed
+    defs = { :a => [:required, [:string, :integer]] }
+    params = { :a => {} }
+    assert_raise ParamGuard::ParameterOfInvalidType do
+      filtered = ParamGuard.filter(params, defs)
+    end
+  end
+
+  def test_filter_when_param_of_matches_any_type
+    defs = { :a => [:required, [:string, :integer]] }
+    params = { :a => 1 }
+    filtered = ParamGuard.filter(params, defs)
+    assert_equal({ :a => 1 }, filtered)
+  end
+
+  def test_filter_raises_error_if_missing_parameter_in_nested_definition
+    defs = {
+      :user => [:required, :hash, {
+        :name => [:required, :string]
+      }]
+    }
+    params = { :user => {} }
+    assert_raise ParamGuard::ParameterMissing do
+      filtered = ParamGuard.filter(params, defs)
+    end
+  end
+
+  def test_filter_returns_only_valid_parameters_in_nested_definition
+    defs = {
+      :user => [:required, :hash, {
+        :name => [:required, :string]
+      }]
+    }
+    params = { :user => { :name => 'Bob', :email => 'bob@example.com' } }
+    filtered = ParamGuard.filter(params, defs)
+    assert_equal({ :user => { :name => 'Bob' } }, filtered)
+  end
+
+  def test_filter_accept_multiparams
+    defs = {
+      dob: [:required, :multi]
+    }
+    params = { "dob(1i)" => 1999, "dob(2i)" => 1, "dob(3i)" => 1 }
+    filtered = ParamGuard.filter(params, defs)
+    assert_equal params, filtered
+  end
+
+  def test_filter_accept_multiparams_when_scalar_or_multi_expected
+    defs = {
+      dob: [:required, [:scalar, :multi]]
+    }
+    params = { "dob(1i)" => "1999", "dob(2i)" => "1", "dob(3i)" => "1" }
+    filtered = ParamGuard.filter(params, defs)
+    assert_equal params, filtered
+  end
+
+  def test_filter_accept_scalar_when_scalar_or_multi_expected
+    defs = {
+      dob: [:required, [:scalar, :multi]]
+    }
+    params = { "dob" => "1999-01-01" }
+    filtered = ParamGuard.filter(params, defs)
+    assert_equal params, filtered
+  end
+
+  def test_filter_raise_if_not_multiparams_given
+    defs = {
+      dob: [:required, :multi]
+    }
+    params = { "dob" => "1999-01-02" }
+    assert_raise ParamGuard::ParameterOfInvalidType do
+      filtered = ParamGuard.filter(params, defs)
+    end
+  end
+
+  def test_filter_accept_multiparams_or_scalar
+    defs = {
+      dob: [:required, [:scalar, :multi]]
+    }
+    params = { "dob" => "1999-01-02" }
+    filtered = ParamGuard.filter(params, defs)
+    assert_equal params, filtered
+  end
+
+  def test_filter_does_not_alter_original_params_object
+    defs = { :a => [:required] }
+    params = { :a => 1, :b => 2 }
+    filtered = ParamGuard.filter(params, defs)
+    assert_equal({ :a => 1, :b => 2 }, params)
+    assert_equal({ :a => 1 }, filtered)
+  end
+end

metadata

@@ -0,0 +1,77 @@
+--- !ruby/object:Gem::Specification
+name: param_guard
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+  prerelease: 
+platform: ruby
+authors:
+- Levente Bagi
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-12-04 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: 
+email:
+- bagilevi@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/param_guard/param_definition.rb
+- lib/param_guard/version.rb
+- lib/param_guard.rb
+- MIT-LICENSE
+- Rakefile
+- README.rdoc
+- test/param_definition_test.rb
+- test/param_guard_test.rb
+homepage: 
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+      segments:
+      - 0
+      hash: 1412847858866998539
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+      segments:
+      - 0
+      hash: 1412847858866998539
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.24
+signing_key: 
+specification_version: 3
+summary: Filter parameters by defining a required structure
+test_files:
+- test/param_definition_test.rb
+- test/param_guard_test.rb