123456789_123456789_123456789_123456789_123456789_

Module: ActionController::ConditionalGet

Relationships & Source Files
Namespace Children
Modules:
Extension / Inclusion / Inheritance Descendants
Included In:
Base, EtagWithTemplateDigest, ::ActionView::TestCase::TestController, Rails::ApplicationController, Rails::InfoController, Rails::MailersController, Rails::WelcomeController
Super Chains via Extension / Inclusion / Inheritance
Class Chain:
Instance Chain:
Defined in: actionpack/lib/action_controller/metal/conditional_get.rb

Class Method Summary

Instance Attribute Summary

Instance Method Summary

Head - Included

#head

Returns a response that has no content (merely headers).

RackDelegation - Included

DSL Calls

included

[ GitHub ]


10
11
12
13
# File 'actionpack/lib/action_controller/metal/conditional_get.rb', line 10

included do
  class_attribute :etaggers
  self.etaggers = []
end

Instance Method Details

#expires_in(seconds, options = {})

Sets a HTTP 1.1 Cache-Control header. Defaults to issuing a private instruction, so that intermediate caches must not cache the response.

expires_in 20.minutes
expires_in 3.hours, public: true
expires_in 3.hours, public: true, must_revalidate: true

This method will overwrite an existing Cache-Control header. See www.w3.org/Protocols/rfc2616/rfc2616-sec14.html for more possibilities.

The method will also ensure a HTTP Date header for client compatibility.

[ GitHub ]

  
# File 'actionpack/lib/action_controller/metal/conditional_get.rb', line 176

def expires_in(seconds, options = {})
  response.cache_control.merge!(
    :max_age         => seconds,
    :public          => options.delete(:public),
    :must_revalidate => options.delete(:must_revalidate)
  )
  options.delete(:private)

  response.cache_control[:extras] = options.map {|k,v| "#{k}=#{v}"}
  response.date = Time.now unless response.date?
end

#expires_now

Sets a HTTP 1.1 Cache-Control header of no-cache so no caching should occur by the browser or intermediate caches (like caching proxy servers).

[ GitHub ]

  
# File 'actionpack/lib/action_controller/metal/conditional_get.rb', line 190

def expires_now
  response.cache_control.replace(:no_cache => true)
end

#fresh_when(record_or_options, additional_options = {})

Sets the etag, last_modified, or both on the response and renders a 304 Not Modified response if the request is already fresh.

Parameters:

  • :etag.

  • :last_modified.

  • :public By default the Cache-Control header is private, set this to true if you want your application to be cachable by other devices (proxy caches).

  • :template By default, the template digest for the current controller/action is included in ETags. If the action renders a different template, you can include its digest instead. If the action doesn't render a template at all, you can pass template: false to skip any attempt to check for a template digest.

Example:

def show
  @article = Article.find(params[:id])
  fresh_when(etag: @article, last_modified: @article.created_at, public: true)
end

This will render the show template if the request isn't sending a matching ETag or If-Modified-Since header and just a 304 Not Modified response if there's a match.

You can also just pass a record where last_modified will be set by calling updated_at and the etag by passing the object itself.

def show
  @article = Article.find(params[:id])
  fresh_when(@article)
end

When passing a record, you can still set whether the public header:

def show
  @article = Article.find(params[:id])
  fresh_when(@article, public: true)
end

When rendering a different template than the default controller/action style, you can indicate which digest to include in the ETag:

before_action { fresh_when @article, template: 'widgets/show' }
[ GitHub ]

  
# File 'actionpack/lib/action_controller/metal/conditional_get.rb', line 80

def fresh_when(record_or_options, additional_options = {})
  if record_or_options.is_a? Hash
    options = record_or_options
    options.assert_valid_keys(:etag, :last_modified, :public, :template)
  else
    record  = record_or_options
    options = { etag: record, last_modified: record.try(:updated_at) }.merge!(additional_options)
  end

  response.etag          = combine_etags(options)   if options[:etag] || options[:template]
  response.last_modified = options[:last_modified]  if options[:last_modified]
  response.cache_control[:public] = true            if options[:public]

  head :not_modified if request.fresh?(response)
end

#stale?(record_or_options, additional_options = {}) ⇒ Boolean

Sets the etag and/or last_modified on the response and checks it against the client request. If the request doesn't match the options provided, the request is considered stale and should be generated from scratch. Otherwise, it's fresh and we don't need to generate anything and a reply of 304 Not Modified is sent.

Parameters:

  • :etag.

  • :last_modified.

  • :public By default the Cache-Control header is private, set this to true if you want your application to be cachable by other devices (proxy caches).

  • :template By default, the template digest for the current controller/action is included in ETags. If the action renders a different template, you can include its digest instead. If the action doesn't render a template at all, you can pass template: false to skip any attempt to check for a template digest.

Example:

def show
  @article = Article.find(params[:id])

  if stale?(etag: @article, last_modified: @article.created_at)
    @statistics = @article.really_expensive_call
    respond_to do |format|
      # all the supported formats
    end
  end
end

You can also just pass a record where last_modified will be set by calling updated_at and the etag by passing the object itself.

def show
  @article = Article.find(params[:id])

  if stale?(@article)
    @statistics = @article.really_expensive_call
    respond_to do |format|
      # all the supported formats
    end
  end
end

When passing a record, you can still set whether the public header:

def show
  @article = Article.find(params[:id])

  if stale?(@article, public: true)
    @statistics = @article.really_expensive_call
    respond_to do |format|
      # all the supported formats
    end
  end
end

When rendering a different template than the default controller/action style, you can indicate which digest to include in the ETag:

def show
  super if stale? @article, template: 'widgets/show'
end
[ GitHub ]

  
# File 'actionpack/lib/action_controller/metal/conditional_get.rb', line 160

def stale?(record_or_options, additional_options = {})
  fresh_when(record_or_options, additional_options)
  !request.fresh?(response)
end