adblock-rust

adblock-rust is the engine that powers Brave’s native ad blocker, packaged as a reusable Rust library (with JS and community Python bindings). It parses Adblock Plus / uBlock Origin style filter lists and applies them to network requests and page content at high speed.

Beyond simple network blocking, it supports cosmetic filtering, resource replacements, hosts-file syntax, uBlock Origin syntax extensions, and conversion to Apple’s iOS/macOS content-blocking format. It compiles to native code or WebAssembly, making it a practical filtering core for browsers, proxies, research tools, and privacy applications that need production-grade ad and tracker blocking.

What You Get

• A request-matching engine for network blocking backed by optimized filter lists
• Cosmetic filtering with a selector cache for hiding page elements
• Support for Adblock Plus, uBlock Origin extensions, and hosts-file filter syntax
• Resource replacement and scriptlet injection support
• Conversion of ABP-style rules into Apple’s iOS/macOS content-blocking format
• Native and WebAssembly compilation targets with Rust, JS, and Python bindings

Common Use Cases

• Embedding ad and tracker blocking into a browser or webview
• Filtering requests inside a privacy-focused proxy or gateway
• Generating iOS/macOS content-blocker rule sets from standard filter lists
• Running research or measurement tools that evaluate filter-list effectiveness

Under The Hood

Architecture - The public entry point is engine.rs, which wraps blocker.rs (network-request matching) and cosmetic_filter_cache.rs (element-hiding rules). lists.rs and the filters/ module parse raw filter lists into typed rules, network_filter_list.rs and optimizer.rs compile them into fast lookup structures, regex_manager.rs manages compiled patterns, url_parser/ normalizes request URLs, and content_blocking.rs converts rules to Apple’s format. A flatbuffers/data_format layer supports serializing a prebuilt engine for fast startup.

Tech Stack - Written in Rust and built with Cargo, exposing native and WASM targets. It uses crates like regex, flatbuffers, and (behind the css-validation feature) selectors and cssparser. JS bindings are published to npm as adblock-rs and community Python bindings to PyPI; optional Cargo features gate CSS validation and content-blocking conversion.

Code Quality - The codebase is well-tested, with 33+ files containing tests plus a tests/ suite exercising real filter lists and matching behavior. Modules are cleanly separated by concern (parsing, matching, cosmetic, serialization), and the engine is battle-tested as the blocker shipping in the Brave browser.

API Design - The core workflow is small and approachable: construct an Engine from filter-list text, then call check_network_request (and cosmetic helpers) per request. Serialization lets callers cache a compiled engine. The Rust example and docs.rs documentation make onboarding straightforward, though advanced features like content-blocking conversion require reading the feature docs.