AdGuard Diff Builder

A tool for generating differential updates for filter lists.

Contents

- Prerequisites
- How to Install
- How to Use
- CLI
- API
- Algorithm Overview

Prerequisites

- [Node.js] v18.13.0 or higher.

- diff utility — this tool relies on the standard Unix diff utility to generate patches efficiently.
Make sure it's installed on your system:
- On macOS: Available by default or through XCode CLI tools.
- On Linux: Available by default or install via your package manager (e.g., apt-get install diffutils).
- On Windows: Available via WSL or Git Bash.

[Node.js]: https://nodejs.org/en/download

How to Install

``bash
pnpm add @adguard/diff-builder
`

How to Use

CLI

`bash
diff-builder build [-c] [-d ] [-r ] [-v] -n -t
`

Where:

- — the relative path to the old filter.
- — the relative path to the new filter.
- — the relative path to the directory with patches.
- -n or --name= — name of the patch file, an arbitrary string to identify the patch.
Must be a string of length 1-64 with no spaces or other special characters.
- -r or --resolution= — is an optional flag,
that specifies the resolution for both expirationPeriod and epochTimestamp (timestamp when the patch was generated).
Possible values:
- h — hours (used if resolution is not specified)
- m — minutes
- s — seconds
- -t or --time= — expiration time for the diff update
(the unit depends on resolution parameter).
- -d or --delete-older-than-sec= — an optional parameter,
this time in seconds will be used when scanning the folder to remove patches,
which not empty and whose created epoch timestamp is older than the specified time.
By default, it will be 604800 (7 days).
- -v or --verbose — verbose mode.
- -c or --checksum — an optional flag, indicating whether it should calculate the SHA sum for the filter
and add it to the diff directive with the filter name and the number of changed lines,
following this format: diff name:[name] checksum:[checksum] lines:[lines]:
- name — the name of the corresponding filter list.
This key-value pair is optional — it will be included only if there is a Diff-Name tag in the .
- checksum — the expected SHA1 checksum of the file after the patch is applied.
This is used to validate the patch.
- lines — the number of lines that follow, making up the RCS diff block.
Note that lines are counted using the same algorithm as used by wc -l, essentially counting \n.

Algorithm Overview

$3

- Resolve absolute paths for the old and new filters and the patches directory.

$3

- Ensure the patches directory exists, creating it if necessary.

$3

- Delete any outdated patches from the patches directory except empty patches.

$3

- Read and split the old and new filter files into lines.
- Check if there are significant changes between the two sets of lines, excluding 'Diff-Path' and 'Checksum' tags.

$3

- If no significant changes are found, revert any changes in the new filter and exit.

$3

- Generate a new patch name and validate its uniqueness.
- Update the 'Diff-Path' tag in the new filter.
- Create a diff patch between the old and new filters.
- Optionally, add a checksum to the patch.

$3

- Write the updated new filter back to its file.
- Create an empty patch file for future use if necessary.
- Save the diff patch to the appropriate file.

API

$3

`javascript
const { DiffBuilder } = require('@adguard/diff-builder');
const { DiffUpdater } = require('@adguard/diff-builder/diff-updater');

await DiffBuilder.buildDiff({
oldFilterPath,
newFilterPath,
patchesPath,
name,
time,
resolution,
verbose: true,
});

const updatedFilter = await DiffUpdater.applyPatch({
filterUrl,
filterContent,
verbose: true,
});
`

$3

`javascript
import { DiffBuilder } from '@adguard/diff-builder/es';
import { DiffUpdater } from '@adguard/diff-builder/diff-updater/es';

await DiffBuilder.buildDiff({
oldFilterPath,
newFilterPath,
patchesPath,
name,
time,
resolution,
verbose: true,
});

const updatedFilter = await DiffUpdater.applyPatch({
filterUrl,
filterContent,
verbose: true,
});
``