webext-messenger 0.25.2 → 0.27.0

package/distribution/receiver.js

@@ -3,8 +3,9 @@ import { getContextName } from "webext-detect-page";
 import { messenger } from "./sender.js";
 import { isObject, MessengerError, __webextMessenger } from "./shared.js";
 import { log } from "./logging.js";
-import { getActionForMessage } from "./thisTarget.js";
+import { getActionForMessage } from "./targetLogic.js";
 import { didUserRegisterMethods, handlers } from "./handlers.js";
+import { getTabDataStatus, thisTarget } from "./thisTarget.js";
 export function isMessengerMessage(message) {
     return (isObject(message) &&
         typeof message["type"] === "string" &&
@@ -18,8 +19,13 @@ function onMessageListener(message, sender) {
         return;
     }
     // Target check must be synchronous (`await` means we're handling the message)
-    const action = getActionForMessage(sender, message);
+    const action = getActionForMessage(sender, message.target, thisTarget);
     if (action === "ignore") {
+        log.debug(message.type, "🤫 ignored due to target mismatch", {
+            requestedTarget: message.target,
+            thisTarget,
+            tabDataStatus: getTabDataStatus(),
+        });
         return;
     }
     return handleMessage(message, sender, action);
@@ -74,6 +80,4 @@ export function registerMethods(methods) {
     browser.runtime.onMessage.addListener(onMessageListener);
 }
 /** Ensure/document that the current function was called via Messenger */
-export function assertMessengerCall(_this
-// eslint-disable-next-line @typescript-eslint/no-empty-function -- TypeScript already does this, it's a documentation-only call
-) { }
+export function assertMessengerCall(_this) { }

package/distribution/sender.js

@@ -128,9 +128,16 @@ async function manageMessage(type, target, seq, retry, sendMessage) {
     log.debug(type, seq, "↘️ replied successfully", response.value);
     return response.value;
 }
+// Not a UID nor a truly global sequence. Signal / console noise compromise.
+// The time part is a pseudo-random number between 0 and 99 that helps visually
+// group messages from the same context. Keeping it a number also gives it a different
+// color in the console log.
+// Example log when seen in the background page:
+// Tab 1 sends: 33000, 33001, 33002
+// Tab 2 sends: 12000, 12001, 12002
+let globalSeq = (Date.now() % 100) * 10_000;
 function messenger(type, options, target, ...args) {
-    // Not a UID. Signal / console noise compromise. They repeat every 100 seconds
-    options.seq = Date.now() % 100000;
+    options.seq = globalSeq++;
     const { seq } = options;
     // Message goes to extension page
     if ("page" in target) {
@@ -160,9 +167,11 @@ function messenger(type, options, target, ...args) {
     // Message tab directly
     return manageConnection(type, options, target, async (attemptCount) => {
         log.debug(type, seq, "↗️ sending message to tab", tabId, "frame", frameId, attemptLog(attemptCount));
-        return browser.tabs.sendMessage(tabId, makeMessage(type, args, target, options), {
-            frameId,
-        });
+        return browser.tabs.sendMessage(tabId, makeMessage(type, args, target, options), frameId === "allFrames"
+            ? {}
+            : {
+                frameId,
+            });
     });
 }
 function getMethod(type, target) {

package/distribution/targetLogic.d.ts

@@ -0,0 +1,3 @@
+import { type AnyTarget, type Sender } from "./types.js";
+export declare function compareTargets(to: AnyTarget, thisTarget: AnyTarget): boolean;
+export declare function getActionForMessage(from: Sender, target: AnyTarget, thisTarget: AnyTarget): "respond" | "forward" | "ignore";

package/distribution/targetLogic.js

@@ -0,0 +1,50 @@
+import { isBackground, isContentScript } from "webext-detect-page";
+export function compareTargets(to, thisTarget) {
+    for (const [key, value] of Object.entries(to)) {
+        if (thisTarget[key] === value) {
+            continue;
+        }
+        if (key !== "page") {
+            return false;
+        }
+        const toUrl = new URL(to.page, location.origin);
+        const thisUrl = new URL(thisTarget.page, location.origin);
+        if (toUrl.pathname !== thisUrl.pathname) {
+            return false;
+        }
+        for (const [parameterKey, parameterValue] of toUrl.searchParams) {
+            if (thisUrl.searchParams.get(parameterKey) !== parameterValue) {
+                return false;
+            }
+        }
+    }
+    return true;
+}
+export function getActionForMessage(from, target, thisTarget) {
+    // Clone object because we're editing it
+    const to = { ...target };
+    if (to.page === "any") {
+        return "respond";
+    }
+    // Content scripts only receive messages that are meant for them. In the future
+    // they'll also forward them, but that still means they need to be handled here.
+    if (isContentScript()) {
+        return "respond";
+    }
+    // We're in an extension page, but the target is not one.
+    if (!to.page) {
+        // Only the background page can forward messages at the moment
+        // https://github.com/pixiebrix/webext-messenger/issues/219#issuecomment-2011000477
+        // If this condition is changed, it might also need to ensure that messages are not
+        // forwarded to itself, e.g. when using the tabs API in an iframed extension page.
+        // https://github.com/pixiebrix/webext-messenger/issues/221#issuecomment-2010165690
+        return isBackground() ? "forward" : "ignore";
+    }
+    // Set "this" tab to the current tabId
+    if (to.tabId === "this" && thisTarget.tabId === from.tab?.id) {
+        to.tabId = thisTarget.tabId;
+    }
+    // Every `target` key must match `thisTarget`
+    const isThisTarget = compareTargets(to, thisTarget);
+    return isThisTarget ? "respond" : "ignore";
+}

package/distribution/targetLogic.test.d.ts

@@ -0,0 +1 @@
+export {};

package/distribution/targetLogic.test.js

@@ -0,0 +1,61 @@
+import { assert, describe, test, vi } from "vitest";
+import { getActionForMessage } from "./targetLogic.js";
+import { isContentScript, isBackground } from "webext-detect-page";
+vi.mock("webext-detect-page");
+const tab = {
+    id: 1,
+    url: "http://example.com",
+    windowId: 1,
+    active: true,
+    index: 0,
+    pinned: false,
+    highlighted: true,
+    incognito: false,
+};
+const senders = {
+    background: { page: "background" },
+    contentScript: { tab },
+    somePage: { page: "/page.html" },
+};
+const targets = {
+    background: { page: "background" },
+    somePage: { page: "/page.html" },
+    anyPage: { page: "any" },
+    thisTab: { tabId: "this" },
+};
+const thisTarget = {
+    background: { page: "background" },
+    somePage: { page: "/page.html" },
+    tab: { tabId: 1, frameId: 0 },
+    frame: { tabId: 1, frameId: 1 },
+};
+describe("getActionForMessage", async () => {
+    test.each([
+        // Sender         Target        Receiver      Expected
+        ["contentScript", "background", "background", "respond"],
+        ["contentScript", "background", "somePage", "ignore"],
+        ["contentScript", "background", "tab", "respond"], // Wrong, but won't happen
+        ["contentScript", "background", "frame", "respond"], // Wrong, but won't happen
+        ["contentScript", "anyPage", "background", "respond"],
+        ["contentScript", "anyPage", "somePage", "respond"],
+        ["contentScript", "anyPage", "tab", "respond"],
+        ["contentScript", "anyPage", "frame", "respond"],
+        ["contentScript", "somePage", "background", "ignore"],
+        ["contentScript", "somePage", "somePage", "respond"],
+        ["contentScript", "somePage", "tab", "respond"], // Wrong, but won't happen
+        ["contentScript", "somePage", "frame", "respond"], // Wrong, but won't happen
+        ["contentScript", "thisTab", "background", "forward"],
+        ["contentScript", "thisTab", "somePage", "ignore"],
+        ["contentScript", "thisTab", "tab", "respond"], // Won't happen, content scripts cannot target tabs
+        ["contentScript", "thisTab", "frame", "respond"], // Won't happen, content scripts cannot target tabs
+    ])("from %s to %s, receiver %s should %s", async (from, to, receiver, expected) => {
+        const isCs = receiver === "tab" || receiver === "frame";
+        vi.mocked(isContentScript).mockReturnValueOnce(isCs);
+        vi.mocked(isBackground).mockReturnValueOnce(receiver === "background");
+        vi.stubGlobal("location", {
+            origin: isCs ? "http://example.com" : "chrome-extension://extension-id",
+        });
+        const result = getActionForMessage(senders[from], targets[to], thisTarget[receiver]);
+        assert(result === expected, `"${receiver}" got message for "${to}" and decided to ${result.toUpperCase()} instead of ${expected.toUpperCase()}`);
+    });
+});

package/distribution/thisTarget.d.ts

@@ -1,6 +1,29 @@
-import { type AnyTarget, type TopLevelFrame, type Message, type MessengerMeta, type Sender, type FrameTarget } from "./types.js";
-export declare function getActionForMessage(from: Sender, message: Message): "respond" | "forward" | "ignore";
+import { type AnyTarget, type KnownTarget, type TopLevelFrame, type MessengerMeta, type FrameTarget } from "./types.js";
+/**
+ * @file This file exists because `runtime.sendMessage` acts as a broadcast to
+ * all open extension pages, so the receiver needs a way to figure out if the
+ * message was intended for them.
+ *
+ * If the requested target only includes a `page` (URL), then it can be determined
+ * immediately. If the target also specifies a tab, like `{tabId: 1, page: '/sidebar.html'}`,
+ * then the receiving target needs to fetch the tab information via `__getTabData`.
+ *
+ * `__getTabData` is called automatically when `webext-messenger` is imported in
+ * a context that requires this logic (most extension:// pages).
+ *
+ * If a broadcast message with `tabId` target is received before `__getTabData` is "received",
+ * the message will be ignored and it can be retried. If `__getTabData` somehow fails,
+ * the target will forever ignore any messages that require the `tabId`. In that case,
+ * an error would be thrown once and will be visible in the console, uncaught.
+ *
+ * Content scripts do not use this logic at all at the moment because they're
+ * always targeted via `tabId/frameId` combo and `tabs.sendMessage`.
+ */
+export declare const thisTarget: KnownTarget;
+declare let tabDataStatus: "needed" | "pending" | "received" | "not-needed" | "error";
+export declare function getTabDataStatus(): typeof tabDataStatus;
 export declare function __getTabData(this: MessengerMeta): AnyTarget;
 export declare function getThisFrame(): Promise<FrameTarget>;
 export declare function getTopLevelFrame(): Promise<TopLevelFrame>;
 export declare function initPrivateApi(): void;
+export {};

package/distribution/thisTarget.js

@@ -1,8 +1,7 @@
-import { getContextName, isBackground, isContentScript, isExtensionContext, } from "webext-detect-page";
+import { getContextName, isBackground, isExtensionContext, } from "webext-detect-page";
 import { messenger } from "./sender.js";
 import { registerMethods } from "./receiver.js";
 import { MessengerError, once } from "./shared.js";
-import { log } from "./logging.js";
 /**
  * @file This file exists because `runtime.sendMessage` acts as a broadcast to
  * all open extension pages, so the receiver needs a way to figure out if the
@@ -26,7 +25,7 @@ import { log } from "./logging.js";
 // Soft warning: Race conditions are possible.
 // This CANNOT be awaited because waiting for it means "I will handle the message."
 // If a message is received before this is ready, it will just have to be ignored.
-const thisTarget = isBackground()
+export const thisTarget = isBackground()
     ? { page: "background" }
     : {
         get page() {
@@ -41,57 +40,8 @@ const thisTarget = isBackground()
 let tabDataStatus = 
 // The background page doesn't have a tab
 isBackground() ? "not-needed" : "needed";
-function compareTargets(to, thisTarget) {
-    for (const [key, value] of Object.entries(to)) {
-        if (thisTarget[key] === value) {
-            continue;
-        }
-        if (key !== "page") {
-            return false;
-        }
-        const toUrl = new URL(to.page, location.origin);
-        const thisUrl = new URL(thisTarget.page, location.origin);
-        if (toUrl.pathname !== thisUrl.pathname) {
-            return false;
-        }
-        for (const [parameterKey, parameterValue] of toUrl.searchParams) {
-            if (thisUrl.searchParams.get(parameterKey) !== parameterValue) {
-                return false;
-            }
-        }
-    }
-    return true;
-}
-// TODO: Test this in Jest, outside the browser
-export function getActionForMessage(from, message) {
-    // Clone object because we're editing it
-    const to = { ...message.target };
-    if (to.page === "any") {
-        return "respond";
-    }
-    // Content scripts only receive messages that are meant for them. In the future
-    // they'll also forward them, but that still means they need to be handled here.
-    if (isContentScript()) {
-        return "respond";
-    }
-    // We're in an extension page, but the target is not one.
-    if (!to.page) {
-        return "forward";
-    }
-    // Set "this" tab to the current tabId
-    if (to.tabId === "this" && thisTarget.tabId === from.tab?.id) {
-        to.tabId = thisTarget.tabId;
-    }
-    // Every `target` key must match `thisTarget`
-    const isThisTarget = compareTargets(to, thisTarget);
-    if (!isThisTarget) {
-        log.debug(message.type, "🤫 ignored due to target mismatch", {
-            requestedTarget: to,
-            thisTarget,
-            tabDataStatus,
-        });
-    }
-    return isThisTarget ? "respond" : "ignore";
+export function getTabDataStatus() {
+    return tabDataStatus;
 }
 const storeTabData = once(async () => {
     if (tabDataStatus !== "needed") {
@@ -99,9 +49,7 @@ const storeTabData = once(async () => {
     }
     try {
         tabDataStatus = "pending";
-        Object.assign(thisTarget, {
-            ...(await messenger("__getTabData", {}, { page: "any" })),
-        });
+        Object.assign(thisTarget, await messenger("__getTabData", {}, { page: "any" }));
         tabDataStatus = "received";
     }
     catch (error) {
@@ -119,7 +67,8 @@ export async function getThisFrame() {
     if (typeof tabId !== "number" || typeof frameId !== "number") {
         let moreInfo = "(error retrieving context information)";
         try {
-            moreInfo = `(context: ${getContextName()}, url: ${globalThis.location?.href})`;
+            moreInfo = `(context: ${getContextName()}, url: ${globalThis.location
+                ?.href})`;
         }
         catch { }
         throw new TypeError(`This target is not in a frame ${moreInfo}`);

package/distribution/types.d.ts

@@ -57,7 +57,7 @@ export type MessengerMessage = Message & {
 };
 export interface AnyTarget {
     tabId?: number | "this";
-    frameId?: number;
+    frameId?: number | "allFrames";
     page?: string;
 }
 export interface TopLevelFrame {
@@ -75,7 +75,7 @@ export interface KnownTarget {
 }
 export interface Target {
     tabId: number;
-    frameId?: number;
+    frameId?: number | "allFrames";
 }
 export interface PageTarget {
     tabId?: number | "this";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "webext-messenger",
-  "version": "0.25.2",
+  "version": "0.27.0",
   "description": "Browser Extension component messaging framework",
   "keywords": [],
   "repository": "pixiebrix/webext-messenger",
@@ -9,7 +9,7 @@
   "type": "module",
   "exports": {
     ".": {
-      "types": "./distribution/index.js",
+      "types": "./distribution/index.d.ts",
       "default": "./distribution/index.js"
     },
     "./*": "./distribution/*"
@@ -19,16 +19,17 @@
     "demo:watch": "parcel watch --no-cache --no-hmr",
     "demo:build": "parcel build --no-cache --no-scope-hoist",
     "prepack": "tsc --sourceMap false",
-    "test": "eslint . && tsc --noEmit",
+    "test": "run-p test:unit lint build demo:build",
+    "test:unit": "vitest run",
     "lint": "eslint .",
     "fix": "eslint . --fix",
     "watch": "tsc --watch"
   },
   "dependencies": {
     "p-retry": "^6.2.0",
-    "serialize-error": "^11.0.2",
-    "type-fest": "^4.10.2",
-    "webext-detect-page": "^5.0.0"
+    "serialize-error": "^11.0.3",
+    "type-fest": "^4.13.0",
+    "webext-detect-page": "^5.0.1"
   },
   "@parcel/resolver-default": {
     "packageExports": true
@@ -36,20 +37,21 @@
   "devDependencies": {
     "@parcel/config-webextension": "^2.11.0",
     "@sindresorhus/tsconfig": "^5.0.0",
-    "@types/chrome": "^0.0.259",
+    "@types/chrome": "^0.0.263",
     "@types/tape": "^5.6.4",
     "@types/webextension-polyfill": "^0.10.7",
     "buffer": "^6.0.3",
-    "eslint": "^8.56.0",
-    "eslint-config-pixiebrix": "^0.34.1",
+    "eslint": "^8.57.0",
+    "eslint-config-pixiebrix": "^0.37.2",
     "events": "^3.3.0",
     "npm-run-all": "^4.1.5",
     "parcel": "^2.11.0",
     "path-browserify": "^1.0.1",
     "process": "^0.11.10",
     "stream-browserify": "^3.0.0",
-    "tape": "^5.7.4",
-    "typescript": "^5.3.3",
+    "tape": "^5.7.5",
+    "typescript": "^5.4.2",
+    "vitest": "^1.4.0",
     "webext-content-scripts": "^2.6.1",
     "webextension-polyfill": "^0.10.0"
   },