Initial notification handling implementation

Author: rekmarks

src/JsonRpcEngine.ts

@@ -1,5 +1,6 @@
 import SafeEventEmitter from '@metamask/safe-event-emitter';
 import { errorCodes, EthereumRpcError, serializeError } from 'eth-rpc-errors';
+import { isJsonRpcRequest } from './utils';
 
 type Maybe<T> = Partial<T> | null | undefined;
 
@@ -32,38 +33,37 @@ export interface JsonRpcError {
   stack?: string;
 }
 
-export interface JsonRpcRequest<T> {
+interface JsonRpcRequestBase<T> {
   jsonrpc: JsonRpcVersion;
   method: string;
-  id: JsonRpcId;
   params?: T;
 }
 
-export interface JsonRpcNotification<T> {
-  jsonrpc: JsonRpcVersion;
-  method: string;
-  params?: T;
-}
+export type JsonRpcRequest<T> = JsonRpcRequestBase<T> & {
+  id: JsonRpcId;
+};
+
+export type JsonRpcNotification<T> = JsonRpcRequestBase<T>;
 
 interface JsonRpcResponseBase {
   jsonrpc: JsonRpcVersion;
   id: JsonRpcId;
 }
 
-export interface JsonRpcSuccess<T> extends JsonRpcResponseBase {
+export type JsonRpcSuccess<T> = JsonRpcResponseBase & {
   result: Maybe<T>;
-}
+};
 
-export interface JsonRpcFailure extends JsonRpcResponseBase {
+export type JsonRpcFailure = JsonRpcResponseBase & {
   error: JsonRpcError;
-}
+};
 
 export type JsonRpcResponse<T> = JsonRpcSuccess<T> | JsonRpcFailure;
 
-export interface PendingJsonRpcResponse<T> extends JsonRpcResponseBase {
+export type PendingJsonRpcResponse<T> = JsonRpcResponseBase & {
   result?: T;
   error?: Error | JsonRpcError;
-}
+};
 
 export type JsonRpcEngineCallbackError = Error | JsonRpcError | null;
 
@@ -86,27 +86,56 @@ export type JsonRpcMiddleware<T, U> = (
   end: JsonRpcEngineEndCallback,
 ) => void;
 
+export type JsonRpcNotificationMiddleware<T> = (
+  req: JsonRpcNotification<T>,
+) => Promise<void>;
+
 /**
  * A JSON-RPC request and response processor.
  * Give it a stack of middleware, pass it requests, and get back responses.
  */
 export class JsonRpcEngine extends SafeEventEmitter {
   private _middleware: JsonRpcMiddleware<unknown, unknown>[];
 
+  private _notificationMiddleware: JsonRpcNotificationMiddleware<unknown>[];
+
   constructor() {
     super();
     this._middleware = [];
+    this._notificationMiddleware = [];
   }
 
   /**
-   * Add a middleware function to the engine's middleware stack.
+   * Add a middleware function to the engine's request middleware stack.
    *
    * @param middleware - The middleware function to add.
    */
-  push<T, U>(middleware: JsonRpcMiddleware<T, U>): void {
+  pushRequestMiddleware<T, U>(middleware: JsonRpcMiddleware<T, U>): void {
     this._middleware.push(middleware as JsonRpcMiddleware<unknown, unknown>);
   }
 
+  /**
+   * Alias for `pushRequestMiddleware`, for backwards compatibility.
+   *
+   * @param middleware - The request middleware function to add.
+   */
+  push<T, U>(middleware: JsonRpcMiddleware<T, U>): void {
+    this.pushRequestMiddleware(
+      middleware as JsonRpcMiddleware<unknown, unknown>,
+    );
+  }
+
+  /**
+   * Add a middleware function to the engine's notification middleware stack.
+   *
+   * @param middleware - The notification middleware function to add.
+   */
+  pushNotificationMiddleware<T>(
+    middleware: JsonRpcNotificationMiddleware<T>,
+  ): void {
+    this._middleware.push(middleware as JsonRpcNotificationMiddleware<unknown>);
+  }
+
   /**
    * Handle a JSON-RPC request, and return a response.
    *
@@ -119,14 +148,26 @@ export class JsonRpcEngine extends SafeEventEmitter {
   ): void;
 
   /**
-   * Handle an array of JSON-RPC requests, and return an array of responses.
+   * Handle a JSON-RPC notification.
+   *
+   * @param notification - The notification to handle.
+   * @param callback - An error-first callback that will receive a `void` response.
+   */
+  handle<T>(
+    request: JsonRpcNotification<T>,
+    callback: (error: unknown, response: void) => void,
+  ): void;
+
+  /**
+   * Handle an array of JSON-RPC requests and/or notifications, and return an
+   * array of responses to any included requests.
    *
    * @param request - The requests to handle.
    * @param callback - An error-first callback that will receive the array of
    * responses.
    */
   handle<T, U>(
-    requests: JsonRpcRequest<T>[],
+    requests: (JsonRpcRequest<T> | JsonRpcNotification<T>)[],
     callback: (error: unknown, responses: JsonRpcResponse<U>[]) => void,
   ): void;
 
@@ -139,12 +180,22 @@ export class JsonRpcEngine extends SafeEventEmitter {
   handle<T, U>(request: JsonRpcRequest<T>): Promise<JsonRpcResponse<U>>;
 
   /**
-   * Handle an array of JSON-RPC requests, and return an array of responses.
+   * Handle a JSON-RPC notification.
+   *
+   * @param notification - The notification to handle.
+   */
+  handle<T>(notification: JsonRpcNotification<T>): Promise<void>;
+
+  /**
+   * Handle an array of JSON-RPC requests and/or notifications, and return an
+   * array of responses to any included requests.
    *
    * @param request - The JSON-RPC requests to handle.
    * @returns An array of JSON-RPC responses.
    */
-  handle<T, U>(requests: JsonRpcRequest<T>[]): Promise<JsonRpcResponse<U>[]>;
+  handle<T, U>(
+    requests: (JsonRpcRequest<T> | JsonRpcNotification<T>)[],
+  ): Promise<JsonRpcResponse<U>[]>;
 
   handle(req: unknown, callback?: any) {
     if (callback && typeof callback !== 'function') {
@@ -199,14 +250,14 @@ export class JsonRpcEngine extends SafeEventEmitter {
    * Like _handle, but for batch requests.
    */
   private _handleBatch(
-    reqs: JsonRpcRequest<unknown>[],
+    reqs: (JsonRpcRequest<unknown> | JsonRpcNotification<unknown>)[],
   ): Promise<JsonRpcResponse<unknown>[]>;
 
   /**
    * Like _handle, but for batch requests.
    */
   private _handleBatch(
-    reqs: JsonRpcRequest<unknown>[],
+    reqs: (JsonRpcRequest<unknown> | JsonRpcNotification<unknown>)[],
     callback: (error: unknown, responses?: JsonRpcResponse<unknown>[]) => void,
   ): Promise<void>;
 
@@ -219,23 +270,23 @@ export class JsonRpcEngine extends SafeEventEmitter {
    * @returns The array of responses, or nothing if a callback was specified.
    */
   private async _handleBatch(
-    reqs: JsonRpcRequest<unknown>[],
+    reqs: (JsonRpcRequest<unknown> | JsonRpcNotification<unknown>)[],
     callback?: (error: unknown, responses?: JsonRpcResponse<unknown>[]) => void,
   ): Promise<JsonRpcResponse<unknown>[] | void> {
     // The order here is important
     try {
       // 2. Wait for all requests to finish, or throw on some kind of fatal
       // error
-      const responses = await Promise.all(
-        // 1. Begin executing each request in the order received
-        reqs.map(this._promiseHandle.bind(this)),
-      );
+      const responses = (
+        await Promise.all(
+          // 1. Begin executing each request in the order received
+          reqs.map(this._promiseHandle.bind(this)),
+          // Filter out falsy responses from notifications
+        )
+      ).filter((response) => Boolean(response)) as JsonRpcResponse<unknown>[];
 
       // 3. Return batch response
-      if (callback) {
-        return callback(null, responses);
-      }
-      return responses;
+      return callback ? callback(null, responses) : responses;
     } catch (error) {
       if (callback) {
         return callback(error);
@@ -252,8 +303,8 @@ export class JsonRpcEngine extends SafeEventEmitter {
    * @returns The JSON-RPC response.
    */
   private _promiseHandle(
-    req: JsonRpcRequest<unknown>,
-  ): Promise<JsonRpcResponse<unknown>> {
+    req: JsonRpcRequest<unknown> | JsonRpcNotification<unknown>,
+  ): Promise<JsonRpcResponse<unknown> | void> {
     return new Promise((resolve) => {
       this._handle(req, (_err, res) => {
         // There will always be a response, and it will always have any error
@@ -264,8 +315,8 @@ export class JsonRpcEngine extends SafeEventEmitter {
   }
 
   /**
-   * Ensures that the request object is valid, processes it, and passes any
-   * error and the response object to the given callback.
+   * Ensures that the request / notification object is valid, processes it, and
+   * passes any error and response object to the given callback.
    *
    * Does not reject.
    *
@@ -274,8 +325,8 @@ export class JsonRpcEngine extends SafeEventEmitter {
    * @returns Nothing.
    */
   private async _handle(
-    callerReq: JsonRpcRequest<unknown>,
-    callback: (error: unknown, response: JsonRpcResponse<unknown>) => void,
+    callerReq: JsonRpcRequest<unknown> | JsonRpcNotification<unknown>,
+    callback: (error: unknown, response?: JsonRpcResponse<unknown>) => void,
   ): Promise<void> {
     if (
       !callerReq ||
@@ -296,18 +347,39 @@ export class JsonRpcEngine extends SafeEventEmitter {
         `Must specify a string method. Received: ${typeof callerReq.method}`,
         { request: callerReq },
       );
-      return callback(error, { id: callerReq.id, jsonrpc: '2.0', error });
+      return callback(error, {
+        id: (callerReq as any).id ?? null,
+        jsonrpc: '2.0',
+        error,
+      });
+    }
+
+    let error: JsonRpcEngineCallbackError = null;
+
+    // Handle notifications.
+    // We can't use isJsonRpcNotification here because that narrows callerReq to
+    // "never" after the if clause.
+    if (!isJsonRpcRequest(callerReq)) {
+      try {
+        await JsonRpcEngine._processNotification(
+          { ...callerReq },
+          this._notificationMiddleware,
+        );
+      } catch (_error) {
+        error = _error;
+      }
+      return callback(error);
     }
 
+    // Handle requests.
     const req: JsonRpcRequest<unknown> = { ...callerReq };
     const res: PendingJsonRpcResponse<unknown> = {
       id: req.id,
       jsonrpc: req.jsonrpc,
     };
-    let error: JsonRpcEngineCallbackError = null;
 
     try {
-      await this._processRequest(req, res);
+      await JsonRpcEngine._processRequest(req, res, this._middleware);
     } catch (_error) {
       // A request handler error, a re-thrown middleware error, or something
       // unexpected.
@@ -325,20 +397,37 @@ export class JsonRpcEngine extends SafeEventEmitter {
     return callback(error, res as JsonRpcResponse<unknown>);
   }
 
+  /**
+   * Runs all notification middleware on the specified notification.
+   *
+   * @param notification - The notification object to process.
+   * @param middlewareStack - The stack of notification middleware functions.
+   */
+  private static async _processNotification(
+    notification: JsonRpcNotification<unknown>,
+    middlewareStack: JsonRpcNotificationMiddleware<unknown>[],
+  ): Promise<void> {
+    for (const middleware of middlewareStack) {
+      await middleware(notification);
+    }
+  }
+
   /**
    * For the given request and response, runs all middleware and their return
    * handlers, if any, and ensures that internal request processing semantics
    * are satisfied.
    *
    * @param req - The request object.
    * @param res - The response object.
+   * @param middlewareStack - The stack of request middleware functions.
    */
-  private async _processRequest(
+  private static async _processRequest(
     req: JsonRpcRequest<unknown>,
     res: PendingJsonRpcResponse<unknown>,
+    middlewareStack: JsonRpcMiddleware<unknown, unknown>[],
   ): Promise<void> {
     const [error, isComplete, returnHandlers] =
-      await JsonRpcEngine._runAllMiddleware(req, res, this._middleware);
+      await JsonRpcEngine._runAllMiddleware(req, res, middlewareStack);
 
     // Throw if "end" was not called, or if the response has neither a result
     // nor an error.