roda 2.29.0 → 3.0.0

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_subdirs+ plugin, or the +multi_run+ plugin.
++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/+
 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_subdirs+,
+You should have a separate view subdirectory per prefix. If you are using +multi_route+ 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.
 
@@ -147,7 +147,7 @@ For larger applications, there are some slight changes to the Roda application f
 
     plugin :render
     plugin :assets
-    plugin :view_subdirs
+    plugin :view_options
     plugin :multi_route
     Dir['./routes/*.rb'].each{|f| require f}
 
@@ -158,7 +158,7 @@ For larger applications, there are some slight changes to the Roda application f
     Dir['./helpers/*.rb'].each{|f| require f}
   end
 
-After loading the +view_subdirs+ and +multi_route+ plugin, you require all of your
+After loading the +view_options+ and +multi_route+ 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
 block, you require all of your helper files containing the instance methods for your

data/doc/release_notes/1.2.0.txt

@@ -322,7 +322,7 @@
   be set to false if you do not want subclasses to inherit
   middleware from the superclass.  This is useful if the
   superclass dispatches to the subclass via r.run, as otherwise
-  it would have to run the the same middleware stack twice.
+  it would have to run the same middleware stack twice.
 
 * A clear_middleware! class accessor has been added, allowing
   you to clear the current middleware stack.

data/doc/release_notes/3.0.0.txt

@@ -0,0 +1,84 @@
+= Major Changes
+
+* String matchers now match literally by default, for simplicity,
+  understandability, and performance.  Use the String class matcher
+  or a symbol matcher to match arbitrary segments.
+
+    # Before
+    r.is "artists/:name" do |artist_name|
+    end
+
+    # Now
+    r.is "artists", String do |artist_name|
+    end
+    # or
+    r.is "artists", :name do |artist_name|
+    end
+
+  You can use the placeholder_string_matchers plugin to restore
+  the historical behavior if you don't want to modify your
+  routes.
+
+* Using an unsupported matcher now raises an error, making it
+  more likely to detect using a unexpected value as a matcher
+  (which previously matched everything).
+
+* Have a route/match block return an unsupported value now
+  raises an error if nothing has been written to the body, making
+  it more likely to detect using an unexpected value as a block
+  result (which previously was ignored).
+
+= Backwards Compatibility
+
+* Deprecated plugins, features, and constants have been removed.
+  Before upgrading to 3.0.0, please upgrade to 2.29.0 first and
+  fix any deprecation warnings.
+
+* Ruby 1.8.7 support has been dropped.  Ruby 1.9.2 is the new
+  minimum supported version.
+
+* The :check_paths render plugin option now defaults to true so that
+  generated template paths are checked by default, reducing the risk
+  of rendering arbitrary files.
+
+* The assets plugin now defaults to using subresource integrity
+  with SHA256 for compiled assets, and using SHA256 instead of
+  SHA1 for compiled asset hashes.
+
+* Subclassing a Roda app that uses the render plugin now always
+  uses a copy of the superclass's template cache.
+
+* Using a Roda app as middleware now always uses a subclass
+  of the app for the middleware.
+
+* public_send is now used instead of send internally unless it is
+  expected that private methods will be called.
+
+* The match methods added by the symbol_matchers and hash_matchers
+  plugins are now private instead of public.
+
+= Other Improvements
+
+* The streaming plugin has been greatly simplified, by dropping
+  deprecated compatibility for EventMachine.
+
+* It is now possible to reset the :include_request option to false
+  in the json and json_parser plugins by loading the plugin a
+  second time with the option set.
+
+* The precompile_templates plugin now always sorts locals.  This
+  plugin should now be used with Tilt 2.0.1+ (which also sorts
+  locals), though it will still work with earlier Tilt versions.
+
+* The multi_run plugin now recomputes the regexp when freezing the
+  app.
+
+= Deprecated Features
+
+These features will be removed in Roda 3.1.0:
+
+* Roda.thread_safe_cache is now deprecated.  RodaCache is now used
+  as the thread-safe cache class.
+
+* RodaRequest#placeholder_string_matcher? (private method) is now
+  deprecated and always returns false.

data/lib/roda.rb

@@ -2,7 +2,7 @@
 
 require "rack"
 require "thread"
-require "roda/version"
+require_relative "roda/version"
 
 # The main class for Roda.  Roda is built completely out of plugins, with the
 # default plugin being Roda::RodaPlugins::Base, so this class is mostly empty
@@ -102,9 +102,11 @@ class Roda
     # Deprecate the constant with the given name in the given module,
     # if the ruby version supports it.
     def self.deprecate_constant(mod, name)
+      # :nocov:
       if RUBY_VERSION >= '2.3'
         mod.deprecate_constant(name)
       end
+      # :nocov:
     end
 
     # The base plugin for Roda, implementing all default functionality.
@@ -177,7 +179,7 @@ class Roda
           
           request_class = Class.new(self::RodaRequest)
           request_class.roda_class = subclass
-          request_class.match_pattern_cache = thread_safe_cache
+          request_class.match_pattern_cache = RodaCache.new
           subclass.const_set(:RodaRequest, request_class)
 
           response_class = Class.new(self::RodaResponse)
@@ -223,16 +225,17 @@ class Roda
           build_rack_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
+          # :nocov:
+          RodaPlugins.warn "Roda.thread_safe_cache is deprecated and will be removed from Roda 3.1."
           RodaCache.new
+          # :nocov:
         end
 
         # Add a middleware to use for the rack application.  Must be
         # called before calling #route to have an effect. Example:
         #
-        #   Roda.use Rack::Session::Cookie, :secret=>ENV['secret']
+        #   Roda.use Rack::Session::Cookie, secret: ENV['secret']
         def use(*args, &block)
           @middleware << [args, block].freeze
           build_rack_app
@@ -357,27 +360,6 @@ class Roda
       # Instance methods for RodaRequest, mostly related to handling routing
       # for the request.
       module RequestMethods
-        PATH_INFO = "PATH_INFO".freeze
-        RodaPlugins.deprecate_constant(self, :PATH_INFO)
-        SCRIPT_NAME = "SCRIPT_NAME".freeze
-        RodaPlugins.deprecate_constant(self, :SCRIPT_NAME)
-        REQUEST_METHOD = "REQUEST_METHOD".freeze
-        RodaPlugins.deprecate_constant(self, :REQUEST_METHOD)
-        EMPTY_STRING = "".freeze
-        RodaPlugins.deprecate_constant(self, :EMPTY_STRING)
-        SLASH = "/".freeze
-        RodaPlugins.deprecate_constant(self, :SLASH)
-        COLON = ":".freeze
-        RodaPlugins.deprecate_constant(self, :COLON)
-        SEGMENT = "([^\\/]+)".freeze
-        RodaPlugins.deprecate_constant(self, :SEGMENT)
-        TERM_INSPECT = "TERM".freeze
-        RodaPlugins.deprecate_constant(self, :TERM_INSPECT)
-        GET_REQUEST_METHOD = 'GET'.freeze
-        RodaPlugins.deprecate_constant(self, :GET_REQUEST_METHOD)
-        SESSION_KEY = 'rack.session'.freeze
-        RodaPlugins.deprecate_constant(self, :SESSION_KEY)
-
         TERM = Object.new
         def TERM.inspect
           "TERM"
@@ -611,7 +593,7 @@ class Roda
           self.class.roda_class
         end
 
-        # Routing matches that only matches +GET+ requests where the current
+        # Match method that only matches +GET+ requests where the current
         # path is +/+.  If it matches, the match block is executed, and when
         # the match block returns, the rack response is returned.
         #
@@ -722,6 +704,7 @@ class Roda
         def _match_class(klass)
           meth = :"_match_class_#{klass}"
           if respond_to?(meth, true)
+            # Allow calling private methods, as match methods are generally private
             send(meth)
           else
             unsupported_matcher(klass)
@@ -730,6 +713,7 @@ class Roda
 
         # Match the given hash if all hash matchers match.
         def _match_hash(hash)
+          # Allow calling private methods, as match methods are generally private
           hash.all?{|k,v| send("match_#{k}", v)}
         end
 
@@ -749,35 +733,14 @@ class Roda
         # string so that regexp metacharacters are not matched, and recognizes
         # colon tokens for placeholders.
         def _match_string(str)
-          if str.index(":") && placeholder_string_matcher?
-            # RODA3: Remove
-            not_warned = true
-            consume(self.class.cached_matcher(str){Regexp.escape(str).gsub(/:(\w+)/) do |m|
-              match = $1
-              if not_warned
-                nor_warned = false
-                RodaPlugins.warn("Placeholder symbol matchers are deprecated by default and will be removed in Roda 3 (matcher used: #{str.inspect}). Use the placeholder_symbol_matchers plugin or split the string and use separate symbol matchers or String class matchers for the placeholders")
-              end
-              _match_symbol_regexp(match)
-            end})
-          else
-            rp = @remaining_path
-            if rp.start_with?("/#{str}")
-              last = str.length + 1
-              case rp[last]
-              when "/"
-                @remaining_path = rp[last, rp.length]
-              when nil
-                @remaining_path = ""
-              when Integer
-                # :nocov:
-                # RODA3: Remove
-                # Ruby 1.8 support
-                if rp[last].chr == "/"
-                  @remaining_path = rp[last, rp.length]
-                end
-                # :nocov:
-              end
+          rp = @remaining_path
+          if rp.start_with?("/#{str}")
+            last = str.length + 1
+            case rp[last]
+            when "/"
+              @remaining_path = rp[last, rp.length]
+            when nil
+              @remaining_path = ""
             end
           end
         end
@@ -801,11 +764,6 @@ class Roda
         # Match any nonempty segment.  This should be called without an argument.
         alias _match_class_String _match_symbol
 
-        # RODA3: Remove
-        def _match_symbol_regexp(s)
-          "([^\\/]+)"
-        end
-
         # The base remaining path to use.
         def _remaining_path(env)
           env["PATH_INFO"]
@@ -838,11 +796,7 @@ class Roda
           when nil, false
             # nothing
           else
-            if roda_class.opts[:unsupported_block_result] == :raise
-              raise RodaError, "unsupported block result: #{result.inspect}"
-            else
-              RodaPlugins.warn("Unsupported match block return result: #{result.inspect}.  This is currently ignored, but will raise an error in Roda 3.  Have the block return nil or false to ignore the result.")
-            end
+            raise RodaError, "unsupported block result: #{result.inspect}"
           end
         end
 
@@ -946,16 +900,15 @@ class Roda
         # Whether string matchers are used verbatim, without handling
         # placeholders via colons.
         def placeholder_string_matcher?
-          !roda_class.opts[:verbatim_string_matcher]
+          # :nocov:
+          RodaPlugins.warn "Roda::RodaRequest.placeholder_string_matcher? is deprecated and will be removed from Roda 3.1."
+          false
+          # :nocov:
         end
 
         # Handle an unsupported matcher.
         def unsupported_matcher(matcher)
-          if roda_class.opts[:unsupported_matcher] == :raise
-            raise RodaError, "unsupported matcher: #{matcher.inspect}"
-          end
-          RodaPlugins.warn("Unsupported matcher used: #{matcher.inspect}.  This currently always matches, but will raise an error in Roda 3.  Switch to using true if you want the matcher to always match.")
-          matcher
+          raise RodaError, "unsupported matcher: #{matcher.inspect}"
         end
       end
 
@@ -976,13 +929,6 @@ class Roda
       module ResponseMethods
         DEFAULT_HEADERS = {"Content-Type" => "text/html".freeze}.freeze
 
-        CONTENT_LENGTH = "Content-Length".freeze
-        RodaPlugins.deprecate_constant(self, :CONTENT_LENGTH)
-        CONTENT_TYPE = "Content-Type".freeze
-        RodaPlugins.deprecate_constant(self, :CONTENT_TYPE)
-        LOCATION = "Location".freeze
-        RodaPlugins.deprecate_constant(self, :LOCATION)
-
         # The body for the current response.
         attr_reader :body
 

data/lib/roda/plugins/assets.rb

@@ -24,7 +24,7 @@ class Roda
     # When loading the plugin, use the :css and :js options
     # to set the source file(s) to use for CSS and javascript assets:
     #
-    #   plugin :assets, :css => 'some_file.scss', :js => 'some_file.coffee'
+    #   plugin :assets, css: 'some_file.scss', js: 'some_file.coffee'
     #
     # This will look for the following files:
     #
@@ -57,10 +57,10 @@ class Roda
     #
     # You can add attributes to the tags by using an options hash:
     #
-    #   <%= assets(:css, :media => 'print') %>
+    #   <%= assets(:css, media: 'print') %>
     #
-    # The assets method will respect the application's :add_script_name option,
-    # if it set it will automatically prefix the path with the SCRIPT_NAME for
+    # The assets method will respect the application's +:add_script_name+ option,
+    # if it set it will automatically prefix the path with the +SCRIPT_NAME+ for
     # the request.
     #
     # == Asset Paths
@@ -84,8 +84,8 @@ class Roda
     # css/js files for your front end and back end.  To use asset groups, you
     # pass a hash for the :css and/or :js options:
     #
-    #   plugin :assets, :css => {:frontend => 'some_frontend_file.scss',
-    #                            :backend => 'some_backend_file.scss'}
+    #   plugin :assets, css: {frontend: 'some_frontend_file.scss',
+    #                         backend: 'some_backend_file.scss'}
     #
     # This expects the following directory structure for your assets:
     #
@@ -93,7 +93,7 @@ class Roda
     #   assets/css/backend/some_backend_file.scss
     #
     # If you do not want to force that directory structure when using
-    # asset groups, you can use the <tt>:group_subdirs => false</tt> option.
+    # asset groups, you can use the <tt>group_subdirs: false</tt> option.
     #
     # In your view code use an array argument in your call to assets:
     #
@@ -106,7 +106,7 @@ class Roda
     # the plugin:
     #
     #   plugin :assets,
-    #     :css => {:frontend => {:dashboard => 'some_frontend_file.scss'}}
+    #     css: {frontend: {dashboard: 'some_frontend_file.scss'}}
     #
     # and an extra entry per nesting level when creating the tags.
     #
@@ -126,7 +126,7 @@ class Roda
     # dependencies of those asset files:
     #
     #   app.plugin :assets,
-    #     :dependencies=>{'assets/css/bootstrap.scss'=>Dir['assets/css/bootstrap/' '**/*.scss']}
+    #     dependencies: {'assets/css/bootstrap.scss'=>Dir['assets/css/bootstrap/' '**/*.scss']}
     #
     # == Asset Compilation
     #
@@ -134,7 +134,7 @@ class Roda
     # into a single file, with you can do by calling compile_assets after
     # loading the plugin:
     #
-    #   plugin :assets, :css => 'some_file.scss', :js => 'some_file.coffee'
+    #   plugin :assets, css: 'some_file.scss', js: 'some_file.coffee'
     #   compile_assets
     #
     # After calling compile_assets, calls to assets in your views will default
@@ -224,8 +224,8 @@ class Roda
     # You can use this to call Autoprefixer on your CSS:
     #
     #   plugin :assets, {
-    #     :css => [ 'style.scss' ],
-    #     :postprocessor => lambda do |file, type, content|
+    #     css: [ 'style.scss' ],
+    #     postprocessor: lambda do |file, type, content|
     #       type == :css ? AutoprefixerRails.process(content).css : content
     #     end
     #   }
@@ -292,7 +292,8 @@ class Roda
     #            paths will be considered relative to the application's :root option.
     # :sri :: Enables subresource integrity when setting up references to compiled assets. The value should be
     #         :sha256, :sha384, or :sha512 depending on which hash algorithm you want to use.  This changes the
-    #         hash algorithm that Roda will use when naming compiled asset files.
+    #         hash algorithm that Roda will use when naming compiled asset files. The default is :sha256, you
+    #         can use nil to disable subresource integrity.
     module Assets
       DEFAULTS = {
         :compiled_name    => 'app'.freeze,
@@ -305,37 +306,9 @@ class Roda
         :group_subdirs    => true,
         :compiled_css_dir => nil,
         :compiled_js_dir  => nil,
+        :sri              => :sha256
       }.freeze
 
-      EMPTY_ATTRS = {}.freeze
-      RodaPlugins.deprecate_constant(self, :EMPTY_ATTRS)
-      JS_END = "\"></script>".freeze
-      RodaPlugins.deprecate_constant(self, :JS_END)
-      CSS_END = "\" />".freeze
-      RodaPlugins.deprecate_constant(self, :CSS_END)
-      SPACE = ' '.freeze
-      RodaPlugins.deprecate_constant(self, :SPACE)
-      DOT = '.'.freeze
-      RodaPlugins.deprecate_constant(self, :DOT)
-      SLASH = '/'.freeze
-      RodaPlugins.deprecate_constant(self, :SLASH)
-      NEWLINE = "\n".freeze
-      RodaPlugins.deprecate_constant(self, :NEWLINE)
-      EMPTY_STRING = ''.freeze
-      RodaPlugins.deprecate_constant(self, :EMPTY_STRING)
-      JS_SUFFIX = '.js'.freeze
-      RodaPlugins.deprecate_constant(self, :JS_SUFFIX)
-      CSS_SUFFIX = '.css'.freeze
-      RodaPlugins.deprecate_constant(self, :CSS_SUFFIX)
-      HTTP_ACCEPT_ENCODING = 'HTTP_ACCEPT_ENCODING'.freeze
-      RodaPlugins.deprecate_constant(self, :HTTP_ACCEPT_ENCODING)
-      CONTENT_ENCODING = 'Content-Encoding'.freeze
-      RodaPlugins.deprecate_constant(self, :CONTENT_ENCODING)
-      GZIP = 'gzip'.freeze
-      RodaPlugins.deprecate_constant(self, :GZIP)
-      DOTGZ = '.gz'.freeze
-      RodaPlugins.deprecate_constant(self, :DOTGZ)
-
       # Internal exception raised when a compressor cannot be found
       CompressorNotFound = Class.new(RodaError)
 
@@ -527,10 +500,8 @@ class Roda
           nil
         end
 
-        # Compress the given content for the given type using yuicompressor,
-        # but handle cases where yuicompressor isn't installed or can't find
-        # a java runtime.  This method can be overridden by the application
-        # to use a different compressor.
+        # Compress the given content for the given type by using the
+        # configured compressor, or trying the supported compressors.
         def compress_asset(content, type)
           case compressor = assets_opts[:"#{type}_compressor"]
           when :none
@@ -538,6 +509,7 @@ class Roda
           when nil
             # default, try different compressors
           else
+            # Allow calling private compress methods
             return send("compress_#{type}_#{compressor}", content)
           end
 
@@ -549,6 +521,7 @@ class Roda
 
           compressors.each do |comp|
             begin
+            # Allow calling private compress methods
               if c = send("compress_#{type}_#{comp}", content)
                 return c
               end
@@ -595,25 +568,19 @@ class Roda
         # Compress the CSS/JS using YUI Compressor, requires java runtime
         def compress_yui(content, meth)
           require 'yuicompressor'
-          ::YUICompressor.send(meth, content, :munge => true)
+          ::YUICompressor.public_send(meth, content, :munge => true)
         rescue ::Errno::ENOENT => e
           raise CompressorNotFound, "#{e.class}: #{e.message}", e.backtrace
         end
 
         # Return a unique id for the given content.  By default, uses the
-        # SHA1 hash of the content.  This method can be overridden to use
+        # SHA256 hash of the content.  This method can be overridden to use
         # a different digest type or to return a static string if you don't
         # want to use a unique value.
         def asset_digest(content)
-          klass = if algo = assets_opts[:sri]
-            require 'digest/sha2'
-            ::Digest.const_get(algo.to_s.upcase)
-          else
-            require 'digest/sha1'
-            ::Digest::SHA1
-          end
-
-          klass.hexdigest(content)
+          require 'digest/sha2'
+          algo = assets_opts[:sri] || :sha256
+          ::Digest.const_get(algo.to_s.upcase).hexdigest(content)
         end
       end
 
@@ -682,7 +649,7 @@ class Roda
         # Render the asset with the given filename.  When assets are compiled,
         # or when the file is already of the given type (no rendering necessary),
         # this returns the contents of the compiled file.
-        # When assets are not compiled and the file is not already of the correct,
+        # When assets are not compiled and the file is not already in the same format,
         # this will render the asset using the render plugin.
         # In both cases, if the file has not been modified since the last request,
         # this will return a 304 response.