class Rack::Cache::Response

Provides access to the response generated by the downstream application. The response, original_response, and entry objects exposed by the Core caching engine are instances of this class.

Response objects respond to a variety of convenience methods, including those defined in Rack::Response::Helpers, Rack::Cache::Headers, and Rack::Cache::ResponseHeaders.

Note that Rack::Cache::Response is not a subclass of Rack::Response and does not perform many of the same initialization and finalization tasks. For example, the body is not slurped during initialization and there are no facilities for generating response output.

Constants

CACHEABLE_RESPONSE_CODES

Status codes of responses that MAY be stored by a cache or used in reply to a subsequent request.

tools.ietf.org/html/rfc2616#section-13.4

NOT_MODIFIED_OMIT_HEADERS

Headers that MUST NOT be included with 304 Not Modified responses.

tools.ietf.org/html/rfc2616#section-10.3.5

Attributes

body[RW]

Rack response tuple accessors.

headers[RW]

Rack response tuple accessors.

now[R]

The time when the Response object was instantiated.

status[RW]

Rack response tuple accessors.

Public Class Methods

new(status, headers, body) click to toggle source

Create a Response instance given the response status code, header hash, and body.

   # File lib/rack/cache/response.rb
40 def initialize(status, headers, body)
41   @status = status.to_i
42   @headers = Headers[headers]
43   @body = body
44   @now = Time.now
45   @headers['date'] ||= @now.httpdate
46 end

Public Instance Methods

age() click to toggle source

The age of the response.

    # File lib/rack/cache/response.rb
160 def age
161   (headers['age'] ||  [(now - date).to_i, 0].max).to_i
162 end
cache_control() click to toggle source

A Hash of name=value pairs that correspond to the cache-control header. Valueless parameters (e.g., must-revalidate, no-store) have a Hash value of true. This method always returns a Hash, empty if no cache-control header is present.

   # File lib/rack/cache/response.rb
77 def cache_control
78   @cache_control ||= CacheControl.new(headers['cache-control'])
79 end
cache_control=(value) click to toggle source

Set the cache-control header to the values specified by the Hash. See the cache_control method for information on expected Hash structure.

   # File lib/rack/cache/response.rb
83 def cache_control=(value)
84   if value.respond_to? :to_hash
85     cache_control.clear
86     cache_control.merge!(value)
87     value = cache_control.to_s
88   end
89 
90   if value.nil? || value.empty?
91     headers.delete('cache-control')
92   else
93     headers['cache-control'] = value
94   end
95 end
cacheable?() click to toggle source

Determine if the response is worth caching under any circumstance. Responses marked “private” with an explicit cache-control directive are considered uncacheable

Responses with neither a freshness lifetime (expires, max-age) nor cache validator (last-modified, etag) are considered uncacheable.

    # File lib/rack/cache/response.rb
111 def cacheable?
112   return false unless CACHEABLE_RESPONSE_CODES.include?(status)
113   return false if cache_control.no_store? || cache_control.private?
114   validateable? || fresh?
115 end
client_ttl=(seconds) click to toggle source

Set the response’s time-to-live for private/client caches. This adjusts the cache-control/max-age directive.

    # File lib/rack/cache/response.rb
217 def client_ttl=(seconds)
218   self.max_age = age + seconds
219 end
date() click to toggle source

The date, as specified by the Date header. When no Date header is present or is unparseable, set the Date header to Time.now and return.

    # File lib/rack/cache/response.rb
147 def date
148   if date = headers['date']
149     Time.httpdate(date)
150   else
151     headers['date'] = now.httpdate unless headers.frozen?
152     now
153   end
154 rescue ArgumentError
155   headers['date'] = now.httpdate unless headers.frozen?
156   now
157 end
etag() click to toggle source

The literal value of etag HTTP header or nil if no etag is specified.

    # File lib/rack/cache/response.rb
228 def etag
229   headers['etag']
230 end
expire!() click to toggle source

Mark the response stale by setting the Age header to be equal to the maximum age of the response.

    # File lib/rack/cache/response.rb
141 def expire!
142   headers['age'] = max_age.to_s if fresh?
143 end
expires() click to toggle source

The value of the expires header as a Time object.

    # File lib/rack/cache/response.rb
177 def expires
178   headers['expires'] && Time.httpdate(headers['expires'])
179 rescue ArgumentError
180   nil
181 end
fresh?() click to toggle source

Determine if the response is “fresh”. Fresh responses may be served from cache without any interaction with the origin. A response is considered fresh when it includes a cache-control/max-age indicator or Expiration header and the calculated age is less than the freshness lifetime.

    # File lib/rack/cache/response.rb
101 def fresh?
102   ttl && ttl > 0
103 end
initialize_copy(other) click to toggle source
Calls superclass method
   # File lib/rack/cache/response.rb
48 def initialize_copy(other)
49   super
50   @headers = other.headers.dup
51   @cache_control = nil
52 end
last_modified() click to toggle source

The String value of the last-modified header exactly as it appears in the response (i.e., no date parsing / conversion is performed).

    # File lib/rack/cache/response.rb
223 def last_modified
224   headers['last-modified']
225 end
max_age() click to toggle source

The number of seconds after the time specified in the response’s Date header when the the response should no longer be considered fresh. First check for a r-maxage directive, then a s-maxage directive, then a max-age directive, and then fall back on an expires header; return nil when no maximum age can be established.

    # File lib/rack/cache/response.rb
169 def max_age
170   cache_control.reverse_max_age ||
171     cache_control.shared_max_age ||
172       cache_control.max_age ||
173        (expires && (expires - date))
174 end
max_age=(value) click to toggle source

The number of seconds after which the response should no longer be considered fresh. Sets the cache-control max-age directive.

    # File lib/rack/cache/response.rb
185 def max_age=(value)
186   self.cache_control = cache_control.merge('max-age' => value.to_s)
187 end
must_revalidate?() click to toggle source

Indicates that the cache must not serve a stale response in any circumstance without first revalidating with the origin. When present, the TTL of the response should not be overriden to be greater than the value provided by the origin.

    # File lib/rack/cache/response.rb
135 def must_revalidate?
136   cache_control.must_revalidate || cache_control.proxy_revalidate
137 end
not_modified!() click to toggle source

Modify the response so that it conforms to the rules defined for ‘304 Not Modified’. This sets the status, removes the body, and discards any headers that MUST NOT be included in 304 responses.

tools.ietf.org/html/rfc2616#section-10.3.5

    # File lib/rack/cache/response.rb
250 def not_modified!
251   body.close if body.respond_to?(:close)
252   self.status = 304
253   self.body = []
254   NOT_MODIFIED_OMIT_HEADERS.each { |name| headers.delete(name) }
255   nil
256 end
private=(value) click to toggle source

Mark the response “private”, making it ineligible for serving other clients.

    # File lib/rack/cache/response.rb
125 def private=(value)
126   value = value ? true : nil
127   self.cache_control = cache_control.
128     merge('public' => !value, 'private' => value)
129 end
reverse_max_age=(value) click to toggle source

Like shared_max_age= but sets the r-maxage directive, which applies only to reverse caches.

    # File lib/rack/cache/response.rb
197 def reverse_max_age=(value)
198   self.cache_control = cache_control.merge('r-maxage' => value.to_s)
199 end
shared_max_age=(value) click to toggle source

Like max_age= but sets the s-maxage directive, which applies only to shared caches.

    # File lib/rack/cache/response.rb
191 def shared_max_age=(value)
192   self.cache_control = cache_control.merge('s-maxage' => value.to_s)
193 end
to_a() click to toggle source

Return the status, headers, and body in a three-tuple.

   # File lib/rack/cache/response.rb
55 def to_a
56   [status, headers.to_hash, body]
57 end
ttl() click to toggle source

The response’s time-to-live in seconds, or nil when no freshness information is present in the response. When the responses ttl is <= 0, the response may not be served from cache without first revalidating with the origin.

    # File lib/rack/cache/response.rb
205 def ttl
206   max_age - age if max_age
207 end
ttl=(seconds) click to toggle source

Set the response’s time-to-live for shared caches to the specified number of seconds. This adjusts the cache-control/s-maxage directive.

    # File lib/rack/cache/response.rb
211 def ttl=(seconds)
212   self.shared_max_age = age + seconds
213 end
validateable?() click to toggle source

Determine if the response includes headers that can be used to validate the response with the origin using a conditional GET request.

    # File lib/rack/cache/response.rb
119 def validateable?
120   headers.key?('last-modified') || headers.key?('etag')
121 end
vary() click to toggle source

The literal value of the vary header, or nil when no header is present.

    # File lib/rack/cache/response.rb
259 def vary
260   headers['vary']
261 end
vary?() click to toggle source

Does the response include a vary header?

    # File lib/rack/cache/response.rb
264 def vary?
265   ! vary.nil?
266 end
vary_header_names() click to toggle source

An array of header names given in the vary header or an empty array when no vary header is present.

    # File lib/rack/cache/response.rb
270 def vary_header_names
271   return [] unless vary = headers['vary']
272   vary.split(/[\s,]+/)
273 end