Linkumori runtime architecture

How Linkumori works inside the browser: what runs where, how rules are loaded, and what happens to a request. It is written for people changing the code. The rule format itself is in filter-syntax.md; building and linting rules are in CONTRIBUTING.md.

File and function names are given so you can jump to the code. Line numbers are not, because they move.

1Overview

Linkumori is a Manifest V3 Firefox extension (desktop 140+, Android 142+). It has three kinds of runtime code:

There is no server. The only network requests Linkumori makes on its own are for remote rule lists, and only when the user configures them (§5.2).

Open full sizeOpen full size

Diagram source

Copy

flowchart LR
    subgraph Browser
        WR[webRequest events] --> BG
        NAV[webNavigation events] --> BG
        subgraph BG[Background page]
            ST[storage.js<br/>settings + rule loading]
            EN[clearurls.js<br/>engine]
            OT[history, context menu,<br/>DNS, whitelist, ETag,<br/>badge, log, watchdog]
        end
        PG[Extension pages<br/>popup, settings, editor, log, …] <-- runtime messages --> BG
        BG -- scripting.executeScript --> TAB[Web page]
        CS[Content scripts<br/>Google / Yandex link fix] --> TAB
    end
    BG <-- browser.storage.local --> DISK[(Storage)]
    BG -. optional .-> REMOTE[Remote rule list + hash]

2The background page

All background scripts are classic scripts in one global scope. They call each other's functions directly (pureCleaning(), getData(), isWhitelisted(), …), so load order matters: a script may only call another script's functions at runtime, never while loading, unless that script is listed earlier.

consent_config.js loads last, but genesis() reads its values only after an asynchronous storage read, so they are defined by then.

Main globals

Keeping the page alive

Firefox can suspend an MV3 background event page when it is idle. tools.js calls browser.runtime.getPlatformInfo every 20 seconds (keepAlive) so the page, its in-memory storage and its compiled providers stay loaded.

3Startup

storage.js calls genesis() once all background scripts have loaded:

Open full sizeOpen full size

Diagram source

Copy

sequenceDiagram
    participant G as genesis()
    participant L as browser.storage.local
    participant P as Public Suffix List
    participant R as loadBundledRules()
    participant E as start() (clearurls.js)
    G->>L: get(null)
    L-->>G: all saved keys
    G->>G: initStorage(): defaults, then setData() for each saved key
    G->>G: consumePostReloadOpenUrl()
    G->>P: initLinkumoriPublicSuffixList()
    G->>R: load and merge rules (§5)
    R-->>G: storage.ClearURLsData
    G->>E: startClearurlsIfConsentGranted()
    G->>G: changeIcon(), contextMenuStart(), historyListenerStart()

If rule loading fails, the same last four steps still run.

Consent gate

Cleaning only starts once the user has accepted the current privacy policy, the current POSAR version and the adult confirmation:

• consent_config.js sets Linkumoriversion and LinkumoriPOSARversion.
• hasPopupConsentForStartup() compares them with the accepted versions in storage (popupConsentPolicyVersionAccepted, popupConsentPOSARVersionAccepted, popupConsentAdultAccepted).
• Until they match, start() is not called, so there are no providers and no webRequest listener. The ETag filter and History API cleaning are registered at load time, so they check isCleaningStarted() and do nothing before then. The context menu is also created, but with no providers it copies links unchanged.
• Accepting in the popup or on legal.html writes those keys. A storage.onChanged listener in storage.js sees them and starts cleaning without a restart.
• When the policy version is raised, earlier consent no longer counts: cleaning does not start, and legal.html opens.

On first install, storage.js opens html/legal.html?source=first_install.

start()

start() in clearurls.js:

1. starts Public Suffix List support (initPslSupport) and requestContextManager;
2. calls tryInitialize(), which builds the providers from storage.ClearURLsData and registers the webRequest listener. If no rules are loaded yet, it retries every 200 ms, up to 50 times, then registers the listener anyway;
3. calls setBadgedStatus().

It also defines globalThis.updateProviderData(), which rebuilds the providers from storage.ClearURLsData without a restart (§5.5).

4Settings and persistence

storage is an in-memory object holding every setting. It is the source of truth while the extension runs; browser.storage.local is its saved copy.

• Defaults: initSettings() sets every default. Remote rules, logging, ETag filtering, redirect bypass and the search link fix start off. Built-in rules, CNAME uncloaking, domain blocking, ping blocking, the History API listener and the context menu start on.
• Loading and writing: setData(key, value) normalises each key as it loads or changes: JSON strings are parsed, booleans coerced, remote URLs validated. It also migrates renamed keys (globalurlcounter becomes totalCounter) and drops obsolete ones.
• Saving: saveOnDisk(keys) writes keys now. deferSaveOnDisk(key) queues a key and writes the queue one minute later (the deferSaveOnDisk alarm); counters and the log use this, because they change on every request. saveOnExit() writes everything.
• Changes made elsewhere: some modules also listen to storage.onChanged, for keys that pages write straight to browser.storage.local:
  • globalStatus and the theme update the toolbar icon;
  • contextMenuEnabled rebuilds the context menu;
  • searchLinkFixEnabled registers or removes the content scripts;
  • the consent keys start cleaning (§3).

Keys that shape the runtime:

The interface language is not in storage: the language selector in settings writes linkumori_language to browser.storage.sync, and external_js/linkumori-i18n.js reads it on every page. Left unset, the browser's language is used.

5Rule loading

loadBundledRules() in storage.js decides which rule sources to use, merges them with the custom rules, and stores the result in storage.ClearURLsData.

5.1Sources

5.2Remote rules

Remote rules are off by default. Each source is a pair of URLs, and both must be valid (areValidRemoteURLsPresent(), isValidRuleURL()).

1. Fetch the hash URL: 32–128 hex characters (fetchRemoteHash).
2. Fetch the rule URL, and check that the SHA-256 of the raw text matches (fetchRemoteRules, verifyRulesHash). A mismatch rejects the source.
3. Parse it as Linkumori JSON with a providers object.

Both requests use cache: 'no-store', so the rules and their hash always come from the same moment. Sources are fetched in parallel. The ones that pass are merged (mergeRemoteRulesSources): providers with the same pattern and settings become one provider (getProviderGroupKey, mergeRemoteProviderGroup). The result is saved as remoteRulescache.

Within a merged provider, two rules count as the same when everything that changes what they do matches, targetId, order and historyBypassProtection included (getStableRuleSignature). Only one is kept, and the other's id and aliases become aliases of it. An inactive provider adds nothing to its group, and a provider-level historyBypassProtection is copied onto its rules, since the merged provider can hold only one.

Each source is checked for rule collisions (LinkumoriRuleIds.findRuleCollisions), and so is each merge, for the collisions merging creates. A merge is also checked for the same text in rules from one file and referralMarketing from another (LinkumoriRuleIds.findReferralTextCollisions). They are logged and shown in settings, and the rules still load.

The outcome of every attempt is recorded in remoteRulesHealth, which settings shows.

Capabilities. When a remote file loads, resolveRemoteFileCapabilities records what its entries can do (LinkumoriRuleIds.deriveRuleFileCapabilities) in remoteRuleCapabilities. strip, rewrite and except are active at once; redirect and block stay off for that file until the user accepts them in Remote Rules Health, which calls acceptRemoteRuleCapabilities and reloads the remote rules. Entries that need a capability the file lacks are left out (restrictRuleFileCapabilities). Without redirect, every raw rule is kept but tagged _linkumoriNoRedirect: a raw rule can take the URL to another scheme, host or port by a rewrite or just by deleting text, which only shows when it runs, so rawRuleMayChangeOrigin() in clearurls.js then leaves such a URL unchanged. The verified cache can't be traced to one file, so when it loads, strip, rewrite and except are active and redirect and block only if every configured file has accepted them (getCapabilitiesAcceptedByAllRemoteFiles). See CLN 1.0 §Remote file capabilities.

5.3Choosing the sources

Open full sizeOpen full size

Diagram source

Copy

flowchart TD
    A[loadBundledRules] --> B{built-in off<br/>and remote off?}
    B -- yes --> C[custom rules only]
    B -- no --> D{remote sources<br/>configured and valid?}
    D -- no --> E{built-in on?}
    E -- yes --> F[bundled LZ4]
    E -- no --> C
    D -- yes --> G[fetch + verify every source]
    G -- at least one passed --> H{overload mode?}
    H -- yes --> I{overload strategy}
    I -- patch-only --> I1[bundled rules + remote patches]
    I -- patch-and-merge --> I2[remote merged with bundled,<br/>then patched]
    I -- merge-only --> I3[remote merged with bundled,<br/>patches skipped]
    H -- no --> J[remote]
    G -- all failed --> K{verified cache<br/>for these sources?}
    K -- yes --> L[cached remote<br/>+ bundled in overload mode]
    K -- no --> E2{built-in on?}
    E2 -- yes --> F
    E2 -- no --> C
    F -- LZ4 fails --> M[remote cache, else last<br/>ClearURLsData, else fallback list]
    I1 & I2 & I3 & J & L & F & M --> N[mergeCustomRules]
    C --> O[ClearURLsData]
    N --> O

Rule patches. A remote file's patches (see filter syntax §Rule patches) are applied by applyRemoteRulePatches() to the rules chosen above, just before mergeCustomRules, including when the remote cache is used. With overload mode on, overloadModeStrategy selects patch-only (use bundled rules as the base and omit remote providers), patch-and-merge (merge remote and bundled providers, then apply patches), or merge-only (merge providers and skip patches). With overload mode off, the strategy is ignored and existing remote rule behavior applies. When every loaded remote file holds only patches, the base is the bundled rules, unmerged so their provider names stay (withPatchOnlyBuiltInRules). Each patch's result (applied, unmatched or skipped) is stored in remoteRulesHealth.rulePatches.

hashStatus records which path was taken, for example bundled_rules_loaded, remote_verified, remote_rules_partially_merged, cache_remote_rules_after_remote_failure or fallback_rules_used. When custom rules are merged in, it gets a custom variant, such as custom_rules_merged.

5.4Merging custom rules

mergeCustomRules(baseRules) builds the final list:

1. Providers the user switched off (customrules_import_exclusions) are removed from both the base rules and the custom rules.
2. Providers without urlPattern or domainPatterns are dropped.
3. A custom provider replaces every base provider with the same pattern (the same urlPattern, or the same domainPatterns in any order), whatever their methods, resourceTypes, completeProvider and forceRedirection (getProviderPatternOnlyGroupKey). Their rules are not combined. Overload mode still merges built-in and remote providers only when the pattern and all four settings match (§5.2). Switching a provider off (step 1) uses the pattern-only key too (isProviderSignatureDisabled), so it removes every provider with that pattern.
4. Other custom providers are added. A name already in use gets _1, _2, ….
5. Every provider goes through attachProviderActivationIds(): each rule gets its activation ids (_linkumoriActivationIds) and, if its id changed, its old ids (_linkumoriLegacyRuleIds); see §6.2.
6. The result is saved as ClearURLsData, with dataHash (SHA-256 of a key-sorted serialisation) and mergeStats.

5.5When rules reload

Rules are loaded at startup, and again only when:

• the custom rules editor saves, or settings asks for a refresh (reloadCustomRules() / refreshRemoteRulesNow()). These call updateProviderData(), so the new rules apply without a restart;
• the extension restarts (reload(), used by some settings and by the watchdog).

Nothing refreshes remote rules on a timer.

6The engine (clearurls.js)

6.1Providers

createProviders() turns every provider in ClearURLsData into a Provider object:

• its match pattern (domainPatterns, or urlPattern plus indexPattern);
• its compiled rule lists: field rules, raw rules, referral-marketing rules, $removeparam filters and their @@ exceptions, exceptions, redirections, field redirections;
• its methods and resourceTypes.

Rules that fail to compile, or use an option the engine does not accept, are skipped. The custom rules editor and lint-rules report such rules before they are saved.

6.2Rule ids and switched-off rules

Every rule has an id: its own id, or one generated by LinkumoriRuleIds from its list and text (see filter-syntax.md: Rule objects). The engine, storage.js, the custom rules editor and the CLI all use core_js/linkumori_rule_ids.js, so they always produce the same ids.

A rule can be switched off in two ways; both are stored in clearurls_disabled_rule_ids:

While providers are built, attachCoreRuleIdentity() gives each rule its ids, and filterCoreRuleActivationIds() drops the switched-off ones.

A setting saved under an old id also counts, and is then moved to the current id (migrateCoreRuleAliasActivationIds). Old ids come from two places:

• the rule's aliases (after a rename);
• its legacy ids, which it gets after its generated id changed.

A generated id changes with the rule's text, so the first switch-off of a rule without an id fixes it (core_js/linkumori_rule_pins.js). The editor writes the id onto a custom rule; for a rule from a built-in or remote list it stores a pin in clearurls_rule_id_pins: { provider, section, generatedId, sourceListId, fingerprintAtToggle, disableKeys }. createProviders() matches each provider's pins to its current rules (same text, same generated id, or text at least 80% alike, resolveProviderPins) and gives a matched rule the pinned id, activation ids included (applyCoreRulePin). A switched-off rule that has no pin yet (switched off before pins existed) gets one, and a pin matched to drifted text remembers it as lastSeenText. Pins that match no rule are listed in clearurlsProviderSnapshot.rulePins.orphaned, which the editor shows as Orphaned toggles.

The result is published as clearurlsProviderSnapshot (via getData), which the editor's Disabled rules page lists.

6.3Finding the providers for a URL

Checking every provider against every URL would be slow, so the engine indexes providers by hostname token:

• Providers. Each provider registers in providersByToken under the main label of each of its domainPatterns. A urlPattern provider uses its indexPattern instead. The main label is the one just before the public suffix: ||amazon.*^ and ||smile.amazon.co.uk^ both register under amazon (getLookupTokens).
• Requests. getHostnameLookupTokens(host) returns every label of the request host, so www.amazon.co.uk looks up www, amazon, co and uk, and finds the amazon providers.
• Global providers. Some providers are in globalProviders and are checked against every URL:
  • a urlPattern provider without indexPattern (which is why lint-rules warns about it);
  • a provider with a /regex/ domain pattern.

6.4Cleaning a request

The webRequest.onBeforeRequest listener (blocking) covers <all_urls> and the request types in types + pingRequestTypes. It records tab and frame URLs for requestContextManager, skips data: URLs, and calls clearUrl(request):

Open full sizeOpen full size

Diagram source

Copy

flowchart TD
    A[request] --> B{paused?}
    B -- yes --> Z[let it through]
    B -- no --> C{whitelisted?<br/>request or its page}
    C -- yes --> Z
    C -- no --> D{cleaning on?}
    D -- no --> Z
    D -- yes --> E{ping or beacon,<br/>ping blocking on?}
    E -- yes --> X[cancel]
    E -- no --> F[collect @@ $removeparam exceptions<br/>from providers matching the page]
    F --> G[candidates: providers indexed under<br/>the request host + global providers]
    G --> H{next candidate matches<br/>method, type, URL?}
    H -- no more --> Y{CNAME uncloaking?}
    H -- yes --> I[removeFieldsFormURL]
    I -- redirect --> R[redirect, or navigate the tab<br/>if forceRedirection]
    I -- block --> K[main frame: siteBlockedAlert page<br/>other: redirect to javascript:void 0]
    I -- changed --> M[redirect to the cleaned URL]
    I -- unchanged --> H
    Y -- decision for the CNAME --> R2[same decision,<br/>mapped back to the original host]
    Y -- none --> Z

The first provider that redirects, blocks or changes the URL decides the result. A redirect is a new request, so the cleaned URL goes through clearUrl() again. The browser keeps the requestId across redirects, so clearUrl() counts the cycles of each request and stops after LINKUMORI_MAX_CLEANING_CYCLES (10), unless unbounded mode (unboundedCyclesEnabled) is on, and an entry with a replacePattern rewrites at most once per request (Termination). pureCleaning() (clipboard, context menu, rule tester) loops the same way, with the same cap (shouldRunAnotherCleaningCycle). In unbounded mode no browser stops a redirect loop there, so it also stops when the URL comes back to one it already produced.

A provider's exceptions are checked while matching the URL (matchRequestURL), so an excepted URL never reaches the next step. removeFieldsFormURL(provider, url, …) then applies the provider in the order described in filter-syntax.md: Processing order:

1. It skips local hosts (localHostsSkipping).
2. redirections and fieldRedirections apply (only while redirection is on). A target that isn't an absolute http or https URL makes the entry not match (getLinkumoriRedirectTarget(), Redirect targets).
3. completeProvider blocks the request (only while domain blocking is on).
4. The ordered cleaning steps run (getOrderedCleaningSteps()): raw rules on the URL text, then field rules and referral-marketing rules on query and fragment parameters. Inside each stage, entries with an order come first, lowest first; then by array (rules, flagged rules, referralMarketing) and array position (Run order). The provider keeps every definition by group and text and resolves them once, in finalizeRules(): the last definition wins and inherits the first one's place (Same text twice). Parameters already handled by a $removeparam filter are left to that filter.
5. $removeparam filters run, minus their @@ exceptions and the exceptions collected from the page's providers. @@ entries are checked against the URL the provider received, before its raw rules ran.

It logs each change and updates the badge unless called in quiet mode.

6.5CNAME uncloaking

If no provider made a decision, and CNAME uncloaking is on, LinkumoriDNS.replayCNAMEIfNeeded() (linkumori_dns.js) checks whether the request host is an alias:

• It asks browser.dns.resolve(host, ['canonical_name']). Answers are cached for 10 minutes, up to 512 hosts.
• It skips page loads (main_frame), non-HTTP(S) URLs, IP addresses, proxied requests, and (by default, cnameIgnoreRootDocument) requests to the page's own host.
• A CNAME within the same registrable domain (a.example.com → b.example.com) counts as no CNAME.
• It runs clearUrl() again on the URL with the canonical host. Unless cnameReplayFullURL is on, that URL keeps only the host and drops the path and query.
• If that produces a block or a redirect, the decision is returned with the original hostname put back.

6.6Request context

Some decisions depend on the page a request comes from:

• @@ exceptions, which also cover requests made by a page the provider matches;
• domain=, first-party and third-party options;
• whitelists, which also cover subresources of a whitelisted page.

requestContextManager.collectContextURLs(request) returns every URL that can stand for that page:

• the request's documentUrl, originUrl, initiator and referrer;
• the tab's URL, kept up to date from tabs.onUpdated and webNavigation.onCommitted;
• the URLs of the frame's ancestor frames.

6.7Public Suffix List

initPslSupport() loads data/public_suffix_list.dat into linkumoriPsl. The engine uses it for:

• hostname tokens (§6.3);
• ||example.*^ patterns, which match any public suffix;
• first-party and third-party, which compare registrable domains.

If it fails to load, hostname tokens fall back to plain labels, .* patterns (in rules and in the whitelist) stop matching, and first-party / third-party compare full hostnames instead of registrable domains.

7Other cleaning paths

7.1pureCleaning(url)

pureCleaning() (pureCleaning.js) cleans a URL outside webRequest. It runs every provider over the URL until it stops changing. It does not use the token index, and there is no request, so options that depend on the request (party, method) do not apply. For request types the URL counts as main_frame (getLinkumoriRequestType()), the page a link opens: a rule or $removeparam filter limited to other types is skipped, and one limited to main_frame applies. It is used by:

• the Copy clean link context menu, which injects clipboard-helper.js and copies the result (context_menu.js);
• History API cleaning (§7.2);
• the Cleaning tool page, over messaging;
• the watchdog (§9).

runRuleTestLab() and pureCleaningTrace() use the same loop, but record which provider and rule changed what. The custom rules editor's test lab shows this trace. traceClearURLWebRequestTest() does the same through the real clearUrl() for the regression page.

7.2History API

webNavigation.onHistoryStateUpdated (historyListener.js) fires when a page changes its own URL with pushState or replaceState. The listener:

1. does nothing before cleaning has started (§3), and skips the URL if it is paused or whitelisted, including the History API whitelist and the temporary tab whitelist;
2. cleans it with pureCleaning(url, false, true), where rules with historyBypassProtection: false do not run;
3. if the URL changed, runs history.replaceState(null, "", cleanUrl) in the frame with scripting.executeScript.

7.3Search link fix (content scripts)

content_script_manager.js registers two content scripts with scripting.registerContentScripts, and only while searchLinkFixEnabled is on (default off). They run at document_end in all frames:

• google_link_fix.js on Google search domains stops Google from rewriting result links into tracking redirects;
• yandex_link_fix.js does the same on Yandex.

The registration is refreshed on install, on browser start, and when the setting changes.

7.4ETag filtering

eTagFilter.js registers a blocking webRequest.onHeadersReceived listener with responseHeaders. While eTagFiltering is on (default off), it replaces the value of each ETag response header with a random value of the same form, so the ETag cannot be used as a tracking id. It does nothing before cleaning has started (§3), and skips local hosts, whitelisted requests, and paused cleaning.

8Whitelists and pausing

Whitelist entries are hostname patterns (example.com also covers its subdomains) or IP addresses (matchWhitelistHostnamePattern). The popup adds and removes entries over messaging.

9Counters, badge, log and watchdog

• Counters: increaseTotalCounter counts parameters seen and increaseCleanedCounter counts cleanings, while statistics are on. Both are saved with deferSaveOnDisk.
• Badge: increaseBadged(request) (badgedHandler.js) counts cleanings per tab and shows the number on the toolbar button. The count resets when the tab's URL changes. Whitelisted requests never count.
• Log: while logging is on, pushToLog() (tools.js) appends an entry to storage.log.log:
  • the entry holds the URL before and after, the rule, the provider and pattern, the request type and method, the tab, and any CNAME;
  • the log keeps at most logLimit entries (default 100, never more than 5000), dropping the oldest;
  • it is saved one minute later (deferSaveOnDisk);
  • each entry also goes straight to every open log page, over a runtime.connect port named linkumori-logger.
• Watchdog: every minute (alarm watchdog), watchdog.js cleans https://linkumori.com?utm_source=addon and checks that the result has no utm_source. It only runs while cleaning is on, consent is given, nothing is paused and a rule source is enabled. On failure it increases watchDogErrorCount and reloads the extension, at most twice in a row. A success resets the count.

10Messaging between the pages and the background

Pages call the background with:

browser.runtime.sendMessage({ function: 'getData', params: ['globalStatus'] })

handleMessage() (message_handler.js) always answers with a promise of { response, error? }.

The allowlist covers:

• whitelist changes (addToWhitelist, addToTemporaryTabWhitelist, addToHistoryApiWhitelist, the matching removeFrom…, getHistoryApiWhitelist, getTemporaryTabWhitelistForTab);
• pausing (pauseCleaningTemporarily, pauseCleaningUntilRestart, resumeCleaningNow, getTemporaryPauseState);
• rule information (getRuleSourceInfo, getMergeStatistics, getRemoteRulesHealth, refreshRemoteRulesNow, getRuleDefaultsStatus, which returns each source's defaults, the mode and the user's own and edited blocks);
• remote capabilities (acceptRemoteRuleCapabilities(ruleURL, capabilities), §5.2);
• the custom rules editor's run-order panel (getProviderRunOrder(name, provider, defaults), simulateProviderRunOrder(name, provider, defaults, url, referralAllowed) and generateProviderTestUrl(name, provider, defaults), §11.1);
• cleaning and tests (pureCleaning, runRuleTestLab, traceClearURLWebRequestTest, applyRegressionRuleData, and setPendingRegressionSuite / getPendingRegressionSuite, which hand a suite from settings to regression.html in memory);
• maintenance (storageAsJSON, saveOnExit, initSettings, reload, start, changeIcon, setBadgedStatus).

To add a background function a page can call: define it in a background script, then add its name to the allowlist.

Pages also read and write some keys directly with browser.storage.local: the popup's consent keys, and settings that background listeners watch (§4).

11Extension pages

Every page loads theme_bootstrap.js (themes), linkumori-i18n.js (text), accessibility_tools.js (accessibility options) and usually write_version.js (version footer).

11.1Run-order panel

Under the custom rules editor's JSON editor, the run-order panel lists the provider's rawRules, rules and referralMarketing entries in the order they run, with each step's sort key (stage, orderGroup, order, rank, arrayIndex), followed by its $removeparam filters. It is worked out by the engine, not by the page: on every edit (debounced) the page sends the unsaved provider and the custom rules' defaults to getProviderRunOrder. That function, in clearurls.js, builds the provider the way createProviders() does (fillProvider(), the custom rules' defaults, the user's rule pins), but as a dry run: its rules are not added to the snapshot the rule controls read, and no pin or alias migration is recorded. Provider.describeRunOrder() returns both variants, with referral-marketing rules and without, and marks the steps the user switched off. The panel starts on the variant the user's referral-marketing setting selects.

Steps can be rearranged in the variant that lists every entry, by dragging or with each step's arrow buttons, but only within their stage: raw rules always run before field rules, and the step a completeProvider adds stays where it is. A move gives every step of that stage an order of 10, 20, 30, … in the new sequence, written on the entry that defines the step (the last definition of its text, which describeRunOrder() reports as source). A plain string entry becomes { "matchPattern": …, "order": … }; its generated id comes from the text, so it doesn't change. Each movable step shows its order (or "no order"); while a step is dragged over a drop point, every step of its stage shows the number the drop would give it (order 5 → 20), and the labels go back if the drag is cancelled. Undo move restores the editor text from before the last move, until the user types. Restore order numbers puts every order back as it was when the provider was opened: an entry that had none loses it again (and a { "matchPattern", "order" } object goes back to a plain string), one that had one gets it back, and entries whose text changed since are left alone. It shows only while some order differs.

Simulate runs the provider on a test URL and steps through it: start, previous, play, next and end, with the URL after each step (removed text struck through, added text highlighted, compared by URL part) and the step's row lit in the list. simulateProviderRunOrder(name, provider, defaults, url, referralAllowed) builds the same dry-run provider with the user's switched-off rules, then calls removeFieldsFormURL() with a stepRecorder array that receives the URL before and after every ordered step and after the $removeparam filters. It runs like cleaning a copied link (no request, quiet), pass after pass while the URL changes, within the cycle limit (shouldRunAnotherCleaningCycle), and stops at a redirect or block. Only this provider runs. storage.referralMarketing is set to the panel's choice for the duration of the call and restored; the call is synchronous, so nothing else can read it meanwhile. The simulation runs again after each edit or move.

Generate test URL fills the test URL from the provider's own rules (generateProviderTestUrl(name, provider, defaults)): a host its domainPatterns or urlPattern match, text in the path for each raw rule, a parameter for each rules, referralMarketing and named $removeparam entry, and keep=1, which no rule should remove. Samples come from Regex.Analyzer (external_js/regex_analyzer.js), and each is checked against the rule it is for and against the provider's exceptions; what can't be sampled, or would make an exception match, is left out and listed. Redirects and blocks are left out too, since they would end the run before the other rules. On the 704 bundled providers it makes a matching URL for all but the two whose exceptions cover every URL they match.

11.2Settings page safeguards

settings.js asks before a few risky changes. These checks live in the page only; the background accepts the keys whatever their value.

• Gatekeeper for remote rule addresses. Each of the rule URL, hash URL and remote rule sets fields is checked on its own. A field that had a saved value can be edited without confirmation as long as it isn't emptied. Typing into an empty field, or emptying one, opens a disclaimer, even when the other fields hold saved addresses, and the change is kept only after the user types the confirmation phrase (I accept full responsibility in English; each language has its own). The confirmation lasts until the page is closed and covers every field. The import and export buttons for remote addresses appear only after confirming.
• Disable Gatekeeper (disableGatekeeper) skips that confirmation and shows the import and export buttons. Turning it on opens a risk warning, then the same disclaimer with a phrase of its own. Turning it off needs no confirmation.
• Redirect bypass (redirectionEnabled): turning it on first shows a warning to review the redirect rules of every source; Cancel leaves it off.

12Code shared between the background, pages and CLI

Some logic has to agree between the background, the custom rules editor (which does not load the background scripts) and linkumori-cli-tool.js (Node):

13Build time and runtime

14Things to know

Facts that matter when changing the code:

• Remote rules have no timer. They are fetched at startup and on a manual refresh (§5.5).
• Listeners registered at load time must check consent. Code that listens to browser events outside start() runs whether or not consent is given. Check isCleaningStarted() first, as the ETag filter and the History API listener do.
• Any extension page can read or write any key. getData and setData over messaging accept every key; other function calls are limited to the allowlist (§10). Web pages cannot send these messages.
• The first provider wins. For each request, the first provider that changes, redirects or blocks it decides the result. Provider order comes from the merged ClearURLsData.

Generated from docs/runtime-architecture.md on the main branch. Found a problem? Open an issue.