DNR 转换器

将块式过滤规则转换成规则的 TypeScript 库 与 Chrome 兼容 申报网请求(DNR) API (英语). 它是为开发者设计的 构建需要翻译现有的 AdGuard 浏览器扩展 或其他将过滤列表添加到现代 Chrome 所需的 DNR 格式 扩展.

• 关键概念
  • 支持的规则类型
• 安装
  • 同伴依赖关系
• API 概览
  • IFilter
  • Filter
  • ConverterOptions
  • 简单流程 : FilterConverter + 键 Ruleset
  • 高级流量 : FilterConverter 与 withSourceMap: true + 键 RulesetWithSourceMap
  • 压缩规则集文件格式
  • MetadataRuleset
  • isSafeRule(rule)
  • DNR_CONVERTER_VERSION
  • 网络规则类型
• 国 际
  • 图标
  • 程序化 API
• 文档

关键概念

• 过滤器 —— 以对象表示的块状过滤列表 id 财务报告和审定财务报表 文本 content,每个过滤列表(如AdGuard Base, EasyList)成为一个 Filter 输入.
• 声明规则 a 包括: chrome.declarativeNetRequest.Rule 浏览器对象 本土评价。 转换器从过滤文本中生成这些.
• 来源地图 ——从每个产生的宣告规则回溯到它的 初始过滤器和规则索引, 当声明时允许反向查找 规则火灾.
• 规则安全 -克罗姆 分类 DNR 规则 作为 保险 (路障,允许, 允许所有请求, 升级计划) 或 不安全 (重定向,修改标题). 这个 库显示一个帮助检查安全性的人.
• 转换器选项 控制转换输出的限制和路径 (最大规则计数,重定向的资源路径).

支持的规则类型

转换器支持几乎所有的块状网络规则修饰. 已知者 MV3限制(声明网请求 API 的固有)为:

支持的修改符 (带有MV3注释):

• 基本封锁/允许规则, $third-party, (中文(简体) ), $domain (无正则说明 / .* TLDs),所有内容类型($script, (中文(简体) ), $image, (中文(简体) ), $stylesheet页:1
• $important, (中文(简体) ), $match-case, (中文(简体) ), $method, (中文(简体) ), $to, (中文(简体) ), $denyallow, (中文(简体) ), $header (无正弦值), $all
• $redirect ——不支持允许列表规则
• $csp, (中文(简体) ), $removeparam, (中文(简体) ), $removeheader, (中文(简体) ), $permissions ——许可规则 未支持;条件相同的规则只在 相同的过滤器, 不跨过滤器
• $urltransform ——有限度;复杂变换产生多种声明 通过管道阶段的规则
• $cookie ——有限;只支持无参数(空) $cookie(中文(简体) )
• $badfilter - 部分:不处理 $domain 正确的相交点

尚未支持/ 不可转换为 DNR数字 :

• $popup, (中文(简体) ), $redirect-rule, (中文(简体) ), $referrerpolicy ——尚未执行
• $replace, (中文(简体) ), $jsonprune, (中文(简体) ), $xmlprune, (中文(简体) ), $hls, (中文(简体) ), $network, DNS 修改器($client, (中文(简体) ), $dnsrewrite, (中文(简体) ), $dnstype, (中文(简体) ), $ctag· 不可在国防情报局中表示 转换出错并被跳过
• 例外修改符 $jsinject, (中文(简体) ), $stealth, (中文(简体) ), $urlblock, (中文(简体) ), $genericblock —— 说 尚未执行
• $webrtc - 贬值和不支持

关于带有输出的详细转换示例,参见 转换示例。 。 。 .

安装

# pnpm
pnpm install @adguard/dnr-converter

# yarn
yarn add @adguard/dnr-converter

# npm
npm install @adguard/dnr-converter

同伴依赖关系

软件包需要 @adguard/re2-wasm (单位:千美元)1.2.0)作为regex验证的对等依赖.

API 概览

图书馆使用单曲 FilterConverter 分类 两种转换模式 选择 withSourceMap 选项 :

IFilter

import type { IFilter } from '@adguard/dnr-converter';

两种转换流所使用的单一接口 :

Filter

唯一的混凝土 IFilter 由库运出的执行支持两个 构造模式 :

• 预装 (单位:千美元)new Filter(id, content: string))——接受过滤文本 直接作为字符串. getContent() 1. 立即作出决定; unloadContent() 是个禁忌 用于简单的转换或当内容已经在内存中时.

• 懒惰 (单位:千美元)new Filter(id, source: () => Promise<string>)(b) —— 接受按要求获取内容的自动调用。 支持承诺 双向调用者之间的重复,以及 unloadContent() 释放 缓存内容 。 使用方式 withSourceMap: true (先进模式).

import { Filter } from '@adguard/dnr-converter';

// Pre-loaded (simple mode)
const filter = new Filter(1, '||example.com^');

// Lazy-loaded (advanced mode with withSourceMap: true)
const lazyFilter = new Filter(1, async () => fetchFilterText());

ConverterOptions

import type { ConverterOptions } from '@adguard/dnr-converter';

转换进程的配置 :

简单流程 : FilterConverter + 键 Ruleset

仅在需要时使用此流量 DeclarativeRule[] 从纯过滤器输出 文本,没有源地图或懒惰的加载.

import { FilterConverter, Filter } from '@adguard/dnr-converter';

const filter = new Filter(1, '||example.com^\n@@||example.com/path^');

const converter = new FilterConverter();
const [{ ruleset, errors, limitations }] = await converter.convert([filter]);

console.log(ruleset.getDeclarativeRules()); // DeclarativeRule[]
console.log(ruleset.getSafeRulesCount());    // 2
console.log(errors.length);                 // 0

将多个过滤器合并为一个规则集 :

const [{ ruleset }] = await converter.convert(
    [filter1, filter2],
    { combine: true },
);
// ruleset.getId() === FilterConverter.COMBINED_RULESET_ID

序列化和恢复 :

const json = ruleset.serialize();   // JSON string of DeclarativeRule[]

const { Ruleset } = await import('@adguard/dnr-converter');
const restored = Ruleset.deserialize(ruleset.getId(), json);

Ruleset (默认返回,无) withSourceMap() 执行 IRuleset数字 :

高级流量 : FilterConverter 与 withSourceMap: true + 键 RulesetWithSourceMap

当您需要源地图时, 在浏览器扩展内部使用此模式 , $badfilter 跨过滤器应用程序,有散列地图的序列化,以及懒惰 内容加载。 过 withSourceMap: true 选项中 RulesetWithSourceMap 结果.

import { Filter, FilterConverter } from '@adguard/dnr-converter';

const filter = new Filter(1, async () => '||example.com^\n@@||example.com/path^');

const converter = new FilterConverter();
const [{ ruleset, errors }] = await converter.convert([filter], { withSourceMap: true });

const declarativeRules = await ruleset.getDeclarativeRules(); // Promise<DeclarativeRule[]>
const sources = await ruleset.getRulesById(declarativeRules[0].id);
console.log(sources[0].sourceRule); // '||example.com^'

应用 $badfilter 从动态过滤器对静态规则集:

const [{ ruleset: dynamicRuleset }] = await converter.convert(
    [dynamicFilter],
    { withSourceMap: true },
);
const rulesToDisable = await converter.computeRulesToDisable(
    [dynamicRuleset],
    [staticRuleset],
);
// rulesToDisable: UpdateStaticRulesOptions[]

RulesetWithSourceMap (返回时) withSourceMap: true() 执行 IRulesetWithSourceMap数字 :

import type { ConversionResult } from '@adguard/dnr-converter';

通过转换器方法返回结果 :

压缩规则集文件格式

serializeCompact() 财务报告和审定财务报表 MetadataRuleset.serialize() 写入 JSON 数组 DNR规则。 数组从一个或多个开始 元数据规则: 块规则 谁 condition.urlFilter 实值 dummy.rule.adguard.com (他们从不匹配) 要求),以及 metadata 值为 { "chunk": "<fragment>" }合并 按数组顺序排列的片段给出了序列元数据。 每个 metadata 值,包括JSON出逃和包装,最多为65 536 UTF-8 字节: Edge Add-ons 拒绝值较大的软件包. 寻常 申报规则遵循元数据规则.

元数据规则被标记识别 urlFilter 一、导 言 metadata 键。 主机的转换规则 dummy.rule.adguard.com 无 metadata 键是一个普通规则.

元数据规则是静态的 DNR 规则:它们数到静态规则 获得规则中任何其他规则没有使用的最小ID. 普通的ID是永远不变的.

[
    { "id": 1, "action": { "type": "block" }, "condition": { "urlFilter": "dummy.rule.adguard.com", "resourceTypes": ["xmlhttprequest"] }, "metadata": { "chunk": "{\"metadata\":{...},\"lazyMetadata\":{...},\"filterCon" } },
    { "id": 2, "action": { "type": "block" }, "condition": { "urlFilter": "dummy.rule.adguard.com", "resourceTypes": ["xmlhttprequest"] }, "metadata": { "chunk": "tent\":\"||example.com^\"}" } },
    { "id": 1234567, "action": { "type": "block" }, "condition": { "urlFilter": "||example.com^" } }
]

读取过滤规则集文件 parseCompactRuleset()数字 :

import { Filter, parseCompactRuleset, RulesetWithSourceMap } from '@adguard/dnr-converter';

const content = parseCompactRuleset('ruleset_1', JSON.parse(fileText));
content.metadata;           // SerializedRulesetData
content.lazyMetadata;       // SerializedRulesetLazyData
content.filterContent;      // original filter text
content.declarativeRules;   // ordinary DNR rules, without the metadata rules
content.metadataRulesCount; // number of metadata rules, for static rule quota accounting

// Build the rule set directly from the parsed content.
const ruleset = RulesetWithSourceMap.fromCompact('ruleset_1', content, [new Filter(1, content.filterContent)]);

fromCompact() 验证 metadata 和懒惰的元数据 第一次负载的普通规则, 其计划与 RulesetWithSourceMap.deserialize()。规则集保留解析内容 一生的记忆; unloadContent() 不释出它.

当这些部件作为字符串存储时, 例如在索引数据库中, 加载它们 懒地与 deserialize() 并用 fromDeserialized(), (中文(简体) ), 传递存储 metadataRulesCount数字 :

const ruleset = RulesetWithSourceMap.fromDeserialized(
    await RulesetWithSourceMap.deserialize(id, rawData, loadLazyData, loadDeclarativeRules, filters),
    metadataRulesCount,
);

读者只接受领先的元数据规则,加入它们 解析一次结果。 它会扔 InvalidMetadataChunksError (带有 rulesetId 属性),当输入不是数组时,没有导线 元数据规则, 有没有字符串的元数据规则 chunk,或当 合并的碎片无效.

MetadataRuleset

import { MetadataRuleset, METADATA_RULESET_ID } from '@adguard/dnr-converter';

用于存储校验和和额外属性的专门规则集 收集 DNR 规则集。 它的序列化在 紧凑规则文件格式: JSON 阵列 仅包含元数据规则 { checksums, additionalProperties } 内 metadata.chunk 碎片.

METADATA_RULESET_ID 是常数 0;规则的字符串ID总是 "ruleset_0"。 。 。 .

校验和方法 :

额外财产方法:

序列化 :

const meta = new MetadataRuleset();
meta.setChecksum('ruleset_1', 'abc123');
meta.setAdditionalProperty('version', '2.0');

const json = meta.serialize();
const restored = MetadataRuleset.deserialize(json);

console.log(restored.getChecksum('ruleset_1')); // "abc123"
console.log(restored.getAdditionalProperty('version')); // "2.0"

isSafeRule(rule)

import { isSafeRule } from '@adguard/dnr-converter';

// DeclarativeRule from the DNR API
const rule = {
    id: 2,
    priority: 1,
    action: { type: 'block' },
    condition: { urlFilter: 'example.com' },
};

isSafeRule(rule); // true — "block" is a safe action

回返 true 如果声明规则的行为是 安全规则行动 (单位:千美元)block, (中文(简体) ), allow, (中文(简体) ), allowAllRequests, (中文(简体) ), upgradeScheme) (中文(简体) ). 用于分离安全静态规则 需要额外审查的不安全动态规则.

DNR_CONVERTER_VERSION

import { DNR_CONVERTER_VERSION } from '@adguard/dnr-converter';

console.log(DNR_CONVERTER_VERSION); // e.g. "0.0.1"

带有当前库版本的字符串常数 .

网络规则类型

与网络规则解析和验证有关的包输出类型 :

import {
    Rule,
    HttpHeaderMatcher,
    RuleDeclarativeValidator,
} from '@adguard/dnr-converter';

• Rule — 解析了域,资源访问器的网络规则 类型、方法、高级修改值、优先级和选项标记. 通过 Rule.createFromText(filterListId, index, text)。 。 。 .
• HttpHeaderMatcher - 描述解析过的类型 $header 修改 数值.
• RuleDeclarativeValidator 静态助手,检查是否 Rule 可转换为 DNR 规则。 打电话 RuleDeclarativeValidator.shouldConvertRule(rule) ——返回 true 如果规则是可兑换的, false 如果它被悄悄地跳过, 或掷出 UnsupportedModifierError 如果规则使用不支持 修饰相.

国 际

货包船a dnr-converter 用于转换过滤器的命令行工具 列表到 DNR 规则,并从编译的规则中提取过滤器内容.

图标

convert

将元目录中的 AdGuard 过滤列表转换为 DNR 规则 .

dnr-converter convert \
  ./filters \
  ./resources \
  ./dist/rulesets

参数 :

选项 :

这个 filters.json 元数据文件必须是一系列过滤元数据对象 最少每个 filterId 财务报告和审定财务报表 name 字段.

extract-filters

提取嵌入编译的 DNR 规则的原始过滤列表内容 编辑 convert 命令.

dnr-converter extract-filters \
  ./dist/rulesets \
  ./extracted-filters

参数 :

程序化 API

CLI逻辑也可以通过下列程序作为API提供: @adguard/dnr-converter/cli 子路径导出 :

import { convertFilters, generateMD5Hash, type ConvertFiltersOptions } from '@adguard/dnr-converter/cli';

await convertFilters(
    './filters',
    './resources',
    './dist/rulesets',
    { debug: true, prettifyJson: true },
);

文档

• 更改日志
• 发展
• 从 surlfilter 迁移
• 转换示例
• LLM 代理规则