[cosmos] Correct documentation for enableBackgroundEndpointRefreshing default value

[heguro]

Packages impacted by this PR

@azure/cosmos

Issues associated with this PR

Describe the problem that is addressed by this PR

JSDoc comment and documentation incorrectly state that enableBackgroundEndpointRefreshing defaults to false, when the actual default value is true as shown in the defaultConnectionPolicy object:

azure-sdk-for-js/sdk/cosmosdb/cosmos/src/documents/ConnectionPolicy.ts

Line 50 in fe306bc

enableBackgroundEndpointRefreshing: true,

What are the possible designs available to address the problem? If there are more than one possible design, why was the one in this PR chosen?

Are there test cases added in this PR? (If not, why?)

Provide a list of related PRs (if any)

#15781 (implemented this parameter)

Command used to generate this PR:**(Applicable only to SDK release request PRs)

Checklists

• Added impacted package name to the issue description
• Does this PR needs any fixes in the SDK Generator?** (If so, create an Issue in the Autorest/typescript repository and link it here)
• Added a changelog (if necessary)

[github-actions]

Thank you for your contribution @heguro! We will review the pull request and get back to you soon.

[azure-sdk]

API change check

API changes are not detected in this pull request.

[github-actions]

Hi @heguro. Thank you for your interest in helping to improve the Azure SDK experience and for your contribution. We've noticed that there hasn't been recent engagement on this pull request. If this is still an active work stream, please let us know by pushing some changes or leaving a comment. Otherwise, we'll close this out in 7 days.

[amanrao23]

During client initialization, user has the option to specify connection policy.

If no connection policy is supplied, then defaultConnectionPolicy is picked up (Value of enableBackgroundEndpointRefreshing flag is true here)

If a connection policy is supplied and enableBackgroundEndpointRefreshing is not set in the custom connection policy, then by default it picks up value as false.

[heguro]

If a connection policy is supplied and enableBackgroundEndpointRefreshing is not set in the custom connection policy, then by default it picks up value as false.

I believe this is not correct. My understanding is that it is only treated as false if enableBackgroundEndpointRefreshing: false (or any falsy value) is explicitly set during client initialization.

azure-sdk-for-js/sdk/cosmosdb/cosmos/src/CosmosClient.ts

Lines 127 to 131 in 4d652c5

	optionsOrConnectionString.connectionPolicy = Object.assign(
	{},
	defaultConnectionPolicy,
	optionsOrConnectionString.connectionPolicy,
	);

As seen here, Object.assign() merges defaultConnectionPolicy with the connectionPolicy provided by the user. Unless the user explicitly sets the enableBackgroundEndpointRefreshing property, the default value of true from defaultConnectionPolicy is applied.

For example, when configured as shown below, enableBackgroundEndpointRefreshing is treated as true, and I confirmed that this.backgroundRefreshEndpointList() is executed within CosmosClient.ts.

const client = new CosmosClient({
  endpoint: "something",
  key: "something",
  connectionPolicy: {
    requestTimeout: 1_000_000,
    // enableBackgroundEndpointRefreshing property is not specified
  },
});

If no connection policy is supplied, then defaultConnectionPolicy is picked up (Value of enableBackgroundEndpointRefreshing flag is true here)

Furthermore, this behavior (that the default is true when no connection policy is supplied or when the property is not explicitly set in a supplied policy) is not mentioned anywhere in the documentation. This lack of documentation, requiring users to read the source code to understand the actual default behavior, can be confusing.