roda-cj 0.9.2 → 0.9.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 2f2740123aa0c6fafe4c1665f9c83e408cef9105
-  data.tar.gz: 74ec8c03a23405c2ac18eb23ceea5ccb3f4813c1
+  metadata.gz: 5360a34504fec1081e28143f1f2ce25c69747061
+  data.tar.gz: a593de99e0868ce9478922e9fc1a775fd28afaf7
 SHA512:
-  metadata.gz: 876514335f729d2beeea7b218bc14d7cac1772f5b568a4a985457b01321c16ef33116bb3dd605e218d3512185d34dffaca426b9e803d0e860c56619eb2838359
-  data.tar.gz: d046733fe6737ccabc612523c7812b1be778cea3675223a1a5bc3c202a91fad2da26e2fac842789542368fcb95e0b8d201cff9235de3410c3e1e5e414314f1f0
+  metadata.gz: 7bf78f056f2b0d1e034e7fab2be1a9dfaad92261c72e692da8c9bcdae895fefa10c348cb8a950445c769b7f7e944e110481e8d066d7a517043a175e647e952be
+  data.tar.gz: d963a3e7c9d02a9077d7f77678d7292b427b8d55ee21b614b7ebd1a401dccd83e9e4d037dd58d319b0490748cf3c33935206437e54ea908365ed8058d6892081

data/CHANGELOG

@@ -1,5 +1,31 @@
 = HEAD
 
+* Add backtracking_array plugin, allowing array matchers to backtrack if later matchers do not match (jeremyevans)
+
+* Add :all hash matcher, allowing array matchers to include conditions where you want to match multiple conditions (jeremyevans)
+
+* Add json plugin, allowing match blocks to return arrays/hashes, returning JSON (jeremyevans)
+
+* Add view_subdirs plugin, for setting a subdirectory for views on a per-request basis (jeremyevans)
+
+* Allow default halt method to take no arguments, and use the current response (jeremyevans)
+
+* Add symbol_views plugin, allowing match blocks to return a template name symbol (jeremyevans)
+
+* Add per_thread_caching plugin, for using separate caches per thread instead of shared thread-safe caches (jeremyevans)
+
+* Add hash_matcher class method, for easily creating hash match methods (jeremyevans)
+
+* Add symbol_matchers plugin, for using symbol-specific matching regexps (jeremyevans)
+
+* Add csrf plugin for csrf protection using rack_csrf (jeremyevans)
+
+* Optimize r.is, r.get, r.post and similar methods by reducing the number of Array objects created (jeremyevans)
+
+* Support RequestClassMethods and ResponseClassMethods in plugins (jeremyevans)
+
+* Add Roda::RodaCache for a thread safe cache, currently used for match patterns, templates, and plugins (jeremyevans)
+
 * Optimize matching by caching consume regexp for strings, regexp, symbol, and :extension matchers (jeremyevans)
 
 * Add r.root for matching root (path "/"), for easier to read version of r.is "" (jeremyevans)

data/README.rdoc

@@ -268,20 +268,17 @@ This makes it easy to handle multiple strings without a Regexp:
 
 === Hash
 
-Hashes call a <tt>match_*</tt> method with the given key using the hash value,
-and match if that matcher returns true.
-
+Hashes allow easily calling specialized match methods on the request.
 The default registered matchers included with Roda are documented below.
-You can add your own hash matchers by adding the appropriate <tt>match_*</tt>
-method to the request class using the +request_module+ method:
+You can add your own hash matchers using the +hash_matcher+ class method,
+which creates an appropriate request match method.  The +hash_matcher+
+block will be called with the value of the hash.
 
   class App < Roda
-    request_module do
-      def match_foo(v)
-        ...
-      end
+    hash_matcher(:foo) do |v|
+      ...
     end
-
+    
     route do |r|
       r.on :foo=>'bar' do
         ...
@@ -289,6 +286,27 @@ method to the request class using the +request_module+ method:
     end
   end
 
+==== :all
+
+The :all matcher matches if all of the entries in the given array matches. So
+
+  r.on :all=>[:a, :b] do
+    ...
+  end
+
+is the same as:
+
+  r.on :a, :b do
+    ...
+  end
+
+The reason it also exists as a separate hash matcher is so you can use it inside
+an array matcher. so:
+
+  r.on ['foo', {:all=>['foos', :id]}] do
+  end
+
+Would match +/foo+ and +/foos/10+, but not +/foos+.
 
 ==== :extension
 
@@ -605,6 +623,7 @@ or modifying the +render_opts+ hash after loading the plugin:
     render_opts[:layout] = "admin_layout" # Default layout template
     render_opts[:layout_opts] = {:engine=>'haml'} # Default layout template options
     render_opts[:opts] = {:default_encoding=>'UTF-8'} # Default template options
+    render_opts[:cache] = false # Disable template caching
   end
 
 == Plugins
@@ -617,6 +636,10 @@ override any Roda method and call +super+ to get the default behavior.
 These plugins ship with roda:
 
 all_verbs :: Adds routing methods to the request for all http verbs.
+backtracking_array :: Allows array matchers to backtrack if later matchers
+                      do not match.
+csrf :: Adds CSRF protection and helper methods using
+        {rack_csrf}[https://github.com/baldowl/rack_csrf].
 default_headers :: Override the default response headers used.
 error_handler :: Adds a +error+ block that is called for all responses that
                  raise exceptions.
@@ -628,6 +651,8 @@ header_matchers :: Adds host, header, and accept hash matchers.
 hooks :: Adds before and after methods to run code before and after requests.
 indifferent_params :: Adds params method with indifferent access to params,
                       allowing use of symbol keys for accessing params.
+json :: Allows match blocks to return arrays and hashes, using a json
+        representation as the response body.
 middleware :: Allows the Roda app to be used as a rack middleware, calling the
               next middleware if no route matches.
 multi_route :: Adds the ability for multiple named route blocks, with the
@@ -636,8 +661,15 @@ not_found :: Adds a +not_found+ block that is called for all 404 responses
              without bodies.
 pass :: Adds a pass method allowing you to skip the current +r.on+ block as if
         it did not match.
+per_thread_caching :: Switches the thread-safe cache from a shared cache to a
+                      per-thread cache.
 render :: Adds support for rendering templates via tilt, as described above.
 streaming :: Adds support for streaming responses.
+symbol_matchers :: Adds support for symbol-specific matching regexps.
+symbol_views :: Allows match blocks to return template name symbols, uses the
+                template view as the response body.
+view_subdirs :: Allows for setting a view subdirectory to use on a per-request
+                basis.
 
 === External Plugins
 
@@ -649,13 +681,15 @@ autoforme :: Adds support for easily creating a simple administrative front
 
 === How to create plugins
 
-Authoring your own plugins is pretty straightforward.  Plugins are just modules
-that contain one of the following modules:
+Authoring your own plugins is pretty straightforward.  Plugins are just modules,
+which may contain any of the following modules:
 
 InstanceMethods :: module included in the Roda class
 ClassMethods :: module that extends the Roda class
 RequestMethods :: module included in the class of the request
+RequestClassMethods :: module extending the class of the request
 ResponseMethods :: module included in the class of the response
+ResponseClassMethods :: module extending the class of the response
 
 If the plugin responds to +load_dependencies+, it will be called first, and should
 be used if the plugin depends on another plugin.

data/lib/roda.rb

@@ -9,88 +9,46 @@ class Roda
   # Error class raised by Roda
   class RodaError < StandardError; end
 
-  # Base class used for Roda requests.  The instance methods for this
-  # class are added by Roda::RodaPlugins::Base::RequestMethods, so this
-  # only contains the class methods.
-  class RodaRequest < ::Rack::Request;
-    @roda_class = ::Roda
-    @match_pattern_cache = {}
-
-    if defined?(RUBY_ENGINE) && RUBY_ENGINE != 'ruby'
-      # :nocov:
-      @match_pattern_mutex = Mutex.new
-
-      def self.cached_matcher(obj)
-        unless pattern = @match_pattern_mutex.synchronize{@match_pattern_cache[obj]}
-          pattern = consume_pattern(yield)
-          @match_pattern_mutex.synchronize{@match_pattern_cache[obj] = pattern}
-        end
-        pattern
+  if defined?(RUBY_ENGINE) && RUBY_ENGINE != 'ruby'
+    # A thread safe cache class, offering only #[] and #[]= methods,
+    # each protected by a mutex.  Used on non-MRI where Hash is not
+    # thread safe.
+    class RodaCache
+      # Create a new thread safe cache.
+      def initialize
+        @mutex = Mutex.new
+        @hash = {}
       end
 
-      def self.inherited(subclass)
-        super
-        subclass.instance_variable_set(:@match_pattern_cache, {})
-        subclass.instance_variable_set(:@match_pattern_mutex, Mutex.new)
-      end
-      # :nocov:
-    else
-      # Return the cached pattern for the given object.  If the object is
-      # not already cached, yield to get the basic pattern, and convert the
-      # basic pattern to a pattern that does not partial segments.
-      def self.cached_matcher(obj)
-        unless pattern = @match_pattern_cache[obj]
-          pattern = @match_pattern_cache[obj] = consume_pattern(yield)
-        end
-        pattern
+      # Make getting value from underlying hash thread safe.
+      def [](key)
+        @mutex.synchronize{@hash[key]}
       end
 
-      # Initialize the match_pattern cache in the subclass.
-      def self.inherited(subclass)
-        super
-        subclass.instance_variable_set(:@match_pattern_cache, {})
+      # Make setting value in underlying hash thread safe.
+      def []=(key, value)
+        @mutex.synchronize{@hash[key] = value}
       end
     end
+  else
+    # Hashes are already thread-safe in MRI, due to the GVL, so they
+    # can safely be used as a cache.
+    RodaCache = Hash
+  end
 
-    class << self
-      # Reference to the Roda class related to this request class.
-      attr_accessor :roda_class
-
-      # Since RodaRequest is anonymously subclassed when Roda is subclassed,
-      # and then assigned to a constant of the Roda subclass, make inspect
-      # reflect the likely name for the class.
-      def inspect
-        "#{roda_class.inspect}::RodaRequest"
-      end
-
-      private
-
-      # The pattern to use for consuming, based on the given argument.  The returned
-      # pattern requires the path starts with a string and does not match partial
-      # segments.
-      def consume_pattern(pattern)
-        /\A(\/(?:#{pattern}))(\/|\z)/
-      end
-    end
+  # Base class used for Roda requests.  The instance methods for this
+  # class are added by Roda::RodaPlugins::Base::RequestMethods, the
+  # class methods are added by Roda::RodaPlugins::Base::RequestClassMethods.
+  class RodaRequest < ::Rack::Request;
+    @roda_class = ::Roda
+    @match_pattern_cache = ::Roda::RodaCache.new
   end
 
   # Base class used for Roda responses.  The instance methods for this
-  # class are added by Roda::RodaPlugins::Base::ResponseMethods, so this
-  # only contains the class methods.
+  # class are added by Roda::RodaPlugins::Base::ResponseMethods, the class
+  # methods are added by Roda::RodaPlugins::Base::ResponseClassMethods.
   class RodaResponse < ::Rack::Response;
     @roda_class = ::Roda
-
-    class << self
-      # Reference to the Roda class related to this response class.
-      attr_accessor :roda_class
-
-      # Since RodaResponse is anonymously subclassed when Roda is subclassed,
-      # and then assigned to a constant of the Roda subclass, make inspect
-      # reflect the likely name for the class.
-      def inspect
-        "#{roda_class.inspect}::RodaResponse"
-      end
-    end
   end
 
   @builder = ::Rack::Builder.new
@@ -100,11 +58,8 @@ class Roda
   # Module in which all Roda plugins should be stored. Also contains logic for
   # registering and loading plugins.
   module RodaPlugins
-    # Mutex protecting the plugins hash
-    @mutex = ::Mutex.new
-
     # Stores registered plugins
-    @plugins = {}
+    @plugins = RodaCache.new
 
     # If the registered plugin already exists, use it.  Otherwise,
     # require it and return it.  This raises a LoadError if such a
@@ -112,9 +67,9 @@ class Roda
     # not register itself correctly.
     def self.load_plugin(name)
       h = @plugins
-      unless plugin = @mutex.synchronize{h[name]}
+      unless plugin = h[name]
         require "roda/plugins/#{name}"
-        raise RodaError, "Plugin #{name} did not register itself correctly in Roda::RodaPlugins" unless plugin = @mutex.synchronize{h[name]}
+        raise RodaError, "Plugin #{name} did not register itself correctly in Roda::RodaPlugins" unless plugin = h[name]
       end
       plugin
     end
@@ -122,7 +77,7 @@ class Roda
     # Register the given plugin with Roda, so that it can be loaded using #plugin
     # with a symbol.  Should be used by plugin files.
     def self.register_plugin(name, mod)
-      @mutex.synchronize{@plugins[name] = mod}
+      @plugins[name] = mod
     end
 
     # The base plugin for Roda, implementing all default functionality.
@@ -145,6 +100,14 @@ class Roda
           app.call(env)
         end
 
+        # Create a match_#{key} method in the request class using the given
+        # block, so that using a hash key in a request match method will
+        # call the block.  The block should return nil or false to not
+        # match, and anything else to match.
+        def hash_matcher(key, &block)
+          request_module{define_method(:"match_#{key}", &block)}
+        end
+
         # When inheriting Roda, setup a new rack app builder, copy the
         # default middleware and opts into the subclass, and set the
         # request and response classes in the subclasses to be subclasses
@@ -159,6 +122,7 @@ class Roda
           
           request_class = Class.new(self::RodaRequest)
           request_class.roda_class = subclass
+          request_class.match_pattern_cache = thread_safe_cache
           subclass.const_set(:RodaRequest, request_class)
 
           response_class = Class.new(self::RodaResponse)
@@ -187,9 +151,15 @@ class Roda
           if defined?(mixin::RequestMethods)
             self::RodaRequest.send(:include, mixin::RequestMethods)
           end
+          if defined?(mixin::RequestClassMethods)
+            self::RodaRequest.extend mixin::RequestClassMethods
+          end
           if defined?(mixin::ResponseMethods)
             self::RodaResponse.send(:include, mixin::ResponseMethods)
           end
+          if defined?(mixin::ResponseClassMethods)
+            self::RodaResponse.extend mixin::ResponseClassMethods
+          end
           
           if mixin.respond_to?(:configure)
             mixin.configure(self, *args, &block)
@@ -218,6 +188,12 @@ class Roda
           @app = @builder.to_app
         end
 
+        # A new thread safe cache instance.  This is a method so it can be
+        # easily overridden for alternative implementations.
+        def thread_safe_cache
+          RodaCache.new
+        end
+
         # Add a middleware to use for the rack application.  Must be
         # called before calling #route.
         def use(*args, &block)
@@ -298,12 +274,50 @@ class Roda
         # behavior after the request and response have been setup.
         def _route(&block)
           catch(:halt) do
-            request.handle_on_result(instance_exec(@_request, &block))
+            request.block_result(instance_exec(@_request, &block))
             response.finish
           end
         end
       end
 
+      # Class methods for RodaRequest
+      module RequestClassMethods
+        # Reference to the Roda class related to this request class.
+        attr_accessor :roda_class
+
+        # The cache to use for match patterns for this request class.
+        attr_accessor :match_pattern_cache
+
+        # Return the cached pattern for the given object.  If the object is
+        # not already cached, yield to get the basic pattern, and convert the
+        # basic pattern to a pattern that does not partial segments.
+        def cached_matcher(obj)
+          cache = @match_pattern_cache
+
+          unless pattern = cache[obj]
+            pattern = cache[obj] = consume_pattern(yield)
+          end
+
+          pattern
+        end
+
+        # Since RodaRequest is anonymously subclassed when Roda is subclassed,
+        # and then assigned to a constant of the Roda subclass, make inspect
+        # reflect the likely name for the class.
+        def inspect
+          "#{roda_class.inspect}::RodaRequest"
+        end
+
+        private
+
+        # The pattern to use for consuming, based on the given argument.  The returned
+        # pattern requires the path starts with a string and does not match partial
+        # segments.
+        def consume_pattern(pattern)
+          /\A(\/(?:#{pattern}))(\/|\z)/
+        end
+      end
+
       # Instance methods for RodaRequest, mostly related to handling routing
       # for the request.
       module RequestMethods
@@ -312,8 +326,15 @@ class Roda
         REQUEST_METHOD = "REQUEST_METHOD".freeze
         EMPTY_STRING = "".freeze
         SLASH = "/".freeze
-        TERM = Object.new.freeze
         SEGMENT = "([^\\/]+)".freeze
+        EMPTY_ARRAY = [].freeze
+        TERM_INSPECT = "TERM".freeze
+
+        TERM = Object.new
+        def TERM.inspect
+          TERM_INSPECT
+        end
+        TERM.freeze
 
         # The current captures for the request.  This gets modified as routing
         # occurs.
@@ -336,24 +357,26 @@ class Roda
           "#{env[SCRIPT_NAME]}#{env[PATH_INFO]}"
         end
 
-        # If this is not a GET method, returns immediately.  Otherwise, calls
-        # #is if there are any arguments, or #on if there are no arguments.
+        # If this is not a GET method, returns immediately.  Otherwise, if there
+        # are arguments, do a terminal match on the arguments, otherwise do a
+        # regular match.
         def get(*args, &block)
-          is_or_on(*args, &block) if get?
+          _verb(args, &block) if get?
         end
 
         # Immediately stop execution of the route block and return the given
-        # rack response array of status, headers, and body.
-        def halt(response)
-          _halt(response)
+        # rack response array of status, headers, and body.  If no argument
+        # is given, uses the current response.
+        def halt(res=response.finish)
+          throw :halt, res
         end
 
         # Handle #on block return values.  By default, if a string is given
         # and the response is empty, use the string as the response body.
-        def handle_on_result(result)
+        def block_result(result)
           res = response
-          if result.is_a?(String) && res.empty?
-            res.write(result)
+          if res.empty? && (body = block_result_body(result))
+            res.write(body)
           end
         end
 
@@ -367,7 +390,7 @@ class Roda
         # there is only a match if #on has fully matched the path.
         def is(*args, &block)
           args << TERM
-          on(*args, &block)
+          _on(args, &block)
         end
 
         # Attempts to match on all of the arguments.  If all of the
@@ -376,31 +399,14 @@ class Roda
         # If any of the arguments fails, ensures the request state is
         # returned to that before matches were attempted.
         def on(*args, &block)
-          try do
-            # We stop evaluation of this entire matcher unless
-            # each and every `arg` defined for this matcher evaluates
-            # to a non-false value.
-            #
-            # Short circuit examples:
-            #    on true, false do
-            #
-            #    # PATH_INFO=/user
-            #    on true, "signup"
-            return unless args.all?{|arg| match(arg)}
-
-            # The captures we yield here were generated and assembled
-            # by evaluating each of the `arg`s above. Most of these
-            # are carried out by #consume.
-            handle_on_result(yield(*captures))
-
-            _halt response.finish
-          end
+          _on(args, &block)
         end
 
-        # If this is not a POST method, returns immediately.  Otherwise, calls
-        # #is if there are any arguments, or #on if there are no arguments.
+        # If this is not a GET method, returns immediately.  Otherwise, if there
+        # are arguments, do a terminal match on the arguments, otherwise do a
+        # regular match.
         def post(*args, &block)
-          is_or_on(*args, &block) if post?
+          _verb(args, &block) if post?
         end
 
         # The response related to the current request.
@@ -411,31 +417,26 @@ class Roda
         # Immediately redirect to the given path.
         def redirect(path, status=302)
           response.redirect(path, status)
-          _halt response.finish
+          throw :halt, response.finish
         end
 
-        #
+        # If the current path is the root ("/"), match on the block.  If a request
+        # method is given, return immediately if the request does not use the given
+        # method.
         def root(request_method=nil, &block)
           if env[PATH_INFO] == SLASH && (!request_method || send(:"#{request_method}?"))
-            on(&block)
+            _on(EMPTY_ARRAY, &block)
           end
         end
 
         # Call the given rack app with the environment and immediately return
         # the response as the response for this request.
         def run(app)
-          _halt app.call(env)
+          throw :halt, app.call(env)
         end
 
         private
 
-        # Internal halt method, used so that halt can be overridden to handle
-        # non-rack response arrays, but internal code that always generates
-        # rack response arrays can use this for performance.
-        def _halt(response)
-          throw :halt, response
-        end
-
         # Match any of the elements in the given array.  Return at the
         # first match without evaluating future matches.  Returns false
         # if no elements in the array match.
@@ -465,12 +466,54 @@ class Roda
         # string so that regexp metacharacters are not matched, and recognizes
         # colon tokens for placeholders.
         def _match_string(str)
-          consume(self.class.cached_matcher(str){Regexp.escape(str).gsub(/:\w+/, SEGMENT)})
+          consume(self.class.cached_matcher(str){Regexp.escape(str).gsub(/:(\w+)/){|m| _match_symbol_regexp($1)}})
         end
 
         # Match the given symbol if any segment matches.
         def _match_symbol(sym)
-          consume(self.class.cached_matcher(sym){SEGMENT})
+          consume(self.class.cached_matcher(sym){_match_symbol_regexp(sym)})
+        end
+
+        # The regular expression to use for matching symbols.  By default, any non-empty
+        # segment matches.
+        def _match_symbol_regexp(s)
+          SEGMENT
+        end
+
+        # Internal match method taking array of matchers instead of multiple
+        # arguments.
+        def _on(args)
+          script = env[SCRIPT_NAME]
+          path = env[PATH_INFO]
+
+          # For every block, we make sure to reset captures so that
+          # nesting matchers won't mess with each other's captures.
+          captures.clear
+
+          return unless match_all(args)
+          block_result(yield(*captures))
+          throw :halt, response.finish
+        ensure
+          env[SCRIPT_NAME] = script
+          env[PATH_INFO] = path
+        end
+
+        # Backbone of the verb method support, using a terminal match if
+        # args is not empty, or a regular match if it is empty.
+        def _verb(args, &block)
+          unless args.empty?
+            args << TERM
+          end
+          _on(args, &block)
+        end
+
+        # The body to use for the response if the response does not return
+        # a body.  By default, a String is returned directly, and nil is
+        # returned otherwise.
+        def block_result_body(result)
+          if result.is_a?(String)
+            result
+          end
         end
 
         # Attempts to match the pattern to the current path.  If there is no
@@ -478,9 +521,7 @@ class Roda
         # SCRIPT_NAME to include the matched path, removes the matched
         # path from PATH_INFO, and updates captures with any regex captures.
         def consume(pattern)
-          matchdata = env[PATH_INFO].match(pattern)
-
-          return false unless matchdata
+          return unless matchdata = env[PATH_INFO].match(pattern)
 
           vars = matchdata.captures
 
@@ -491,16 +532,6 @@ class Roda
           captures.concat(vars)
         end
 
-        # Backbone of the verb method support, calling #is if there are any
-        # arguments, or #on if there are none.
-        def is_or_on(*args, &block)
-          if args.empty?
-            on(*args, &block)
-          else
-            is(*args, &block)
-          end
-        end
-
         # Attempt to match the argument to the given request, handling
         # common ruby types.
         def match(matcher)
@@ -524,6 +555,11 @@ class Roda
           end
         end
 
+        # Match only if all of the arguments in the given array match.
+        def match_all(args)
+          args.all?{|arg| match(arg)}
+        end
+
         # Match files with the given extension.  Requires that the
         # request path end with the extension.
         def match_extension(ext)
@@ -555,22 +591,18 @@ class Roda
             captures << v
           end
         end
+      end
 
-        # Yield to the given block, clearing any captures before
-        # yielding and restoring the SCRIPT_NAME and PATH_INFO on exit.
-        def try
-          script = env[SCRIPT_NAME]
-          path = env[PATH_INFO]
-
-          # For every block, we make sure to reset captures so that
-          # nesting matchers won't mess with each other's captures.
-          captures.clear
-
-          yield
+      # Class methods for RodaResponse
+      module ResponseClassMethods
+        # Reference to the Roda class related to this response class.
+        attr_accessor :roda_class
 
-        ensure
-          env[SCRIPT_NAME] = script
-          env[PATH_INFO] = path
+        # Since RodaResponse is anonymously subclassed when Roda is subclassed,
+        # and then assigned to a constant of the Roda subclass, make inspect
+        # reflect the likely name for the class.
+        def inspect
+          "#{roda_class.inspect}::RodaResponse"
         end
       end