123456789_123456789_123456789_123456789_123456789_

Module: ActionController::ConditionalGet

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

Class Method Summary

::ActiveSupport::Concern - Extended

class_methods

Define class methods from given block.

included

Evaluate given block in context of base class, so that you can write class macros here.

prepended

Evaluate given block in context of base class, so that you can write class macros here.

Instance Method Summary

Head - Included

#head

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

DSL Calls

included

[ GitHub ]


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

included do
  class_attribute :etaggers, default: []
end

Instance Method Details

#expires_in(seconds, options = {})

Sets the Cache-Control header, overwriting existing directives. This method will also ensure an HTTP ::Date header for client compatibility.

Defaults to issuing the private directive, so that intermediate caches must not cache the response.

Options

:public

If true, replaces the default private directive with the public directive.

:must_revalidate

If true, adds the must-revalidate directive.

:stale_while_revalidate

Sets the value of the stale-while-revalidate directive.

:stale_if_error

Sets the value of the stale-if-error directive.

Any additional key-value pairs are concatenated as directives. For a list of supported Cache-Control directives, see the article on MDN.

Examples

expires_in 10.minutes
# => Cache-Control: max-age=600, private

expires_in 10.minutes, public: true
# => Cache-Control: max-age=600, public

expires_in 10.minutes, public: true, must_revalidate: true
# => Cache-Control: max-age=600, public, must-revalidate

expires_in 1.hour, stale_while_revalidate: 60.seconds
# => Cache-Control: max-age=3600, private, stale-while-revalidate=60

expires_in 1.hour, stale_if_error: 5.minutes
# => Cache-Control: max-age=3600, private, stale-if-error=300

expires_in 1.hour, public: true, "s-maxage": 3.hours, "no-transform": true
# => Cache-Control: max-age=3600, public, s-maxage=10800, no-transform=true
[ GitHub ]

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

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

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

#expires_now

Sets an HTTP 1.1 Cache-Control header of no-cache. This means the resource will be marked as stale, so clients must always revalidate. Intermediate/browser caches may still store the asset.

[ GitHub ]

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

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

#fresh_when(object = nil, etag: nil, weak_etag: nil, strong_etag: nil, last_modified: nil, public: false, cache_control: {}, template: nil)

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

Options

:etag

Sets a “weak” ETag validator on the response. See the :weak_etag option.

:weak_etag

Sets a “weak” ETag validator on the response. Requests that specify an If-None-Match header may receive a 304 Not Modified response if the ETag matches exactly.

A weak ETag indicates semantic equivalence, not byte-for-byte equality, so they’re good for caching HTML pages in browser caches. They can’t be used for responses that must be byte-identical, like serving ::Range requests within a PDF file.

:strong_etag

Sets a “strong” ETag validator on the response. Requests that specify an If-None-Match header may receive a 304 Not Modified response if the ETag matches exactly.

A strong ETag implies exact equality – the response must match byte for byte. This is necessary for serving ::Range requests within a large video or PDF file, for example, or for compatibility with some CDNs that don’t support weak ETags.

:last_modified

Sets a “weak” last-update validator on the response. Subsequent requests that specify an If-Modified-Since header may receive a 304 Not Modified response if last_modified <= If-Modified-Since.

:public

By default the Cache-Control header is private. Set this option to true if you want your application to be cacheable by other devices, such as proxy caches.

:cache_control

When given, will overwrite an existing Cache-Control header. For a list of Cache-Control directives, see the article on MDN.

: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.

Examples

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

This will send a 304 Not Modified response if the request specifies a matching ETag and If-Modified-Since header. Otherwise, it will render the show template.

You can also just pass a record:

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

etag will be set to the record, and last_modified will be set to the record’s updated_at.

You can also pass an object that responds to maximum, such as a collection of records:

def index
  @articles = Article.all
  fresh_when(@articles)
end

In this case, etag will be set to the collection, and last_modified will be set to maximum(:updated_at) (the timestamp of the most recently updated record).

When passing a record or a collection, you can still specify other options, such as :public and :cache_control:

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

The above will set Cache-Control: public, no-cache in the response.

When rendering a different template than the controller/action’s default template, 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 128

def fresh_when(object = nil, etag: nil, weak_etag: nil, strong_etag: nil, last_modified: nil, public: false, cache_control: {}, template: nil)
  response.cache_control.delete(:no_store)
  weak_etag ||= etag || object unless strong_etag
  last_modified ||= object.try(:updated_at) || object.try(:maximum, :updated_at)

  if strong_etag
    response.strong_etag = combine_etags strong_etag,
      last_modified: last_modified, public: public, template: template
  elsif weak_etag || template
    response.weak_etag = combine_etags weak_etag,
      last_modified: last_modified, public: public, template: template
  end

  response.last_modified = last_modified if last_modified
  response.cache_control[:public] = true if public
  response.cache_control.merge!(cache_control)

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

#http_cache_forever(public: false)

Cache or yield the block. The cache is supposed to never expire.

You can use this method when you have an HTTP response that never changes, and the browser and proxies should cache it indefinitely.

  • public: By default, HTTP responses are private, cached only on the user’s web browser. To allow proxies to cache the response, set true to indicate that they can serve the cached response to all users.

[ GitHub ]

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

def http_cache_forever(public: false)
  expires_in 100.years, public: public

  yield if stale?(etag: request.fullpath,
                  last_modified: Time.new(2011, 1, 1).utc,
                  public: public)
end

#no_store

Sets an HTTP 1.1 Cache-Control header of no-store. This means the resource may not be stored in any cache.

[ GitHub ]

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

def no_store
  response.cache_control.replace(no_store: true)
end

#stale?(object = nil, **freshness_kwargs) ⇒ Boolean

Sets the etag and/or last_modified on the response and checks them against the request. If the request doesn’t match the provided options, it is considered stale, and the response should be rendered from scratch. Otherwise, it is fresh, and a 304 Not Modified is sent.

Options

See #fresh_when for supported options.

Examples

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

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

You can also just pass a record:

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

etag will be set to the record, and last_modified will be set to the record’s updated_at.

You can also pass an object that responds to maximum, such as a collection of records:

def index
  @articles = Article.all

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

In this case, etag will be set to the collection, and last_modified will be set to maximum(:updated_at) (the timestamp of the most recently updated record).

When passing a record or a collection, you can still specify other options, such as :public and :cache_control:

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

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

The above will set Cache-Control: public, no-cache in the response.

When rendering a different template than the controller/action’s default template, 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 227

def stale?(object = nil, **freshness_kwargs)
  fresh_when(object, **freshness_kwargs)
  !request.fresh?(response)
end