Failover configuration

examples/cookbook/api-keys/near-connection.js

@@ -7,16 +7,15 @@ const CREDENTIALS_DIR = ".near-credentials";
 const credentialsPath = path.join(homedir, CREDENTIALS_DIR);
 const keyStore = new keyStores.UnencryptedFileSystemKeyStore(credentialsPath);
 
-const RPC_API_ENDPOINT = '<Replace this string with your RPC server URL>';
 const API_KEY = '<Replace this string with your API KEY>';
-
 const ACCOUNT_ID = '<Replace this string with existing account ID>';
 
 const config = {
     networkId: 'testnet',
     keyStore,
-    nodeUrl: RPC_API_ENDPOINT,
-    headers: { 'x-api-key': API_KEY },
+    nodeUrl: '<Replace this string with your RPC server URL>',
+    // RPC server URL in apiKeys should match the one specified in nodeUrl
+    apiKeys: { '<Replace this string with your RPC server URL>': API_KEY },
 };
 
 async function getState(accountId) {

examples/cookbook/api-keys/provider-example.js

@@ -1,12 +1,12 @@
 // demonstrates how to use API-KEY with provider 
 const { providers } = require("near-api-js");
 
-const RPC_API_ENDPOINT = '<Replace this string with your RPC server URL>';
 const API_KEY = '<Replace this string with your API KEY>';
 
 const provider = new providers.JsonRpcProvider({
-    url: RPC_API_ENDPOINT,
-    headers: { 'x-api-key': API_KEY },
+    url: '<Replace this string with your RPC server URL>',
+    // RPC server URL in apiKeys should match the one specified in url
+    apiKeys: { '<Replace this string with your RPC server URL>': API_KEY }
 });
 
 getNetworkStatus();

examples/cookbook/failover-configuration.js

@@ -0,0 +1,36 @@
+// Demonstrates how to use failover functionality RPC Servers
+const { providers, connect } = require("near-api-js");
+
+const MAIN_RPC_SERVER = '<RPC Server 1>';
+const FAILOVER_RPC_SERVER_1 = '<RPC Server 2>';
+const FAILOVER_RPC_SERVER_2 = '<RPC Server 1>';
+
+// Provider example
+const provider = new providers.JsonRpcProvider({
+    // preoritized list of RPC Servers
+    url: [MAIN_RPC_SERVER, FAILOVER_RPC_SERVER_1, FAILOVER_RPC_SERVER_2],
+});
+
+async function getNetworkStatus() {
+    const result = await provider.status();
+    console.log(result);
+}
+
+getNetworkStatus();
+
+// Connection example
+const ACCOUNT_ID = "<Account ID>";
+
+const config = {
+    networkId: 'testnet',
+    nodeUrl: [MAIN_RPC_SERVER, FAILOVER_RPC_SERVER_1, FAILOVER_RPC_SERVER_2],
+};
+
+async function getState(accountId) {
+    const near = await connect(config);
+    const account = await near.account(accountId);
+    const state = await account.state();
+    console.log(state);
+}
+
+getState(ACCOUNT_ID);

src/near.ts

@@ -50,10 +50,16 @@ export interface NearConfig {
     networkId: string;
 
     /**
-     * NEAR RPC API url. used to make JSON RPC calls to interact with NEAR.
+     * NEAR RPC API url. Used to make JSON RPC calls to interact with NEAR.
+     * You can set multiple RPC Server URLs to turn on failover functionality.
      * @see {@link JsonRpcProvider.JsonRpcProvider | JsonRpcProvider}
      */
-    nodeUrl: string;
+    nodeUrl: string | string[];
+
+    /**
+     * RPC API Keys. Used to authenticate users on RPC Server.
+     */
+    apiKeys: string;
 
     /**
      * NEAR RPC API headers. Can be used to pass API KEY and other parameters.
@@ -84,7 +90,13 @@ export class Near {
         this.config = config;
         this.connection = Connection.fromConfig({
             networkId: config.networkId,
-            provider: { type: 'JsonRpcProvider', args: { url: config.nodeUrl, headers: config.headers } },
+            provider: {
+                type: 'JsonRpcProvider', args: {
+                    url: config.nodeUrl,
+                    apiKeys: config.apiKeys,
+                    headers: config.headers,
+                }
+            },
             signer: config.signer || { type: 'InMemorySigner', keyStore: config.keyStore || (config.deps && config.deps.keyStore) }
         });
         if (config.masterAccount) {

src/providers/json-rpc-provider.ts

@@ -339,6 +339,19 @@ export class JsonRpcProvider extends Provider {
         return await this.sendJsonRpc('gas_price', [blockId]);
     }
 
+    /**
+     * Part of the RPC failover design.
+     * Changing current (first) rpc server and moves it to the and of the queue.
+     */
+    private rotateRpcServers() {
+        if (typeof this.connection.url === 'string') { return; }
+        const currentRpcServer = this.connection.url.shift();
+        this.connection.url.push(currentRpcServer);
+        if (!process.env['NEAR_NO_LOGS']) {
+            console.warn(`Switched from ${currentRpcServer} RPC Server to ${this.connection.url[0]}`);
+        }
+    }
+
     /**
      * Directly call the RPC specifying the method and params
      *
@@ -379,9 +392,11 @@ export class JsonRpcProvider extends Provider {
                 return response;
             } catch (error) {
                 if (error.type === 'TimeoutError') {
-                    if (!process.env['NEAR_NO_LOGS']){
+                    if (!process.env['NEAR_NO_LOGS']) {
                         console.warn(`Retrying request to ${method} as it has timed out`, params);
                     }
+                    // switch  to another server if it's available
+                    this.rotateRpcServers();
                     return null;
                 }
 

src/utils/web.ts

@@ -9,7 +9,9 @@ const BACKOFF_MULTIPLIER = 1.5;
 const RETRY_NUMBER = 10;
 
 export interface ConnectionInfo {
-    url: string;
+    // RPC Server URL or the prioritized array of such URLs
+    url: string | string[];
+    apiKeys?: { [url: string]: string };
     user?: string;
     password?: string;
     allowInsecure?: boolean;
@@ -25,31 +27,37 @@ export async function fetchJson(connectionInfoOrUrl: string | ConnectionInfo, js
         connectionInfo = connectionInfoOrUrl as ConnectionInfo;
     }
 
+    const currentRpcServer = typeof connectionInfo.url === 'string' ? connectionInfo.url : connectionInfo.url[0];
+
     const response = await exponentialBackoff(START_WAIT_TIME_MS, RETRY_NUMBER, BACKOFF_MULTIPLIER, async () => {
         try {
-            const response = await fetch(connectionInfo.url, {
+            const response = await fetch(currentRpcServer, {
                 method: json ? 'POST' : 'GET',
                 body: json ? json : undefined,
-                headers: { ...connectionInfo.headers, 'Content-Type': 'application/json' }
+                headers: {
+                    'Content-Type': 'application/json',
+                    'x-api-key': connectionInfo.apiKeys ? connectionInfo.apiKeys[currentRpcServer] : undefined,
+                    ...connectionInfo.headers,
+                },
             });
             if (!response.ok) {
                 if (response.status === 503) {
-                    logWarning(`Retrying HTTP request for ${connectionInfo.url} as it's not available now`);
+                    logWarning(`Retrying HTTP request for ${currentRpcServer} as it's not available now`);
                     return null;
                 }
                 throw createError(response.status, await response.text());
             }
             return response;
         } catch (error) {
             if (error.toString().includes('FetchError') || error.toString().includes('Failed to fetch')) {
-                logWarning(`Retrying HTTP request for ${connectionInfo.url} because of error: ${error}`);
+                logWarning(`Retrying HTTP request for ${currentRpcServer} because of error: ${error}`);
                 return null;
             }
             throw error;
         }
     });
     if (!response) {
-        throw new TypedError(`Exceeded ${RETRY_NUMBER} attempts for ${connectionInfo.url}.`, 'RetriesExceeded');
+        throw new TypedError(`Exceeded ${RETRY_NUMBER} attempts for ${currentRpcServer}.`, 'RetriesExceeded');
     }
     return await response.json();
 }