roda 3.2.0 → 3.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: e4935b8951819226ca81b82723628a6c555e505e
-  data.tar.gz: c3fd3714c47c7b5e014ed34a2f817a249b257fa6
+  metadata.gz: 992b12eaa4153e29ad448ac21c6afafe12f9a89a
+  data.tar.gz: 3ce43ca69c2faeb4a335968959365f33309460ed
 SHA512:
-  metadata.gz: 7bf5572895450e439a6559a79815603a98fd5dd1b2a1b11a1b13218dd15a35cbdbc67db60021752878c22fc1dceadc8f4926c79f90d65705ca78187a68fb8c55
-  data.tar.gz: 4a6e9c478b28b58da51dedad966cd77b72ff5bca90a21d4adcba47c4560252549af8d9f75df2123fc30f46c600b7da06e7b6f5d8bb692b36d5f7052a0a364148
+  metadata.gz: af0baab222fcd78a7b49e5d8d2e204139ab7b1ec25cf75d001c2715777d31effa1527dda7ecfe9e1f18082978f77ad419d5c0b020667c6265d9273038d441483
+  data.tar.gz: 4b7da58d7c976ed77f7da407090c14f38f912ac0dbead739cc676a16b10665d09866a95f739c852139919a260805e839a80ea0c9797a3da8413aaef632109046

data/CHANGELOG

@@ -1,3 +1,7 @@
+= 3.3.0 (2017-12-14)
+
+* Add typecast_params plugin for converting param values to explicit types (jeremyevans)
+
 = 3.2.0 (2017-11-16)
 
 * Use microseconds in assets plugin :timestamp_paths timestamps (jeremyevans)

data/README.rdoc

@@ -443,7 +443,7 @@ treat it as one route with an optional segment.  One simple way to do that is to
 use a parameter instead of an optional segment (e.g. +/items/123?opt=456+).
 
   r.is "items", Integer do |item_id|
-    optional_data = r.params['opt']
+    optional_data = r.params['opt'].to_s
   end
 
 However, if you really do want to use a optional segment, there are a couple different
@@ -812,6 +812,34 @@ are not escaping the output of the content template:
 
 This support requires {Erubi}[https://github.com/jeremyevans/erubi].
 
+=== Unexpected Parameter Types
+
+Rack converts submitted parameters into a hash of strings, arrays, and
+nested hashes.  Since the user controls the submission of parameters, you
+should treat any submission of parameters with caution, and should be
+explicitly checking and/or converting types before using any submitted 
+parameters.  One way to do this is explicitly after accessing them:
+
+  # Convert foo_id parameter to an integer
+  request.params['foo_id'].to_i
+
+However, it is easy to forget to convert the type, and if the user
+submits +foo_id+ as a hash or array, a NoMethodError will be raised.
+Worse is if you do:
+
+  some_method(request.params['bar'])
+
+Where +some_method+ supports both a string argument and a hash
+argument, and you expect the parameter will be submitted as a
+string, and +some_method+'s handling of a hash argument performs
+an unauthorized action.
+
+Roda ships with a +typecast_params+ plugin that can easily handle
+the typecasting of submitted parameters, and it is recommended
+that all Roda applications that deal with parameters use it or
+another tool to explicitly convert submitted parameters to the
+expected types.
+
 === Security Related HTTP Headers
 
 You may want to look into setting the following HTTP headers, which

data/doc/release_notes/3.3.0.txt

@@ -0,0 +1,291 @@
+= New Features
+
+* A typecast_params plugin has been added for handling the
+  conversion of params to the expected type.  This plugin is
+  recommended for all applications that deal with submitted
+  parameters.
+
+  Submitted parameters should be considered untrusted input, and in
+  standard use with browsers, parameters are submitted as strings
+  (or a hash/array containing strings).  In most cases it makes sense
+  to explicitly convert the parameter to the desired type.  While this
+  can be done via manual conversion:
+    
+    key = request.params['key'].to_i
+    key = nil unless key > 0
+    
+  the typecast_params plugin adds a friendlier interface:
+    
+    key = typecast_params.pos_int('key')
+    
+  As typecast_params is a fairly long method name, you may want to
+  consider aliasing it to something more terse in your application,
+  such as tp.
+
+  One advantage of using typecast_params is that access or conversion
+  errors are raised as a specific exception class
+  (Roda::RodaPlugins::TypecastParams::Error).  This allows you to
+  handle this specific exception class globally and return an
+  appropriate 4xx response to the client.  You can use the
+  Error#param_name and Error#reason methods to get more information
+  about the error.
+    
+  typecast_params offers support for default values:
+    
+    key = typecast_params.pos_int('key', 1)
+    
+  The default value is only used if no value has been submitted for
+  the parameter, or if the conversion of the value results in nil.
+  Handling defaults for parameter conversion manually is more
+  difficult, since the parameter may not be present at all, or it may
+  be present but an empty string because the user did not enter a
+  value on the related form.  Use of typecast_params for the
+  conversion handles both cases.
+
+  In many cases, parameters should be required, and if they aren't
+  submitted, that should be considered an error.  typecast_params
+  handles this with ! methods:
+
+    key = typecast_params.pos_int!('key')
+
+  These ! methods raise an error instead of returning nil, and do not
+  allow defaults.
+
+  To make it easy to handle cases where many parameters need the same
+  conversion done, you can pass an array of keys to a conversion
+  method, and it will return an array of converted values:
+
+    key1, key2 = typecast_params.pos_int(['key1', 'key2'])
+
+  This is equivalent to:
+
+    key1 = typecast_params.pos_int('key1')
+    key2 = typecast_params.pos_int('key2')
+
+  The ! methods also support arrays of keys, ensuring that all
+  parameters have a value:
+
+    key1, key2 = typecast_params.pos_int!(['key1', 'key2'])
+
+  For handling of array parameters, where all entries in the array
+  use the same conversion, there is an array method which takes the
+  type as the first argument and the keys to convert as the second
+  argument:
+
+    keys = typecast_params.array(:pos_int, 'keys')
+
+  If you want to ensure that all entries in the array are converted
+  successfully and that there is a value for the array itself, you
+  can use array!:
+
+    keys = typecast_params.array!(:pos_int, 'keys')
+
+  This will raise an exception if any of the values in the array for
+  parameter keys cannot be converted to a positive integer.
+
+  Both array and array! support default values which are used if no
+  value is present for the parameter:
+
+    keys = typecast_params.array(:pos_int, 'keys', [])
+    keys = typecast_params.array!(:pos_int, 'keys', [])
+
+  You can also pass an array of keys to array or array!, if you would
+  like to perform the same conversion on multiple arrays:
+
+    foo_ids, bar_ids = typecast_params.array!(:pos_int, ['foo_ids', 'bar_ids'])
+
+  The previous examples have shown use of the pos_int method, which
+  uses to_i to convert the value to an integer, but returns nil if the
+  resulting integer is not positive.  Unless you need to handle
+  negative numbers, it is recommended to use pos_int instead of int as
+  int will convert invalid values to 0 (since that is how
+  <tt>String#to_i</tt> works).
+
+  There are many built in methods for type conversion:
+
+  any :: Returns the value as is without conversion
+  str :: Raises if value is not already a string
+  nonempty_str :: Raises if value is not already a string, and
+                  converts the empty string or string containing only
+                  whitespace to nil
+  bool :: Converts entry to boolean if in one of the recognized
+          formats (case insensitive for strings):
+          nil :: nil, ''
+          true :: true, 1, '1', 't', 'true', 'yes', 'y', 'on'
+          false :: false, 0, '0', 'f', 'false', 'no', 'n', 'off'
+          If not in one of those formats, raises an error.
+  int :: Converts value to integer using to_i (note that invalid
+         input strings will be converted to 0)
+  pos_int :: Converts value using to_i, but non-positive values
+             are converted to nil
+  Integer :: Converts value to integer using
+             Kernel::Integer(value, 10)
+  float :: Converts value to float using to_f (note that invalid
+           input strings will be converted to 0.0)
+  Float :: Converts value to float using Kernel::Float(value)
+  Hash :: Raises if value is not already a hash
+  date :: Converts value to Date using Date.parse(value)
+  time :: Converts value to Time using Time.parse(value)
+  datetime :: Converts value to DateTime using DateTime.parse(value)
+  file :: Raises if value is not already a hash with a :tempfile key
+          whose value responds to read (this is the format rack uses
+          for uploaded files).
+
+  All of these methods also support ! methods (e.g. pos_int!), and all
+  of them can be used in the array and array! methods to support
+  arrays of values.
+
+  Since parameter hashes can be nested, the [] method can be used to
+  access nested
+  hashes:
+
+    # params: {'key'=>{'sub_key'=>'1'}}
+    typecast_params['key'].pos_int!('sub_key') # => 1
+
+  This works to an arbitrary depth:
+
+    # params: {'key'=>{'sub_key'=>{'sub_sub_key'=>'1'}}}
+    typecast_params['key']['sub_key'].pos_int!('sub_sub_key') # => 1
+
+  And also works with arrays at any depth, if those arrays contain
+  hashes:
+
+    # params: {'key'=>[{'sub_key'=>{'sub_sub_key'=>'1'}}]}
+    typecast_params['key'][0]['sub_key'].pos_int!('sub_sub_key') # => 1
+
+    # params: {'key'=>[{'sub_key'=>['1']}]}
+    typecast_params['key'][0].array!(:pos_int, 'sub_key') # => [1]
+
+  To allow easier access to nested data, there is a dig method:
+
+    typecast_params.dig(:pos_int, 'key', 'sub_key')
+    typecast_params.dig(:pos_int, 'key', 0, 'sub_key', 'sub_sub_key')
+
+  dig will return nil if any access while looking up the nested value
+  returns nil.  There is also a dig! method, which will raise an Error
+  if dig would return nil:
+
+    typecast_params.dig!(:pos_int, 'key', 'sub_key')
+    typecast_params.dig!(:pos_int, 'key', 0, 'sub_key', 'sub_sub_key')
+
+  Note that none of these conversion methods modify request.params.
+  They purely do the conversion and return the converted value.
+  However, in some cases it is useful to do all the conversion up
+  front, and then pass a hash of converted parameters to an internal
+  method that expects to receive values in specific types.  The
+  convert! method does this, and there is also a convert_each! method
+  designed for converting multiple values using the same block:
+
+    converted_params = typecast_params.convert! do |tp|
+      tp.int('page')
+      tp.pos_int!('artist_id')
+      tp.array!(:pos_int, 'album_ids')
+      tp.convert!('sales') do |stp|
+        tp.pos_int!(['num_sold', 'num_shipped'])
+      end
+      tp.convert!('members') do |mtp|
+        mtp.convert_each! do |stp|
+          stp.str!(['first_name', 'last_name'])
+        end
+      end
+    end
+
+    # converted_params:
+    # {
+    #   'page' => 1,
+    #   'artist_id' => 2,
+    #   'album_ids' => [3, 4],
+    #   'sales' => {
+    #     'num_sold' => 5,
+    #     'num_shipped' => 6
+    #   },
+    #   'members' => [
+    #      {'first_name' => 'Foo', 'last_name' => 'Bar'},
+    #      {'first_name' => 'Baz', 'last_name' => 'Quux'}
+    #   ]
+    # }
+
+  convert! and convert_each! only return values you explicitly specify
+  for conversion inside the passed block.
+  
+  You can specify the :symbolize option to convert! or convert_each!,
+  which will symbolize the resulting hash keys:
+
+    converted_params = typecast_params.convert!(symbolize: true) do |tp|
+      tp.int('page')
+      tp.pos_int!('artist_id')
+      tp.array!(:pos_int, 'album_ids')
+      tp.convert!('sales') do |stp|
+        tp.pos_int!(['num_sold', 'num_shipped'])
+      end
+      tp.convert!('members') do |mtp|
+        mtp.convert_each! do |stp|
+          stp.str!(['first_name', 'last_name'])
+        end
+      end
+    end
+
+    # converted_params:
+    # {
+    #   :page => 1,
+    #   :artist_id => 2,
+    #   :album_ids => [3, 4],
+    #   :sales => {
+    #     :num_sold => 5,
+    #     :num_shipped => 6
+    #   },
+    #   :members => [
+    #      {:first_name => 'Foo', :last_name => 'Bar'},
+    #      {:first_name => 'Baz', :last_name => 'Quux'}
+    #   ]
+    # }
+
+  Using the :symbolize option makes it simpler to transition from
+  untrusted external data (string keys), to trusted data that can be
+  used internally (trusted in the sense that the expected types are
+  used).
+
+  Note that if there are multiple conversion errors raised inside a
+  convert! or convert_each!  block, they are recorded and a single
+  Roda::RodaPlugins::TypecastParams::Error instance is raised after
+  processing the block.  TypecastParams::Error#params_names can be
+  called on the exception to get an array of all parameter names
+  with conversion issues, and TypecastParams::Error#all_errors
+  can be used to get an array of all Error instances.
+
+  Because of how convert! and convert_each! work, you should avoid
+  calling TypecastParams::Params#[] inside the block you pass to
+  these methods, because if the #[] call fails, it will skip the
+  reminder of the block.
+
+  Be aware that when you use convert! and convert_each!, the
+  conversion methods called inside the block may return nil if there
+  is a error raised, and nested calls to convert! and convert_each!
+  may not return values.
+
+  When loading the typecast_params plugin, a subclass of
+  TypecastParams::Params is created specific to the Roda application.
+  You can add support for custom types by passing a block when loading
+  the typecast_params plugin.  This block is executed in the context
+  of the subclass, and calling handle_type in the block can be used to
+  add conversion methods.  handle_type accepts a type name and the
+  block used to convert the type:
+
+    plugin :typecast_params do
+      handle_type(:album) do |value|
+        if id = convert_pos_int(val)
+          Album[id]
+        end
+      end
+    end
+
+  By default, the typecast_params conversion procs are passed the
+  parameter value directly from request.params without modification.
+  In some cases, it may be beneficial to strip leading and trailing
+  whitespace from parameter string values before processing, which
+  you can do by passing the strip: :all> option when loading the
+  plugin.
+
+  By design, typecast_params only deals with string keys, it is not
+  possible to use symbol keys as arguments to the conversion methods
+  and have them converted.

data/lib/roda/plugins/class_matchers.rb

@@ -28,7 +28,7 @@ class Roda
     # This is useful to DRY up code if you are using the same type of pattern and
     # type conversion in multiple places in your application.
     #
-    # This plugin does not work with the params capturing plugin, as it does not
+    # This plugin does not work with the params_capturing plugin, as it does not
     # offer the ability to associate block arguments with named keys.
     module ClassMatchers
       module ClassMethods

data/lib/roda/plugins/indifferent_params.rb

@@ -6,7 +6,14 @@ class Roda
     # The indifferent_params plugin adds a +params+ instance
     # method which offers indifferent access to the request
     # params, allowing you to use symbols to lookup values in
-    # a hash where the keys are strings.  Example:
+    # a hash where the keys are strings.  Note that while this
+    # allows for an easier transition from some other ruby frameworks,
+    # it is a bad idea in general as it makes it more difficult to
+    # separate external data from internal data, and doesn't handle
+    # any typecasting of the data.  Consider using the typecast_params
+    # plugin instead of this plugin for accessing parameters.
+    #
+    # Example:
     #
     #   plugin :indifferent_params
     #

data/lib/roda/plugins/param_matchers.rb

@@ -9,7 +9,7 @@ class Roda
     # It adds a :param matcher for matching on any param with the
     # same name, yielding the value of the param:
     #
-    #   r.on param: 'foo' do |value|
+    #   r.on param: 'foo' do |foo|
     #     # Matches '?foo=bar', '?foo='
     #     # Doesn't match '?bar=foo'
     #   end
@@ -17,7 +17,7 @@ class Roda
     # It adds a :param! matcher for matching on any non-empty param
     # with the same name, yielding the value of the param:
     #
-    #   r.on(param!: 'foo') do |value|
+    #   r.on(param!: 'foo') do |foo|
     #     # Matches '?foo=bar'
     #     # Doesn't match '?foo=', '?bar=foo'
     #   end
@@ -25,16 +25,23 @@ class Roda
     # It also adds :params and :params! matchers, for matching multiple
     # params at the same time:
     #
-    #   r.on params: ['foo', 'baz'] do |value|
+    #   r.on params: ['foo', 'baz'] do |foo, baz|
     #     # Matches '?foo=bar&baz=quuz', '?foo=&baz='
     #     # Doesn't match '?foo=bar', '?baz='
     #   end
     #
-    #   r.on params!: ['foo', 'baz'] do |value|
+    #   r.on params!: ['foo', 'baz'] do |foo, baz|
     #     # Matches '?foo=bar&baz=quuz'
     #     # Doesn't match '?foo=bar', '?baz=', '?foo=&baz=', '?foo=bar&baz='
     #   end
     #
+    # Because users have some control over the types of submitted parameters,
+    # it is recommended that you explicitly force the correct type for values
+    # yielded by the block:
+    #
+    #   r.get(:param=>'foo') do |foo|
+    #     foo = foo.to_s
+    #   end
     module ParamMatchers
       module RequestMethods
         # Match the given parameter if present, even if the parameter is empty.

data/lib/roda/plugins/path.rb

@@ -32,8 +32,11 @@ class Roda
     #     end
     #
     #     r.post 'bar' do
-    #       bar = Bar.create(r.params['bar'])
-    #       r.redirect bar_path(bar) # /bar/1
+    #       bar_params = r.params['bar']
+    #       if bar_params.is_a?(Hash)
+    #         bar = Bar.create(bar_params)
+    #         r.redirect bar_path(bar) # /bar/1
+    #       end
     #     end
     #
     #     r.post 'baz' do

data/lib/roda/plugins/symbol_status.rb

@@ -7,10 +7,10 @@ class Roda
     # the default behaviour is used.
     #
     # Examples:
-    #   r.is "needs_authorization"
+    #   r.is "needs_authorization" do
     #     response.status = :unauthorized
     #   end
-    #   r.is "nothing"
+    #   r.is "nothing" do
     #     response.status = :no_content
     #   end
     #