Subresource Filter

The subresource_filter component deals with code that tags and filters subresource requests based on:

Some page-level activation signal (e.g. should sub-resource filtering take place on this page).

A ruleset used to match URLs for filtering.

The primary consumer of this component is Chrome's ad filter, which filters ads on pages that violate the Better Ads Standard.

Additionally, Chrome will filter pages Safe Browsing determines are used for phishing (i.e. on pages after the user has proceeded through the security interstitial).

High Level Description

At a high level, the component uses a memory mapped file of filtering rules to filter subresource requests in Blink, as well as subframe navigations in the browser process.

For historical reasons (intention to support iOS), code is split into two components, core and content. The core code is code that we could share with a non-content client like iOS, while all the content code depends on the Content API.

Most of the logic in core deals with reading, indexing, and matching URLs off a ruleset.

Most of the logic in content deals with tracking navigations, communicating with the renderer, and interacting with the //chrome client code.

Detailed Architecture

In this section, ‘=>’ represents strong ownership, and ‘~>’ is a weak reference.

Code in core/browser is responsible for writing and indexing filtering rules. The class that does most of this work is the RulesetService.

BrowserProcessImpl=>ContentRulesetService=>RulesetService

The RulesetService is responsible for indexing filtering rules into a Flatbuffer format, and writing them to disk. These rules come from the RulesetServiceDelegate as an UnindexedRuleset which will be downloaded via the Component Updater. It also performs other tasks like deleting obsolete rulesets.

The code in this component also maintains a global ConfigurationList, which defines how the entire subresource_filter component behaves.

The code in core/common deals with logic involved in filtering subresources that is used in both browser and renderer processes. The most important class is the DocumentSubresourceFilter which contains logic to filter subresources in the scope of a given document.

Currently, the SubresourceFilterSafeBrowsingActivationThrottle checks every redirect URL speculatively, but makes an activation decision based on the last URL.

Document-level activation

The ruleset has rules for whitelisting documents in specific ways. How a given document is activated is codified in the ActivationState struct.

In order to notify a document in the renderer about how it should be activated, we read from the ruleset in the browser process and send an IPC to the frame at ReadyToCommitNavigationTime.

This logic is Handled by the ActivationStateComputingNavigationThrottle. ActivationStateComputingNavigationThrottle=>AsyncDocumentSubresourceFilter This ownership is passed to the ContentSubresourceFilterThrottleManager at ReadyToCommitNavigation time.

Subframe filtering

This component also needs to filter subframes that match the ruleset. This is done by the SubframeNavigationFilteringThrottle, which consults its parent frame's AsyncDocumentSubresourceFilter.

Throttle management

The ContentSubresourceFilterThrottleManager is a WebContentsObserver, and manages both the ActivationStateComputingNavigationThrottle and the SubframeNavigationFilteringThrottle. It maintains a map of all the activated frames in the frame tree, along with that frame's current AsyncDocumentSubresourceFilter, taken from the ActivationStateComputingNavigationThrottle.