brave/adblock-rust: Brave's adblock engine as a Rust and Node library

What adblock-rust actually solves, and for whom

The README is blunt about the scope: this is "the engine powering Brave's native adblocker, available as a library for anyone to use." It is not a browser extension, not a proxy, and not a subscription service. It is the component that takes filter list text and answers the question "should this request be blocked?" plus the follow-up question "which page elements should be hidden?"

The audience follows from that. The README states the crate is used in browsers, research tools and proxies. If you are writing any of those and you do not want to reimplement Adblock Plus filter syntax, this is the piece you would otherwise spend months on. The feature list covers network blocking, cosmetic filtering, resource replacements, hosts syntax, uBlock Origin syntax extensions, and conversion to Apple's content-blocking format for iOS and macOS.

What it does not include matters just as much. There is no filter list in the repository's top level, no subscription URL baked into the API, and no user interface. You bring the lists. That is a deliberate boundary, and it is the first thing to understand before evaluating anything else.

How the engine is put together: parsing, matching, and two output paths

The data flow visible in the repository is a pipeline. Filter list text goes in, rules are parsed into an internal representation, and the resulting engine answers queries about URLs and about page elements. The Cargo.toml dependencies hint at what that parsing involves: regex, idna for internationalized domain names, percent-encoding, base64, seahash and rustc-hash for fast lookups, arrayvec for small stack-allocated collections, and flatbuffers, which points at serialization of a compiled engine.

That compiled form is worth noting. The examples directory contains deserialization.rs, generate-dat.rs and use-dat.rs, which suggests a workflow where an engine built from filter lists is serialized to disk and loaded later rather than rebuilt from text on every start. For a browser shipping lists to millions of users, that distinction is the difference between a slow first run and a fast one.

Feature flags change the pipeline substantially. With css-validation enabled, the crate pulls in selectors and cssparser to reject cosmetic rules whose CSS is invalid. With content-blocking enabled, rules can be converted into Apple's content-blocking format for export. With resource-assembler enabled, it parses scriptlet and redirect resources from the file formats used by the uBlock Origin repository. Each flag adds dependencies, and the README frames them as a way to "tweak adblock-rust to best fit your use-case" rather than as defaults you should leave on.

Installing adblock-rust and blocking your first URL

There are two supported bindings, and the choice depends on your host language. For Rust, the crate is named adblock on crates.io. For Node, the package is adblock-rs, and its package.json declares a postinstall script that runs npm run build-release, which in turn invokes cargo-cp-artifact to compile the native module into index.node. That means a Node install requires a working Rust toolchain on the machine doing the install, not just npm.

For Rust, the README points to docs.rs for the API reference and to examples/example.rs for a worked example. Add the dependency first:

cargo add adblock

The README does not print a minimal Rust snippet, so read examples/example.rs for the exact call sequence rather than guessing at method names. For Node, the README points at js/example.mjs:

npm install adblock-rs
node js/example.mjs

What you should see, based on the example files being runnable programs, is an engine constructed from a filter list, then a query against a URL. The repository also ships helper scripts for list management: npm run update-lists runs data/update-lists.js and npm run fetch-live-lists runs data/fetch-live-lists.js. Those are development conveniences in the repository, not part of the published package contract.

One configuration decision comes up immediately. The single-thread feature is enabled by default and the README says it "enables optimizations for rule matching speed and the amount of memory used by the engine." Disabling it makes the engine Send + Sync, but the README still recommends accessing the engine on a single thread "to maintain optimal performance." If your architecture spreads request checks across a thread pool, you are choosing between synchronization and the default fast path.

Where adblock-rust will disappoint you

The most consequential limitation is stated plainly in the README's feature list: the crate is a library, and the README's own framing is that it may be "a good fit for yours, too" for projects like browsers, research tools and proxies. Nothing in the README describes list downloading, subscription refresh, disk caching policy, or a UI. If you expected an engine that keeps itself current, it does not exist here.

Thread safety is the second constraint. The default build is optimized for single-threaded access. Disabling that feature is described as making the engine Send + Sync, with a performance caveat attached. There is no documented middle ground such as a sharded engine per thread, so the trade-off is yours to design around.

Domain resolution is the third. By default the crate embeds a resolver through the addr crate with the psl feature. The README says this "will generally suffice for standalone use-cases" and that disabling embedded-domain-resolver lets you supply your own, which it describes as useful "to reduce binary bloat and improve consistency when embedding adblock-rust within a browser." That wording implies the built-in resolver's results may differ from a browser's own public suffix handling. If your host application already has an opinion about what a registrable domain is, using two implementations is a source of subtle mismatches.

Finally, the Python bindings on pypi are labeled community-maintained in the README. That is a different support level from the Rust and JS bindings, and it should shape whether you build on them.

adblock-rust against uBlock Origin: engine versus product

The comparison people reach for is uBlock Origin, and the honest answer is that they are not the same category of thing. uBlock Origin is a finished browser extension with its own filter lists, its own settings UI, and a release cadence tied to browser extension stores. adblock-rust is the matching layer that a host application calls into.

The overlap is in syntax. The README lists uBlock Origin syntax extensions as a supported feature, and the resource-assembler feature parses "the file formats used by the uBlock Origin repository" for scriptlet injection and redirect rules. So the rule language is largely compatible even though the delivery is not.

If you are choosing for yourself as a user, adblock-rust is not the answer to your question; you install an extension or use a browser that embeds it. If you are choosing as an implementer, the relevant question is whether you want to own the surrounding product. adblock-rust gives you the engine and leaves the rest to you, which is more work and more control. That is the actual difference in approach: uBlock Origin packages the engine with a product, adblock-rust packages the engine alone.

Licence and the cost of keeping up

adblock-rust is MPL-2.0. The Mozilla Public License is file-level copyleft: modifications to files already under the licence generally have to be published under the same terms, while larger works that combine it with other code are treated differently. This is not legal advice, and the exact boundary matters if you are shipping a closed-source product that links the crate. Read the LICENSE file in the repository and get counsel if the answer affects your business.

The upgrade cost is a different question, and the repository gives some signals. Cargo.toml pins the Rust edition to 2024 and pins several dev-dependencies to exact versions with the equals syntax, including criterion, csv, mock_instant and sha2. The engine depends on a long list of crates, among them regex, idna, serde, serde_json, flatbuffers and bitflags. Each of those is a surface you inherit when you upgrade.

There is also a serialization compatibility question that the README does not address. Since the crate uses flatbuffers and the examples include deserialization, any persisted engine format presumably has to stay readable across versions. The README does not document a format version guarantee or a migration path. If you plan to ship compiled engines to clients, that is a gap you should test before you depend on it. The CHANGELOG.md at the repository root is where release notes would live, and it is the file to read before bumping the version.

Editorial conclusion

Adopt adblock-rust if you are building a browser, proxy or research tool and want the matching engine rather than a finished blocker: it is a library, so you supply the filter lists, the storage and the request interception. Do not adopt it if you want a browser extension you can install and forget, or if you need a supported Python API, since the README calls the pypi bindings community-maintained. Before committing, verify three things: whether the single-thread feature is acceptable for your threading model, whether you want the built-in domain resolver or will disable embedded-domain-resolver, and how you will ship updated filter lists to users, because the README describes no update mechanism.

Frequently asked questions

Official sources

1. brave/adblock-rust on GitHub
2. Issues
3. License: MPL-2.0
4. README