Generalize the usage of referrer chain

chrome/browser/safe_browsing/safe_browsing_navigation_observer_manager.h

 // Copyright 2016 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 CHROME_BROWSER_SAFE_BROWSING_SAFE_BROWSING_NAVIGATION_OBSERVER_MANAGER_H_
 #define CHROME_BROWSER_SAFE_BROWSING_SAFE_BROWSING_NAVIGATION_OBSERVER_MANAGER_H_
 
 #include <deque>
 #include "base/feature_list.h"
 #include "base/supports_user_data.h"
@@ skipping 25 matching lines @@
 };
 
 // Struct that manages insertion, cleanup, and lookup of NavigationEvent
 // objects. Its maximum size is kNavigationRecordMaxSize.
 struct NavigationEventList {
  public:
   explicit NavigationEventList(std::size_t size_limit);
 
   ~NavigationEventList();
 
-  // Find the most recent navigation event that navigated to |target_url| and
+  // Finds the most recent navigation event that navigated to |target_url| and
   // its associated |target_main_frame_url| in the tab with ID |target_tab_id|.
-  // If navigation happened in the main frame, |target_url| and |target_main_
-  // frame_url| are the same.
+  // If navigation happened in the main frame, |target_url| and
+  // |target_main_frame_url| are the same.
   // If |target_url| is empty, we use its main frame url (a.k.a.
   // |target_main_frame_url|) to search for navigation events.
   // If |target_tab_id| is not available (-1), we look for all tabs for the most
   // recent navigation to |target_url| or |target_main_frame_url|.
   // For some cases, the most recent navigation to |target_url| may not be
   // relevant.
   // For example, url1 in window A opens url2 in window B, url1 then opens an
   // about:blank page window C and injects script code in it to trigger a
-  // delayed download in Window D. Before the download occurs, url2 in window B
-  // opens a different about:blank page in window C.
+  // delayed event (e.g. a download) in Window D. Before the event occurs, url2
+  // in window B opens a different about:blank page in window C.
   // A ---- C - D
   //   \   /
   //     B
   // In this case, FindNavigationEvent() will think url2 in Window B is the
   // referrer of about::blank in Window C since this navigation is more recent.
   // However, it does not prevent us to attribute url1 in Window A as the cause
   // of all these navigations.
   NavigationEvent* FindNavigationEvent(const GURL& target_url,
                                        const GURL& target_main_frame_url,
                                        int target_tab_id);
 
-  // Find the most recent retargeting NavigationEvent that satisfies
+  // Finds the most recent retargeting NavigationEvent that satisfies
   // |target_url|, and |target_tab_id|.
   NavigationEvent* FindRetargetingNavigationEvent(const GURL& target_url,
                                                   int target_tab_id);
 
   void RecordNavigationEvent(std::unique_ptr<NavigationEvent> nav_event);
 
-  // Remove stale NavigationEvents and return the number of items removed.
+  // Removes stale NavigationEvents and return the number of items removed.
   std::size_t CleanUpNavigationEvents();
 
   std::size_t Size() { return navigation_events_.size(); }
 
   NavigationEvent* Get(std::size_t index) {
     return navigation_events_[index].get();
   }
 
  private:
   std::deque<std::unique_ptr<NavigationEvent>> navigation_events_;
   const std::size_t size_limit_;
 };
 
 // Manager class for SafeBrowsingNavigationObserver, which is in charge of
 // cleaning up stale navigation events, and identifying landing page/landing
-// referrer for a specific download.
+// referrer for a specific Safe Browsing event.
 class SafeBrowsingNavigationObserverManager
     : public base::RefCountedThreadSafe<SafeBrowsingNavigationObserverManager> {
  public:
   static const base::Feature kDownloadAttribution;
 
   // For UMA histogram counting. Do NOT change order.
   enum AttributionResult {
     SUCCESS = 1,                   // Identified referrer chain is not empty.
     SUCCESS_LANDING_PAGE = 2,      // Successfully identified landing page.
     SUCCESS_LANDING_REFERRER = 3,  // Successfully identified landing referrer.
     INVALID_URL = 4,
     NAVIGATION_EVENT_NOT_FOUND = 5,
 
     // Always at the end.
     ATTRIBUTION_FAILURE_TYPE_MAX
   };
 
   // Helper function to check if user gesture is older than
   // kUserGestureTTLInSecond.
   static bool IsUserGestureExpired(const base::Time& timestamp);
 
   // Helper function to strip empty ref fragment from a URL. Many pages
   // end up with a "#" at the end of their URLs due to navigation triggered by
   // href="#" and javascript onclick function. We don't want to have separate
   // entries for these cases in the maps.
   static GURL ClearEmptyRef(const GURL& url);
 
   // Checks if we should enable observing navigations for safe browsing purpose.
-  // Return true if the safe browsing service and the download attribution
+  // Return true if the safe browsing service and the |kDownloadAttribution|
   // feature are both enabled, and safe browsing service is initialized.
   static bool IsEnabledAndReady(Profile* profile);
 
   SafeBrowsingNavigationObserverManager();
 
-  // Add |nav_event| to |navigation_event_list_|. Object pointed to by
+  // Adds |nav_event| to |navigation_event_list_|. Object pointed to by
   // |nav_event| will be no longer accessible after this function.
   void RecordNavigationEvent(std::unique_ptr<NavigationEvent> nav_event);
   void RecordUserGestureForWebContents(content::WebContents* web_contents,
                                        const base::Time& timestamp);
   void OnUserGestureConsumed(content::WebContents* web_contents,
                              const base::Time& timestamp);
   bool HasUserGesture(content::WebContents* web_contents);
   void RecordHostToIpMapping(const std::string& host, const std::string& ip);
 
   // Clean-ups need to be done when a WebContents gets destroyed.
   void OnWebContentDestroyed(content::WebContents* web_contents);
 
-  // Remove all the observed NavigationEvents, user gestures, and resolved IP
+  // Removes all the observed NavigationEvents, user gestures, and resolved IP
   // addresses that are older than kNavigationFootprintTTLInSecond.
   void CleanUpStaleNavigationFootprints();
 
-  // Based on the |target_url| and |target_tab_id|, trace back the observed
+  // Based on the |target_url| and |target_tab_id|, traces back the observed
   // NavigationEvents in navigation_event_list_ to identify the sequence of
   // navigations leading to the target, with the coverage limited to
-  // |user_gesture_count_limit| number of user gestures. Then convert these
+  // |user_gesture_count_limit| number of user gestures. Then converts these
   // identified NavigationEvents into ReferrerChainEntrys and append them to
   // |out_referrer_chain|.
-  AttributionResult IdentifyReferrerChainForDownload(
-      const GURL& target_url,
-      int target_tab_id,  // -1 if tab id is not valid
+  AttributionResult IdentifyReferrerChainByEventURL(
+      const GURL& event_url,
+      int event_tab_id,  // -1 if tab id is unknown or not available
       int user_gesture_count_limit,
       ReferrerChain* out_referrer_chain);
 
-  // Based on the |web_contents| associated with a download, trace back the
-  // observed NavigationEvents in navigation_event_list_ to identify the
-  // sequence of navigations leading to the download hosting page, with the
+  // Based on the |web_contents| associated with an event, traces back the
+  // observed NavigationEvents in |navigation_event_list_| to identify the
+  // sequence of navigations leading to the event hosting page, with the
   // coverage limited to |user_gesture_count_limit| number of user gestures.
-  // Then convert these identified NavigationEvents into ReferrerChainEntrys
+  // Then converts these identified NavigationEvents into ReferrerChainEntrys
   // and append them to |out_referrer_chain|.
-  AttributionResult IdentifyReferrerChainByDownloadWebContent(
+  AttributionResult IdentifyReferrerChainByWebContents(
       content::WebContents* web_contents,
       int user_gesture_count_limit,
       ReferrerChain* out_referrer_chain);
 
-  // Based on the |initiating_frame_url| and its associated |tab_id|, trace back
-  // the observed NavigationEvents in navigation_event_list_ to identify those
-  // navigations leading to this |initiating_frame_url|. If this initiating
-  // frame has a user gesture, we trace back with the coverage limited to
-  // |user_gesture_count_limit|-1 number of user gestures, otherwise we trace
-  // back |user_gesture_count_limit| number of user gestures. We then convert
-  // these identified NavigationEvents into ReferrerChainEntrys and append them
-  // to |out_referrer_chain|.
-  AttributionResult IdentifyReferrerChainForDownloadHostingPage(
+  // Based on the |initiating_frame_url| and its associated |tab_id|, traces
+  // back the observed NavigationEvents in navigation_event_list_ to identify
+  // those navigations leading to this |initiating_frame_url|. If this
+  // initiating frame has a user gesture, we trace back with the coverage
+  // limited to |user_gesture_count_limit|-1 number of user gestures, otherwise
+  // we trace back |user_gesture_count_limit| number of user gestures. We then
+  // converts these identified NavigationEvents into ReferrerChainEntrys and
+  // appends them to |out_referrer_chain|.
+  AttributionResult IdentifyReferrerChainByHostingPage(
       const GURL& initiating_frame_url,
       const GURL& initiating_main_frame_url,
       int tab_id,
       bool has_user_gesture,
       int user_gesture_count_limit,
       ReferrerChain* out_referrer_chain);
 
   // Record the creation of a new WebContents by |source_web_contents|. This is
   // used to detect cross-frame and cross-tab navigations.
   void RecordNewWebContents(content::WebContents* source_web_contents,
@@ skipping 67 matching lines @@
   NavigationEventList navigation_event_list_;
 
   // user_gesture_map_ keeps track of the timestamp of last user gesture in
   // in each WebContents. We assume for majority of cases, a navigation
   // shortly after a user gesture indicate this navigation is user initiated.
   UserGestureMap user_gesture_map_;
 
   // Host to timestamped IP addresses map that covers all the main frame and
   // subframe URLs' hosts. Since it is possible for a host to resolve to more
   // than one IP in even a short period of time, we map a single host to a
-  // vector of ResolvedIPAddresss. This map is used to fill in ip_address field
-  // in URLChainEntry in ClientDownloadRequest.
+  // vector of ResolvedIPAddresss.
   HostToIpMap host_to_ip_map_;
 
   base::OneShotTimer cleanup_timer_;
 
   DISALLOW_COPY_AND_ASSIGN(SafeBrowsingNavigationObserverManager);
 };
 }  // namespace safe_browsing
 
 #endif  // CHROME_BROWSER_SAFE_BROWSING_SAFE_BROWSING_NAVIGATION_OBSERVER_MANAGER_H_