stale-while-revalidate experimental implementation.

net/http/http_response_headers.h

Index: net/http/http_response_headers.h
diff --git a/net/http/http_response_headers.h b/net/http/http_response_headers.h
index ddab798c0a2c0795556d1b2da0a583574c581553..ac7c351bd519117d414cfb19c8a85383c07b213c 100644
--- a/net/http/http_response_headers.h
+++ b/net/http/http_response_headers.h
@@ -28,6 +28,12 @@ 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> {
@@ -43,6 +49,14 @@ class NET_EXPORT HttpResponseHeaders
   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:
@@ -201,19 +215,28 @@ class NET_EXPORT HttpResponseHeaders
   // 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 the amount of time the server claims the response is fresh from
+  // 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;
+
+  // 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.