roda 3.55.0 → 3.58.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1b862c4eb1dcca9fbbf0ccacc130779fdecf610a5a064ef94c17384d073e29dd
-  data.tar.gz: 1e9a991190a6572283350bf1941fca8b83f8496bc519156d5ec3cc5d613d2407
+  metadata.gz: 01acdb87d6bf21ec4137dd2b6c7e3210c5923c43f188a510135c30a66945160a
+  data.tar.gz: e84ddddfbfe23a4be3951c2611f38916cb6dfb60b15c1a6bfd18155869ad4985
 SHA512:
-  metadata.gz: 55fdc91ab21dbb1cf6884ee6b0384ef15db41f830d704ec6c445435ec76e302cb166f18c6f032390193c6d43d6922c7762d03768fd5c22188c3c7f937dc21d4a
-  data.tar.gz: d1272f1fc0e2707d2daf590ea71a4970ae2b133f0b4ba669e60296d6900422d3746bff8722d44eb636df5aefab0bd6b51382b88de1265924c4243322646335e7
+  metadata.gz: 1681a1b8b8eb950be113d1a533c545ed0a71c24dc6d027a41d2cddb1ae99e4a2c2d23fc0e4c84d1f2960fd141021684d37d75e8509b247d732203100eae6ab2f
+  data.tar.gz: a21456321d0ab6f3c32d4ba97dabd31635751caee7889a2b556dd17cc74fb019d974cc06500081a859402cbf8002a26144d4885dbd8c47589852395d1e398ed2

data/CHANGELOG

@@ -1,3 +1,37 @@
+= 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)
+
+* Add RodaRequest#http_version for determining the HTTP version in use (jeremyevans)
+
+* Do not set a body for 405 responses when using the verb methods in the not_allowed plugin (jeremyevans) (#267)
+
+* Support status_handler method :keep_headers option in status_handler plugin (jeremyevans) (#267)
+
+* Make not_allowed plugin have r.root return 405 responses for non-GET requests (jeremyevans) (#266)
+
+* In Rack 3, only require the parts of rack used by Roda, instead of requiring rack itself and relying on autoload (jeremyevans)
+ 
+* Add run_require_slash plugin, for skipping application dispatch for remaining paths that would violate Rack SPEC (jeremyevans)
+
 = 3.55.0 (2022-04-12)
 
 * Allow passing blocks to the view method in the render plugin (jeremyevans) (#262)

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.56.0.txt

@@ -0,0 +1,33 @@
+= New Features
+
+* RodaRequest#http_version has been added for determining the HTTP
+  version the request was submitted with.  This will be a string
+  such as "HTTP/1.0", "HTTP/1.1", "HTTP/2", etc. This will use the
+  SERVER_PROTOCOL and HTTP_VERSION entries from the environment to
+  determine which HTTP version is in use.
+
+* The status_handler method in the status_handler plugin now supports
+  a :keep_headers option.  The value for this option should be an
+  array of header names to keep.  All other headers are removed. The
+  default behavior without the option is still to remove all headers.
+
+* A run_require_slash plugin has been added, which will skip
+  dispatching to another rack application if the remaining path is not
+  empty and does not start with a slash.
+
+= Other Improvements
+
+* The status_303 plugin will use 303 as the default redirect status
+  for non-GET requests for HTTP/2 and higher HTTP versions. Previously,
+  it only used 303 for HTTP/1.1.
+
+* The not_allowed plugin now overrides the r.root method to return
+  405 responses to non-GET requests to the root.
+
+* The not_allowed plugin no longer sets the body when returning 405
+  responses using methods such as r.get and r.post. Previously, the
+  body was unintentionally set to the same value as the Allow header.
+
+* When using the Rack master branch (what will become Rack 3), Roda
+  only requires the parts of rack that it uses, instead of requiring
+  rack and relying on autoload to load the parts of rack in use.

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/lib/roda/plugins/chunked.rb

@@ -226,7 +226,7 @@ class Roda
         # an overview.  If a block is given, it is passed to #delay.
         def chunked(template, opts=OPTS, &block)
           unless defined?(@_chunked)
-            @_chunked = !self.opts[:force_chunked_encoding] || env['HTTP_VERSION'] == "HTTP/1.1" 
+            @_chunked = !self.opts[:force_chunked_encoding] || @_request.http_version == "HTTP/1.1" 
           end
 
           if block

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?)} #{env["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/cookies.rb

@@ -1,5 +1,7 @@
 # frozen-string-literal: true
 
+require 'rack/utils'
+
 #
 class Roda
   module RodaPlugins

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