@adguard/dnr-converter 1.1.2 → 2.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +674 -0
- package/README.md +75 -5
- package/dist/cli.cjs +694 -179
- package/dist/errors/metadata-errors/invalid-metadata-chunks-error.js +23 -0
- package/dist/index.js +2 -0
- package/dist/package.json.js +144 -2
- package/dist/ruleset/compact-ruleset.js +32 -0
- package/dist/ruleset/metadata-chunks.js +178 -0
- package/dist/ruleset/metadata-rule.js +100 -28
- package/dist/ruleset/metadata-ruleset.js +23 -31
- package/dist/ruleset/ruleset-with-source-map.js +135 -46
- package/dist/types/src/errors/metadata-errors/invalid-metadata-chunks-error.d.ts +21 -0
- package/dist/types/src/index.d.ts +2 -0
- package/dist/types/src/ruleset/compact-ruleset.d.ts +52 -0
- package/dist/types/src/ruleset/metadata-ruleset.d.ts +10 -6
- package/dist/types/src/ruleset/ruleset-with-source-map.d.ts +120 -3
- package/dist/types/src/version.d.ts +6 -0
- package/dist/utils/string.js +1 -1
- package/dist/version.js +11 -2
- package/package.json +9 -11
package/README.md
CHANGED
|
@@ -27,6 +27,7 @@ extensions.
|
|
|
27
27
|
- [`ConverterOptions`](#converteroptions)
|
|
28
28
|
- [Simple flow: `FilterConverter` + `Ruleset`](#simple-flow-filterconverter--ruleset)
|
|
29
29
|
- [Advanced flow: `FilterConverter` with `withSourceMap: true` + `RulesetWithSourceMap`](#advanced-flow-filterconverter-with-withsourcemap-true--rulesetwithsourcemap)
|
|
30
|
+
- [Compact ruleset file format](#compact-ruleset-file-format)
|
|
30
31
|
- [`MetadataRuleset`](#metadataruleset)
|
|
31
32
|
- [`isSafeRule(rule)`](#issaferulerule)
|
|
32
33
|
- [`DNR_CONVERTER_VERSION`](#dnr_converter_version)
|
|
@@ -274,8 +275,11 @@ const rulesToDisable = await converter.computeRulesToDisable(
|
|
|
274
275
|
| `getRulesById(id)` | `Promise<SourceRuleAndFilterId[]>` | Source rules for a DNR rule |
|
|
275
276
|
| `getBadFilterRules()` | `NetworkRule[]` | `$badfilter` rules in this set |
|
|
276
277
|
| `getRulesHashMap()` | `IRulesHashMap` | Hash map for fast `$badfilter` matching |
|
|
277
|
-
| `
|
|
278
|
+
| `getMetadataRulesCount()` | `number` | Metadata rules in the ruleset file the rule set was read from (0 if not read from a file) |
|
|
279
|
+
| `serializeCompact(unsafeRules, prettyPrint?)` | `Promise<string>` | Ruleset file in the [compact ruleset file format](#compact-ruleset-file-format) |
|
|
278
280
|
| `unloadContent()` | `void` | Release lazy-loaded content |
|
|
281
|
+
| `RulesetWithSourceMap.fromCompact(id, content, filters)` | `RulesetWithSourceMap` | Build a rule set from `parseCompactRuleset()` output |
|
|
282
|
+
| `RulesetWithSourceMap.fromDeserialized(deserialized, metadataRulesCount)` | `RulesetWithSourceMap` | Build a rule set from `RulesetWithSourceMap.deserialize()` output |
|
|
279
283
|
|
|
280
284
|
```ts
|
|
281
285
|
import type { ConversionResult } from '@adguard/dnr-converter';
|
|
@@ -290,6 +294,71 @@ Result returned by converter methods:
|
|
|
290
294
|
| `limitations` | `LimitationError[]` | Warnings about exceeded limits |
|
|
291
295
|
| `declarativeRulesToCancel` | `UpdateStaticRulesOptions[]?` | Static rule IDs to disable (from `computeRulesToDisable`) |
|
|
292
296
|
|
|
297
|
+
### Compact ruleset file format
|
|
298
|
+
|
|
299
|
+
`serializeCompact()` and `MetadataRuleset.serialize()` write a JSON array of
|
|
300
|
+
DNR rules. The array starts with one or more **metadata rules**: block rules
|
|
301
|
+
whose `condition.urlFilter` is `dummy.rule.adguard.com` (they never match a
|
|
302
|
+
request) and whose `metadata` value is `{ "chunk": "<fragment>" }`. Joining
|
|
303
|
+
the fragments in array order gives the serialized metadata. Every `metadata`
|
|
304
|
+
value, including JSON escaping and the wrapper, is at most 65,536 UTF-8
|
|
305
|
+
bytes: Edge Add-ons rejects packages with larger values. The ordinary
|
|
306
|
+
declarative rules follow the metadata rules.
|
|
307
|
+
|
|
308
|
+
A metadata rule is recognized by the marker `urlFilter` together with the
|
|
309
|
+
`metadata` key. A converted rule for the host `dummy.rule.adguard.com`
|
|
310
|
+
without a `metadata` key is an ordinary rule.
|
|
311
|
+
|
|
312
|
+
Metadata rules are static DNR rules: they count towards the static rule
|
|
313
|
+
quota and get the smallest IDs not used by any other rule of the ruleset.
|
|
314
|
+
Ordinary rule IDs are never changed.
|
|
315
|
+
|
|
316
|
+
```json
|
|
317
|
+
[
|
|
318
|
+
{ "id": 1, "action": { "type": "block" }, "condition": { "urlFilter": "dummy.rule.adguard.com", "resourceTypes": ["xmlhttprequest"] }, "metadata": { "chunk": "{\"metadata\":{...},\"lazyMetadata\":{...},\"filterCon" } },
|
|
319
|
+
{ "id": 2, "action": { "type": "block" }, "condition": { "urlFilter": "dummy.rule.adguard.com", "resourceTypes": ["xmlhttprequest"] }, "metadata": { "chunk": "tent\":\"||example.com^\"}" } },
|
|
320
|
+
{ "id": 1234567, "action": { "type": "block" }, "condition": { "urlFilter": "||example.com^" } }
|
|
321
|
+
]
|
|
322
|
+
```
|
|
323
|
+
|
|
324
|
+
Read a filter ruleset file with `parseCompactRuleset()`:
|
|
325
|
+
|
|
326
|
+
```ts
|
|
327
|
+
import { Filter, parseCompactRuleset, RulesetWithSourceMap } from '@adguard/dnr-converter';
|
|
328
|
+
|
|
329
|
+
const content = parseCompactRuleset('ruleset_1', JSON.parse(fileText));
|
|
330
|
+
content.metadata; // SerializedRulesetData
|
|
331
|
+
content.lazyMetadata; // SerializedRulesetLazyData
|
|
332
|
+
content.filterContent; // original filter text
|
|
333
|
+
content.declarativeRules; // ordinary DNR rules, without the metadata rules
|
|
334
|
+
content.metadataRulesCount; // number of metadata rules, for static rule quota accounting
|
|
335
|
+
|
|
336
|
+
// Build the rule set directly from the parsed content.
|
|
337
|
+
const ruleset = RulesetWithSourceMap.fromCompact('ruleset_1', content, [new Filter(1, content.filterContent)]);
|
|
338
|
+
```
|
|
339
|
+
|
|
340
|
+
`fromCompact()` validates `metadata` at once and the lazy metadata and
|
|
341
|
+
ordinary rules on first load, with the same schemas as
|
|
342
|
+
`RulesetWithSourceMap.deserialize()`. The rule set keeps the parsed content
|
|
343
|
+
in memory for its whole lifetime; `unloadContent()` does not release it.
|
|
344
|
+
|
|
345
|
+
When the parts are stored as strings, for example in IndexedDB, load them
|
|
346
|
+
lazily with `deserialize()` and build the rule set with `fromDeserialized()`,
|
|
347
|
+
passing the stored `metadataRulesCount`:
|
|
348
|
+
|
|
349
|
+
```ts
|
|
350
|
+
const ruleset = RulesetWithSourceMap.fromDeserialized(
|
|
351
|
+
await RulesetWithSourceMap.deserialize(id, rawData, loadLazyData, loadDeclarativeRules, filters),
|
|
352
|
+
metadataRulesCount,
|
|
353
|
+
);
|
|
354
|
+
```
|
|
355
|
+
|
|
356
|
+
The reader takes only the leading run of metadata rules, joins them and
|
|
357
|
+
parses the result once. It throws `InvalidMetadataChunksError` (with a
|
|
358
|
+
`rulesetId` property) when the input is not an array, has no leading
|
|
359
|
+
metadata rule, has a metadata rule without a string `chunk`, or when the
|
|
360
|
+
joined fragments are not valid JSON.
|
|
361
|
+
|
|
293
362
|
### `MetadataRuleset`
|
|
294
363
|
|
|
295
364
|
```ts
|
|
@@ -297,9 +366,10 @@ import { MetadataRuleset, METADATA_RULESET_ID } from '@adguard/dnr-converter';
|
|
|
297
366
|
```
|
|
298
367
|
|
|
299
368
|
A specialized ruleset that stores checksums and additional properties for a
|
|
300
|
-
collection of DNR rule sets. It serializes
|
|
301
|
-
|
|
302
|
-
|
|
369
|
+
collection of DNR rule sets. It serializes in the
|
|
370
|
+
[compact ruleset file format](#compact-ruleset-file-format): a JSON array
|
|
371
|
+
that contains only metadata rules carrying `{ checksums, additionalProperties }`
|
|
372
|
+
in `metadata.chunk` fragments.
|
|
303
373
|
|
|
304
374
|
`METADATA_RULESET_ID` is the constant `0`; the ruleset's string ID is always
|
|
305
375
|
`"ruleset_0"`.
|
|
@@ -327,7 +397,7 @@ carrier within serialized ruleset files (never matches real requests).
|
|
|
327
397
|
| Method | Returns | Description |
|
|
328
398
|
| --- | --- | --- |
|
|
329
399
|
| `serialize(pretty?)` | `string` | JSON string; `pretty=true` for human-readable output |
|
|
330
|
-
| `MetadataRuleset.deserialize(json)` | `MetadataRuleset` | Reconstruct from a serialized string; throws on invalid
|
|
400
|
+
| `MetadataRuleset.deserialize(json)` | `MetadataRuleset` | Reconstruct from a serialized string; throws `SyntaxError` on invalid JSON, `InvalidMetadataChunksError` on malformed metadata rules, a validation error on a bad payload |
|
|
331
401
|
|
|
332
402
|
```ts
|
|
333
403
|
const meta = new MetadataRuleset();
|