roda 3.18.0 → 3.19.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f39ffb4b00598e7e113f06c2f6e43e968f96b2a447059de8b351c7f5cc35675a
-  data.tar.gz: eacc16913dcfd72ad822fd8b6f25e132be80123c25a6a0c29869b39a13f04b50
+  metadata.gz: 930b16a28e9acd91a802b03248b36f940ee50f22b387e2e6839b34513b181c19
+  data.tar.gz: ff504ecc1d793e7af9180742204e219e26838f2187c0538241e2c240d57d4ad9
 SHA512:
-  metadata.gz: 8aec053c2bda39f201cb03043cfe382d5982e5e16abca381ba76220603a25d680425a8aaf4b405f4134caef4336e3586e83d2ae0f43e8c7a40279650927237d3
-  data.tar.gz: 104867afa6a526d13acd76eab634eaf9688f44131606e1c7c67f73f1464c662d16d76938217c0b878deb0d7e6217ae5586fc2764be13cdd64298b5256bd4b3b8
+  metadata.gz: 472f855ac1ea091a973d5396dd5950147cdee2f72fa4692233e0acca033ed989ad3d7c7aa338c053058b070efaa151de4b40ad475a9a14e70a32a21e81fe0f3c
+  data.tar.gz: bc8c7417ec1922531a2a535b57ca3528fe0de9731df0aaed520d9e3df22263fa96f23eadf2313284a8f03af3e77addafaf45c1fc0061e3795e01b3dd18024922

data/CHANGELOG

@@ -1,3 +1,27 @@
+= 3.19.0 (2019-04-12)
+
+* Allow assets plugin :timestamp_paths option to be a string to specify a custom separator (jeremyevans)
+
+* Fix handling for blocks with arity > 1 where expected arity is 1 (jeremyevans)
+
+* Improve performance for handling blocks with arity 0 where expected arity is 1 by avoiding instance_exec (jeremyevans)
+
+* Improve terminal maching by around 4x (jeremyevans)
+
+* Improve symbol matching by 10-20% (jeremyevans)
+
+* Improve string matching by 10-20% (jeremyevans)
+
+* Automatically load the direct_call plugin when freezing if no middleware is used for better performance (jeremyevans)
+
+* Delay building rack app until Roda.app is called (jeremyevans)
+
+* Add hash_routes plugin for O(1) route dispatching at any level in the routing tree (jeremyevans)
+
+* Add support for per-cookie cipher secrets in the sessions plugin, and enable them by default (jeremyevans)
+
+* Add match_hook plugin for calling hooks when there is a successful match block (adam12) (#164)
+
 = 3.18.0 (2019-03-15)
 
 * Add direct_call plugin for making Roda.call skip middleware, allowing more optimization when dispatching routes (jeremyevans)

data/README.rdoc

@@ -633,25 +633,23 @@ If you have a lot of rack applications that you want to dispatch to, and
 which one to dispatch to is based on the request path prefix, look into the
 +multi_run+ plugin.
 
-=== multi_route plugin
+=== hash_routes plugin
 
 If you are just looking to split up the main route block up by branches,
-you should use the +multi_route+ plugin,
+you should use the +hash_routes+ plugin,
 which keeps the current scope of the +route+ block:
 
   class App < Roda
-    plugin :multi_route
+    plugin :hash_routes
 
-    route "api" do |r|
+    hash_branch "api" do |r|
       r.is do
         # ...
       end
     end
 
     route do |r|
-      r.on "api" do
-        r.route "api"
-      end
+      r.hash_routes
     end
   end
 
@@ -662,8 +660,8 @@ and still have access to them inside the +api+ +route+ block.
 
 == Testing
 
-It is very easy to test Roda with {Rack::Test}[https://github.com/brynary/rack-test]
-or {Capybara}[https://github.com/jnicklas/capybara].
+It is very easy to test Roda with {Rack::Test}[https://github.com/rack-test/rack-test]
+or {Capybara}[https://github.com/teamcapybara/capybara].
 Roda's own tests use {minitest/spec}[https://github.com/seattlerb/minitest].
 The default Rake task will run the specs for Roda.
 

data/doc/conventions.rdoc

@@ -78,14 +78,14 @@ 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 +multi_route+ and +view_options+ plugin, or the +multi_run+ plugin.
-The routes used by the +multi_route+ or +multi_run+ should be stored in routing files in the +routes/+
++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/+
 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/+.
 
-You should have a separate view subdirectory per prefix. If you are using +multi_route+ and +view_options+ plugins,
+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.
 
@@ -95,7 +95,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 +multi_route+ or +multi_run+ plugins to organize your application, and have
+it is recommended to use the +hash_routes+ 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
@@ -112,7 +112,7 @@ For a small application, the convention in Roda is to layout your Roda applicati
 
     use SomeMiddleware
 
-    plugin :render
+    plugin :render, escape: true
     plugin :assets
 
     route do |r|
@@ -145,21 +145,21 @@ For larger applications, there are some slight changes to the Roda application f
 
     use SomeMiddleware
 
-    plugin :render
+    plugin :render, escape: true
     plugin :assets
     plugin :view_options
-    plugin :multi_route
+    plugin :hash_routes
     Dir['./routes/*.rb'].each{|f| require f}
 
     route do |r|
-      r.multi_route
+      r.hash_routes
     end
 
     Dir['./helpers/*.rb'].each{|f| require f}
   end
 
-After loading the +view_options+ and +multi_route+ plugin, you require all of your
+After loading the +view_options+ and +hash_routes+ plugin, you require all of your
 routing files.  Inside your route block, instead of defining your routes, you just call
-+r.multi_route+, which will dispatch to all of your routing files.  After your route
++r.hash_routes+, 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.19.0.txt

@@ -0,0 +1,229 @@
+= New Features
+
+* A hash_routes plugin has been added for O(1) route dispatching at
+  any level of the routing tree.  By default, Roda uses a linear
+  search of possible branches at each level of the routing tree,
+  which results in roughly O(log(n)) routing behavior in most
+  applications (where n is the total number of routes in the
+  application).
+  
+  Assume you have the following routing tree:
+
+    route do |r|
+      r.on "a" do
+        # ...
+      end
+
+      r.on "b" do
+        # ...
+      end
+
+      r.is "c" do
+        # ...
+      end
+
+      # ...
+    end
+
+  With this routing tree, a request for /c will first check /a and
+  /b.  This is not normally a performance issue, but if you have a
+  large number of routes at a particular level, it can be.
+
+  The hash_routes plugin allows you to convert this routing tree to:
+
+    plugin :hash_routes
+
+    hash_routes do
+      on "a" do |r|
+        # ...
+      end
+
+      on "b" do |r|
+        # ...
+      end
+
+      is "c" do |r|
+        # ...
+      end
+
+      # ...
+    end
+
+    route do |r|
+      r.hash_routes
+    end
+
+  This routing tree looks similar to Roda's standard routing tree, and
+  will have the same behavior as the previous example, but dispatching
+  to the routes inside the hash_routes block by the r.hash_routes
+  method will be an O(1) operation, instead of a linear search.  This
+  can significantly improve performance in cases where you have a large
+  number of branches at any point in the routing tree.
+
+  In order to support O(1) route dispatching at any level of the
+  tree, the hash_routes plugin supports namespaces.  You can use this
+  namespace support to keep the primary advantage of Roda when using
+  the hash_routes plugin, which is the ability to operate on a request
+  at any point during routing.  Assume you have this routing tree:
+
+    hash_routes :root do
+      on "foo" do |r|
+        r.on Integer do |foo_id|
+          next unless @foo = Foo[foo_id]
+          r.hash_routes(:foo)
+        end
+      end
+
+      on "bar" do |r|
+        r.on Integer do |bar_id|
+          next unless @bar = Bar[bar_id]
+          r.hash_routes(:bar)
+        end
+      end
+
+      # ...
+    end
+
+    hash_routes :foo do
+      get "show" do
+        @page_title = @foo.name
+        view('foo/show')
+      end
+
+      # ...
+    end
+
+    hash_routes :bar do
+      post "edit" do
+        @bar.update(:name=>request.params['name'])
+        r.redirect "/"
+      end
+
+      # ...
+    end
+
+    route do |r|
+      r.hash_routes(:root)
+    end
+
+  With this routing tree, a GET /foo/123/show request will first get
+  dispatched to the on "foo" block in the :root namespace.  That will
+  extract the 123 segment from the path, and use it to find the Foo
+  object with id 123 and set that to the instance variable @foo.
+  If there is no matching foo, the rest of the block will be skipped,
+  which will result in a 404 response.  If there is a matching foo,
+  after setting the instance variable, it will dispatch to routes in
+  the :foo namespace, one of which is show, which will be able to use
+  the @foo variable, both in the route and in the view.
+  
+  Similarly, a POST /bar/321/edit request would dispatch to the on
+  "bar" block in the :root namespace, will look up the matching bar,
+  then will dispatch to the edit route in the :bar namespace.
+
+  The hash_routes plugin can be used as a faster version of the
+  multi_route plugin's r.multi_route method.  It can also be used as
+  a faster replacement for the multi_view plugin.
+  
+  Please see the hash_routes plugin documentation for additional
+  methods and configuration styles supported by the plugin.
+
+* A match_hook plugin has been added, which is called for each
+  successful match, before yielding to the match block.  For example,
+  with the following routing tree:
+
+    plugin :match_hook
+
+    match_hook do
+      puts "#{r.matched_path}|#{r.remaining_path}"
+    end
+
+    route do |r|
+      r.on "a" do
+        r.is "b" do
+          r.get do
+          end
+
+          r.post do
+          end
+        end
+      end
+    end
+
+  A GET request for /a/b would call the match hook three times, and
+  output the following:
+
+    /a|/b # When the r.on block matches
+    /a/b| # When the r.is block matches
+    /a/b| # When the r.get block matches
+
+  A GET request for /a/c would call the match hook once, and output
+  the following:
+
+    /a|/b # When the r.on block matches
+
+  This plugin can be used to make debugging easier, as well as for
+  metrics.
+
+= Other Improvements
+
+* Per-cookie cipher secrets are now supported and used automatically
+  by default in the sessions plugin.  This can prevent issues where
+  the cipher secret can be leaked if the random initialization vector
+  turns out not to be so random and ends up being reused.  This
+  makes the session cookies slightly larger and about 10-20% slower.
+
+  Note that because of the way the sessions plugin is designed,
+  even if the cipher secret was leaked and you are not using
+  per-cookie cipher secrets, it would not allow an attacker to
+  forge a session, it would only allow them to read the contents of
+  an existing session.
+
+  If you are currently using the sessions plugin, and performing
+  rolling restarts, you should temporarily disable per-cookie session
+  secrets until all processes have been restarted and are able to
+  support per-cookie session secrets.  You can do so by setting the
+  :per_cookie_cipher_secret sessions plugin option to false
+  temporarily until all processes have restarted and are running Roda
+  3.19.0+.
+
+* When passing route blocks to Roda that have 0 arity instead of the
+  expected arity of 1, emulate an arity of 1 using an approach that is
+  about 2.75-8x faster.  This emulation is still about 20% slower than
+  using the expected arity.
+
+* Fix emulation of route blocks that have >1 arity but where the
+  expected arity is 1.  Such blocks were not handled correctly in
+  Roda 3.18.0.
+
+* String matching performance has been improved by 10-20%.
+
+* Symbol and String class matching performance has improved by 10-20%.
+
+* Terminal matching performance has improved by about 4x.
+
+* Roda will now automatically load the direct_call plugin when
+  freezing the application if there is no middleware used and the
+  application has not been subclassed, for improved performance.
+
+* Roda no longer builds the rack application until the app class
+  method is called.  This can fix O(n^2) issues when building
+  applications with a lot of middleware.  One consequence of
+  this is that a Roda.route block is no longer required. If
+  Roda.route is not called, then the default routing tree will
+  return a 404 response for all requests.
+
+  The delay_build plugin used to support delaying building the rack
+  application until a build! method is called.  Now that Roda delays
+  building the rack application until the app method is called, there
+  is no reason to use this plugin, and it is now a no-op.
+
+* The assets plugin :timestamp_paths option now supports a string
+  value to use a custom separator. A slash separator is still used
+  by default.
+
+= Backwards Compatibility
+
+* The static_routing plugin internals have changed, as the
+  static_routing is now implemented via the hash_routes plugin.  If
+  you were depending on the internals, you will need to update your
+  code.

data/lib/roda.rb

@@ -118,7 +118,9 @@ class Roda
       # Class methods for the Roda class.
       module ClassMethods
         # The rack application that this class uses.
-        attr_reader :app
+        def app
+          @app || build_rack_app
+        end
 
         # Whether middleware from the current class should be inherited by subclasses.
         # True by default, should be set to false when using a design where the parent
@@ -142,7 +144,7 @@ class Roda
         # Clear the middleware stack
         def clear_middleware!
           @middleware.clear
-          build_rack_app
+          @app = nil
         end
 
         # Define an instance method using the block with the provided name and
@@ -172,6 +174,7 @@ class Roda
           if meth.is_a?(String)
             meth = roda_method_name(meth)
           end
+          call_meth = meth
 
           if (check_arity = opts.fetch(:check_arity, true)) && !block.lambda?
             required_args, optional_args, rest, keyword = _define_roda_method_arg_numbers(block)
@@ -194,8 +197,15 @@ class Roda
                 if check_arity == :warn
                   RodaPlugins.warn "Arity mismatch in block passed to define_roda_method. Expected Arity 1, but no arguments accepted for #{block.inspect}"
                 end
+                temp_method = roda_method_name("temp")
+                class_eval("def #{temp_method}(_) #{meth =~ /\A\w+\z/ ? "#{meth}_arity" : "send(:\"#{meth}_arity\")"} end", __FILE__, __LINE__)
+                alias_method meth, temp_method
+                undef_method temp_method
+                private meth
+                meth = :"#{meth}_arity"
+              elsif required_args > 1
                 b = block
-                block = lambda{|_| instance_exec(&b)} # Fallback
+                block = lambda{|r| instance_exec(r, &b)} # Fallback
               end
             when :any
               if check_dynamic_arity = opts.fetch(:check_dynamic_arity, check_arity)
@@ -239,10 +249,9 @@ class Roda
               send(meth, *a)
             end
             private arity_meth
-            arity_meth
-          else
-            meth
           end
+
+          call_meth
         end
 
         # Expand the given path, using the root argument as the base directory.
@@ -258,8 +267,7 @@ class Roda
         # Note that freezing the class prevents you from subclassing it, mostly because
         # it would cause some plugins to break.
         def freeze
-          @opts.freeze
-          @middleware.freeze
+          return self if frozen?
 
           unless opts[:subclassed]
             # If the _roda_run_main_route instance method has not been overridden,
@@ -276,8 +284,16 @@ class Roda
                 end
               end
             end
+
+            if @middleware.empty? && use_new_dispatch_api?
+              plugin :direct_call
+            end
           end
 
+          build_rack_app
+          @opts.freeze
+          @middleware.freeze
+
           super
         end
 
@@ -340,7 +356,7 @@ class Roda
           self::RodaResponse.send(:include, plugin::ResponseMethods) if defined?(plugin::ResponseMethods)
           self::RodaResponse.extend(plugin::ResponseClassMethods) if defined?(plugin::ResponseClassMethods)
           plugin.configure(self, *args, &block) if plugin.respond_to?(:configure)
-          nil
+          @app = nil
         end
 
         # Setup routing tree for the current Roda application, and build the
@@ -366,7 +382,7 @@ class Roda
           @route_block = block = convert_route_block(block)
           @rack_app_route_block = block = rack_app_route_block(block)
           public define_roda_method(:_roda_main_route, 1, &block)
-          build_rack_app
+          @app = nil
         end
 
         # Add a middleware to use for the rack application.  Must be
@@ -375,7 +391,7 @@ class Roda
         #   Roda.use Rack::ShowExceptions
         def use(*args, &block)
           @middleware << [args, block].freeze
-          build_rack_app
+          @app = nil
         end
 
         private
@@ -426,29 +442,15 @@ class Roda
 
         # Build the rack app to use
         def build_rack_app
-          if @rack_app_route_block
-            # RODA4: Assume optimize is true
-            optimize = ancestors.each do |mod|
-              break true if mod == InstanceMethods
-              meths = mod.instance_methods(false)
-              if meths.include?(:call) && !(meths.include?(:_roda_handle_main_route) || meths.include?(:_roda_run_main_route))
-              RodaPlugins.warn <<WARNING
-Falling back to using #call for dispatching for #{self}, due to #call override in #{mod}.
-#{mod} should be fixed to adjust to Roda's new dispatch API, and override _roda_handle_main_route or _roda_run_main_route
-WARNING
-                break false
-              end
-            end
-
-            app = base_rack_app_callable(optimize)
+          app = base_rack_app_callable(use_new_dispatch_api?)
 
-            @middleware.reverse_each do |args, bl|
-              mid, *args = args
-              app = mid.new(app, *args, &bl)
-              app.freeze if opts[:freeze_middleware]
-            end
-            @app = app
+          @middleware.reverse_each do |args, bl|
+            mid, *args = args
+            app = mid.new(app, *args, &bl)
+            app.freeze if opts[:freeze_middleware]
           end
+
+          @app = app
         end
 
         # Modify the route block to use for any route block provided as input,
@@ -499,6 +501,24 @@ WARNING
           block
         end
 
+        # Whether the new dispatch API should be used.
+        def use_new_dispatch_api?
+          # RODA4: remove this method
+          ancestors.each do |mod|
+            break if mod == InstanceMethods
+            meths = mod.instance_methods(false)
+            if meths.include?(:call) && !(meths.include?(:_roda_handle_main_route) || meths.include?(:_roda_run_main_route))
+            RodaPlugins.warn <<WARNING
+Falling back to using #call for dispatching for #{self}, due to #call override in #{mod}.
+#{mod} should be fixed to adjust to Roda's new dispatch API, and override _roda_handle_main_route or _roda_run_main_route
+WARNING
+              return false
+            end
+          end
+
+          true
+        end
+
         method_num = 0
         method_num_mutex = Mutex.new
         # Return a unique method name symbol for the given suffix.
@@ -1017,13 +1037,34 @@ WARNING
         # request path is a slash (indicating a new segment).
         def _match_string(str)
           rp = @remaining_path
-          if rp.start_with?("/#{str}")
-            last = str.length + 1
-            case rp[last]
-            when "/"
-              @remaining_path = rp[last, rp.length]
+          length = str.length
+
+          match = case rp.rindex(str, length)
+          when nil
+            # segment does not match, most common case
+            return
+          when 1
+            # segment matches, check first character is /
+            rp.getbyte(0) == 47
+          else # must be 0
+            # segment matches at first character, only a match if
+            # empty string given and first character is /
+            length == 0 && rp.getbyte(0) == 47
+          end
+
+          if match 
+            length += 1
+            case rp.getbyte(length)
+            when 47
+              # next character is /, update remaining path to rest of string
+              @remaining_path = rp[length, 100000000]
             when nil
+              # end of string, so remaining path is empty
               @remaining_path = ""
+            # else
+              # Any other value means this was partial segment match,
+              # so we return nil in that case without updating the
+              # remaining_path.  No need for explicit else clause.
             end
           end
         end
@@ -1031,7 +1072,7 @@ WARNING
         # Match the given symbol if any segment matches.
         def _match_symbol(sym=nil)
           rp = @remaining_path
-          if rp[0, 1] == "/"
+          if rp.getbyte(0) == 47
             if last = rp.index('/', 1)
               if last > 1
                 @captures << rp[1, last-1]
@@ -1117,7 +1158,7 @@ WARNING
 
         # Whether the current path is considered empty.
         def empty_path?
-          remaining_path == ""
+          remaining_path.empty?
         end
 
         # If all of the arguments match, yields to the match block and
@@ -1148,18 +1189,20 @@ WARNING
             _match_class(matcher)
           when TERM
             empty_path?
-          when Symbol
-            _match_symbol(matcher)
           when Regexp
             _match_regexp(matcher)
-          when Hash
-            _match_hash(matcher)
+          when true
+            matcher
           when Array
             _match_array(matcher)
+          when Hash
+            _match_hash(matcher)
+          when Symbol
+            _match_symbol(matcher)
+          when false, nil
+            matcher
           when Proc
             matcher.call
-          when true, false, nil
-            matcher
           else
             unsupported_matcher(matcher)
           end