webext-messenger 0.34.0 → 0.35.0

package/distribution/receiver.js

@@ -42,7 +42,7 @@ function onMessageListener(message, sender, sendResponse) {
         return;
     }
     const { type, target, args, options = {} } = message;
-    const { trace = [], seq } = options;
+    const { trace = [], seq, retry } = options;
     if (action === "forward") {
         log.debug(type, seq, "🔀 forwarded", { sender, target });
     }
@@ -57,7 +57,7 @@ function onMessageListener(message, sender, sendResponse) {
     (async () => {
         try {
             trace.push(sender);
-            const value = await prepareResponse(message, action, { trace });
+            const value = await prepareResponse(message, action, { trace, retry });
             log.debug(type, seq, "↗️ responding", { value });
             sendResponse({ __webextMessenger, value });
         }
@@ -87,17 +87,18 @@ function onMessageExternalListener(message, sender, sendResponse) {
     });
 }
 /** Generates the value or error to return to the sender; does not include further messaging logic */
-async function prepareResponse(message, action, meta) {
+async function prepareResponse(message, action, options) {
     const { type, target, args } = message;
     if (action === "forward") {
-        return messenger(type, meta, target, ...args);
+        return messenger(type, options, target, ...args);
     }
     const localHandler = handlers.get(type);
     if (localHandler) {
         if ("extensionId" in target && !externalMethods.has(type)) {
             throw new MessengerError(`The ${type} handler is registered in ${getContextName()} for internal use only`);
         }
-        return localHandler.apply(meta, args);
+        const { trace = [] } = options;
+        return localHandler.apply({ trace }, args);
     }
     if (didUserRegisterMethods()) {
         throw new MessengerError(`No handler registered for ${type} in ${getContextName()}`);

package/distribution/sender.js

@@ -1,10 +1,11 @@
-import pRetry from "p-retry";
-import { isBackground, isExtensionContext } from "webext-detect";
+import { isExtensionContext } from "webext-detect";
 import { deserializeError } from "serialize-error";
 import { isObject, MessengerError, ExtensionNotFoundError, __webextMessenger, } from "./shared.js";
 import { log } from "./logging.js";
 import { handlers } from "./handlers.js";
 import { events } from "./events.js";
+import { compareTargets } from "./targetLogic.js";
+import { thisTarget } from "./thisTarget.js";
 const _errorNonExistingTarget = "Could not establish connection. Receiving end does not exist.";
 const _errorTargetClosedEarly = "A listener indicated an asynchronous response by returning true, but the message channel closed before a response was received";
 export const errorTargetClosedEarly = "The target was closed before receiving a response";
@@ -20,6 +21,28 @@ function attemptLog(attemptCount) {
 function wasContextInvalidated() {
     return !chrome.runtime?.id;
 }
+function getErrorMessage(error) {
+    if (error && typeof error === "object" && "message" in error) {
+        return String(error.message);
+    }
+    return undefined;
+}
+function shouldRetryError(error, target) {
+    const message = getErrorMessage(error);
+    // Don't retry sending to the background page unless it really hasn't loaded yet
+    if (target.page !== "background" && error instanceof MessengerError) {
+        return true;
+    }
+    // Page or its content script not yet loaded
+    if (message === _errorNonExistingTarget) {
+        return true;
+    }
+    // `registerMethods` not yet loaded
+    if (message?.startsWith("No handlers registered in ")) {
+        return true;
+    }
+    return false;
+}
 function makeMessage(type, args, target, options) {
     return {
         __webextMessenger,
@@ -39,102 +62,108 @@ function manageConnection(type, { seq, isNotification, retry }, target, sendMess
     });
 }
 async function manageMessage(type, target, seq, retry, sendMessage) {
-    // TODO: Split this up a bit because it's too long. Probably drop p-retry
-    const response = await pRetry(async (attemptCount) => {
-        const response = await sendMessage(attemptCount);
-        if (isMessengerResponse(response)) {
-            return response;
-        }
-        // If no one answers, `response` will be `undefined`
-        // If the target does not have any `onMessage` listener at all, it will throw
-        // Possible:
-        // - Any target exists and has onMessage handler, but never handled the message
-        // - Extension page exists and has Messenger, but never handled the message (Messenger in Runtime ignores messages when the target isn't found)
-        // Not possible:
-        // - Tab exists and has Messenger, but never handled the message (Messenger in CS always handles messages)
-        // - Any target exists, but Messenger didn't have the specific Type handler (The receiving Messenger will throw an error)
-        // - No targets exist (the browser immediately throws "Could not establish connection. Receiving end does not exist.")
-        if (response === undefined) {
-            if ("page" in target) {
-                throw new MessengerError(`The target ${JSON.stringify(target)} for ${type} was not found`);
+    const startTime = Date.now();
+    const maxRetryTime = 4000;
+    const minTimeout = 100;
+    const factor = 1.3;
+    // Safety cap to avoid infinite loops, generally stops at 11 with current setting
+    // MUST BE UPDATED if maxRetryTime, minTimeout or factor are changed
+    const maxRetryCount = 15;
+    let attemptCount = 0;
+    let currentTimeout = minTimeout;
+    while (attemptCount < maxRetryCount) {
+        attemptCount++;
+        try {
+            // eslint-disable-next-line no-await-in-loop -- Necessary for retry logic
+            const response = await sendMessage(attemptCount);
+            if (isMessengerResponse(response)) {
+                if ("error" in response) {
+                    log.debug(type, seq, "↘️ replied with error", response.error);
+                    throw deserializeError(response.error);
+                }
+                log.debug(type, seq, "↘️ replied successfully", response.value);
+                return response.value;
+            }
+            // If no one answers, `response` will be `undefined`
+            // If the target does not have any `onMessage` listener at all, it will throw
+            // Possible:
+            // - Any target exists and has onMessage handler, but never handled the message
+            // - Extension page exists and has Messenger, but never handled the message (Messenger in Runtime ignores messages when the target isn't found)
+            // Not possible:
+            // - Tab exists and has Messenger, but never handled the message (Messenger in CS always handles messages)
+            // - Any target exists, but Messenger didn't have the specific Type handler (The receiving Messenger will throw an error)
+            // - No targets exist (the browser immediately throws "Could not establish connection. Receiving end does not exist.")
+            if (response === undefined) {
+                if ("page" in target) {
+                    throw new MessengerError(`The target ${JSON.stringify(target)} for ${type} was not found`);
+                }
+                throw new MessengerError(`Messenger was not available in the target ${JSON.stringify(target)} for ${type}`);
             }
-            throw new MessengerError(`Messenger was not available in the target ${JSON.stringify(target)} for ${type}`);
+            // Possible:
+            // - Non-Messenger handler responded
+            throw new MessengerError(`Conflict: The message ${type} was handled by a third-party listener`);
         }
-        // Possible:
-        // - Non-Messenger handler responded
-        throw new MessengerError(`Conflict: The message ${type} was handled by a third-party listener`);
-    }, {
-        minTimeout: 100,
-        factor: 1.3,
-        // Do not set this to undefined or Infinity, it doesn't work the same way
-        ...(retry ? {} : { retries: 0 }),
-        maxRetryTime: 4000,
-        async onFailedAttempt(error) {
+        catch (error) {
+            const errorMessage = getErrorMessage(error);
             events.dispatchEvent(new CustomEvent("failed-attempt", {
                 detail: {
                     type,
                     seq,
                     target,
                     error,
-                    attemptCount: error.attemptNumber,
+                    attemptCount,
                 },
             }));
-            if ("extensionId" in target &&
-                error.message === _errorNonExistingTarget) {
-                // The extension is not available and it will not be. Do not retry.
+            // Check for non-retryable errors
+            if ("extensionId" in target && errorMessage === _errorNonExistingTarget) {
                 throw new ExtensionNotFoundError(errorExtensionNotFound.replace("$ID", target.extensionId));
             }
             if (isExtensionContext() && wasContextInvalidated()) {
-                // The error matches the native context invalidated error
-                // *.sendMessage() might fail with a message-specific error that is less useful,
-                // like "Sender closed without responding"
                 throw new Error("Extension context invalidated.");
             }
-            if (error.message === _errorTargetClosedEarly) {
+            if (errorMessage === _errorTargetClosedEarly) {
                 throw new Error(errorTargetClosedEarly);
             }
-            if (!(
-            // If NONE of these conditions is true, stop retrying
-            // Don't retry sending to the background page unless it really hasn't loaded yet
-            ((target.page !== "background" &&
-                error instanceof MessengerError) ||
-                // Page or its content script not yet loaded
-                error.message === _errorNonExistingTarget ||
-                // `registerMethods` not yet loaded
-                String(error.message).startsWith("No handlers registered in ")))) {
+            if (!shouldRetryError(error, target)) {
                 throw error;
             }
+            // Check if tab is still valid
             if (chrome.tabs && typeof target.tabId === "number") {
+                let tabInfo;
                 try {
-                    const tabInfo = await chrome.tabs.get(target.tabId);
-                    if (tabInfo.discarded) {
-                        throw new Error(errorTabWasDiscarded);
-                    }
+                    // eslint-disable-next-line no-await-in-loop -- Necessary to check tab status during retry
+                    tabInfo = await chrome.tabs.get(target.tabId);
                 }
                 catch {
                     throw new Error(errorTabDoesntExist);
                 }
+                if (tabInfo.discarded) {
+                    throw new Error(errorTabWasDiscarded);
+                }
             }
-            log.debug(type, seq, "will retry. Attempt", error.attemptNumber);
-        },
-    }).catch((error) => {
-        if (error &&
-            typeof error === "object" &&
-            "message" in error &&
-            error?.message === _errorNonExistingTarget) {
-            throw new MessengerError(`The target ${JSON.stringify(target)} for ${type} was not found`);
+            // Check if we should stop retrying
+            const elapsedTime = Date.now() - startTime;
+            if (!retry || elapsedTime >= maxRetryTime) {
+                if (errorMessage === _errorNonExistingTarget) {
+                    throw new MessengerError(`The target ${JSON.stringify(target)} for ${type} was not found`);
+                }
+                events.dispatchEvent(new CustomEvent("attempts-exhausted", {
+                    detail: { type, seq, target, error },
+                }));
+                throw error;
+            }
+            log.debug(type, seq, "will retry", attemptLog(attemptCount));
+            // Wait before retrying with exponential backoff
+            const waitTime = currentTimeout;
+            // eslint-disable-next-line no-await-in-loop -- Necessary for retry delay
+            await new Promise((resolve) => {
+                setTimeout(resolve, waitTime);
+            });
+            currentTimeout = Math.floor(currentTimeout * factor);
         }
-        events.dispatchEvent(new CustomEvent("attempts-exhausted", {
-            detail: { type, seq, target, error },
-        }));
-        throw error;
-    });
-    if ("error" in response) {
-        log.debug(type, seq, "↘️ replied with error", response.error);
-        throw deserializeError(response.error);
     }
-    log.debug(type, seq, "↘️ replied successfully", response.value);
-    return response.value;
+    // If you reach this, refer to note above `maxRetryCount` definition
+    throw new MessengerError("Exceeded maximum retry attempts. This suggests a low `maxRetryCount`");
 }
 // 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
@@ -157,16 +186,17 @@ function messenger(type, options, target, ...args) {
         };
         return manageConnection(type, options, target, sendMessage);
     }
+    // Use local methods if the target matches the current context
+    if (compareTargets(target, thisTarget)) {
+        const handler = handlers.get(type);
+        if (handler) {
+            log.warn(type, seq, "is being handled locally");
+            return handler.apply({ trace: [] }, args);
+        }
+        throw new MessengerError("No handler registered locally for " + type);
+    }
     // Message goes to extension page
     if ("page" in target) {
-        if (target.page === "background" && isBackground()) {
-            const handler = handlers.get(type);
-            if (handler) {
-                log.warn(type, seq, "is being handled locally");
-                return handler.apply({ trace: [] }, args);
-            }
-            throw new MessengerError("No handler registered locally for " + type);
-        }
         const sendMessage = async (attemptCount) => {
             log.debug(type, seq, "↗️ sending message to runtime", attemptLog(attemptCount));
             return chrome.runtime.sendMessage(makeMessage(type, args, target, options));

package/distribution/sender.test.d.ts

@@ -0,0 +1,6 @@
+declare global {
+    interface MessengerMethods {
+        testMethod: () => Promise<string>;
+    }
+}
+export {};

package/distribution/sender.test.js

@@ -0,0 +1,160 @@
+/* eslint-disable @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-argument, @typescript-eslint/naming-convention */
+import { describe, test, expect, vi, beforeEach } from "vitest";
+import { handlers } from "./handlers.js";
+import * as thisTargetModule from "./thisTarget.js";
+// Mock dependencies
+vi.mock("webext-detect", () => ({
+    isBackground: vi.fn(() => false),
+    isExtensionContext: vi.fn(() => true),
+    isOffscreenDocument: vi.fn(() => false),
+    isContentScript: vi.fn(() => true),
+}));
+vi.mock("./logging.js", () => ({
+    log: {
+        debug: vi.fn(),
+        warn: vi.fn(),
+    },
+}));
+vi.mock("./events.js", () => ({
+    events: {
+        dispatchEvent: vi.fn(),
+    },
+}));
+// Mock chrome APIs - simulate content script environment (no chrome.tabs)
+globalThis.chrome = {
+    runtime: {
+        id: "test-extension-id",
+        sendMessage: vi.fn(),
+    },
+    // Note: chrome.tabs is undefined in content scripts
+};
+describe("messenger with tab targets and local methods", () => {
+    beforeEach(() => {
+        vi.clearAllMocks();
+        handlers.clear();
+    });
+    test("should use local method when targeting same tab and frame", async () => {
+        // Setup: Set thisTarget to have tabId: 1, frameId: 0
+        const mockThisTarget = {
+            tabId: 1,
+            frameId: 0,
+            page: "test",
+        };
+        vi.spyOn(thisTargetModule, "thisTarget", "get").mockReturnValue(mockThisTarget);
+        // Register a local handler
+        const mockHandler = vi.fn(async () => "local result");
+        handlers.set("testMethod", mockHandler);
+        // Import messenger after mocks are set up
+        const { messenger } = await import("./sender.js");
+        // Test: Send message to same tab and frame
+        const result = await messenger("testMethod", {}, { tabId: 1, frameId: 0 });
+        // Verify: Handler was called locally
+        expect(mockHandler).toHaveBeenCalledOnce();
+        expect(mockHandler).toHaveBeenCalledWith();
+        expect(result).toBe("local result");
+        // Verify: No message was sent via chrome.runtime.sendMessage
+        expect(chrome.runtime.sendMessage).not.toHaveBeenCalled();
+    });
+    test("should send message when targeting different tab", async () => {
+        // Setup: Set thisTarget to have tabId: 1, frameId: 0
+        const mockThisTarget = {
+            tabId: 1,
+            frameId: 0,
+            page: "test",
+        };
+        vi.spyOn(thisTargetModule, "thisTarget", "get").mockReturnValue(mockThisTarget);
+        // Register a local handler (should not be used)
+        const mockHandler = vi.fn(async () => "local result");
+        handlers.set("testMethod", mockHandler);
+        // Mock chrome.runtime.sendMessage to return a messenger response
+        vi.mocked(chrome.runtime.sendMessage).mockResolvedValue({
+            __webextMessenger: true,
+            value: "remote result",
+        });
+        // Import messenger after mocks are set up
+        const { messenger } = await import("./sender.js");
+        // Test: Send message to different tab
+        const result = await messenger("testMethod", {}, { tabId: 2, frameId: 0 });
+        // Verify: Message was sent via chrome.runtime.sendMessage
+        expect(chrome.runtime.sendMessage).toHaveBeenCalledOnce();
+        expect(result).toBe("remote result");
+        // Verify: Local handler was not called
+        expect(mockHandler).not.toHaveBeenCalled();
+    });
+    test("should send message when targeting different frame in same tab", async () => {
+        // Setup: Set thisTarget to have tabId: 1, frameId: 0
+        const mockThisTarget = {
+            tabId: 1,
+            frameId: 0,
+            page: "test",
+        };
+        vi.spyOn(thisTargetModule, "thisTarget", "get").mockReturnValue(mockThisTarget);
+        // Register a local handler (should not be used)
+        const mockHandler = vi.fn(async () => "local result");
+        handlers.set("testMethod", mockHandler);
+        // Mock chrome.runtime.sendMessage to return a messenger response
+        vi.mocked(chrome.runtime.sendMessage).mockResolvedValue({
+            __webextMessenger: true,
+            value: "remote result",
+        });
+        // Import messenger after mocks are set up
+        const { messenger } = await import("./sender.js");
+        // Test: Send message to different frame in same tab
+        const result = await messenger("testMethod", {}, { tabId: 1, frameId: 1 });
+        // Verify: Message was sent via chrome.runtime.sendMessage
+        expect(chrome.runtime.sendMessage).toHaveBeenCalledOnce();
+        expect(result).toBe("remote result");
+        // Verify: Local handler was not called
+        expect(mockHandler).not.toHaveBeenCalled();
+    });
+    test("should send message when targeting allFrames", async () => {
+        // Setup: Set thisTarget to have tabId: 1, frameId: 0
+        const mockThisTarget = {
+            tabId: 1,
+            frameId: 0,
+            page: "test",
+        };
+        vi.spyOn(thisTargetModule, "thisTarget", "get").mockReturnValue(mockThisTarget);
+        // Register a local handler (should not be used for allFrames)
+        const mockHandler = vi.fn(async () => "local result");
+        handlers.set("testMethod", mockHandler);
+        // Mock chrome.runtime.sendMessage to return a messenger response
+        vi.mocked(chrome.runtime.sendMessage).mockResolvedValue({
+            __webextMessenger: true,
+            value: "remote result",
+        });
+        // Import messenger after mocks are set up
+        const { messenger } = await import("./sender.js");
+        // Test: Send message to allFrames in same tab
+        const result = await messenger("testMethod", {}, { tabId: 1, frameId: "allFrames" });
+        // Verify: Message was sent via chrome.runtime.sendMessage
+        expect(chrome.runtime.sendMessage).toHaveBeenCalledOnce();
+        expect(result).toBe("remote result");
+        // Verify: Local handler was not called
+        expect(mockHandler).not.toHaveBeenCalled();
+    });
+    test("should throw error when no local handler registered for same tab/frame", async () => {
+        // Setup: Set thisTarget to have tabId: 1, frameId: 0
+        const mockThisTarget = {
+            tabId: 1,
+            frameId: 0,
+            page: "test",
+        };
+        vi.spyOn(thisTargetModule, "thisTarget", "get").mockReturnValue(mockThisTarget);
+        // No handler registered
+        // Import messenger and MessengerError after mocks are set up
+        const { messenger } = await import("./sender.js");
+        const { MessengerError } = await import("./shared.js");
+        // Test: Send message to same tab and frame without handler
+        try {
+            await messenger("testMethod", {}, { tabId: 1, frameId: 0 });
+            expect.fail("Should have thrown an error");
+        }
+        catch (error) {
+            expect(error).toBeInstanceOf(MessengerError);
+            expect(error.message).toBe("No handler registered locally for testMethod");
+        }
+        // Verify: No message was sent via chrome.runtime.sendMessage
+        expect(chrome.runtime.sendMessage).not.toHaveBeenCalled();
+    });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "webext-messenger",
-  "version": "0.34.0",
+  "version": "0.35.0",
   "description": "Browser Extension component messaging framework",
   "keywords": [],
   "repository": "pixiebrix/webext-messenger",
@@ -28,7 +28,6 @@
   },
   "dependencies": {
     "one-event": "^4.3.0",
-    "p-retry": "^6.2.1",
     "serialize-error": "^12.0.0",
     "type-fest": "^5.0.1",
     "webext-detect": "^5.3.2"
@@ -37,16 +36,16 @@
     "packageExports": true
   },
   "devDependencies": {
-    "@parcel/config-webextension": "^2.15.4",
+    "@parcel/config-webextension": "^2.16.0",
     "@sindresorhus/tsconfig": "^8.0.1",
-    "@types/chrome": "^0.1.16",
+    "@types/chrome": "^0.1.22",
     "@types/tape": "^5.8.1",
     "buffer": "^6.0.3",
     "eslint": "^8.57.0",
     "eslint-config-pixiebrix": "^0.41.1",
     "events": "^3.3.0",
     "npm-run-all": "^4.1.5",
-    "parcel": "^2.15.4",
+    "parcel": "^2.16.0",
     "path-browserify": "^1.0.1",
     "process": "^0.11.10",
     "stream-browserify": "^3.0.0",