webext-messenger 0.20.0 → 0.21.0

package/distribution/index.js

@@ -1,8 +1,4 @@
-// Imports must use the .js extension because of ESM requires it and TS refuses to rewrite .ts to .js
-// This works in TS even if the .js doesn't exist, but it breaks Parcel (the tests builder)
-// For this reason, there's an `alias` field in package.json to redirect these imports.
-// If you see "@parcel/resolver-default: Cannot load file './yourNewFile.js'" you need to add it to the `alias` list
-// 🥲
+// Imports must use the .js extension because ESM requires it and TS refuses to rewrite .ts to .js
 export * from "./receiver.js";
 export * from "./sender.js";
 export * from "./types.js";

package/distribution/receiver.js

@@ -1,8 +1,8 @@
 import { serializeError } from "serialize-error";
-import { getContextName, isBackground } from "webext-detect-page";
+import { getContextName } from "webext-detect-page";
 import { messenger } from "./sender.js";
 import { isObject, MessengerError, debug, __webextMessenger, } from "./shared.js";
-import { getActionForMessage, nameThisTarget } from "./thisTarget.js";
+import { getActionForMessage } from "./thisTarget.js";
 import { didUserRegisterMethods, handlers } from "./handlers.js";
 export function isMessengerMessage(message) {
     return (isObject(message) &&
@@ -17,7 +17,7 @@ function onMessageListener(message, sender) {
         return;
     }
     // Target check must be synchronous (`await` means we're handling the message)
-    const action = getActionForMessage(sender, message.target);
+    const action = getActionForMessage(sender, message);
     if (action === "ignore") {
         return;
     }
@@ -43,11 +43,13 @@ action) {
             args,
             wasForwarded: trace.length > 1,
         });
-        if (!didUserRegisterMethods()) {
-            throw new MessengerError(`No handlers registered in ${getContextName()}`);
-        }
         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()}`);
         }
         handleMessage = async () => localHandler.apply(meta, args);
@@ -61,9 +63,6 @@ action) {
     return { ...response, __webextMessenger };
 }
 export function registerMethods(methods) {
-    if (!isBackground()) {
-        void nameThisTarget();
-    }
     for (const [type, method] of Object.entries(methods)) {
         if (handlers.has(type)) {
             throw new MessengerError(`Handler already set for ${type}`);

package/distribution/sender.js

@@ -33,10 +33,27 @@ function manageConnection(type, options, target, sendMessage) {
 async function manageMessage(type, target, sendMessage) {
     const response = await pRetry(async () => {
         const response = await sendMessage();
-        if (!isMessengerResponse(response)) {
-            throw new MessengerError(`No handler registered for ${type} in the receiving end`);
+        if (isMessengerResponse(response)) {
+            return 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`);
+            }
+            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`);
     }, {
         minTimeout: 100,
         factor: 1.3,
@@ -49,7 +66,7 @@ async function manageMessage(type, target, sendMessage) {
             // 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
-                String(error.message).startsWith(_errorNonExistingTarget) ||
+                error.message === _errorNonExistingTarget ||
                 // `registerMethods` not yet loaded
                 String(error.message).startsWith("No handlers registered in ")) {
                 if (browser.tabs &&
@@ -63,6 +80,11 @@ async function manageMessage(type, target, sendMessage) {
                 throw error;
             }
         },
+    }).catch((error) => {
+        if (error?.message === _errorNonExistingTarget) {
+            throw new MessengerError(`The target ${JSON.stringify(target)} for ${type} was not found`);
+        }
+        throw error;
     });
     if ("error" in response) {
         debug(type, "↘️ replied with error", response.error);
@@ -80,7 +102,7 @@ function messenger(type, options, target, ...args) {
                 warn(type, "is being handled locally");
                 return handler.apply({ trace: [] }, args);
             }
-            throw new MessengerError("No handler registered for " + type);
+            throw new MessengerError("No handler registered locally for " + type);
         }
         const sendMessage = async () => {
             debug(type, "↗️ sending message to runtime");

package/distribution/shared.js

@@ -1,3 +1,4 @@
+import { errorConstructors } from "serialize-error";
 const logging = (() => {
     try {
         // @ts-expect-error it would break Webpack
@@ -25,6 +26,8 @@ export class MessengerError extends Error {
         });
     }
 }
+// @ts-expect-error Wrong `errorConstructors` types
+errorConstructors.set("MessengerError", MessengerError);
 // .bind preserves the call location in the console
 export const debug = logging ? console.debug.bind(console, "Messenger:") : noop;
 export const warn = logging ? console.warn.bind(console, "Messenger:") : noop;

package/distribution/thisTarget.d.ts

@@ -1,5 +1,4 @@
-import { AnyTarget, MessengerMeta, Sender } from "./types.js";
-export declare function getActionForMessage(from: Sender, { ...to }: AnyTarget): "respond" | "forward" | "ignore";
-export declare function nameThisTarget(): Promise<void>;
+import { AnyTarget, Message, MessengerMeta, Sender } from "./types.js";
+export declare function getActionForMessage(from: Sender, message: Message): "respond" | "forward" | "ignore";
 export declare function __getTabData(this: MessengerMeta): AnyTarget;
 export declare function initPrivateApi(): void;

package/distribution/thisTarget.js

@@ -1,11 +1,44 @@
 import { isBackground, isContentScript, isExtensionContext, } from "webext-detect-page";
 import { messenger } from "./sender.js";
 import { registerMethods } from "./receiver.js";
-import { debug } from "./shared.js";
+import { debug, MessengerError } from "./shared.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`.
+ */
 // 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.
-let thisTarget;
+const thisTarget = isBackground()
+    ? { page: "background" }
+    : {
+        get page() {
+            return location.pathname + location.search;
+        },
+    };
+let tabDataStatus = 
+// The background page doesn't have a tab
+isBackground() ||
+    // Content scripts don't use named targets yet
+    isContentScript()
+    ? "not-needed"
+    : "needed";
 function compareTargets(to, thisTarget) {
     for (const [key, value] of Object.entries(to)) {
         if (thisTarget[key] === value) {
@@ -27,8 +60,10 @@ function compareTargets(to, thisTarget) {
     }
     return true;
 }
-export function getActionForMessage(from, { ...to } // Clone object because we're editing it
-) {
+// 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";
     }
@@ -41,11 +76,6 @@ export function getActionForMessage(from, { ...to } // Clone object because we'r
     if (!to.page) {
         return "forward";
     }
-    if (!thisTarget) {
-        console.warn("A message was received before this context was ready");
-        // If this *was* the target, then probably no one else answered
-        return "ignore";
-    }
     // Set "this" tab to the current tabId
     if (to.tabId === "this" && thisTarget.tabId === from.tab?.id) {
         to.tabId = thisTarget.tabId;
@@ -53,28 +83,42 @@ export function getActionForMessage(from, { ...to } // Clone object because we'r
     // Every `target` key must match `thisTarget`
     const isThisTarget = compareTargets(to, thisTarget);
     if (!isThisTarget) {
-        debug("The message’s target is", to, "but this is", thisTarget);
+        debug(message.type, "🤫 ignored due to target mismatch", {
+            requestedTarget: to,
+            thisTarget,
+            tabDataStatus,
+        });
     }
     return isThisTarget ? "respond" : "ignore";
 }
-let nameRequested = false;
-export async function nameThisTarget() {
-    // Same as above: CS receives messages correctly
-    if (!nameRequested && !thisTarget && !isContentScript()) {
-        nameRequested = true;
-        thisTarget = await messenger("__getTabData", {}, { page: "any" });
-        thisTarget.page = location.pathname + location.search;
+async function storeTabData() {
+    if (tabDataStatus !== "needed") {
+        return;
+    }
+    try {
+        tabDataStatus = "pending";
+        Object.assign(thisTarget, {
+            ...(await messenger("__getTabData", {}, { page: "any" })),
+        });
+        tabDataStatus = "received";
+    }
+    catch (error) {
+        tabDataStatus = "error";
+        throw new MessengerError("Tab registration failed. This page won’t be able to receive messages that require tab information", 
+        // @ts-expect-error TODO: update lib to accept Error#cause
+        { cause: error });
     }
 }
 export function __getTabData() {
     return { tabId: this.trace[0]?.tab?.id, frameId: this.trace[0]?.frameId };
 }
 export function initPrivateApi() {
-    if (isBackground()) {
-        thisTarget = { page: "background" };
-    }
     if (isExtensionContext()) {
-        // Any context can handler this message
+        // Only `runtime` pages can handle this message but I can't remove it  because its listener
+        // also serves the purpose of throwing a specific error when no methods have been registered.
+        // https://github.com/pixiebrix/webext-messenger/pull/80
         registerMethods({ __getTabData });
+        // `getTabInformation` includes per-context exclusion logic
+        void storeTabData();
     }
 }

package/distribution/types.d.ts

@@ -40,7 +40,9 @@ export declare type Message<LocalArguments extends Arguments = Arguments> = {
     /** If the message is being sent to an intermediary receiver, also set the options */
     options?: Options;
 };
-export declare type Sender = Runtime.MessageSender;
+export declare type Sender = Runtime.MessageSender & {
+    origin?: string;
+};
 export declare type MessengerMessage = Message & {
     /** Guarantees that a message is meant to be handled by this library */
     __webextMessenger: true;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "webext-messenger",
-  "version": "0.20.0",
+  "version": "0.21.0",
   "description": "Browser Extension component messaging framework",
   "keywords": [],
   "repository": "pixiebrix/webext-messenger",

package/readme.md

@@ -18,3 +18,7 @@ import messenger from "webext-messenger";
 ## Context
 
 - [Initial considerations for this library](https://github.com/pixiebrix/webext-messenger/issues/1)
+
+## npm publishing
+
+Collaborators can publish a new version of what's on main [via "workflow_dispatch"](https://github.blog/changelog/2020-07-06-github-actions-manual-triggers-with-workflow_dispatch/) under [Actions » Publish](https://github.com/pixiebrix/webext-messenger/actions/workflows/npm-publish.yml)