docs(UPGRADING): on the use of expiration in credential provider functions (#5961)

Author: kuhe

UPGRADING.md

@@ -36,7 +36,8 @@ This list is indexed by [v2 config parameters](https://docs.aws.amazon.com/AWSJa
   - **v3**: No change.
 - [`credentials`](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#credentials-property)
   - **v2**: The AWS credentials to sign requests with.
-  - **v3**: No change. It can also be an async function that returns credentials.
+  - **v3**: No change. It can also be an async function that returns credentials. If the function returns an `expiration (Date)`, the function will
+    be called again when the expiration datetime nears.
     See [v3 reference for AwsAuthInputConfig credentials](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/interfaces/_aws_sdk_middleware_signing.awsauthinputconfig-1.html#credentials).
 - [`endpointCacheSize`](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#endpointCacheSize-property)
   - **v2**: The size of the global cache storing endpoints from endpoint discovery operations.

supplemental-docs/CLIENTS.md

@@ -135,10 +135,17 @@ import { fromCognitoIdentity } from "@aws-sdk/credential-providers";
 const client = new S3Client({
   credentials: async () => {
     // get credentials from any source.
+    const credentials = {
+      /* ... */
+    };
     return {
-      accessKeyId: "...",
-      secretAccessKey: "...",
-      sessionToken: "...",
+      accessKeyId: credentials.accessKeyId,
+      secretAccessKey: "etc.",
+      sessionToken: "etc.",
+      // 1. You can set an expiration near which this function will be called again.
+      // 2. You can use the expiration given by your upstream credentials provider, if it exists.
+      // 3. Omitting an expiration will result in this function not being called more than once.
+      expiration: new Date(),
     };
   },
 });
@@ -340,11 +347,12 @@ const client = new DynamoDBClient({
   requestHandler: new NodeHttpHandler({
     requestTimeout: 3_000,
     httpsAgent: new https.Agent({
-      maxSockets: 25
+      maxSockets: 25,
     }),
   }),
 });
 ```
+
 ```ts
 // Example: short form requestHandler configuration.
 import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
@@ -356,8 +364,9 @@ const client = new DynamoDBClient({
   },
 });
 ```
+
 You can instead pass the constructor parameters directly. The default requestHandler for the platform and service will be used.
-For Node.js, most services use `NodeHttpHandler`. For browsers, most services use `FetchHttpHandler`. 
+For Node.js, most services use `NodeHttpHandler`. For browsers, most services use `FetchHttpHandler`.
 
 Kinesis, Lex Runtime v2, QBusiness, TranscribeStreaming use `NodeHttp2Handler` by default instead in Node.js.
 RekognitionStreaming and TranscribeStreaming use the `WebSocketFetchHandler` by default instead in browsers.