roda 2.2.0 → 2.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 9bbbb565f4b5766e8e11f78d322a5446da6358bd
-  data.tar.gz: 4e7b782d3d4a2292e9461c47053156a18d56bec2
+  metadata.gz: 9c94569f43d36e67b81fa0f67d739a24f9b5a594
+  data.tar.gz: 8420ceb5dafb0f76e840fdeff028e46f4b0842f9
 SHA512:
-  metadata.gz: 864fd659136483c2867b91e6512df778fd9f331c60e30b8166f1146afda0810cb1f08d56b38f2c01f50d7fcd477b9914def3d0eb1479de2533f0db8f94dc3dc3
-  data.tar.gz: 79dcb04899e305ed875f439d3ebb57cbaf9092bba1614e8fcbbb4b15da55c9b10c74086f3bf24e7b543b9dcaaf9f3042009ab611a9e7b7f0aa0b0077a91a32b0
+  metadata.gz: ab68ffe4810164018008821e8a8ae7a66469a58884ff5a25599e0cac03330e393d9b62cf5d8712ceea8e9a870afd431f52a072294c710285a7e69d1a243326b0
+  data.tar.gz: ab79ec088d85b8daa3f705fb92bcd9e64be19ae9a5bf131f9414fca72c53a89f00a9c82465ed8db68440bf120a783c1ad4e521e295f15868a4a372463ecf8a06

data/CHANGELOG

@@ -1,3 +1,37 @@
+= 2.3.0 (2015-05-13)
+
+* Make assets plugin work better with json plugin when r.assets is the last method called in a route block (jeremyevans) (#27)
+
+* Support no_mail! method in the mailer plugin, for skipping an email (jeremyevans)
+
+* Add precompile_templates plugin, for saving memory when using a forking webserver (jeremyevans)
+
+* Document how to allow per-branch HTML escaping of <%= %> in the view_options plugin (jeremyevans)
+
+* Add :include_request option to json and json_parser plugins to include request in :serializer/:parser call (janko-m) (#26)
+
+* Optimize template cache lookup in render plugin when :cache_key is given (jeremyevans)
+
+* Add :engine_opts option to render plugin, for specifying per-template engine options (jeremyevans)
+
+* The render plugin and render/view :ext option is now replaced by the :engine option (jeremyevans)
+
+* Add path_rewriter plugin, for rewriting paths before routing (jeremyevans)
+
+* Add :cache_key option to render/view to explicitly set the template cache key (jeremyevans)
+
+* Don't cache templates if :template_block is given to render/view, unless :cache=>true is used  (jeremyevans)
+
+* Add :cache option to render/view to force caching or not caching the template (jeremyevans)
+
+* Avoid rehashing hashes at runtime in plugins (jeremyevans)
+
+* Add heartbeat plugin for heartbeat support (jeremyevans)
+
+* Support :serializer option in json plugin (janko-m) (#21)
+
+* Add json_parser plugin, for parsing request bodies in JSON format (jeremyevans)
+
 = 2.2.0 (2015-04-13)
 
 * Add :escaper render plugin option to support custom escaping of <%= %> tags when :escape is used (jeremyevans)

data/Rakefile

@@ -66,53 +66,29 @@ end
 
 ### Specs
 
-begin
-  begin
-    raise LoadError if ENV['RSPEC1']
-    # RSpec 2
-    require "rspec/core/rake_task"
-    spec_class = RSpec::Core::RakeTask
-    spec_files_meth = :pattern=
-  rescue LoadError
-    # RSpec 1
-    require "spec/rake/spectask"
-    spec_class = Spec::Rake::SpecTask
-    spec_files_meth = :spec_files=
-  end
-
-  spec = lambda do |name, files, d|
-    lib_dir = File.join(File.dirname(File.expand_path(__FILE__)), 'lib')
-    ENV['RUBYLIB'] ? (ENV['RUBYLIB'] += ":#{lib_dir}") : (ENV['RUBYLIB'] = lib_dir)
-
-    desc "#{d} with -w, some warnings filtered"
-    task "#{name}_w" do
-      ENV['RUBYOPT'] ? (ENV['RUBYOPT'] += " -w") : (ENV['RUBYOPT'] = '-w')
-      rake = ENV['RAKE'] || "#{FileUtils::RUBY} -S rake"
-      sh "#{rake} #{name} 2>&1 | egrep -v \"(spec/.*: warning: (possibly )?useless use of == in void context|: warning: instance variable @.* not initialized|: warning: method redefined; discarding old|: warning: previous definition of)|rspec\""
-    end
-
-    desc d
-    spec_class.new(name) do |t|
-      t.send spec_files_meth, files
-      t.spec_opts = ENV["#{NAME.upcase}_SPEC_OPTS"].split if ENV["#{NAME.upcase}_SPEC_OPTS"]
-    end
-  end
-
-  spec_with_cov = lambda do |name, files, d|
-    spec.call(name, files, d)
-    desc "#{d} with coverage"
-    task "#{name}_cov" do
-      ENV['COVERAGE'] = '1'
-      Rake::Task[name].invoke
-    end
-  end
+spec = proc do |env|
+  env.each{|k,v| ENV[k] = v}
+  sh "#{FileUtils::RUBY} -rubygems -I lib -e 'ARGV.each{|f| require f}' ./spec/*_spec.rb ./spec/plugin/*_spec.rb"
+  env.each{|k,v| ENV.delete(k)}
+end
+
+desc "Run specs"
+task "spec" do
+  spec.call({})
+end
+
+task :default=>:spec
+
+desc "Run specs with coverage"
+task "spec_cov" do
+  spec.call('COVERAGE'=>'1')
+end
   
-  task :default => [:spec]
-  spec_with_cov.call("spec", Dir["spec/*_spec.rb"] + Dir["spec/plugin/*_spec.rb"], "Run specs")
-rescue LoadError
-  task :default do
-    puts "Must install rspec to run the default task (which runs specs)"
-  end
+desc "Run specs with -w, some warnings filtered"
+task "spec_w" do
+  ENV['RUBYOPT'] ? (ENV['RUBYOPT'] += " -w") : (ENV['RUBYOPT'] = '-w')
+  rake = ENV['RAKE'] || "#{FileUtils::RUBY} -S rake"
+  sh %{#{rake} 2>&1 | egrep -v \": warning: instance variable @.* not initialized|: warning: method redefined; discarding old|: warning: previous definition of|: warning: statement not reached"}
 end
 
 ### Other

data/doc/release_notes/2.3.0.txt

@@ -0,0 +1,109 @@
+= New Plugins
+
+* A json_parser plugin has been added, for parsing request bodies in
+  JSON format.  This is faster than using a middleware to perform
+  the same task.  This plugin supports a :parser option to use a
+  custom JSON parser, an :include_request option to include the
+  request when calling the parser, and a :error_handler option for
+  a proc to call with the request if there is an error when parsing.
+  Example:
+
+    plugin :json_parser,
+      :parser=>JSON.method(:parse),
+      :include_request=>false,
+      :error_handler=>proc{|r| r.halt [400, {}, []]} 
+
+* A path_rewriter plugin has been added, allowing for the rewriting
+  of paths before routing.  This allows you to rewrite just the
+  routing path (the default), or PATH_INFO as well as the routing
+  path (if the :path_info option is used).  This is useful if you
+  want to internally treat one path exactly the same as another
+  path.
+
+  By default, path rewriting is done on prefixes, so any path that
+  starts with the prefix will be rewritten.  You can pass a
+  Regexp when rewriting the path for more complete control.
+
+  Examples:
+
+    plugin :path_rewriter
+    rewrite_path '/a', '/b'
+    # GET /a treated as GET /b
+    # GET /a/c treated as GET /b/c
+
+    rewrite_path /\A\/c\z/, '/d'
+    # GET /c treated as GET /d
+    # GET /c/e no change
+
+* A precompiled_templates plugin has been added, for precompiling
+  templates before starting the application.  This can save a
+  substantial amount of memory if you are using large templates or
+  a large number of small templates in conjunction when using
+  application preloading with a forking webserver.  Example:
+
+    plugin :precompile_templates
+    precompile_templates "views/\*\*/*.erb"
+    precompile_templates "views/users/_*.erb", :locals=>[:user]
+
+* A heartbeat plugin has been added, for easily handling
+  heartbeat/status requests.  If a heartbeat/status request comes in,
+  it will get a 200 response with a body of "OK".  This is designed
+  for automated systems that check if the application is functioning.
+  The default heartbeat path is /heartbeat, but you can choose a
+  different one using the :path option.
+
+    plugin :heartbeat, :path=>'/heartbeat'
+
+= Other New Features
+
+* The json plugin now supports a :serializer option to use a custom
+  serializer.  Additionally, it now supports a :include_request
+  option to include the request when calling the serializer.
+
+* In the render plugin, the render/view methods now support a
+  :cache=>false option to not cache the template.  This can be useful
+  for large but rarely used templates, or where a new template object
+  is created for every render/view call.
+
+* In the render plugin, the render/view methods now support a
+  :cache_key option to force a specific cache key.  Manually setting
+  cache keys can result in improved performance, as automatically
+  determining the cache key can be a relatively expensive operation.
+
+* The render plugin now supports a :engine_opts option, to specify
+  per-template engine options.  :engine options should be a hash
+  keyed by render engine strings, with values being hashes of
+  template options.
+
+* In the mailer plugin, a no_mail! method is now supported when
+  mailing, which will skip the current mail.  This makes it easier
+  to delay the decision about actually sending the email till it is
+  time to send the email, which makes it easier to avoid race
+  conditions if you are using a job queue for mailing.
+
+= Other Improvements
+
+* Roda avoids rehashing hashes at runtime in some places, for a minor
+  speedup.
+
+* If the :template_block is given to render/view, default to not
+  caching the template, since it is likely the template block is
+  specific to the request.  Allow for the :cache=>true option to be
+  used to force the caching of the template.
+
+* Roda now returns a 404 response for unmatched GET requests when
+  using the assets and json plugins where r.assets is the last
+  method called in a route block.
+
+= Backwards Compatibility
+
+* In the render plugin, the :ext option to the plugin and to the
+  render/view methods is now replaced by the :engine option.
+  Previously, :engine was used by default if :ext was not given. In
+  general, there is no need for two separate options, the engine is
+  used as the extension by Tilt.
+
+  In general, this is a backwards compatible change, except when
+  both :ext and :engine were specified differently as plugin options,
+  and an inline template is used with render or view without either
+  the :ext or :engine options being specified.

data/lib/roda/plugins/assets.rb

@@ -214,7 +214,7 @@ class Roda
     # :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').   Relative
-    #            paths will be considered relative to the application's :root option.
+    #          paths will be considered relative to the application's :root option.
     # :prefix :: Prefix for assets path in your URL/routes (default: 'assets')
     # :precompiled :: Path to the compiled asset metadata file.  If the file exists, will use compiled
     #                 mode using the metadata in the file.  If the file does not exist, will use
@@ -611,6 +611,7 @@ class Roda
                 scope.render_asset(file, type)
               end
             end
+            nil
           end
         end
       end

data/lib/roda/plugins/caching.rb

@@ -197,7 +197,7 @@ class Roda
         # cached for.  Also sets the Expires header, useful if you have
         # HTTP 1.0 clients (Cache-Control is an HTTP 1.1 header).
         def expires(max_age, opts=OPTS)
-          cache_control(opts.merge(:max_age=>max_age))
+          cache_control(Hash[opts].merge!(:max_age=>max_age))
           self[EXPIRES] = (Time.now + max_age).httpdate
         end
 

data/lib/roda/plugins/chunked.rb

@@ -229,7 +229,7 @@ class Roda
             if opts.empty?
               opts = template
             else
-              opts = opts.merge(template)
+              opts = Hash[opts].merge!(template)
             end
           end
           

data/lib/roda/plugins/error_email.rb

@@ -92,7 +92,7 @@ END
         def error_email(e)
           email_opts = self.class.opts[:error_email].dup
           headers = email_opts[:default_headers].call(email_opts, e)
-          headers = headers.merge(email_opts[:headers])
+          headers = Hash[headers].merge!(email_opts[:headers])
           headers = headers.map{|k,v| "#{k}: #{v.gsub(/\r?\n/m, "\r\n ")}"}.sort.join("\r\n")
           body = email_opts[:body].call(self, e)
           email_opts[:message] = "#{headers}\r\n\r\n#{body}"

data/lib/roda/plugins/head.rb

@@ -22,6 +22,12 @@ class Roda
     #
     # HEAD requests for +/+, +/a+, and +/b+ will all return 200 status
     # with an empty body.
+    #
+    # NOTE: if you have a public facing website it is recommended that
+    # you enable this plugin. Search engines and other bots may send a
+    # HEAD request prior to crawling a page with a GET request. Without
+    # this plugin those HEAD requests will return a 404 status, which
+    # may prevent search engine's from crawling your website.
     module Head
       EMPTY_ARRAY = [].freeze
 

data/lib/roda/plugins/heartbeat.rb

@@ -0,0 +1,40 @@
+class Roda
+  module RodaPlugins
+    # The heartbeat handles heartbeat/status requests.  If a request for
+    # the heartbeat path comes in, a 200 response with a
+    # text/plain Content-Type and a body of "OK" will be returned.
+    # The default heartbeat path is "/heartbeat", so to use that:
+    #
+    #   plugin :heartbeat
+    #
+    # You can also specify a custom heartbeat path:
+    #
+    #   plugin :heartbeat, :path=>'/status'
+    module Heartbeat
+      OPTS = {}.freeze
+      PATH_INFO = 'PATH_INFO'.freeze
+      HEARTBEAT_RESPONSE = [200, {'Content-Type'=>'text/plain'}.freeze, ['OK'.freeze].freeze].freeze
+
+      # Set the heartbeat path to the given path.
+      def self.configure(app, opts=OPTS)
+        app.opts[:heartbeat_path] = (opts[:path] || app.opts[:heartbeat_path] || "/heartbeat").dup.freeze
+      end
+
+      module InstanceMethods
+        # If the request is for a heartbeat path, return the heartbeat response.
+        def call
+          if env[PATH_INFO] == opts[:heartbeat_path]
+            response = HEARTBEAT_RESPONSE.dup
+            response[1] = Hash[response[1]]
+            response
+          else
+            super
+          end
+        end
+      end
+    end
+
+    register_plugin(:heartbeat, Heartbeat)
+  end
+end
+

data/lib/roda/plugins/json.rb

@@ -32,16 +32,34 @@ class Roda
     # using the :classes option when loading the plugin:
     #
     #   plugin :json, :classes=>[Array, Hash, Sequel::Model]
+    #
+    # By default objects are serialized with +to_json+, but you
+    # can pass in a custom serializer, which can be any object
+    # that responds to +call(object)+.
+    #
+    #   plugin :json, :serializer=>proc{|o| o.to_json(root: true)}
+    #
+    # If you need the request information during serialization, such
+    # as HTTP headers or query parameters, you can pass in the
+    # +:include_request+ option, which will pass in the request
+    # object as the second argument when calling the serializer.
+    #
+    #   plugin :json, include_request=>true, serializer=>proc{|o, request| ...}
     module Json
       OPTS = {}.freeze
+      DEFAULT_SERIALIZER = lambda{|o| o.to_json}
 
-      # Set the classes to automatically convert to JSON
+      # Set the classes to automatically convert to JSON, and the serializer to use.
       def self.configure(app, opts=OPTS)
         classes = opts[:classes] || [Array, Hash]
         app.opts[:json_result_classes] ||= []
         app.opts[:json_result_classes] += classes
         app.opts[:json_result_classes].uniq!
         app.opts[:json_result_classes].freeze
+
+        app.opts[:json_result_serializer] = opts[:serializer] || app.opts[:json_result_serializer] || DEFAULT_SERIALIZER
+
+        app.opts[:json_result_include_request] = opts[:include_request] || app.opts[:json_result_include_request]
       end
 
       module ClassMethods
@@ -71,9 +89,11 @@ class Roda
         end
 
         # Convert the given object to JSON.  Uses to_json by default,
-        # but can be overridden to use a different implementation.
+        # but can use a custom serializer passed to the plugin.
         def convert_to_json(obj)
-          obj.to_json
+          args = [obj]
+          args << self if roda_class.opts[:json_result_include_request]
+          roda_class.opts[:json_result_serializer].call(*args)
         end
       end
     end

data/lib/roda/plugins/json_parser.rb

@@ -0,0 +1,72 @@
+require 'json'
+
+class Roda
+  module RodaPlugins
+    # The json_parser plugin parses request bodies in json format
+    # if the request's content type specifies json. This is mostly
+    # designed for use with JSON API sites.
+    #
+    # This only parses the request body as JSON if the Content-Type
+    # header for the request includes "json".
+    module JsonParser
+      OPTS = {}.freeze
+      JSON_PARAMS_KEY = "roda.json_params".freeze
+      INPUT_KEY = "rack.input".freeze
+      FORM_HASH_KEY = "rack.request.form_hash".freeze
+      FORM_INPUT_KEY = "rack.request.form_input".freeze
+      DEFAULT_ERROR_HANDLER = proc{|r| r.halt [400, {}, []]}
+      DEFAULT_PARSER = JSON.method(:parse)
+
+      # Handle options for the json_parser plugin:
+      # :error_handler :: A proc to call if an exception is raised when
+      #                   parsing a JSON request body.  The proc is called
+      #                   with the request object, and should probably call
+      #                   halt on the request or raise an exception.
+      # :parser :: The parser to use for parsing incoming json.  Should be
+      #            an object that responds to +call(str)+ and returns the
+      #            parsed data.  The default is to call JSON.parse.
+      # :include_request :: If true, the parser will be called with the request
+      #                     object as the second argument, so the parser needs
+      #                     to respond to +call(str, request)+.
+      def self.configure(app, opts=OPTS)
+        app.opts[:json_parser_error_handler] = opts[:error_handler] || app.opts[:json_parser_error_handler] || DEFAULT_ERROR_HANDLER
+        app.opts[:json_parser_parser] = opts[:parser] || app.opts[:json_parser_parser] || DEFAULT_PARSER
+        app.opts[:json_parser_include_request] = opts[:include_request] || app.opts[:json_parser_include_request]
+      end
+
+      module RequestMethods
+        # If the Content-Type header in the request includes "json",
+        # parse the request body as JSON.  Ignore an empty request body.
+        def POST
+          env = @env
+          if post_params = (env[JSON_PARAMS_KEY] || env[FORM_HASH_KEY])
+            post_params
+          elsif (input = env[INPUT_KEY]) && content_type =~ /json/
+            str = input.read
+            input.rewind
+            return super if str.empty?
+            begin
+              json_params = env[JSON_PARAMS_KEY] = parse_json(str)
+            rescue
+              roda_class.opts[:json_parser_error_handler].call(self)
+            end
+            env[FORM_INPUT_KEY] = input
+            json_params
+          else
+            super
+          end
+        end
+
+        private
+
+        def parse_json(str)
+          args = [str]
+          args << self if roda_class.opts[:json_parser_include_request]
+          roda_class.opts[:json_parser_parser].call(*args)
+        end
+      end
+    end
+
+    register_plugin(:json_parser, JsonParser)
+  end
+end