@tokioapp/adblock 0.0.0-stage → 0.0.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.
Files changed (143) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +68 -2
  3. package/THIRD_PARTY_NOTICES.md +50 -0
  4. package/dist/content/cosmetics.d.ts +22 -0
  5. package/dist/content/cosmetics.js +173 -0
  6. package/dist/content/mainWorld.d.ts +8 -0
  7. package/dist/content/mainWorld.js +10 -0
  8. package/dist/content/preload.d.ts +1 -0
  9. package/dist/content/preload.js +34 -0
  10. package/dist/content/procedural.d.ts +19 -0
  11. package/dist/content/procedural.js +212 -0
  12. package/dist/cosmetic/engine.d.ts +95 -0
  13. package/dist/cosmetic/engine.js +268 -0
  14. package/dist/electron/blocker.d.ts +84 -0
  15. package/dist/electron/blocker.js +320 -0
  16. package/dist/electron/channels.d.ts +10 -0
  17. package/dist/electron/channels.js +6 -0
  18. package/dist/electron/scheme.d.ts +21 -0
  19. package/dist/electron/scheme.js +21 -0
  20. package/dist/engine.d.ts +86 -0
  21. package/dist/engine.js +163 -0
  22. package/dist/index.d.ts +13 -0
  23. package/dist/index.js +12 -0
  24. package/dist/lists/defaults.d.ts +6 -0
  25. package/dist/lists/defaults.js +59 -0
  26. package/dist/lists/manager.d.ts +86 -0
  27. package/dist/lists/manager.js +154 -0
  28. package/dist/lists/preprocessor.d.ts +21 -0
  29. package/dist/lists/preprocessor.js +152 -0
  30. package/dist/lists/storage.d.ts +37 -0
  31. package/dist/lists/storage.js +66 -0
  32. package/dist/network/engine.d.ts +105 -0
  33. package/dist/network/engine.js +431 -0
  34. package/dist/network/filterIndex.d.ts +40 -0
  35. package/dist/network/filterIndex.js +343 -0
  36. package/dist/network/modifiers.d.ts +23 -0
  37. package/dist/network/modifiers.js +192 -0
  38. package/dist/network/pattern.d.ts +7 -0
  39. package/dist/network/pattern.js +145 -0
  40. package/dist/network/request.d.ts +50 -0
  41. package/dist/network/request.js +136 -0
  42. package/dist/network/tokens.d.ts +5 -0
  43. package/dist/network/tokens.js +150 -0
  44. package/dist/parser/cosmetic.d.ts +21 -0
  45. package/dist/parser/cosmetic.js +171 -0
  46. package/dist/parser/hosts.d.ts +20 -0
  47. package/dist/parser/hosts.js +143 -0
  48. package/dist/parser/index.d.ts +40 -0
  49. package/dist/parser/index.js +158 -0
  50. package/dist/parser/network.d.ts +6 -0
  51. package/dist/parser/network.js +474 -0
  52. package/dist/parser/selector.d.ts +25 -0
  53. package/dist/parser/selector.js +522 -0
  54. package/dist/parser/types.d.ts +175 -0
  55. package/dist/parser/types.js +75 -0
  56. package/dist/preload.cjs +1988 -0
  57. package/dist/psl/psl.d.ts +32 -0
  58. package/dist/psl/psl.js +119 -0
  59. package/dist/resources/binary.d.ts +9 -0
  60. package/dist/resources/binary.js +54 -0
  61. package/dist/resources/defusers.d.ts +29 -0
  62. package/dist/resources/defusers.js +180 -0
  63. package/dist/resources/documents.d.ts +12 -0
  64. package/dist/resources/documents.js +56 -0
  65. package/dist/resources/ima.d.ts +6 -0
  66. package/dist/resources/ima.js +313 -0
  67. package/dist/resources/index.d.ts +14 -0
  68. package/dist/resources/index.js +85 -0
  69. package/dist/resources/surrogates.d.ts +30 -0
  70. package/dist/resources/surrogates.js +486 -0
  71. package/dist/scriptlets/abort.d.ts +5 -0
  72. package/dist/scriptlets/abort.js +97 -0
  73. package/dist/scriptlets/dom/attributes.d.ts +5 -0
  74. package/dist/scriptlets/dom/attributes.js +92 -0
  75. package/dist/scriptlets/dom/click.d.ts +2 -0
  76. package/dist/scriptlets/dom/click.js +107 -0
  77. package/dist/scriptlets/dom/cookies.d.ts +16 -0
  78. package/dist/scriptlets/dom/cookies.js +194 -0
  79. package/dist/scriptlets/dom/createHtml.d.ts +2 -0
  80. package/dist/scriptlets/dom/createHtml.js +27 -0
  81. package/dist/scriptlets/dom/dialogs.d.ts +3 -0
  82. package/dist/scriptlets/dom/dialogs.js +21 -0
  83. package/dist/scriptlets/dom/hrefSanitizer.d.ts +2 -0
  84. package/dist/scriptlets/dom/hrefSanitizer.js +91 -0
  85. package/dist/scriptlets/dom/index.d.ts +3 -0
  86. package/dist/scriptlets/dom/index.js +38 -0
  87. package/dist/scriptlets/dom/navigation.d.ts +5 -0
  88. package/dist/scriptlets/dom/navigation.js +60 -0
  89. package/dist/scriptlets/dom/nodeText.d.ts +3 -0
  90. package/dist/scriptlets/dom/nodeText.js +98 -0
  91. package/dist/scriptlets/dom/spoofCss.d.ts +2 -0
  92. package/dist/scriptlets/dom/spoofCss.js +58 -0
  93. package/dist/scriptlets/dom/storage.d.ts +5 -0
  94. package/dist/scriptlets/dom/storage.js +50 -0
  95. package/dist/scriptlets/dom/watch.d.ts +8 -0
  96. package/dist/scriptlets/dom/watch.js +41 -0
  97. package/dist/scriptlets/events.d.ts +2 -0
  98. package/dist/scriptlets/events.js +42 -0
  99. package/dist/scriptlets/helpers.d.ts +58 -0
  100. package/dist/scriptlets/helpers.js +206 -0
  101. package/dist/scriptlets/index.d.ts +6 -0
  102. package/dist/scriptlets/index.js +47 -0
  103. package/dist/scriptlets/network/edit.d.ts +9 -0
  104. package/dist/scriptlets/network/edit.js +104 -0
  105. package/dist/scriptlets/network/eval.d.ts +3 -0
  106. package/dist/scriptlets/network/eval.js +22 -0
  107. package/dist/scriptlets/network/fetch.d.ts +10 -0
  108. package/dist/scriptlets/network/fetch.js +145 -0
  109. package/dist/scriptlets/network/index.d.ts +3 -0
  110. package/dist/scriptlets/network/index.js +43 -0
  111. package/dist/scriptlets/network/jsonPath.d.ts +13 -0
  112. package/dist/scriptlets/network/jsonPath.js +482 -0
  113. package/dist/scriptlets/network/media.d.ts +3 -0
  114. package/dist/scriptlets/network/media.js +97 -0
  115. package/dist/scriptlets/network/methods.d.ts +5 -0
  116. package/dist/scriptlets/network/methods.js +139 -0
  117. package/dist/scriptlets/network/prune.d.ts +13 -0
  118. package/dist/scriptlets/network/prune.js +194 -0
  119. package/dist/scriptlets/network/rendering.d.ts +4 -0
  120. package/dist/scriptlets/network/rendering.js +46 -0
  121. package/dist/scriptlets/network/replace.d.ts +5 -0
  122. package/dist/scriptlets/network/replace.js +168 -0
  123. package/dist/scriptlets/network/request.d.ts +19 -0
  124. package/dist/scriptlets/network/request.js +124 -0
  125. package/dist/scriptlets/network/util.d.ts +19 -0
  126. package/dist/scriptlets/network/util.js +80 -0
  127. package/dist/scriptlets/network/webrtc.d.ts +3 -0
  128. package/dist/scriptlets/network/webrtc.js +62 -0
  129. package/dist/scriptlets/network/windowOpen.d.ts +2 -0
  130. package/dist/scriptlets/network/windowOpen.js +28 -0
  131. package/dist/scriptlets/network/xhr.d.ts +9 -0
  132. package/dist/scriptlets/network/xhr.js +177 -0
  133. package/dist/scriptlets/runner.d.ts +8 -0
  134. package/dist/scriptlets/runner.js +19 -0
  135. package/dist/scriptlets/setConstant.d.ts +5 -0
  136. package/dist/scriptlets/setConstant.js +117 -0
  137. package/dist/scriptlets/timers.d.ts +5 -0
  138. package/dist/scriptlets/timers.js +66 -0
  139. package/dist/scriptlets/types.d.ts +32 -0
  140. package/dist/scriptlets/types.js +1 -0
  141. package/dist/util.d.ts +5 -0
  142. package/dist/util.js +16 -0
  143. package/package.json +83 -4
@@ -0,0 +1,320 @@
1
+ import { randomBytes } from "node:crypto";
2
+ import { fileURLToPath } from "node:url";
3
+ import { Engine } from "../engine.js";
4
+ import { hostnameOf } from "../network/request.js";
5
+ import { findResource } from "../resources/index.js";
6
+ import { isRecord, toError } from "../util.js";
7
+ import { DOCUMENT_CHANNEL, GENERIC_CHANNEL } from "./channels.js";
8
+ import { ADBLOCK_SCHEME } from "./scheme.js";
9
+ const TYPES = {
10
+ mainFrame: "document",
11
+ subFrame: "subdocument",
12
+ stylesheet: "stylesheet",
13
+ script: "script",
14
+ image: "image",
15
+ font: "font",
16
+ object: "object",
17
+ xhr: "xhr",
18
+ ping: "ping",
19
+ media: "media",
20
+ webSocket: "websocket",
21
+ };
22
+ // What filters are about. The rest (the blocker's own scheme, data:, blob:,
23
+ // file:, devtools:) is never touched.
24
+ const FILTERED = /^(?:https?|wss?):/i;
25
+ const MAX_NAMES = 10_000;
26
+ /** The address of the first document, from a frame up, that has one. */
27
+ function documentUrl(frame) {
28
+ for (let up = frame; up; up = up.parent) {
29
+ if (FILTERED.test(up.url))
30
+ return up.url;
31
+ }
32
+ return "";
33
+ }
34
+ /**
35
+ * Applies uBlock Origin's filter lists in Electron sessions: it blocks,
36
+ * redirects and rewrites requests, adds policies to documents, and gives
37
+ * each document its scriptlets and cosmetic filters through a preload.
38
+ *
39
+ * The app registers `adblockScheme` with its own schemes before `ready`,
40
+ * creates one blocker, and enables it in the sessions it wants filtered.
41
+ * In those sessions the blocker owns `webRequest.onBeforeRequest` and
42
+ * `webRequest.onHeadersReceived`: Electron keeps one listener per event.
43
+ */
44
+ export class ElectronBlocker {
45
+ /** The lists and what decides from them. */
46
+ engine;
47
+ /** Resolves once the lists are in effect. It never rejects. */
48
+ ready;
49
+ counts = {
50
+ blocked: 0,
51
+ redirected: 0,
52
+ rewritten: 0,
53
+ responses: 0,
54
+ documents: 0,
55
+ scriptlets: 0,
56
+ };
57
+ ipcMain;
58
+ preloadPath;
59
+ onError;
60
+ /** The sessions it is enabled in, with the id of their preload. */
61
+ sessions = new Map();
62
+ // Part of every resource's address, so a page can't ask for one to find
63
+ // out the blocker is there.
64
+ token = randomBytes(8).toString("hex");
65
+ disposed = false;
66
+ constructor(options) {
67
+ const { ipcMain, preloadPath, ...engine } = options;
68
+ this.ipcMain = ipcMain;
69
+ this.onError = options.onError ?? (() => { });
70
+ this.preloadPath =
71
+ preloadPath ?? fileURLToPath(new URL("../preload.cjs", import.meta.url));
72
+ this.engine = new Engine(engine);
73
+ this.ready = this.engine.ready;
74
+ ipcMain.on(DOCUMENT_CHANNEL, this.onDocument);
75
+ ipcMain.handle(GENERIC_CHANNEL, this.onGeneric);
76
+ }
77
+ /** Starts filtering a session. Enabling one twice changes nothing. */
78
+ enable(session) {
79
+ if (this.disposed || this.sessions.has(session))
80
+ return;
81
+ this.sessions.set(session, session.registerPreloadScript({
82
+ type: "frame",
83
+ filePath: this.preloadPath,
84
+ }));
85
+ session.webRequest.onBeforeRequest(this.onBeforeRequest);
86
+ session.webRequest.onHeadersReceived(this.onHeadersReceived);
87
+ session.protocol.handle(ADBLOCK_SCHEME, this.serve);
88
+ }
89
+ /** Stops filtering a session. Pages already loaded keep what they got. */
90
+ disable(session) {
91
+ const preload = this.sessions.get(session);
92
+ if (preload === undefined)
93
+ return;
94
+ this.sessions.delete(session);
95
+ // Each on its own: a session that is going away may refuse one.
96
+ for (const undo of [
97
+ () => session.unregisterPreloadScript(preload),
98
+ () => session.webRequest.onBeforeRequest(null),
99
+ () => session.webRequest.onHeadersReceived(null),
100
+ () => session.protocol.unhandle(ADBLOCK_SCHEME),
101
+ ]) {
102
+ try {
103
+ undo();
104
+ }
105
+ catch (error) {
106
+ this.onError(toError(error));
107
+ }
108
+ }
109
+ }
110
+ isEnabled(session) {
111
+ return this.sessions.has(session);
112
+ }
113
+ /** Looks for new versions of the lists. See `Engine.update()`. */
114
+ update(force = false) {
115
+ return this.engine.update(force);
116
+ }
117
+ /** Stops everything: every session, the updates and the IPC channels. */
118
+ dispose() {
119
+ if (this.disposed)
120
+ return;
121
+ this.disposed = true;
122
+ for (const session of [...this.sessions.keys()])
123
+ this.disable(session);
124
+ this.engine.dispose();
125
+ this.ipcMain.removeListener(DOCUMENT_CHANNEL, this.onDocument);
126
+ this.ipcMain.removeHandler(GENERIC_CHANNEL);
127
+ }
128
+ /** The address a redirect resource is served from. */
129
+ resourceUrl(name, original) {
130
+ const url = `${ADBLOCK_SCHEME}://${this.token}/${encodeURIComponent(name)}`;
131
+ // This one shows the address of the frame it stands in for.
132
+ return name === "click2load.html"
133
+ ? `${url}?url=${encodeURIComponent(original)}`
134
+ : url;
135
+ }
136
+ /**
137
+ * `webRequest.onBeforeRequest`: blocks, redirects or rewrites a request.
138
+ * A listener of the app's own can call it for the sessions it handles.
139
+ */
140
+ onBeforeRequest = (details, callback) => {
141
+ let response = {};
142
+ try {
143
+ response = this.decide(details);
144
+ }
145
+ catch (error) {
146
+ // A failure here must never fail the request.
147
+ this.onError(toError(error));
148
+ }
149
+ callback(response);
150
+ };
151
+ /** What filters ask about a request Electron describes. */
152
+ requestOf(details) {
153
+ let sourceUrl = details.referrer;
154
+ let topUrl;
155
+ try {
156
+ const { frame } = details;
157
+ // A frame's own navigation comes from the document that holds it.
158
+ const from = details.resourceType === "subFrame" ? frame?.parent : frame;
159
+ sourceUrl = documentUrl(from) || details.referrer;
160
+ topUrl = frame?.top?.url;
161
+ }
162
+ catch {
163
+ // The frame is gone already: the referrer is what is left.
164
+ }
165
+ return this.engine.network.request({
166
+ url: details.url,
167
+ type: TYPES[details.resourceType] ?? "other",
168
+ sourceUrl,
169
+ topUrl,
170
+ method: details.method,
171
+ });
172
+ }
173
+ decide(details) {
174
+ if (!FILTERED.test(details.url))
175
+ return {};
176
+ // The page asked for the frame it had been given a placeholder for.
177
+ if (details.resourceType === "subFrame" &&
178
+ details.frame?.url.startsWith(`${ADBLOCK_SCHEME}://${this.token}/`) ===
179
+ true) {
180
+ return {};
181
+ }
182
+ const { network } = this.engine;
183
+ const request = this.requestOf(details);
184
+ const decision = network.match(request);
185
+ if (decision.block) {
186
+ this.counts.blocked++;
187
+ if (decision.redirect !== undefined) {
188
+ this.counts.redirected++;
189
+ return {
190
+ redirectURL: this.resourceUrl(decision.redirect, details.url),
191
+ };
192
+ }
193
+ }
194
+ const rewritten = network.rewrite(request, decision.block);
195
+ if (rewritten !== undefined) {
196
+ this.counts.rewritten++;
197
+ return { redirectURL: rewritten };
198
+ }
199
+ return decision.block ? { cancel: true } : {};
200
+ }
201
+ /**
202
+ * `webRequest.onHeadersReceived`: blocks a response by its headers, adds
203
+ * the policies of `csp=` and `permissions=` to a document and removes the
204
+ * headers `##^responseheader()` names.
205
+ */
206
+ onHeadersReceived = (details, callback) => {
207
+ let response = {};
208
+ try {
209
+ response = this.decideResponse(details);
210
+ }
211
+ catch (error) {
212
+ this.onError(toError(error));
213
+ }
214
+ callback(response);
215
+ };
216
+ decideResponse(details) {
217
+ if (!FILTERED.test(details.url))
218
+ return {};
219
+ const isDocument = details.resourceType === "mainFrame" ||
220
+ details.resourceType === "subFrame";
221
+ const headers = { ...details.responseHeaders };
222
+ // Servers write header names in any case.
223
+ const nameOf = (lower) => Object.keys(headers).find((name) => name.toLowerCase() === lower);
224
+ const { network, cosmetic } = this.engine;
225
+ const request = this.requestOf(details);
226
+ const decision = network.response(request, (lower) => {
227
+ const name = nameOf(lower);
228
+ return name === undefined ? undefined : headers[name].join(", ");
229
+ });
230
+ if (decision.block) {
231
+ this.counts.responses++;
232
+ return { cancel: true };
233
+ }
234
+ if (!isDocument)
235
+ return {};
236
+ let changed = false;
237
+ for (const [header, policies] of [
238
+ ["content-security-policy", decision.csp],
239
+ ["permissions-policy", decision.permissions],
240
+ ]) {
241
+ if (policies.length === 0)
242
+ continue;
243
+ // A second header of the same name: the browser applies both.
244
+ const name = nameOf(header) ?? header;
245
+ headers[name] = [...(headers[name] ?? []), ...policies];
246
+ changed = true;
247
+ }
248
+ for (const header of cosmetic.headersToRemove(request.hostname)) {
249
+ const name = nameOf(header);
250
+ if (name === undefined)
251
+ continue;
252
+ delete headers[name];
253
+ changed = true;
254
+ }
255
+ if (!changed)
256
+ return {};
257
+ this.counts.responses++;
258
+ return { responseHeaders: headers };
259
+ }
260
+ /** The protocol handler: serves the redirect resources. */
261
+ serve = (request) => {
262
+ const url = new URL(request.url);
263
+ const resource = url.hostname === this.token
264
+ ? findResource(decodeURIComponent(url.pathname.slice(1)))
265
+ : undefined;
266
+ if (resource === undefined)
267
+ return new Response(null, { status: 404 });
268
+ const { body } = resource;
269
+ return new Response(typeof body === "string" ? body : Buffer.from(body), {
270
+ headers: {
271
+ "content-type": resource.mime,
272
+ // The page that asked is on another origin.
273
+ "access-control-allow-origin": "*",
274
+ },
275
+ });
276
+ };
277
+ /** A document asks what it gets: answered at once, from memory. */
278
+ onDocument = (event, url) => {
279
+ let config = null;
280
+ try {
281
+ if (this.sessions.has(event.sender.session) && typeof url === "string") {
282
+ // A document without an address of its own (about:blank, srcdoc)
283
+ // is filtered as the document that holds it.
284
+ const address = FILTERED.test(url)
285
+ ? url
286
+ : documentUrl(event.senderFrame?.parent);
287
+ if (address !== "") {
288
+ config = this.engine.document(address, event.senderFrame?.top?.url);
289
+ this.counts.documents++;
290
+ this.counts.scriptlets += config.scriptlets.length;
291
+ }
292
+ }
293
+ }
294
+ catch (error) {
295
+ this.onError(toError(error));
296
+ }
297
+ // Always answered: the page waits for it.
298
+ event.returnValue = config;
299
+ };
300
+ /** A page asks for the generic filters of its classes and ids. */
301
+ onGeneric = (event, request) => {
302
+ try {
303
+ if (!this.sessions.has(event.sender.session) || !isRecord(request)) {
304
+ return "";
305
+ }
306
+ const { url, classes, ids } = request;
307
+ const names = (given) => Array.isArray(given)
308
+ ? given.filter((name) => typeof name === "string").slice(0, MAX_NAMES)
309
+ : [];
310
+ const hostname = typeof url === "string" ? hostnameOf(url) : "";
311
+ return hostname === ""
312
+ ? ""
313
+ : this.engine.cosmetic.genericFor(hostname, names(classes), names(ids));
314
+ }
315
+ catch (error) {
316
+ this.onError(toError(error));
317
+ return "";
318
+ }
319
+ };
320
+ }
@@ -0,0 +1,10 @@
1
+ /** Synchronous: a document asks what it gets, before its scripts run. */
2
+ export declare const DOCUMENT_CHANNEL = "tokio-adblock:document";
3
+ /** A page asks for the generic filters of the classes and ids it uses. */
4
+ export declare const GENERIC_CHANNEL = "tokio-adblock:generic";
5
+ /** What a page sends with `GENERIC_CHANNEL`. */
6
+ export interface GenericRequest {
7
+ url: string;
8
+ classes: string[];
9
+ ids: string[];
10
+ }
@@ -0,0 +1,6 @@
1
+ // The IPC channels between the preload and the main process. The preload is
2
+ // bundled with this file, so it holds nothing but the names.
3
+ /** Synchronous: a document asks what it gets, before its scripts run. */
4
+ export const DOCUMENT_CHANNEL = "tokio-adblock:document";
5
+ /** A page asks for the generic filters of the classes and ids it uses. */
6
+ export const GENERIC_CHANNEL = "tokio-adblock:generic";
@@ -0,0 +1,21 @@
1
+ /** The scheme the redirect resources are served from. */
2
+ export declare const ADBLOCK_SCHEME = "tokio-adblock";
3
+ /**
4
+ * The entry a host app adds to its own `protocol.registerSchemesAsPrivileged`
5
+ * call, before `app.ready`. The library never registers it: Electron takes one
6
+ * call for the whole app, and a second call replaces the first.
7
+ *
8
+ * NOTE: DO NOT CHANGE the privileges without a run of `yarn smoke`. Without
9
+ * `bypassCSP` a page's CSP blocks the redirected scripts, and without
10
+ * `standard` and `secure` an https page can't load them.
11
+ */
12
+ export declare const adblockScheme: {
13
+ readonly scheme: "tokio-adblock";
14
+ readonly privileges: {
15
+ readonly standard: true;
16
+ readonly secure: true;
17
+ readonly supportFetchAPI: true;
18
+ readonly corsEnabled: true;
19
+ readonly bypassCSP: true;
20
+ };
21
+ };
@@ -0,0 +1,21 @@
1
+ /** The scheme the redirect resources are served from. */
2
+ export const ADBLOCK_SCHEME = "tokio-adblock";
3
+ /**
4
+ * The entry a host app adds to its own `protocol.registerSchemesAsPrivileged`
5
+ * call, before `app.ready`. The library never registers it: Electron takes one
6
+ * call for the whole app, and a second call replaces the first.
7
+ *
8
+ * NOTE: DO NOT CHANGE the privileges without a run of `yarn smoke`. Without
9
+ * `bypassCSP` a page's CSP blocks the redirected scripts, and without
10
+ * `standard` and `secure` an https page can't load them.
11
+ */
12
+ export const adblockScheme = {
13
+ scheme: ADBLOCK_SCHEME,
14
+ privileges: {
15
+ standard: true,
16
+ secure: true,
17
+ supportFetchAPI: true,
18
+ corsEnabled: true,
19
+ bypassCSP: true,
20
+ },
21
+ };
@@ -0,0 +1,86 @@
1
+ import { CosmeticEngine, type DocumentCosmetics } from "./cosmetic/engine.js";
2
+ import { type FetchLike, type ListDefinition } from "./lists/manager.js";
3
+ import { type ListStorage } from "./lists/storage.js";
4
+ import { NetworkEngine } from "./network/engine.js";
5
+ import { type ParseStats } from "./parser/index.js";
6
+ export interface EngineOptions {
7
+ /** The filter lists to apply (default: `DEFAULT_LISTS`). */
8
+ lists?: readonly ListDefinition[];
9
+ /**
10
+ * Where downloaded lists are kept. Without one they live in memory and are
11
+ * downloaded again at every start: pass a `FileStorage`.
12
+ */
13
+ storage?: ListStorage;
14
+ /** Defaults to the global `fetch`. */
15
+ fetch?: FetchLike;
16
+ /** Look for new versions of the lists as they expire (default true). */
17
+ autoUpdate?: boolean;
18
+ /**
19
+ * Where to download Mozilla's Public Suffix List from, which tells a site
20
+ * from its subdomains (default: `PUBLIC_SUFFIX_LIST_URLS`). Empty: don't,
21
+ * and guess instead.
22
+ */
23
+ publicSuffixListUrls?: readonly string[];
24
+ /** Told about what went wrong in the background. Nothing is ever thrown. */
25
+ onError?: (error: Error) => void;
26
+ now?: () => number;
27
+ }
28
+ /** Where the Public Suffix List is published. It is downloaded, not shipped. */
29
+ export declare const PUBLIC_SUFFIX_LIST_URLS: readonly string[];
30
+ /**
31
+ * Downloads the filter lists, keeps them up to date and applies them.
32
+ */
33
+ export declare class Engine {
34
+ /**
35
+ * Decides what happens to requests. Replaced when the lists change, so
36
+ * read it from the engine each time instead of keeping it.
37
+ */
38
+ network: NetworkEngine;
39
+ /**
40
+ * Decides what a document gets: selectors to hide, procedural filters and
41
+ * scriptlets. Replaced when the lists change, like `network`.
42
+ */
43
+ cosmetic: CosmeticEngine;
44
+ /**
45
+ * Resolves once the lists that could be loaded are in effect. It never
46
+ * rejects: a list that can't be loaded is reported to `onError` and left
47
+ * out.
48
+ */
49
+ readonly ready: Promise<void>;
50
+ /** What each loaded list holds, by list id. */
51
+ stats: Record<string, ParseStats>;
52
+ private readonly lists;
53
+ private readonly pslUrls;
54
+ private readonly manager;
55
+ private readonly autoUpdate;
56
+ private readonly onError;
57
+ private readonly now;
58
+ private queue;
59
+ private timer;
60
+ private built;
61
+ private disposed;
62
+ constructor(options?: EngineOptions);
63
+ /**
64
+ * Looks for new versions of the lists that expired (of all of them with
65
+ * `force`) and rebuilds the rules when one changed. Resolves to whether
66
+ * the rules changed. Calls run one after the other.
67
+ */
68
+ update(force?: boolean): Promise<boolean>;
69
+ /**
70
+ * What the document at `url` gets as it starts loading: its scriptlets,
71
+ * its stylesheet and its procedural filters, with the `generichide`,
72
+ * `specifichide` and `elemhide` exceptions for it applied. `topUrl` is the
73
+ * top document's, when this one is in a frame.
74
+ */
75
+ document(url: string, topUrl?: string): DocumentCosmetics;
76
+ /**
77
+ * Whether a `popup` filter blocks a window the page at `openerUrl` wants
78
+ * to open at `url`. Nothing asks by itself: an app decides about new
79
+ * windows in its own `setWindowOpenHandler`, and can ask there.
80
+ */
81
+ blocksPopup(url: string, openerUrl: string): boolean;
82
+ /** Stops the updates. The rules stay in effect. */
83
+ dispose(): void;
84
+ private run;
85
+ private schedule;
86
+ }
package/dist/engine.js ADDED
@@ -0,0 +1,163 @@
1
+ import { CosmeticEngine } from "./cosmetic/engine.js";
2
+ import { DEFAULT_LISTS } from "./lists/defaults.js";
3
+ import { ListManager, } from "./lists/manager.js";
4
+ import { MemoryStorage } from "./lists/storage.js";
5
+ import { NetworkEngine } from "./network/engine.js";
6
+ import { emptyParsedList, parseInto } from "./parser/index.js";
7
+ import { PublicSuffixList } from "./psl/psl.js";
8
+ import { toError } from "./util.js";
9
+ /** Where the Public Suffix List is published. It is downloaded, not shipped. */
10
+ export const PUBLIC_SUFFIX_LIST_URLS = [
11
+ "https://publicsuffix.org/list/public_suffix_list.dat",
12
+ ];
13
+ // Lines parsed per turn of the event loop: a few milliseconds of work, so a
14
+ // host's main process stays responsive while 300,000 lines load.
15
+ const SLICE = 4000;
16
+ const MINUTE = 60_000;
17
+ const DAY = 24 * 60 * MINUTE;
18
+ const nextTurn = () => new Promise((resolve) => setImmediate(resolve));
19
+ /**
20
+ * Downloads the filter lists, keeps them up to date and applies them.
21
+ */
22
+ export class Engine {
23
+ /**
24
+ * Decides what happens to requests. Replaced when the lists change, so
25
+ * read it from the engine each time instead of keeping it.
26
+ */
27
+ network = new NetworkEngine();
28
+ /**
29
+ * Decides what a document gets: selectors to hide, procedural filters and
30
+ * scriptlets. Replaced when the lists change, like `network`.
31
+ */
32
+ cosmetic = new CosmeticEngine();
33
+ /**
34
+ * Resolves once the lists that could be loaded are in effect. It never
35
+ * rejects: a list that can't be loaded is reported to `onError` and left
36
+ * out.
37
+ */
38
+ ready;
39
+ /** What each loaded list holds, by list id. */
40
+ stats = {};
41
+ lists;
42
+ pslUrls;
43
+ manager;
44
+ autoUpdate;
45
+ onError;
46
+ now;
47
+ queue = Promise.resolve();
48
+ timer;
49
+ built = false;
50
+ disposed = false;
51
+ constructor(options = {}) {
52
+ this.lists = options.lists ?? DEFAULT_LISTS;
53
+ this.pslUrls = options.publicSuffixListUrls ?? PUBLIC_SUFFIX_LIST_URLS;
54
+ this.autoUpdate = options.autoUpdate ?? true;
55
+ this.onError = options.onError ?? (() => { });
56
+ this.now = options.now ?? Date.now;
57
+ this.manager = new ListManager({
58
+ storage: options.storage ?? new MemoryStorage(),
59
+ fetch: options.fetch,
60
+ now: options.now,
61
+ onError: this.onError,
62
+ });
63
+ this.ready = this.update().then(() => { });
64
+ }
65
+ /**
66
+ * Looks for new versions of the lists that expired (of all of them with
67
+ * `force`) and rebuilds the rules when one changed. Resolves to whether
68
+ * the rules changed. Calls run one after the other.
69
+ */
70
+ update(force = false) {
71
+ const run = this.queue.then(() => this.run(force));
72
+ this.queue = run.catch(() => { });
73
+ return run.catch((error) => {
74
+ this.onError(toError(error));
75
+ return false;
76
+ });
77
+ }
78
+ /**
79
+ * What the document at `url` gets as it starts loading: its scriptlets,
80
+ * its stylesheet and its procedural filters, with the `generichide`,
81
+ * `specifichide` and `elemhide` exceptions for it applied. `topUrl` is the
82
+ * top document's, when this one is in a frame.
83
+ */
84
+ document(url, topUrl) {
85
+ const request = this.network.request({ url, type: "document", topUrl });
86
+ return this.cosmetic.forDocument(request.hostname, this.network.cosmeticSwitches(request));
87
+ }
88
+ /**
89
+ * Whether a `popup` filter blocks a window the page at `openerUrl` wants
90
+ * to open at `url`. Nothing asks by itself: an app decides about new
91
+ * windows in its own `setWindowOpenHandler`, and can ask there.
92
+ */
93
+ blocksPopup(url, openerUrl) {
94
+ const { network } = this;
95
+ return network.match(network.request({ url, type: "popup", sourceUrl: openerUrl })).block;
96
+ }
97
+ /** Stops the updates. The rules stay in effect. */
98
+ dispose() {
99
+ this.disposed = true;
100
+ clearTimeout(this.timer);
101
+ }
102
+ async run(force) {
103
+ if (this.disposed)
104
+ return false;
105
+ const reported = (error) => {
106
+ this.onError(toError(error));
107
+ return undefined;
108
+ };
109
+ const [suffixes, ...loaded] = await Promise.all([
110
+ this.pslUrls.length === 0
111
+ ? undefined
112
+ : this.manager
113
+ // The list changes a few times a month.
114
+ .resource("public_suffix_list", this.pslUrls, { updateAfterDays: 19 }, force)
115
+ .catch(reported),
116
+ ...this.lists.map((list) => this.manager.load(list, force).catch(reported)),
117
+ ]);
118
+ const changed = !this.built ||
119
+ suffixes?.changed === true ||
120
+ loaded.some((list) => list?.changed);
121
+ if (changed) {
122
+ const stats = {};
123
+ const psl = new PublicSuffixList(suffixes?.resource.text);
124
+ const network = new NetworkEngine({ psl });
125
+ const cosmetic = new CosmeticEngine({ psl });
126
+ for (const list of loaded) {
127
+ if (list === undefined)
128
+ continue;
129
+ const rules = emptyParsedList();
130
+ const context = { trusted: list.trusted };
131
+ for (let start = 0; start < list.lines.length; start += SLICE) {
132
+ parseInto(rules, list.lines, context, start, Math.min(start + SLICE, list.lines.length));
133
+ await nextTurn();
134
+ }
135
+ stats[list.id] = rules.stats;
136
+ network.add(rules.network);
137
+ cosmetic.add(rules);
138
+ }
139
+ const steps = network.finalizing();
140
+ while (steps.next().done !== true)
141
+ await nextTurn();
142
+ this.network = network;
143
+ this.cosmetic = cosmetic;
144
+ this.stats = stats;
145
+ this.built = true;
146
+ }
147
+ this.schedule();
148
+ return changed;
149
+ }
150
+ schedule() {
151
+ clearTimeout(this.timer);
152
+ if (!this.autoUpdate || this.disposed)
153
+ return;
154
+ const expiry = this.manager.nextExpiry();
155
+ if (expiry === undefined)
156
+ return;
157
+ // Not sooner than a minute, so a list that fails to load isn't hammered.
158
+ const delay = Math.min(Math.max(expiry - this.now(), MINUTE), DAY);
159
+ this.timer = setTimeout(() => void this.update(), delay);
160
+ // The updates alone don't keep a process alive.
161
+ this.timer.unref?.();
162
+ }
163
+ }
@@ -0,0 +1,13 @@
1
+ export { CosmeticEngine, type CosmeticStats, type DocumentCosmetics, } from "./cosmetic/engine.js";
2
+ export { ElectronBlocker, type BlockerCounts, type ElectronBlockerOptions, } from "./electron/blocker.js";
3
+ export { ADBLOCK_SCHEME, adblockScheme } from "./electron/scheme.js";
4
+ export { Engine, PUBLIC_SUFFIX_LIST_URLS, type EngineOptions, } from "./engine.js";
5
+ export { DEFAULT_LISTS } from "./lists/defaults.js";
6
+ export { ListManager, type FetchLike, type ListDefinition, type ListManagerOptions, type LoadedList, } from "./lists/manager.js";
7
+ export { FileStorage, MemoryStorage, type ListStorage, type StoredResource, } from "./lists/storage.js";
8
+ export { NetworkEngine, type Decision, type NetworkEngineOptions, type NetworkStats, type ResponseDecision, } from "./network/engine.js";
9
+ export { Request, type RequestInfo, type RequestType, } from "./network/request.js";
10
+ export { PublicSuffixList } from "./psl/psl.js";
11
+ export { RESOURCES, findResource, type RedirectResource, } from "./resources/index.js";
12
+ export { parseList, type ParsedList, type ParseStats } from "./parser/index.js";
13
+ export type * from "./parser/types.js";
package/dist/index.js ADDED
@@ -0,0 +1,12 @@
1
+ export { CosmeticEngine, } from "./cosmetic/engine.js";
2
+ export { ElectronBlocker, } from "./electron/blocker.js";
3
+ export { ADBLOCK_SCHEME, adblockScheme } from "./electron/scheme.js";
4
+ export { Engine, PUBLIC_SUFFIX_LIST_URLS, } from "./engine.js";
5
+ export { DEFAULT_LISTS } from "./lists/defaults.js";
6
+ export { ListManager, } from "./lists/manager.js";
7
+ export { FileStorage, MemoryStorage, } from "./lists/storage.js";
8
+ export { NetworkEngine, } from "./network/engine.js";
9
+ export { Request, } from "./network/request.js";
10
+ export { PublicSuffixList } from "./psl/psl.js";
11
+ export { RESOURCES, findResource, } from "./resources/index.js";
12
+ export { parseList } from "./parser/index.js";
@@ -0,0 +1,6 @@
1
+ import type { ListDefinition } from "./manager.js";
2
+ /**
3
+ * The lists uBlock Origin enables by default, from its published asset index
4
+ * (`assets/assets.json`), with the same ids.
5
+ */
6
+ export declare const DEFAULT_LISTS: readonly ListDefinition[];