webext-messenger 0.30.0 → 0.32.0-0

package/distribution/logging.js

@@ -1,4 +1,3 @@
-/* Warning: Do not use import browser-polyfill directly or indirectly */
 // .bind preserves the call location in the console
 const debug = console.debug.bind(console, "Messenger:");
 const warn = console.warn.bind(console, "Messenger:");

package/distribution/receiver.d.ts

@@ -1,5 +1,7 @@
-import { type Message, type MessengerMeta } from "./types.js";
+import { type Message, type ExternalMessage, type MessengerMeta } from "./types.js";
 export declare function isMessengerMessage(message: unknown): message is Message;
+export declare function isExternalMessengerMessage(message: unknown): message is ExternalMessage;
 export declare function registerMethods(methods: Partial<MessengerMethods>): void;
+export declare function allowExternalUse(...types: Array<keyof MessengerMethods>): void;
 /** Ensure/document that the current function was called via Messenger */
 export declare function assertMessengerCall(_this: MessengerMeta): asserts _this is MessengerMeta;

package/distribution/receiver.js

@@ -1,19 +1,35 @@
 import { serializeError } from "serialize-error";
-import { getContextName } from "webext-detect";
+import { getContextName, isBackground } from "webext-detect";
 import { messenger } from "./sender.js";
 import { isObject, MessengerError, __webextMessenger } from "./shared.js";
 import { log } from "./logging.js";
 import { getActionForMessage } from "./targetLogic.js";
 import { didUserRegisterMethods, handlers } from "./handlers.js";
 import { getTabDataStatus, thisTarget } from "./thisTarget.js";
+const externalMethods = new Set();
 export function isMessengerMessage(message) {
     return (isObject(message) &&
         typeof message["type"] === "string" &&
         message["__webextMessenger"] === true &&
         Array.isArray(message["args"]));
 }
-// MUST NOT be `async` or Promise-returning-only
-function onMessageListener(message, sender) {
+export function isExternalMessengerMessage(message) {
+    return (isObject(message) &&
+        typeof message["type"] === "string" &&
+        message["__webextMessenger"] === true &&
+        Array.isArray(message["args"]) &&
+        isObject(message["target"]) &&
+        Object.keys(message["target"]).length === 1 && // Ensure it's *only* `extensionId`
+        typeof message["target"]["extensionId"] === "string");
+}
+/**
+ * Decides what to do with a message and sends a response (value or error) back to the sender.
+ *
+ * @warn This function cannot return a Promise.
+ * @warn Limit the amount of logic here because errors won't make it to `sendResponse`
+ */
+//
+function onMessageListener(message, sender, sendResponse) {
     if (!isMessengerMessage(message)) {
         // TODO: Add test for this eventuality: ignore unrelated messages
         return;
@@ -28,21 +44,10 @@ function onMessageListener(message, sender) {
         });
         return;
     }
-    return handleMessage(message, sender, action);
-}
-// This function can only be called when the message *will* be handled locally.
-// Returning "undefined" or throwing an error will still handle it.
-async function handleMessage(message, sender, 
-// Once messages reach this function they cannot be "ignored", they're already being handled
-action) {
     const { type, target, args, options = {} } = message;
     const { trace = [], seq } = options;
-    trace.push(sender);
-    const meta = { trace };
-    let handleMessage;
     if (action === "forward") {
         log.debug(type, seq, "🔀 forwarded", { sender, target });
-        handleMessage = async () => messenger(type, meta, target, ...args);
     }
     else {
         log.debug(type, seq, "↘️ received in", getContextName(), {
@@ -50,24 +55,56 @@ action) {
             args,
             wasForwarded: trace.length > 1,
         });
-        const localHandler = handlers.get(type);
-        if (!localHandler) {
-            if (!didUserRegisterMethods()) {
-                // TODO: Test the handling of __getTabData in contexts that have no registered methods
-                // https://github.com/pixiebrix/webext-messenger/pull/82
-                throw new MessengerError(`No handlers registered in ${getContextName()}`);
-            }
-            throw new MessengerError(`No handler registered for ${type} in ${getContextName()}`);
+    }
+    // Prepare the response asynchronously because the listener must return `true` synchronously
+    (async () => {
+        try {
+            trace.push(sender);
+            const value = await prepareResponse(message, action, { trace });
+            log.debug(type, seq, "↗️ responding", { value });
+            sendResponse({ __webextMessenger, value });
+        }
+        catch (error) {
+            log.debug(type, seq, "↗️ responding", { error });
+            sendResponse({ __webextMessenger, error: serializeError(error) });
         }
-        handleMessage = async () => localHandler.apply(meta, args);
+    })();
+    // This indicates that the message is being handled and a response will be sent asynchronously
+    // TODO: Just return a promise if this is ever implemented https://issues.chromium.org/issues/40753031
+    return true;
+}
+// Do not remove.
+// Early validation to ensure that the message matches the specific allowed target
+// before letting it flow into the rest of messenger.
+function onMessageExternalListener(message, sender, sendResponse) {
+    if (isExternalMessengerMessage(message) &&
+        message.target.extensionId === chrome.runtime.id) {
+        return onMessageListener(message, sender, sendResponse);
     }
-    const response = await handleMessage().then((value) => ({ value }), (error) => ({
-        // Errors must be serialized because the stack traces are currently lost on Chrome
-        // and https://github.com/mozilla/webextension-polyfill/issues/210
-        error: serializeError(error),
-    }));
-    log.debug(type, seq, "↗️ responding", response);
-    return { ...response, __webextMessenger };
+    log.debug("Ignored external message", {
+        message,
+        sender,
+    });
+}
+/** Generates the value or error to return to the sender; does not include further messaging logic */
+async function prepareResponse(message, action, meta) {
+    const { type, target, args } = message;
+    if (action === "forward") {
+        return messenger(type, meta, target, ...args);
+    }
+    const localHandler = handlers.get(type);
+    if (localHandler) {
+        if ("extensionId" in target && !externalMethods.has(type)) {
+            throw new MessengerError(`${type} is not allowed to be called externally in ${getContextName()}`);
+        }
+        return localHandler.apply(meta, args);
+    }
+    if (didUserRegisterMethods()) {
+        throw new MessengerError(`No handler registered for ${type} in ${getContextName()}`);
+    }
+    // TODO: Test the handling of __getTabData in contexts that have no registered methods
+    // https://github.com/pixiebrix/webext-messenger/pull/82
+    throw new MessengerError(`No handlers registered in ${getContextName()}`);
 }
 export function registerMethods(methods) {
     for (const [type, method] of Object.entries(methods)) {
@@ -77,7 +114,16 @@ export function registerMethods(methods) {
         log.debug("Registered", type);
         handlers.set(type, method);
     }
-    browser.runtime.onMessage.addListener(onMessageListener);
+    chrome.runtime.onMessage.addListener(onMessageListener);
+    // Only handle direct-to-background messages for now
+    if (isBackground()) {
+        chrome.runtime.onMessageExternal.addListener(onMessageExternalListener);
+    }
+}
+export function allowExternalUse(...types) {
+    for (const type of types) {
+        externalMethods.add(type);
+    }
 }
 /** Ensure/document that the current function was called via Messenger */
 export function assertMessengerCall(_this) { }

package/distribution/sender.d.ts

@@ -1,15 +1,15 @@
-import { type PublicMethod, type PublicMethodWithTarget, type Options, type Target, type PageTarget } from "./types.js";
+import { type PublicMethod, type PublicMethodWithTarget, type Options, type AnySpecificTarget, type PageTarget } from "./types.js";
 import { type Promisable, type SetReturnType } from "type-fest";
 export declare const errorTargetClosedEarly = "The target was closed before receiving a response";
 export declare const errorTabDoesntExist = "The tab doesn't exist";
 export declare const errorTabWasDiscarded = "The tab was discarded";
 declare function messenger<Type extends keyof MessengerMethods, Method extends MessengerMethods[Type]>(type: Type, options: {
     isNotification: true;
-}, target: Target | PageTarget, ...args: Parameters<Method>): void;
-declare function messenger<Type extends keyof MessengerMethods, Method extends MessengerMethods[Type], ReturnValue extends Promise<ReturnType<Method>>>(type: Type, options: Options, target: Target | PageTarget, ...args: Parameters<Method>): ReturnValue;
-declare function getMethod<Type extends keyof MessengerMethods, Method extends MessengerMethods[Type], PublicMethodType extends PublicMethod<Method>>(type: Type, target: Promisable<Target | PageTarget>): PublicMethodType;
+}, target: AnySpecificTarget, ...args: Parameters<Method>): void;
+declare function messenger<Type extends keyof MessengerMethods, Method extends MessengerMethods[Type], ReturnValue extends Promise<ReturnType<Method>>>(type: Type, options: Options, target: AnySpecificTarget, ...args: Parameters<Method>): ReturnValue;
+declare function getMethod<Type extends keyof MessengerMethods, Method extends MessengerMethods[Type], PublicMethodType extends PublicMethod<Method>>(type: Type, target: Promisable<AnySpecificTarget>): PublicMethodType;
 declare function getMethod<Type extends keyof MessengerMethods, Method extends MessengerMethods[Type], PublicMethodWithDynamicTarget extends PublicMethodWithTarget<Method>>(type: Type): PublicMethodWithDynamicTarget;
-declare function getNotifier<Type extends keyof MessengerMethods, Method extends MessengerMethods[Type], PublicMethodType extends SetReturnType<PublicMethod<Method>, void>>(type: Type, target: Promisable<Target | PageTarget>): PublicMethodType;
+declare function getNotifier<Type extends keyof MessengerMethods, Method extends MessengerMethods[Type], PublicMethodType extends SetReturnType<PublicMethod<Method>, void>>(type: Type, target: Promisable<AnySpecificTarget>): PublicMethodType;
 declare function getNotifier<Type extends keyof MessengerMethods, Method extends MessengerMethods[Type], PublicMethodWithDynamicTarget extends SetReturnType<PublicMethodWithTarget<Method>, void>>(type: Type): PublicMethodWithDynamicTarget;
 export { messenger, getMethod, getNotifier };
 export declare const backgroundTarget: PageTarget;

package/distribution/sender.js

@@ -6,7 +6,6 @@ import { log } from "./logging.js";
 import { handlers } from "./handlers.js";
 import { events } from "./events.js";
 const _errorNonExistingTarget = "Could not establish connection. Receiving end does not exist.";
-// https://github.com/mozilla/webextension-polyfill/issues/384
 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";
 export const errorTabDoesntExist = "The tab doesn't exist";
@@ -99,9 +98,9 @@ async function manageMessage(type, target, seq, retry, sendMessage) {
                 String(error.message).startsWith("No handlers registered in ")))) {
                 throw error;
             }
-            if (browser.tabs && typeof target.tabId === "number") {
+            if (chrome.tabs && typeof target.tabId === "number") {
                 try {
-                    const tabInfo = await browser.tabs.get(target.tabId);
+                    const tabInfo = await chrome.tabs.get(target.tabId);
                     if (tabInfo.discarded) {
                         throw new Error(errorTabWasDiscarded);
                     }
@@ -142,6 +141,13 @@ let globalSeq = (Date.now() % 100) * 10_000;
 function messenger(type, options, target, ...args) {
     options.seq = globalSeq++;
     const { seq } = options;
+    if ("extensionId" in target) {
+        const sendMessage = async (attemptCount) => {
+            log.debug(type, seq, "↗️ sending message to extension", attemptLog(attemptCount));
+            return chrome.runtime.sendMessage(target.extensionId, makeMessage(type, args, target, options));
+        };
+        return manageConnection(type, options, target, sendMessage);
+    }
     // Message goes to extension page
     if ("page" in target) {
         if (target.page === "background" && isBackground()) {
@@ -154,15 +160,15 @@ function messenger(type, options, target, ...args) {
         }
         const sendMessage = async (attemptCount) => {
             log.debug(type, seq, "↗️ sending message to runtime", attemptLog(attemptCount));
-            return browser.runtime.sendMessage(makeMessage(type, args, target, options));
+            return chrome.runtime.sendMessage(makeMessage(type, args, target, options));
         };
         return manageConnection(type, options, target, sendMessage);
     }
     // Contexts without direct Tab access must go through background
-    if (!browser.tabs) {
+    if (!chrome.tabs) {
         return manageConnection(type, options, target, async (attemptCount) => {
             log.debug(type, seq, "↗️ sending message to runtime", attemptLog(attemptCount));
-            return browser.runtime.sendMessage(makeMessage(type, args, target, options));
+            return chrome.runtime.sendMessage(makeMessage(type, args, target, options));
         });
     }
     // `frameId` must be specified. If missing, the message is sent to every frame
@@ -170,7 +176,7 @@ 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 === "allFrames"
+        return chrome.tabs.sendMessage(tabId, makeMessage(type, args, target, options), frameId === "allFrames"
             ? {}
             : {
                 frameId,

package/distribution/targetLogic.js

@@ -23,6 +23,10 @@ export function compareTargets(to, thisTarget) {
 export function getActionForMessage(from, target, thisTarget) {
     // Clone object because we're editing it
     const to = { ...target };
+    if (to.extensionId) {
+        // Only handle external messages in the background page
+        return isBackground() ? "respond" : "ignore";
+    }
     if (to.page === "any") {
         return "respond";
     }

package/distribution/targetLogic.test.js

@@ -11,11 +11,15 @@ const tab = {
     pinned: false,
     highlighted: true,
     incognito: false,
+    discarded: false,
+    frozen: false,
+    selected: true,
+    autoDiscardable: false,
+    groupId: -1,
 };
 const senders = {
-    background: { page: "background" },
     contentScript: { tab },
-    somePage: { page: "/page.html" },
+    // TODO: Test more senders
 };
 const targets = {
     background: { page: "background" },

package/distribution/types.d.ts

@@ -1,4 +1,3 @@
-import { type Runtime } from "webextension-polyfill";
 import { type Asyncify, type ValueOf } from "type-fest";
 import { type ErrorObject } from "serialize-error";
 /**
@@ -11,7 +10,7 @@ declare global {
         _: Method;
     }
 }
-type WithTarget<Method> = Method extends (...args: infer PreviousArguments) => infer TReturnValue ? (target: Target | PageTarget, ...args: PreviousArguments) => TReturnValue : never;
+type WithTarget<Method> = Method extends (...args: infer PreviousArguments) => infer TReturnValue ? (target: AnySpecificTarget, ...args: PreviousArguments) => TReturnValue : never;
 type ActuallyOmitThisParameter<T> = T extends (...args: infer A) => infer R ? (...args: A) => R : T;
 /** Removes the `this` type and ensure it's always Promised */
 export type PublicMethod<Method extends ValueOf<MessengerMethods>> = Asyncify<ActuallyOmitThisParameter<Method>>;
@@ -44,13 +43,14 @@ export interface Options {
 export type Message<LocalArguments extends Arguments = Arguments> = {
     type: keyof MessengerMethods;
     args: LocalArguments;
-    target: Target | PageTarget;
+    target: AnySpecificTarget;
     /** If the message is being sent to an intermediary receiver, also set the options */
     options?: Options;
 };
-export type Sender = Runtime.MessageSender & {
-    origin?: string;
+export type ExternalMessage = Message & {
+    target: ExtensionTarget;
 };
+export type Sender = chrome.runtime.MessageSender;
 export type MessengerMessage = Message & {
     /** Guarantees that a message is meant to be handled by this library */
     __webextMessenger: true;
@@ -59,6 +59,7 @@ export interface AnyTarget {
     tabId?: number | "this";
     frameId?: number | "allFrames";
     page?: string;
+    extensionId?: string;
 }
 export interface TopLevelFrame {
     tabId: number;
@@ -81,4 +82,8 @@ export interface PageTarget {
     tabId?: number | "this";
     page: string;
 }
+export interface ExtensionTarget {
+    extensionId: string;
+}
+export type AnySpecificTarget = Target | PageTarget | ExtensionTarget;
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "webext-messenger",
-  "version": "0.30.0",
+  "version": "0.32.0-0",
   "description": "Browser Extension component messaging framework",
   "keywords": [],
   "repository": "pixiebrix/webext-messenger",
@@ -16,7 +16,7 @@
   },
   "scripts": {
     "build": "tsc",
-    "demo:watch": "parcel watch --no-cache --no-hmr",
+    "demo:watch": "parcel serve --no-cache --no-hmr",
     "demo:build": "parcel build --no-cache --no-scope-hoist",
     "prepack": "tsc --sourceMap false",
     "test": "run-p test:unit lint build demo:build",
@@ -29,9 +29,8 @@
     "p-event": "^6.0.1",
     "p-retry": "^6.2.1",
     "serialize-error": "^12.0.0",
-    "type-fest": "^4.31.0",
-    "webext-detect": "^5.3.2",
-    "webext-events": "^3.1.1"
+    "type-fest": "^4.36.0",
+    "webext-detect": "^5.3.2"
   },
   "@parcel/resolver-default": {
     "packageExports": true
@@ -39,9 +38,8 @@
   "devDependencies": {
     "@parcel/config-webextension": "^2.11.0",
     "@sindresorhus/tsconfig": "^7.0.0",
-    "@types/chrome": "^0.0.287",
-    "@types/tape": "^5.8.0",
-    "@types/webextension-polyfill": "^0.12.1",
+    "@types/chrome": "^0.0.307",
+    "@types/tape": "^5.8.1",
     "buffer": "^6.0.3",
     "eslint": "^8.57.0",
     "eslint-config-pixiebrix": "^0.41.1",
@@ -52,18 +50,19 @@
     "process": "^0.11.10",
     "stream-browserify": "^3.0.0",
     "tape": "^5.9.0",
-    "typescript": "^5.7.2",
-    "vitest": "^2.1.8",
-    "webext-content-scripts": "^2.7.0",
-    "webextension-polyfill": "^0.12.0"
+    "typescript": "^5.8.2",
+    "vitest": "^3.0.7"
   },
   "targets": {
     "main": false,
-    "default": {
+    "external": {
+      "source": "source/test/external.html"
+    },
+    "extension": {
+      "source": "source/test/manifest.json",
       "engines": {
         "browsers": "Chrome 110"
       },
-      "source": "source/test/manifest.json",
       "sourceMap": {
         "inline": true
       }
@@ -75,7 +74,8 @@
       "startUrl": [
         "https://fregante.github.io/pixiebrix-testing-ground/Will-call-background-methods",
         "https://fregante.github.io/pixiebrix-testing-ground/Will-call-other-CS-via-background",
-        "https://fregante.github.io/pixiebrix-testing-ground/Will-call-offscreen-methods"
+        "https://fregante.github.io/pixiebrix-testing-ground/Will-call-offscreen-methods",
+        "http://localhost:1234/external.html"
       ]
     }
   }