feat: Add messenger `delegate` and `revoke` methods #6132

Gudahtt · 2025-07-17T00:22:32Z

Explanation

The methods delegate and revoke have been added to the Messenger class. These methods replace the need for the RestrictedMessenger. The getRestricted method, and the RestrictedMessenger class, have been removed as obsolete.

Note that the parent constructor parameter described in the ADR is not implemented yet, that will come in the next PR.

References

See this ADR PR for details: MetaMask/decisions#53
Relates to #5626

Checklist

I've updated the test suite for new or updated code as appropriate
I've updated documentation (JSDoc, Markdown, etc.) for new or updated code as appropriate
I've communicated my changes to consumers by updating changelogs for packages I've changed, highlighting breaking changes as necessary
I've prepared draft pull requests for clients and consumer packages to resolve any breaking changes

mcmire

I had some comments, mostly around documentation, but I was also curious about some behavior in delegate which seems to be replicated in #registerInitialEventPayload.

mcmire · 2025-07-21T19:20:50Z

packages/messenger/src/Messenger.ts

+  constructor({ namespace }: { namespace: Namespace }) {
+    this.#namespace = namespace;
+  }
+
  /**
   * Register an action handler.


To better distinguish this method from registerDelegatedActionHandler, should we clarify that the action here is one that the messenger "owns"?

Suggested change

* Register an action handler.

* Register a handler for an action under this messenger's namespace.

Or, perhaps literally:

Suggested change

* Register an action handler.

* Register an action owned by this messenger.

mcmire · 2025-07-21T19:23:17Z

packages/messenger/src/Messenger.ts

@@ -160,7 +196,42 @@ export class Messenger<
   * @throws Will throw when a handler has been registered for this action type already.
   * @template ActionType - A type union of Action type strings.


Maybe this should say:

Suggested change

* @template ActionType - A type union of Action type strings.

* @template ActionType - A union of type strings for actions under this messenger's namespace.

packages/messenger/src/Messenger.ts

mcmire · 2025-07-23T18:31:58Z

packages/messenger/src/Messenger.ts

+   * Register a delegated action handler.
+   *
+   * This will make the registered function available to call via the `call` method.


Is it worth expanding this description slightly to clarify what "delegated" means? My thought is that it might seem odd that we are defining a method that is very similar to registerActionHandler, but doesn't require that the action has this messenger's namespace or that the action is one that this messenger recognizes.

Suggested change

* Register a delegated action handler.

*

* This will make the registered function available to call via the `call` method.

* Register a delegated action handler (that is, a handler which comes from another messenger

* that this messenger is permitted to call).

*

* This will make the registered function available to call via the `call` method.

I guess if we make this change, we may have to clarify what "delegated" means for other methods that handle delegation, so there is that.

Alternatively, we could tell people to read the docs for delegate if they want more context. I know we mention this method in the @deprecate tag, but it might be missed.

The idea was that these delegated____ methods are internal-only (i.e. called only from within this class). I wasn't too concerned with making the intended usage clear, so long as we understand the intended usage. Everyone else just needs to understand not to call this, ever.

Maybe there is something better than deprecating we can do to achieve this though, e.g. move it under a namespace or something.

The idea was that these delegated____ methods are internal-only (i.e. called only from within this class). I wasn't too concerned with making the intended usage clear, so long as we understand the intended usage. Everyone else just needs to understand not to call this, ever.

Yeah, that's fair.

Maybe there is something better than deprecating we can do to achieve this though, e.g. move it under a namespace or something.

Maybe we could prefix the methods with something ugly like __INTERNAL__ or __PRIVATE__ or just _? But then again, VSCode will highlight the usage of the method as deprecated with an underline, so if you were to use it, I feel like you would know. Maybe the @deprecated is good enough.

I'll try something different out, I wasn't totally happy with relying on just the method name prefix + @deprecated tag. I'll attempt to revise the description as well.

mcmire · 2025-07-23T18:32:53Z

packages/messenger/src/Messenger.ts

@@ -180,7 +251,7 @@ export class Messenger<
   * handlers
   */
  registerMethodActionHandlers<
-    MessengerClient extends { name: string },
+    MessengerClient extends { name: Namespace },


Ah, good catch.

mcmire · 2025-07-23T18:53:50Z

packages/messenger/src/Messenger.ts

+    handler:
+      | ActionHandler<Action, ActionType>
+      | ActionHandler<ActionConstraint, ActionType>,


This seems to allow any kind of action handler, but if ActionType must refer to an action that this messenger recognizes, then shouldn't the handler be connected to that action?

Suggested change

handler:

| ActionHandler<Action, ActionType>

| ActionHandler<ActionConstraint, ActionType>,

handler: ActionHandler<Action, ActionType>,

mcmire · 2025-07-23T18:58:19Z

packages/messenger/src/Messenger.ts

+  }
+
+  /**
+   * Publish a delegated event.


Similar as above — is it worth adding more language here?

Suggested change

* Publish a delegated event.

* Publish a delegated event (that is, an event published by another messenger that this

* messenger is permitted to subscribe to).

mcmire · 2025-07-23T19:14:35Z

packages/messenger/src/Messenger.ts

-   * @template AllowedEvent - A type union of the 'type' string for any allowed events.
-   * This must not include internal events that are in the messenger's namespace.
-   * @returns The restricted messenger.
+   * Delegate actions and/or events to another messenger.


Is it worth explaining what this does?

Suggested change

* Delegate actions and/or events to another messenger.

* Delegate actions and/or events to another messenger.

*

* - For all actions specified, this method will register an action handler

* on the given messenger that calls the same action within this messenger.

* - For all events specified, this method will register an event handler

* on this messenger that publishes the same event within that messenger.

*

* In other words:

*

* - The delegated messenger is able to call any of the specified actions

* known to this messenger as though they had been registered directly; when

* they are called there, they are called here.

* - The delegated messenger is able to subscribe to any of the specified

* events known to this messenger; when they are published here they will

* be published there as well.

*

* Note that to delegate an action to a messenger, it needs to be already

* present in the type union of all Action types for that messenger; and

* similarly for an event.

(Also, if any of that is wrong, feel free to correct me)

mcmire · 2025-07-23T19:16:21Z

packages/messenger/src/Messenger.ts

+      const getPayload = this.#initialEventPayloadGetters.get(eventType);
+      if (getPayload) {
+        messenger.registerDelegatedInitialEventPayload({
+          eventType,
+          getPayload,
+        });
+      }


It seems like we are already calling registerDelegatedInitialEventPayload for all delegation targets within #registerInitialEventPayload. Do we need this?

Suggested change

const getPayload = this.#initialEventPayloadGetters.get(eventType);

if (getPayload) {

messenger.registerDelegatedInitialEventPayload({

eventType,

getPayload,

});

}

Yes; this is for the case where the initial payload is registered before the delegation. My intent was to support both scenarios (see the correctly registers initial event payload when delegated before payload is set and correctly registers initial event payload when delegated after payload is set tests)

mcmire · 2025-07-23T19:27:39Z

packages/messenger/CHANGELOG.md

+
+- **BREAKING:** Add `Namespace` type parameter and required `namespace` constructor parameter ([#6132](https://github.com/MetaMask/core/pull/6132))
+  - All published events and registered actions should fall under the given namespace. Typically the namespace is the controller or service name. This is the equivalent to the `Namespace` parameter from the old `RestrictedMessenger` class.
+- **BREAKING:** Remove `RestrictedMessenger` class ([#6132](https://github.com/MetaMask/core/pull/6132))


Should this be in "Removed"?

mcmire · 2025-07-23T19:46:21Z

packages/messenger/src/Messenger.ts

+  Action extends ActionConstraint,
+  Event extends EventConstraint,
+> = Pick<
+  Messenger<string, Action | ActionConstraint, Event | EventConstraint>,


Similar question to https://github.com/MetaMask/core/pull/6132/files#r2226392393 — why do we need to allow any kind of action or event?

Good question. I ran into problems with covariance/contravariance here (see https://en.wikipedia.org/wiki/Covariance_and_contravariance_(computer_science)), but I can't recall the specifics. I'll investigate.

The methods `delegate` and `revoke` have been added to the Messenger class. These methods replace the need for the `RestrictedMessenger`. The `getRestricted` method, and the `RestrictedMessenger` class, have been removed as obsolete. See this ADR PR for details: MetaMask/decisions#53

Co-authored-by: Elliot Winkler <elliot.winkler@gmail.com>

Gudahtt force-pushed the create-messenger-package branch 2 times, most recently from 4876850 to e3899db Compare July 17, 2025 12:36

Base automatically changed from create-messenger-package to main July 17, 2025 12:41

Gudahtt force-pushed the add-messenger-delegation branch 7 times, most recently from 776c9b8 to c249e17 Compare July 17, 2025 16:09

Gudahtt marked this pull request as ready for review July 17, 2025 16:09

Gudahtt requested a review from a team as a code owner July 17, 2025 16:10

This comment was marked as outdated.

Sign in to view

Gudahtt mentioned this pull request Jul 17, 2025

feat: Add Messenger parent parameter #6142

Draft

4 tasks

mcmire reviewed Jul 23, 2025

View reviewed changes

Gudahtt and others added 3 commits July 23, 2025 17:41

Update clearActions to handle delegated actions

6a04f54

Fix typos

6729773

Co-authored-by: Elliot Winkler <elliot.winkler@gmail.com>

Gudahtt force-pushed the add-messenger-delegation branch from 2dd241a to 6729773 Compare July 23, 2025 20:11

	* Register an action handler.
	* Register a handler for an action under this messenger's namespace.

	* Register an action handler.
	* Register an action owned by this messenger.

		@@ -160,7 +196,42 @@ export class Messenger<
		* @throws Will throw when a handler has been registered for this action type already.
		* @template ActionType - A type union of Action type strings.

	* @template ActionType - A type union of Action type strings.
	* @template ActionType - A union of type strings for actions under this messenger's namespace.

	* Publish a delegated event.
	* Publish a delegated event (that is, an event published by another messenger that this
	* messenger is permitted to subscribe to).

-   * Delegate actions and/or events to another messenger.
+   * Delegate actions and/or events to another messenger.
+   *
+   * - For all actions specified, this method will register an action handler
+   * on the given messenger that calls the same action within this messenger.
+   * - For all events specified, this method will register an event handler
+   * on this messenger that publishes the same event within that messenger.
+   *
+   * In other words:
+   *
+   * - The delegated messenger is able to call any of the specified actions
+   * known to this messenger as though they had been registered directly; when
+   * they are called there, they are called here.
+   * - The delegated messenger is able to subscribe to any of the specified
+   * events known to this messenger; when they are published here they will
+   * be published there as well.
+   *
+   * Note that to delegate an action to a messenger, it needs to be already
+   * present in the type union of all Action types for that messenger; and
+   * similarly for an event.

Uh oh!

feat: Add messenger delegate and revoke methods #6132

Are you sure you want to change the base?

feat: Add messenger delegate and revoke methods #6132

Conversation

Gudahtt commented Jul 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Explanation

References

Checklist

Uh oh!

This comment was marked as outdated.

Uh oh!

mcmire left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

mcmire Jul 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mcmire Jul 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

feat: Add messenger `delegate` and `revoke` methods #6132

feat: Add messenger `delegate` and `revoke` methods #6132

Gudahtt commented Jul 17, 2025 •

edited

Loading

mcmire Jul 23, 2025 •

edited

Loading

mcmire Jul 23, 2025 •

edited

Loading