instance method fresh_when

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 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 set If-None-Match header may return a 304 Not Modified response if it matches the ETag 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 set If-None-Match header may return a 304 Not Modified response if it matches the ETag exactly. A strong ETag implies exact equality: the response must match byte for byte. This is necessary for doing 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 set If-Modified-Since may return a 304 Not Modified response if last_modified <= If-Modified-Since.

• :public By default the Cache-Control header is private, set this to true if you want your application to be cacheable 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.updated_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. In this case last_modified will be set by calling updated_at and etag by passing the object itself.

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

You can also pass an object that responds to maximum, such as a collection of active records. In this case last_modified will be set by calling maximum(:updated_at) on the collection (the timestamp of the most recently updated record) and the etag by passing the object itself.

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

When passing a record or a collection, you can still set 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' }