README has unsaved pending edits...

This commit is contained in:
Raymond Hill 2021-08-06 08:29:13 -04:00
parent 4495c37ca3
commit af54415959
No known key found for this signature in database
GPG Key ID: 25E1490B761470C2
2 changed files with 50 additions and 38 deletions

View File

@ -16,7 +16,8 @@ This package uses [native JavaScript modules](https://developer.mozilla.org/en-U
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 for large lists of hostnames.
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](https://easylist.to/),
[uBlock filters](https://github.com/uBlockOrigin/uAssets/tree/master/filters),
@ -39,47 +40,58 @@ 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:
async function main() {
// Initialize the internal Public Suffix List database, which is necessary
// for the filtering engine to assess whether a network request is
// 3rd-party to the context from which it is fired.
await pslInit();
```js
await pslInit();
```
// Feed EasyList and EasyPrivacy to the filtering engine. A list is
// an object exposing the property `raw`, which contains the raw text of
// the filter lists.
const snfe = await useRawLists([
fetch('easylist').then(raw => ({ name: 'easylist', raw })),
fetch('easyprivacy').then(raw => ({ name: 'easyprivacy', raw })),
]);
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):
// Reuse a single instance of filtering context used for matching
const fctxt = new FilteringContext();
```js
const snfe = await useRawLists([
fetch('easylist').then(raw => ({ name: 'easylist', raw })),
fetch('easyprivacy').then(raw => ({ name: 'easyprivacy', raw })),
]);
```
// Tests
// 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());
}
`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:
// 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());
}
```js
const fctxt = new FilteringContext();
```
// 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());
}
Now we are ready to match network requests:
```js
// 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());
}
```

View File

@ -1,6 +1,6 @@
{
"name": "@gorhill/ubo-core",
"version": "0.1.4",
"version": "0.1.5",
"description": "To create a working instance of uBlock Origin's static network filtering engine",
"type": "module",
"main": "index.js",