roda 3.17.0 → 3.18.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ea47f91d6b930ef7822fef3781ef11f959ace8f9e6a907f24481c5f797678482
-  data.tar.gz: 13b182e1651d996e1493078301888b6671dd91ea0516f441ad1bc59cba940d6d
+  metadata.gz: f39ffb4b00598e7e113f06c2f6e43e968f96b2a447059de8b351c7f5cc35675a
+  data.tar.gz: eacc16913dcfd72ad822fd8b6f25e132be80123c25a6a0c29869b39a13f04b50
 SHA512:
-  metadata.gz: 2bc04891739a93f46839abf14fd915b2f470e835e6c200fa1f8fd8a168cda13406c424fa0e1cc1eee5ce0e1e50b0dfbbe6440d27bec2112a2c6cf3dc83951ffc
-  data.tar.gz: 68a1ec7f9ead2ce2fda252d36c7edf0df3c53d1aa02a246669d8d0700afd65d1a010179be92c1973b9c511386df39e2b7d1fd041228add83d2ef344e9d49a475
+  metadata.gz: 8aec053c2bda39f201cb03043cfe382d5982e5e16abca381ba76220603a25d680425a8aaf4b405f4134caef4336e3586e83d2ae0f43e8c7a40279650927237d3
+  data.tar.gz: 104867afa6a526d13acd76eab634eaf9688f44131606e1c7c67f73f1464c662d16d76938217c0b878deb0d7e6217ae5586fc2764be13cdd64298b5256bd4b3b8

data/CHANGELOG

@@ -1,3 +1,51 @@
+= 3.18.0 (2019-03-15)
+
+* Add direct_call plugin for making Roda.call skip middleware, allowing more optimization when dispatching routes (jeremyevans)
+
+* Improve performance of default_headers plugin by directly defining set_default_headers (jeremyevans)
+
+* Improve performance when freezing app if certain methods have not been overridden (jeremyevans)
+
+* Support :check_arity and :check_dynamic_arity app options for whether/how to check arity for blocks used to define methods (jeremyevans)
+
+* Improve performance of the status_handler plugin by using methods instead of instance_exec (jeremyevans)
+
+* Remove r.static_route method from the static_routing plugin (jeremyevans)
+
+* Improve performance of the static_routing plugin by using methods instead of instance_exec (jeremyevans)
+
+* Add support for the route_block_args plugin to the route_csrf plugin (jeremyevans)
+
+* Improve performance of the route_csrf plugin by using a method instead of instance_exec (jeremyevans)
+
+* Improve performance of the route_block_args plugin by using a method instead of instance_exec (jeremyevans)
+
+* Improve performance of the path plugin by using methods instead of instance_exec (jeremyevans)
+
+* Improve performance of the named_templates plugin by using methods instead of instance_exec (jeremyevans)
+
+* Improve performance of the multi_route plugin by using methods instead of instance_exec (jeremyevans)
+
+* Improve performance of the hooks plugin by using methods instead of instance_exec (jeremyevans)
+
+* Improve performance of the mail_processor plugin by using methods instead of instance_exec (jeremyevans)
+
+* Improve performance of the default_status plugin by directly defining the default_status method (jeremyevans)
+
+* Improve performance of class_level_routing plugin using methods instead of instance_exec (jeremyevans)
+
+* Do not have route_block_args plugin affect class_level_routes plugin (jeremyevans)
+
+* Integrate internal after hook with error_handler plugin (jeremyevans)
+
+* Improve performance of internal before and after hooks (jeremyevans)
+
+* Improve performance by using method instead of instance_exec for main route block (jeremyevans)
+
+* Add Roda.define_roda_method for defining instance methods instead of using instance_exec (jeremyevans)
+
+* Include cookie_options when clearing the cookie (#162, #163) (eiko, jeremyevans)
+
 = 3.17.0 (2019-02-15)
 
 * Improve performance in the common case for RodaResponse#finish (jeremyevans)

data/MIT-LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2014-2018 Jeremy Evans
+Copyright (c) 2014-2019 Jeremy Evans
 Copyright (c) 2010-2014 Michel Martens, Damian Janowski and Cyril David
 Copyright (c) 2008-2009 Christian Neukirchen
 

data/README.rdoc

@@ -103,7 +103,7 @@ The primary way routes are matched in Roda is by calling
 Each of these "routing methods" takes a "match block".
 
 Each routing method takes each of the arguments (called matchers)
-that is given and tries to match it to the current request.
+that are given and tries to match it to the current request.
 If the method is able to match all of the arguments, it yields to the match block;
 otherwise, the block is skipped and execution continues.
 
@@ -592,8 +592,9 @@ with your application code.  Some of the things Roda does:
   are <tt>@_request</tt> and <tt>@_response</tt>.  All instance variables in the
   scope of the +route+ block used by plugins that ship with Roda are prefixed
   with an underscore.
-- The only methods defined (beyond the default methods for +Object+) are:
-  +call+, +env+, +opts+, +request+, +response+, and +session+.
+- The main methods defined, beyond the default methods for +Object+, are
+  +env+, +opts+, +request+, +response+, and +session+.  +call+ and +_call+ are also
+  defined, but are deprecated.  All other methods defined are prefixed with +_roda_+
 - Constants inside the Roda namespace are all prefixed with +Roda+
   (e.g., <tt>Roda::RodaRequest</tt>).
 
@@ -698,6 +699,23 @@ The following options are respected by the default library or multiple plugins:
 
 :add_script_name :: Prepend the SCRIPT_NAME for the request to paths.  This is
                     useful if you mount the app as a path under another app.
+:check_arity :: Whether arity for blocks passed to Roda should be checked
+                to determine if they can be used directly to define methods
+                or need to be wrapped. By default, for backwards compatibility,
+                this is true, so Roda will check blocks and handle cases where
+                the arity of the block does not match the expected arity.  This
+                can be set to +:warn+ to issue warnings whenever Roda detects an
+                arity mismatch.  If set to +false+, Roda does not check the arity
+                of blocks, which can result in failures at runtime if the arity
+                of the block does not match what Roda expects.  Note that Roda
+                does not check the arity for lambda blocks, as those are strict
+                by default.
+:check_dynamic_arity :: Similar to :check_arity, but used for checking blocks
+                        where the number of arguments Roda will call the blocks
+                        with is not possible to determine when defining the
+                        method.  By default, Roda checks arity for such methods,
+                        but doing so actually slows the method down even if the
+                        number of arguments matches the expected number of arguments.
 :freeze_middleware :: Whether to freeze all middleware when building the rack app.
 :json_parser :: A callable for parsing JSON (+JSON.parse+ in general used by
                 default).
@@ -831,7 +849,7 @@ but before handling other requests:
 
 The easiest way to prevent XSS with Roda is to use a template library
 that automatically escapes output by default.
-The +:escape+ option to the +render+ plugin sets the ERb template processor
+The +:escape+ option to the +render+ plugin sets the ERB template processor
 to escape by default, so that in your templates:
 
   <%= '<>' %>  # outputs &lt;&gt; 

data/doc/release_notes/3.18.0.txt

@@ -0,0 +1,170 @@
+= New Features
+
+* A direct_call plugin has been added.  This plugin makes Roda.call
+  call the app directly, skipping any middleware.  This plugin
+  can be used for performance reasons, as the class itself can be
+  used as the base rack app, instead of using a lambda as the base
+  rack app.  Roda.app.call will still call all middleware when
+  using this plugin.
+
+= Other Improvements
+
+* Blocks that are given during application configuration, and
+  previously executed with instance_exec, instead now define methods,
+  and Roda now calls these methods. This is a much faster approach.
+  This new approach, combined with the direct_call plugin and the
+  Roda.freeze optimizations, can be over 80% faster for trivial
+  applications, with measureable improvements in most applications.
+
+  As methods are strict in regards to arity and instance_exec is
+  not, Roda now checks all such blocks for arity mismatches, and
+  attempts to compensate for arity mismatches.  In case of an arity
+  mismatch, Roda will define a method that will call instance_exec,
+  in which case there will not be a performance improvement.
+
+  For some methods, Roda may not know the expected arity until
+  runtime.  In that case, Roda will check the arity at runtime and
+  try to call the method with the arity that it supports if there is
+  an arity mismatch.
+
+  You can control the checking of arity via two options:
+
+  :check_arity :: Set to false to turn off all arity checking. Set to
+                  :warn to issue a warning when defining the method if
+                  there is an arity mismatch (for methods where the
+                  expected arity is known in advance).
+  :check_dynamic_arity :: Set to false to turn off arity checking for
+                          methods defined where the arity is not known
+                          at compile time.  Set to :warn to issue a
+                          warning at runtime every time the method is
+                          called and there is an arity mismatch (for
+                          methods where the expected arity is not
+                          known in advance).  Note that checking the
+                          arity at runtime has a performance cost,
+                          so for maximum performance this should be
+                          set to false.
+
+  Note that this arity checking is only done to keep backwards
+  compatibility.  Since lambdas already used strict arity, no arity
+  checking is done if the block is a lambda and not a regular proc.
+
+  Roda has a new dispatch API that works with these defined methods.
+  The new dispatch API uses the following methods:
+
+  * _roda_handle_main_route: Entry point for normal request dispatch.
+  * _roda_handle_route: Yields to the routing block, catching any
+    halts inside the block, treating the block as a routing block.
+  * _roda_main_route: Roda.route defines this method using the
+    block provided, it accepts the request as an argument.
+  * _roda_run_main_route: Calls _roda_main_route with the request,
+    allowing for plugins to execute code around the main routing,
+    while still being able to throw :halt to return a response.
+
+  All instance methods defined by Roda use the _roda_ prefix.
+
+* When deleting the session cookie in the sessions plugin, the
+  Set-Cookie response header now uses the same path and domain 
+  that was originally used to set the cookie.  This can fix cases
+  where the cookie was not being cleared as expected.
+
+* Freezing a Roda app now can add performance improvements in
+  addition to reliability improvements. When freezing the class,
+  if certain methods in the class have not been overridden, Roda
+  now defines aliases or more optimized methods to improve
+  performance.
+
+* Roda now warns if the Roda#call method is overridden in a module,
+  without the module also overridding _roda_handle_main_route or
+  _roda_run_main_route.  This indicates that the module needs
+  to be updated to use Roda's new dispatch API.  Roda will continue
+  to work in this case, but it will be slower than the Roda's now
+  default behavior, as it will force usage of the old dispatch API.
+  This check will be removed in Roda 4, which will remove support
+  for Roda#call (and Roda#_call).
+
+* When there is only a single internal before or after hook defined,
+  the hook is now faster by using a method alias.
+
+* The route_csrf plugin block or :csrf_failure option proc now
+  integrates with the route_block_args plugin.
+
+* The default_status plugin is now faster by defining the
+  default_status method directly.
+
+* The default_headers plugin is now faster by defining an optimized
+  set_default_headers method directly.
+
+* The hooks plugin is now faster by defining methods for each
+  hook block, with a main hook method that dispatches to each
+  of the hook block methods.  If only a single hook block is
+  used, the main hook method is an alias to the hook block
+  method to avoid an extra method call.
+
+* The following plugins now use define_method instead of
+  instance_exec for better performance:
+
+  * defaults_setter
+  * mail_processor
+  * multi_route
+  * named_templates
+  * path
+  * route_block_args
+  * route_csrf
+  * static_routing
+  * status_handler
+
+* The internal after hook implementation has now been merged into
+  the error_handler plugin. This is faster in cases where the
+  error_handler plugin is used, and slower in cases where the
+  internal after hook plugin was used without the error_handler
+  plugin.
+
+* The route_block_args plugin now handles cases where
+  Roda.convert_route_block has already been overridden.
+
+* Performance of routing methods that can yield captures has been
+  improved.
+
+* Hash#merge is now used in preference to Hash[].merge! in cases
+  where the receiver of Hash#merge would not be provided by the
+  user.  This is because Hash#merge is faster than Hash[].merge!
+  in recent ruby versions.  If the receiver of #merge is provided
+  by the user, then Hash[].merge! is still used to ensure that the
+  resulting value is plain hash.
+
+* The static_routing plugin no longer removes existing static
+  routes if loaded more than once.
+
+* Roda now warns when calling Roda.route without a block.
+
+= Backwards Compatibility
+
+* The route_block_args plugin no longer affects the
+  class_level_routing plugin.  Support for this was added in Roda
+  3.17.0 when the route_block_args plugin was added, but this was a
+  mistake as class_level_routing blocks should be called with the
+  captures for their matchers, not with the route block args.
+
+* Some of the internal state was changed in the following plugins:
+
+  * class_level_routing
+  * mail_processor
+  * multi_route
+  * named_templates
+  * static_routing
+  * status_handler
+
+  This only affects you if you were accessing the internal state
+  via the opts hash.
+
+* The static_routing plugin no longer defines the r.static_route
+  method.
+
+* The mailer plugin was switched to use the new dispatch API, and
+  will no longer handle cases where the old dispatch API (Roda#call)
+  was overrridden.
+
+* The static_route method in the static_routing plugin must
+  now be called with a block.  Previously, that would not
+  cause a failure until runtime, where it would fail when
+  you tried to execute the route.

data/lib/roda.rb

@@ -145,6 +145,106 @@ class Roda
           build_rack_app
         end
 
+        # Define an instance method using the block with the provided name and
+        # expected arity.  If the name is given as a Symbol, it is used directly.
+        # If the name is given as a String, a unique name will be generated using
+        # that string.  The expected arity should be either 0 (no arguments),
+        # 1 (single argument), or :any (any number of arguments).
+        #
+        # If the :check_arity app option is not set to false, Roda will check that
+        # the arity of the block matches the expected arity, and compensate for
+        # cases where it does not.  If it is set to :warn, Roda will warn in the
+        # cases where the arity does not match what is expected.
+        #
+        # If the expected arity is :any, Roda must perform a dynamic arity check
+        # when the method is called, which can hurt performance even in the case
+        # where the arity matches.  The :check_dynamic_arity app option can be
+        # set to false to turn off the dynamic arity checks.  The
+        # :check_dynamic_arity app option can be to :warn to warn if Roda needs
+        # to adjust arity dynamically.
+        #
+        # Roda only checks arity for regular blocks, not lambda blocks, as the
+        # fixes Roda uses for regular blocks would not work for lambda blocks.
+        #
+        # Roda does not support blocks with required keyword arguments if the
+        # expected arity is 0 or 1.
+        def define_roda_method(meth, expected_arity, &block)
+          if meth.is_a?(String)
+            meth = roda_method_name(meth)
+          end
+
+          if (check_arity = opts.fetch(:check_arity, true)) && !block.lambda?
+            required_args, optional_args, rest, keyword = _define_roda_method_arg_numbers(block)
+
+            if keyword == :required && (expected_arity == 0 || expected_arity == 1)
+              raise RodaError, "cannot use block with required keyword arguments when calling define_roda_method with expected arity #{expected_arity}"
+            end
+
+            case expected_arity
+            when 0
+              unless required_args == 0
+                if check_arity == :warn
+                  RodaPlugins.warn "Arity mismatch in block passed to define_roda_method. Expected Arity 0, but arguments required for #{block.inspect}"
+                end
+                b = block
+                block = lambda{instance_exec(&b)} # Fallback
+              end
+            when 1
+              if required_args == 0 && optional_args == 0 && !rest
+                if check_arity == :warn
+                  RodaPlugins.warn "Arity mismatch in block passed to define_roda_method. Expected Arity 1, but no arguments accepted for #{block.inspect}"
+                end
+                b = block
+                block = lambda{|_| instance_exec(&b)} # Fallback
+              end
+            when :any
+              if check_dynamic_arity = opts.fetch(:check_dynamic_arity, check_arity)
+                if keyword
+                  # Complexity of handling keyword arguments using define_method is too high,
+                  # Fallback to instance_exec in this case.
+                  b = block
+                  block = lambda{|*a| instance_exec(*a, &b)} # Keyword arguments fallback
+                else
+                  arity_meth = meth
+                  meth = :"#{meth}_arity"
+                end
+              end
+            else
+              raise RodaError, "unexpected arity passed to define_roda_method: #{expected_arity.inspect}"
+            end
+          end
+
+          define_method(meth, &block)
+          private meth
+
+          if arity_meth
+            required_args, optional_args, rest, keyword = _define_roda_method_arg_numbers(instance_method(meth))
+            max_args = required_args + optional_args
+            define_method(arity_meth) do |*a|
+              arity = a.length
+              if arity > required_args
+                if arity > max_args && !rest
+                  if check_dynamic_arity == :warn
+                    RodaPlugins.warn "Dynamic arity mismatch in block passed to define_roda_method. At most #{max_args} arguments accepted, but #{arity} arguments given for #{block.inspect}"
+                  end
+                  a = a.slice(0, max_args)
+                end
+              elsif arity < required_args
+                if check_dynamic_arity == :warn
+                  RodaPlugins.warn "Dynamic arity mismatch in block passed to define_roda_method. #{required_args} args required, but #{arity} arguments given for #{block.inspect}"
+                end
+                a.concat([nil] * (required_args - arity))
+              end
+
+              send(meth, *a)
+            end
+            private arity_meth
+            arity_meth
+          else
+            meth
+          end
+        end
+
         # Expand the given path, using the root argument as the base directory.
         def expand_path(path, root=opts[:root])
           ::File.expand_path(path, root)
@@ -160,6 +260,24 @@ class Roda
         def freeze
           @opts.freeze
           @middleware.freeze
+
+          unless opts[:subclassed]
+            # If the _roda_run_main_route instance method has not been overridden,
+            # make it an alias to _roda_main_route for performance
+            if instance_method(:_roda_run_main_route).owner == InstanceMethods
+              class_eval("alias _roda_run_main_route _roda_main_route")
+            end
+            self::RodaResponse.class_eval do
+              if instance_method(:set_default_headers).owner == ResponseMethods &&
+                 instance_method(:default_headers).owner == ResponseMethods
+
+                def set_default_headers
+                  @headers['Content-Type'] ||= 'text/html'
+                end
+              end
+            end
+          end
+
           super
         end
 
@@ -176,10 +294,16 @@ class Roda
         # and setup the request and response subclasses.
         def inherited(subclass)
           raise RodaError, "Cannot subclass a frozen Roda class" if frozen?
+
+          # Mark current class as having been subclassed, as some optimizations
+          # depend on the class not being subclassed
+          opts[:subclassed] = true
+
           super
           subclass.instance_variable_set(:@inherit_middleware, @inherit_middleware)
           subclass.instance_variable_set(:@middleware, @inherit_middleware ? @middleware.dup : [])
           subclass.instance_variable_set(:@opts, opts.dup)
+          subclass.opts.delete(:subclassed)
           subclass.opts.to_a.each do |k,v|
             if (v.is_a?(Array) || v.is_a?(Hash)) && !v.frozen?
               subclass.opts[k] = v.dup
@@ -233,9 +357,15 @@ class Roda
         # This should only be called once per class, and if called multiple
         # times will overwrite the previous routing.
         def route(&block)
+          unless block
+            RodaPlugins.warn "no block passed to Roda.route"
+            return
+          end
+
           @raw_route_block = block
           @route_block = block = convert_route_block(block)
-          @rack_app_route_block = rack_app_route_block(block)
+          @rack_app_route_block = block = rack_app_route_block(block)
+          public define_roda_method(:_roda_main_route, 1, &block)
           build_rack_app
         end
 
@@ -250,10 +380,68 @@ class Roda
 
         private
 
+        # Return the number of required argument, optional arguments,
+        # whether the callable accepts any additional arguments,
+        # and whether the callable accepts keyword arguments (true, false
+        # or :required).
+        def _define_roda_method_arg_numbers(callable)
+          optional_args = 0
+          rest = false
+          keyword = false
+          callable.parameters.map(&:first).each do |arg_type, _|
+            case arg_type
+            when :opt
+              optional_args += 1
+            when :rest
+              rest = true
+            when :keyreq
+              keyword = :required
+            when :key, :keyrest
+              keyword ||= true
+            end
+          end
+          arity = callable.arity
+          if arity < 0
+            arity = arity.abs - 1
+          end
+          required_args = arity
+          arity -= 1 if keyword == :required
+
+          if callable.is_a?(Proc) && !callable.lambda?
+            optional_args -= arity
+          end
+
+          [required_args, optional_args, rest, keyword]
+        end
+
+        # The base rack app to use, before middleware is added.
+        def base_rack_app_callable(new_api=true)
+          if new_api
+            lambda{|env| new(env)._roda_handle_main_route}
+          else
+            block = @rack_app_route_block
+            lambda{|env| new(env).call(&block)}
+          end
+        end
+
         # Build the rack app to use
         def build_rack_app
-          if block = @rack_app_route_block
-            app = lambda{|env| new(env).call(&block)}
+          if @rack_app_route_block
+            # RODA4: Assume optimize is true
+            optimize = ancestors.each do |mod|
+              break true if mod == InstanceMethods
+              meths = mod.instance_methods(false)
+              if meths.include?(:call) && !(meths.include?(:_roda_handle_main_route) || meths.include?(:_roda_run_main_route))
+              RodaPlugins.warn <<WARNING
+Falling back to using #call for dispatching for #{self}, due to #call override in #{mod}.
+#{mod} should be fixed to adjust to Roda's new dispatch API, and override _roda_handle_main_route or _roda_run_main_route
+WARNING
+                break false
+              end
+            end
+
+            app = base_rack_app_callable(optimize)
+
             @middleware.reverse_each do |args, bl|
               mid, *args = args
               app = mid.new(app, *args, &bl)
@@ -274,13 +462,15 @@ class Roda
         # in order, if any _roda_before_* methods are defined. Also, rebuild
         # the route block if a _roda_before method is defined.
         def def_roda_before
-          meths = private_instance_methods.grep(/\A_roda_before_\d\d/).sort.join(';')
+          meths = private_instance_methods.grep(/\A_roda_before_\d\d/).sort
           unless meths.empty?
-            class_eval("def _roda_before; #{meths} end", __FILE__, __LINE__)
-            private :_roda_before
-            if @raw_route_block
-              route(&@raw_route_block)
+            plugin :_before_hook unless private_method_defined?(:_roda_before)
+            if meths.length == 1
+              class_eval("alias _roda_before #{meths.first}", __FILE__, __LINE__)
+            else
+              class_eval("def _roda_before; #{meths.join(';')} end", __FILE__, __LINE__)
             end
+            private :_roda_before
           end
         end
 
@@ -288,10 +478,14 @@ class Roda
         # in order, if any _roda_after_* methods are defined. Also, use
         # the internal after hook plugin if the _roda_after method is defined.
         def def_roda_after
-          meths = private_instance_methods.grep(/\A_roda_after_\d\d/).sort.map{|s| "#{s}(res)"}.join(';')
+          meths = private_instance_methods.grep(/\A_roda_after_\d\d/).sort
           unless meths.empty?
-            plugin :_after_hook unless private_method_defined?(:_roda_after)
-            class_eval("def _roda_after(res); #{meths} end", __FILE__, __LINE__)
+            plugin :error_handler unless private_method_defined?(:_roda_after)
+            if meths.length == 1
+              class_eval("alias _roda_after #{meths.first}", __FILE__, __LINE__)
+            else
+              class_eval("def _roda_after(res); #{meths.map{|s| "#{s}(res)"}.join(';')} end", __FILE__, __LINE__)
+            end
             private :_roda_after
           end
         end
@@ -302,14 +496,14 @@ class Roda
         # if any before hooks are defined.
         # Can be modified by plugins.
         def rack_app_route_block(block)
-          if private_method_defined?(:_roda_before)
-            lambda do |r|
-              _roda_before
-              instance_exec(r, &block)
-            end
-          else
-            block
-          end
+          block
+        end
+
+        method_num = 0
+        method_num_mutex = Mutex.new
+        # Return a unique method name symbol for the given suffix.
+        define_method(:roda_method_name) do |suffix|
+          :"_roda_#{suffix}_#{method_num_mutex.synchronize{method_num += 1}}"
         end
       end
 
@@ -328,20 +522,49 @@ class Roda
           @_response = klass::RodaResponse.new
         end
 
-        # instance_exec the route block in the scope of the
-        # receiver, with the related request.  Catch :halt so that
-        # the route block can throw :halt at any point with the
-        # rack response to use.
+        # Handle dispatching to the main route, catching :halt and handling
+        # the result of the block.
+        def _roda_handle_main_route
+          catch(:halt) do
+            r = @_request
+            r.block_result(_roda_run_main_route(r))
+            @_response.finish
+          end
+        end
+
+        # Treat the given block as a routing block, catching :halt if
+        # thrown by the block.
+        def _roda_handle_route
+          catch(:halt) do
+            @_request.block_result(yield)
+            @_response.finish
+          end
+        end
+
+        # Default implementation of the main route, usually overridden
+        # by Roda.route.
+        def _roda_main_route(_)
+        end
+
+        # Run the main route block with the request.  Designed for
+        # extension by plugins
+        def _roda_run_main_route(r)
+          _roda_main_route(r)
+        end
+
+        # Deprecated method for the previous main route dispatch API.
         def call(&block)
+          # RODA4: Remove
           catch(:halt) do
             r = @_request
-            r.block_result(instance_exec(r, &block))
+            r.block_result(instance_exec(r, &block)) # Fallback
             @_response.finish
           end
         end
 
-        # Private alias for internal use
+        # Deprecated private alias for internal use
         alias _call call
+        # RODA4: Remove
         private :_call
 
         # The environment hash for the current request. Example:
@@ -904,7 +1127,7 @@ class Roda
           path = @remaining_path
           # For every block, we make sure to reset captures so that
           # nesting matchers won't mess with each other's captures.
-          @captures.clear
+          captures = @captures.clear
 
           if match_all(args)
             block_result(yield(*captures))