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].
of supported +Cache-Control+ directives, see the {article on
Any additional key-value pairs are concatenated as directives. For a list

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

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

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

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.
resource will be marked as stale, so clients must always revalidate.
Sets an HTTP 1.1 +Cache-Control+ header of no-cache. This means the

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

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

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

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

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

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:

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

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

==== Examples

for a template digest.
all, you can pass template: false to skip any attempt to check
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].
list of +Cache-Control+ directives, see the {article on
When given, will overwrite an existing +Cache-Control+ header. For a
[+:cache_control+]
such as proxy caches.
+true+ if you want your application to be cacheable by other devices,
By default the +Cache-Control+ header is private. Set this option to
[+:public+]
response if +last_modified+ <= +If-Modified-Since+.
that specify an +If-Modified-Since+ header may receive a 304 Not Modified
Sets a "weak" last-update validator on the response. Subsequent requests
[+:last_modified+]
don't support weak ETags.
video or PDF file, for example, or for compatibility with some CDNs that
byte. This is necessary for serving +Range+ requests within a large
A strong ETag implies exact equality -- the response must match byte for

if the ETag matches exactly.
+If-None-Match+ header may receive a 304 Not Modified response
Sets a "strong" ETag validator on the response. Requests that specify an
[+:strong_etag+]
requests within a PDF file.
used for responses that must be byte-identical, like serving +Range+
so they're good for caching HTML pages in browser caches. They can't be
A weak ETag indicates semantic equivalence, not byte-for-byte equality,

if the ETag matches exactly.
+If-None-Match+ header may receive a 304 Not Modified response
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

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

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

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

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

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

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

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

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

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

@articles = Article.all
def index

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

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

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

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