Allow createFetchMiddleware to take an RPC service (#357)

`@metamask/network-controller` now contains an `RpcService` class. Using
this class not only allows us to remove a lot of code from this package,
as it incorporates the vast majority of logic contained in
`createFetchMiddleware`, including the retry logic, but it also allows
us to use the circuit breaker pattern and the exponential backoff
pattern to prevent too many retries if the network is unreliable, and
then automatically cut over to a failover node when the network truly
goes down.

Closes #356.
Closes #207.
Closes #209.
Closes #211.
Closes #166.

Author: mcmire

CHANGELOG.md

@@ -6,7 +6,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 ### Changed
-- Bump `@metamask/utils` to `^11.1.0`
+- Bump `@metamask/utils` to `^11.1.0` ([#358](https://github.com/MetaMask/eth-json-rpc-middleware/pull/358))
+- Deprecate passing an RPC endpoint to `createFetchMiddleware`, and add a way to pass an RPC service instead ([#357](https://github.com/MetaMask/eth-json-rpc-middleware/pull/357))
+  - The new, recommended method signature is now `createFetchMiddleware({ rpcService: AbstractRpcService; options?: { originHttpHeaderKey?: string; } })`, where `AbstractRpcService` matches the same interface from `@metamask/network-controller`
+  - This allows us to support automatic failover to a secondary node when the network goes down
+  - The existing method signature `createFetchMiddleware({ btoa: typeof btoa; fetch: typeof fetch; rpcUrl: string; originHttpHeaderKey?: string; })` will be removed in a future major version
 
 ## [15.1.2]
 ### Changed

jest.config.js

@@ -22,7 +22,7 @@ module.exports = {
   collectCoverage: true,
 
   // An array of glob patterns indicating a set of files for which coverage information should be collected
-  collectCoverageFrom: ['./src/**/*.ts'],
+  collectCoverageFrom: ['./src/**/*.ts', '!./src/**/*.test-d.ts'],
 
   // The directory where Jest should output its coverage files
   coverageDirectory: 'coverage',

package.json

@@ -24,7 +24,8 @@
     "lint:fix": "yarn lint:eslint --fix && yarn lint:misc --write",
     "lint:misc": "prettier '**/*.json' '**/*.md' '!CHANGELOG.md' '**/*.yml' '!.yarnrc.yml' --ignore-path .gitignore --no-error-on-unmatched-pattern",
     "prepack": "./scripts/prepack.sh",
-    "test": "jest",
+    "test": "jest && yarn build:clean && yarn test:types",
+    "test:types": "tsd --files 'src/**/*.test-d.ts'",
     "test:watch": "jest --watch"
   },
   "dependencies": {
@@ -48,6 +49,7 @@
     "@metamask/eslint-config-jest": "^12.1.0",
     "@metamask/eslint-config-nodejs": "^12.1.0",
     "@metamask/eslint-config-typescript": "^12.1.0",
+    "@metamask/network-controller": "22.2.0",
     "@types/btoa": "^1.2.3",
     "@types/jest": "^27.4.1",
     "@types/node": "^18.16",
@@ -68,6 +70,7 @@
     "rimraf": "^3.0.2",
     "ts-jest": "^27.1.4",
     "ts-node": "^10.7.0",
+    "tsd": "^0.31.2",
     "typescript": "~4.8.4"
   },
   "packageManager": "[email protected]",

src/fetch.test.ts

@@ -1,4 +1,9 @@
+import { JsonRpcEngine } from '@metamask/json-rpc-engine';
+import type { Json, JsonRpcParams, JsonRpcRequest } from '@metamask/utils';
+
 import { createFetchConfigFromReq } from '.';
+import { createFetchMiddleware } from './fetch';
+import type { AbstractRpcService } from './types';
 
 /**
  * Generate a base64-encoded string from a binary string. This should be equivalent to
@@ -12,7 +17,178 @@ function btoa(stringToEncode: string) {
   return Buffer.from(stringToEncode).toString('base64');
 }
 
-describe('fetch', () => {
+describe('createFetchMiddleware', () => {
+  it('calls the RPC service with the correct request headers and body when no `originHttpHeaderKey` option given', async () => {
+    const rpcService = buildRpcService();
+    const requestSpy = jest.spyOn(rpcService, 'request');
+    const middleware = createFetchMiddleware({
+      rpcService,
+    });
+
+    const engine = new JsonRpcEngine();
+    engine.push(middleware);
+    await engine.handle({
+      id: 1,
+      jsonrpc: '2.0',
+      method: 'eth_chainId',
+      params: [],
+    });
+
+    expect(requestSpy).toHaveBeenCalledWith(
+      {
+        id: 1,
+        jsonrpc: '2.0',
+        method: 'eth_chainId',
+        params: [],
+      },
+      {
+        headers: {},
+      },
+    );
+  });
+
+  it('includes the `origin` from the given request in the request headers under the given `originHttpHeaderKey`', async () => {
+    const rpcService = buildRpcService();
+    const requestSpy = jest.spyOn(rpcService, 'request');
+    const middleware = createFetchMiddleware({
+      rpcService,
+      options: {
+        originHttpHeaderKey: 'X-Dapp-Origin',
+      },
+    });
+
+    const engine = new JsonRpcEngine();
+    engine.push(middleware);
+    // Type assertion: This isn't really a proper JSON-RPC request, but we have
+    // to get `json-rpc-engine` to think it is.
+    await engine.handle({
+      id: 1,
+      jsonrpc: '2.0' as const,
+      method: 'eth_chainId',
+      params: [],
+      origin: 'somedapp.com',
+    } as JsonRpcRequest);
+
+    expect(requestSpy).toHaveBeenCalledWith(
+      {
+        id: 1,
+        jsonrpc: '2.0',
+        method: 'eth_chainId',
+        params: [],
+      },
+      {
+        headers: {
+          'X-Dapp-Origin': 'somedapp.com',
+        },
+      },
+    );
+  });
+
+  describe('if the request to the service returns a successful JSON-RPC response', () => {
+    it('includes the `result` field from the RPC service in its own response', async () => {
+      const rpcService = buildRpcService();
+      jest.spyOn(rpcService, 'request').mockResolvedValue({
+        id: 1,
+        jsonrpc: '2.0',
+        result: 'the result',
+      });
+      const middleware = createFetchMiddleware({
+        rpcService,
+      });
+
+      const engine = new JsonRpcEngine();
+      engine.push(middleware);
+      const result = await engine.handle({
+        id: 1,
+        jsonrpc: '2.0',
+        method: 'eth_chainId',
+        params: [],
+      });
+
+      expect(result).toStrictEqual({
+        id: 1,
+        jsonrpc: '2.0',
+        result: 'the result',
+      });
+    });
+  });
+
+  describe('if the request to the service returns a unsuccessful JSON-RPC response', () => {
+    it('includes the `error` field from the service in a new internal JSON-RPC error', async () => {
+      const rpcService = buildRpcService();
+      jest.spyOn(rpcService, 'request').mockResolvedValue({
+        id: 1,
+        jsonrpc: '2.0',
+        error: {
+          code: -1000,
+          message: 'oops',
+        },
+      });
+      const middleware = createFetchMiddleware({
+        rpcService,
+      });
+
+      const engine = new JsonRpcEngine();
+      engine.push(middleware);
+      const result = await engine.handle({
+        id: 1,
+        jsonrpc: '2.0',
+        method: 'eth_chainId',
+        params: [],
+      });
+
+      expect(result).toMatchObject({
+        id: 1,
+        jsonrpc: '2.0',
+        error: {
+          code: -32603,
+          message: 'Internal JSON-RPC error.',
+          stack: expect.stringContaining('Internal JSON-RPC error.'),
+          data: {
+            code: -1000,
+            message: 'oops',
+            cause: null,
+          },
+        },
+      });
+    });
+  });
+
+  describe('if the request to the service throws', () => {
+    it('includes the message and stack of the error in a new JSON-RPC error', async () => {
+      const rpcService = buildRpcService();
+      jest.spyOn(rpcService, 'request').mockRejectedValue(new Error('oops'));
+      const middleware = createFetchMiddleware({
+        rpcService,
+      });
+
+      const engine = new JsonRpcEngine();
+      engine.push(middleware);
+      const result = await engine.handle({
+        id: 1,
+        jsonrpc: '2.0',
+        method: 'eth_chainId',
+        params: [],
+      });
+
+      expect(result).toMatchObject({
+        id: 1,
+        jsonrpc: '2.0',
+        error: {
+          code: -32603,
+          data: {
+            cause: {
+              message: 'oops',
+              stack: expect.stringContaining('Error: oops'),
+            },
+          },
+        },
+      });
+    });
+  });
+});
+
+describe('createFetchConfigFromReq', () => {
   it('should create a fetch config from a request', async () => {
     const req = {
       id: 1,
@@ -65,3 +241,44 @@ describe('fetch', () => {
     });
   });
 });
+
+/**
+ * Constructs a fake RPC service for use as a failover in tests.
+ *
+ * @returns The fake failover service.
+ */
+function buildRpcService(): AbstractRpcService {
+  return {
+    async request<Params extends JsonRpcParams, Result extends Json>(
+      jsonRpcRequest: JsonRpcRequest<Params>,
+      _fetchOptions?: RequestInit,
+    ) {
+      return {
+        id: jsonRpcRequest.id,
+        jsonrpc: jsonRpcRequest.jsonrpc,
+        result: 'ok' as Result,
+      };
+    },
+    onRetry() {
+      return {
+        dispose() {
+          // do nothing
+        },
+      };
+    },
+    onBreak() {
+      return {
+        dispose() {
+          // do nothing
+        },
+      };
+    },
+    onDegraded() {
+      return {
+        dispose() {
+          // do nothing
+        },
+      };
+    },
+  };
+}