pub struct Engine { /* private fields */ }
Expand description
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 Resource
s, 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§
source§impl Engine
impl Engine
sourcepub fn new(optimize: bool) -> Self
pub fn new(optimize: bool) -> Self
Creates a new adblocking Engine
. Engine
s 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.
sourcepub fn from_rules(
rules: impl IntoIterator<Item = impl AsRef<str>>,
opts: ParseOptions,
) -> Self
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.
sourcepub fn from_rules_debug(
rules: impl IntoIterator<Item = impl AsRef<str>>,
opts: ParseOptions,
) -> Self
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
sourcepub fn from_filter_set(set: FilterSet, 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.
sourcepub fn serialize_raw(&self) -> Result<Vec<u8>, SerializationError>
pub fn serialize_raw(&self) -> Result<Vec<u8>, SerializationError>
Serializes the Engine
into a binary format so that it can be quickly reloaded later.
sourcepub fn deserialize(
&mut self,
serialized: &[u8],
) -> Result<(), DeserializationError>
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.
sourcepub fn check_network_request(&self, request: &Request) -> BlockerResult
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
sourcepub fn get_csp_directives(&self, request: &Request) -> Option<String>
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.
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.
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.
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.
sourcepub fn tag_exists(&self, tag: &str) -> bool
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.
sourcepub fn use_resources(&mut self, resources: impl IntoIterator<Item = Resource>)
pub fn use_resources(&mut self, resources: impl IntoIterator<Item = Resource>)
Sets this engine’s resources to be only the ones provided in resources
.
sourcepub fn add_resource(
&mut self,
resource: Resource,
) -> Result<(), AddResourceError>
pub fn add_resource( &mut self, resource: Resource, ) -> Result<(), AddResourceError>
Sets this engine’s resources to additionally include resource
.
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
.
sourcepub fn url_cosmetic_resources(&self, url: &str) -> 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).