3.1 KiB
uBlock Origin Core
The core filtering engines used in the uBlock Origin ("uBO") extension, and has no external dependencies.
Installation
Install: npm install --save @gorhill/ubo-core
This is a very early version and the API is subject to change at any time.
This package uses native JavaScript modules.
Description
The package contains uBO's static network filtering engine ("SNFE"), which purpose is to parse and enforce filter lists. The matching algorithm is highly efficient, and especially optimized to match against large sets of pure hostnames.
The SNFE can be fed filter lists from a variety of sources, such as EasyList/EasyPrivacy, uBlock filters, and also lists of domain names or hosts file format (i.e. block lists from The Block List Project, Steven Black's HOSTS, etc).
Usage
At the moment, there can be only one instance of the static network filtering engine, which API must be imported as follow:
import { FilteringContext, pslInit, useRawLists } from '@gorhill/ubo-core';
If you must import as a NodeJS module:
const { FilteringContext, pslInit, useRawLists } await import from '@gorhill/ubo-core';
uBO's SNFE works best with a properly initialized Public Suffix List database, since it needs to evaluate whether a network request to match is either 1st- or 3rd-party to the context in which it is fired:
await pslInit();
Now feed the SNFE with filter lists -- useRawLists()
accepts an array of
objects (or promises to object) which expose the raw text of a list
through the raw
property, and optionally the name of the list through the
name
property (how you fetch the lists is up to you):
const snfe = await useRawLists([
fetch('easylist').then(raw => ({ name: 'easylist', raw })),
fetch('easyprivacy').then(raw => ({ name: 'easyprivacy', raw })),
]);
useRawLists()
returns a reference to the SNFE, which you can use later to
match network requests. First we need a filtering context instance, which is
required as an argument to match networkrequests:
const fctxt = new FilteringContext();
Now we are ready to match network requests:
// Not blocked
fctxt.setDocOriginFromURL('https://www.bloomberg.com/');
fctxt.setURL('https://www.bloomberg.com/tophat/assets/v2.6.1/that.css');
fctxt.setType('stylesheet');
if ( snfe.matchRequest(fctxt) !== 0 ) {
console.log(snfe.toLogData());
}
// Blocked
fctxt.setDocOriginFromURL('https://www.bloomberg.com/');
fctxt.setURL('https://securepubads.g.doubleclick.net/tag/js/gpt.js');
fctxt.setType('script');
if ( snfe.matchRequest(fctxt) !== 0 ) {
console.log(snfe.toLogData());
}
// Unblocked
fctxt.setDocOriginFromURL('https://www.bloomberg.com/');
fctxt.setURL('https://sourcepointcmp.bloomberg.com/ccpa.js');
fctxt.setType('script');
if ( snfe.matchRequest(fctxt) !== 0 ) {
console.log(snfe.toLogData());
}