@adguard/dnr-converter 1.1.1 → 2.0.0-beta.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/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
- | `serializeCompact(unsafeRules, prettyPrint?)` | `Promise<string>` | Compact JSON serialization |
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 as a single-element JSON array
301
- containing a declarative rule with a `metadata` field, acting as a data
302
- carrier within serialized ruleset files (never matches real requests).
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 input |
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();