roda 3.109.0 → 3.110.0

data/lib/roda/plugins/content_security_policy.rb

@@ -41,7 +41,7 @@ class Roda
     #   end
     #
     # The following methods are available for configuring the content security policy,
-    # which specify the setting (substituting _ with -): 
+    # which specify the setting (substituting +_+ with +-+): 
     #
     # * base_uri
     # * child_src
@@ -92,7 +92,7 @@ class Roda
     #   content_security_policy.get_script_src
     #   # => [:self, :unsafe_eval, 'example.com', [:nonce, 'foobarbaz']]
     #
-    # The clear method can be used to remove all settings from the policy. Empty policies
+    # The +clear+ method can be used to remove all settings from the policy. Empty policies
     # do not set any headers. You can use +response.skip_content_security_policy!+ to skip
     # setting a policy.  This is faster than calling +content_security_policy.clear+, since
     # it does not duplicate the default policy.
@@ -115,7 +115,7 @@ class Roda
 
       # Represents a content security policy.
       class Policy
-        '
+        %w'
         base-uri
         child-src
         connect-src
@@ -136,7 +136,7 @@ class Roda
         script-src
         style-src
         worker-src
-        '.split.each(&:freeze).each do |setting|
+        '.each(&:freeze).each do |setting|
           meth = setting.tr('-', '_').freeze
 
           # Setting method name sets the setting value, or removes it if no args are given.
@@ -153,9 +153,12 @@ class Roda
           # are given.
           define_method("add_#{meth}") do |*args|
             unless args.empty?
-              @opts[setting] ||= EMPTY_ARRAY
-              @opts[setting] += args
-              @opts[setting].freeze
+              if @opts[setting]
+                @opts[setting] += args
+                @opts[setting].freeze
+              else
+                @opts[setting] = args.freeze
+              end
             end
             nil
           end
@@ -187,16 +190,13 @@ class Roda
           end
         end
 
-        def initialize
-          clear
-        end
-
         # Clear all settings, useful to remove any inherited settings.
         def clear
           @opts = {}
           @report_only = nil
           @header_value = nil
         end
+        alias initialize clear
 
         # Do not allow future modifications to any settings.
         def freeze
@@ -276,7 +276,6 @@ class Roda
         end
       end
 
-
       # Yield the current Content Security Policy to the block.
       def self.configure(app)
         policy = app.opts[:content_security_policy] = if policy = app.opts[:content_security_policy]

data/lib/roda/plugins/cookie_flags.rb

@@ -60,7 +60,11 @@ class Roda
       class Error < RodaError
       end
 
+      Config = Struct.new(*DEFAULTS.keys, :same_site_string)
+      private_constant :Config
+
       def self.configure(app, opts=OPTS)
+        RodaPlugins.check_supported_opts("the cookie_flags plugin", opts, DEFAULTS.keys)
         previous = app.cookie_flags || DEFAULTS
         opts = app.opts[:cookie_flags] = previous.merge(opts)
 
@@ -72,24 +76,26 @@ class Roda
         end
 
         opts.freeze
+        app.opts[:cookie_flags_config] = Config.new(*opts.values_at(*Config.members)).freeze
       end
 
       module ClassMethods
         RodaPlugins.opt_attr_reader(self, :cookie_flags)
+        RodaPlugins.opt_attr_reader(self, :cookie_flags_config)
       end
 
       module InstanceMethods
         private
 
         def _handle_cookie_flags_array(cookies)
-          opts = self.class.cookie_flags
-          needs_secure = opts[:secure]
-          needs_httponly = opts[:httponly]
-          if needs_same_site = opts[:same_site]
-            same_site_string = opts[:same_site_string]
+          opts = self.class.cookie_flags_config
+          needs_secure = opts.secure
+          needs_httponly = opts.httponly
+          if needs_same_site = opts.same_site
+            same_site_string = opts.same_site_string
             same_site_regexp = /;\s*samesite\s*=\s*(\S+)\s*(?:\z|;)/i
           end
-          action = opts[:action]
+          action = opts.action
 
           cookies.map do |cookie|
             if needs_secure

data/lib/roda/plugins/cookies.rb

@@ -19,8 +19,8 @@ class Roda
     #   plugin :cookies, domain: 'example.com', path: '/api'
     module Cookies
       # Allow setting default cookie options when loading the cookies plugin.
-      def self.configure(app, opts={})
-        app.opts[:cookies_opts] = (app.cookies_opts||{}).merge(opts).freeze
+      def self.configure(app, opts=OPTS)
+        app.opts[:cookies_opts] = (app.cookies_opts||OPTS).merge(opts).freeze
       end
 
       module ClassMethods
@@ -28,15 +28,17 @@ class Roda
       end
 
       module ResponseMethods
-        # Modify the headers to include a Set-Cookie value that
+        # Modify the headers to include a <tt>Set-Cookie</tt> value that
         # deletes the cookie.  A value hash can be provided to
         # override the default one used to delete the cookie.
         # Example:
         #
         #   response.delete_cookie('foo')
         #   response.delete_cookie('foo', domain: 'example.org')
-        def delete_cookie(key, value = {})
-          ::Rack::Utils.delete_cookie_header!(@headers, key, roda_class.cookies_opts.merge(value))
+        def delete_cookie(key, value = OPTS)
+          opts = roda_class.cookies_opts
+          value = value.empty? ? opts : opts.merge(value)
+          ::Rack::Utils.delete_cookie_header!(@headers, key, value)
         end
 
         # Set the cookie with the given key in the headers.

data/lib/roda/plugins/csrf.rb

@@ -1,11 +1,12 @@
 # frozen-string-literal: true
 
-# RODA4: Remove plugin
 
 require 'rack/csrf'
 
 class Roda
   module RodaPlugins
+    warn("The csrf plugin is deprecated and will be removed in Roda 4. Switch to the route_csrf or sec_fetch_site_csrf plugin, or use the Rack::Csrf middleware directly.", uplevel: 1)
+
     # This plugin is no longer recommended for use, it exists only for
     # backwards compatibility.  Consider using the route_csrf plugin
     # instead, as that provides stronger CSRF protection.

data/lib/roda/plugins/custom_block_results.rb

@@ -5,12 +5,11 @@ class Roda
   module RodaPlugins
     # The custom_block_results plugin allows you to specify handling
     # for different block results.  By default, Roda only supports
-    # nil, false, and string block results, but using this plugin,
+    # +nil+, +false+, and string block results, but using this plugin,
     # you can support other block results.
     #
-    # For example, if you wanted to support returning Integer
-    # block results, and have them set the response status code,
-    # you could do:
+    # For example, if you wanted to support Integer block results, and
+    # have the integer set the response status code, you could do:
     #
     #   plugin :custom_block_results
     #
@@ -23,12 +22,12 @@ class Roda
     #   end
     #
     # The expected use case for this is to customize behavior by
-    # class, but matching uses ===, so it is possible to use non-class
-    # objects that respond to === appropriately.
+    # class, but matching uses <tt>===</tt>, so it is possible to use non-class
+    # objects that respond to <tt>===</tt> appropriately.
     #
     # Note that custom block result handling only occurs if the types
     # are not handled by Roda itself.  You cannot use this to modify
-    # the handling of nil, false, or string results.  Additionally,
+    # the handling of +nil+, +false+, or string results.  Additionally,
     # if the response body has already been written to before the the
     # route block exits, then the result of the block is ignored,
     # and the related +handle_block_result+ block will not be called

data/lib/roda/plugins/default_headers.rb

@@ -4,7 +4,7 @@
 class Roda
   module RodaPlugins
     # The default_headers plugin accepts a hash of headers,
-    # and overrides the default_headers method in the
+    # and overrides the +default_headers+ method in the
     # response class to be a copy of the headers.
     #
     # Note that when using this module, you should not
@@ -22,7 +22,7 @@ class Roda
     #   plugin :default_headers, 'Bar'=>'baz'
     module DefaultHeaders
       # Merge the given headers into the existing default headers, if any.
-      def self.configure(app, headers={})
+      def self.configure(app, headers=OPTS)
         app.opts[:default_headers] = (app.default_headers || app::RodaResponse::DEFAULT_HEADERS).merge(headers).freeze
       end 
 

data/lib/roda/plugins/delay_build.rb

@@ -3,7 +3,7 @@
 #
 class Roda
   module RodaPlugins
-    warn("The delay_build plugin no longer has an effect. It will be removed in Roda 4.")
+    warn("The delay_build plugin no longer has an effect. It will be removed in Roda 4.", uplevel: 1)
 
     module DelayBuild
       module ClassMethods

data/lib/roda/plugins/delegate.rb

@@ -5,10 +5,10 @@ class Roda
   module RodaPlugins
     # The delegate plugin allows you to easily setup instance methods in
     # the scope of the route block that call methods on the related
-    # request, response, or class which may offer a simpler API in some cases.
+    # request, response, or class, which may offer a simpler API in some cases.
     # Roda doesn't automatically setup such delegate methods because
-    # it pollutes the application's method namespace, but this plugin
-    # allows the user to do so.
+    # it pollutes the application's method namespace, and doing so should be
+    # the user's choice.
     #
     # Here's an example based on the README's initial example, using the
     # request_delegate method to simplify the DSL:
@@ -49,26 +49,27 @@ class Roda
     #   end
     module Delegate
       module ClassMethods
-        # Delegate the given methods to the class
+        # Delegate the given instance methods to the class
         def class_delegate(*meths)
           meths.each do |meth|
             define_method(meth){|*a, &block| self.class.public_send(meth, *a, &block)}
           end
         end
 
-        # Delegate the given methods to the request
+        # Delegate the given instance methods to the request
         def request_delegate(*meths)
           meths.each do |meth|
             define_method(meth){|*a, &block| @_request.public_send(meth, *a, &block)}
           end
         end
 
-        # Delegate the given methods to the response
+        # Delegate the given instance methods to the response
         def response_delegate(*meths)
           meths.each do |meth|
             define_method(meth){|*a, &block| @_response.public_send(meth, *a, &block)}
           end
         end
+        # RODA4: Switch the above calls to ...
       end
     end
 

data/lib/roda/plugins/direct_call.rb

@@ -7,6 +7,11 @@ class Roda
     # (app.call will still call the middleware).
     # This can be used as an optimization, as the Roda class itself can be used
     # as the callable, which is faster than using a lambda.
+    #
+    # This plugin is used automatically by Roda when freezing an app, if Roda
+    # determines that doing so is safe (where there is no middleware). However,
+    # it can be used manually for unfrozen apps, or in cases where middleware
+    # is used.
     module DirectCall
       def self.configure(app)
         app.send(:build_rack_app)
@@ -35,4 +40,3 @@ class Roda
     register_plugin(:direct_call, DirectCall)
   end
 end
-

data/lib/roda/plugins/disallow_file_uploads.rb

@@ -12,7 +12,7 @@ class Roda
     #
     #   plugin :disallow_file_uploads
     #
-    # This plugin is only supported on Rack 1.6+.  This plugin does not technically
+    # This plugin is supported on Rack 1.6+.  This plugin does not technically
     # block users from uploading files, it only blocks the parsing of request bodies containing
     # multipart file uploads.  So if you do not call +r.POST+ (or something that calls it such as
     # +r.params+), then Roda will not attempt to parse the request body, and an exception will not
@@ -24,7 +24,7 @@ class Roda
       NO_TEMPFILE = lambda{|_,_| raise Error, "Support for uploading files has been disabled"}
 
       module RequestMethods
-        # HTML escape the input and return the escaped version.
+        # Raise an error if there is an attempt to use a tempfile.
         def initialize(_, env)
           env['rack.multipart.tempfile_factory'] = NO_TEMPFILE
           super
@@ -35,4 +35,3 @@ class Roda
     register_plugin(:disallow_file_uploads, DisallowFileUploads)
   end
 end
-

data/lib/roda/plugins/drop_body.rb

@@ -4,9 +4,9 @@
 class Roda
   module RodaPlugins
     # The drop_body plugin automatically drops the body and
-    # Content-Type/Content-Length headers from the response if
+    # +Content-Type+/+Content-Length+ headers from the response if
     # the response status indicates that the response should
-    # not include a body (response statuses 100, 101, 102, 204,
+    # not include a body (response statuses 100-199, 204,
     # and 304).  For response status 205, the body and Content-Type
     # headers are dropped, but the Content-length header is set to
     # '0' instead of being dropped.
@@ -15,16 +15,13 @@ class Roda
         DROP_BODY_STATUSES = [100, 101, 102, 204, 205, 304].freeze
         RodaPlugins.deprecate_constant(self, :DROP_BODY_STATUSES)
 
-        DROP_BODY_RANGE = 100..199
-        private_constant :DROP_BODY_RANGE
-
         # If the response status indicates a body should not be
         # returned, use an empty body and remove the Content-Length
         # and Content-Type headers.
         def finish
           r = super
           case r[0]
-          when DROP_BODY_RANGE, 204, 304
+          when 100..199, 204, 304
             r[2] = EMPTY_ARRAY
             h = r[1]
             h.delete(RodaResponseHeaders::CONTENT_LENGTH)

data/lib/roda/plugins/each_part.rb

@@ -3,8 +3,8 @@
 #
 class Roda
   module RodaPlugins
-    # The each_part plugin adds an each_part method, which is a
-    # render_each-like method that treats all keywords as locals.
+    # The each_part plugin adds an +each_part+ method, which is similar to
+    # +render_each+, but treats all keywords as locals.
     #
     #   # Can replace this:
     #   render_each(enum, :template, locals: {foo: 'bar'})
@@ -15,7 +15,7 @@ class Roda
     # On Ruby 2.7+, the part method takes a keyword splat, so you
     # must pass keywords and not a positional hash for the locals.
     #
-    # If you are using the :assume_fixed_locals render plugin option,
+    # If you are using the +:assume_fixed_locals+ render plugin option,
     # template caching is enabled, you are using Ruby 3+, and you
     # are freezing your Roda application, in addition to providing a
     # simpler API, this also provides a performance improvement.
@@ -51,9 +51,7 @@ class Roda
       end
 
       module AssumeFixedLocalsInstanceMethods
-        # simplecov:disable
-        if RUBY_VERSION >= '3.0'
-        # simplecov:enable
+        if RUBY_VERSION >= '3.0' # simplecov:disable
           def each_part(enum, template, **locals, &block)
             if optimized_method = _cached_render_each_template_method(template)
               optimized_method = optimized_method[0]

data/lib/roda/plugins/early_hints.rb

@@ -3,14 +3,14 @@
 #
 class Roda
   module RodaPlugins
-    # The early_hints plugin allows sending 103 Early Hints responses
-    # using the rack.early_hints environment variable.
+    # The early_hints plugin adds the +send_early_hints+ method for sending
+    # 103 Early Hints responses using the +rack.early_hints+ environment variable.
     # Early hints allow clients to preload necessary files before receiving
     # the response.
     module EarlyHints
       module InstanceMethods
-        # Send given hash of Early Hints using the rack.early_hints environment variable,
-        # currenly only supported by puma.  hash given should generally have the single
+        # Send given hash of Early Hints using the +rack.early_hints+ environment variable,
+        # currenly supported by puma and falcon.  hash given should generally have the single
         # key 'Link', and a string or array of strings for each of the early hints.
         def send_early_hints(hash)
           if eh_proc = env['rack.early_hints']

data/lib/roda/plugins/empty_root.rb

@@ -3,10 +3,10 @@
 #
 class Roda
   module RodaPlugins
-    # The empty_root plugin makes +r.root+ match both on +/+ and
-    # on the empty string.  This is mostly useful when using multiple
-    # rack applications, where the initial PATH_INFO has been moved
-    # to SCRIPT_NAME.  For example, if you have the following
+    # The empty_root plugin makes +r.root+ match both +/+ and
+    # the empty string.  This is mostly useful when using multiple
+    # rack applications, where the initial +PATH_INFO+ has been moved
+    # to +SCRIPT_NAME+.  For example, if you have the following
     # applications:
     #
     #   class App1 < Roda
@@ -28,7 +28,7 @@ class Roda
     # Then requests for both +/albums/+ and +/albums+ will return
     # "root".  Without this plugin loaded into App2, only requests
     # for +/albums/+ will return "root", since by default, +r.root+
-    # matches only when the current PATH_INFO is +/+ and not when
+    # matches only when the current +PATH_INFO+ is +/+ and not when
     # it is empty.
     module EmptyRoot
       module RequestMethods

data/lib/roda/plugins/environments.rb

@@ -3,10 +3,10 @@
 #
 class Roda
   module RodaPlugins
-    # The environments plugin adds a environment class accessor to get
-    # the environment for the application, 3 predicate class methods
-    # to check for the current environment (development?, test? and
-    # production?), and a class configure method that takes environment(s)
+    # The environments plugin adds a +environment+ class accessor to get
+    # the environment for the application, predicate class methods
+    # to check for the current environment (+development?+, +test?+ and
+    # +production?+), and a class +configure+ method that takes environment(s)
     # and yields to the block if the given environment(s) match the
     # current environment.
     #
@@ -40,8 +40,8 @@ class Roda
     #     end
     #   end
     module Environments
-      # Set the environment to use for the app.  Default to ENV['RACK_ENV']
-      # if no environment is given.  If ENV['RACK_ENV'] is not set and
+      # Set the environment to use for the app.  Default to <tt>ENV['RACK_ENV']</tt>
+      # if no environment is given.  If <tt>ENV['RACK_ENV']</tt> is not set and
       # no environment is given, assume the development environment.
       def self.configure(app, env=ENV["RACK_ENV"])
         app.opts[:environment] = (env || 'development').to_sym
@@ -53,13 +53,13 @@ class Roda
         # If no environments are given or one of the given environments
         # matches the current environment, yield the receiver to the block.
         def configure(*envs)
-          if envs.empty? || envs.any?{|s| s == environment}
+          if envs.empty? || envs.include?(environment)
             yield self
           end
         end
 
         # Override the environment for the application, instead of using
-        # RACK_ENV.
+        # <tt>ENV['RACK_ENV']</tt>.
         def environment=(v)
           opts[:environment] = v
         end

data/lib/roda/plugins/erb_h.rb

@@ -12,9 +12,9 @@ class Roda
     #
     # To make sure that this speeds up applications using the h
     # plugin, this depends on the h plugin, and overrides the
-    # h method.
+    # +h+ method.
     #
-    # The following example will return "<foo>" as the body.
+    # The following example will return <tt>"&lt;foo&gt;"</tt> as the body.
     #
     #   plugin :erb_h
     #
@@ -25,8 +25,8 @@ class Roda
     # The faster performance offered by the erb_h plugin is due
     # to erb/escape avoiding allocations if not needed (returning the
     # input object if no escaping is needed).  That behavior change
-    # can cause problems if you mutate the result of the h method
-    # (which can mutate the input), or mutate the input of the h
+    # can cause problems if you mutate the result of the +h+ method
+    # (which can mutate the input), or mutate the input of the +h+
     # method after calling it (which can mutate the result).
     module ErbH
       def self.load_dependencies(app)

data/lib/roda/plugins/error_email.rb

@@ -5,8 +5,8 @@ require 'net/smtp'
 class Roda
   module RodaPlugins
     # The error_email plugin adds an +error_email+ instance method that
-    # send an email related to the exception.  This is most useful if you are
-    # also using the error_handler plugin:
+    # sends an email related to the exception.  This is designed for use in
+    # combination with the error_handler plugin:
     #
     #   plugin :error_email, to: 'to@example.com', from: 'from@example.com'
     #   plugin :error_handler do |e|
@@ -16,19 +16,19 @@ class Roda
     #
     # It is similar to the error_mail plugin, except that it uses net/smtp
     # directly instead of using the mail library.  If you are not already using the
-    # mail library in your application, it makes sense to use error_email
-    # instead of error_mail.
+    # mail library in your application, using error_email may be preferable over
+    # error_mail in terms of limiting the number of dependencies.
     #
     # Options:
     #
-    # :filter :: Callable called with the key and value for each parameter, environment
-    #            variable, and session value.  If it returns true, the value of the
-    #            parameter is filtered in the email.
-    # :from :: The From address to use in the email (required)
-    # :headers :: A hash of additional headers to use in the email (default: empty hash)
-    # :host :: The SMTP server to use to send the email (default: localhost)
-    # :prefix :: A prefix to use in the email's subject line (default: no prefix)
-    # :to :: The To address to use in the email (required)
+    # +:filter+ :: Callable called with the key and value for each parameter, environment
+    #              variable, and session value.  If it returns true, the value of the
+    #              parameter is filtered in the email.
+    # +:from+ :: The From address to use in the email (required)
+    # +:headers+ :: A hash of additional headers to use in the email (default: empty hash)
+    # +:host+ :: The SMTP server to use to send the email (default: localhost)
+    # +:prefix+ :: A prefix to use in the email's subject line (default: no prefix)
+    # +:to+ :: The To address to use in the email (required)
     #
     # The subject of the error email shows the exception class and message.
     # The body of the error email shows the backtrace of the error and the
@@ -111,17 +111,16 @@ END
         end
       }.freeze
 
-      # Set default opts for plugin.  See ErrorEmail module RDoc for options.
       def self.configure(app, opts=OPTS)
+        RodaPlugins.check_supported_opts("the error_email plugin", opts, [*DEFAULTS.keys, :prefix, :to, :from])
+
         email_opts = app.opts[:error_email] ||= DEFAULTS
         email_opts = email_opts.merge(opts)
-        email_opts[:headers] = email_opts[:headers].dup
+        email_opts[:headers] = email_opts[:headers].dup.freeze
         unless email_opts[:to] && email_opts[:from]
           raise RodaError, "must provide :to and :from options to error_email plugin"
         end
-        app.opts[:error_email] = email_opts
-        app.error_email_opts[:headers].freeze
-        app.error_email_opts.freeze
+        app.opts[:error_email] = email_opts.freeze
       end
 
       module ClassMethods