adblock-rust

adblock-rust is available as a library for multiple environments. You can use the Rust implementation via crates.io or the JavaScript implementation via npm.

• Rust: Use the adblock crate.
• JavaScript/Node.js: Use the adblock-rs npm package.
• Python: Community-maintained bindings are available on PyPI as adblock.

To run the fuzzing suite specifically for the filter parsing logic, you must first install cargo-fuzz and then execute the parse_filter target.

cargo install cargo-fuzz
cargo fuzz run parse_filter

The Engine is the primary interface for adblocking. It is designed to be immutable after creation; to change rules, you must create a new engine.

To initialize an engine, combine your filter lists into a FilterSet and use Engine::new_with_filter_set. You can also provide Resources (used for $redirect filters and ##+js(...) scriptlets) using Engine::use_resources.

Cosmetic filtering is a two-step process:

1. Identify required resources: Call Engine::url_cosmetic_resources(url) to get UrlSpecificResources. This tells you what actions are needed to prepare the page.
2. Handle dynamic elements: As the page loads, pass any new CSS classes or IDs to Engine::hidden_class_id_selectors to find additional elements that should be hidden.

hidden_class_id_selectors requires a HashSet<String> of exceptions passed directly from the UrlSpecificResources obtained in step 1.

When adding filters to a FilterSet, use ParseOptions to control how the rules are interpreted. It is recommended to use the struct update syntax with ParseOptions::default() to ensure compatibility with future fields.

Key options include:

• format: The FilterFormat to use (e.g., Standard or Hosts). Defaults to FilterFormat::Standard.
• rule_types: A RuleTypes enum to filter which rules are kept (e.g., All, NetworkOnly, or CosmeticOnly). This can reduce memory usage.
• permissions: A PermissionMask specifying permissions for the parsed list.

use adblock::lists::{FilterFormat, ParseOptions, RuleTypes};

let parse_options = ParseOptions {
    format: FilterFormat::Hosts,
    rule_types: RuleTypes::NetworkOnly,
    ..ParseOptions::default()
};

The RegexManager manages the storage of compiled regular expressions used by filters. To reduce the memory footprint, it can discard infrequently used regexes. You can customize this behavior using the RegexManagerDiscardPolicy struct.

Set the following fields:

• cleanup_interval: The duration at which the RegexManager checks for and cleans up unused filters.
• discard_unused_time: The duration after which a regex is considered unused and eligible for discarding.

Use set_discard_policy to apply a new policy to an existing RegexManager instance.

When writing cosmetic filters, be aware that the following pseudo-classes are currently unsupported and will cause parsing errors:

• -abp-contains / -abp-has (Note: these are aliases for has-text and are supported, but other specific -abp- prefixes might not be)
• -abp-properties
• if
• if-not
• matches-property
• nth-ancestor
• properties
• subject
• remove
• remove-attr
• remove-class

The CbAction struct defines what happens when a rule's trigger matches. It contains a typ (of type CbType) and an optional selector.

Available CbType values:

• Block: Stops loading of the resource.
• BlockCookies: Strips cookies from the header.
• CssDisplayNone: Hides elements using a CSS selector. Note: The selector field is required when using this type and should contain a comma-separated list of CSS identifiers.
• IgnorePreviousRules: Ignores previously triggered actions.
• MakeHttps: Changes a URL from http to https.

Important: If typ is CssDisplayNone, the selector field must be populated, otherwise Safari will ignore the rule.

Use FilterSet to assemble a compound list of rules from multiple sources before compiling them into an Engine. This is necessary to handle special options like $badfilter and to allow for optimizations during engine creation.

To create a new set, use FilterSet::new(debug). Setting debug to true allows the engine to retain information about the original raw filter rules.