Content Classifier Service

The Content Classifier Service (toolkit/components/content-classifier/) is the anti-tracking component that classifies network channels against adblock-format filter lists delivered through Remote Settings. It is a parallel classification path layered alongside the older URL Classifier and its safebrowsing-format hash tables: same set of features (trackers, social trackers, fingerprinters, cryptominers, email trackers, plus allow-list/exception features and dedicated test_block / test_annotate features), but driven by full adblock syntax rules evaluated by a Rust engine wrapping the adblock crate.

This page is a reference for how the service is wired up internally: where list bytes live, how they get turned into engines, how a channel classification request flows through it, and which invariants the code depends on.

Components

File

Role

nsIContentClassifierService.idl

XPCOM contract surfaced to JS: onListsChanged(updated, removed), getFeatureNames(), and the test-only NS_CONTENT_CLASSIFIER_FILTER_LISTS_LOADED_TOPIC observer notification that fires after every rebuild.

nsIContentClassifierRemoteSettingsClient.idl

JS-side contract: init, shutdown, getListBytes(listName).

ContentClassifierService.{h,cpp}

The singleton C++ service. Owns the feature table, the per-feature engine map, the four mode-keyed active-engine lists, the mutex, pref/Nimbus observers, async-shutdown blocker, and the build thread.

ContentClassifierRemoteSettingsClient.sys.mjs

Wraps the content-classifier-lists Remote Settings collection. Owns the on-disk attachment cache, registers a sync listener, and pulls bytes on demand.

content_classifier_engine/ (Rust crate)

Wraps the adblock crate (v0.12.1, full-regex-handling + single-thread features) behind a small FFI: engine_from_rules, check_network_request_preparsed, engine_destroy, plus init/teardown for an nsIEffectiveTLDService-backed domain resolver.

ContentClassifierEngine.{h,cpp}

Thread-safe refcounted C++ wrapper around the Rust FFI engine. Extracts request metadata from an nsIChannel-derived ContentClassifierRequest and calls into Rust.

components.conf, moz.build

Component registration and build setup (cbindgen generates content_classifier_ffi.h).

Features and prefs

The static kFeatures[] table (ContentClassifierService.cpp) is the single source of truth for which feature names exist, which Remote Settings list IDs roll up into each feature’s engine, and how matches are reported to the channel. Each entry carries:

  • mName — the identifier used in prefs.

  • mListIds — one or more Remote Settings record names whose attachments are concatenated into the feature’s engine rules.

  • mClassificationFlag — the nsIClassifiedChannel::ClassificationFlags bit set on the channel for an annotation match.

  • mLoadedState / mReplacedState / mAllowedState — nsIWebProgressListener STATE_LOADED_* / STATE_REPLACED_* / STATE_ALLOWED_* values logged into the content blocking log. mLoadedState == 0 denotes an annotate-without-notify feature.

  • mBlockingErrorCode — NS_ERROR_*_URI passed to UrlClassifierCommon::SetBlockedContent for a cancellation; NS_OK means the feature has no blocking variant and is only ever an annotation.

  • mExceptionOnly — true if the feature contains only allowlist / exception rules. This means it must be last in a list of features. A console warning will yell at you for this.

Enable switches (per mode):

  • privacy.trackingprotection.content.protection.enabled

  • privacy.trackingprotection.content.annotation.enabled

Feature selection (comma-separated feature names):

  • privacy.trackingprotection.content.protection.engines

  • privacy.trackingprotection.content.protection.engines.pbmode

  • privacy.trackingprotection.content.annotation.engines

  • privacy.trackingprotection.content.annotation.engines.pbmode

Test-only lists fetched over HTTP (used by the test_block / test_annotate features so tests don’t need a live Remote Settings collection):

  • privacy.trackingprotection.content.protection.test_list_urls

  • privacy.trackingprotection.content.annotation.test_list_urls

All of the above prefs are mapped onto Nimbus feature variables in toolkit/components/nimbus/FeatureManifest.yaml.

Threading model

Three thread types appear in this code, and the rebuild and classify paths both deliberately move work between them:

  • Main thread. All init, pref observers, Remote Settings sync callbacks, and final channel-side decisions (MaybeCancelChannel, MaybeAnnotateChannel) run here.

  • mBuildThread (an nsISerialEventTarget task queue, created in Init). The CPU-heavy half of an engine rebuild runs here: Engine::from_rules calls (the actual adblock parser) happen with no lock held, and the lock-protected InstallEngine / PopulateAllActiveEnginesFromPreferenceSnapshot / PruneInactiveEngines steps run here too, just briefly under mLock.

  • URL-classifier worker thread. ClassifyForCancel and ClassifyForAnnotate run here, called from netwerk/url-classifier/AsyncUrlChannelClassifier.cpp. Both acquire mLock briefly to snapshot the active-engine list pointer and then release it before crossing the FFI.

The mozilla::Mutex mLock is non-recursive. Reacquiring it while already held will deadlock the calling thread. The header enforces this by:

  • Marking mInitPhase, mEngines, mFeatureVersions, mUpdateGeneration, and the four active-engine arrays as MOZ_GUARDED_BY(mLock).

  • Annotating InstallEngine, PopulateAllActiveEnginesFromPreferenceSnapshot, and PruneInactiveEngines with MOZ_REQUIRES(mLock).

  • Releasing mLock before any call into the engine FFI (so a long classification cannot stall a rebuild and vice versa).

You may be tempted to use a RWLock. This will give you less than you think because we really only have one classifying thread. Worse yet, I don’t remember if the engine lookup is threadsafe.

List load and engine rebuild

A rebuild is triggered by any of:

  • Initial InitRSClient() (first time the service sees an active RS feature).

  • A Remote Settings sync push (onSync in the JS client).

  • A pref change: master enable, an engines selection pref, or one of the test_list_urls prefs.

onListsChanged(updated, removed) on the main thread calls ProcessListChanges, which takes a fresh EnginesPrefsSnapshot of the current pref state, walks the active features named in that snapshot, and selects every feature that either has no engine yet or whose mListIds overlap updated ∪ removed. That set goes to UpdateFeatures.

UpdateFeatures (main thread) bumps mUpdateGeneration (global) and the per-feature mFeatureVersions entry for every feature it’s about to rebuild — both under mLock. It then fires FetchEngineDataForFeature to get the rule lists. The MozPromise<> returned by each fetch is collected via MozPromise::AllSettled; when all of them resolve, the collected rule arrays plus the captured generation and per-feature versions are dispatched onto mBuildThread.

On mBuildThread, with no lock held, we build the rule engines.

The same mBuildThread task then reacquires mLock and performs the install / populate / prune step under it:

  • For each freshly built engine, compare the captured per-feature version to the current mFeatureVersions entry. If a newer rebuild has been issued since this one was dispatched, the captured version is stale and the engine is dropped on the floor. Otherwise it’s stored into mEngines via InstallEngine.

  • After all installs, compare the captured mUpdateGeneration to the current one. Only if it’s still the latest do we run PopulateAllActiveEnginesFromPreferenceSnapshot (rebuild the four per-mode active-engine arrays from mEngines, in pref order) and PruneInactiveEngines (drop entries from mEngines not referenced by any active-engine array).

This versioning-and-recheck pattern is the safety invariant for concurrent rebuilds: two rebuilds racing through mBuildThread can never have the older one’s snapshot overwrite the newer one’s results, because the older one’s captured generation no longer matches by the time it tries to commit.

Finally a small task is dispatched back to the main thread to fire NS_CONTENT_CLASSIFIER_FILTER_LISTS_LOADED_TOPIC (test-only, gated on the privacy.trackingprotection.content.testing pref), which is how the browser tests await rebuild completion. These need to be debounced.

Channel classification

A channel classification request enters from netwerk/url-classifier/AsyncUrlChannelClassifier.cpp on the URL-classifier worker thread. The caller has already constructed a ContentClassifierRequest on the main thread that extracts the URL, the schemeless site and source schemeless site (via nsIEffectiveTLDService), the request type (mapped from ExtContentPolicyType to an adblock type string), the third-party flag (via mozIThirdPartyUtil), and the PBM flag.

ClassifyForCancel and ClassifyForAnnotate both acquire mLock, pick the appropriate active-engine array based on PBM and mode, and call ClassifyWithEngines. The lock is released before returning the result.

ClassifyWithEngines takes an aIndependentEngines flag that controls how engine evaluation chains:

  • Cancel (aIndependentEngines = false). Threads a matchedSoFar flag through every CheckNetworkRequest call so exception-only engines see the propagated matched_rule. Stops iterating when the aggregated status reaches ImportantHit or ImportantException — either of those pins the outcome and further engines can’t change it — but otherwise continues so a trailing exception can still demote an earlier hit.

  • Annotate (aIndependentEngines = true). Each engine sees previously_matched_rule = false, so each evaluates its own rules in isolation and MaybeAnnotateChannel can attribute matches to every feature whose rules fired.

ContentClassifierEngine::CheckNetworkRequest short-circuits to a Miss for first-party requests before crossing the FFI. For genuine third-party requests, it builds the preparsed request fields once and calls content_classifier_engine_check_network_request_preparsed. The Rust side constructs an adblock::Request via Request::preparsed, calls Engine::check_network_request_subset(req, previously_matched_rule, false), and writes back matched, important, and an optional exception rule string.

Each per-engine result is folded into a ContentClassifierResult via Accumulate. The status enum is ordered (Miss < Hit < Exception < ImportantHit < ImportantException), and Accumulate promotes monotonically: any Exception promotes the aggregate over a Hit, and any Important value pins the status against later non-Important results. Really, the status enum only matters for annotation.

The worker thread dispatches the result back to the main thread, which then calls either MaybeCancelChannel (consults ChannelClassifierUtils::IsAllowListed, finds the first matched feature whose mBlockingErrorCode is non-NS_OK, hands off to ChannelClassifierUtils::MaybeBlockChannel) or MaybeAnnotateChannel (iterates the engine-result list and calls ChannelClassifierUtils::AnnotateChannel for each matched feature with a non-zero mLoadedState, applying the feature’s classification flag and loaded state to the channel).