[Cosmos] Simple endpoint refresh interval

sdk/cosmosdb/cosmos/review/cosmos.api.md

@@ -112,8 +112,12 @@ export class ClientContext {
     // (undocumented)
     getReadEndpoint(): Promise<string>;
     // (undocumented)
+    getReadEndpoints(): Promise<readonly string[]>;
+    // (undocumented)
     getWriteEndpoint(): Promise<string>;
     // (undocumented)
+    getWriteEndpoints(): Promise<readonly string[]>;
+    // (undocumented)
     partitionKeyDefinitionCache: {
         [containerUrl: string]: any;
     };
@@ -236,6 +240,7 @@ export enum ConnectionMode {
 export interface ConnectionPolicy {
     connectionMode?: ConnectionMode;
     enableEndpointDiscovery?: boolean;
+    endpointRefreshRateInMs?: number;
     preferredLocations?: string[];
     requestTimeout?: number;
     retryOptions?: RetryOptions;
@@ -486,9 +491,12 @@ export class CosmosClient {
     constructor(options: CosmosClientOptions);
     database(id: string): Database;
     readonly databases: Databases;
+    dispose(): void;
     getDatabaseAccount(options?: RequestOptions): Promise<ResourceResponse<DatabaseAccount>>;
     getReadEndpoint(): Promise<string>;
+    getReadEndpoints(): Promise<readonly string[]>;
     getWriteEndpoint(): Promise<string>;
+    getWriteEndpoints(): Promise<readonly string[]>;
     offer(id: string): Offer;
     readonly offers: Offers;
 }

sdk/cosmosdb/cosmos/src/ClientContext.ts

@@ -544,6 +544,14 @@ export class ClientContext {
     return this.globalEndpointManager.getReadEndpoint();
   }
 
+  public getWriteEndpoints(): Promise<readonly string[]> {
+    return this.globalEndpointManager.getWriteEndpoints();
+  }
+
+  public getReadEndpoints(): Promise<readonly string[]> {
+    return this.globalEndpointManager.getReadEndpoints();
+  }
+
   public async bulk<T>({
     body,
     path,

sdk/cosmosdb/cosmos/src/CosmosClient.ts

@@ -50,6 +50,7 @@ export class CosmosClient {
    */
   public readonly offers: Offers;
   private clientContext: ClientContext;
+  private endpointRefresher: NodeJS.Timer;
   /**
    * Creates a new {@link CosmosClient} object from a connection string. Your database connection string can be found in the Azure Portal
    */
@@ -93,6 +94,12 @@ export class CosmosClient {
       async (opts: RequestOptions) => this.getDatabaseAccount(opts)
     );
     this.clientContext = new ClientContext(optionsOrConnectionString, globalEndpointManager);
+    if (optionsOrConnectionString.connectionPolicy?.enableEndpointDiscovery) {
+      this.backgroundRefreshEndpointList(
+        globalEndpointManager,
+        optionsOrConnectionString.connectionPolicy.endpointRefreshRateInMs
+      );
+    }
 
     this.databases = new Databases(this, this.clientContext);
     this.offers = new Offers(this, this.clientContext);
@@ -126,6 +133,24 @@ export class CosmosClient {
     return this.clientContext.getReadEndpoint();
   }
 
+  /**
+   * Gets the known write endpoints. Useful for troubleshooting purposes.
+   *
+   * The urls may contain a region suffix (e.g. "-eastus") if we're using location specific endpoints.
+   */
+  public getWriteEndpoints(): Promise<readonly string[]> {
+    return this.clientContext.getWriteEndpoints();
+  }
+
+  /**
+   * Gets the currently used read endpoint. Useful for troubleshooting purposes.
+   *
+   * The url may contain a region suffix (e.g. "-eastus") if we're using location specific endpoints.
+   */
+  public getReadEndpoints(): Promise<readonly string[]> {
+    return this.clientContext.getReadEndpoints();
+  }
+
   /**
    * Used for reading, updating, or deleting a existing database by id or accessing containers belonging to that database.
    *
@@ -153,4 +178,28 @@ export class CosmosClient {
   public offer(id: string): Offer {
     return new Offer(this, id, this.clientContext);
   }
+
+  /**
+   * Clears background endpoint refresher. Use client.dispose() when destroying the CosmosClient within another process.
+   */
+  public dispose(): void {
+    clearTimeout(this.endpointRefresher);
+  }
+
+  private async backgroundRefreshEndpointList(
+    globalEndpointManager: GlobalEndpointManager,
+    refreshRate: number
+  ) {
+    this.endpointRefresher = setInterval(() => {
+      try {
+        globalEndpointManager.refreshEndpointList();
+      } catch (e) {
+        console.warn("Failed to refresh endpoints", e);
+      }
+    }, refreshRate);
+    const isBrowser = new Function("try {return this===window;}catch(e){ return false;}");
+    if (!isBrowser) {
+      this.endpointRefresher.unref();
+    }
+  }
 }

sdk/cosmosdb/cosmos/src/documents/ConnectionPolicy.ts

@@ -10,7 +10,10 @@ export interface ConnectionPolicy {
   connectionMode?: ConnectionMode;
   /** Request timeout (time to wait for response from network peer). Represented in milliseconds. */
   requestTimeout?: number;
-  /** Flag to enable/disable automatic redirecting of requests based on read/write operations. */
+  /**
+   * Flag to enable/disable automatic redirecting of requests based on read/write operations.
+   * Required to call client.dispose() when this is set to true after destroying the CosmosClient inside another process or in the browser.
+   */
   enableEndpointDiscovery?: boolean;
   /** List of azure regions to be used as preferred locations for read requests. */
   preferredLocations?: string[];
@@ -21,16 +24,23 @@ export interface ConnectionPolicy {
    * Default is `false`.
    */
   useMultipleWriteLocations?: boolean;
+  /** Rate in milliseconds at which the client will refresh the endpoints list in the background */
+  endpointRefreshRateInMs?: number;
 }
 
 /**
  * @hidden
  */
-export const defaultConnectionPolicy = Object.freeze({
+export const defaultConnectionPolicy: ConnectionPolicy = Object.freeze({
   connectionMode: ConnectionMode.Gateway,
   requestTimeout: 60000,
   enableEndpointDiscovery: true,
   preferredLocations: [],
-  retryOptions: {},
-  useMultipleWriteLocations: true
+  retryOptions: {
+    maxRetryAttemptCount: 9,
+    fixedRetryIntervalInMilliseconds: 100,
+    maxWaitTimeInSeconds: 30
+  },
+  useMultipleWriteLocations: true,
+  endpointRefreshRateInMs: 300000
 });

sdk/cosmosdb/cosmos/src/globalEndpointManager.ts

@@ -25,8 +25,8 @@ export class GlobalEndpointManager {
    * List of azure regions to be used as preferred locations for read requests.
    */
   private preferredLocations: string[];
-  private writeableLocations: Location[];
-  private readableLocations: Location[];
+  private writeableLocations: Location[] = [];
+  private readableLocations: Location[] = [];
 
   /**
    * @param options - The document client instance.
@@ -175,7 +175,7 @@ export class GlobalEndpointManager {
         this.writeableLocations.push(location);
       }
     }
-    for (const location of databaseAccount.writableLocations) {
+    for (const location of databaseAccount.readableLocations) {
       const existingLocation = this.readableLocations.find((loc) => loc.name === location.name);
       if (!existingLocation) {
         this.readableLocations.push(location);

sdk/cosmosdb/cosmos/test/public/functional/client.spec.ts

@@ -13,6 +13,7 @@ import {
 } from "../common/TestHelpers";
 import AbortController from "node-abort-controller";
 import { UsernamePasswordCredential } from "@azure/identity";
+import { defaultConnectionPolicy } from "../../../src/documents";
 
 describe("NodeJS CRUD Tests", function(this: Suite) {
   this.timeout(process.env.MOCHA_TIMEOUT || 20000);
@@ -126,4 +127,34 @@ describe("NodeJS CRUD Tests", function(this: Suite) {
       }
     });
   });
+  describe("Background refresher", async function() {
+    // not async to leverage done() callback inside setTimeout
+    it("should fetch new endpoints", function(done) {
+      // set refresh rate to 700ms
+      const client = new CosmosClient({
+        endpoint,
+        key: masterKey,
+        connectionPolicy: { ...defaultConnectionPolicy, endpointRefreshRateInMs: 700 }
+      });
+
+      // then timeout 1.2s so that we first fetch no endpoints, then after it refreshes we see them
+      client
+        .getReadEndpoints()
+        .then((firstEndpoints) => {
+          assert.equal(firstEndpoints.length, 0);
+          setTimeout(() => {
+            client
+              .getReadEndpoints()
+              .then((endpoints) => {
+                assert.notEqual(firstEndpoints, endpoints);
+                done();
+                return;
+              })
+              .catch(console.warn);
+          }, 1200);
+          return;
+        })
+        .catch(console.warn);
+    });
+  });
 });