roda 1.2.0 → 1.3.0

data/doc/release_notes/1.3.0.txt

@@ -0,0 +1,109 @@
+= Preparation for Roda 2
+
+* In Roda 2 (the next version), the PATH_INFO and SCRIPT_NAME
+  env variables will not be modified during routing. Instead,
+  Roda will use the static_path_info plugin behavior by default.
+  Users are strongly encouraged to use the static_path_info
+  plugin to make sure their apps will work with Roda 2.
+
+* In Roda 2, Roda#initialize will take the env hash, and #call
+  will take the route block.  The private #_route method will be
+  eliminated.  This should not affect applications, but it will
+  affect plugins that override these methods.
+  
+* The issues mentioned below should all have deprecation warnings,
+  except where noted.
+
+== New Plugins to Replace Deprecated Features
+
+* RodaResponse#set_cookie and #delete_cookie have been moved to the
+  cookies plugin.
+
+* Roda.request_module and .response_module have been moved to the
+  module_include plugin.
+
+* Roda.hash_matcher has been moved to the hash_matcher plugin.
+
+* The :extension hash matcher has been moved to the path_machers
+  plugin.  This plugin also contains new :prefix and :suffix hash
+  matchers.
+
+* The :param and :param! hash matchers have been moved to the
+  param_matchers plugin.
+
+== Other Deprecation Issues
+
+* The :opts render plugin option and :opts option to render and
+  view are now deprecated.  Use the :template_opts option instead.
+
+* RodaRequest#full_path_info has been deprecated, switch to using
+  #path.
+
+* Mutating plugin option hashes for the chunked, default_headers,
+  error_email, json, and render plugins is now deprecated, these
+  option hashes will be frozen in Roda 2.
+
+* The :header hash matcher in the header_matchers plugin now
+  gives a deprecation warning, because in Roda 2, the matcher will
+  yield the value of the header to the block.  To get the new
+  behavior and silence the deprecation warning, you need to set an
+  option:
+
+    Roda.opts[:match_header_yield] = true
+
+* Mutating json_result_classes directly in the json plugin is now
+  deprecated.  You should now pass a :classes option to the plugin
+  specifying the classes to convert, if you want to handle classes
+  other than Array and Hash.  There will not be a deprecation warning
+  if you attempt to mutate json_result_classes.
+
+= New Features
+
+* The Roda.freeze method now freezes internal datastructures to avoid
+  thread safety issues.  The plugins that ship with Roda will freeze
+  their datastructures when Roda.freeze is called.  It is recommended
+  that production applications call freeze on the application after
+  fully loading it, especially if they are using a threaded webserver
+  and a non-MRI ruby.
+
+* A delete_empty_headers plugin has been added that automatically
+  deletes headers set to the empty string.  This makes it simpler to
+  delete default headers if they shouldn't be set for a specific
+  request.
+  
+* A class_delegate method has been added to the delegate plugin. This
+  makes it easier to create instance methods that call class methods.
+
+* Roda::RodaMajorVersion, RodaMinorVersion, and RodaPatchVersion
+  constants have been added.
+
+= Other Improvements
+
+* The error_handler plugin now uses a new response instead of reusing
+  the existing response.  This fixes cases where changing the
+  Content-Type and then raising an exception would result in a error
+  page that used the previously set Content-Type.
+
+* The not_found plugin now clears previous set headers before calling
+  not found.  This fixes cases where Content-Type was set previously,
+  and also fixes an incorrect Content-Length being used for the
+  response.
+
+* The static_path_info plugin now restores the original SCRIPT_NAME
+  and PATH_INFO before returning from r.run, fixing usage with some
+  middleware.
+
+* The multi_run plugin now works when subclassing the app.
+
+* The default_headers plugin is now faster by skipping an unnecessary
+  hash duplication.
+
+* A Gemfile has been added to make development slightly easier.
+
+= Backwards Compatibility
+
+* RodaResponse is no longer a subclass of Rack::Response, it is now a
+  subclass of Object.  This shouldn't have an effect unless you were
+  calling a method on an instance that was defined by Rack::Response
+  and not RodaResponse, but most of those methods would have raised
+  exceptions.

data/lib/roda.rb

@@ -41,7 +41,7 @@ class Roda
   # 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;
+  class RodaRequest < ::Rack::Request
     @roda_class = ::Roda
     @match_pattern_cache = ::Roda::RodaCache.new
   end
@@ -49,7 +49,7 @@ class Roda
   # Base class used for Roda responses.  The instance methods for this
   # class are added by Roda::RodaPlugins::Base::ResponseMethods, the class
   # methods are added by Roda::RodaPlugins::Base::ResponseClassMethods.
-  class RodaResponse < ::Rack::Response;
+  class RodaResponse
     @roda_class = ::Roda
   end
 
@@ -59,6 +59,18 @@ class Roda
   @opts = {}
   @route_block = nil
 
+  module RodaDeprecateMutation
+    [:[]=, :clear, :compare_by_identity, :default=, :default_proc=, :delete, :delete_if,
+     :keep_if, :merge!, :reject!, :replace, :select!, :shift, :store, :update].each do |m|
+      class_eval(<<-END, __FILE__, __LINE__+1)
+        def #{m}(*)
+          RodaPlugins.deprecate("Mutating this hash (\#{inspect}) via the #{m} method is deprecated, this hash will be frozen in Roda 2.")
+          super
+        end
+      END
+    end
+  end
+
   # Module in which all Roda plugins should be stored. Also contains logic for
   # registering and loading plugins.
   module RodaPlugins
@@ -86,6 +98,12 @@ class Roda
       @plugins[name] = mod
     end
 
+    # Emit a deprecation message.  By default this just calls warn.  You can override this
+    # method to log deprecation messages to a file or include backtraces (or something else).
+    def self.deprecate(msg)
+      warn(msg)
+    end
+
     # The base plugin for Roda, implementing all default functionality.
     # Methods are put into a plugin so future plugins can easily override
     # them and call super to get the default behavior.
@@ -120,29 +138,28 @@ class Roda
           build_rack_app
         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.
-        #
-        #   class App < Roda
-        #     hash_matcher(:foo) do |v|
-        #       self['foo'] == v
-        #     end
+        # Freeze the internal state of the class, to avoid thread safety issues at runtime.
+        # It's optional to call this method, as nothing should be modifying the
+        # internal state at runtime anyway, but this makes sure an exception will
+        # be raised if you try to modify the internal state after calling this.
         #
-        #     route do
-        #       r.on :foo=>'bar' do
-        #         # matches when param foo has value bar
-        #       end
-        #     end
-        #   end
+        # 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
+          super
+        end
+
         def hash_matcher(key, &block)
-          request_module{define_method(:"match_#{key}", &block)}
+          RodaPlugins.deprecate("Roda.hash_matcher is deprecated and will be removed in Roda 2.  It has been moved to the hash_matcher plugin.")
+          self::RodaRequest.send(:define_method, :"match_#{key}", &block)
         end
 
         # When inheriting Roda, copy the shared data into the subclass,
         # and setup the request and response subclasses.
         def inherited(subclass)
+          raise RodaError, "Cannot subclass a frozen Roda class" if frozen?
           super
           subclass.instance_variable_set(:@inherit_middleware, @inherit_middleware)
           subclass.instance_variable_set(:@middleware, @inherit_middleware ? @middleware.dup : [])
@@ -150,6 +167,9 @@ class Roda
           subclass.opts.to_a.each do |k,v|
             if (v.is_a?(Array) || v.is_a?(Hash)) && !v.frozen?
               subclass.opts[k] = v.dup
+              if v.is_a?(RodaDeprecateMutation)
+                subclass.opts[k].extend(RodaDeprecateMutation)
+              end
             end
           end
           subclass.instance_variable_set(:@route_block, @route_block)
@@ -172,73 +192,25 @@ class Roda
         #   Roda.plugin PluginModule
         #   Roda.plugin :csrf
         def plugin(plugin, *args, &block)
-          if plugin.is_a?(Symbol)
-            plugin = RodaPlugins.load_plugin(plugin)
-          end
-
-          if plugin.respond_to?(:load_dependencies)
-            plugin.load_dependencies(self, *args, &block)
-          end
-
-          if defined?(plugin::InstanceMethods)
-            include(plugin::InstanceMethods)
-          end
-          if defined?(plugin::ClassMethods)
-            extend(plugin::ClassMethods)
-          end
-          if defined?(plugin::RequestMethods)
-            self::RodaRequest.send(:include, plugin::RequestMethods)
-          end
-          if defined?(plugin::RequestClassMethods)
-            self::RodaRequest.extend(plugin::RequestClassMethods)
-          end
-          if defined?(plugin::ResponseMethods)
-            self::RodaResponse.send(:include, plugin::ResponseMethods)
-          end
-          if defined?(plugin::ResponseClassMethods)
-            self::RodaResponse.extend(plugin::ResponseClassMethods)
-          end
-          
-          if plugin.respond_to?(:configure)
-            plugin.configure(self, *args, &block)
-          end
+          raise RodaError, "Cannot subclass a frozen Roda class" if frozen?
+          plugin = RodaPlugins.load_plugin(plugin) if plugin.is_a?(Symbol)
+          plugin.load_dependencies(self, *args, &block) if plugin.respond_to?(:load_dependencies)
+          include(plugin::InstanceMethods) if defined?(plugin::InstanceMethods)
+          extend(plugin::ClassMethods) if defined?(plugin::ClassMethods)
+          self::RodaRequest.send(:include, plugin::RequestMethods) if defined?(plugin::RequestMethods)
+          self::RodaRequest.extend(plugin::RequestClassMethods) if defined?(plugin::RequestClassMethods)
+          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)
         end
 
-        # Include the given module in the request class. If a block
-        # is provided instead of a module, create a module using the
-        # the block. Example:
-        #
-        #   Roda.request_module SomeModule
-        #
-        #   Roda.request_module do
-        #     def description
-        #       "#{request_method} #{path_info}"
-        #     end
-        #   end
-        #
-        #   Roda.route do |r|
-        #     r.description
-        #   end
         def request_module(mod = nil, &block)
+          RodaPlugins.deprecate("Roda.request_module is deprecated and will be removed in Roda 2.  It has been moved to the module_include plugin.")
           module_include(:request, mod, &block)
         end
     
-        # Include the given module in the response class. If a block
-        # is provided instead of a module, create a module using the
-        # the block. Example:
-        #
-        #   Roda.response_module SomeModule
-        #
-        #   Roda.response_module do
-        #     def error!
-        #       self.status = 500
-        #     end
-        #   end
-        #
-        #   Roda.route do |r|
-        #     response.error!
-        #   end
         def response_module(mod = nil, &block)
+          RodaPlugins.deprecate("Roda.response_module is deprecated and will be removed in Roda 2.  It has been moved to the module_include plugin.")
           module_include(:response, mod, &block)
         end
 
@@ -271,7 +243,7 @@ class Roda
         #
         #   Roda.use Rack::Session::Cookie, :secret=>ENV['secret']
         def use(*args, &block)
-          @middleware << [args, block]
+          @middleware << [args, block].freeze
           build_rack_app
         end
 
@@ -287,7 +259,7 @@ class Roda
           end
         end
 
-        # Backbone of the request_module and response_module support.
+        # REMOVE20
         def module_include(type, mod)
           if type == :response
             klass = self::RodaResponse
@@ -357,7 +329,7 @@ class Roda
         end
 
         # The session hash for the current request. Raises RodaError
-        # if no session existsExample:
+        # if no session exists. Example:
         #
         #   session # => {}
         def session
@@ -599,7 +571,11 @@ class Roda
           e = @env
           "#{e[SCRIPT_NAME]}#{e[PATH_INFO]}"
         end
-        alias full_path_info path
+
+        def full_path_info
+          RodaPlugins.deprecate("RodaRequest#full_path_info is deprecated and will be removed in Roda 2.  Switch to using #path.")
+          path
+        end
 
         # The current path to match requests against.  This is the same as PATH_INFO
         # in the environment, which gets updated as the request is being routed.
@@ -649,7 +625,7 @@ class Roda
         #   response.status = 200
         #   response['Header-Name'] = 'Header value'
         def response
-          scope.response
+          @scope.response
         end
 
         # Return the Roda class related to this request.
@@ -888,9 +864,8 @@ class Roda
           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)
+          RodaPlugins.deprecate("The :extension matcher is deprecated and will be removed in Roda 2.  It has been moved to the path_matchers plugin.")
           consume(self.class.cached_matcher([:extension, ext]){/([^\\\/]+)\.#{ext}/})
         end
 
@@ -904,17 +879,15 @@ class Roda
           end
         end
 
-        # Match the given parameter if present, even if the parameter is empty.
-        # Adds any match to the captures.
         def match_param(key)
+          RodaPlugins.deprecate("The :param matcher is deprecated and will be removed in Roda 2.  It has been moved to the param_matchers plugin.")
           if v = self[key]
             @captures << v
           end
         end
 
-        # Match the given parameter if present and not empty.
-        # Adds any match to the captures.
         def match_param!(key)
+          RodaPlugins.deprecate("The :param! matcher is deprecated and will be removed in Roda 2.  It has been moved to the param_matchers plugin.")
           if (v = self[key]) && !v.empty?
             @captures << v
           end
@@ -949,6 +922,9 @@ class Roda
         DEFAULT_HEADERS = {"Content-Type" => "text/html".freeze}.freeze
         LOCATION = "Location".freeze
 
+        # The body for the current response.
+        attr_reader :body
+
         # The hash of response headers for the current response.
         attr_reader :headers
 
@@ -983,14 +959,8 @@ class Roda
           DEFAULT_HEADERS
         end
 
-        # Modify the headers to include a Set-Cookie value that
-        # deletes the cookie.  A value hash can be provided to
-        # override the default one used to delete the cookie.
-        # Example:
-        #
-        #   response.delete_cookie('foo')
-        #   response.delete_cookie('foo', :domain=>'example.org')
         def delete_cookie(key, value = {})
+          RodaPlugins.deprecate("RodaResponse#delete_cookie is deprecated and will be removed in Roda 2.  It has been moved to the cookies plugin.")
           ::Rack::Utils.delete_cookie_header!(@headers, key, value)
         end
 
@@ -1055,11 +1025,8 @@ class Roda
           self.class.roda_class
         end
 
-        # Set the cookie with the given key in the headers.
-        #
-        #   response.set_cookie('foo', 'bar')
-        #   response.set_cookie('foo', :value=>'bar', :domain=>'example.org')
         def set_cookie(key, value)
+          RodaPlugins.deprecate("RodaResponse#set_cookie is deprecated and will be removed in Roda 2.  It has been moved to the cookies plugin.")
           ::Rack::Utils.set_cookie_header!(@headers, key, value)
         end
 

data/lib/roda/plugins/assets.rb

@@ -197,7 +197,7 @@ class Roda
     #                 and compressing files (default: false)
     # :css_dir :: Directory name containing your css source, inside :path (default: 'css')
     # :css_headers :: A hash of additional headers for your rendered css files
-    # :css_opts :: Template options to pass to the render plugin (via :opts) when rendering css assets
+    # :css_opts :: Template options to pass to the render plugin (via :template_opts) when rendering css assets
     # :css_route :: Route under :prefix for css assets (default: :css_dir)
     # :dependencies :: A hash of dependencies for your asset files.  Keys should be paths to asset files,
     #                  values should be arrays of paths your asset files depends on.  This is used to
@@ -207,7 +207,7 @@ class Roda
     # :headers :: A hash of additional headers for both js and css rendered files
     # :js_dir :: Directory name containing your javascript source, inside :path (default: 'js')
     # :js_headers :: A hash of additional headers for your rendered javascript files
-    # :js_opts :: Template options to pass to the render plugin (via :opts) when rendering javascript assets
+    # :js_opts :: Template options to pass to the render plugin (via :template_opts) when rendering javascript assets
     # :js_route :: Route under :prefix for javascript assets (default: :js_dir)
     # :path :: Path to your asset source directory (default: 'assets')
     # :prefix :: Prefix for assets path in your URL/routes (default: 'assets')
@@ -242,7 +242,7 @@ class Roda
 
       # Load the render and caching plugins plugins, since the assets plugin
       # depends on them.
-      def self.load_dependencies(app, _opts = {})
+      def self.load_dependencies(app, _opts = nil)
         app.plugin :render
         app.plugin :caching
       end
@@ -520,7 +520,7 @@ class Roda
           if file.end_with?(".#{type}")
             ::File.read(file)
           else
-            render_asset_file(file, :opts=>self.class.assets_opts[:"#{type}_opts"])
+            render_asset_file(file, :template_opts=>self.class.assets_opts[:"#{type}_opts"])
           end
         end
 

data/lib/roda/plugins/chunked.rb

@@ -141,7 +141,10 @@ class Roda
       # :headers :: Set default additional headers to use when calling view
       def self.configure(app, opts=OPTS)
         app.opts[:chunk_by_default] = opts[:chunk_by_default]
-        app.opts[:chunk_headers] = opts[:headers]
+        if opts[:headers]
+          app.opts[:chunk_headers] = (app.opts[:chunk_headers] || {}).merge(opts[:headers])
+          app.opts[:chunk_headers].extend(RodaDeprecateMutation)
+        end
       end
 
       # Rack response body instance for chunked responses