roda 3.54.0 → 3.57.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '083b83c9271643842b60c7027b16a3ed2068fef54423b3a80dae73ffa991b0cf'
-  data.tar.gz: c2b9efd6155dd597f13e7167ce6ad6044f8692fb5dafa7994c1527c3a94f1641
+  metadata.gz: 578868ccd08ba1fa91302273c92176def99072db735ec119d13cbf49e78a7249
+  data.tar.gz: b95b2a33a18a3b135f494ba7f0ffa1639a5fd876b0b199f414826cab7fa75a9d
 SHA512:
-  metadata.gz: e33b2bc1b476bb103d380ac0b310e09640a0bdbce160c7307c92fba93b2dbb2f2a149b2ea3e1db65701354ab274d4d5cea03a7d813f9c81b271bb43d31915503
-  data.tar.gz: 9c3f7d67ed534f769ba453974b2dca02318a3330064d5f350ed6f8e0d25314513d884cddbaa6a0e0b9fae36b962fec659db050ced37e543201d4271099813eda
+  metadata.gz: 2b7b769a1653315b1fd9bca1a993ff0e699f2a09fb4db135304d8c7473f2c834c61b91e188005ac029fd85feaca6cc6a106efdd83f0e53771cddd8f3a73204aa
+  data.tar.gz: 7bdc602a54f8f5b34a7edc0355b3e6a426b29dd4671c30ef9d7712c757e116c9e6679cd08884f28c7636a80560878284ff4de479f0c479d905948ebfce9b12b3

data/CHANGELOG

@@ -1,3 +1,35 @@
+= 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)
+
+* Add :forward_response_headers middleware plugin option to use app headers as default for response (janko) (#259)
+
 = 3.54.0 (2022-03-14)
 
 * Make chunked plugin not use Transfer-Encoding: chunked by default (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.55.0.txt

@@ -0,0 +1,12 @@
+= New Features
+
+* A :forward_response_headers option has been added to the middleware
+  plugin, which uses the response headers added by the middleware
+  as default response headers even if the middleware does not handle
+  the response. Response headers set by the underlying application
+  take precedence over response headers set by the middleware.
+
+* The render plugin view method now accepts a block and will pass the
+  block to the underlying render method call.  This is useful for
+  rendering a template that yields inside of an existing layout.
+  Previously, you had to nest render calls to do that.

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

@@ -215,7 +215,7 @@ class Roda
         # If chunking by default, call chunked if it hasn't yet been
         # called and chunking is not specifically disabled.
         def view(*a)
-          if opts[:chunk_by_default] && !defined?(@_chunked)
+          if opts[:chunk_by_default] && !defined?(@_chunked) && !defined?(yield)
             chunked(*a)
           else
             super
@@ -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/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