$ show gorhill/uBlock
uBlock Origin is a high-performance, wide-spectrum content blocker implemented as a browser extension for Chromium, Firefox, Edge, Opera, and Thunderbird. The architecture is a multi-platform browser extension with a core filtering engine (static network filtering, cosmetic filtering, scriptlet injection) written in highly optimized JavaScript with WebAssembly acceleration (custom HNTrie/BidiTrie compressed tries, LZ4 block codec, public suffix list). The MV2 variant uses webRequestBlocking for real-time request interception, while the MV3 variant (uBO Lite) uses declarativeNetRequest with offscreen documents for filter compilation. A standalone npm package (@gorhill/ubo-core) exposes the static network filtering engine for programmatic use outside the browser. The codebase demonstrates exceptional craftsmanship in its filtering engines: the static network filtering parser and matcher handle the full EasyList syntax plus extensive uBO-specific extensions (replace=, urlskip=, ipaddress=, header=, csp=, permissions=, etc.). The HNTrieContainer implements a compressed trie specialized for right-to-left hostname matching with both JS and WASM implementations. The cosmetic filtering engine supports procedural selectors, scriptlet injection with 50+ scriptlets, and HTML filtering. The s14e-serializer provides efficient binary serialization with LZ4 compression for fast engine state snapshots. Differential updates for filter lists minimize bandwidth. The code is meticulously optimized for CPU and memory efficiency, which is critical for a content blocker processing every network request.
The LLM identified 6 files worth highlighting for reuse:
HNTrieContainer implements a compressed trie data structure specialized for efficient hostname matching, where labels are matched right-to-left (e.g., 'www.example.org' matches if 'example.org' is stored). It supports both pure JavaScript and WebAssembly implementations, with the WASM version compiled from hand-written WAT (WebAssembly Text) source. The container manages multiple tries sharing a single memory buffer, with add/lookup/matches operations optimized for the specific access pattern of ad-blocking filter matching against large hostname sets (40,000+ entries). This is a key performance component that could be extracted for any application needing fast hostname or domain matching against large sets.
The static network filtering engine (SNFE) is the core of uBO's request blocking capability. It parses and compiles EasyList-format filter rules (plus uBO-specific extensions like replace=, urlskip=, ipaddress=, header=, csp=, permissions=, redirect=, etc.) into an optimized internal representation for fast matching. The engine supports compilation, serialization/deserialization (via s14e-serializer with LZ4 compression), token-based pattern matching, and complex filter options including domain matching, regex patterns, and redirect rules. Exposed via the npm package @gorhill/ubo-core for standalone use outside the browser.
The npm package entry point (@gorhill/ubo-core) exposes StaticNetFilteringEngine as a standalone API for programmatic use of uBO's filtering engine outside the browser. It provides create/useLists/matchRequest/serialize/deserialize methods, enabling any Node.js application to load filter lists (EasyList, EasyPrivacy, hosts files, etc.) and match network requests against them. The API supports WASM acceleration, public suffix list initialization, and efficient serialization for caching compiled engine state. This is genuinely reusable as a standalone content-filtering library.
AstFilterParser is a comprehensive parser for the EasyList/uBO static filter syntax, producing an AST representation of filter rules. It handles network filters (with all option types: domain, redirect, csp, permissions, replace, urlskip, ipaddress, header, etc.), cosmetic filters (CSS selectors, procedural operators, scriptlet injection), and HTML filters. The parser validates syntax, classifies filter types, and supports incremental parsing. This is a non-trivial, well-structured parser that could be reused by any tool needing to analyze or transform ad-blocking filter lists.
A custom binary serializer/deserializer that efficiently encodes complex JavaScript data structures (TypedArrays, ArrayBuffers, Maps, Sets, etc.) into a compact format with optional LZ4 compression. Used for serializing the full filtering engine state to enable fast cold-start loads without re-parsing filter lists. Handles shared ArrayBuffer references across multiple TypedArrays correctly during deserialization. The serializer is self-contained and could be extracted for any application needing efficient binary serialization of structured data with compression.
A clean, self-contained Most Recently Used (MRU) cache implementation combining a Map for O(1) lookup with an Array for O(1) most-recent access tracking. The lookup method promotes accessed items to the front via array copyWithin, and add evicts the least recently used item when capacity is reached. Simple, dependency-free, and immediately reusable in any JavaScript project needing a bounded cache with MRU eviction semantics.