Implement new referrer policies

net/url_request/url_request.h

Index: net/url_request/url_request.h
diff --git a/net/url_request/url_request.h b/net/url_request/url_request.h
index e5b06ad0c0e6535794763bb1c7a6939b11681ddd..0dc5cacbdf5112e2138acf554817d6d5b18af22a 100644
--- a/net/url_request/url_request.h
+++ b/net/url_request/url_request.h
@@ -87,25 +87,30 @@ class NET_EXPORT URLRequest : public base::SupportsUserData {
   // setting the initial Referer, and the ReferrerPolicy only controls
   // what happens to the Referer while following redirects.
   enum ReferrerPolicy {
-    // Clear the referrer header if the protocol changes from HTTPS to
-    // HTTP. This is the default behavior of URLRequest.
+    // Clear the referrer header if the header value is HTTPS but the request
+    // destination is HTTP. This is the default behavior of URLRequest.
     CLEAR_REFERRER_ON_TRANSITION_FROM_SECURE_TO_INSECURE,
-    // A slight variant on
-    // CLEAR_REFERRER_ON_TRANSITION_FROM_SECURE_TO_INSECURE: If the
-    // request downgrades from HTTPS to HTTP, the referrer will be
-    // cleared. If the request transitions cross-origin (but does not
-    // downgrade), the referrer's granularity will be reduced (currently
-    // stripped down to an origin rather than a full URL). Same-origin
-    // requests will send the full referrer.
+    // A slight variant on CLEAR_REFERRER_ON_TRANSITION_FROM_SECURE_TO_INSECURE:
+    // If the request destination is HTTP, an HTTPS referrer will be cleared. If
+    // the request's destination is cross-origin with the referrer (but does not
+    // downgrade), the referrer's granularity will be stripped down to an origin
+    // rather than a full URL. Same-origin requests will send the full referrer.
     REDUCE_REFERRER_GRANULARITY_ON_TRANSITION_CROSS_ORIGIN,
-    // Strip the referrer down to an origin upon cross-origin navigation.
+    // Strip the referrer down to an origin when the origin of the referrer is
+    // different from the destination's origin.
     ORIGIN_ONLY_ON_TRANSITION_CROSS_ORIGIN,
     // Never change the referrer.
     NEVER_CLEAR_REFERRER,
     // Strip the referrer down to the origin regardless of the redirect
     // location.
     ORIGIN,
-    // Always clear the referrer regardless of the redirect location.
+    // Clear the referrer when the request's referrer is cross-origin with
+    // the request's destination.
+    CLEAR_REFERRER_ON_TRANSITION_CROSS_ORIGIN,
+    // Strip the referrer down to the origin, but clear it entirely if the
+    // referrer value is HTTPS and the destination is HTTP.
+    ORIGIN_CLEAR_ON_TRANSITION_FROM_SECURE_TO_INSECURE,
+    // Always clear the referrer regardless of the request destination.
     NO_REFERRER,
     MAX_REFERRER_POLICY
   };
@@ -314,16 +319,22 @@ class NET_EXPORT URLRequest : public base::SupportsUserData {
   const std::string& method() const { return method_; }
   void set_method(const std::string& method);
 
-  // The referrer URL for the request.  This header may actually be suppressed
-  // from the underlying network request for security reasons (e.g., a HTTPS
-  // URL will not be sent as the referrer for a HTTP request).  The referrer
-  // may only be changed before Start() is called.
+  // The referrer URL for the request
   const std::string& referrer() const { return referrer_; }
-  // Referrer is sanitized to remove URL fragment, user name and password.
+  // Sets the referrer URL for the request. Can only be changed before Start()
+  // is called. |referrer| is sanitized to remove URL fragment, user name and
+  // password. If a referrer policy is set via set_referrer_policy(), then
+  // |referrer| should obey the policy; if it doesn't, it will be cleared when
+  // the request is started. The referrer URL may be suppressed or changed
+  // during the course of the request, for example because of a referrer policy
+  // set with set_referrer_policy().
   void SetReferrer(const std::string& referrer);
 
   // The referrer policy to apply when updating the referrer during redirects.
-  // The referrer policy may only be changed before Start() is called.
+  // The referrer policy may only be changed before Start() is called. Any
+  // referrer set via SetReferrer() is expected to obey the policy set via
+  // set_referrer_policy(); otherwise the referrer will be cleared when the
+  // request is started.
   ReferrerPolicy referrer_policy() const { return referrer_policy_; }
   void set_referrer_policy(ReferrerPolicy referrer_policy);