coercive 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d1b6a873b4a86ca962a22d60630a4de5355b278b529fccbd2615a794a7a94448
+  data.tar.gz: 62f47d1f35c9d931935138872dace70a7c39d3eb090529f1f2886448dca2e4ad
+SHA512:
+  metadata.gz: d2d5f401306d119e14a761aa1937f6c5777f69458d9db1367d35bd2a02fcea8a2d41876db4331a0086af8ec49db00b3f892d3c76dbcbacd6d297edc836cfb3db
+  data.tar.gz: e5e4ffc4e9e7874807a2b3af33fb3f846752acce0e9748d06c79247e54f7120ffb38ac5a764c33a629ee05009c62154864f41f975a7fa19985f77b96caa5d53e

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2020 Theorem
+
+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.md

@@ -0,0 +1,201 @@
+# coercive
+
+`Coercive` is a Ruby library to validate and coerce user input.
+
+Define your coercion modules like this:
+
+```ruby
+module CoerceFoo
+  extend Coercive
+
+  attribute :foo, string(min: 1, max: 10), required
+end
+```
+
+Pass in your user input and you'll get back validated and coerced attributes:
+
+```ruby
+attributes = CoerceFoo.call("foo" => "bar")
+
+attributes["foo"]
+# => "bar"
+
+CoerceFoo.call("foo" => "more than 10 chars long")
+# => Coercive::Error: {"foo"=>"too_long"}
+
+CoerceFoo.call("bar" => "foo is not here")
+# => Coercive::Error: {"foo"=>"not_present", "bar"=>"unknown"}
+```
+
+`Coercive`'s single entry-point is the `call` method that receives a `Hash`. It will compare each key-value pair against the definitions provided by the `attribute` method.
+
+The `attribute` functions takes three arguments:
+* The first one is the name of the attribute.
+* The second one is a coerce function. Coercive comes with many available, and you can always write your own.
+* The third one is a fetch function, used to look up the attribute in the input `Hash`.
+
+## Fetch functions
+
+As you saw in the example above, `required` is one of the three fetch functions available. Let's get into each of them and how they work.
+
+### `required`
+
+As the name says, `Coercive` will raise an error if the input lacks the attribute, and add the `"not_present"` error code.
+
+```ruby
+CoerceFoo.call("bar" => "foo is not here")
+# => Coercive::Error: {"foo"=>"not_present", "bar"=>"unknown"}
+```
+
+### `optional`
+
+The `optional` fetch function will grab an attribute from the input, but do nothing if it's not there. Let's look again at the example above:
+
+```ruby
+module CoerceFoo
+  extend Coercive
+
+  attribute :foo, string(min: 1, max: 10), required
+end
+
+CoerceFoo.call("bar" => "foo is not here")
+# => Coercive::Error: {"foo"=>"not_present", "bar"=>"unknown"}
+```
+
+The `"bar"` attribute raises an error because it's unexpected. `Coercive` is thorough when it comes to the input. To make this go away, we have to add `"bar"` as optional:
+
+```ruby
+module CoerceFoo
+  extend Coercive
+
+  attribute :foo, string(min: 1, max: 10), required
+  attribute :bar, any,                     optional
+end
+
+CoerceFoo.call("bar" => "foo is not here")
+# => Coercive::Error: {"foo"=>"not_present"}
+```
+
+### `implicit`
+
+The last fetch function `Coercive` has is a handy way to set a default value when an attribute is not present in the input.
+
+```ruby
+module CoerceFoo
+  extend Coercive
+
+  attribute :foo, string(min: 1, max: 10), implicit("default")
+  attribute :bar, any,                     optional
+end
+
+CoerceFoo.call("bar" => "any")
+# => {"foo"=>"default", "bar"=>"any"}
+```
+
+Keep in mind that your default must comply with the declared type and restrictions. In this case, `implicit("very long default value")` will raise an error because it's longer than 10 characters.
+
+## Coercion functions
+
+We already got a taste for the coercion functions with `string(min: 1, max:10)` and there are many more! but let's start there.
+
+### `string(min:, max:, pattern:)`
+
+The `string` coercion function will enforce a minimum and maximum character length, throwing `"too_short"` and `"too_long"` errors respectively if the input is not within the declared bounds.
+
+Additionally, you can also verify your String matches a regular expression with the `pattern:` option.
+
+```ruby
+module CoerceFoo
+  extend Coercive
+
+  attribute :foo, string(pattern: /\A\h+\z/), optional
+end
+
+CoerceFoo.call("foo" => "REDBEETS")
+# => Coercive::Error: {"foo"=>"not_valid"}
+
+CoerceFoo.call("foo" => "DEADBEEF")
+# => {"foo"=>"DEADBEEF"}
+```
+
+### `any`
+
+The `any` coercion function lets anything pass through. It's commonly used with the `optional` fetch function when an attribute may or many not be a part of the input.
+
+### `member`
+
+`member` will check that the value is one of the values of the given array.
+
+```ruby
+module CoerceFoo
+  extend Coercive
+
+  attribute :foo, member(["one", "two", "three"]), optional
+end
+
+CoerceFoo.call("foo" => 4)
+# => Coercive::Error: {"foo"=>"not_valid"}
+```
+
+### `float`
+
+`float` expects, well, a float value.
+
+```ruby
+module CoerceFoo
+  extend Coercive
+
+  attribute :foo, float, optional
+end
+
+CoerceFoo.call("foo" => "bar")
+# => Coercive::Error: {"foo"=>"not_valid"}
+
+CoerceFoo.call("foo" => "0.1")
+# => {"foo"=>0.1}
+  
+CoerceFoo.call("foo" => "0.1e5")
+# => {"foo"=>10000.0}
+```
+
+### `array`
+
+The `array` coercion is interesting because it's where `Coercive` starts to shine, by letting you compose coercion functions together. Let's see:
+
+```ruby
+module CoerceFoo
+  extend Coercive
+
+  attribute :foo, array(string), optional
+end
+
+CoerceFoo.call("foo" => ["one", "two", "three"])
+# => {"foo"=>["one", "two", "three"]}
+
+CoerceFoo.call("foo" => [1, 2, 3])
+# => {"foo"=>["1", "2", "3"]}
+
+CoerceFoo.call("foo" => [nil, true])
+# => {"foo"=>["", "true"]}
+
+CoerceFoo.call("foo" => [BasicObject.new])
+# => Coercive::Error: {"foo"=>["not_valid"]}
+```
+
+### `hash`
+
+`hash` coercion let's you manipulate the key and values, similarly to how `array` does
+
+```ruby
+module CoerceFoo
+  extend Coercive
+
+  attribute :foo, hash(string(max: 3), float), optional
+end
+
+CoerceFoo.call("foo" => {"bar" => "0.1"})
+# => {"foo"=>{"bar"=>0.1}}
+
+CoerceFoo.call("foo" => {"barrrr" => "0.1"})
+# => Coercive::Error: {"foo"=>{"barrrr"=>"too_long"}}
+```

data/lib/coercive.rb

@@ -0,0 +1,289 @@
+require_relative "coercive/uri"
+
+# Public: The Coercive module implements a succinct DSL for declaring callable
+# modules that will validate and coerce input data to an expected format.
+module Coercive
+  # Public: An error raised when a coercion cannot produce a suitable result.
+  class Error < ArgumentError
+    # Public: The error or errors encountered in coercing the input.
+    attr_accessor :errors
+
+    def initialize(errors)
+      @errors = errors
+      super(errors.inspect)
+    end
+  end
+
+  # Public: Coercive the given input using the declared attribute coercions.
+  #
+  # input - input Hash with string keys that correspond to declared attributes.
+  #
+  # Returns a Hash with known attributes as string keys and coerced values.
+  # Raises a Coercive::Error if the given input is not a Hash, or if there are
+  # any unknown string keys in the Hash, or if the values for the known keys
+  # do not pass the inner coercions for the associated declared attributes.
+  def call(input)
+    fail Coercive::Error.new("not_valid") unless input.is_a?(Hash)
+
+    errors  = {}
+
+    # Fetch attributes from the input Hash into the fetched_attrs Hash.
+    #
+    # Each fetch function is responsible for fetching its associated attribute
+    # into the fetched_attrs Hash, or choosing not to fetch it, or choosing to
+    # raise a Coercive::Error.
+    #
+    # These fetch functions encapsulate the respective strategies for dealing
+    # with required, optional, or implicit attributes appropriately.
+    fetched_attrs = {}
+    attr_fetch_fns.each do |name, fetch_fn|
+      begin
+        fetch_fn.call(input, fetched_attrs)
+      rescue Coercive::Error => e
+        errors[name] = e.errors
+      end
+    end
+
+    # Check for unknown names in the input (not declared, and thus not fetched).
+    input.each_key do |name|
+      errors[name] = "unknown" unless fetched_attrs.key?(name)
+    end
+
+    # Coercive fetched attributes into the coerced_attrs Hash.
+    #
+    # Each coerce function will coerce the given input value for that attribute
+    # to an acceptable output value, or choose to raise a Coercive::Error.
+    coerced_attrs = {}
+    fetched_attrs.each do |name, value|
+      coerce_fn = attr_coerce_fns.fetch(name)
+      begin
+        coerced_attrs[name] = coerce_fn.call(value)
+      rescue Coercive::Error => e
+        errors[name] = e.errors
+      end
+    end
+
+    # Fail if fetching or coercion caused any errors.
+    fail Coercive::Error.new(errors) unless errors.empty?
+
+    coerced_attrs
+  end
+
+  private
+
+  # Private: Hash with String attribute names as keys and fetch function values.
+  #
+  # Each coerce function will be called with one argument: the input to coerce.
+  #
+  # The coerce function can use any logic to convert the given input value
+  # to an acceptable output value, or raise a Coercive::Error for failure.
+  #
+  # In practice, it is most common to use one of the builtin generator methods
+  # (for example, string, or array(string)), or to use a module that was
+  # declared using the Coercive DSL functions, though any custom coerce function
+  # may be created and used for other behaviour, provided that it conforms to
+  # the same interface.
+  def attr_coerce_fns
+    @attr_coerce_fns ||= {}
+  end
+
+  # Private: Hash with String attribute names as keys and fetch function values.
+  #
+  # Each fetch function will be called with two arguments:
+  # 1 - input Hash of input attributes with String keys.
+  # 2 - output Hash in which the fetched attribute should be stored (if at all).
+  #
+  # The fetch function can use any logic to determine whether the attribute is
+  # present, whether it should be stored, whether to use an implicit default
+  # value, or whether to raise a Coercive::Error to propagate failure upward.
+  #
+  # In practice, it is most common to use one of the builtin generator methods,
+  # (required, optional, or implicit) to create the fetch function, though
+  # any custom fetch function could also be used for other behaviour.
+  #
+  # The return value of the fetch function will be ignored.
+  def attr_fetch_fns
+    @attr_fetch_fns ||= {}
+  end
+
+  # Public DSL: Declare a named attribute with a coercion and fetcher mechanism.
+  #
+  # name               - a Symbol name for this attribute.
+  # coerce_fn          - a coerce function which may be any callable object
+  #                      that accepts a single argument as the input data and
+  #                      returns the coerced output (or raises a Coercive::Error).
+  #                      See documentation for the attr_coerce_fns method.
+  # fetch_fn_generator - a callable generator that returns a fetch function when
+  #                      given the String name of the attribute to be fetched.
+  #                      See documentation for the attr_fetch_fns method.
+  #
+  # Returns the given name.
+  def attribute(name, coerce_fn, fetch_fn_generator)
+    str_name = name.to_s
+
+    attr_coerce_fns[str_name] = coerce_fn
+    attr_fetch_fns[str_name]  = fetch_fn_generator.call(str_name)
+
+    name
+  end
+
+  # Public DSL: Return a coerce function that doesn't change or reject anything.
+  # Used when declaring an attribute. See documentation for attr_coerce_fns.
+  def any
+    ->(input) do
+      input
+    end
+  end
+
+  # Public DSL: Return a coerce function to validate that the input is a
+  # member of the given set. That is, the input must be equal to at least
+  # one member of the given set, or a Coercive::Error will be raised.
+  # Used when declaring an attribute. See documentation for attr_coerce_fns.
+  #
+  # set - the Array of objects to use as the set for checking membership.
+  def member(set)
+    ->(input) do
+      fail Coercive::Error.new("not_valid") unless set.include?(input)
+
+      input
+    end
+  end
+
+  # Public DSL: Return a coerce function to coerce input to a Float.
+  # Used when declaring an attribute. See documentation for attr_coerce_fns.
+  def float
+    ->(input) do
+      begin
+        Float(input)
+      rescue TypeError, ArgumentError
+        fail Coercive::Error.new("not_numeric")
+      end
+    end
+  end
+
+  # Public DSL: Return a coerce function to coerce input to a String.
+  # Used when declaring an attribute. See documentation for attr_coerce_fns.
+  #
+  # min     - if given, restrict the minimum size of the input String.
+  # max     - if given, restrict the maximum size of the input String.
+  # pattern - if given, enforce that the input String matches the pattern.
+  def string(min: nil, max: nil, pattern: nil)
+    ->(input) do
+      input = begin
+                String(input)
+              rescue TypeError
+                fail Coercive::Error.new("not_valid")
+              end
+
+      if min && min > 0
+        fail Coercive::Error.new("is_empty")  if input.empty?
+        fail Coercive::Error.new("too_short") if input.bytesize < min
+      end
+
+      if max && input.bytesize > max
+        fail Coercive::Error.new("too_long")
+      end
+
+      if pattern && !pattern.match(input)
+        fail Coercive::Error.new("not_valid")
+      end
+
+      input
+    end
+  end
+
+  # Public DSL: Return a coercion function to coerce input to an Array.
+  # Used when declaring an attribute. See documentation for attr_coerce_fns.
+  #
+  # inner_coerce_fn - the coerce function to use on each element of the Array.
+  def array(inner_coerce_fn)
+    ->(input) do
+      output = []
+      errors = []
+      Array(input).each do |value|
+        begin
+          output << inner_coerce_fn.call(value)
+          errors << nil # pad the errors array with a nil element so that any
+                        # errors that follow will be in the right position
+        rescue Coercive::Error => e
+          errors << e.errors
+        end
+      end
+
+      fail Coercive::Error.new(errors) if errors.any?
+
+      output
+    end
+  end
+
+  # Public DSL: Return a coercion function to coerce input to a Hash.
+  # Used when declaring an attribute. See documentation for attr_coerce_fns.
+  #
+  # key_coerce_fn - the coerce function to use on each key of the Hash.
+  # val_coerce_fn - the coerce function to use on each value of the Hash.
+  def hash(key_coerce_fn, val_coerce_fn)
+    ->(input) do
+      fail Coercive::Error.new("not_valid") unless input.is_a?(Hash)
+
+      output = {}
+      errors = {}
+      input.each do |key, value|
+        begin
+          key         = key_coerce_fn.call(key)
+          output[key] = val_coerce_fn.call(value)
+        rescue Coercive::Error => e
+          errors[key] = e.errors
+        end
+      end
+
+      fail Coercive::Error.new(errors) if errors.any?
+
+      output
+    end
+  end
+
+  # Public DSL: See Coercive::URI.coerce_fn
+  def uri(*args)
+    Coercive::URI.coerce_fn(*args)
+  end
+
+  # Public DSL: Return a generator function for a "required" fetch function.
+  # Used when declaring an attribute. See documentation for attr_fetch_fns.
+  #
+  # The fetcher will store the present attribute or raise a Coercive::Error.
+  def required
+    ->(name) do
+      ->(input, fetched) do
+        fail Coercive::Error.new("not_present") unless input.key?(name)
+
+        fetched[name] = input[name]
+      end
+    end
+  end
+
+  # Public DSL: Return a generator function for a "optional" fetch function.
+  # Used when declaring an attribute. See documentation for attr_fetch_fns.
+  #
+  # The fetcher will store the attribute if it is present.
+  def optional
+    ->(name) do
+      ->(input, fetched) do
+        fetched[name] = input[name] if input.key?(name)
+      end
+    end
+  end
+
+  # Public DSL: Return a generator function for an "implicit" fetch function.
+  # Used when declaring an attribute. See documentation for attr_fetch_fns.
+  #
+  # The fetcher will store either the present attribute or the given default.
+  #
+  # default - the implicit value to use if the attribute is not present.
+  def implicit(default)
+    ->(name) do
+      ->(attrs, fetched) do
+        fetched[name] = attrs.key?(name) ? attrs[name] : default
+      end
+    end
+  end
+end

data/lib/coercive/uri.rb

@@ -0,0 +1,103 @@
+require "ipaddr"
+require "uri"
+
+module Coercion
+  module URI
+    # Setting this `true` allows outbound connections to private IP addresses,
+    # bypassing the security check that the IP address is public. This is designed
+    # to be used in devlopment so that the tests can connect to local services.
+    #
+    # This SHOULD NOT be set in PRODUCTION.
+    ALLOW_PRIVATE_IP_CONNECTIONS =
+      ENV.fetch("ALLOW_PRIVATE_IP_CONNECTIONS", "").downcase == "true"
+
+    PRIVATE_IP_RANGES = [
+      IPAddr.new("0.0.0.0/8"),       # Broadcasting to the current network. RFC 1700.
+      IPAddr.new("10.0.0.0/8"),      # Local private network. RFC 1918.
+      IPAddr.new("127.0.0.0/8"),     # Loopback addresses to the localhost. RFC 990.
+      IPAddr.new("169.254.0.0/16"),  # link-local addresses between two hosts on a single link. RFC 3927.
+      IPAddr.new("172.16.0.0/12"),   # Local private network. RFC 1918.
+      IPAddr.new("192.168.0.0/16"),  # Local private network. RFC 1918.
+      IPAddr.new("198.18.0.0/15"),   # Testing of inter-network communications between two separate subnets. RFC 2544.
+      IPAddr.new("198.51.100.0/24"), # Assigned as "TEST-NET-2" in RFC 5737.
+      IPAddr.new("203.0.113.0/24"),  # Assigned as "TEST-NET-3" in RFC 5737.
+      IPAddr.new("240.0.0.0/4"),     # Reserved for future use, as specified by RFC 6890
+      IPAddr.new("::1/128"),         # Loopback addresses to the localhost. RFC 5156.
+      IPAddr.new("2001:20::/28"),    # Non-routed IPv6 addresses used for Cryptographic Hash Identifiers. RFC 7343.
+      IPAddr.new("fc00::/7"),        # Unique Local Addresses (ULAs). RFC 1918.
+      IPAddr.new("fe80::/10"),       # link-local addresses between two hosts on a single link. RFC 3927.
+    ].freeze
+
+    # Public DSL: Return a coercion function to coerce input to a URI.
+    # Used when declaring an attribute. See documentation for attr_coerce_fns.
+    #
+    # string_coerce_fn - the string coerce function used to coerce the URI
+    # schema_fn        - the optional function used to coerce the schema
+    # require_path     - set true to make the URI path a required element
+    # require_port     - set true to make the URI port a required element
+    # require_user     - set true to make the URI user a required element
+    # require_password - set true to make the URI password a required element
+    def self.coerce_fn(string_coerce_fn, schema_fn: nil, require_path: false,
+            require_port: false, require_user: false, require_password: false)
+      ->(input) do
+        uri = begin
+          ::URI.parse(string_coerce_fn.call(input))
+        rescue ::URI::InvalidURIError
+          fail Coercion::Error.new("not_valid")
+        end
+
+        fail Coercion::Error.new("no_host") unless uri.host
+        fail Coercion::Error.new("not_resolvable") unless resolvable_public_ip?(uri) || ALLOW_PRIVATE_IP_CONNECTIONS
+        fail Coercion::Error.new("no_path") if require_path && uri.path.empty?
+        fail Coercion::Error.new("no_port") if require_port && !uri.port
+        fail Coercion::Error.new("no_user") if require_user && !uri.user
+        fail Coercion::Error.new("no_password") if require_password && !uri.password
+
+        if schema_fn
+          begin
+            schema_fn.call(uri.scheme)
+          rescue Coercion::Error
+            fail Coercion::Error.new("unsupported_schema")
+          end
+        end
+
+        uri.to_s
+      end
+    end
+
+    # Internal: Return true if the given URI is resolvable to a non-private IP.
+    #
+    # uri - the URI to check.
+    def self.resolvable_public_ip?(uri)
+      begin
+        _, _, _, *resolved_addresses = Socket.gethostbyname(uri.host)
+      rescue SocketError
+        return false
+      end
+
+      resolved_addresses.none? do |bytes|
+        ip = ip_from_bytes(bytes)
+
+        ip.nil? || PRIVATE_IP_RANGES.any? { |range| range.include?(ip) }
+      end
+    end
+
+    # Internal: Return an IPAddr built from the given address bytes.
+    #
+    # bytes - the binary-encoded String returned by Socket.gethostbyname.
+    def self.ip_from_bytes(bytes)
+      octets = bytes.unpack("C*")
+
+      string =
+        if octets.length == 4 # IPv4
+          octets.join(".")
+        else # IPv6
+          octets.map { |i| "%02x" % i }.each_slice(2).map(&:join).join(":")
+        end
+
+      IPAddr.new(string)
+    rescue IPAddr::InvalidAddressError
+      nil
+    end
+  end
+end

data/test/coercive.rb

@@ -0,0 +1,336 @@
+require_relative "../lib/coercive"
+require "minitest/autorun"
+require "bigdecimal"
+
+describe "Coercive" do
+  def assert_coercion_error(errors)
+    yield
+    assert false, "should have raised a Coercive::Error"
+  rescue Coercive::Error => e
+    assert_equal errors, e.errors
+  end
+
+  describe "required" do
+    it "errors when the attribute isn't present" do
+      coercion = Module.new do
+        extend Coercive
+
+        attribute :foo, any, required
+        attribute :bar, any, required
+        attribute :baz, any, required
+      end
+
+      expected_errors = { "foo" => "not_present", "baz" => "not_present" }
+
+      assert_coercion_error(expected_errors) { coercion.call("bar" => "red") }
+    end
+  end
+
+  describe "implicit" do
+    it "uses a default value when the attribute isn't present" do
+      coercion = Module.new do
+        extend Coercive
+
+        attribute :foo, any, implicit("black")
+        attribute :bar, any, implicit("grey")
+        attribute :baz, any, implicit("blue")
+      end
+
+      expected = { "foo" => "black", "bar" => "red", "baz" => "blue" }
+
+      assert_equal expected, coercion.call("bar" => "red")
+    end
+  end
+
+  describe "optional" do
+    it "omits the attribute in the output when not present in the input" do
+      coercion = Module.new do
+        extend Coercive
+
+        attribute :foo, any, optional
+        attribute :bar, any, optional
+        attribute :baz, any, optional
+      end
+
+      expected = { "bar" => "red" }
+
+      assert_equal expected, coercion.call("bar" => "red")
+    end
+  end
+
+  describe "any" do
+    it "accepts any input" do
+      coercion = Module.new do
+        extend Coercive
+
+        attribute :foo, any, required
+      end
+
+      [true, nil, "red", 88, [1, 2, 3]].each do |value|
+        expected = { "foo" => value }
+
+        assert_equal expected, coercion.call("foo" => value)
+      end
+    end
+  end
+
+  describe "member" do
+    before do
+      @coercion = Module.new do
+        extend Coercive
+
+        attribute :foo, member([nil, "red", "black"]), required
+      end
+    end
+
+    it "accepts any input in the set" do
+      [nil, "red", "black"].each do |value|
+        expected = { "foo" => value }
+
+        assert_equal expected, @coercion.call("foo" => value)
+      end
+    end
+
+    it "errors on any other input in the set" do
+      [true, "blue", 88, [1, 2, 3]].each do |bad|
+        expected_errors = { "foo" => "not_valid" }
+
+        assert_coercion_error(expected_errors) { @coercion.call("foo" => bad) }
+      end
+    end
+  end
+
+  describe "float" do
+    before do
+      @coercion = Module.new do
+        extend Coercive
+
+        attribute :foo, float, required
+      end
+    end
+
+    it "coerces the input value to a float" do
+      fixnum     = 2
+      rational   = 2 ** -2
+      bignum     = 2 ** 64
+      bigdecimal = BigDecimal.new("0.1")
+
+      [fixnum, rational, bignum, bigdecimal].each do |value|
+        attributes = { "foo" => value }
+
+        expected = { "foo" => Float(value) }
+
+        assert_equal expected, @coercion.call(attributes)
+        assert_equal Float,    @coercion.call(attributes)["foo"].class
+      end
+    end
+
+    it "errors when the input value can't be coerced to a float" do
+      [true, nil, "red", [1, 2, 3]].each do |bad|
+        expected_errors = { "foo" => "not_numeric" }
+
+        assert_coercion_error(expected_errors) { @coercion.call("foo" => bad) }
+      end
+    end
+  end
+
+  describe "string" do
+    before do
+      @coercion = Module.new do
+        extend Coercive
+
+        attribute :foo,   string,                     optional
+        attribute :bar,   string,                     optional
+        attribute :baz,   string,                     optional
+        attribute :min,   string(min: 4),             optional
+        attribute :max,   string(max: 6),             optional
+        attribute :sized, string(min: 4, max: 6),     optional
+        attribute :hex_a, string(pattern: /\A\h+\z/), optional
+        attribute :hex_b, string(pattern: /\A\h+\z/), optional
+      end
+    end
+
+    it "coerces the input value to a string" do
+      attributes = { "foo" => false, "bar" => 88, "baz" => "string" }
+
+      expected = { "foo" => "false", "bar" => "88", "baz" => "string" }
+
+      assert_equal expected, @coercion.call(attributes)
+    end
+
+    it "errors if the input is longer than the declared maximum size" do
+      attributes = {
+        "min" => "this will be okay",
+        "max" => "this is too long",
+        "sized" => "this also",
+      }
+
+      expected_errors = { "max" => "too_long", "sized" => "too_long" }
+
+      assert_coercion_error(expected_errors) { @coercion.call(attributes) }
+    end
+
+    it "errors if the input is shorter than the declared minimum size" do
+      attributes = {
+        "min"   => "???",
+        "max"   => "???",
+        "sized" => "???",
+      }
+
+      expected_errors = { "min" => "too_short", "sized" => "too_short" }
+
+      assert_coercion_error(expected_errors) { @coercion.call(attributes) }
+    end
+
+    it "errors if the input does not match the declared pattern" do
+      attributes = { "hex_a" => "DEADBEEF", "hex_b" => "REDBEETS" }
+
+      expected_errors = { "hex_b" => "not_valid" }
+
+      assert_coercion_error(expected_errors) { @coercion.call(attributes) }
+    end
+
+    it "checks size of the input after coercing to a string" do
+      attributes = { "max" => 1234567, "min" => 89 }
+
+      expected_errors = { "max" => "too_long", "min" => "too_short" }
+
+      assert_coercion_error(expected_errors) { @coercion.call(attributes) }
+    end
+  end
+
+  describe "array" do
+    before do
+      @coercion = Module.new do
+        extend Coercive
+
+        attribute :strings, array(string), required
+      end
+    end
+
+    it "coerces a array attribute input value to an array" do
+      attributes = { "strings" => "foo" }
+
+      expected = { "strings" => ["foo"] }
+
+      assert_equal expected, @coercion.call(attributes)
+    end
+
+    it "coerces a array attribute input's elements with the inner coercion" do
+      attributes = { "strings" => ["", 88, true] }
+
+      expected = { "strings" => ["", "88", "true"] }
+
+      assert_equal expected, @coercion.call(attributes)
+    end
+
+    it "collects errors from an array attribute input's elements" do
+      bad        = BasicObject.new
+      attributes = { "strings" => ["ok", bad, "ok"] }
+
+      expected_errors = { "strings" => [nil, "not_valid", nil] }
+
+      assert_coercion_error(expected_errors) { @coercion.call(attributes) }
+    end
+  end
+
+  describe "hash" do
+    before do
+      @coercion = Module.new do
+        extend Coercive
+
+        attribute :strings, hash(string(max: 6), string), required
+      end
+    end
+
+    it "errors when a hash attribute input value isn't a hash" do
+      [nil, true, "foo", []].each do |invalid|
+        attributes = { "strings" => invalid }
+
+        expected_errors = { "strings" => "not_valid" }
+
+        assert_coercion_error(expected_errors) { @coercion.call(attributes) }
+      end
+    end
+
+    it "coerces a hash attribute keys and values with the inner coercions" do
+      attributes = { "strings" => { false => nil } }
+
+      expected = { "strings" => { "false" => "" } }
+
+      assert_equal expected, @coercion.call(attributes)
+    end
+
+    it "collects errors from a hash attribute input's keys and values" do
+      bad        = BasicObject.new
+      attributes = { "strings" => { "foo" => bad, "food_truck" => "ok" } }
+
+      expected_errors = {
+        "strings" => { "foo" => "not_valid", "food_truck" => "too_long" }
+      }
+
+      assert_coercion_error(expected_errors) { @coercion.call(attributes) }
+    end
+  end
+
+  describe "with various declared attributes" do
+    before do
+      @coercion = Module.new do
+        extend Coercive
+
+        attribute :req_hash,
+          hash(string(max: 6), string),
+          required
+
+        attribute :opt_string,
+          string(min: 4, max: 6),
+          optional
+
+        attribute :imp_array,
+          array(string),
+          implicit(["default"])
+      end
+
+      @valid_attributes = {
+        "req_hash"   => { "one" => "red", "two" => "blue" },
+        "opt_string" => "apple",
+        "imp_array"  => ["foo", "bar", "baz"],
+      }
+    end
+
+    it "returns valid attributes without changing them" do
+      assert_equal @valid_attributes, @coercion.call(@valid_attributes)
+    end
+
+    it "errors when given an undeclared attribute" do
+      attributes = @valid_attributes.merge("bogus" => true)
+
+      expected_errors = { "bogus" => "unknown" }
+
+      assert_coercion_error(expected_errors) { @coercion.call(attributes) }
+    end
+
+    it "collects errors from all fetchers and coercions before reporting" do
+      attributes = {
+        "bogus"      => "bogus",
+        "opt_string" => "bar",
+        "imp_array"  => ["ok", BasicObject.new, "ok"],
+      }
+
+      expected_errors = {
+        "bogus"      => "unknown",
+        "req_hash"   => "not_present",
+        "opt_string" => "too_short",
+        "imp_array"  => [nil, "not_valid", nil],
+      }
+
+      assert_coercion_error(expected_errors) { @coercion.call(attributes) }
+    end
+
+    it "errors if given input that is not a Hash" do
+      assert_coercion_error("not_valid") { @coercion.call(nil) }
+      assert_coercion_error("not_valid") { @coercion.call(88) }
+      assert_coercion_error("not_valid") { @coercion.call([]) }
+    end
+  end
+end

data/test/uri.rb

@@ -0,0 +1,196 @@
+require "minitest/autorun"
+
+require_relative "../lib/coercive"
+require_relative "../lib/coercive/uri"
+
+describe "Coercive::URI" do
+  def assert_coercion_error(errors)
+    yield
+    assert false, "should have raised a Coercive::Error"
+  rescue Coercive::Error => e
+    assert_equal errors, e.errors
+  end
+
+  setup do
+    @coercion = Module.new do
+      extend Coercive
+
+      attribute :any,   uri(string),                   optional
+      attribute :min,   uri(string(min: 13)),          optional
+      attribute :max,   uri(string(max: 17)),          optional
+      attribute :sized, uri(string(min: 13, max: 17)), optional
+
+      attribute :schema,
+        uri(string(min: 1, max: 255), schema_fn: member(%w{http})),
+        optional
+
+      attribute :require_path,
+        uri(string(min: 1, max: 255), require_path: true),
+        optional
+
+      attribute :require_port,
+        uri(string(min: 1, max: 255), require_port: true),
+        optional
+
+      attribute :require_user,
+        uri(string(min: 1, max: 255), require_user: true),
+        optional
+
+      attribute :require_password,
+        uri(string(min: 1, max: 255), require_password: true),
+        optional
+    end
+  end
+
+  test "coerces a valid string to a URI" do
+    attributes = {
+      "any" => "http://user:pass@www.example.com:1234/path"
+    }
+
+    assert_equal attributes, @coercion.call(attributes)
+  end
+
+  test "errors if input is an invalid URI" do
+    attributes = { "any" => "%" }
+
+    expected_errors = { "any" => "not_valid" }
+
+    assert_coercion_error(expected_errors) { @coercion.call(attributes) }
+  end
+
+  test "errors if the input is longer than the declared maximum size" do
+    attributes = {
+      "min"   => "http://foo.com",
+      "max"   => "http://long.url.com",
+      "sized" => "http://way.too.long.com",
+    }
+
+    expected_errors = { "max" => "too_long", "sized" => "too_long" }
+
+    assert_coercion_error(expected_errors) { @coercion.call(attributes) }
+  end
+
+  test "errors if the input is shorter than the declared minimum size" do
+    attributes = {
+      "min"   => "http://a.com",
+      "max"   => "http://bar.com",
+      "sized" => "http://c.com"
+    }
+
+    expected_errors = { "min" => "too_short", "sized" => "too_short" }
+
+    assert_coercion_error(expected_errors) { @coercion.call(attributes) }
+  end
+
+  test "errors if the URI is an empty string" do
+    attributes      = { "schema" => "" }
+    expected_errors = { "schema" => "is_empty" }
+
+    assert_coercion_error(expected_errors) { @coercion.call(attributes) }
+  end
+
+  test "errors if no host" do
+    attributes = { "any" => "http://" }
+
+    expected_errors = { "any" => "no_host" }
+
+    assert_coercion_error(expected_errors) { @coercion.call(attributes) }
+  end
+
+  test "errors if schema is not supported" do
+    attributes = { "schema" => "foo://example.com" }
+
+    expected_errors = { "schema" => "unsupported_schema" }
+
+    assert_coercion_error(expected_errors) { @coercion.call(attributes) }
+  end
+
+  test "errors if required elements are not provided" do
+    attributes = {
+      "require_path"     => "foo://example.com",
+      "require_port"     => "foo://example.com",
+      "require_user"     => "foo://example.com",
+      "require_password" => "foo://example.com",
+    }
+
+    expected_errors = {
+      "require_path"     => "no_path",
+      "require_port"     => "no_port",
+      "require_user"     => "no_user",
+      "require_password" => "no_password",
+    }
+
+    assert_coercion_error(expected_errors) { @coercion.call(attributes) }
+  end
+
+  Coercive::URI::PRIVATE_IP_RANGES.each do |range|
+    range = range.to_range
+    first = range.first
+    last  = range.last
+    first = first.ipv6? ? "[#{first}]" : first.to_s
+    last  = last.ipv6?  ? "[#{last}]"  : last.to_s
+
+    test "errors when the URI host is an IP in the range #{first}..#{last}" do
+      attributes_first = { "schema" => "http://#{first}/path" }
+      attributes_last  = { "schema" => "http://#{last}/path" }
+      expected_errors  = { "schema" => "not_resolvable" }
+
+      assert_coercion_error(expected_errors) { @coercion.call(attributes_first) }
+      assert_coercion_error(expected_errors) { @coercion.call(attributes_last) }
+    end
+  end
+
+  test "errors when the URI host is not resolvable" do
+    attributes = {
+      "schema" => "http://bogus-host-that-cant-possibly-exist-here/path"
+    }
+
+    expected_errors = { "schema" => "not_resolvable" }
+
+    assert_coercion_error(expected_errors) { @coercion.call(attributes) }
+  end
+
+  test "errors when the URI host resolves to an IP in a private range" do
+    attributes = { "schema" => "http://localhost/path" }
+
+    expected_errors = { "schema" => "not_resolvable" }
+
+    assert_coercion_error(expected_errors) { @coercion.call(attributes) }
+  end
+
+  test "allows a URI host to be IP that isn't in a private range" do
+    attributes = { "schema" => "http://8.8.8.8/path" }
+
+    assert_equal attributes, @coercion.call(attributes)
+  end
+
+  test "allows a URI host that resolves to an IP not in a private range" do
+    attributes = { "schema" => "http://www.example.com/path" }
+
+    assert_equal attributes, @coercion.call(attributes)
+  end
+
+  test "allows a URI with no explicit path component" do
+    attributes = { "schema" => "http://www.example.com" }
+
+    assert_equal attributes, @coercion.call(attributes)
+  end
+
+  test "errors for a string that does not pass URI.parse" do
+    attributes = { "schema" => "\\" }
+    expected_errors = { "schema" => "not_valid" }
+
+    assert_coercion_error(expected_errors) { @coercion.call(attributes) }
+  end
+
+  test "errors for a URL that passes URI.parse, but is ill-formed" do
+    attributes = { "schema" => "http:example.com/path" }
+
+    begin
+      @coercion.call(attributes)
+      assert false, "should have raised a Coercive::Error"
+    rescue Coercive::Error => e
+      assert !e.errors["schema"].empty?, "should have a schema error"
+    end
+  end
+end

metadata

@@ -0,0 +1,51 @@
+--- !ruby/object:Gem::Specification
+name: coercive
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Joe McIlvain
+- Lucas Tolchinsky
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2020-08-04 00:00:00.000000000 Z
+dependencies: []
+description: Coercive is a library to validate and coerce user input
+email:
+- joe.eli.mac@gmail.com
+- tonchis@protonmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/coercive.rb
+- lib/coercive/uri.rb
+- test/coercive.rb
+- test/uri.rb
+homepage: https://github.com/Theorem/coercive
+licenses:
+- MIT
+metadata: {}
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.0.3
+signing_key:
+specification_version: 4
+summary: Coercive is a library to validate and coerce user input
+test_files: []