roda 1.0.0 → 1.1.0

data/lib/roda/plugins/caching.rb

@@ -0,0 +1,215 @@
+class Roda
+  module RodaPlugins
+    # The caching plugin adds methods related to HTTP caching.
+    #
+    # For proper caching, you should use either the +last_modified+ or
+    # +etag+ request methods.  
+    #
+    #   r.get '/albums/:d' do |album_id|
+    #     @album = Album[album_id]
+    #     r.last_modified @album.updated_at
+    #     view('album')
+    #   end
+    #
+    #   # or
+    #
+    #   r.get '/albums/:d' do |album_id|
+    #     @album = Album[album_id]
+    #     r.etag @album.sha1
+    #     view('album')
+    #   end
+    #
+    # Both +last_modified+ or +etag+ will immediately halt processing
+    # if there have been no modifications since the last time the
+    # client requested the resource, assuming the client uses the
+    # appropriate HTTP 1.1 request headers.
+    #
+    # This plugin also includes the +cache_control+ and +expires+
+    # response methods.  The +cache_control+ method sets the
+    # Cache-Control header using the given hash:
+    #
+    #   response.cache_control :public=>true, :max_age=>60
+    #   # Cache-Control: public, max-age=60
+    # 
+    # The +expires+ method is similar, but in addition
+    # to setting the HTTP 1.1 Cache-Control header, it also sets
+    # the HTTP 1.0 Expires header:
+    #
+    #   response.expires 60, :public=>true
+    #   # Cache-Control: public, max-age=60
+    #   # Expires: Mon, 29 Sep 2014 21:25:47 GMT
+    #
+    # The implementation was originally taken from Sinatra,
+    # which is also released under the MIT License:
+    #
+    # Copyright (c) 2007, 2008, 2009 Blake Mizerany
+    # Copyright (c) 2010, 2011, 2012, 2013, 2014 Konstantin Haase
+    # 
+    # Permission is hereby granted, free of charge, to any person
+    # obtaining a copy of this software and associated documentation
+    # files (the "Software"), to deal in the Software without
+    # restriction, including without limitation the rights to use,
+    # copy, modify, merge, publish, distribute, sublicense, and/or sell
+    # copies of the Software, and to permit persons to whom the
+    # Software is furnished to do so, subject to the following
+    # conditions:
+    # 
+    # The above copyright notice and this permission notice shall be
+    # included in all copies or substantial portions of the Software.
+    # 
+    # THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+    # EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+    # OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+    # NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+    # HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+    # WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+    # FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+    # OTHER DEALINGS IN THE SOFTWARE.
+    module Caching
+      module RequestMethods
+        LAST_MODIFIED = 'Last-Modified'.freeze
+        HTTP_IF_NONE_MATCH = 'HTTP_IF_NONE_MATCH'.freeze
+        HTTP_IF_MATCH = 'HTTP_IF_MATCH'.freeze
+        HTTP_IF_MODIFIED_SINCE = 'HTTP_IF_MODIFIED_SINCE'.freeze
+        HTTP_IF_UNMODIFIED_SINCE = 'HTTP_IF_UNMODIFIED_SINCE'.freeze
+        ETAG = 'ETag'.freeze
+        STAR = '*'.freeze
+
+        # Set the last modified time of the resource using the Last-Modified header.
+        # The +time+ argument should be a Time instance.
+        #
+        # If the current request includes an If-Modified-Since header that is
+        # equal or later than the time specified, immediately returns a response
+        # with a 304 status.
+        #
+        # If the current request includes an If-Unmodified-Since header that is
+        # before than the time specified, immediately returns a response
+        # with a 412 status.
+        def last_modified(time)
+          return unless time
+          response[LAST_MODIFIED] = time.httpdate
+          e = env
+          return if e[HTTP_IF_NONE_MATCH]
+          status = response.status
+
+          if (!status || status == 200) && (ims = time_from_header(e[HTTP_IF_MODIFIED_SINCE])) && ims >= time.to_i
+            response.status = 304
+            halt
+          end
+
+          if (!status || (status >= 200 && status < 300) || status == 412) && (ius = time_from_header(e[HTTP_IF_UNMODIFIED_SINCE])) && ius < time.to_i
+            response.status = 412
+            halt
+          end
+        end
+
+        # Set the response entity tag using the ETag header.
+        #
+        # The +value+ argument is an identifier that uniquely
+        # identifies the current version of the resource.
+        # Options:
+        # :weak :: Use a weak cache validator (a strong cache validator is the default)
+        # :new_resource :: Whether this etag should match an etag of * (true for POST, false otherwise)
+        #
+        # When the current request includes an If-None-Match header with a
+        # matching etag, immediately returns a response with a 304 or 412 status,
+        # depending on the request method.
+        #
+        # When the current request includes an If-Match header with a
+        # etag that doesn't match, immediately returns a response with a 412 status.
+        def etag(value, opts={})
+          # Before touching this code, please double check RFC 2616 14.24 and 14.26.
+          weak = opts[:weak]
+          new_resource = opts.fetch(:new_resource){post?}
+
+          response[ETAG] = etag = "#{'W/' if weak}\"#{value}\""
+          status = response.status
+          e = env
+
+          if (!status || (status >= 200 && status < 300) || status == 304)
+            if etag_matches?(e[HTTP_IF_NONE_MATCH], etag, new_resource)
+              response.status = (request_method =~ /\AGET|HEAD|OPTIONS|TRACE\z/i ? 304 : 412)
+              halt
+            end
+
+            if ifm = e[HTTP_IF_MATCH]
+              unless etag_matches?(ifm, etag, new_resource)
+                response.status = 412
+                halt
+              end
+            end
+          end
+        end
+
+        private
+
+        # Helper method checking if a ETag value list includes the current ETag.
+        def etag_matches?(list, etag, new_resource)
+          return unless list
+          return !new_resource if list == STAR
+          list.to_s.split(/\s*,\s*/).include?(etag)
+        end
+
+        # Helper method parsing a time value from an HTTP header, returning the
+        # time as an integer.
+        def time_from_header(t)
+          Time.httpdate(t).to_i if t
+        rescue ArgumentError
+        end
+      end
+
+      module ResponseMethods
+        UNDERSCORE = '_'.freeze
+        DASH = '-'.freeze
+        COMMA = ', '.freeze
+        CACHE_CONTROL = 'Cache-Control'.freeze
+        EXPIRES = 'Expires'.freeze
+        CONTENT_TYPE = 'Content-Type'.freeze
+        CONTENT_LENGTH = 'Content-Length'.freeze
+
+        # Specify response freshness policy for using the Cache-Control header.
+        # Options can can any non-value directives (:public, :private, :no_cache,
+        # :no_store, :must_revalidate, :proxy_revalidate), with true as the value.
+        # Options can also contain value directives (:max_age, :s_maxage).
+        #
+        #   response.cache_control :public=>true, :max_age => 60
+        #   # => Cache-Control: public, max-age=60
+        #
+        # See RFC 2616 / 14.9 for more on standard cache control directives:
+        # http://tools.ietf.org/html/rfc2616#section-14.9.1
+        def cache_control(opts)
+          values = []
+          opts.each do |k, v|
+            next unless v
+            k = k.to_s.tr(UNDERSCORE, DASH)
+            values << (v == true ? k : "#{k}=#{v}")
+          end
+
+          self[CACHE_CONTROL] = values.join(COMMA) unless values.empty?
+        end
+
+        # Set Cache-Control header with the max_age given.  max_age should
+        # be an integer number of seconds that the current request should be
+        # 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={})
+          cache_control(opts.merge(:max_age=>max_age))
+          self[EXPIRES] = (Time.now + max_age).httpdate
+        end
+
+        # Remove Content-Type and Content-Length for 304 responses.
+        def finish
+          a = super
+          if a[0] == 304
+            h = a[1]
+            h.delete(CONTENT_TYPE)
+            h.delete(CONTENT_LENGTH)
+          end
+          a
+        end
+      end
+    end
+
+    register_plugin(:caching, Caching)
+  end
+end

data/lib/roda/plugins/chunked.rb

@@ -0,0 +1,278 @@
+class Roda
+  module RodaPlugins
+    # The chunked plugin allows you to stream responses to clients using
+    # Transfer-Encoding: chunked.  This can significantly improve performance
+    # of page rendering on the client, as it flushes the headers and top part
+    # of the layout template (generally containing references to the stylesheet
+    # and javascript assets) before rendering the content template.
+    #
+    # This allows the client to fetch the assets while the template is still
+    # being rendered.  Additionally, this plugin makes it easy to defer
+    # executing code required to render the content template until after
+    # the top part of the layout has been flushed, so the client can fetch the
+    # assets while the application is still doing the necessary processing in
+    # order to render the content template, such as retrieving values from a
+    # database.
+    #
+    # There are a couple disadvantages of streaming using chunked encoding.
+    # First is that the layout must be rendered before the content, so any state 
+    # changes made in your content template will not affect the layout template.
+    # Second, error handling is reduced, since if an error occurs while
+    # rendering a template, a successful response code has already been sent.
+    #
+    # To use chunked encoding for a response, just call the chunked method
+    # instead of view:
+    #
+    #   r.root do
+    #     chunked(:index)
+    #   end
+    #
+    # If you want to execute code after flushing the top part of the layout
+    # template, but before rendering the content template, pass a block to
+    # chunked:
+    #
+    #   r.root do
+    #     chunked(:index) do
+    #       # expensive calculation here
+    #     end
+    #   end
+    #
+    # If you want to chunk all responses, pass the :chunk_by_default option
+    # when loading the plugin:
+    #
+    #   plugin :chunked, :chunk_by_default => true
+    #
+    # then you can just use the normal view method:
+    #
+    #   r.root do
+    #     view(:index)
+    #   end
+    #
+    # and it will chunk the response.  Note that you still need to call
+    # chunked if you want to pass a block of code to be executed after flushing
+    # the layout and before rendering the content template. Also, before you
+    # enable chunking by default, you need to make sure that none of your
+    # content templates make state changes that affect the layout template.
+    # Additionally, make sure nowhere in your app are you doing any processing
+    # after the call to view.
+    #
+    # If you use :chunk_by_default, but want to turn off chunking for a view,
+    # call no_chunk!:
+    #
+    #   r.root do
+    #     no_chunk!
+    #     view(:index)
+    #   end
+    #
+    # Inside your layout or content templates, you can call the flush method
+    # to flush the current result of the template to the user, useful for
+    # streaming large datasets.
+    #
+    #   <% (1..100).each do |i| %>
+    #     <%= i %>
+    #     <% sleep 0.1 %>
+    #     <% flush %>
+    #   <% end %>
+    #
+    # Note that you should not call flush from inside subtemplates of the
+    # content or layout templates, unless you are also calling flush directly
+    # before rendering the subtemplate, and also directly injecting the
+    # subtemplate into the current template without modification.  So if you
+    # are using the above template code in a subtemplate, in your content
+    # template you should do:
+    #
+    #   <% flush %><%= render(:subtemplate) %>
+    #
+    # If you want to use chunked encoding when rendering a template, but don't
+    # want to use a layout, pass the :layout=>false option to chunked.
+    #
+    #   r.root do
+    #     chunked(:index, :layout=>false)
+    #   end
+    #
+    # In order to handle errors in chunked responses, you can override the
+    # handle_chunk_error method:
+    #
+    #   def handle_chunk_error(e)
+    #     env['rack.logger'].error(e)
+    #   end
+    #
+    # It is possible to set @_out_buf to an error notification and call
+    # flush to output the message to the client inside handle_chunk_error.
+    #
+    # In order for chunking to work, you must make sure that no proxies between
+    # the application and the client buffer responses.  Also, this
+    # plugin only works for HTTP/1.1 requests since Transfer-Encoding: chunked
+    # is not supported in HTTP/1.0.  If an HTTP/1.0 request is submitted, this
+    # plugin will automatically fallback to the normal template rendering.
+    # Note that some proxies including nginx default to HTTP/1.0 even if the
+    # client supports HTTP/1.1.  For nginx, set the proxy_http_version to 1.1.
+    #
+    # If you are using nginx and have it set to buffer proxy responses by
+    # default, you can turn this off on a per response basis using the
+    # X-Accel-Buffering header.  To set this header or similar headers for
+    # all chunked responses, pass a :headers option when loading the plugin:
+    #
+    #   plugin :chunked, :headers=>{'X-Accel-Buffering'=>'no'}
+    #
+    # The chunked plugin requires the render plugin, and only works for
+    # template engines that store their template output variable in
+    # @_out_buf.  Also, it only works if the content template is directly
+    # injected into the layout template without modification.
+    #
+    # If using the chunked plugin with the flash plugin, make sure you
+    # call the flash method early in your route block.  If the flash
+    # method is not called until template rendering, the flash may not be
+    # rotated.
+    module Chunked
+      HTTP_VERSION = 'HTTP_VERSION'.freeze
+      HTTP11 = "HTTP/1.1".freeze
+      TRANSFER_ENCODING = 'Transfer-Encoding'.freeze
+      CHUNKED = 'chunked'.freeze
+      OPTS = {}.freeze
+
+      # Depend on the render plugin
+      def self.load_dependencies(app, opts=OPTS)
+        app.plugin :render
+      end
+
+      # Set plugin specific options.  Options:
+      # :chunk_by_default :: chunk all calls to view by default
+      # :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]
+      end
+
+      # Rack response body instance for chunked responses
+      class Body
+        CHUNK_SIZE = "%x\r\n".freeze
+        CRLF = "\r\n".freeze
+        FINISH = "0\r\n\r\n".freeze
+
+        # Save the scope of the current request handling.
+        def initialize(scope)
+          @scope = scope
+        end
+
+        # For each response chunk yielded by the scope,
+        # yield it it to the caller in chunked format, starting
+        # with the size of the request in ASCII hex format, then
+        # the chunk.  After all chunks have been yielded, yield
+        # a 0 sized chunk to finish the response.
+        def each
+          @scope.each_chunk do |chunk|
+            next if !chunk || chunk.empty?
+            yield(CHUNK_SIZE % chunk.bytesize)
+            yield(chunk)
+            yield(CRLF)
+          end
+        ensure
+          yield(FINISH)
+        end
+      end
+
+      module InstanceMethods
+        # Disable chunking for the current request.  Mostly useful when
+        # chunking is turned on by default.
+        def no_chunk!
+          @_chunked = false
+        end
+
+        # If chunking by default, call chunked if it hasn't yet been
+        # called and chunking is not specifically disabled.
+        def view(*a)
+          if opts[:chunk_by_default] && !defined?(@_chunked)
+            chunked(*a)
+          else
+            super
+          end
+        end
+
+        # Render a response to the user in chunks.  See Chunked for
+        # an overview.
+        def chunked(template, opts=OPTS, &block)
+          unless defined?(@_chunked)
+            @_chunked = env[HTTP_VERSION] == HTTP11
+          end
+
+          unless @_chunked
+            # If chunking is disabled, do a normal rendering of the view.
+            yield if block
+            return view(template, opts)
+          end
+
+          if template.is_a?(Hash)
+            if opts.empty?
+              opts = template
+            else
+              opts = opts.merge(template)
+            end
+          end
+          
+          # Hack so that the arguments don't need to be passed
+          # through the response and body objects.
+          @_each_chunk_args = [template, opts, block]
+
+          res = response
+          headers = res.headers
+          if chunk_headers = self.opts[:chunk_headers]
+            headers.merge!(chunk_headers)
+          end
+          headers[TRANSFER_ENCODING] = CHUNKED
+
+          throw :halt, res.finish_with_body(Body.new(self))
+        end
+
+        # Yield each chunk of the template rendering separately.
+        def each_chunk
+          response.body.each{|s| yield s}
+
+          template, opts, block = @_each_chunk_args
+
+          # Use a lambda for the flusher, so that a call to flush
+          # by a template can result in this method yielding a chunk
+          # of the response.
+          @_flusher = lambda do
+            yield @_out_buf
+            @_out_buf = ''
+          end
+
+          if layout =  opts.fetch(:layout, render_opts[:layout])
+            if layout_opts = opts[:layout_opts]
+              layout_opts = render_opts[:layout_opts].merge(layout_opts)
+            end
+
+            @_out_buf = render(layout, layout_opts||OPTS) do
+              flush
+              block.call if block
+              yield opts[:content] || render(template, opts)
+              nil
+            end
+          else
+            yield if block
+            yield view(template, opts)
+          end
+
+          flush
+        rescue => e
+          handle_chunk_error(e)
+        end
+
+        # By default, raise the exception.
+        def handle_chunk_error(e)
+          raise e
+        end
+
+        # Call the flusher if one is defined.  If one is not defined, this
+        # is a no-op, so flush can be used inside views without breaking
+        # things if chunking is not used.
+        def flush
+          @_flusher.call if @_flusher
+        end
+      end
+    end
+
+    register_plugin(:chunked, Chunked)
+  end
+end