classy_hash 0.1.6 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: c00ef449de055dd11f7d65c7b69078d335a5faac
-  data.tar.gz: 08492cddaf3d56b469fd326290c4668dcf3d6dea
+  metadata.gz: c4927a8047b123422e97f63378b847c94a97a17e
+  data.tar.gz: bcd0d314bb6a21956fd988e940122cb309d5ee2a
 SHA512:
-  metadata.gz: b0eb3ad07f5843c3c477165b74553103bc3f250b09742dffd0c6b6157bc639b46e1fbf83825eda66b2d8deb1369f375e02e8ab27c1e644958bfc27fe3ec9e6ed
-  data.tar.gz: 79a18a2a41913d4d25b8ce8b15f47d5a4caac5b85ee91e77a762e9034f010496a28ddc2e83fecf86442ba10e0625c24ab32f3afb9663310ea5efbb5cb9b1c144
+  metadata.gz: 5469c836aa915fbc73f8e5f813cf53f171d8da96968a40d3c116b159eaa0fde389dff32ee797a9b2b205c02c7022da440d40fe371af5e9743c4dd3170a5a1460
+  data.tar.gz: 797f7b0f12681b4a8febb6661334b3ad90aabcb6551af8707f4e1c9eb3211700b8cf73494c13d3f7750a3ed8c5276a13d6f603cf800b9a44fb0f8adabc90afa3

data/lib/classy_hash.rb

@@ -1,178 +1,460 @@
 # Classy Hash: Keep Your Hashes Classy
 # Created May 2014 by Mike Bourgeous, DeseretBook.com
-# Copyright (C)2014 Deseret Book
+# Copyright (C)2016 Deseret Book and Contributors (see git history)
 # See LICENSE and README.md for details.
+# frozen_string_literal: true
+
+require 'set'
+require 'securerandom'
 
 # This module contains the ClassyHash methods for making sure Ruby Hash objects
 # match a given schema.  ClassyHash runs fast by taking advantage of Ruby
 # language features and avoiding object creation during validation.
 module ClassyHash
-  # Validates a +hash+ against a +schema+.  The +parent_path+ parameter is used
-  # internally to generate error messages.
-  def self.validate(hash, schema, parent_path=nil)
-    raise 'Must validate a Hash' unless hash.is_a?(Hash) # TODO: Allow validating other types by passing to #check_one?
-    raise 'Schema must be a Hash' unless schema.is_a?(Hash) # TODO: Allow individual element validations?
-
-    schema.each do |key, constraint|
-      if hash.include?(key)
-        self.check_one(key, hash[key], constraint, parent_path)
-      elsif !(constraint.is_a?(Array) && constraint.include?(:optional))
-        self.raise_error(parent_path, key, "present")
-      end
-    end
-
-    nil
-  end
-
-  # As with #validate, but members not specified in the +schema+ are forbidden.
-  # Only the top-level schema is strictly validated.  If +verbose+ is true, the
-  # names of unexpected keys will be included in the error message.
-  def self.validate_strict(hash, schema, verbose=false, parent_path=nil)
-    raise 'Must validate a Hash' unless hash.is_a?(Hash) # TODO: Allow validating other types by passing to #check_one?
-    raise 'Schema must be a Hash' unless schema.is_a?(Hash) # TODO: Allow individual element validations?
+  # Raised when a validation fails.  Allows ClassyHash#validate_full to
+  # continue validation and gather all errors.
+  class SchemaViolationError < StandardError
+    # The list of errors passed to the constructor.  Contains an Array of Hashes:
+    #   [
+    #     { full_path: ClassyHash.join_path(parent_path, key), message: "something the full_path was supposed to be" },
+    #     ...
+    #   ]
+    attr_reader :entries
 
-    extra_keys = hash.keys - schema.keys
-    unless extra_keys.empty?
-      if verbose
-        raise "Hash contains members (#{extra_keys.map(&:inspect).join(', ')}) not specified in schema"
-      else
-        raise 'Hash contains members not specified in schema'
-      end
-    end
-
-    # TODO: Strict validation for nested schemas as well
-
-    self.validate(hash, schema, parent_path)
-  end
-
-  # Raises an error unless the given +value+ matches one of the given multiple
-  # choice +constraints+.
-  def self.check_multi(key, value, constraints, parent_path=nil)
-    if constraints.length == 0
-        self.raise_error(parent_path, key, "a valid multiple choice constraint (array must not be empty)")
+    # Initializes a schema violation error with the given list of schema
+    # +errors+.
+    def initialize(errors = [])
+      @entries = errors
     end
 
-    # Optimize the common case of a direct class match
-    return if constraints.include?(value.class)
-
-    error = nil
-    constraints.each do |c|
-      next if c == :optional
-      begin
-        self.check_one(key, value, c, parent_path)
-        return
-      rescue => e
-        # Throw schema and array errors immediately
-        if (c.is_a?(Hash) && value.is_a?(Hash)) ||
-          (c.is_a?(Array) && value.is_a?(Array) && c.length == 1 && c.first.is_a?(Array))
-          raise e
+    # Joins all errors passed to the constructor into a comma-separated String.
+    def to_s
+      @msg ||= @entries.map{|e|
+        begin
+          "#{e[:full_path]} is not #{e[:message]}"
+        rescue
+          "ERR: #{e.inspect}"
         end
-      end
+      }.join(', ')
     end
-
-    self.raise_error(parent_path, key, "one of #{multiconstraint_string(constraints, value)}")
   end
 
-  # Generates a semi-compact String describing the given +constraints+.
-  def self.multiconstraint_string(constraints, value)
-    constraints.map{|c|
-      if c.is_a?(Hash)
-        "{...schema...}"
-      elsif c.is_a?(Array)
-        "[#{self.multiconstraint_string(c, value)}]"
-      elsif c.is_a?(Proc)
-        c.call(value) || "a value accepted by #{c.inspect}"
-      elsif c == :optional
-        nil
-      elsif c == TrueClass || c == FalseClass
-        'true or false'
-      else
-        c.inspect
-      end
-    }.compact.join(', ')
-  end
+  # Internal symbol representing the absence of a value for error message
+  # generation.  Generated at runtime to prevent potential malicious use of the
+  # no-value symbol.
+  NO_VALUE = "__ch_no_value_#{SecureRandom.hex(10)}".to_sym
+
+  # Validates a +value+ against a ClassyHash +constraint+.  Typically +value+
+  # is a Hash and +constraint+ is a ClassyHash schema.
+  #
+  # Returns false if validation fails and raise_errors was false.  Otherwise
+  # returns true.
+  #
+  # Parameters:
+  #   value - The Hash or other value to validate.
+  #   constraint - The schema or single constraint against which to validate.
+  #   :strict - If true, rejects Hashes with members not in the schema.
+  #           Applies to the top level and to nested Hashes.
+  #   :full - If true, gathers all invalid values.  If false, stops checking at
+  #           the first invalid value.
+  #   :verbose - If true, the error message for failed strictness will include
+  #           the names of the unexpected keys.  Note that this can be a
+  #           security risk if the key names are controlled by an attacker and
+  #           the result is sent via HTTPS (see e.g. the CRIME attack).
+  #   :raise_errors - If true, any errors will be raised.  If false, they will
+  #           be returned as a String.  Default is true.
+  #   :errors - Used internally for aggregating error messages.  You can also
+  #           pass in an Array here to collect any errors (useful if
+  #           raise_errors is false).  If you pass a non-empty array,
+  #           validation will fail.
+  #   :parent_path - Used internally for tracking the current validation path
+  #           in error messages (e.g. :key1[:key2][0]).
+  #   :key - Used internally for tracking the current validation key in error
+  #           messages (e.g. :key1 or 0).
+  #
+  # Examples:
+  #   ClassyHash.validate({a: 1}, {a: Integer})
+  #   ClassyHash.validate(1, Integer)
+  def self.validate(value, constraint, strict: false, full: false, verbose: false,
+                    raise_errors: true, errors: nil, parent_path: nil, key: NO_VALUE)
+    errors = [] if errors.nil? && (full || !raise_errors)
+    raise_below = raise_errors && !full
 
-  # Checks a single value against a single constraint.
-  def self.check_one(key, value, constraint, parent_path=nil)
     case constraint
     when Class
       # Constrain value to be a specific class
       if constraint == TrueClass || constraint == FalseClass
         unless value == true || value == false
-          self.raise_error(parent_path, key, "true or false")
+          add_error(raise_below, errors, parent_path, key, constraint, value)
+          return false unless full
         end
       elsif !value.is_a?(constraint)
-        self.raise_error(parent_path, key, "a/an #{constraint}")
+        add_error(raise_below, errors, parent_path, key, constraint, value)
+        return false unless full
       end
 
     when Hash
       # Recursively check nested Hashes
-      self.raise_error(parent_path, key, "a Hash") unless value.is_a?(Hash)
-      self.validate(value, constraint, self.join_path(parent_path, key))
+      if !value.is_a?(Hash)
+        add_error(raise_below, errors, parent_path, key, constraint, value)
+        return false unless full
+      else
+        if strict
+          extra_keys = value.keys - constraint.keys
+          if extra_keys.any?
+            if verbose
+              msg = "valid: contains members #{extra_keys.map(&:inspect).join(', ')} not specified in schema"
+            else
+              msg = 'valid: contains members not specified in schema'
+            end
+
+            add_error(raise_below, errors, parent_path, key, msg, NO_VALUE)
+            return false unless full
+          end
+        end
+
+        parent_path = join_path(parent_path, key)
+
+        constraint.each do |k, c|
+          if value.include?(k)
+            # TODO: Benchmark how much slower allocating a state object is than
+            # passing lots of parameters?
+            res = self.validate(
+              value[k],
+              c,
+              strict: strict,
+              full: full,
+              verbose: verbose,
+              raise_errors: raise_below,
+              parent_path: parent_path,
+              key: k,
+              errors: errors
+            )
+            return false unless res || full
+          elsif !(c.is_a?(Array) && c.first == :optional)
+            add_error(raise_below, errors, parent_path, k, "present", NO_VALUE)
+            return false unless full
+          end
+        end
+      end
 
     when Array
       # Multiple choice or array validation
       if constraint.length == 1 && constraint.first.is_a?(Array)
         # Array validation
-        self.raise_error(parent_path, key, "an Array") unless value.is_a?(Array)
-
-        constraints = constraint.first
-        value.each_with_index do |v, idx|
-          self.check_multi(idx, v, constraints, self.join_path(parent_path, key))
+        if !value.is_a?(Array)
+          add_error(raise_below, errors, parent_path, key, constraint, value)
+          return false unless full
+        else
+          constraints = constraint.first
+          value.each_with_index do |v, idx|
+            res = self.check_multi(
+              v,
+              constraints,
+              strict: strict,
+              full: full,
+              verbose: verbose,
+              raise_errors: raise_below,
+              parent_path: join_path(parent_path, key),
+              key: idx,
+              errors: errors
+            )
+            return false unless res || full
+          end
         end
       else
         # Multiple choice
-        self.check_multi(key, value, constraint, parent_path)
+        res = self.check_multi(
+          value,
+          constraint,
+          strict: strict,
+          full: full,
+          verbose: verbose,
+          raise_errors: raise_below,
+          parent_path: parent_path,
+          key: key,
+          errors: errors
+        )
+        return false unless res || full
       end
 
     when Regexp
       # Constrain value to be a String matching a Regexp
       unless value.is_a?(String) && value =~ constraint
-        self.raise_error(parent_path, key, "a String matching #{constraint.inspect}")
+        add_error(raise_below, errors, parent_path, key, constraint, value)
+        return false unless full
       end
 
     when Proc
       # User-specified validator
       result = constraint.call(value)
       if result != true
-        self.raise_error(parent_path, key, result.is_a?(String) ? result : "accepted by Proc")
+        if result.is_a?(String)
+          add_error(raise_below, errors, parent_path, key, result, NO_VALUE)
+        else
+          add_error(raise_below, errors, parent_path, key, constraint, value)
+        end
+        return false unless full
       end
 
     when Range
       # Range (with type checking for common classes)
+      range_type_valid = true
+
       if constraint.min.is_a?(Integer) && constraint.max.is_a?(Integer)
-        self.raise_error(parent_path, key, "an Integer") unless value.is_a?(Integer)
+        unless value.is_a?(Integer)
+          add_error(raise_below, errors, parent_path, key, constraint, value)
+          return false unless full
+          range_type_valid = false
+        end
       elsif constraint.min.is_a?(Numeric)
-        self.raise_error(parent_path, key, "a Numeric") unless value.is_a?(Numeric)
+        unless value.is_a?(Numeric)
+          add_error(raise_below, errors, parent_path, key, constraint, value)
+          return false unless full
+          range_type_valid = false
+        end
       elsif constraint.min.is_a?(String)
-        self.raise_error(parent_path, key, "a String") unless value.is_a?(String)
+        unless value.is_a?(String)
+          add_error(raise_below, errors, parent_path, key, constraint, value)
+          return false unless full
+          range_type_valid = false
+        end
+      end
+
+      if range_type_valid && !constraint.cover?(value)
+        add_error(raise_below, errors, parent_path, key, constraint, value)
+        return false unless full
+      end
+
+    when Set
+      # Set/enumeration
+      unless constraint.include?(value)
+        add_error(raise_below, errors, parent_path, key, constraint, value)
+        return false unless full
       end
 
-      unless constraint.cover?(value)
-        self.raise_error(parent_path, key, "in range #{constraint.inspect}")
+    when CH::G::Composite
+      constraint.constraints.each do |c|
+        result = self.validate(
+          value,
+          c,
+          strict: strict,
+          full: full,
+          verbose: verbose,
+          raise_errors: false,
+          parent_path: parent_path,
+          key: key,
+          errors: nil
+        )
+
+        if constraint.negate == result
+          add_error(raise_below, errors, parent_path, key, constraint, value)
+          return false unless full
+          break
+        end
       end
 
     when :optional
-      # Optional key marker in multiple choice validators
-      nil
+      # Optional key marker in multiple choice validators (do nothing)
 
     else
       # Unknown schema constraint
-      self.raise_error(parent_path, key, "a valid schema constraint: #{constraint.inspect}")
+      add_error(raise_below, errors, parent_path, key, constraint, value)
+      return false unless full
     end
 
-    nil
+    # If full was true, we need to raise here now that all the errors were
+    # gathered.
+    if raise_errors && errors && errors.any?
+      raise SchemaViolationError, errors
+    end
+
+    errors.nil? || errors.empty?
+  end
+
+  # Deprecated.  Retained for compatibility with v0.1.x.  Calls .validate with
+  # :strict set to true.  If +verbose+ is true, the names of unexpected keys
+  # will be included in the error message.
+  def self.validate_strict(hash, schema, verbose=false, parent_path=nil)
+    validate(hash, schema, parent_path: parent_path, verbose: verbose, strict: true)
   end
 
+  # Raises an error unless the given +value+ matches one of the given multiple
+  # choice +constraints+.  Other parameters are used for internal state.  If
+  # +full+ is true, the error message for an invalid value will include the
+  # errors for all of the failing components of the multiple choice constraint.
+  def self.check_multi(value, constraints, strict: nil, full: nil, verbose: nil, raise_errors: nil,
+                       parent_path: nil, key: nil, errors: nil)
+    if constraints.length == 0 || constraints.length == 1 && constraints.first == :optional
+      return add_error(raise_errors, errors,
+        parent_path,
+        key,
+        "a valid multiple choice constraint (array must not be empty)",
+        NO_VALUE
+      )
+    end
+
+    # Optimize the common case of a direct class match
+    return true if constraints.include?(value.class)
+
+    local_errors = []
+    constraints.each do |c|
+      next if c == :optional
+
+      constraint_errors = []
+
+      # Only need one match to accept the value, so return if one is found
+      return true if self.validate(
+        value,
+        c,
+        strict: strict,
+        full: full,
+        verbose: verbose,
+        raise_errors: false,
+        parent_path: parent_path,
+        key: key,
+        errors: constraint_errors
+      )
+
+      local_errors << { constraint: c, errors: constraint_errors }
+    end
+
+    # Accumulate all errors if full, the constraint with the most similar keys
+    # and fewest errors if a Hash or Array, or just the constraint with the
+    # fewest errors otherwise.  This doesn't always choose the intended
+    # constraint for error reporting, which would require a more complex
+    # algorithm.
+    #
+    # See https://github.com/deseretbook/classy_hash/pull/16#issuecomment-257484267
+    if full
+      local_errors.map!{|e| e[:errors] }
+      local_errors.flatten!
+    elsif value.is_a?(Hash)
+      # Prefer error messages from similar-looking hash constraints for hashes
+      local_errors = local_errors.min_by{|err|
+        c = err[:constraint]
+        e = err[:errors]
+
+        if c.is_a?(Hash)
+          keydiff = (c.keys | value.keys) - (c.keys & value.keys)
+          [ keydiff.length, e.length ]
+        else
+          [ 1<<30, e.length ] # Put non-hashes after hashes
+        end
+      }[:errors]
+    elsif value.is_a?(Array)
+      # Prefer error messages from array constraints for arrays
+      local_errors = local_errors.min_by{|err|
+        c = err[:constraint]
+        [
+          c.is_a?(Array) ? (c.first.is_a?(Array) ? 0 : 1) : 2,
+          err[:errors].length
+        ]
+      }[:errors]
+    else
+      # FIXME: if full is false, e.length should always be 1 (or 2 if strict)
+      # Also, array and multiple-choice errors have lots of room for improvement
+      local_errors = local_errors.min_by{|e| e[:errors].length }[:errors]
+    end
+
+    errors.concat(local_errors) if errors
+    add_error(raise_errors, errors || local_errors, parent_path, key, constraints, value)
+  end
+
+  # Generates a String describing the +value+'s failure to match the
+  # +constraint+.  The value itself should not be included in the string to
+  # avoid attacker-controlled plaintext.  If +value+ is CH::NO_VALUE, then
+  # generic error messages will be used for constraints (e.g. Procs) that would
+  # otherwise have been value-dependent.
+  def self.constraint_string(constraint, value)
+    case constraint
+    when Hash
+      "a Hash matching {schema with keys #{constraint.keys.inspect}}"
+
+    when Class
+      if constraint == TrueClass || constraint == FalseClass
+        'true or false'
+      else
+        "a/an #{constraint}"
+      end
+
+    when Array
+      if constraint.length == 1 && constraint.first.is_a?(Array)
+        "an Array of #{constraint_string(constraint.first, NO_VALUE)}"
+      else
+        "one of #{constraint.map{|c| constraint_string(c, value) }.join(', ')}"
+      end
+
+    when Regexp
+      "a String matching #{constraint.inspect}"
+
+    when Proc
+      if value != NO_VALUE && (result = constraint.call(value)).is_a?(String)
+        result
+      else
+        "accepted by Proc"
+      end
+
+    when Range
+      base = "in range #{constraint.inspect}"
+
+      if constraint.min.is_a?(Integer) && constraint.max.is_a?(Integer)
+        "an Integer #{base}"
+      elsif constraint.min.is_a?(Numeric)
+        "a Numeric #{base}"
+      elsif constraint.min.is_a?(String)
+        "a String #{base}"
+      else
+        base
+      end
+
+    when Set
+      "an element of #{constraint.to_a.inspect}"
+
+    when CH::G::Composite
+      constraint.describe(value)
+
+    when :optional
+      "absent (marked as :optional)"
+
+    else
+      "a valid schema constraint: #{constraint.inspect}"
+
+    end
+  end
+
+  # Joins parent_path and key for display in error messages.
   def self.join_path(parent_path, key)
-    parent_path ? "#{parent_path}[#{key.inspect}]" : key.inspect
+    if parent_path
+      "#{parent_path}[#{key.inspect}]"
+    elsif key == NO_VALUE
+      nil
+    else
+      key.inspect
+    end
   end
 
-  # Raises an error indicating that the given +key+ under the given
-  # +parent_path+ fails because the value "is not #{+message+}".
-  def self.raise_error(parent_path, key, message)
-    # TODO: Ability to validate all keys
-    raise "#{self.join_path(parent_path, key)} is not #{message}"
+  # Raises or adds to +errors+ an error indicating that the given +key+ under
+  # the given +parent_path+ fails because the value is not valid.  If
+  # +constraint+ is a String, then it will be used as the error message.
+  # Otherwise
+  #
+  # If +raise_errors+ is true, raises an error immediately.  Otherwise adds an
+  # error to +errors+.
+  #
+  # See .constraint_string.
+  def self.add_error(raise_errors, errors, parent_path, key, constraint, value)
+    message = constraint.is_a?(String) ? constraint : constraint_string(constraint, value)
+    entry = { full_path: self.join_path(parent_path, key) || 'Top level', message: message }
+
+    if raise_errors
+      errors ||= []
+      errors << entry
+      raise SchemaViolationError, errors
+    else
+      errors << entry if errors
+      return false
+    end
   end
 end
 

data/lib/classy_hash/generate.rb

@@ -1,12 +1,69 @@
 # Classy Hash extended validation generators
-# Copyright (C)2014 Deseret Book
+# Copyright (C)2016 Deseret Book and Contributors (see git history)
+# frozen_string_literal: true
 
 module ClassyHash
   # This module contains helpers that generate constraints for common
   # ClassyHash validation tasks.
   module Generate
-    # Generates a ClassyHash constraint that ensures a value is equal to one of
-    # the arguments in +args+.
+    # Used by the .all and .not generators.  Do not use directly.
+    class Composite
+      # Array of constraints to apply together.
+      attr_reader :constraints
+
+      # True if the constraints must all not match, false if they must all
+      # match.
+      attr_reader :negate
+
+      # Initializes a composite constraint with the given Array of
+      # +constraints+.  If +negate+ is true, then the constraints must all fail
+      # for the value to pass.
+      def initialize(constraints, negate = false)
+        raise 'No constraints were given' if constraints.empty?
+
+        @constraints = constraints
+        @negate = negate
+      end
+
+      # Returns a String describing the composite constraint failing against
+      # the given +value+.
+      def describe(value)
+        "#{negate ? 'none' : 'all'} of [#{CH.constraint_string(constraints, value)}]"
+      end
+    end
+
+    # Generates a constraint that requires a value to match *all* of the given
+    # constraints.  If no constraints are given, always passes.
+    #
+    # Raises an error if no constraints are given.
+    #
+    # Example:
+    #     schema = {
+    #       a: CH::G.all(Integer, 1..100, CH::G.not(Set.new([7, 13])))
+    #     }
+    #     ClassyHash.validate({ a: 25 }, schema)
+    def self.all(*constraints)
+      Composite.new(constraints.freeze)
+    end
+
+    # Generates a constraint that requires a value to match *none* of the given
+    # constraints.
+    #
+    # Raises an error if no constraints are given.
+    #
+    # Example:
+    #     schema = {
+    #       a: CH::G.not(Rational, BigDecimal)
+    #     }
+    #     ClassyHash.validate({ a: 1.25 }, schema)
+    def self.not(*constraints)
+      Composite.new(constraints.freeze, true)
+    end
+
+    # Deprecated.  Generates a ClassyHash constraint that ensures a value is
+    # equal to one of the arguments in +args+.
+    #
+    # For new schemas, consider creating a Set with the enumeration elements.
     #
     # Example:
     #     schema = {
@@ -14,9 +71,7 @@ module ClassyHash
     #     }
     #     ClassyHash.validate({ a: 1 }, schema)
     def self.enum(*args)
-      lambda {|v|
-        args.include?(v) || "an element of #{args.inspect}"
-      }
+      Set.new(args)
     end
 
     # Generates a constraint that imposes a length limitation (an exact length

metadata

@@ -1,15 +1,16 @@
 --- !ruby/object:Gem::Specification
 name: classy_hash
 version: !ruby/object:Gem::Version
-  version: 0.1.6
+  version: 0.2.0
 platform: ruby
 authors:
 - Deseret Book
 - Mike Bourgeous
+- Git Contributors
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-08-03 00:00:00.000000000 Z
+date: 2016-11-08 00:00:00.000000000 Z
 dependencies: []
 description: |2
       Classy Hash is a schema validator for Ruby Hashes.  You provide a simple