Add GetExpirationTimes() to HttpResponseHeader.

net/http/http_response_headers.cc

 // Copyright (c) 2012 The Chromium Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
 // The rules for header parsing were borrowed from Firefox:
 // http://lxr.mozilla.org/seamonkey/source/netwerk/protocol/http/src/nsHttpResponseHead.cpp
 // The rules for parsing content-types were also borrowed from Firefox:
 // http://lxr.mozilla.org/mozilla/source/netwerk/base/src/nsURLHelper.cpp#834
 
 #include "net/http/http_response_headers.h"
@@ skipping 759 matching lines @@
           StringPiece(value.begin() + directive_size + 1, value.end()),
           &seconds);
       *result = TimeDelta::FromSeconds(seconds);
       return true;
     }
   }
 
   return false;
 }
 
+// From RFC 2616 section 13.2.4:
+//
+// The max-age directive takes priority over Expires, so if max-age is present
+// in a response, the calculation is simply:
+//
+//   freshness_lifetime = max_age_value
+//
+// Otherwise, if Expires is present in the response, the calculation is:
+//
+//   freshness_lifetime = expires_value - date_value
+//
+// Note that neither of these calculations is vulnerable to clock skew, since
+// all of the information comes from the origin server.
+//
+// Also, if the response does have a Last-Modified time, the heuristic
+// expiration value SHOULD be no more than some fraction of the interval since
+// that time. A typical setting of this fraction might be 10%:
+//
+//   freshness_lifetime = (date_value - last_modified_value) * 0.10
+//
+// If the stale-while-revalidate directive is present, then it is used to set
+// the |staleness| time, unless it overridden by another directive.
+//
+void HttpResponseHeaders::CalculateLifetimes(

[mmenke, 2016/04/29 16:15:53]

Definition order should match delcaration order.  Or could just moving this up
to an anonymous namespace, since it doesn't depend on private variables or
methods.

+    const Time& response_time,

[mmenke, 2016/04/29 16:15:53]

nit:  Believe the preferred style is not to pass times (And TimeDeltas) by
reference.  Passing 64 bits is probably more efficient than a 32-bit pointer, on
32-bit systems.

+    TimeDelta* out_freshness_lifetime,
+    TimeDelta* out_staleness_lifetime) const {
+  *out_freshness_lifetime = TimeDelta();
+  *out_staleness_lifetime = TimeDelta();
+
+  // Check for headers that force a response to never be fresh.  For backwards
+  // compat, we treat "Pragma: no-cache" as a synonym for "Cache-Control:
+  // no-cache" even though RFC 2616 does not specify it.
+  if (HasHeaderValue("cache-control", "no-cache") ||
+      HasHeaderValue("cache-control", "no-store") ||
+      HasHeaderValue("pragma", "no-cache") ||
+      // Vary: * is never usable: see RFC 2616 section 13.6.
+      HasHeaderValue("vary", "*")) {
+    return;
+  }
+
+  // Cache-Control directive must_revalidate overrides stale-while-revalidate.

[mmenke, 2016/04/29 16:15:53]

nit:  must-revalidate

+  bool must_revalidate = HasHeaderValue("cache-control", "must-revalidate");
+
+  if (must_revalidate ||
+      !GetStaleWhileRevalidateValue(out_staleness_lifetime)) {
+    DCHECK_EQ(TimeDelta(), *out_staleness_lifetime);

[mmenke, 2016/04/29 16:15:53]

This DCHECK seems out of place - we aren't DCHECKing out_freshness_lifetime is 0
when GetMaxAgeValue returns false, for instance.

+  }
+
+  // NOTE: "Cache-Control: max-age" overrides Expires, so we only check the
+  // Expires header after checking for max-age in GetFreshnessLifetimes.  This

[Randy Smith (Not in Mondays), 2016/05/04 19:22:15]

This comment seems out of date, since I don't think there's a function of this
name in this file anymore.

+  // is important since "Expires: <date in the past>" means not fresh, but
+  // it should not trump a max-age value.
+  if (GetMaxAgeValue(out_freshness_lifetime))
+    return;
+
+  // If there is no Date header, then assume that the server response was
+  // generated at the time when we received the response.
+  Time date_value;
+  if (!GetDateValue(&date_value))
+    date_value = response_time;
+
+  Time expires_value;
+  if (GetExpiresValue(&expires_value)) {
+    // The expires value can be a date in the past!

[Randy Smith (Not in Mondays), 2016/05/04 19:22:15]

nit, suggestion: I'd value a comment here indicating what the spec behavior is
when the expires value is a date in the past.  It looks like it's ignored in
that case, but that's surprising to me, so I'd ideally have it confirmed by
comment.

+    if (expires_value > date_value) {
+      *out_freshness_lifetime = expires_value - date_value;
+      return;
+    }
+
+    DCHECK_EQ(TimeDelta(), *out_freshness_lifetime);

[mmenke, 2016/04/29 16:15:53]

Should this be under GetDateValue?  How many DCHECKs do we need that methods
don't set their arguments when they return false?  Seems like we should DCHECK
all or none.

+    return;
+  }
+
+  // From RFC 2616 section 13.4:
+  //
+  //   A response received with a status code of 200, 203, 206, 300, 301 or 410
+  //   MAY be stored by a cache and used in reply to a subsequent request,
+  //   subject to the expiration mechanism, unless a cache-control directive
+  //   prohibits caching.
+  //   ...
+  //   A response received with any other status code (e.g. status codes 302
+  //   and 307) MUST NOT be returned in a reply to a subsequent request unless
+  //   there are cache-control directives or another header(s) that explicitly
+  //   allow it.
+  //
+  // From RFC 2616 section 14.9.4:
+  //
+  //   When the must-revalidate directive is present in a response received by
+  //   a cache, that cache MUST NOT use the entry after it becomes stale to
+  //   respond to a subsequent request without first revalidating it with the
+  //   origin server. (I.e., the cache MUST do an end-to-end revalidation every
+  //   time, if, based solely on the origin server's Expires or max-age value,
+  //   the cached response is stale.)
+  //
+  // https://datatracker.ietf.org/doc/draft-reschke-http-status-308/ is an
+  // experimental RFC that adds 308 permanent redirect as well, for which "any
+  // future references ... SHOULD use one of the returned URIs."
+  if ((response_code_ == 200 || response_code_ == 203 ||
+       response_code_ == 206) && !must_revalidate) {
+    // TODO(darin): Implement a smarter heuristic.
+    Time last_modified_value;
+    if (GetLastModifiedValue(&last_modified_value)) {
+      // The last-modified value can be a date in the future!
+      if (last_modified_value <= date_value) {
+        *out_freshness_lifetime = (date_value - last_modified_value) / 10;

[mmenke, 2016/04/29 16:15:53]

This "/ 10" is just a magic heuristic?  Maybe comment on that?

[Randy Smith (Not in Mondays), 2016/05/04 19:22:15]

There's a comment about it at the top of the function; maybe a reference to that
comment?

+        return;
+      }
+    }
+  }
+
+  // These responses are implicitly fresh (unless otherwise overruled):

[mmenke, 2016/04/29 16:15:53]

"Otherwise overruled" does not include having the "must_revalidate" header?

+  if (response_code_ == 300 || response_code_ == 301 || response_code_ == 308 ||
+      response_code_ == 410) {
+    *out_freshness_lifetime = TimeDelta::Max();
+    *out_staleness_lifetime = TimeDelta();  // It should never be stale.

[mmenke, 2016/04/29 16:15:53]

In the calling function, should we just always set out_staleness_lifetime to 0,
whenever it's less than freshness lifetime?

+    return;
+  }
+
+  // Our heuristic freshness estimate for this resource is 0 seconds, in
+  // accordance with common browser behaviour. However, stale-while-revalidate
+  // may still apply.
+  DCHECK_EQ(TimeDelta(), *out_freshness_lifetime);
+  return;
+}
+
 void HttpResponseHeaders::AddHeader(std::string::const_iterator name_begin,
                                     std::string::const_iterator name_end,
                                     std::string::const_iterator values_begin,
                                     std::string::const_iterator values_end) {
   // If the header can be coalesced, then we should split it up.
   if (values_begin == values_end ||
       HttpUtil::IsNonCoalescingHeader(name_begin, name_end)) {
     AddToParsed(name_begin, name_end, values_begin, values_end);
   } else {
     HttpUtil::ValuesIterator it(values_begin, values_end, ',');
@@ skipping 147 matching lines @@
 bool HttpResponseHeaders::IsRedirectResponseCode(int response_code) {
   // Users probably want to see 300 (multiple choice) pages, so we don't count
   // them as redirects that need to be followed.
   return (response_code == 301 ||
           response_code == 302 ||
           response_code == 303 ||
           response_code == 307 ||
           response_code == 308);
 }
 
-// From RFC 2616 section 13.2.4:
+// We calculate and return |corrected_response_time|, defined by:
 //
-// The calculation to determine if a response has expired is quite simple:
+//   current_age = now - corrected_response_time
 //
-//   response_is_fresh = (freshness_lifetime > current_age)
+// So a caller can store an ExpirationTimes object and use it to determine
+// freshness throughout the objects lifetime.
 //
 // Of course, there are other factors that can force a response to always be
 // validated or re-fetched.
-//
-// From RFC 5861 section 3, a stale response may be used while revalidation is
-// performed in the background if
-//
-//   freshness_lifetime + stale_while_revalidate > current_age
-//
-ValidationType HttpResponseHeaders::RequiresValidation(
+HttpResponseHeaders::ExpirationTimes HttpResponseHeaders::GetExpirationTimes(
     const Time& request_time,
-    const Time& response_time,
-    const Time& current_time) const {
-  FreshnessLifetimes lifetimes = GetFreshnessLifetimes(response_time);
-  if (lifetimes.freshness.is_zero() && lifetimes.staleness.is_zero())
-    return VALIDATION_SYNCHRONOUS;
-
-  TimeDelta age = GetCurrentAge(request_time, response_time, current_time);
-
-  if (lifetimes.freshness > age)
-    return VALIDATION_NONE;
-
-  if (lifetimes.freshness + lifetimes.staleness > age)
-    return VALIDATION_ASYNCHRONOUS;
-
-  return VALIDATION_SYNCHRONOUS;
-}
-
-// From RFC 2616 section 13.2.4:
-//
-// The max-age directive takes priority over Expires, so if max-age is present
-// in a response, the calculation is simply:
-//
-//   freshness_lifetime = max_age_value
-//
-// Otherwise, if Expires is present in the response, the calculation is:
-//
-//   freshness_lifetime = expires_value - date_value
-//
-// Note that neither of these calculations is vulnerable to clock skew, since
-// all of the information comes from the origin server.
-//
-// Also, if the response does have a Last-Modified time, the heuristic
-// expiration value SHOULD be no more than some fraction of the interval since
-// that time. A typical setting of this fraction might be 10%:
-//
-//   freshness_lifetime = (date_value - last_modified_value) * 0.10
-//
-// If the stale-while-revalidate directive is present, then it is used to set
-// the |staleness| time, unless it overridden by another directive.
-//
-HttpResponseHeaders::FreshnessLifetimes
-HttpResponseHeaders::GetFreshnessLifetimes(const Time& response_time) const {
-  FreshnessLifetimes lifetimes;
-  // Check for headers that force a response to never be fresh.  For backwards
-  // compat, we treat "Pragma: no-cache" as a synonym for "Cache-Control:
-  // no-cache" even though RFC 2616 does not specify it.
-  if (HasHeaderValue("cache-control", "no-cache") ||
-      HasHeaderValue("cache-control", "no-store") ||
-      HasHeaderValue("pragma", "no-cache") ||
-      // Vary: * is never usable: see RFC 2616 section 13.6.
-      HasHeaderValue("vary", "*")) {
-    return lifetimes;
-  }
-
-  // Cache-Control directive must_revalidate overrides stale-while-revalidate.
-  bool must_revalidate = HasHeaderValue("cache-control", "must-revalidate");
-
-  if (must_revalidate || !GetStaleWhileRevalidateValue(&lifetimes.staleness)) {
-    DCHECK_EQ(TimeDelta(), lifetimes.staleness);
-  }
-
-  // NOTE: "Cache-Control: max-age" overrides Expires, so we only check the
-  // Expires header after checking for max-age in GetFreshnessLifetimes.  This
-  // is important since "Expires: <date in the past>" means not fresh, but
-  // it should not trump a max-age value.
-  if (GetMaxAgeValue(&lifetimes.freshness))
-    return lifetimes;
+    const Time& response_time) const {
+  // From RFC 2616 section 13.2.3:
+  //
+  // Summary of age calculation algorithm, when a cache receives a response:
+  //
+  //   /*
+  //    * age_value
+  //    *      is the value of Age: header received by the cache with
+  //    *              this response.
+  //    * date_value
+  //    *      is the value of the origin server's Date: header
+  //    * request_time
+  //    *      is the (local) time when the cache made the request
+  //    *              that resulted in this cached response
+  //    * response_time
+  //    *      is the (local) time when the cache received the
+  //    *              response
+  //    * now
+  //    *      is the current (local) time
+  //    */
+  //   apparent_age = max(0, response_time - date_value);
+  //   corrected_received_age = max(apparent_age, age_value);
+  //   response_delay = response_time - request_time;
+  //   corrected_initial_age = corrected_received_age + response_delay;
+  //   resident_time = now - response_time;
+  //   current_age   = corrected_initial_age + resident_time;
 
   // If there is no Date header, then assume that the server response was
   // generated at the time when we received the response.
   Time date_value;
-  if (!GetDateValue(&date_value))
-    date_value = response_time;
-
-  Time expires_value;
-  if (GetExpiresValue(&expires_value)) {
-    // The expires value can be a date in the past!
-    if (expires_value > date_value) {
-      lifetimes.freshness = expires_value - date_value;
-      return lifetimes;
-    }
-
-    DCHECK_EQ(TimeDelta(), lifetimes.freshness);
-    return lifetimes;
-  }
-
-  // From RFC 2616 section 13.4:
-  //
-  //   A response received with a status code of 200, 203, 206, 300, 301 or 410
-  //   MAY be stored by a cache and used in reply to a subsequent request,
-  //   subject to the expiration mechanism, unless a cache-control directive
-  //   prohibits caching.
-  //   ...
-  //   A response received with any other status code (e.g. status codes 302
-  //   and 307) MUST NOT be returned in a reply to a subsequent request unless
-  //   there are cache-control directives or another header(s) that explicitly
-  //   allow it.
-  //
-  // From RFC 2616 section 14.9.4:
-  //
-  //   When the must-revalidate directive is present in a response received by
-  //   a cache, that cache MUST NOT use the entry after it becomes stale to
-  //   respond to a subsequent request without first revalidating it with the
-  //   origin server. (I.e., the cache MUST do an end-to-end revalidation every
-  //   time, if, based solely on the origin server's Expires or max-age value,
-  //   the cached response is stale.)
-  //
-  // https://datatracker.ietf.org/doc/draft-reschke-http-status-308/ is an
-  // experimental RFC that adds 308 permanent redirect as well, for which "any
-  // future references ... SHOULD use one of the returned URIs."
-  if ((response_code_ == 200 || response_code_ == 203 ||
-       response_code_ == 206) && !must_revalidate) {
-    // TODO(darin): Implement a smarter heuristic.
-    Time last_modified_value;
-    if (GetLastModifiedValue(&last_modified_value)) {
-      // The last-modified value can be a date in the future!
-      if (last_modified_value <= date_value) {
-        lifetimes.freshness = (date_value - last_modified_value) / 10;
-        return lifetimes;
-      }
-    }
-  }
-
-  // These responses are implicitly fresh (unless otherwise overruled):
-  if (response_code_ == 300 || response_code_ == 301 || response_code_ == 308 ||
-      response_code_ == 410) {
-    lifetimes.freshness = TimeDelta::Max();
-    lifetimes.staleness = TimeDelta();  // It should never be stale.
-    return lifetimes;
-  }
-
-  // Our heuristic freshness estimate for this resource is 0 seconds, in
-  // accordance with common browser behaviour. However, stale-while-revalidate
-  // may still apply.
-  DCHECK_EQ(TimeDelta(), lifetimes.freshness);
-  return lifetimes;
-}
-
-// From RFC 2616 section 13.2.3:
-//
-// Summary of age calculation algorithm, when a cache receives a response:
-//
-//   /*
-//    * age_value
-//    *      is the value of Age: header received by the cache with
-//    *              this response.
-//    * date_value
-//    *      is the value of the origin server's Date: header
-//    * request_time
-//    *      is the (local) time when the cache made the request
-//    *              that resulted in this cached response
-//    * response_time
-//    *      is the (local) time when the cache received the
-//    *              response
-//    * now
-//    *      is the current (local) time
-//    */
-//   apparent_age = max(0, response_time - date_value);
-//   corrected_received_age = max(apparent_age, age_value);
-//   response_delay = response_time - request_time;
-//   corrected_initial_age = corrected_received_age + response_delay;
-//   resident_time = now - response_time;
-//   current_age   = corrected_initial_age + resident_time;
-//
-TimeDelta HttpResponseHeaders::GetCurrentAge(const Time& request_time,
-                                             const Time& response_time,
-                                             const Time& current_time) const {
-  // If there is no Date header, then assume that the server response was
-  // generated at the time when we received the response.
-  Time date_value;
   if (!GetDateValue(&date_value))
     date_value = response_time;
 
   // If there is no Age header, then assume age is zero.  GetAgeValue does not
   // modify its out param if the value does not exist.
   TimeDelta age_value;
   GetAgeValue(&age_value);
 
   TimeDelta apparent_age = std::max(TimeDelta(), response_time - date_value);
   TimeDelta corrected_received_age = std::max(apparent_age, age_value);
   TimeDelta response_delay = response_time - request_time;
   TimeDelta corrected_initial_age = corrected_received_age + response_delay;
-  TimeDelta resident_time = current_time - response_time;
-  TimeDelta current_age = corrected_initial_age + resident_time;
 
-  return current_age;
+  // From the age calculation algorithm above, we can derive the corrected
+  // response time, the |now| for which |current_age == 0|. Substituting into
+  // the RFC 2616 13.2.3 equations above, and simplyfing:
+  //
+  //    corrected_initial_age + resident_time == 0
+  //    corrected_initial_age + corrected_response_time - response_time == 0
+  //    corrected_response_time == response_time - corrected_initial_age
+
+  ExpirationTimes expirations;
+  expirations.corrected_response_time = response_time - corrected_initial_age;
+  CalculateLifetimes(response_time, &expirations.freshness_lifetime,
+                     &expirations.staleness_lifetime);
+  return expirations;
 }
 
 bool HttpResponseHeaders::GetMaxAgeValue(TimeDelta* result) const {
   return GetCacheControlDirective("max-age", result);
 }
 
 bool HttpResponseHeaders::GetAgeValue(TimeDelta* result) const {
   std::string value;
   if (!EnumerateHeader(nullptr, "Age", &value))
     return false;
@@ skipping 306 matching lines @@
   return true;
 }
 
 bool HttpResponseHeaders::IsChunkEncoded() const {
   // Ignore spurious chunked responses from HTTP/1.0 servers and proxies.
   return GetHttpVersion() >= HttpVersion(1, 1) &&
       HasHeaderValue("Transfer-Encoding", "chunked");
 }
 
 }  // namespace net