feat: Migrate controller guidelines and examples to new Messenger

Migrate the controller guidelines and the `sample-controllers` package
to the `next` export of the `@metamask/base-controller` package and the
new `Messenger` class from `@metamask/messenger`.

Author: Gudahtt

docs/controller-guidelines.md

@@ -78,7 +78,7 @@ Next we'll define the messenger. We give the messenger a namespace, and we expos
 ```typescript
 // (top of file)
 
-import type { RestrictedMessenger } from '@metamask/base-controller';
+import type { Messenger } from '@metamask/base-controller';
 
 const SERVICE_NAME = 'GasPricesService';
 

docs/data-services.md

@@ -9,6 +9,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Changed
 
+- **BREAKING:** Migrate to new `Messenger` class ([#6335](https://github.com/MetaMask/core/pull/6335))
 - Bump `@metamask/utils` from `^11.2.0` to `^11.4.2` ([#6054](https://github.com/MetaMask/core/pull/6054))
 - Bump `@metamask/base-controller` from `^8.0.1` to `^8.1.0` ([#6284](https://github.com/MetaMask/core/pull/6284))
 

packages/sample-controllers/CHANGELOG.md

@@ -48,6 +48,7 @@
   },
   "dependencies": {
     "@metamask/base-controller": "^8.1.0",
+    "@metamask/messenger": "^0.0.0",
     "@metamask/utils": "^11.4.2"
   },
   "devDependencies": {

packages/sample-controllers/package.json

@@ -1,16 +1,16 @@
-import { Messenger } from '@metamask/base-controller';
-import { SampleGasPricesController } from '@metamask/sample-controllers';
-import type { SampleGasPricesControllerMessenger } from '@metamask/sample-controllers';
+import {
+  Messenger,
+  type MessengerActions,
+  type MessengerEvents,
+} from '@metamask/messenger';
 
 import {
   getDefaultNetworkControllerState,
   type NetworkControllerGetStateAction,
 } from './network-controller-types';
+import { SampleGasPricesController } from './sample-gas-prices-controller';
+import type { SampleGasPricesControllerMessenger } from './sample-gas-prices-controller';
 import type { SampleAbstractGasPricesService } from './sample-gas-prices-service';
-import type {
-  ExtractAvailableAction,
-  ExtractAvailableEvent,
-} from '../../base-controller/tests/helpers';
 
 describe('SampleGasPricesController', () => {
   describe('constructor', () => {
@@ -94,23 +94,26 @@ describe('SampleGasPricesController', () => {
 });
 
 /**
- * The union of actions that the root messenger allows.
+ * The union of all SampleGasPricesController actions.
  */
-type RootAction = ExtractAvailableAction<SampleGasPricesControllerMessenger>;
+type AllSampleGasPricesControllerActions =
+  MessengerActions<SampleGasPricesControllerMessenger>;
 
 /**
- * The union of events that the root messenger allows.
+ * The union of all SampleGasPricesController events.
  */
-type RootEvent = ExtractAvailableEvent<SampleGasPricesControllerMessenger>;
+type AllSampleGasPricesControllerEvents =
+  MessengerEvents<SampleGasPricesControllerMessenger>;
 
 /**
- * Constructs the unrestricted messenger. This can be used to call actions and
- * publish events within the tests for this controller.
+ * Construct the root messenger that is populated with all external actions/events that the
+ * SampleGasPricesController needs.
  *
  * @param args - The arguments to this function.
  * @param args.networkControllerGetStateActionHandler - Used to mock the
  * `NetworkController:getState` action on the messenger.
- * @returns The unrestricted messenger suited for SampleGasPricesController.
+ * @returns A root messenger that is populated with all external actions/events that the
+ * SampleGasPricesController needs.
  */
 function getRootMessenger({
   networkControllerGetStateActionHandler = jest
@@ -121,30 +124,57 @@ function getRootMessenger({
     .mockReturnValue(getDefaultNetworkControllerState()),
 }: {
   networkControllerGetStateActionHandler?: NetworkControllerGetStateAction['handler'];
-} = {}): Messenger<RootAction, RootEvent> {
-  const rootMessenger = new Messenger<RootAction, RootEvent>();
-  rootMessenger.registerActionHandler(
+} = {}): Messenger<
+  'Root',
+  AllSampleGasPricesControllerActions,
+  AllSampleGasPricesControllerEvents
+> {
+  const rootMessenger = new Messenger<
+    'Root',
+    AllSampleGasPricesControllerActions,
+    AllSampleGasPricesControllerEvents
+  >({ namespace: 'Root' });
+  // Create NetworkController messenger just so that it can delegate to root
+  const networkControllerMessenger = new Messenger<
+    'NetworkController',
+    NetworkControllerGetStateAction,
+    never,
+    typeof rootMessenger
+  >({ namespace: 'NetworkController', parent: rootMessenger });
+  // Register stubs for required action handlers
+  networkControllerMessenger.registerActionHandler(
     'NetworkController:getState',
     networkControllerGetStateActionHandler,
   );
+
   return rootMessenger;
 }
 
 /**
- * Constructs the messenger which is restricted to relevant SampleGasPricesController
- * actions and events.
+ * Constructs the SampleGasPricesController messenger.
  *
- * @param rootMessenger - The root messenger to restrict.
+ * @param rootMessenger - The root messenger, with all external actions/events required by the
+ * SampleGasPricesController messenger.
  * @returns The restricted messenger.
  */
 function getMessenger(
   rootMessenger = getRootMessenger(),
 ): SampleGasPricesControllerMessenger {
-  return rootMessenger.getRestricted({
-    name: 'SampleGasPricesController',
-    allowedActions: ['NetworkController:getState'],
-    allowedEvents: [],
+  const messenger = new Messenger<
+    'SampleGasPricesController',
+    AllSampleGasPricesControllerActions,
+    AllSampleGasPricesControllerEvents,
+    typeof rootMessenger
+  >({
+    namespace: 'SampleGasPricesController',
+    parent: rootMessenger,
+  });
+  // Delegate external actions/events
+  rootMessenger.delegate({
+    actions: ['NetworkController:getState'],
+    messenger,
   });
+  return messenger;
 }
 
 /**

packages/sample-controllers/src/sample-gas-prices-controller.test.ts

@@ -1,10 +1,10 @@
 import type {
   ControllerGetStateAction,
   ControllerStateChangeEvent,
-  RestrictedMessenger,
   StateMetadata,
-} from '@metamask/base-controller';
-import { BaseController } from '@metamask/base-controller';
+} from '@metamask/base-controller/next';
+import { BaseController } from '@metamask/base-controller/next';
+import type { Messenger } from '@metamask/messenger';
 import type { Hex } from '@metamask/utils';
 
 import type { NetworkControllerGetStateAction } from './network-controller-types';
@@ -123,12 +123,10 @@ type AllowedEvents = never;
  * The messenger which is restricted to actions and events accessed by
  * {@link SampleGasPricesController}.
  */
-export type SampleGasPricesControllerMessenger = RestrictedMessenger<
+export type SampleGasPricesControllerMessenger = Messenger<
   typeof controllerName,
   SampleGasPricesControllerActions | AllowedActions,
-  SampleGasPricesControllerEvents | AllowedEvents,
-  AllowedActions['type'],
-  AllowedEvents['type']
+  SampleGasPricesControllerEvents | AllowedEvents
 >;
 
 /**

packages/sample-controllers/src/sample-gas-prices-controller.ts

@@ -1,11 +1,11 @@
-import { Messenger } from '@metamask/base-controller';
+import {
+  Messenger,
+  type MessengerActions,
+  type MessengerEvents,
+} from '@metamask/messenger';
 
 import type { SamplePetnamesControllerMessenger } from './sample-petnames-controller';
 import { SamplePetnamesController } from './sample-petnames-controller';
-import type {
-  ExtractAvailableAction,
-  ExtractAvailableEvent,
-} from '../../base-controller/tests/helpers';
 import { PROTOTYPE_POLLUTION_BLOCKLIST } from '../../controller-utils/src/util';
 
 describe('SamplePetnamesController', () => {
@@ -143,38 +143,28 @@ describe('SamplePetnamesController', () => {
 });
 
 /**
- * The union of actions that the root messenger allows.
+ * The union of all SamplePetnamesController actions.
  */
-type RootAction = ExtractAvailableAction<SamplePetnamesControllerMessenger>;
+type AllSamplePetnamesControllerActions =
+  MessengerActions<SamplePetnamesControllerMessenger>;
 
 /**
- * The union of events that the root messenger allows.
+ * The union of all SamplePetnamesController events.
  */
-type RootEvent = ExtractAvailableEvent<SamplePetnamesControllerMessenger>;
+type AllSamplePetnamesControllerEvents =
+  MessengerEvents<SamplePetnamesControllerMessenger>;
 
 /**
- * Constructs the unrestricted messenger. This can be used to call actions and
- * publish events within the tests for this controller.
+ * Constructs the SamplePetnamesController messenger.
  *
- * @returns The unrestricted messenger suited for SamplePetnamesController.
+ * @returns The SamplePetnamesController messenger.
  */
-function getRootMessenger(): Messenger<RootAction, RootEvent> {
-  return new Messenger<RootAction, RootEvent>();
-}
-
-/**
- * Constructs the messenger which is restricted to relevant SamplePetnamesController
- * actions and events.
- *
- * @param rootMessenger - The root messenger to restrict.
- * @returns The restricted messenger.
- */
-function getMessenger(
-  rootMessenger = getRootMessenger(),
-): SamplePetnamesControllerMessenger {
-  return rootMessenger.getRestricted({
-    name: 'SamplePetnamesController',
-    allowedActions: [],
-    allowedEvents: [],
+function getMessenger(): SamplePetnamesControllerMessenger {
+  return new Messenger<
+    'SamplePetnamesController',
+    AllSamplePetnamesControllerActions,
+    AllSamplePetnamesControllerEvents
+  >({
+    namespace: 'SamplePetnamesController',
   });
 }

packages/sample-controllers/src/sample-petnames-controller.test.ts

@@ -1,11 +1,11 @@
 import type {
   ControllerGetStateAction,
   ControllerStateChangeEvent,
-  RestrictedMessenger,
   StateMetadata,
-} from '@metamask/base-controller';
-import { BaseController } from '@metamask/base-controller';
+} from '@metamask/base-controller/next';
+import { BaseController } from '@metamask/base-controller/next';
 import { isSafeDynamicKey } from '@metamask/controller-utils';
+import type { Messenger } from '@metamask/messenger';
 import type { Hex } from '@metamask/utils';
 
 // === GENERAL ===
@@ -92,12 +92,10 @@ type AllowedEvents = never;
  * The messenger which is restricted to actions and events accessed by
  * {@link SamplePetnamesController}.
  */
-export type SamplePetnamesControllerMessenger = RestrictedMessenger<
+export type SamplePetnamesControllerMessenger = Messenger<
   typeof controllerName,
   SamplePetnamesControllerActions | AllowedActions,
-  SamplePetnamesControllerEvents | AllowedEvents,
-  AllowedActions['type'],
-  AllowedEvents['type']
+  SamplePetnamesControllerEvents | AllowedEvents
 >;
 
 /**

packages/sample-controllers/src/sample-petnames-controller.ts

@@ -7,6 +7,7 @@
   },
   "references": [
     { "path": "../../packages/base-controller/tsconfig.build.json" },
+    { "path": "../../packages/messenger/tsconfig.build.json" },
     { "path": "../../packages/network-controller/tsconfig.build.json" }
   ],
   "include": ["../../types", "./src"]

packages/sample-controllers/tsconfig.build.json

@@ -6,6 +6,7 @@
   "references": [
     { "path": "../../packages/base-controller" },
     { "path": "../../packages/controller-utils" },
+    { "path": "../../packages/messenger" },
     { "path": "../../packages/network-controller" }
   ],
   "include": ["../../types", "./src"],