Struct adblock::Engine

pub struct Engine { /* private fields */ }

Drives high-level blocking logic and is responsible for loading filter lists into an optimized format that can be queried efficiently.

For performance optimization reasons, the Engine is not designed to have rules added or removed after its initial creation. Making changes to the rules loaded is accomplished by creating a new engine to replace it.

Usage

Initialization

You’ll first want to combine all of your filter lists in a FilterSet, which will parse list header metadata. Once all lists have been composed together, you can call Engine::from_filter_set to start using them for blocking.

You may also want to supply certain assets for $redirect filters and ##+js(...) scriptlet injections. These are known as Resources, and can be provided with Engine::use_resources. See the crate::resources module for more information.

Network blocking

Use the Engine::check_network_request method to determine how to handle a network request.

If you only need network blocking, consider using a Blocker directly.

Cosmetic filtering

Call Engine::url_cosmetic_resources to determine what actions should be taken to prepare a particular page before it starts loading.

Once the page has been loaded, any new CSS classes or ids that appear on the page should be passed to Engine::hidden_class_id_selectors on an ongoing basis to determine additional elements that should be hidden dynamically.

Implementations

impl Engine

pub fn new(optimize: bool) -> Self

Creates a new adblocking Engine. Engines created without rules should generally only be used with deserialization.

• optimize specifies whether or not to attempt to compress the internal representation by combining similar rules.

pub fn from_rules( rules: impl IntoIterator<Item = impl AsRef<str>>, opts: ParseOptions, ) -> Self

Loads rules in a single format, enabling optimizations and discarding debug information.

pub fn from_rules_debug( rules: impl IntoIterator<Item = impl AsRef<str>>, opts: ParseOptions, ) -> Self

Loads rules, enabling optimizations and including debug information.

pub fn from_rules_parametrised( filter_rules: impl IntoIterator<Item = impl AsRef<str>>, opts: ParseOptions, debug: bool, optimize: bool, ) -> Self

pub fn from_filter_set(set: FilterSet, optimize: bool) -> Self

Loads rules from the given FilterSet. It is recommended to use a FilterSet when adding rules from multiple sources.

pub fn serialize_raw(&self) -> Result<Vec<u8>, SerializationError>

Serializes the Engine into a binary format so that it can be quickly reloaded later.

pub fn deserialize( &mut self, serialized: &[u8], ) -> Result<(), DeserializationError>

Deserialize the Engine from the binary format generated by Engine::serialize_raw. The method will automatically select the correct deserialization implementation.

pub fn check_network_request(&self, request: &Request) -> BlockerResult

Check if a request for a network resource from url, of type request_type, initiated by source_url, should be blocked.

pub fn check_network_request_subset( &self, request: &Request, previously_matched_rule: bool, force_check_exceptions: bool, ) -> BlockerResult

pub fn get_csp_directives(&self, request: &Request) -> Option<String>

Returns a string containing any additional CSP directives that should be added to this request’s response. Only applies to document and subdocument requests.

If multiple policies are present from different rules, they will be joined by commas.

pub fn use_tags(&mut self, tags: &[&str])

Sets this engine’s tags to be only the ones provided in tags.

Tags can be used to cheaply enable or disable network rules with a corresponding $tag option.

pub fn enable_tags(&mut self, tags: &[&str])

Sets this engine’s tags to additionally include the ones provided in tags.

Tags can be used to cheaply enable or disable network rules with a corresponding $tag option.

pub fn disable_tags(&mut self, tags: &[&str])

Sets this engine’s tags to no longer include the ones provided in tags.

Tags can be used to cheaply enable or disable network rules with a corresponding $tag option.

pub fn tag_exists(&self, tag: &str) -> bool

Checks if a given tag exists in this engine.

Tags can be used to cheaply enable or disable network rules with a corresponding $tag option.

pub fn use_resources(&mut self, resources: impl IntoIterator<Item = Resource>)

Sets this engine’s resources to be only the ones provided in resources.

pub fn add_resource( &mut self, resource: Resource, ) -> Result<(), AddResourceError>

Sets this engine’s resources to additionally include resource.

pub fn hidden_class_id_selectors( &self, classes: impl IntoIterator<Item = impl AsRef<str>>, ids: impl IntoIterator<Item = impl AsRef<str>>, exceptions: &HashSet<String>, ) -> Vec<String>

If any of the provided CSS classes or ids could cause a certain generic CSS hide rule (i.e. { display: none !important; }) to be required, this method will return a list of CSS selectors corresponding to rules referencing those classes or ids, provided that the corresponding rules are not excepted.

exceptions should be passed directly from UrlSpecificResources.

pub fn url_cosmetic_resources(&self, url: &str) -> UrlSpecificResources

Returns a set of cosmetic filter resources required for a particular url. Once this has been called, all CSS ids and classes on a page should be passed to hidden_class_id_selectors to obtain any stylesheets consisting of generic rules (if the returned generichide value is false).

pub fn set_regex_discard_policy( &mut self, new_discard_policy: RegexManagerDiscardPolicy, )

Trait Implementations

impl Default for Engine

fn default() -> Self

Equivalent to Engine::new(true).