module ActionController::ConditionalGet

def combine_etags(validator, options)
  [validator, *etaggers.map { |etagger| instance_exec(options, &etagger) }].compact
end

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

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

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

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

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

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

#### Examples

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


: Sets the value of the `stale-if-error` directive.
`:stale_if_error`

: Sets the value of the `stale-while-revalidate` directive.
`:stale_while_revalidate`

: If true, adds the `must-revalidate` directive.
`:must_revalidate`

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

#### Options

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

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

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

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

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

before_action { fresh_when @article, template: "widgets/show" }

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

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

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

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

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

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

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

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

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

You can also just pass a record:

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

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

#### Examples


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

MDN](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control).
of `Cache-Control` directives, see the [article on
: When given, will overwrite an existing `Cache-Control` header. For a list
`:cache_control`

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

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

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

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

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

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

: Sets a "weak" ETag validator on the response. See the `:weak_etag` option.
`:etag`

#### Options

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

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

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

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

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

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

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

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

end
super if stale?(@article, template: "widgets/show")
def show

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

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

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

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

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

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

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

@articles = Article.all
def index

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

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

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

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

You can also just pass a record:

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

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

#### Examples

See #fresh_when for supported options.

#### Options

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

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