This page defines the core vocabulary used throughout the uBlock Origin codebase. It is intended as a reference glossary for developers reading source code or other wiki pages. It does not explain how any system works in detail—for that, see the dedicated pages for each subsystem:
µb singleton → see 4.1A filter list is a plain-text file containing one rule per line. Rules are written in EasyList syntax (or uBO's extended superset of it). Each list has a registry entry in assets/assets.json that declares its ID, content type, source URLs, CDN fallbacks, and diff-patch URLs.
Content type values found in assets.json:
content value | Meaning |
|---|---|
"filters" | A filter list compiled into the filtering engines |
"internal" | A metadata or configuration asset (e.g., public_suffix_list.dat) |
Filter lists ship in groups: default, ads, privacy, malware, annoyances, multipurpose, regions. The "off": true field in an entry means the list is disabled by default.
Sources: assets/assets.json1-100 assets/assets.dev.json1-60
The codebase recognizes several broad categories of filter rule. The AstFilterParser in src/js/static-filtering-parser.js assigns each parsed rule one of these AST types:
AST_TYPE_NETWORK — network request filter (block/allow/redirect/modify)
AST_TYPE_EXTENDED — extended filter (cosmetic, scriptlet, HTML, response-header)
AST_TYPE_COMMENT — comment or preparser directive
AST_TYPE_UNKNOWN — unrecognized or unsupported syntax
The following diagram maps filter syntax to AST types and processing engines:
Filter Type → AST Node → Engine
Sources: src/js/static-filtering-parser.js59-76 src/js/static-filtering-parser.js762-780
A network filter matches against HTTP(S) requests. The two fundamental subtypes are block and allow (exception):
| Syntax | Behavior |
|---|---|
| ` | |
| `@@ | |
| ` |
Network filters are processed by StaticNetFilteringEngine in src/js/static-net-filtering.js Internally, each filter is assigned a category bitmask (called a realm) encoding its action, party scope, and request type.
Realm bit layout (from src/js/static-net-filtering.js49-89):
| Bits | Name | Meaning |
|---|---|---|
| 0–1 | BLOCK_REALM / ALLOW_REALM / IMPORTANT_REALM | Block, exception, or $important |
| 3–4 | FIRSTPARTY_REALM / THIRDPARTY_REALM | $1p or $3p scope |
| 5–9 | TYPE_REALM | Request type (script, image, xhr, etc.) |
| 10 | HEADERS_REALM | $header= filter |
| 11 | REDIRECT_REALM | $redirect= / $redirect-rule= |
| 12 | REMOVEPARAM_REALM | $removeparam= |
| 13 | CSP_REALM | $csp= |
| 14 | PERMISSIONS_REALM | $permissions= |
| 15 | URLTRANSFORM_REALM | $uritransform= |
| 16 | REPLACE_REALM | $replace= |
| 17 | URLSKIP_REALM | $urlskip= |
Request type names recognized by the parser (from typeNameToTypeValue in src/js/static-net-filtering.js93-119):
stylesheet, image, object, script, fetch / xmlhttprequest, sub_frame, font, media, websocket, beacon / ping, other, popup, popunder, main_frame, generichide, specifichide, inline-font, inline-script, cname, webrtc
Filter options recognized by the parser are declared in nodeTypeFromOptionName in src/js/static-filtering-parser.js221-287 Common ones include $domain= / $from=, $3p, $1p, $important, $redirect=, $csp=, $removeparam=, $badfilter, $denyallow=.
Static filtering refers to rules that are compiled from filter lists at startup and frozen into data structures that cannot be changed at runtime without a full reload. The term static contrasts with dynamic (see below).
The static filtering pipeline has three engines, each handling a different rule family:
| Engine | Source File | Rule Family |
|---|---|---|
StaticNetFilteringEngine | src/js/static-net-filtering.js | Network block/allow/modify rules |
CosmeticFilteringEngine | src/js/cosmetic-filtering.js | Element hiding (##) rules |
ScriptletFilteringEngineEx | src/js/scriptlet-filtering.js | Scriptlet injection (##+js()) rules |
These engines are initialized at startup by reading compiled filter data from cachestorage and cannot be modified piecemeal during a session.
Sources: src/js/static-net-filtering.js1-90 src/js/static-filtering-parser.js59-76
Cosmetic filters hide page elements by injecting CSS display: none rules or by using JavaScript-based procedural selectors. They do not block network requests.
Rule syntax examples:
| Syntax | Effect |
|---|---|
##.ad-banner | Hide any element with class ad-banner on all sites (generic) |
example.com##.ad-banner | Hide .ad-banner only on example.com (specific) |
example.com#@#.ad-banner | Exception: do not hide .ad-banner on example.com |
##^script:has-text(ad) | HTML filter: remove <script> tags containing "ad" from the DOM |
example.com##+js(set, adblock, false) | Scriptlet: run the named scriptlet on example.com |
The AST node type for cosmetic patterns is AST_TYPE_EXTENDED_COSMETIC (src/js/static-filtering-parser.js72). The decoration characters that distinguish cosmetic filter subtypes are:
| Decoration | Subtype |
|---|---|
## | Standard cosmetic (hide by CSS selector) |
#@# | Cosmetic exception |
##^ | HTML filter (response body) |
##+js(…) | Scriptlet injection |
Sources: src/js/static-filtering-parser.js72-76 src/js/static-filtering-parser.js559-586
A scriptlet is a small JavaScript function injected into a page's execution context before any page scripts run. Scriptlets are used to neutralize anti-adblock scripts, defuse tracking code, or spoof browser APIs.
Scriptlet rules use the ##+js() syntax. The token after ##+js( names the scriptlet; arguments follow after a comma:
example.com##+js(set-constant, adblockDetected, false)
The scriptlet library is compiled into web_accessible_resources/scriptlets.js. The ScriptletFilteringEngineEx class (src/js/scriptlet-filtering.js) resolves which scriptlets apply to a given hostname and injects them via the browser's scripting API. For MV3, the equivalent is handled by scripting-manager.js in platform/mv3/.
Sources: src/js/static-filtering-parser.js73 src/js/static-filtering-parser.js130-133
Dynamic filtering refers to rules that can be changed at runtime without reloading filter lists. These rules are set by the user through the popup's firewall grid or through the "My rules" pane in the dashboard.
Dynamic rules operate on three dimensions:
allow, block, or noop (no override)Dynamic rules are evaluated after static rules and can override them. A per-site dynamic rule takes priority over a global dynamic rule. The $important option in a static rule overrides dynamic rules in the allow direction.
Dynamic filtering is processed separately from the StaticNetFilteringEngine. The relevant source is src/js/dynamic-net-filtering.js and the session firewall state is managed in src/js/traffic.js.
Sources: Diagram 2 in system overview; see 3.5 for full documentation.
These are the two browser extension manifest versions, which impose fundamentally different architectural constraints:
Manifest Version Comparison:
| Feature | MV2 (uBlock Origin) | MV3 (uBO Lite) |
|---|---|---|
| Background | Persistent page | Ephemeral service worker |
| Request interception | browser.webRequest (dynamic) | declarativeNetRequest (static) |
| Filter compilation | At runtime, in-memory | At build time, JSON rulesets |
| Dynamic filtering | Full support | Not supported |
| Scriptlet injection | Full support (via content scripts) | Limited (via scripting API) |
| HTML filtering | Supported | Not supported |
| Product name | uBlock Origin | uBO Lite (uBOLite) |
| Build output | dist/build/uBlock0.* | dist/build/uBOLite.* |
The MV3 ruleset compilation happens in tools/make-rulesets.js. For full MV3 architecture details, see 10.
Sources: platform/mv3/rulesets.json1-50
vAPI is the browser abstraction layer — a global object present in all extension contexts (background, content scripts, UI pages) that wraps browser-specific APIs behind a unified interface.
Key namespaces on the vAPI object:
| Property / Namespace | Purpose |
|---|---|
vAPI.messaging | IPC between background, content scripts, and UI pages |
vAPI.tabs | Tab lifecycle management (vAPI.Tabs) |
vAPI.Net | webRequest listener registration and management |
vAPI.storage | Key-value persistence via browser.storage.local |
vAPI.localStorage | Synchronous local storage wrapper |
vAPI.browserAction | Toolbar button badge and icon |
vAPI.browserSettings | Browser-level settings (e.g., proxy, cookie policy) |
vAPI.getURL(path) | Resolve extension-relative resource paths |
Platform-specific implementations live in:
platform/chromium/vapi-background.jsplatform/firefox/vapi-background.jsThe shared base is in platform/common/vapi-common.js.
The vAPI object is referenced extensively throughout the codebase: for example, vAPI.localStorage is accessed in src/js/static-net-filtering.js42-44 as a key-value store for optimization parameters.
Sources: src/js/static-net-filtering.js42-44 src/js/utils.js63
µb (typed as µb in source, declared in src/js/background.js and imported as µb throughout) is the central state container for the entire background process. It is a single shared object that holds references to every major subsystem.
Key properties of the µb object:
| Property | Type / Source | Purpose |
|---|---|---|
µb.staticNetFilteringEngine | StaticNetFilteringEngine | Main network filter engine |
µb.cosmeticFilteringEngine | CosmeticFilteringEngine | Cosmetic/element hiding engine |
µb.scriptletFilteringEngine | ScriptletFilteringEngineEx | Scriptlet injection engine |
µb.redirectEngine | RedirectEngine | Resource redirection engine |
µb.pageStores | Map<tabId, PageStore> | Per-tab request state |
µb.userSettings | Object | Persisted user preferences |
µb.hiddenSettings | Object | Advanced hidden settings |
µb.assets | Asset manager | Filter list fetching and caching |
µb.logger | Logger | Request logging for the logger UI |
µb is imported via import µb from './background.js' in files like src/js/utils.js22 and many others. It acts as the single source of truth for all background-page state.
Diagram: µb and its engine dependencies
Sources: src/js/utils.js22
The AstFilterParser class in src/js/static-filtering-parser.js762 converts a raw filter rule string into an AST (Abstract Syntax Tree). The AST is represented as a flat integer array — all nodes are allocated in a single Uint32Array to avoid GC pressure (src/js/static-filtering-parser.js766-768).
Key classes in the parser:
| Class | Role |
|---|---|
AstFilterParser | Main parser; parses one rule at a time into an AST |
AstWalker | Traverses the AST depth-first (src/js/static-filtering-parser.js640) |
DomainListIterator | Iterates from= / domain= option value lists (src/js/static-filtering-parser.js709) |
The parser outputs AST node types (constants prefixed NODE_TYPE_) and AST-level flags (constants prefixed AST_FLAG_). For example:
AST_FLAG_IS_EXCEPTION — set when the rule starts with @@AST_FLAG_NET_PATTERN_LEFT_HNANCHOR — set when the pattern starts with ||AST_FLAG_HAS_OPTIONS — set when the rule has a $options sectionSources: src/js/static-filtering-parser.js59-211 src/js/static-filtering-parser.js640-705
Inside StaticNetFilteringEngine, each filter is stored not as a JavaScript object but as a set of integers in a flat Int32Array (filterData). The filter class is identified by a numeric ID (fid). Each class is a static JavaScript class registered via registerFilterClass().
Core filter class hierarchy (from src/js/static-net-filtering.js671-724):
Sources: src/js/static-net-filtering.js671-724 src/js/static-net-filtering.js728-779
When filter lists are compiled, the result is stored in a selfie — a serialized snapshot of the filtering engine's internal state. On subsequent startups, the selfie is loaded from cachestorage instead of re-parsing the raw filter lists, which is significantly faster.
Key functions in src/js/static-net-filtering.js:
| Function | Purpose |
|---|---|
filterDataToSelfie() | Serialize filterData Int32Array to storable form |
filterDataFromSelfie(selfie) | Restore filterData from stored selfie |
filterRefsToSelfie() | Serialize the filterRefs reference array |
filterRefsFromSelfie(selfie) | Restore filterRefs from stored selfie |
The selfie is invalidated whenever filter lists change (version bump or manual update), forcing a fresh compilation.
Sources: src/js/static-net-filtering.js501-533
Preparser directives are special comment lines in filter lists that conditionally include or exclude subsequent rules based on the runtime environment. They use !#if / !#endif syntax.
Recognized tokens (from preparserIfTokens in src/js/static-filtering-parser.js597-626):
| Token | Meaning |
|---|---|
ext_ublock | Running as uBlock Origin |
ext_ubol | Running as uBO Lite |
env_chromium / env_firefox / env_edge / env_safari | Browser environment |
env_mv3 | Running under Manifest V3 |
cap_html_filtering | HTML filtering is available |
cap_user_stylesheet | User stylesheet injection is available |
Sources: src/js/static-filtering-parser.js597-626
The term realm is used internally to describe a partition of the filter namespace. The static net filtering engine organizes filters into buckets keyed by a combined bitmask of realm constants. This ensures that when a request arrives, only the relevant bucket is searched.
The realm bitmask is composed of:
BLOCK_REALM, ALLOW_REALM, IMPORTANT_REALMFIRSTPARTY_REALM, THIRDPARTY_REALMtypeNameToTypeValueREDIRECT_REALM, CSP_REALM, REMOVEPARAM_REALM, etc.Sources: src/js/static-net-filtering.js48-90
| Term | Codebase Symbol / File | Role |
|---|---|---|
| Filter list | assets/assets.json | Registry of rule text files |
| Static filtering | StaticNetFilteringEngine | Network block/allow decisions from compiled lists |
| Dynamic filtering | src/js/dynamic-net-filtering.js | Runtime-editable user firewall rules |
| Network filter | AST_TYPE_NETWORK | Matches/blocks/modifies HTTP requests |
| Cosmetic filter | AST_TYPE_EXTENDED_COSMETIC | Hides page elements via CSS |
| Scriptlet | AST_TYPE_EXTENDED_SCRIPTLET | JS injected into page context |
| HTML filter | AST_TYPE_EXTENDED_HTML | Rewrites response body DOM |
| vAPI | platform/*/vapi-*.js | Browser API abstraction layer |
| µb | src/js/background.js | Central background state singleton |
| Selfie | filterDataToSelfie() | Serialized compiled filter state |
| Realm | Bitmask constants in static-net-filtering.js | Filter partitioning by action/party/type |
| Preparser directive | preparserIfTokens | Conditional filter list inclusion |
| AstFilterParser | src/js/static-filtering-parser.js | Converts raw rule text to AST |
| MV2 | dist/build/uBlock0.* | Classic uBlock Origin (webRequest-based) |
| MV3 | dist/build/uBOLite.* | uBO Lite (declarativeNetRequest-based) |
Refresh this wiki
This wiki was recently refreshed. Please wait 2 days to refresh again.