@gorhill/ubo-core

中文文档
0.1.30发布于 2024/10/07GPL-3.0-or-laterES Module零依赖近 30 天下载 1.1万

To create a working instance of uBlock Origin's static network filtering engine

原始使用文档
文档目录5 节
  1. Installation
  2. Description
  3. Usage
  4. Extras
  5. HNTrieContainer

uBlock Origin Core

The core filtering engines used in the uBlock Origin ("uBO") extension, and has no external dependencies.

Installation

Install: npm install @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

See ./demo.js in package for instructions to quickly get started.

At the moment, there can be only one instance of the static network filtering engine ("SNFE"), which proxy API must be imported as follow:

import { StaticNetFilteringEngine } from '@gorhill/ubo-core';

If you must import as a NodeJS module:

const { StaticNetFilteringEngine } = await import('@gorhill/ubo-core');

Create an instance of SNFE:

const snfe = await StaticNetFilteringEngine.create();

Feed the SNFE with filter lists -- useLists() 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):

await snfe.useLists([
    fetch('easylist').then(r => r.text()).then(raw => ({ name: 'easylist', raw })),
    fetch('easyprivacy').then(r => r.text()).then(raw => ({ name: 'easyprivacy', raw })),
]);

Now we are ready to match network requests:

// Not blocked
if ( snfe.matchRequest({
    originURL: 'https://www.bloomberg.com/',
    url: 'https://www.bloomberg.com/tophat/assets/v2.6.1/that.css',
    type: 'stylesheet'
}) !== 0 ) {
    console.log(snfe.toLogData());
}

// Blocked
if ( snfe.matchRequest({
    originURL: 'https://www.bloomberg.com/',
    url: 'https://securepubads.g.doubleclick.net/tag/js/gpt.js',
    type: 'script'
}) !== 0 ) {
    console.log(snfe.toLogData());
}

// Unblocked
if ( snfe.matchRequest({
    originURL: 'https://www.bloomberg.com/',
    url: 'https://sourcepointcmp.bloomberg.com/ccpa.js',
    type: 'script'
}) !== 0 ) {
    console.log(snfe.toLogData());
}

Once all the filter lists are loaded into the static network filtering engine, you can serialize the content of the engine into a JS string:

const serializedData = await snfe.serialize();

You can save and later use that JS string to fast-load the content of the static network filtering engine without having to parse and compile the lists:

const snfe = await StaticNetFilteringEngine.create();
await snfe.deserialize(serializedData);

Extras

You can directly use specific APIs exposed by this package, here are some of them, which are used internally by uBO's SNFE.

HNTrieContainer

A well optimised compressed trie container specialized to specifically store and lookup hostnames.

The matching algorithm is designed for hostnames, i.e. the hostname labels making up a hostname are matched from right to left, such that www.example.org with be a match if example.org is stored into the trie, while anotherexample.org won't be a match.

HNTrieContainer is designed to store a large number of hostnames with CPU and memory efficiency as a main concern -- and is a key component of uBO.

To create and use a standalone HNTrieContainer object:

import HNTrieContainer from '@gorhill/ubo-core/js/hntrie.js';

const trieContainer = new HNTrieContainer();

const aTrie = trieContainer.createOne();
trieContainer.add(aTrie, 'example.org');
trieContainer.add(aTrie, 'example.com');

const anotherTrie = trieContainer.createOne();
trieContainer.add(anotherTrie, 'foo.invalid');
trieContainer.add(anotherTrie, 'bar.invalid');

// matches() return the position at which the match starts, or -1 when
// there is no match.

// Matches: return 4
console.log("trieContainer.matches(aTrie, 'www.example.org')", trieContainer.matches(aTrie, 'www.example.org'));

// Does not match: return -1
console.log("trieContainer.matches(aTrie, 'www.foo.invalid')", trieContainer.matches(aTrie, 'www.foo.invalid'));

// Does not match: return -1
console.log("trieContainer.matches(anotherTrie, 'www.example.org')", trieContainer.matches(anotherTrie, 'www.example.org'));

// Matches: return 0
console.log("trieContainer.matches(anotherTrie, 'foo.invalid')", trieContainer.matches(anotherTrie, 'foo.invalid'));

The reset() method must be used to remove all the tries from a trie container, you can't remove a single trie from the container.

trieContainer.reset();

When you reset a trie container, you can't use the reference to prior instances of trie, i.e. aTrie and anotherTrie are no longer valid and shouldn't be used following a reset.

版本与发布记录

@gorhill/ubo-core 共发布 29 个版本,首次发布于 2021/08/06;过去 12 个月发布了 0 个版本。

版本发布日期距今
0.1.30latest2024/10/072 年前
0.1.292024/10/072 年前
0.1.282024/10/072 年前
0.1.272024/10/072 年前
0.1.262023/03/163 年前
0.1.252022/03/314 年前

关于 @gorhill/ubo-core 的常见问题

@gorhill/ubo-core 是什么?

To create a working instance of uBlock Origin's static network filtering engine

如何安装 @gorhill/ubo-core?

在项目目录运行 npm install @gorhill/ubo-core,或使用 pnpm add / yarn add / bun add。

@gorhill/ubo-core 支持 TypeScript 吗?

该包的 package.json 没有声明类型入口。需要类型提示时,可以在 npm 上查找社区维护的 @types/gorhill__ubo-core 是否存在。

@gorhill/ubo-core 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@gorhill/ubo-core 需要什么版本的 Node.js?

package.json 的 engines 字段要求 Node.js >=18.0.0。版本不符时 npm 默认只给出警告,开启 engine-strict 后会拒绝安装。

@gorhill/ubo-core 可以商用吗?

@gorhill/ubo-core 使用 GPL-3.0-or-later 许可。强 Copyleft:分发包含该代码的软件时,整个作品需以 GPL-3.0 兼容许可开源,并附带专利与反锁定条款。仅内部使用不触发此义务。以上为概括,不构成法律意见,请以许可原文为准。

@gorhill/ubo-core 的下载量有多少?

根据 npm 官方下载统计,@gorhill/ubo-core 在 2026/10/17 – 2026/11/15 这 30 天内被下载 10,982 次,日均约 366 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@gorhill/ubo-core 还在维护吗?

最新版本 0.1.30 发布于 2024/10/07(2 年前);至今共发布 29 个版本,其中过去 12 个月发布了 0 个;首次发布于 2021/08/06。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。