roda 3.83.0 → 3.84.0

data/doc/release_notes/3.29.0.txt

@@ -1,15 +0,0 @@
-= Improvements
-
-* The common_logger plugin now includes the SCRIPT_NAME when
-  logging, for greater compatibility with typical web server
-  logs.
-
-* The exception_page plugin now handles invalid POST data.
-  Previously, invalid POST data would cause the exception page
-  display to raise an exception.
-
-* An error is now raised if trying to load a plugin that is not a
-  module or a recognized plugin symbol.
-
-* Specs and older release notes are no longer shipped in the
-  gem, reducing gem size by over 35%.

data/doc/release_notes/3.3.0.txt

@@ -1,291 +0,0 @@
-= 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#param_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/doc/release_notes/3.30.0.txt

@@ -1,14 +0,0 @@
-= New Features
-
-* A :relative_paths plugin option has been added to the assets
-  plugin.  This option makes the paths to the asset files in the
-  link and script tags relative paths instead of absolute paths.
-
-= Other Improvements
-
-* The :header matcher in the header_matchers plugin now works
-  correctly for the Content-Type and Content-Length headers, which
-  are not prefixed with HTTP_ in the rack environment.
-
-* The run_append_slash and run_handler plugins now work correctly
-  when used together.

data/doc/release_notes/3.31.0.txt

@@ -1,11 +0,0 @@
-= New Features
-
-* A relative_path plugin has been added, adding a relative_path
-  method that will take an absolute path and make it relative to the
-  current request by prepending an appropriate prefix.  This is
-  helpful when using Roda as a static site generator to generate a
-  site that can be hosted at any subpath or directly from the
-  filesystem.
-
-* In the path plugin, the path method now accepts a :relative
-  option for generating relative paths instead of absolute paths.

data/doc/release_notes/3.32.0.txt

@@ -1,42 +0,0 @@
-= New Features
-
-* render_each in the render_each plugin now automatically handles
-  template names with subdirectories and extensions.  Previously, these
-  caused issues unless the :local option was provided.  So now you
-  can use:
-
-    render_each(foos, "items/foo")
-
-  instead of:
-
-    render_each(foos, "items/foo", :local=>:foo)
-
-* each_partial has been added to the partials plugin.  It operates
-  similarly to render_each, but uses the convention for partial
-  template naming.  So this:
-
-    each_partial(foos, "items/foo")
-
-  is the same as:
-
-    render_each(foos, "items/_foo", :local=>:foo)
-
-= Other Improvements
-
-* The :dependencies option in the assets plugin now works correctly
-  with compiled templates in the render plugin in uncached mode
-  (the default in development).  Previously, modifying a dependency
-  file would not result in recompiling the asset template when
-  requesting the main file.
-
-* Method visibility issues in the following plugins have been fixed:
-
-  * content_security_policy
-  * default_headers
-  * indifferent_params
-  * placeholder_string_matchers
-  * symbol_matchers
-
-  Previously, these plugins made private methods public by mistake
-  when overriding them.  Additionally, Roda.freeze no longer changes
-  the visibility of the set_default_headers private method.

data/doc/release_notes/3.33.0.txt

@@ -1,8 +0,0 @@
-= New Features
-
-* The path plugin now supports a url method, allowing for returning
-  the entire URL instead of just the path for class-based paths.
-
-* The public plugin now supports a :brotli option that will directly
-  serve brotli-compressed files (with .br extension) similar to how the
-  :gzip option directly serves gzipped files (with the .gz extension).

data/doc/release_notes/3.34.0.txt

@@ -1,17 +0,0 @@
-= Improvements
-
-* Multiple unneeded conditionals have been removed.
-
-* pre_content and post_context sections in backtraces are no longer
-  included in the exception_page plugin output if they would be
-  empty.
-
-* The match_affix plugin can be loaded again with a single argument.
-  It was originally designed to accept a single argument, but a bug
-  introduced in 2.29.0 made it require two arguments.
-
-* Core Roda and all plugins that ship with Roda now have 100% branch
-  coverage.
-
-* The sinatra_helpers plugin no longer emits statement not reached
-  warnings in verbose mode.

data/doc/release_notes/3.35.0.txt

@@ -1,12 +0,0 @@
-= New Features
-
-* An r plugin has been added.  This plugin adds an r method for the
-  request, useful for allowing the use of r.halt and r.redirect even
-  in methods where the r local variable is not in scope.
-
-= Other Improvements
-
-* Attempting to load a plugin with an argument or block when the plugin
-  does not accept arguments or a block now warns.  This is because a
-  future update to support a block or an optional argument could break
-  the call.

data/doc/release_notes/3.36.0.txt

@@ -1,17 +0,0 @@
-= New Features
-
-* A multi_public plugin has been added, which allows serving static
-  files from multiple separate directories.  This is especially
-  useful when there are different access control requirements per
-  directory.
-  
-* The content_security_policy now supports a
-  content_security_policy.report_to method to set the
-  report-to directive.
-
-= Other Improvements
-
-* When using the type_routing plugin and performing type routing
-  using the Accept request header, the Vary response header will be
-  added or updated so that http caches do not cache a response for one
-  type and serve it for a different type.

data/doc/release_notes/3.37.0.txt

@@ -1,42 +0,0 @@
-= New Features
-
-* A custom_matchers plugin has been added, which allows using
-  arbitrary objects as matchers, as long as the matcher has been
-  registered.  You can register matchers using the custom_matcher
-  class method, which takes the class of the matcher, and a block
-  which is yielded the matcher object.  The block should return
-  nil or false if the matcher doesn't match, and any other value
-  if the matcher does match.  Example:
-
-    plugin :custom_matchers
-    method_segment = Struct.new(:request_method, :next_segment)
-    custom_matcher(method_segment) do |matcher|
-      # self is the request instance ("r" yielded in the route block below)
-      if matcher.request_method == self.request_method
-        match(matcher.next_segment)
-      end
-    end
- 
-    get_foo = method_segment.new('GET', 'foo')
-    post_any = method_segment.new('POST', String)
-    route do |r|
-      r.on('baz') do
-        r.on(get_foo) do
-          # GET method, /baz/foo prefix
-        end
- 
-        r.is(post_any) do |seg|
-          # for POST /baz/bar, seg is "bar"
-        end
-      end
- 
-      r.on('quux') do
-        r.is(get_foo) do
-          # GET method, /quux/foo route
-        end
- 
-        r.on(post_any) do |seg|
-          # for POST /quux/xyz, seg is "xyz"
-        end
-      end
-    end

data/doc/release_notes/3.38.0.txt

@@ -1,5 +0,0 @@
-= Improvements
-
-* The error_email and error_mail plugins now rescue invalid parameter
-  errors when preparing the email body, because you generally don't
-  want your error handler to raise an exception.

data/doc/release_notes/3.39.0.txt

@@ -1,16 +0,0 @@
-= Improvements
-
-* The relative_path plugin is now faster if you are calling
-  relative_path or relative_prefix more than once when handling a
-  request.
-
-* The typecast_params.convert! method in the typecast_params plugin
-  now handles explicit nil values the same as missing values.
-  Explicit nil values do not generally occur in normal Rack parameter
-  parsing, but they can occur when using the json_parser plugin to
-  parse JSON requests.
-
-* Roda now avoids method redefinition warnings in verbose mode by
-  using a self alias.  As Ruby 3 is dropping uninitialized instance
-  variable warnings, Roda will be verbose warning free if you are
-  using Ruby 3.

data/doc/release_notes/3.4.0.txt

@@ -1,24 +0,0 @@
-= New Features
-
-* A middleware_stack plugin has been added for more detailed control
-  over middleware, allowing for the removal of middleware and the
-  insertion of middleware before existing middleware.  Example:
-
-    plugin :middleware_stack
-
-    # Remove csrf middleware
-    middleware_stack.remove{|m, *args| m == Rack::Csrf}
-
-    # Insert csrf middleware before logger middleware
-    middleware_stack.before{|m, *args| m == Rack::CommonLogger}.
-      use(Rack::Csrf, raise: true)
-
-    # Insert csrf middleware after logger middleware
-    middleware_stack.after{|m, *args| m == Rack::CommonLogger}.
-      use(Rack::Csrf, raise: true)
-
-= Other Improvements
-
-* The head plugin now calls close on the response body if the body
-  responds to close.  Previously an existing response body was
-  just ignored.

data/doc/release_notes/3.40.0.txt

@@ -1,24 +0,0 @@
-= New Features
-
-* A precompile_views method has been added to the
-  precompile_templates plugin.  This method works with Roda's
-  optimized compiled view methods, allowing additional memory
-  sharing between parent and child processes.
-
-* A freeze_template_caches! method has been added to the
-  precompile_templates plugin.  This freezes the template caches,
-  preventing the compilation of additional templates, useful for
-  enforcing that only precompiled templates are used.  Additionally,
-  this speeds up access to the template caches.
-
-* RodaCache#freeze now returns the frozen internal hash, which can
-  then be accessed without a mutex. Previously, freeze only froze
-  the receiver and not the internal hash, so it didn't have the
-  expected effect.
-
-= Other Improvements
-
-* The view method in the render plugin is now faster in most cases
-  when a single argument is used.  When freezing the application,
-  an additional optimization is performed to increase the
-  performance of the view method even further.

data/doc/release_notes/3.41.0.txt

@@ -1,9 +0,0 @@
-= Improvements
-
-* The performance of the render plugin's view method when passed the
-  :content option and no other options or arguments has been improved
-  by about 3x, by calling compiled template methods directly.
-
-* The compiled template method for the layout is cleared when the
-  render plugin is loaded again, which can fix issues when it is
-  loaded with different options that affect the layout.

data/doc/release_notes/3.42.0.txt

@@ -1,21 +0,0 @@
-= New Features
-
-* A recheck_precompiled_assets plugin has been added, which allows
-  for checking for updates to the precompiled asset metadata file,
-  and automatically using the updated data.
-
-* The common_logger plugin now supports a :method plugin option to
-  specify the method to call on the logger.
-
-= Other Improvements
-
-* Plugins and middleware that use keyword arguments are now supported
-  in Ruby 3.
-
-* The compile_assets class method in the assets plugin now uses an
-  atomic approach to writing the precompiled asset metadata file.
-
-* Minor method visibility issues have been fixed.  The custom_matchers
-  plugin no longer makes the unsupported_matcher request method
-  public, and the render plugin no longer makes the _layout_method
-  public when the application is frozen.

data/doc/release_notes/3.43.0.txt

@@ -1,34 +0,0 @@
-= New Features
-
-* A host_authorization plugin has been added to verify the requested
-  Host header is authorized.  Using it can prevent DNS rebinding
-  attacks in cases where the application can receive requests for
-  arbitrary hosts.
-
-  To check for authorized hosts in your routing tree, you call the
-  check_host_authorization! method.  For example, if you want to
-  check for authorized hosts after serving requests for public
-  files, you could do:
-
-    plugin :public
-    plugin :host_authorization, 'my-domain-name.example.com'
-
-    route do |r|
-      r.public
-      check_host_authorized!
-
-      # ... rest of routing tree
-    end
-
-  In addition to handling single domain names via a string, you can
-  provide an array of domain names, a regexp to match again, or a
-  proc.
-  
-  By default, requests using unauthorized hosts receive an empty 403
-  response.  If you would like to customize the response, you can
-  pass a block when loading the plugin:
-
-    plugin :host_authorization, 'my-domain-name.example.com' do |r|
-      response.status = 403
-      "Response Body Here"
-    end

data/doc/release_notes/3.44.0.txt

@@ -1,23 +0,0 @@
-= New Features
-
-* An optimized_segment_matchers plugin has been added that offers
-  very fast matchers for arbitrary segments (the same segments
-  that would be matched by the String class matcher).  The
-  on_segment method it offers accepts no arguments and yields
-  the next segment if there is a segment.  The is_segment method
-  is similar, but only yields if the next segment is the final
-  segment.
-
-= Other Improvements
-
-* The send_file and attachment methods in the sinatra_helpers plugin
-  now support RFC 5987 UTF-8 and ISO-8859-1 encoded filenames,
-  allowing modern browsers to save files with encoded chracters. For
-  older browsers that do not support RFC 5987, unsupported characters
-  in filenames are replaced with dashes.  This is considered to be an
-  improvement over the previous behavior of using Ruby's inspect
-  output for the filename, which could contain backslashes (backslash
-  is not an allowed chracter in Windows filenames).
-
-* The performance of the String class matcher has been slightly
-  improved.

data/doc/release_notes/3.45.0.txt

@@ -1,22 +0,0 @@
-= Improvements
-
-* The typecast_params plugin checks now checks for null bytes by
-  default before typecasting.  If null bytes are present, it raises
-  an error.  Most applications do not require null bytes in
-  parameters, and in some cases allowing them can lead to security
-  issues, especially when parameters are passed to C extensions.
-  In general, the benefit of forbidding null bytes in parameters is
-  greater than the cost.
-  
-  If you would like to continue allowing null bytes, use the
-  :allow_null_bytes option when loading the plugin.
-
-  Note that this change does not affect uploaded files, since those
-  are expected to contain null bytes.
-
-= Backwards Compatibility
-
-* The change to the typecast_params plugin to raise an error for
-  null bytes can break applications that are expecting null bytes
-  to be passed in parameters.  Such applications should use the
-  :allow_null_bytes option when loading the plugin.