#filter #matching #syntax #module #engine #native #block #plus #ad


Native Rust module for Adblock Plus syntax (e.g. EasyList, EasyPrivacy) filter parsing and matching.

61 releases

0.3.11 May 12, 2021
0.3.10 Mar 18, 2021
0.3.6 Feb 23, 2021
0.3.4 Dec 11, 2020
0.1.28 Jul 22, 2019
Download history 1404/week @ 2021-02-20 1373/week @ 2021-02-27 1431/week @ 2021-03-06 1402/week @ 2021-03-13 1677/week @ 2021-03-20 1191/week @ 2021-03-27 1409/week @ 2021-04-03 2143/week @ 2021-04-10 2456/week @ 2021-04-17 2166/week @ 2021-04-24 2033/week @ 2021-05-01 2152/week @ 2021-05-08 2601/week @ 2021-05-15 2120/week @ 2021-05-22 2035/week @ 2021-05-29 2578/week @ 2021-06-05

7,401 downloads per month
Used in adblock-rust-server

MPL-2.0 license

13K SLoC

Rust 10K SLoC // 0.0% comments JavaScript 2.5K SLoC // 0.2% comments

Ad Block engine in Rust

docs.rs crates.io npmjs.com Build Status

Native Rust module for Adblock Plus syntax (e.g. EasyList, EasyPrivacy) filter parsing and matching.

It uses a tokenisation approach for quickly reducing the potentially matching rule search space against a URL.

The algorithm is inspired by, and closely follows the algorithm of uBlock Origin and Cliqz.

Somewhat graphical explanation of the algorithm:

Ad Block Algorithm


Demo use in Rust:

use adblock::engine::Engine;
use adblock::lists::{FilterFormat, FilterSet};

fn main() {
    let rules = vec![

    let mut filter_set = FilterSet::new(true);
    filter_set.add_filters(&rules, FilterFormat::Standard);

    let blocker = Engine::from_filter_set(&filter_set, true);
    let blocker_result = blocker.check_network_urls("http://example.com/-advertisement-icon.", "http://example.com/helloworld", "image");

    println!("Blocker result: {:?}", blocker_result);

Node.js module demo

Note the Node.js module has overheads inherent to boundary crossing between JS and native code.

const AdBlockClient = require('adblock-rs');
let el_rules = fs.readFileSync('./data/easylist.to/easylist/easylist.txt', { encoding: 'utf-8' }).split('\n');
let ubo_unbreak_rules = fs.readFileSync('./data/uBlockOrigin/unbreak.txt', { encoding: 'utf-8' }).split('\n');
let rules = el_rules.concat(ubo_unbreak_rules);
let resources = AdBlockClient.uBlockResources('uBlockOrigin/src/web_accessible_resources', 'uBlockOrigin/src/js/redirect-engine.js', 'uBlockOrigin/assets/resources/scriptlets.js');

const filterSet = new AdBlockClient.FilterSet(true);
const client = new AdBlockClient.Engine(filterSet, true);

const serializedArrayBuffer = client.serialize(); // Serialize the engine to an ArrayBuffer

console.log(`Engine size: ${(serializedArrayBuffer.byteLength / 1024 / 1024).toFixed(2)} MB`);

console.log("Matching:", client.check("http://example.com/-advertisement-icon.", "http://example.com/helloworld", "image"))
// Match with full debuging info
console.log("Matching:", client.check("http://example.com/-advertisement-icon.", "http://example.com/helloworld", "image", true))
// No, but still with debugging info
console.log("Matching:", client.check("https://github.githubassets.com/assets/frameworks-64831a3d.js", "https://github.com/AndriusA", "script", true))
// Example that inlcludes a redirect response
console.log("Matching:", client.check("https://bbci.co.uk/test/analytics.js", "https://bbc.co.uk", "script", true))

Optional features

CSS validation during rule parsing

When parsing cosmetic filter rules, it's possible to include a built-in implementation of CSS validation (through the selectors and cssparser crates) by enabling the css-validation feature. This will cause adblock-rust to reject cosmetic filter rules with invalid CSS syntax.

Content blocking format translation

Enabling the content-blocking feature gives adblock-rust support for conversion of standard ABP-style rules into Apple's content-blocking format, which can be exported for use on iOS and macOS platforms.

External domain resolution

By default, adblock-rust ships with a built-in domain resolution implementation (through the addr crate) that will generally suffice for standalone use-cases. For more advanced use-cases, disabling the embedded-domain-resolver feature will allow adblock-rust to use an external domain resolution implementation instead. This is extremely useful to reduce binary bloat and improve consistency when embedding adblock-rust within a browser.

Parsing resources from uBlock Origin's formats

adblock-rust uses uBlock Origin-compatible resources for scriptlet injection and redirect rules. The resource-assembler feature allows adblock-rust to parse these resources directly from the file formats used by the uBlock Origin repository.


~175K SLoC