roda 3.56.0 → 3.59.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 25ca2a1c88af9f7305cdcdb21e3b5983f879386f07c296d7ea0e8f863fddfeac
-  data.tar.gz: 24d9dbfeaa438c859b2b3fcecd2170d55e9d4335b1b57ca06c140b900d4a8283
+  metadata.gz: 963e2d9ac538dbe97835ef65e2e2ba4184838664696bb084ce423a85ef23c205
+  data.tar.gz: d47a7f9c86357e99b0c9f470b6c33a32962df55189303020982af55d70907c7b
 SHA512:
-  metadata.gz: 8c1b58f0a4ac491533eebb08e83c5801d095d94dbf4270d5834fb3511c82fd305244c0c02e23ba51dba1479e81b361faf556ad85698ea77ebd8a130f471b9527
-  data.tar.gz: b18e88e98b3c42a83f0e66891e48b03b9b641ecaf5963e5e5fd71d086c92176cefd5642464c790ed5edde30459c4a1d78b62864b1f14cd38f3bea1c9b6cefa30
+  metadata.gz: c84cb0ae8c66b537c0a7d32d83d9c5a639439b15fbc650d3569efab5e134e0883ba06183c7f17bfb379f4018060c7d276a5016431ae3e21d05c2db3801a85762
+  data.tar.gz: 0c9495ec5fe24b774512f6495f97f5bb4cf8189b964f21a04c5e880d4a536ade2e045c7131f0a54a7c1cd203fe142d53c6d7cde4cf223a8e8be4cb5c5475fede

data/CHANGELOG

@@ -1,3 +1,27 @@
+= 3.59.0 (2022-08-12)
+
+* Add additional_render_engines plugin, for considering multiple render engines for templates (jeremyevans)
+
+* Fix typo in private method name in delete_empty_headers plugin (mculpt) (#279)
+
+= 3.58.0 (2022-07-13)
+
+* Add filter_common_logger plugin for skipping the logging of certain requests when using the common_logger plugin (jeremyevans)
+
+* Make exception_page plugin use Exception#detailed_message on Ruby 3.2+ (jeremyevans)
+
+* Make heartbeat plugin compatible with recent changes in the rack master branch (jeremyevans)
+
+= 3.57.0 (2022-06-14)
+
+* Make static_routing plugin depend on the hash_paths instead of the hash_routes plugin (jeremyevans)
+
+* Split hash_branches and hash_paths plugins from hash_routes plugin (jeremyevans)
+
+* Hex escape unprintable characters in common_logger plugin output (jeremyevans)
+
+* Add hash_branch_view_subdir plugin for automatically appending a view subdirectory on a successful hash branch (jeremyevans)
+
 = 3.56.0 (2022-05-13)
 
 * Make status_303 plugin use 303 responses for HTTP/2 and higher versions (jeremyevans)

data/doc/conventions.rdoc

@@ -86,17 +86,17 @@ Large applications generally need more structure:
 
 For larger apps, the +Rakefile+, +assets/+, +migrate+, +models.rb+, +models/+, +public/+, remain the same.
 
-+app_name.rb+ should use the +hash_routes+ and +view_options+ plugin, or the +multi_run+ plugin.
-The routes used by the +hash_routes+ or +multi_run+ should be stored in routing files in the +routes/+
++app_name.rb+ should use the +hash_branch_view_subdir+ plugin (which builds on the +hash_branches+ and
++view_options+ plugin), or the +multi_run+ plugin.
+The routes used by the +hash_branches+ or +multi_run+ should be stored in routing files in the +routes/+
 directory, with one file per prefix.
 
 For specs/tests, you should have +spec/models/+ and +spec/web/+, with one file per model in +spec/models/+
 and one file per prefix in +spec/web/+. Substitute +spec+ with +test+ if that is what you are using as the
 name of the directory.
 
-You should have a separate view subdirectory per prefix. If you are using +hash_routes+ and +view_options+ plugins,
-use +set_view_subdir+ in your routing files to specify the subdirectory to use, so it doesn't need to be
-specified on every call to view.
+You should have a separate view subdirectory per prefix. With the +hash_branch_view_subdir+, the application
+will automatically set a separate view subdirectory per routing tree branch.
 
 +helpers/+ should be used to store helper methods for your application, that you call in your routing files
 and views.  In a small application, these methods should just be specified in +app_name.rb+
@@ -104,7 +104,7 @@ and views.  In a small application, these methods should just be specified in +a
 === Really Large Applications
 
 For very large applications, it's expected that there will be deviations from these conventions. However,
-it is recommended to use the +hash_routes+ or +multi_run+ plugins to organize your application, and have
+it is recommended to use the +hash_branch_view_subdir+ or +multi_run+ plugins to organize your application, and have
 subdirectories in the +routes/+ directory, and nested subdirectories in the +views/+ directory.
 
 == Roda Application File Layout
@@ -156,19 +156,22 @@ For larger applications, there are some slight changes to the Roda application f
 
     plugin :render, escape: true, layout: './layout'
     plugin :assets
-    plugin :view_options
-    plugin :hash_routes
+    plugin :hash_branch_view_subdir
     Dir['routes/*.rb'].each{|f| require_relative f}
 
     route do |r|
-      r.hash_routes
+      r.hash_branches('')
+
+      r.root do
+        # ...
+      end
     end
 
     Dir['helpers/*.rb'].each{|f| require_relative f}
   end
 
-After loading the +view_options+ and +hash_routes+ plugin, you require all of your
+After loading the +hash_branch_view_subdir+ plugin, you require all of your
 routing files.  Inside your route block, instead of defining your routes, you just call
-+r.hash_routes+, which will dispatch to all of your routing files.  After your route
++r.hash_branches+, which will dispatch to all of your routing files.  After your route
 block, you require all of your helper files containing the instance methods for your
 route block or views, instead of defining the methods directly.

data/doc/release_notes/3.57.0.txt

@@ -0,0 +1,34 @@
+= New Features
+
+* hash_branches and hash_paths plugins have been split off from the
+  hash_routes plugin, allowing you to use only those parts instead
+  of all of hash_routes.
+
+  The hash_branches plugin supports the hash_branch class method
+  and r.hash_branches routing method.
+
+  The hash_paths plugin supports the hash_path class method and
+  r.hash_paths routing method.
+  
+  The hash_routes plugin functions as it did previously by
+  requiring the hash_branches and hash_paths plugins. It adds
+  the hash_routes DSL and r.hash_routes routing method.
+
+* A hash_branch_view_subdir has been added.  It builds on the
+  view_options plugin and new hash_branches plugin, automatically
+  appending a view subdirectory for each successful hash branch.
+  This can DRY up code that uses a separate view subdirectory for
+  each branch.
+
+= Other Improvements
+
+* Unprintable characters are now hex escaped in the output of the
+  common_logger plugin.  This can protect users who use software
+  that respects shell escape sequences to view the logs.
+
+= Backwards Compatibility
+
+* The static_routing plugin now depends on the hash_paths plugin
+  instead of the hash_routes plugin, so you will need to update
+  your application to explicitly load the hash_routes plugin if
+  you were relying on static_routing to implicitly load it.

data/doc/release_notes/3.58.0.txt

@@ -0,0 +1,16 @@
+= New Features
+
+* A filter_common_logger plugin has been added, allowing you to skip
+  logging of certain requests in the common_logger plugin. This
+  allows you to only log requests for certain paths, or only log
+  requests for certain types of responses.
+
+= Other Improvements
+
+* The heartbeat plugin is now compatible with recent changes in the
+  rack master branch (what will be rack 3).
+
+* The exception_page plugin will now use Exception#detailed_message
+  on Ruby 3.2+, preserving the did_you_mean and error_highlight
+  information.  Additionally, the display of exception messages
+  has been improved.

data/doc/release_notes/3.59.0.txt

@@ -0,0 +1,17 @@
+= New Features
+
+* An additional_render_engines plugin has been added, for considering
+  multiple render engines for templates. If the template path does not
+  exist for the default render engine, then each additional render
+  engine will be checked, returning the first path that exists:
+
+    plugin :additional_render_engines, ['haml', 'str']
+
+  This is similar to the additional_view_directories plugin added in
+  3.53.0.  Both plugins can be used if you want to consider multiple
+  view directories and multiple render engines.
+
+= Other Improvements
+
+* A typo in a private method name in the delete_empty_headers plugin
+  has been fixed.

data/lib/roda/plugins/additional_render_engines.rb

@@ -0,0 +1,61 @@
+# frozen-string-literal: true
+
+#
+class Roda
+  module RodaPlugins
+    # The additional_render_engines plugin allows for specifying additional render
+    # engines to consider for templates.  When rendering a template, it will
+    # first try the default template engine specified in the render plugin.  If the
+    # template file to be rendered does not exist, it will try each additional render
+    # engine specified in this plugin, in order, using the path to the first
+    # template file that exists in the file system.  If no such path is found, it
+    # uses the default path specified by the render plugin.
+    #
+    # Example:
+    #
+    #   plugin :render # default engine is 'erb'
+    #   plugin :additional_render_engines, ['haml', 'str']
+    #
+    #   route do |r|
+    #     # Will check the following in order, using path for first
+    #     # template file that exists:
+    #     # * views/t.erb
+    #     # * views/t.haml
+    #     # * views/t.str
+    #     render :t
+    #   end
+    module AdditionalRenderEngines
+      def self.load_dependencies(app, render_engines)
+        app.plugin :render
+      end
+
+      # Set the additional render engines to consider.
+      def self.configure(app, render_engines)
+        app.opts[:additional_render_engines] = render_engines.dup.freeze
+      end
+
+      module InstanceMethods
+        private
+
+        # If the template path does not exist, try looking for the template
+        # using each of the render engines, in order, returning
+        # the first path that exists. If no template path exists for the
+        # default any or any additional engines, return the original path.
+        def template_path(opts)
+          orig_path = super
+
+          unless File.file?(orig_path)
+            self.opts[:additional_render_engines].each do |engine|
+              path = super(opts.merge(:engine=>engine))
+              return path if File.file?(path)
+            end
+          end
+
+          orig_path
+        end
+      end
+    end
+
+    register_plugin(:additional_render_engines, AdditionalRenderEngines)
+  end
+end

data/lib/roda/plugins/assets.rb

@@ -147,7 +147,7 @@ class Roda
     # If you have the yuicompressor gem installed and working, it will be used
     # automatically to compress your javascript and css assets.  For javascript
     # assets, if yuicompressor is not available, the plugin will check for
-    # closure_compiler, uglifier, and minjs and use the first one that works.
+    # closure-compiler, uglifier, and minjs and use the first one that works.
     # If no compressors are available, the assets will just be concatenated
     # together and not compressed during compilation.  You can use the
     # :css_compressor and :js_compressor options to specify the compressor to use.

data/lib/roda/plugins/common_logger.rb

@@ -20,6 +20,9 @@ class Roda
     #   plugin :common_logger, Logger.new('filename')
     #   plugin :common_logger, Logger.new('filename'), method: :debug
     module CommonLogger
+      MUTATE_LINE = RUBY_VERSION < '2.3' || RUBY_VERSION >= '3'
+      private_constant :MUTATE_LINE
+
       def self.configure(app, logger=nil, opts=OPTS)
         app.opts[:common_logger] = logger || app.opts[:common_logger] || $stderr
         app.opts[:common_logger_meth] = app.opts[:common_logger].method(opts.fetch(:method){logger.respond_to?(:write) ? :write : :<<})
@@ -53,7 +56,15 @@ class Roda
 
           env = @_request.env
 
-          opts[:common_logger_meth].call("#{env['HTTP_X_FORWARDED_FOR'] || env["REMOTE_ADDR"] || "-"} - #{env["REMOTE_USER"] || "-"} [#{Time.now.strftime("%d/%b/%Y:%H:%M:%S %z")}] \"#{env["REQUEST_METHOD"]} #{env["SCRIPT_NAME"]}#{env["PATH_INFO"]}#{"?#{env["QUERY_STRING"]}" if ((qs = env["QUERY_STRING"]) && !qs.empty?)} #{@_request.http_version}\" #{result[0]} #{((length = result[1]['Content-Length']) && (length unless length == '0')) || '-'} #{elapsed_time}\n")
+          line = "#{env['HTTP_X_FORWARDED_FOR'] || env["REMOTE_ADDR"] || "-"} - #{env["REMOTE_USER"] || "-"} [#{Time.now.strftime("%d/%b/%Y:%H:%M:%S %z")}] \"#{env["REQUEST_METHOD"]} #{env["SCRIPT_NAME"]}#{env["PATH_INFO"]}#{"?#{env["QUERY_STRING"]}" if ((qs = env["QUERY_STRING"]) && !qs.empty?)} #{@_request.http_version}\" #{result[0]} #{((length = result[1]['Content-Length']) && (length unless length == '0')) || '-'} #{elapsed_time}\n"
+          if MUTATE_LINE
+            line.gsub!(/[^[:print:]\n]/){|c| sprintf("\\x%x", c.ord)}
+          # :nocov:
+          else
+            line = line.gsub(/[^[:print:]\n]/){|c| sprintf("\\x%x", c.ord)}
+          # :nocov:
+          end
+          opts[:common_logger_meth].call(line)
         end
 
         # Create timer instance used for timing

data/lib/roda/plugins/delete_empty_headers.rb

@@ -13,18 +13,18 @@ class Roda
       module ResponseMethods
         # Delete any empty headers when calling finish
         def finish
-          delelete_empty_headers(super)
+          delete_empty_headers(super)
         end
 
         # Delete any empty headers when calling finish_with_body
         def finish_with_body(_)
-          delelete_empty_headers(super)
+          delete_empty_headers(super)
         end
 
         private
 
         # Delete any empty headers from response
-        def delelete_empty_headers(res)
+        def delete_empty_headers(res)
           res[1].delete_if{|_, v| v.is_a?(String) && v.empty?}
           res
         end

data/lib/roda/plugins/exception_page.rb

@@ -127,7 +127,7 @@ div.context ol.context-line li span { float: right; }
 div.commands { margin-left: 40px; }
 div.commands a { color:black; text-decoration:none; }
 #summary { background: #ffc; }
-#summary h2 { font-weight: normal; color: #666; }
+#summary h2 { font-weight: normal; color: #666; font-family: monospace; white-space: pre-wrap;}
 #summary ul#quicklinks { list-style-type: none; margin-bottom: 2em; }
 #summary ul#quicklinks li { float: left; padding: 0 1em; }
 #summary ul#quicklinks>li+li { border-left: 1px #666 solid; }
@@ -196,12 +196,13 @@ END
         #          Designed to be used with the +json+ exception, which will
         #          automatically convert the hash to JSON format.
         def exception_page(exception, opts=OPTS)
+          message = exception_page_exception_message(exception)
           if opts[:json]
             @_response['Content-Type'] = "application/json"
             {
               "exception"=>{
                 "class"=>exception.class.to_s,
-                "message"=>exception.message.to_s,
+                "message"=>message,
                 "backtrace"=>exception.backtrace.map(&:to_s)
               }
             }
@@ -319,7 +320,7 @@ END
 
 <div id="summary">
   <h1>#{h exception.class} at #{h r.path}</h1>
-  <h2>#{h exception.message}</h2>
+  <h2>#{h message}</h2>
   <table><tr>
     <th>Ruby</th>
     <td>
@@ -394,7 +395,22 @@ END1
 END
           else
             @_response['Content-Type'] = "text/plain"
-            "#{exception.class}: #{exception.message}\n#{exception.backtrace.map{|l| "\t#{l}"}.join("\n")}"
+            "#{exception.class}: #{message}\n#{exception.backtrace.map{|l| "\t#{l}"}.join("\n")}"
+          end
+        end
+
+        private
+
+        # :nocov:
+        if RUBY_VERSION >= '3.2'
+          def exception_page_exception_message(exception)
+            exception.detailed_message(highlight: false).to_s
+          end
+        # :nocov:
+        else
+          # Return message to use for exception.
+          def exception_page_exception_message(exception)
+            exception.message.to_s
           end
         end
       end

data/lib/roda/plugins/filter_common_logger.rb

@@ -0,0 +1,46 @@
+# frozen-string-literal: true
+
+#
+class Roda
+  module RodaPlugins
+    # The skip_common_logger plugin allows for skipping common_logger logging
+    # of some requests. You pass a block when loading the plugin, and the
+    # block will be called before logging each request.  The block should return
+    # whether the request should be logged.
+    #
+    # Example:
+    #
+    #   # Only log server errors
+    #   plugin :filter_common_logger do |result|
+    #     result[0] >= 500
+    #   end
+    #
+    #   # Don't log requests to certain paths
+    #   plugin :filter_common_logger do |_|
+    #     # Block is called in the same context as the route block
+    #     !request.path.start_with?('/admin/')
+    #   end
+    module FilterCommonLogger
+      def self.load_dependencies(app)
+        app.plugin :common_logger
+      end
+
+      def self.configure(app, &block)
+        app.send(:define_method, :_common_log_request?, &block)
+        app.send(:private, :_common_log_request?)
+        app.send(:alias_method, :_common_log_request?, :_common_log_request?)
+      end
+
+      module InstanceMethods
+        private
+
+        # Log request/response information in common log format to logger.
+        def _roda_after_90__common_logger(result)
+          super if result && _common_log_request?(result)
+        end
+      end
+    end
+
+    register_plugin(:filter_common_logger, FilterCommonLogger)
+  end
+end

data/lib/roda/plugins/hash_branch_view_subdir.rb

@@ -0,0 +1,76 @@
+# frozen-string-literal: true
+
+#
+class Roda
+  module RodaPlugins
+    # The hash_branch_view_subdir plugin builds on the hash_branches and view_options
+    # plugins, automatically appending a view subdirectory for any matching hash branch
+    # taken. In cases where you are using a separate view subdirectory per hash branch,
+    # this can result in DRYer code. Example:
+    #
+    #   plugin :hash_branch_view_subdir
+    #
+    #   route do |r|
+    #     r.hash_branches
+    #   end
+    #
+    #   hash_branch 'foo' do |r|
+    #     # view subdirectory here is 'foo'
+    #     r.hash_branches('foo')
+    #   end
+    #
+    #   hash_branch 'foo', 'bar' do |r|
+    #     # view subdirectory here is 'foo/bar'
+    #   end
+    module HashBranchViewSubdir
+      def self.load_dependencies(app)
+        app.plugin :hash_branches
+        app.plugin :view_options
+      end
+
+      def self.configure(app)
+        app.opts[:hash_branch_view_subdir_methods] ||= {}
+      end
+
+      module ClassMethods
+        # Freeze the hash_branch_view_subdir metadata when freezing the app.
+        def freeze
+          opts[:hash_branch_view_subdir_methods].freeze.each_value(&:freeze)
+          super
+        end
+
+        # Duplicate hash_branch_view_subdir metadata in subclass.
+        def inherited(subclass)
+          super
+
+          h = subclass.opts[:hash_branch_view_subdir_methods]
+          opts[:hash_branch_view_subdir_methods].each do |namespace, routes|
+            h[namespace] = routes.dup
+          end
+        end
+
+        # Automatically append a view subdirectory for a successful hash_branch route,
+        # by modifying the generated method to append the view subdirectory before
+        # dispatching to the original block.
+        def hash_branch(namespace='', segment, &block)
+          meths = opts[:hash_branch_view_subdir_methods][namespace] ||= {}
+
+          if block
+            meth = meths[segment] = define_roda_method(meths[segment] || "_hash_branch_view_subdir_#{namespace}_#{segment}", 1, &convert_route_block(block))
+            super do |*_|
+              append_view_subdir(segment)
+              send(meth, @_request)
+            end
+          else
+            if meth = meths.delete(segment)
+              remove_method(meth)
+            end
+            super
+          end
+        end
+      end
+    end
+
+    register_plugin(:hash_branch_view_subdir, HashBranchViewSubdir)
+  end
+end

data/lib/roda/plugins/hash_branches.rb

@@ -0,0 +1,145 @@
+# frozen-string-literal: true
+
+#
+class Roda
+  module RodaPlugins
+    # The hash_branches plugin allows for O(1) dispatch to multiple route tree branches,
+    # based on the next segment in the remaining path:
+    #
+    #   class App < Roda
+    #     plugin :hash_branches
+    #
+    #     hash_branch("a") do |r|
+    #       # /a branch
+    #     end
+    #
+    #     hash_branch("b") do |r|
+    #       # /b branch
+    #     end
+    #
+    #     route do |r|
+    #       r.hash_branches
+    #     end
+    #   end
+    #
+    # With the above routing tree, the +r.hash_branches+ call in the main routing tree
+    # will dispatch requests for the +/a+ and +/b+ branches of the tree to the appropriate
+    # routing blocks.
+    #
+    # In this example, the hash branches for +/a+ and +/b+ are in the same file, but in larger
+    # applications, they are usually stored in separate files.  This allows for easily splitting
+    # up the routing tree into a separate file per branch.
+    #
+    # The +hash_branch+ method supports namespaces, which allow for dispatching to sub-branches
+    # any level of the routing tree, fully supporting the needs of applications with large and
+    # deep routing branches:
+    #
+    #   class App < Roda
+    #     plugin :hash_branches
+    #
+    #     # Only one argument used, so the namespace defaults to '', and the argument
+    #     # specifies the route name
+    #     hash_branch("a") do |r|
+    #       # No argument given, so uses the already matched path as the namespace,
+    #       # which is '/a' in this case.
+    #       r.hash_branches
+    #     end
+    #
+    #     hash_branch("b") do |r|
+    #       # uses :b as the namespace when looking up routes, as that was explicitly specified
+    #       r.hash_branches(:b)
+    #     end
+    #
+    #     # Two arguments used, so first specifies the namespace and the second specifies
+    #     # the branch name
+    #     hash_branch("/a", "b") do |r|
+    #       # /a/b path
+    #     end
+    #
+    #     hash_branch("/a", "c") do |r|
+    #       # /a/c path 
+    #     end
+    #
+    #     hash_branch(:b, "b") do |r|
+    #       # /b/b path
+    #     end
+    #
+    #     hash_branch(:b, "c") do |r|
+    #       # /b/c path 
+    #     end
+    #
+    #     route do |r|
+    #       # No argument given, so uses '' as the namespace, as no part of the path has
+    #       # been matched yet
+    #       r.hash_branches
+    #     end
+    #   end
+    #
+    # With the above routing tree, requests for the +/a+ and +/b+ branches will be
+    # dispatched to the appropriate +hash_branch+ block.  Those blocks will the dispatch
+    # to the remaining +hash_branch+ blocks, with the +/a+ branch using the implicit namespace of
+    # +/a+, and the +/b+ branch using the explicit namespace of +:b+.
+    #
+    # It is best for performance to explicitly specify the namespace when calling
+    # +r.hash_branches+.
+    module HashBranches
+      def self.configure(app)
+        app.opts[:hash_branches] ||= {}
+      end
+
+      module ClassMethods
+        # Freeze the hash_branches metadata when freezing the app.
+        def freeze
+          opts[:hash_branches].freeze.each_value(&:freeze)
+          super
+        end
+
+        # Duplicate hash_branches metadata in subclass.
+        def inherited(subclass)
+          super
+
+          h = subclass.opts[:hash_branches]
+          opts[:hash_branches].each do |namespace, routes|
+            h[namespace] = routes.dup
+          end
+        end
+
+        # Add branch handler for the given namespace and segment. If called without
+        # a block, removes the existing branch handler if it exists.
+        def hash_branch(namespace='', segment, &block)
+          segment = "/#{segment}"
+          routes = opts[:hash_branches][namespace] ||= {}
+          if block
+            routes[segment] = define_roda_method(routes[segment] || "hash_branch_#{namespace}_#{segment}", 1, &convert_route_block(block))
+          elsif meth = routes.delete(segment)
+            remove_method(meth)
+          end
+        end
+      end
+
+      module RequestMethods
+        # Checks the matching hash_branch namespace for a branch matching the next
+        # segment in the remaining path, and dispatch to that block if there is one.
+        def hash_branches(namespace=matched_path)
+          rp = @remaining_path
+
+          return unless rp.getbyte(0) == 47 # "/"
+
+          if routes = roda_class.opts[:hash_branches][namespace]
+            if segment_end = rp.index('/', 1)
+              if meth = routes[rp[0, segment_end]]
+                @remaining_path = rp[segment_end, 100000000]
+                always{scope.send(meth, self)}
+              end
+            elsif meth = routes[rp]
+              @remaining_path = ''
+              always{scope.send(meth, self)}
+            end
+          end
+        end
+      end
+    end
+
+    register_plugin(:hash_branches, HashBranches)
+  end
+end

data/lib/roda/plugins/hash_paths.rb

@@ -0,0 +1,128 @@
+# frozen-string-literal: true
+
+#
+class Roda
+  module RodaPlugins
+    # The hash_paths plugin allows for O(1) dispatch to multiple routes at any point
+    # in the routing tree.  It is useful when you have a large number of specific routes
+    # to dispatch to at any point in the routing tree.
+    #
+    # You configure the hash paths to dispatch to using the +hash_path+ class method,
+    # specifying the remaining path, with a block to handle that path.  Then you dispatch
+    # to the configured paths using +r.hash_paths+:
+    #
+    #   class App < Roda
+    #     plugin :hash_paths
+    #
+    #     hash_path("/a") do |r|
+    #       # /a path
+    #     end
+    #
+    #     hash_path("/a/b") do |r|
+    #       # /a/b path 
+    #     end
+    #
+    #     route do |r|
+    #       r.hash_paths
+    #     end
+    #   end
+    #
+    # With the above routing tree, the +r.hash_paths+ call will dispatch requests for the +/a+ and
+    # +/a/b+ request paths.
+    #
+    # The +hash_path+ class method supports namespaces, which allows +r.hash_paths+ to be used at
+    # any level of the routing tree.  Here is an example that uses namespaces for sub-branches:
+    #
+    #   class App < Roda
+    #     plugin :hash_paths
+    #
+    #     # Two arguments provided, so first argument is the namespace
+    #     hash_path("/a", "/b") do |r|
+    #       # /a/b path
+    #     end
+    #
+    #     hash_path("/a", "/c") do |r|
+    #       # /a/c path 
+    #     end
+    #
+    #     hash_path(:b, "/b") do |r|
+    #       # /b/b path
+    #     end
+    #
+    #     hash_path(:b, "/c") do |r|
+    #       # /b/c path 
+    #     end
+    #
+    #     route do |r|
+    #       r.on 'a' do
+    #         # No argument given, so uses the already matched path as the namespace,
+    #         # which is '/a' in this case.
+    #         r.hash_paths
+    #       end
+    #
+    #       r.on 'b' do
+    #         # uses :b as the namespace when looking up routes, as that was explicitly specified
+    #         r.hash_paths(:b)
+    #       end
+    #     end
+    #   end
+    #
+    # With the above routing tree, requests for the +/a+ branch will be handled by the first
+    # +r.hash_paths+ call, and requests for the +/b+ branch will be handled by the second
+    # +r.hash_paths+ call.  Those will dispatch to the configured hash paths for the +/a+ and
+    # +:b+ namespaces.
+    #
+    # It is best for performance to explicitly specify the namespace when calling
+    # +r.hash_paths+.
+    module HashPaths
+      def self.configure(app)
+        app.opts[:hash_paths] ||= {}
+      end
+
+      module ClassMethods
+        # Freeze the hash_paths metadata when freezing the app.
+        def freeze
+          opts[:hash_paths].freeze.each_value(&:freeze)
+          super
+        end
+
+        # Duplicate hash_paths metadata in subclass.
+        def inherited(subclass)
+          super
+
+          h = subclass.opts[:hash_paths]
+          opts[:hash_paths].each do |namespace, routes|
+            h[namespace] = routes.dup
+          end
+        end
+
+        # Add path handler for the given namespace and path. When the
+        # r.hash_paths method is called, checks the matching namespace
+        # for the full remaining path, and dispatch to that block if
+        # there is one.  If called without a block, removes the existing
+        # path handler if it exists.
+        def hash_path(namespace='', path, &block)
+          routes = opts[:hash_paths][namespace] ||= {}
+          if block
+            routes[path] = define_roda_method(routes[path] || "hash_path_#{namespace}_#{path}", 1, &convert_route_block(block))
+          elsif meth = routes.delete(path)
+            remove_method(meth)
+          end
+        end
+      end
+
+      module RequestMethods
+        # Checks the matching hash_path namespace for a branch matching the 
+        # remaining path, and dispatch to that block if there is one.
+        def hash_paths(namespace=matched_path)
+          if (routes = roda_class.opts[:hash_paths][namespace]) && (meth = routes[@remaining_path])
+            @remaining_path = ''
+            always{scope.send(meth, self)}
+          end
+        end
+      end
+    end
+
+    register_plugin(:hash_paths, HashPaths)
+  end
+end

data/lib/roda/plugins/hash_routes.rb

@@ -3,58 +3,9 @@
 #
 class Roda
   module RodaPlugins
-    # The hash_routes plugin combines the O(1) dispatching speed of the static_routing plugin with
-    # the flexibility of the multi_route plugin.  For any point in the routing tree,
-    # it allows you dispatch to multiple routes where the next segment or the remaining path
-    # is a static string.
-    #
-    # For a basic replacement of the multi_route plugin, you can replace class level
-    # <tt>route('segment')</tt> calls with <tt>hash_branch('segment')</tt>:
-    #
-    #   class App < Roda
-    #     plugin :hash_routes
-    #
-    #     hash_branch("a") do |r|
-    #       # /a branch
-    #     end
-    #
-    #     hash_branch("b") do |r|
-    #       # /b branch
-    #     end
-    #
-    #     route do |r|
-    #       r.hash_branches
-    #     end
-    #   end
-    #
-    # With the above routing tree, the +r.hash_branches+ call in the main routing tree,
-    # will dispatch requests for the +/a+ and +/b+ branches of the tree to the appropriate
-    # routing blocks.
-    #
-    # In addition to supporting routing via the next segment, you can also support similar
-    # routing for entire remaining path using the +hash_path+ class method:
-    #
-    #   class App < Roda
-    #     plugin :hash_routes
-    #
-    #     hash_path("/a") do |r|
-    #       # /a path
-    #     end
-    #
-    #     hash_path("/a/b") do |r|
-    #       # /a/b path 
-    #     end
-    #
-    #     route do |r|
-    #       r.hash_paths
-    #     end
-    #   end
-    #
-    # With the above routing tree, the +r.hash_paths+ call will dispatch requests for the +/a+ and
-    # +/a/b+ request paths.
-    #
-    # You can combine the two approaches, and use +r.hash_routes+ to first try routing the
-    # full path, and then try routing the next segment:
+    # The hash_routes plugin builds on top of the hash_branches and hash_paths plugins, and adds
+    # a DSL for configuring hash branches and paths. It also adds an +r.hash_routes+ method for
+    # first attempting dispatch to the configured hash_paths, then to the configured hash_branches:
     #
     #   class App < Roda
     #     plugin :hash_routes
@@ -84,60 +35,14 @@ class Roda
     # +hash_path+ block.  Other requests for the +/a+ branch, and all requests for the +/b+
     # branch will be routed to the appropriate +hash_branch+ block.
     #
-    # Both +hash_branch+ and +hash_path+ support namespaces, which allows them to be used at
-    # any level of the routing tree.  Here is an example that uses namespaces for sub-branches:
-    #
-    #   class App < Roda
-    #     plugin :hash_routes
-    #
-    #     # Only one argument used, so the namespace defaults to '', and the argument
-    #     # specifies the route name
-    #     hash_branch("a") do |r|
-    #       # uses '/a' as the namespace when looking up routes,
-    #       # as that part of the path has been routed now
-    #       r.hash_routes
-    #     end
-    #
-    #     # Two arguments used, so first specifies the namespace and the second specifies
-    #     # the route name
-    #     hash_branch('', "b") do |r|
-    #       # uses :b as the namespace when looking up routes, as that was explicitly specified
-    #       r.hash_routes(:b)
-    #     end
-    #
-    #     hash_path("/a", "/b") do |r|
-    #       # /a/b path
-    #     end
-    #
-    #     hash_path("/a", "/c") do |r|
-    #       # /a/c path 
-    #     end
-    #
-    #     hash_path(:b, "/b") do |r|
-    #       # /b/b path
-    #     end
-    #
-    #     hash_path(:b, "/c") do |r|
-    #       # /b/c path 
-    #     end
-    #
-    #     route do |r|
-    #       # uses '' as the namespace, as no part of the path has been routed yet
-    #       r.hash_branches
-    #     end
-    #   end
-    #
-    # With the above routing tree, requests for the +/a+ and +/b+ branches will be
-    # dispatched to the appropriate +hash_branch+ block.  Those blocks will the dispatch
-    # to the +hash_path+ blocks, with the +/a+ branch using the implicit namespace of
-    # +/a+, and the +/b+ branch using the explicit namespace of +:b+.  In general, it
-    # is best for performance to explicitly specify the namespace when calling
-    # +r.hash_branches+, +r.hash_paths+, and +r.hash_routes+.
+    # It is best for performance to explicitly specify the namespace when calling
+    # +r.hash_routes+.
     #
     # Because specifying routes explicitly using the +hash_branch+ and +hash_path+
     # class methods can get repetitive, the hash_routes plugin offers a DSL for DRYing
-    # the code up.  This DSL is used by calling the +hash_routes+ class method.  Below
-    # is a translation of the previous example to using the +hash_routes+ DSL:
+    # the code up.  This DSL is used by calling the +hash_routes+ class method.  The
+    # DSL used tries to mirror the standard Roda DSL, but it is not a normal routing
+    # tree (it's not possible to execute arbitrary code between branches during routing).
     #
     #   class App < Roda
     #     plugin :hash_routes
@@ -264,9 +169,12 @@ class Roda
     # * views
     # * all verb methods (get, post, etc.)
     module HashRoutes
+      def self.load_dependencies(app)
+        app.plugin :hash_branches
+        app.plugin :hash_paths
+      end
+
       def self.configure(app)
-        app.opts[:hash_branches] ||= {}
-        app.opts[:hash_paths] ||= {}
         app.opts[:hash_routes_methods] ||= {}
       end
 
@@ -359,24 +267,10 @@ class Roda
       module ClassMethods
         # Freeze the hash_routes metadata when freezing the app.
         def freeze
-          opts[:hash_branches].freeze.each_value(&:freeze)
-          opts[:hash_paths].freeze.each_value(&:freeze)
           opts[:hash_routes_methods].freeze
           super
         end
 
-        # Duplicate hash_routes metadata in subclass.
-        def inherited(subclass)
-          super
-
-          [:hash_branches, :hash_paths].each do |k|
-            h = subclass.opts[k]
-            opts[k].each do |namespace, routes|
-              h[namespace] = routes.dup
-            end
-          end
-        end
-
         # Invoke the DSL for configuring hash routes, see DSL for methods inside the
         # block.  If the block accepts an argument, yield the DSL instance.  If the
         # block does not accept an argument, instance_exec the block in the context
@@ -393,66 +287,9 @@ class Roda
 
           dsl
         end
-
-        # Add branch handler for the given namespace and segment. If called without
-        # a block, removes the existing branch handler if it exists.
-        def hash_branch(namespace='', segment, &block)
-          segment = "/#{segment}"
-          routes = opts[:hash_branches][namespace] ||= {}
-          if block
-            routes[segment] = define_roda_method(routes[segment] || "hash_branch_#{namespace}_#{segment}", 1, &convert_route_block(block))
-          elsif meth = routes[segment]
-            routes.delete(segment)
-            remove_method(meth)
-          end
-        end
-
-        # Add path handler for the given namespace and path. When the
-        # r.hash_paths method is called, checks the matching namespace
-        # for the full remaining path, and dispatch to that block if
-        # there is one.  If called without a block, removes the existing
-        # path handler if it exists.
-        def hash_path(namespace='', path, &block)
-          routes = opts[:hash_paths][namespace] ||= {}
-          if block
-            routes[path] = define_roda_method(routes[path] || "hash_path_#{namespace}_#{path}", 1, &convert_route_block(block))
-          elsif meth = routes[path]
-            routes.delete(path)
-            remove_method(meth)
-          end
-        end
       end
 
       module RequestMethods
-        # Checks the matching hash_branch namespace for a branch matching the next
-        # segment in the remaining path, and dispatch to that block if there is one.
-        def hash_branches(namespace=matched_path)
-          rp = @remaining_path
-
-          return unless rp.getbyte(0) == 47 # "/"
-
-          if routes = roda_class.opts[:hash_branches][namespace]
-            if segment_end = rp.index('/', 1)
-              if meth = routes[rp[0, segment_end]]
-                @remaining_path = rp[segment_end, 100000000]
-                always{scope.send(meth, self)}
-              end
-            elsif meth = routes[rp]
-              @remaining_path = ''
-              always{scope.send(meth, self)}
-            end
-          end
-        end
-
-        # Checks the matching hash_path namespace for a branch matching the 
-        # remaining path, and dispatch to that block if there is one.
-        def hash_paths(namespace=matched_path)
-          if (routes = roda_class.opts[:hash_paths][namespace]) && (meth = routes[@remaining_path])
-            @remaining_path = ''
-            always{scope.send(meth, self)}
-          end
-        end
-
         # Check for matches in both the hash_path and hash_branch namespaces for
         # a matching remaining path or next segment in the remaining path, respectively.
         def hash_routes(namespace=matched_path)

data/lib/roda/plugins/heartbeat.rb

@@ -14,13 +14,6 @@ class Roda
     #
     #   plugin :heartbeat, path: '/status'
     module Heartbeat
-      # :nocov:
-      HEADER_CLASS = (defined?(Rack::Headers) && Rack::Headers.is_a?(Class)) ? Rack::Headers : Hash
-      # :nocov:
-      private_constant :HEADER_CLASS
-
-      HEARTBEAT_RESPONSE = [200, {'Content-Type'=>'text/plain'}.freeze, ['OK'.freeze].freeze].freeze
-
       # Set the heartbeat path to the given path.
       def self.configure(app, opts=OPTS)
         app.opts[:heartbeat_path] = (opts[:path] || app.opts[:heartbeat_path] || "/heartbeat").dup.freeze
@@ -32,9 +25,11 @@ class Roda
         # If the request is for a heartbeat path, return the heartbeat response.
         def _roda_before_20__heartbeat
           if env['PATH_INFO'] == opts[:heartbeat_path]
-            response = HEARTBEAT_RESPONSE.dup
-            response[1] = HEADER_CLASS[response[1]]
-            throw :halt, response
+            response = @_response
+            response.status = 200
+            response['Content-Type'] = 'text/plain'
+            response.write 'OK'
+            throw :halt, response.finish
           end
         end
       end

data/lib/roda/plugins/mail_processor.rb

@@ -465,7 +465,11 @@ class Roda
             def #{field}(address, &block)
               on(:#{field}=>address, &block)
             end
+          END
+
+          next if [:rcpt, :text, :body, :subject].include?(field)
 
+          class_eval(<<-END, __FILE__, __LINE__+1)
             private
 
             def match_#{field}(address)
@@ -474,11 +478,6 @@ class Roda
           END
         end
 
-        undef_method :match_rcpt
-        undef_method :match_text
-        undef_method :match_body
-        undef_method :match_subject
-
         # Same as +header+, but also mark the message as being handled.
         def handle_header(key, value=nil)
           header(key, value) do |*args|

data/lib/roda/plugins/multi_route.rb

@@ -8,7 +8,7 @@ class Roda
     # which will check # if the first segment in the path matches a named route,
     # and dispatch to that named route.
     #
-    # The hash_routes plugin offers a +r.hash_routes+ method that is similar to
+    # The hash_branches plugin offers a +r.hash_branches+ method that is similar to
     # and performs better than the +r.multi_route+ method, and it is recommended
     # to consider using that instead of this plugin.
     #

data/lib/roda/plugins/multi_view.rb

@@ -16,10 +16,6 @@ class Roda
     # +multi_view_compile+ class method that will take an array of view template
     # names and construct a regexp that can be passed to +r.multi_view+.
     #
-    # The hash_routes plugin offers a views method that is similar to and performs
-    # better than the +r.multi_view+ method, and it is recommended to consider
-    # using that instead of this plugin.
-    #
     # Example:
     #
     #   plugin :multi_view

data/lib/roda/plugins/named_routes.rb

@@ -145,8 +145,7 @@ class Roda
             routes = opts[:namespaced_routes][namespace] ||= {}
             if block
               routes[name] = define_roda_method(routes[name] || "named_routes_#{namespace}_#{name}", 1, &convert_route_block(block))
-            elsif meth = routes[name]
-              routes.delete(name)
+            elsif meth = routes.delete(name)
               remove_method(meth)
             end
           else

data/lib/roda/plugins/static_routing.rb

@@ -50,7 +50,7 @@ class Roda
     # while still handling the request methods differently.
     module StaticRouting
       def self.load_dependencies(app)
-        app.plugin :hash_routes
+        app.plugin :hash_paths
       end
 
       module ClassMethods

data/lib/roda/version.rb

@@ -4,7 +4,7 @@ class Roda
   RodaMajorVersion = 3
 
   # The minor version of Roda, updated for new feature releases of Roda.
-  RodaMinorVersion = 56
+  RodaMinorVersion = 59
 
   # The patch version of Roda, updated only for bug fixes from the last
   # feature release.

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: roda
 version: !ruby/object:Gem::Version
-  version: 3.56.0
+  version: 3.59.0
 platform: ruby
 authors:
 - Jeremy Evans
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2022-05-13 00:00:00.000000000 Z
+date: 2022-08-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rack
@@ -228,6 +228,9 @@ extra_rdoc_files:
 - doc/release_notes/3.54.0.txt
 - doc/release_notes/3.55.0.txt
 - doc/release_notes/3.56.0.txt
+- doc/release_notes/3.57.0.txt
+- doc/release_notes/3.58.0.txt
+- doc/release_notes/3.59.0.txt
 - doc/release_notes/3.6.0.txt
 - doc/release_notes/3.7.0.txt
 - doc/release_notes/3.8.0.txt
@@ -291,6 +294,9 @@ files:
 - doc/release_notes/3.54.0.txt
 - doc/release_notes/3.55.0.txt
 - doc/release_notes/3.56.0.txt
+- doc/release_notes/3.57.0.txt
+- doc/release_notes/3.58.0.txt
+- doc/release_notes/3.59.0.txt
 - doc/release_notes/3.6.0.txt
 - doc/release_notes/3.7.0.txt
 - doc/release_notes/3.8.0.txt
@@ -302,6 +308,7 @@ files:
 - lib/roda/plugins/_before_hook.rb
 - lib/roda/plugins/_optimized_matching.rb
 - lib/roda/plugins/_symbol_regexp_matchers.rb
+- lib/roda/plugins/additional_render_engines.rb
 - lib/roda/plugins/additional_view_directories.rb
 - lib/roda/plugins/all_verbs.rb
 - lib/roda/plugins/assets.rb
@@ -334,10 +341,14 @@ files:
 - lib/roda/plugins/error_handler.rb
 - lib/roda/plugins/error_mail.rb
 - lib/roda/plugins/exception_page.rb
+- lib/roda/plugins/filter_common_logger.rb
 - lib/roda/plugins/flash.rb
 - lib/roda/plugins/h.rb
 - lib/roda/plugins/halt.rb
+- lib/roda/plugins/hash_branch_view_subdir.rb
+- lib/roda/plugins/hash_branches.rb
 - lib/roda/plugins/hash_matcher.rb
+- lib/roda/plugins/hash_paths.rb
 - lib/roda/plugins/hash_routes.rb
 - lib/roda/plugins/head.rb
 - lib/roda/plugins/header_matchers.rb