# What Information Does the Filtering Context Contain in uBlock Origin?

> Explore the filtering context in uBlock Origin. Discover how it holds essential metadata like URL components, resource types, and tab IDs for effective network request evaluation.

- Repository: [Raymond Hill/uBlock](https://github.com/gorhill/uBlock)
- Tags: deep-dive
- Published: 2026-03-05

---

**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`](https://github.com/gorhill/uBlock/blob/main/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:

```javascript
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`](https://github.com/gorhill/uBlock/blob/main/src/js/filtering-engines.js) where the context is instantiated from WebRequest events before being passed to [`static-net-filtering.js`](https://github.com/gorhill/uBlock/blob/main/static-net-filtering.js) and [`dynamic-net-filtering.js`](https://github.com/gorhill/uBlock/blob/main/dynamic-net-filtering.js).

## Summary

- **The filtering context** is defined in [`src/js/filtering-context.js`](https://github.com/gorhill/uBlock/blob/main/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`](https://github.com/gorhill/uBlock/blob/main/uri-utils.js) for hostname extraction and supports the filtering pipeline used by [`static-net-filtering.js`](https://github.com/gorhill/uBlock/blob/main/static-net-filtering.js) and [`dynamic-net-filtering.js`](https://github.com/gorhill/uBlock/blob/main/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`](https://github.com/gorhill/uBlock/blob/main/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`](https://github.com/gorhill/uBlock/blob/main/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`](https://github.com/gorhill/uBlock/blob/main/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.