coercive 1.0.1 → 1.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 867918b9a3ee09bdfc89a10e802032e229fdf4ab250f80727a68197f8144d615
-  data.tar.gz: 9d1dcfcc05db65d1669049c87f36bf9a252fe91ce68b9298a7578ce630aeae50
+  metadata.gz: a9ce029330ac405fde945a05e6f81c62361027ebe5d03659fd82b067554087e7
+  data.tar.gz: 89cfe35313fde4e0b0cea25d6050b008e75c8457ca440b71cf1c2acca26d13d1
 SHA512:
-  metadata.gz: 2dc34142c2553b747290451db7ca631dd12b31e9e7488502e4a54b3fc1cf372a7dd498c951498f8c3b86d519172bb879fb7f650e97448260dd8fad2c5c5c8662
-  data.tar.gz: 513cb240285c58fbf784d3a61fae066bf7c768836cdc06281357b92f8c7a62ad72ea2c0114f3ba6645da29b4ed01fbabff616f10db91f93b8194c587d2f9c623
+  metadata.gz: d5260061302b501653bf64ce29988622f5ea06739a32058778a64106ad25ddd28567773048ac48addf510adc5f08357f0f6258c2877b67b8e2c0a3e3352baf48
+  data.tar.gz: 25e42dec9a930a6cea139f581114abf59d166a95210a5884edb0276a29bbbee7cb365959d51c6caddc4c76c827d0dfecf5bdb71386e262d2e8fccd3b20decacc

data/README.md

@@ -128,6 +128,30 @@ CoerceFoo.call("foo" => "DEADBEEF")
 # => {"foo"=>"DEADBEEF"}
 ```
 
+### `date` and `datetime`
+
+The `date` and `datetime` coercion functions will receive a `String` and give you `Date` and `DateTime` objects, respectively.
+
+By default they expect an ISO 8601 string, but they provide a `format` option in case you need to parse something different, following the `strftime` format.
+
+```ruby
+module CoerceFoo
+  extend Coercive
+
+  attribute :date_foo,      date,                     optional
+  attribute :american_date, date(format: "%m-%d-%Y"), optional
+  attribute :datetime_foo,  datetime,                 optional
+end
+
+CoerceFoo.call("date_foo" => "1988-05-18", "datetime_foo" => "1988-05-18T21:00:00Z", "american_date" => "05-18-1988")
+# => {"date_foo"=>#<Date: 1988-05-18 ((2447300j,0s,0n),+0s,2299161j)>,
+#  "american_date"=>#<Date: 1988-05-18 ((2447300j,0s,0n),+0s,2299161j)>,
+#  "datetime_foo"=>#<DateTime: 1988-05-18T21:00:00+00:00 ((2447300j,75600s,0n),+0s,2299161j)>}
+
+CoerceFoo.call("date_foo" => "18th May 1988")
+# => Coercive::Error: {"date_foo"=>"not_valid"}
+```
+
 ### `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.
@@ -147,20 +171,58 @@ CoerceFoo.call("foo" => 4)
 # => Coercive::Error: {"foo"=>"not_valid"}
 ```
 
-### `float`
+### `integer(min:, max:)`
 
-`float` expects, well, a float value.
+`integer` expects an integer value. It supports optional `min` and `max` options to check if the user input is within certain bounds.
 
 ```ruby
 module CoerceFoo
   extend Coercive
 
-  attribute :foo, float, optional
+  attribute :foo,        integer,                  optional
+  attribute :foo_bounds, integer(min: 1, max: 10), optional
 end
 
+CoerceFoo.call("foo" => "1")
+# => {"foo"=>1}
+
 CoerceFoo.call("foo" => "bar")
 # => Coercive::Error: {"foo"=>"not_valid"}
 
+CoerceFoo.call("foo" => "1.5")
+# => Coercive::Error: {"foo"=>"not_numeric"}
+
+CoerceFoo.call("foo" => 1.5)
+# => Coercive::Error: {"foo"=>"float_not_permitted"}
+
+CoerceFoo.call("foo_bounds" => 0)
+# => Coercive::Error: {"foo_bounds"=>"too_low"}
+
+CoerceFoo.call("foo_bounds" => 11)
+# => Coercive::Error: {"foo_bounds"=>"too_high"}
+```
+
+### `float(min:, max:)`
+
+`float` expects, well, a float value. It supports optional `min` and `max` options to check if the user input is within certain bounds.
+
+```ruby
+module CoerceFoo
+  extend Coercive
+
+  attribute :foo,        float,                     optional
+  attribute :foo_bounds, float(min: 1.0, max: 5.5), optional
+end
+
+CoerceFoo.call("foo" => "bar")
+# => Coercive::Error: {"foo"=>"not_valid"}
+
+CoerceFoo.call("foo" => "0.5")
+# => Coercive::Error: {"foo"=>"too_low"}
+
+CoerceFoo.call("foo" => 6.5)
+# => Coercive::Error: {"foo"=>"too_high"}
+
 CoerceFoo.call("foo" => "0.1")
 # => {"foo"=>0.1}
   
@@ -212,4 +274,45 @@ CoerceFoo.call("foo" => {"barrrr" => "0.1"})
 
 ### `uri`
 
-The `uri` coercion validates 
+The `uri` coercion function really showcases how it's very easy to build custom logic to validate and coerce any kind of input. `uri` is meant to verify IP and URLs and has a variety of options.
+
+```ruby
+module CoerceFoo
+  extend Coercive
+
+  attribute :foo, uri(string), optional
+end
+
+CoerceFoo.call("foo" => "http://github.com")
+# => {"foo"=>"http://github.com"}
+
+CoerceFoo.call("foo" => "not a url")
+# => Coercive::Error: {"foo"=>"not_valid"}
+```
+
+#### Requiring a specific URI schema
+
+The `schema_fn` option allows you to compose additional coercion functions to verify the schema.
+
+```ruby
+module CoerceFoo
+  extend Coercive
+
+  attribute :foo, uri(string, schema_fn: member(%w{http https})), optional
+end
+
+CoerceFoo.call("foo" => "https://github.com")
+# => {"foo"=>"https://github.com"}
+
+CoerceFoo.call("foo" => "ftp://github.com")
+# => Coercive::Error: {"foo"=>"unsupported_schema"}
+```
+
+#### Requiring URI elements
+
+There's a number of boolean options to enforce the presence of parts of a URI to be present. By default they're all false.
+
+* `require_path`: for example, `"https://github.com/Theorem"`
+* `require_port`: for example, `"https://github.com:433"`
+* `require_user`: for example, `"https://user@github.com"`
+* `require_password`: for example, `"https://:password@github.com"`

data/coercive.gemspec

@@ -1,6 +1,6 @@
 Gem::Specification.new do |s|
   s.name = "coercive"
-  s.version = "1.0.1"
+  s.version = "1.5.0"
   s.summary = "Coercive is a library to validate and coerce user input"
   s.description = s.summary
   s.authors = ["Joe McIlvain", "Lucas Tolchinsky"]

data/lib/coercive.rb

@@ -1,3 +1,4 @@
+require "date"
 require_relative "coercive/uri"
 
 # Public: The Coercive module implements a succinct DSL for declaring callable
@@ -149,15 +150,39 @@ module Coercive
     end
   end
 
+  # Public DSL: Return a coerce function to coerce input to an Integer.
+  # Used when declaring an attribute. See documentation for attr_coerce_fns.
+  def integer(min: nil, max: nil)
+    ->(input) do
+      fail Coercive::Error.new("float_not_permitted") if input.is_a?(Float)
+
+      input = begin
+                Integer(input)
+              rescue TypeError, ArgumentError
+                fail Coercive::Error.new("not_numeric")
+              end
+
+      fail Coercive::Error.new("too_low")  if min && input < min
+      fail Coercive::Error.new("too_high") if max && input > max
+
+      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
+  def float(min: nil, max: nil)
     ->(input) do
-      begin
-        Float(input)
-      rescue TypeError, ArgumentError
-        fail Coercive::Error.new("not_numeric")
-      end
+      input = begin
+                Float(input)
+              rescue TypeError, ArgumentError
+                fail Coercive::Error.new("not_numeric")
+              end
+
+      fail Coercive::Error.new("too_low")  if min && input < min
+      fail Coercive::Error.new("too_high") if max && input > max
+
+      input
     end
   end
 
@@ -192,6 +217,48 @@ module Coercive
     end
   end
 
+  # Public DSL: Return a coercion function to coerce input into a Date.
+  # Used when declaring an attribute. See documentation for attr_coerce_fns.
+  #
+  # format - String following Ruby's `strftime` format to change the parsing behavior. When empty
+  #          it will expect the String to be ISO 8601 compatible.
+  def date(format: nil)
+    ->(input) do
+      input = begin
+                if format
+                  Date.strptime(input, format)
+                else
+                  Date.iso8601(input)
+                end
+              rescue ArgumentError
+                fail Coercive::Error.new("not_valid")
+              end
+
+      input
+    end
+  end
+
+  # Public DSL: Return a coercion function to coerce input into a DateTime.
+  # Used when declaring an attribute. See documentation for attr_coerce_fns.
+  #
+  # format - String following Ruby's `strftime` format to change the parsing behavior. When empty
+  #          it will expect the String to be ISO 8601 compatible.
+  def datetime(format: nil)
+    ->(input) do
+      input = begin
+                if format
+                  DateTime.strptime(input, format)
+                else
+                  DateTime.iso8601(input)
+                end
+              rescue ArgumentError
+                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.
   #

data/lib/coercive/uri.rb

@@ -3,27 +3,6 @@ require "uri"
 
 module Coercive
   module URI
-    # The IP ranges below are considered private and by default not permitted by the `uri`
-    # coercion function. To allow connecting to local services (in development, for example)
-    # users can set the `allow_private_ip` option, which ignores if the URI resolves to a public
-    # address or not.
-    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.
     #
@@ -34,8 +13,7 @@ module Coercive
     # 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,
-            allow_private_ip: false)
+            require_port: false, require_user: false, require_password: false)
       ->(input) do
         uri = begin
           ::URI.parse(string_coerce_fn.call(input))
@@ -44,7 +22,6 @@ module Coercive
         end
 
         fail Coercive::Error.new("no_host") unless uri.host
-        fail Coercive::Error.new("not_resolvable") unless allow_private_ip || resolvable_public_ip?(uri)
         fail Coercive::Error.new("no_path") if require_path && uri.path.empty?
         fail Coercive::Error.new("no_port") if require_port && !uri.port
         fail Coercive::Error.new("no_user") if require_user && !uri.user
@@ -61,40 +38,5 @@ module Coercive
         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

@@ -100,12 +100,57 @@ describe "Coercive" do
     end
   end
 
+  describe "integer" do
+    before do
+      @coercion = Module.new do
+        extend Coercive
+
+        attribute :foo, integer, optional
+        attribute :bar, integer, optional
+        attribute :baz, integer(min: 1, max: 10), optional
+      end
+    end
+
+    it "coerces the input value to an integer" do
+      attributes = { "foo" => "100", "bar" => 100 }
+
+      expected = { "foo" => 100, "bar" => 100 }
+
+      assert_equal expected, @coercion.call(attributes)
+    end
+
+    it "doesn't allow Float" do
+      expected_errors = { "foo" => "float_not_permitted" }
+
+      assert_coercion_error(expected_errors) { @coercion.call("foo" => 100.5) }
+    end
+
+    it "errors if the input can't be coerced into an Integer" do
+      ["nope", "100.5", "1e5"].each do |value|
+        expected_errors = { "foo" => "not_numeric" }
+
+        assert_coercion_error(expected_errors) { @coercion.call("foo" => value) }
+      end
+    end
+
+    it "errors if the input is out of bounds" do
+      expected_errors = { "baz" => "too_low" }
+
+      assert_coercion_error(expected_errors) { @coercion.call("baz" => 0) }
+      
+      expected_errors = { "baz" => "too_high" }
+
+      assert_coercion_error(expected_errors) { @coercion.call("baz" => 11) }
+    end
+  end
+
   describe "float" do
     before do
       @coercion = Module.new do
         extend Coercive
 
-        attribute :foo, float, required
+        attribute :foo, float,                     optional
+        attribute :bar, float(min: 1.0, max: 5.5), optional
       end
     end
 
@@ -132,6 +177,16 @@ describe "Coercive" do
         assert_coercion_error(expected_errors) { @coercion.call("foo" => bad) }
       end
     end
+
+    it "errors if the input is out of bounds" do
+      expected_errors = { "bar" => "too_low" }
+
+      assert_coercion_error(expected_errors) { @coercion.call("bar" => 0.5) }
+      
+      expected_errors = { "bar" => "too_high" }
+
+      assert_coercion_error(expected_errors) { @coercion.call("bar" => 6.0) }
+    end
   end
 
   describe "string" do
@@ -199,6 +254,84 @@ describe "Coercive" do
     end
   end
 
+  describe "date" do
+    before do
+      @coercion = Module.new do
+        extend Coercive
+
+        attribute :date,          date,                     optional
+        attribute :american_date, date(format: "%m-%d-%Y"), optional
+      end
+    end
+
+    it "coerces a string into a Date object with ISO 8601 format by default" do
+      attributes = { "date" => "1988-05-18" }
+
+      expected = { "date" => Date.new(1988, 5, 18) }
+
+      assert_equal expected, @coercion.call(attributes)
+    end
+
+    it "supports a custom date format" do
+      attributes = { "american_date" => "05-18-1988" }
+
+      expected = { "american_date" => Date.new(1988, 5, 18) }
+
+      assert_equal expected, @coercion.call(attributes)
+    end
+
+    it "errors if the input doesn't parse" do
+      attributes = { "date" => "12-31-1990" }
+
+      expected_errors = { "date" => "not_valid" }
+
+      assert_coercion_error(expected_errors) { @coercion.call(attributes) }
+    end
+  end
+
+  describe "datetime" do
+    before do
+      @coercion = Module.new do
+        extend Coercive
+
+        attribute :datetime,      datetime,                                 optional
+        attribute :american_date, datetime(format: "%m-%d-%Y %I:%M:%S %p"), optional
+      end
+    end
+
+    it "coerces a string into a DateTime object with ISO 8601 format by default" do
+      attributes = { "datetime" => "1988-05-18T21:00:00Z" }
+
+      expected = { "datetime" => DateTime.new(1988, 5, 18, 21, 00, 00) }
+
+      assert_equal expected, @coercion.call(attributes)
+    end
+
+    it "honors the timezone" do
+      attributes = { "datetime" => "1988-05-18T21:00:00-0300" }
+
+      expected = { "datetime" => DateTime.new(1988, 5, 18, 21, 00, 00, "-03:00") }
+
+      assert_equal expected, @coercion.call(attributes)
+    end
+
+    it "supports a custom date format" do
+      attributes = { "american_date" => "05-18-1988 09:00:00 PM" }
+
+      expected = { "american_date" => DateTime.new(1988, 5, 18, 21, 00, 00) }
+
+      assert_equal expected, @coercion.call(attributes)
+    end
+
+    it "errors if the input doesn't parse" do
+      attributes = { "datetime" => "12-31-1990T21:00:00Z" }
+
+      expected_errors = { "datetime" => "not_valid" }
+
+      assert_coercion_error(expected_errors) { @coercion.call(attributes) }
+    end
+  end
+
   describe "array" do
     before do
       @coercion = Module.new do

data/test/uri.rb

@@ -39,10 +39,6 @@ describe "Coercive::URI" do
       attribute :require_password,
         uri(string(min: 1, max: 255), require_password: true),
         optional
-
-      attribute :allow_private_ip,
-        uri(string(min: 1, max: 255), allow_private_ip: true),
-        optional
     end
   end
 
@@ -127,61 +123,12 @@ describe "Coercive::URI" do
     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
-
-    it "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
-
-    it "allows overriding private IP address checks" do
-      attributes_first = { "allow_private_ip" => "http://#{first}/path" }
-      attributes_last  = { "allow_private_ip" => "http://#{last}/path" }
-
-      assert_equal attributes_first, @coercion.call(attributes_first)
-      assert_equal attributes_last,  @coercion.call(attributes_last)
-    end
-  end
-
-  it "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
-
-  it "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
-
-  it "allows a URI host to be IP that isn't in a private range" do
+  it "allows a URI host to be an IP" do
     attributes = { "schema" => "http://8.8.8.8/path" }
 
     assert_equal attributes, @coercion.call(attributes)
   end
 
-  it "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
-
   it "allows a URI with no explicit path component" do
     attributes = { "schema" => "http://www.example.com" }
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: coercive
 version: !ruby/object:Gem::Version
-  version: 1.0.1
+  version: 1.5.0
 platform: ruby
 authors:
 - Joe McIlvain
@@ -9,7 +9,7 @@ authors:
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2020-08-05 00:00:00.000000000 Z
+date: 2020-09-03 00:00:00.000000000 Z
 dependencies: []
 description: Coercive is a library to validate and coerce user input
 email: