webext-messenger 0.32.0 → 0.33.0-0

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,17 +1,27 @@
 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"]));
 }
+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.
  *
@@ -63,6 +73,19 @@ function onMessageListener(message, sender, sendResponse) {
     // 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);
+    }
+    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;
@@ -71,6 +94,9 @@ async function prepareResponse(message, action, meta) {
     }
     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()) {
@@ -89,6 +115,15 @@ export function registerMethods(methods) {
         handlers.set(type, method);
     }
     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

@@ -141,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()) {

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

@@ -18,9 +18,8 @@ const tab = {
     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

@@ -10,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>>;
@@ -43,10 +43,13 @@ 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 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 */
@@ -56,6 +59,7 @@ export interface AnyTarget {
     tabId?: number | "this";
     frameId?: number | "allFrames";
     page?: string;
+    extensionId?: string;
 }
 export interface TopLevelFrame {
     tabId: number;
@@ -78,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.32.0",
+  "version": "0.33.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",
@@ -55,11 +55,14 @@
   },
   "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
       }
@@ -71,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"
       ]
     }
   }