Module: ActionController::ConditionalGet

Extended by:
ActiveSupport::Concern
Includes:
Head
Included in:
Base, EtagWithFlash, EtagWithTemplateDigest
Defined in:
lib/action_controller/metal/conditional_get.rb

Defined Under Namespace

Modules: ClassMethods

Instance Method Summary collapse

Methods included from Head

#head

Instance Method Details

#expires_in(seconds, options = {}) ⇒ Object

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.

‘:immutable` : If true, adds the `immutable` directive.

Any additional key-value pairs are concatenated as directives. For a list of supported ‘Cache-Control` directives, see the [article on MDN](developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control).

#### 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



290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
 
# File 'lib/action_controller/metal/conditional_get.rb', line 290

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),
    immutable: options.delete(:immutable),
  )
  options.delete(:private)

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

#expires_now ⇒ Object

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.



309
310
311
 
# File 'lib/action_controller/metal/conditional_get.rb', line 309

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) ⇒ Object

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](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control).

‘: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" }



137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
 
# File 'lib/action_controller/metal/conditional_get.rb', line 137

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) ⇒ Object

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.



321
322
323
324
325
326
327
 
# File 'lib/action_controller/metal/conditional_get.rb', line 321

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

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

#no_store ⇒ Object

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



331
332
333
 
# File 'lib/action_controller/metal/conditional_get.rb', line 331

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

Returns:

  • (Boolean) 


236
237
238
239
 
# File 'lib/action_controller/metal/conditional_get.rb', line 236

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