What Information Does the Filtering Context Contain in uBlock Origin?

The FilteringContext class in gorhill/uBlock encapsulates every piece of metadata a network request needs for rule evaluation, including URL components, resource types, HTTP methods, document origins, tab identifiers, and helper flags for third-party detection.

The filtering context serves as the central data structure that carries request information through uBlock Origin's filtering pipeline. Defined in src/js/filtering-context.js, this class collects all attributes that static and dynamic filtering engines require to determine whether a request should be blocked, allowed, redirected, or modified. Understanding its properties is essential for developers extending the extension or debugging filter behavior.

Core Properties Stored in the Filtering Context

The FilteringContext instance gathers data through explicit setters and lazy getters, ensuring that expensive hostname extractions or domain lookups occur only when accessed.

Request Identifiers and URL Data

Every context tracks the fundamental network request details:

• url – The full request URL string (line 39-40)
• hostname – Extracted lazily from url via hostnameFromURI() (line 28-33)
• domain – The effective second-level domain computed from the hostname via getDomain() (line 43-48)
• ipaddress – Resolved IP address for IP literals, or empty string for hostnames (line 55-68)
• realm – Arbitrary string identifier used by the engine to group related requests (line 34-36)

Resource Type and HTTP Method

The context stores type information as both integers and strings to optimize bitmask comparisons:

• itype / stype – Integer and string representations of the resource type (script, image, main_frame, etc.). The type setter converts strings like "script" to integer bitmasks using typeStrToIntMap (line 37-39, 61-64)
• method – Bitmask representing the HTTP method (GET, POST, etc.), set via setMethod() through methodStrToBitMap (line 30-33)

The class also re-exports constants such as FilteringContext.SCRIPT and FilteringContext.METHOD_GET so other modules can reference resource types without importing separate constant blocks.

Document Context Fields

To evaluate $third-party filters and document-level rules, the context tracks the containing document:

• docId / frameId – Internal identifiers for the document frame, initialized to -1 (line 44-46)
• docOrigin – The origin (scheme + host + port) of the top-level document (line 46-48)
• docHostname / docDomain – Hostname and domain of the document origin, populated lazily by getDocHostname() and getDocDomain() (line 71-76)

Tab Context and Origin Data

For tab-specific filtering and proper isolation:

• tabId – Browser tab identifier (line 48-50)
• tabOrigin / tabHostname / tabDomain – Origin, hostname, and domain of the tab's top-level URL (line 50-53), set via setTabOriginFromURL()

Filtering Results and Redirects

After evaluation, engines populate:

• redirectURL – Target URL when a redirect filter matches (line 53-55)
• filter – The matching filter object or array of filters, managed via setFilter(), pushFilter(), and pushFilters() (line 99-127)

Helper Methods for Request Classification

The class provides efficient boolean checks used throughout the engine:

• isRootDocument() – Returns true when itype includes MAIN_FRAME, identifying top-level navigation requests (line 66-68)
• isDocument() – Returns true for any frame type (main, sub-frame, object) via FRAME_ANY bitmask check (line 69-71)
• isFont() – Returns true for font resources using FONT_ANY bitmask (line 72-74)

Third-Party Detection

Two critical methods compare the request's domain against the document or tab origin:

• is3rdPartyToDoc() – Checks if the request hostname is third-party relative to docDomain (line 123-140)
• is3rdPartyToTab() – Performs the same check against tabDomain (line 187-200)

Both utilize fast string comparison optimized for the filtering engine's performance requirements.

Instantiating and Populating FilteringContext

Developers typically build a context using the factory method fromDetails(), which chains internal setters:

import { FilteringContext } from "./filtering-context.js";

// Create context from webRequest details
const fc = new FilteringContext()
    .fromDetails({
        originURL: details.initiator,   // Document origin
        url:       details.url,
        type:      details.type        // "script", "image", etc.
    })
    .setTabOriginFromURL(tabUrl);

// Access computed properties
console.log(fc.getHostname());      // Extracted from URL
console.log(fc.is3rdPartyToDoc());  // Boolean check

The fromDetails() helper (lines 98-104) internally calls setDocOriginFromURL(), setURL(), and setType() to populate the instance. This pattern appears throughout the codebase, particularly in src/js/filtering-engines.js where the context is instantiated from WebRequest events before being passed to static-net-filtering.js and dynamic-net-filtering.js.

Summary

• The filtering context is defined in src/js/filtering-context.js and serves as the primary data structure for request metadata in gorhill/uBlock.
• It stores URL components (url, hostname, domain, ipaddress), request metadata (method, itype/stype), and origin data for documents and tabs.
• Lazy getters like getDomain() and getDocHostname() optimize performance by computing values only when accessed.
• Boolean helpers including isRootDocument() and is3rdPartyToTab() provide fast bitmask-based classification for filtering rules.
• The class integrates with uri-utils.js for hostname extraction and supports the filtering pipeline used by static-net-filtering.js and dynamic-net-filtering.js.

Frequently Asked Questions

What is the difference between docOrigin and tabOrigin in the filtering context?

The docOrigin property represents the immediate document that initiated the request (the frame's origin), while tabOrigin represents the top-level tab's URL. For most frames, these differ when a sub-frame requests resources. The distinction allows filters to target $third-party requests relative to either the immediate document or the top-level tab.

How does FilteringContext handle IP addresses versus hostnames?

When the request URL contains an IP literal (e.g., http://192.168.1.1/script.js), the ipaddress property stores that IP string, and getDomain() returns the IP address as-is. For standard hostnames, ipaddress remains an empty string, and getDomain() extracts the effective second-level domain using functions from uri-utils.js.

Why does uBlock Origin use integer bitmasks (itype) for resource types instead of strings?

Integer bitmasks enable extremely fast bitwise operations when matching filter rules. The FilteringContext class maintains both representations: stype holds the human-readable string (like "script") for logging and debugging, while itype stores the integer bitmask (like SCRIPT). This design allows the engine to check multiple resource types simultaneously using bitwise AND operations.

Where is the filtering context instantiated in the uBlock Origin codebase?

The context is typically created in src/js/filtering-engines.js when processing WebRequest events. The fromDetails() method populates the instance from browser API data, after which the object passes through static-net-filtering.js for rule evaluation. The context travels through the entire pipeline, accumulating matched filters and redirect information before the final decision reaches the browser.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}