docs: add supplemental docs (#5776)

* docs: add supplemental docs

* docs: more about client options

Author: kuhe

README.md

@@ -153,7 +153,7 @@ Here’s an example of logging requests using middleware:
 const client = new DynamoDB({ region: "us-west-2" });
 
 client.middlewareStack.add(
-  (next, context) => (args) => {
+  (next, context) => async (args) => {
     console.log("AWS SDK context", context.clientName, context.commandName);
     console.log("AWS SDK request input", args.input);
     const result = await next(args);
@@ -533,7 +533,7 @@ const client = new S3({ region: "us-west-2" });
 
 // Middleware added to client, applies to all commands.
 client.middlewareStack.add(
-  (next, context) => (args) => {
+  (next, context) => async (args) => {
     args.request.headers["x-amz-meta-foo"] = "bar";
     console.log("AWS SDK context", context.clientName, context.commandName);
     console.log("AWS SDK request input", args.input);

private/aws-client-api-test/src/client-interface-tests/client-s3/impl/initializeWithMaximalConfiguration.ts

@@ -1,6 +1,7 @@
-import { S3Client } from "@aws-sdk/client-s3";
-import { defaultProvider as credentialDefaultProvider } from "@aws-sdk/credential-provider-node";
+import { S3Client, S3ClientConfigType } from "@aws-sdk/client-s3";
+import { defaultProvider as credentialDefaultProvider, defaultProvider } from "@aws-sdk/credential-provider-node";
 import { NODE_USE_ARN_REGION_CONFIG_OPTIONS } from "@aws-sdk/middleware-bucket-endpoint";
+import { S3ExpressIdentityProviderImpl } from "@aws-sdk/middleware-sdk-s3";
 import { SignatureV4MultiRegion } from "@aws-sdk/signature-v4-multi-region";
 import { defaultUserAgent } from "@aws-sdk/util-user-agent-node";
 import {
@@ -14,16 +15,17 @@ import { Hash } from "@smithy/hash-node";
 import { readableStreamHasher as streamHasher } from "@smithy/hash-stream-node";
 import { NODE_MAX_ATTEMPT_CONFIG_OPTIONS, NODE_RETRY_MODE_CONFIG_OPTIONS } from "@smithy/middleware-retry";
 import { loadConfig as loadNodeConfig } from "@smithy/node-config-provider";
-import { NodeHttpHandler as RequestHandler, streamCollector } from "@smithy/node-http-handler";
+import { NodeHttpHandler, streamCollector } from "@smithy/node-http-handler";
 import { loadConfigsForDefaultMode } from "@smithy/smithy-client";
 import { EndpointV2 } from "@smithy/types";
 import { parseUrl } from "@smithy/url-parser";
 import { fromBase64, toBase64 } from "@smithy/util-base64";
 import { calculateBodyLength } from "@smithy/util-body-length-node";
 import { resolveDefaultsModeConfig } from "@smithy/util-defaults-mode-node";
-import { DEFAULT_RETRY_MODE } from "@smithy/util-retry";
+import { ConfiguredRetryStrategy, DEFAULT_RETRY_MODE, StandardRetryStrategy } from "@smithy/util-retry";
 import { getAwsChunkedEncodingStream, sdkStreamMixin } from "@smithy/util-stream";
 import { fromUtf8, toUtf8 } from "@smithy/util-utf8";
+import https from "https";
 
 /**
  * Successful compilation indicates the client can be initialized
@@ -33,51 +35,90 @@ export const initializeWithMaximalConfiguration = () => {
   const defaultsMode = resolveDefaultsModeConfig({});
   const defaultConfigProvider = () => defaultsMode().then(loadConfigsForDefaultMode);
 
-  const s3 = new S3Client({
+  const config: Required<S3ClientConfigType> = {
+    // BEGIN user options
+    region: loadNodeConfig(NODE_REGION_CONFIG_OPTIONS, NODE_REGION_CONFIG_FILE_OPTIONS),
+    credentials: defaultProvider({}),
     endpoint: "endpoint",
-    customUserAgent: "aws-client-api-test-user-agent",
-    apiVersion: "2006-03-01",
-    base64Decoder: fromBase64,
-    base64Encoder: toBase64,
-    disableHostPrefix: false,
-    endpointProvider: () => null as unknown as EndpointV2,
+    requestHandler: new NodeHttpHandler({
+      httpsAgent: new https.Agent({
+        maxSockets: 200,
+        keepAlive: true,
+      }),
+      requestTimeout: 15000,
+      connectionTimeout: 6000,
+    }),
+    retryStrategy:
+      new StandardRetryStrategy(3) ||
+      new ConfiguredRetryStrategy(3, (attempt) => {
+        return attempt * 1_000;
+      }),
+    retryMode: loadNodeConfig({
+      ...NODE_RETRY_MODE_CONFIG_OPTIONS,
+      default: async () => (await defaultConfigProvider()).retryMode || DEFAULT_RETRY_MODE,
+    }),
+    maxAttempts: loadNodeConfig(NODE_MAX_ATTEMPT_CONFIG_OPTIONS),
     logger: {
       trace() {},
       debug() {},
       info() {},
       warn() {},
       error() {},
     },
+    signer: new SignatureV4MultiRegion({
+      service: "s3",
+      region: "us-west-2",
+      credentials: defaultProvider({}),
+      sha256: Hash.bind(null, "sha256"),
+    }),
+    useDualstackEndpoint: loadNodeConfig(NODE_USE_DUALSTACK_ENDPOINT_CONFIG_OPTIONS),
+    useFipsEndpoint: loadNodeConfig(NODE_USE_FIPS_ENDPOINT_CONFIG_OPTIONS),
+    customUserAgent: "aws-client-api-test-user-agent",
+    extensions: [],
+    tls: true,
+    disableHostPrefix: false,
+    signingRegion: "us-west-2",
+    // END user options
+
+    // BEGIN internal options
+    apiVersion: "2006-03-01",
     serviceId: "S3",
+    runtime: "node",
+    systemClockOffset: 0,
     signerConstructor: SignatureV4MultiRegion,
-    signingEscapePath: false,
+    endpointProvider: () => null as unknown as EndpointV2,
     urlParser: parseUrl,
-    runtime: "node",
+    base64Decoder: fromBase64,
+    base64Encoder: toBase64,
     defaultsMode,
     bodyLengthChecker: calculateBodyLength,
     credentialDefaultProvider: credentialDefaultProvider,
     defaultUserAgentProvider: defaultUserAgent({ serviceId: "S3", clientVersion: "3.0.0-client-s3-interface-test" }),
     eventStreamSerdeProvider: eventStreamSerdeProvider,
     getAwsChunkedEncodingStream: getAwsChunkedEncodingStream,
-    maxAttempts: loadNodeConfig(NODE_MAX_ATTEMPT_CONFIG_OPTIONS),
     md5: Hash.bind(null, "md5"),
-    region: loadNodeConfig(NODE_REGION_CONFIG_OPTIONS, NODE_REGION_CONFIG_FILE_OPTIONS),
-    requestHandler: new RequestHandler(defaultConfigProvider),
-    retryMode: loadNodeConfig({
-      ...NODE_RETRY_MODE_CONFIG_OPTIONS,
-      default: async () => (await defaultConfigProvider()).retryMode || DEFAULT_RETRY_MODE,
-    }),
     sdkStreamMixin: sdkStreamMixin,
     sha1: Hash.bind(null, "sha1"),
     sha256: Hash.bind(null, "sha256"),
     streamCollector: streamCollector,
     streamHasher: streamHasher,
-    useArnRegion: loadNodeConfig(NODE_USE_ARN_REGION_CONFIG_OPTIONS),
-    useDualstackEndpoint: loadNodeConfig(NODE_USE_DUALSTACK_ENDPOINT_CONFIG_OPTIONS),
-    useFipsEndpoint: loadNodeConfig(NODE_USE_FIPS_ENDPOINT_CONFIG_OPTIONS),
     utf8Decoder: fromUtf8,
     utf8Encoder: toUtf8,
-  });
+    // END internal options
+
+    // S3 specific options below
+    useAccelerateEndpoint: false,
+    useArnRegion: loadNodeConfig(NODE_USE_ARN_REGION_CONFIG_OPTIONS),
+    forcePathStyle: false,
+    disableMultiregionAccessPoints: false,
+    followRegionRedirects: false,
+    s3ExpressIdentityProvider: new S3ExpressIdentityProviderImpl("createSessionFn" as any),
+    disableS3ExpressSessionAuth: false,
+    useGlobalEndpoint: false,
+    signingEscapePath: false,
+  };
+
+  const s3 = new S3Client(config);
 
   return s3;
 };