stale-while-revalidate experimental implementation.

net/http/http_response_headers.h

 // 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.
 
 #ifndef NET_HTTP_HTTP_RESPONSE_HEADERS_H_
 #define NET_HTTP_HTTP_RESPONSE_HEADERS_H_
 
 #include <string>
 #include <vector>
 
@@ skipping 10 matching lines @@
 
 namespace base {
 class Time;
 class TimeDelta;
 }
 
 namespace net {
 
 class HttpByteRange;
 
+enum ValidationType {
+  VALIDATION_NONE = 0,      // The resource is fresh.

[mmenke, 2014/10/09 14:29:58]

Does this "= 0" give us anything?

[Adam Rice, 2014/10/20 09:31:24]

No. But all the cool kids are doing it.

Removed in https://crrev.com/665023002/

+  VALIDATION_ASYNCHRONOUS,  // The resource requires async revalidation.
+  VALIDATION_SYNCHRONOUS    // The resource requires sync revalidation.
+};
+
 // HttpResponseHeaders: parses and holds HTTP response headers.
 class NET_EXPORT HttpResponseHeaders
     : public base::RefCountedThreadSafe<HttpResponseHeaders> {
  public:
   // Persist options.
   typedef int PersistOptions;
   static const PersistOptions PERSIST_RAW = -1;  // Raw, unparsed headers.
   static const PersistOptions PERSIST_ALL = 0;  // Parsed headers.
   static const PersistOptions PERSIST_SANS_COOKIES = 1 << 0;
   static const PersistOptions PERSIST_SANS_CHALLENGES = 1 << 1;
   static const PersistOptions PERSIST_SANS_HOP_BY_HOP = 1 << 2;
   static const PersistOptions PERSIST_SANS_NON_CACHEABLE = 1 << 3;
   static const PersistOptions PERSIST_SANS_RANGES = 1 << 4;
   static const PersistOptions PERSIST_SANS_SECURITY_STATE = 1 << 5;
 
+  struct FreshnessLifetimes {
+    // How long the resource will be fresh for.
+    base::TimeDelta fresh;
+    // How long after becoming not fresh that the resource will be stale but
+    // usable (if async revalidation is enabled).
+    base::TimeDelta stale;

[mmenke, 2014/10/09 14:29:58]

I think these names are very confusing - it doesn't imply they're deltas. 
"fresh" sounds like a bool to me "FreshnessLifetime" sounds like either an
expiration time, or total duration, neither of which is correct, so doesn't
really help.

Also, "fresh" and "stale" seem a bit confusing - generally something is
considered fresh until it's stale.

Maybe rename these:
fresh -> fresh_time_remaining
stale -> usable_time_remaining (Or stale_while_revalidate_time_remaining - a bit
of a mouthful, but clearer)

Or maybe time_until_stale / time_until_unusable?  I'm open to other ideas.

[rvargas (doing something else), 2014/10/09 19:13:45]

FreshnessLifetime is the standard term for time delta until the resource becomes
stale: http://tools.ietf.org/html/rfc7234#section-4.2.1 so it should provide
enough context for the meaning of the members (maybe add a link to the rfc?).
The idea is that now we compute two lifetimes instead of one.

maybe fresh_delta or freshness_delta? I don't want to deviate too much from the
standard name.

The second part is more complicated because from the point of view of the
standard there are multiple conditions that allow use of stale data even without
considering SWR.

maybe stale_while_revalidate_delta?

I'm not very fond of adding part of the type name to the name of variables
though.

[mmenke, 2014/10/09 19:32:01]

Thanks for the link!  I guess this function only makes sense for for recently
received headers, and not those read from the cache, which means the time from
now until expiration is the same as freshness lifetime?

"Fresh" really does sounds like a bool to me - either something is fresh, or it
isn't, which initially confused me.  Since it's a defined term, as you point
out, maybe just freshness_lifetime?
Understandable - given my misunderstanding about when this method is used, I'm
fine with using something that just implies "not a bool", rather than
specifically "time delta".  stale_while_revalidate_until?

Anyhow, I'm not really too picky.

[rvargas (doing something else), 2014/10/09 21:29:32]

GetFreshnessLifetimes() is used by RequiresValidation() to calculate validation
requirements for cached content.
That works for me.
"until" suggests to me an absolute value (base::Time) :(

Maybe stale_while_revalidate_lifetime? stale_while_revalidate_value?

[rvargas (doing something else), 2014/10/09 21:47:14]

BTW, another thing to consider is how the code reads when it is used.

Today this means
  lifetime.fresh.InSeconds(),
  lifetime.stale.InSeconds(),

and
  TimeDelta freshness_lifetime =
     foo->GetFreshnessLifetimes(blah).fresh;

crazy idea: 
  lifetime.freshness.InSeconds(),
  lifetime.staleness.InSeconds(),

on the upside (and downside), I don't think "staleness" means anything :p

[mmenke, 2014/10/09 21:50:28]

I was looking at it in chrome_network_delegate.cc..By the time I'd gotten to the
end of that line, I'd forgotten about what the start looked like.

[Adam Rice, 2014/10/20 09:31:24]

I have implemented the freshness/staleness approach in
https://crrev.com/665023002/

Just to complicate things, I thought of another possible naming strategy:

UsableLifetime usable_lifetime = headers.GetUsableLifetime(...);
usable_lifetime.as_fresh.InSeconds(),
usable_lifetime.as_stale.InSeconds()

+  };
+
   static const char kContentRange[];
 
   // Parses the given raw_headers.  raw_headers should be formatted thus:
   // includes the http status response line, each line is \0-terminated, and
   // it's terminated by an empty line (ie, 2 \0s in a row).
   // (Note that line continuations should have already been joined;
   // see HttpUtil::AssembleRawHeaders)
   //
   // HttpResponseHeaders does not perform any encoding changes on the input.
   //
@@ skipping 138 matching lines @@
   bool GetCharset(std::string* charset) const;
 
   // Returns true if this response corresponds to a redirect.  The target
   // location of the redirect is optionally returned if location is non-null.
   bool IsRedirect(std::string* location) const;
 
   // Returns true if the HTTP response code passed in corresponds to a
   // redirect.
   static bool IsRedirectResponseCode(int response_code);
 
-  // Returns true if the response cannot be reused without validation.  The
-  // result is relative to the current_time parameter, which is a parameter to
-  // support unit testing.  The request_time parameter indicates the time at
-  // which the request was made that resulted in this response, which was
-  // received at response_time.
-  bool RequiresValidation(const base::Time& request_time,
-                          const base::Time& response_time,
-                          const base::Time& current_time) const;
+  // Returns VALIDATION_NONE if the response can be reused without
+  // validation. VALIDATION_ASYNCHRONOUS means the response can be re-used, but
+  // asynchronous revalidation must be performed. VALIDATION_SYNCHRONOUS means
+  // that the result cannot be reused without revalidation.
+  // The result is relative to the current_time parameter, which is
+  // a parameter to support unit testing.  The request_time parameter indicates
+  // the time at which the request was made that resulted in this response,
+  // which was received at response_time.
+  ValidationType RequiresValidation(const base::Time& request_time,
+                                    const base::Time& response_time,
+                                    const base::Time& current_time) const;
 
-  // Returns the amount of time the server claims the response is fresh from
+  // Calculates the amount of time the server claims the response is fresh from
   // the time the response was generated.  See section 13.2.4 of RFC 2616.  See
-  // RequiresValidation for a description of the response_time parameter.
-  base::TimeDelta GetFreshnessLifetime(const base::Time& response_time) const;
+  // RequiresValidation for a description of the response_time parameter.  Sets
+  // |FreshnessLifetimes.fresh| to the length of time the response may be used
+  // without revalidation, and |FreshnessLifetimes.stale| to the length of time

[mmenke, 2014/10/09 14:29:58]

nit:  Only use || around argument names.  I documenting FreshnessLifetime's
fields again here isn't needed, since it's redundant with the struct - suspect
the documentation here is much more likely to become outdated if things ever
change.  Fine to mention RFC5861, and the usable while stale behavior.

[Adam Rice, 2014/10/20 09:31:24]

Done.

+  // the response may be used stale with asynchronous revalidation if
+  // stale-while-revalidate support is enabled.  See RFC 5861 section 3 for the
+  // definition of stale-while-revalidate.
+  FreshnessLifetimes GetFreshnessLifetimes(
+      const base::Time& response_time) const;
 
   // Returns the age of the response.  See section 13.2.3 of RFC 2616.
   // See RequiresValidation for a description of this method's parameters.
   base::TimeDelta GetCurrentAge(const base::Time& request_time,
                                 const base::Time& response_time,
                                 const base::Time& current_time) const;
 
   // The following methods extract values from the response headers.  If a
   // value is not present, then false is returned.  Otherwise, true is returned
   // and the out param is assigned to the corresponding value.
@@ skipping 161 matching lines @@
 
   // The parsed http version number (not normalized).
   HttpVersion parsed_http_version_;
 
   DISALLOW_COPY_AND_ASSIGN(HttpResponseHeaders);
 };
 
 }  // namespace net
 
 #endif  // NET_HTTP_HTTP_RESPONSE_HEADERS_H_