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:
self,
::ActiveSupport::Concern
|
|
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
-
#expires_in(seconds, options = {})
Sets the
Cache-Control
header, overwriting existing directives. -
#expires_now
Sets an HTTP 1.1
Cache-Control
header ofno-cache
. -
#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 a304 Not Modified
response if the request is already fresh. -
#http_cache_forever(public: false)
Cache or yield the block.
-
#no_store
Sets an HTTP 1.1
Cache-Control
header ofno-store
. -
#stale?(object = nil, **freshness_kwargs) ⇒ Boolean
Sets the
etag
and/orlast_modified
on the response and checks them against the request.
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 thepublic
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
# File 'actionpack/lib/action_controller/metal/conditional_get.rb', line 274
def expires_in(seconds, = {}) response.cache_control.delete(:no_store) response.cache_control.merge!( max_age: seconds, public: .delete(:public), must_revalidate: .delete(:must_revalidate), stale_while_revalidate: .delete(:stale_while_revalidate), stale_if_error: .delete(:stale_if_error), ) .delete(:private) response.cache_control[:extras] = .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.
# 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 a304 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 a304 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 a304 Not Modified
response iflast_modified
<=If-Modified-Since
. :public
-
By default the
Cache-Control
header is private. Set this option totrue
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 ofCache-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" }
# 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 = strong_etag, last_modified: last_modified, public: public, template: template elsif weak_etag || template response.weak_etag = 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, settrue
to indicate that they can serve the cached response to all users.
# 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.
# 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
# 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