diff --git a/UPGRADING.md b/UPGRADING.md index 1e2f27ccf372..c7b14cc106ec 100644 --- a/UPGRADING.md +++ b/UPGRADING.md @@ -4,7 +4,8 @@ This document captures notable changes from AWS SDK for JavaScript v2 to v3. The v3 is also known as modular AWS SDK for JavaScript. Because, v3 is a modular rewrite of v2, some basic conceptions are different between v2 and v3. You can learn about -these changes in our [blog posts](https://aws.amazon.com/blogs/developer/category/developer-tools/aws-sdk-for-javascript-in-node-js/). +these changes in +our [blog posts](https://aws.amazon.com/blogs/developer/category/developer-tools/aws-sdk-for-javascript-in-node-js/). The following blog posts will get you up to speed: - [Modular packages in AWS SDK for JavaScript](https://aws.amazon.com/blogs/developer/modular-packages-in-aws-sdk-for-javascript/) @@ -22,8 +23,10 @@ This list is indexed by [v2 config parameters](https://docs.aws.amazon.com/AWSJa only). - **v3**: applicable commands of S3 (PutObject, PutBucketCors, etc.) will automatically compute the MD5 checksums for of the request payload. You can also specify a different checksum algorithm in the commands' `ChecksumAlgorithm` - parameter to use a different checksum algorithm. You can find more infomation in the [S3 feature announcement](https://aws.amazon.com/blogs/aws/new-additional-checksum-algorithms-for-amazon-s3/) -- [`convertResponseTypes`](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#convertResponseTypes-property) + parameter to use a different checksum algorithm. You can find more infomation in + the [S3 feature announcement](https://aws.amazon.com/blogs/aws/new-additional-checksum-algorithms-for-amazon-s3/) +- [ + `convertResponseTypes`](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#convertResponseTypes-property) - **v2**: Whether types are converted when parsing response data. - **v3**: **Deprecated**. This option is considered not type-safe because it doesn't convert the types like time stamp or base64 binaries from the JSON response. @@ -36,13 +39,15 @@ 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. If the function returns an `expiration (Date)`, the function will + - **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. - **v3**: No change. -- [`endpointDiscoveryEnabled`](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#endpointDiscoveryEnabled-property) +- [ + `endpointDiscoveryEnabled`](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#endpointDiscoveryEnabled-property) - **v2**: Whether to call operations with endpoints given by service dynamically. - **v3**: No change. - [`hostPrefixEnabled`](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#hostPrefixEnabled-property) @@ -52,7 +57,8 @@ This list is indexed by [v2 config parameters](https://docs.aws.amazon.com/AWSJa A set of options to pass to the low-level HTTP request. These options are aggregated differently in v3. You can configure them by supplying a new `requestHandler`. Here's the example of setting http options in Node.js runtime. You - can find more in [v3 reference for NodeHttpHandler](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-smithy-node-http-handler/). + can find more + in [v3 reference for NodeHttpHandler](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-smithy-node-http-handler/). All v3 requests use HTTPS by default. You can provide a custom agent via the `httpsAgent` field of the `NodeHttpHandler` constructor input. @@ -66,76 +72,113 @@ This list is indexed by [v2 config parameters](https://docs.aws.amazon.com/AWSJa httpsAgent: new Agent({ /*params*/ }), - connectionTimeout: /*number in milliseconds*/, - socketTimeout: /*number in milliseconds*/ + /** + * The maximum time in milliseconds that the connection phase of a request + * may take before the connection attempt is abandoned. + * Defaults to 0, which disables the timeout. + */ + connectionTimeout: 5_000 /*number in milliseconds*/, + /** + * The maximum number of milliseconds request & response should take. + * Defaults to 0, which disables the timeout. + * + * If exceeded, a warning will be emitted unless throwOnRequestTimeout=true, + * in which case a TimeoutError will be thrown. + */ + requestTimeout: 10_000 /*number in milliseconds*/, + /** + * @since 3.910.0 + */ + throwOnRequestTimeout: true, + + /** + * The maximum time in milliseconds that a socket may remain idle before it + * is closed. Defaults to 0, which means no maximum. + * + * This does not affect the server, which may still close the connection due to an idle socket. + */ + socketTimeout: 6_000 /*number in milliseconds*/, }), }); ``` - If you are using a custom endpoint which uses http, then you can provide an `httpAgent`. +In [v3.521.0](https://github.com/aws/aws-sdk-js-v3/releases/tag/v3.521.0) or later, you don't need to import the +`NodeHttpHandler` or https `Agent` classes. Objects will be interpreted as constructor parameters. - ```javascript - const { Agent } = require("http"); - const { NodeHttpHandler } = require("@smithy/node-http-handler"); - - const dynamodbClient = new DynamoDBClient({ - endpoint: "http://example.com", - requestHandler: new NodeHttpHandler({ - httpAgent: new Agent({ - /*params*/ - }), - }), - }); - ``` - - If the client is running in browsers, a different set of options is available. You can find more in [v3 - reference for FetchHttpHandler](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-smithy-fetch-http-handler/). - - ```javascript - const { FetchHttpHandler } = require("@smithy/fetch-http-handler"); +```js +const dynamodbClient = new DynamoDBClient({ + requestHandler: { + httpsAgent: { + maxSockets: 100, + }, + connectionTimeout: 5_000 /*number in milliseconds*/, + requestTimeout: 10_000 /*number in milliseconds*/, + /** + * @since 3.910.0 + */ + throwOnRequestTimeout: true, + socketTimeout: 6_000 /*number in milliseconds*/, + }, +}); +``` - const dynamodbClient = new DynamoDBClient({ - requestHandler: new FetchHttpHandler({ - requestTimeout: /*number in milliseconds*/ - }), - }); - ``` +If the client is running in browsers, a different set of options is available. You can find more in [v3 +reference for FetchHttpHandler](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-smithy-fetch-http-handler/). +Note that the `FetchHttpHandler` does not have the `connectionTimeout` or `socketTimeout` options found in Node.js. - Each option of `httpOptions` is specified below: - - - `proxy` - - **v2**: The URL to proxy requests through - - **v3**: You can set up a proxy with an agent following [Configuring proxies for Node.js](https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/node-configuring-proxies.html) - - `agent` - - - **v2**: The Agent object to perform HTTP requests with. Used for connection pooling. - - **v3**: You can configure `httpAgent` or `httpsAgent` as shown in the examples above. - - - `connectTimeout` - - **v2**: Sets the socket to timeout after failing to establish a connection with the server after connectTimeout - milliseconds. - - **v3**: `connectionTimeout` is available [in `NodeHttpHandler` options](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-smithy-node-http-handler/). - - `timeout` - - **v2**: The number of milliseconds a request can take before automatically being terminated. - - **v3**: `socketTimeout` is available [in `NodeHttpHandler` options](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-smithy-node-http-handler/). - - `xhrAsync` - - **v2**: Whether the SDK will send asynchronous HTTP requests. - - **v3**: **Deprecated**. Requests are _always_ asynchronous. - - `xhrWithCredentials` - - **v2**: Sets the "withCredentials" property of an XMLHttpRequest object. - - **v3**: the `fetch` equivalent field `credentials` can be set via constructor - configuration to the `requestHandler` config when using the browser - default `FetchHttpHandler`. +```javascript +const { FetchHttpHandler } = require("@smithy/fetch-http-handler"); + +const dynamodbClient = new DynamoDBClient({ + requestHandler: new FetchHttpHandler({ + cache: "default", + credentials: "omit", + keepAlive: true, + requestTimeout: 10_000 /*number in milliseconds*/, + }), +}); +``` +Each option of `httpOptions` is specified below: + +- `proxy` + - **v2**: The URL to proxy requests through + - **v3**: You can set up a proxy with an agent + following [Configuring proxies for Node.js](https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/node-configuring-proxies.html) +- `agent` + + - **v2**: The Agent object to perform HTTP requests with. Used for connection pooling. + - **v3**: You can configure `httpAgent` or `httpsAgent` as shown in the examples above. + +- `connectTimeout` + - **v2**: Sets the socket to timeout after failing to establish a connection with the server after connectTimeout + milliseconds. + - **v3**: `connectionTimeout` is available [in + `NodeHttpHandler` options](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-smithy-node-http-handler/). +- `timeout` + - **v2**: The number of milliseconds a request can take before automatically being terminated. + - **v3**: `requestTimeout` is available [in + `NodeHttpHandler` options](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-smithy-node-http-handler/). +- `xhrAsync` + - **v2**: Whether the SDK will send asynchronous HTTP requests. + - **v3**: **Deprecated**. Requests are _always_ asynchronous. +- `xhrWithCredentials` + - **v2**: Sets the "withCredentials" property of an XMLHttpRequest object. + - **v3**: the `fetch` equivalent field `credentials` can be set via constructor + configuration to the `requestHandler` config when using the browser + default `FetchHttpHandler`. - [`logger`](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#logger-property) - - **v2**: An object that responds to .write() (like a stream) or .log() (like the console object) in order to log information about requests. + - **v2**: An object that responds to .write() (like a stream) or .log() (like the console object) in order to log + information about requests. - **v3**: No change. More granular logs are available in v3. - [`maxRedirects`](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#maxRedirects-property) - **v2**: The maximum amount of redirects to follow for a service request. - - **v3**: **Deprecated**. SDK _does not_ follow redirects to avoid unintentional cross-region requests. S3 region redirects can be enabled separately with `followRegionRedirects=true` in the S3 Client only. + - **v3**: **Deprecated**. SDK _does not_ follow redirects to avoid unintentional cross-region requests. S3 region + redirects can be enabled separately with `followRegionRedirects=true` in the S3 Client only. - [`maxRetries`](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#maxRetries-property) - **v2**: The maximum amount of retries to perform for a service request. - - **v3**: Changed to `maxAttempts`. See more in [v3 reference for RetryInputConfig](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-smithy-middleware-retry/#maxattempts). + - **v3**: Changed to `maxAttempts`. See more + in [v3 reference for RetryInputConfig](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-smithy-middleware-retry/#maxattempts). Note that the `maxAttempt` should be `maxRetries + 1`. - [`paramValidation`](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#paramValidation-property) - **v2**: Whether input parameters should be validated against the operation description before sending the request. @@ -145,14 +188,19 @@ This list is indexed by [v2 config parameters](https://docs.aws.amazon.com/AWSJa - **v3**: No change. It can also be an async function that returns a region string. - [`retryDelayOptions`](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#retryDelayOptions-property) - **v2**: A set of options to configure the retry delay on retryable errors. - - **v3**: **Deprecated**. SDK supports more flexible retry strategy with `retryStrategy` client constructor option. See + - **v3**: **Deprecated**. SDK supports more flexible retry strategy with `retryStrategy` client constructor option. + See more [in v3 reference](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-smithy-util-retry/) - [`s3BucketEndpoint`](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#s3BucketEndpoint-property) - **v2**: Whether the provided endpoint addresses an individual bucket (false if it addresses the root API endpoint). - - **v3**: Changed to `bucketEndpoint`. See more in [v3 reference for bucketEndpoint](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/clients/client-s3/interfaces/s3clientconfig.html#bucketendpoint). - Note that when set to `true`, you specify the request endpoint in the `Bucket` request parameter, the original endpoint - will be overwritten. Whereas in v2, the request endpoint in client constructor overwrites the `Bucket` request parameter. -- [`s3DisableBodySigning`](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#s3DisableBodySigning-property) + - **v3**: Changed to `bucketEndpoint`. See more + in [v3 reference for bucketEndpoint](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/clients/client-s3/interfaces/s3clientconfig.html#bucketendpoint). + Note that when set to `true`, you specify the request endpoint in the `Bucket` request parameter, the original + endpoint + will be overwritten. Whereas in v2, the request endpoint in client constructor overwrites the `Bucket` request + parameter. +- [ + `s3DisableBodySigning`](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#s3DisableBodySigning-property) - **v2**: Whether to disable S3 body signing when using signature version v4. - **v3**: Renamed to `applyChecksum` - [`s3ForcePathStyle`](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#s3ForcePathStyle-property) @@ -161,7 +209,8 @@ This list is indexed by [v2 config parameters](https://docs.aws.amazon.com/AWSJa - [`s3UseArnRegion`](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#s3UseArnRegion-property) - **v2**: Whether to override the request region with the region inferred from requested resource's ARN. - **v3**: Renamed to `useArnRegion` -- [`s3UsEast1RegionalEndpoint`](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#s3UsEast1RegionalEndpoint-property) +- [ + `s3UsEast1RegionalEndpoint`](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#s3UsEast1RegionalEndpoint-property) - **v2**: When region is set to 'us-east-1', whether to send s3 request to global endpoints or 'us-east-1' regional endpoints. - **v3**: **Deprecated**. S3 client will always use regional endpoint if region is set to `us-east-1`. You can set the @@ -171,15 +220,18 @@ This list is indexed by [v2 config parameters](https://docs.aws.amazon.com/AWSJa - **v3**: **Deprecated**. SDK _always_ caches the hashed signing keys. - [`signatureVersion`](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#signatureVersion-property) - **v2**: The signature version to sign requests with (overriding the API configuration). - - **v3**: **Deprecated**. Signature V2 supported in v2 SDK has been deprecated by AWS. v3 _only_ supports signature v4. + - **v3**: **Deprecated**. Signature V2 supported in v2 SDK has been deprecated by AWS. v3 _only_ supports signature + v4. - [`sslEnabled`](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#sslEnabled-property) - **v2**: Whether SSL is enabled for requests. - **v3**: Renamed to `tls`. -- [`stsRegionalEndpoints`](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#stsRegionalEndpoints-property) +- [ + `stsRegionalEndpoints`](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#stsRegionalEndpoints-property) - **v2**: Whether to send sts request to global endpoints or regional endpoints. - **v3**: **Deprecated**. STS client will _always_ use regional endpoints if set to a specific region. You can set the region to `aws-global` to send request to STS global endpoint. -- [`useAccelerateEndpoint`](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#useAccelerateEndpoint-property) +- [ + `useAccelerateEndpoint`](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#useAccelerateEndpoint-property) - **v2**: Whether to use the Accelerate endpoint with the S3 service. - **v3**: No change. @@ -199,7 +251,8 @@ here: [ERROR_HANDLING](./supplemental-docs/ERROR_HANDLING.md). ## Credential Providers In v2, the SDK provides a list of credential providers to choose from, as well as a credentials provider chain, -available by default on Node.js, that tries to load the AWS credentials from all the most common providers. V3 simplifies +available by default on Node.js, that tries to load the AWS credentials from all the most common providers. V3 +simplifies the credential provider's interface, making it easier to use and write custom credential providers. On top of a new credentials provider chain, V3 all provides a list of credential providers aiming to provide equivalent to v2. @@ -209,7 +262,8 @@ Here is all the credential providers in v2 and their equivalents in v3. Default credential provider is how SDK resolve the AWS credential if you DO NOT provide one explicitly. -- **v2**: [CredentialProviderChain](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/CredentialProviderChain.html) +- **v2 + **: [CredentialProviderChain](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/CredentialProviderChain.html) in Node.js resolves credential from sources as following order: - [environmental variable](https://docs.aws.amazon.com/sdk-for-javascript/v2/developer-guide/loading-node-credentials-environment.html) @@ -224,24 +278,31 @@ Default credential provider is how SDK resolve the AWS credential if you DO NOT In Browsers and ReactNative, the chain is empty, meaning you always need supply credentials explicitly. -- **v3**: [defaultProvider](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/modules/_aws_sdk_credential_providers#fromnodejsproviderchain-1) - The credential sources and fallback order _does not_ change in v3. It also supports [AWS Single Sign-On credentials](https://aws.amazon.com/single-sign-on/). +- **v3 + **: [defaultProvider](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/modules/_aws_sdk_credential_providers#fromnodejsproviderchain-1) + The credential sources and fallback order _does not_ change in v3. It also + supports [AWS Single Sign-On credentials](https://aws.amazon.com/single-sign-on/). ### Temporary Credentials -- **v2**: [`ChainableTemporaryCredentials`](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/ChainableTemporaryCredentials.html) +- **v2**: [ + `ChainableTemporaryCredentials`](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/ChainableTemporaryCredentials.html) Represents temporary credentials retrieved from `AWS.STS`. Without any extra parameters, credentials will be - fetched from the `AWS.STS.getSessionToken()` operation. If an IAM role is provided, the `AWS.STS.assumeRole()` operation + fetched from the `AWS.STS.getSessionToken()` operation. If an IAM role is provided, the `AWS.STS.assumeRole()` + operation will be used to fetch credentials for the role instead. `AWS.ChainableTemporaryCredentials` differs from `AWS.TemporaryCredentials` in the way masterCredentials and refreshes are handled. `AWS.ChainableTemporaryCredentials` refreshes expired credentials using the masterCredentials passed by the user to support chaining of STS credentials. However, `AWS.TemporaryCredentials` recursively collapses the - masterCredentials during instantiation, precluding the ability to refresh credentials which require intermediate, temporary credentials. + masterCredentials during instantiation, precluding the ability to refresh credentials which require intermediate, + temporary credentials. - The original [`TemporaryCredentials`](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/TemporaryCredentials.html) + The original [ + `TemporaryCredentials`](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/TemporaryCredentials.html) has been **deprecated** in favor of `ChainableTemporaryCredentials` in v2. -- **v3**: [`Temporary Credentials Provider`](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/modules/_aws_sdk_credential_providers.html). +- **v3**: [ + `Temporary Credentials Provider`](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/modules/_aws_sdk_credential_providers.html). You can call `fromTemporaryCredentials()` from `@aws-sdk/credential-providers` package. Here's an example: ```javascript @@ -265,19 +326,25 @@ Default credential provider is how SDK resolve the AWS credential if you DO NOT Load credentials from Cognito Identity service, normally used in browsers. -- **v2**: [`CognitoIdentityCredentials`](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/CognitoIdentityCredentials.html) +- **v2**: [ + `CognitoIdentityCredentials`](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/CognitoIdentityCredentials.html) Represents credentials retrieved from STS Web Identity Federation using the Amazon Cognito Identity service. -- **v3**: [`Cognito Identity Credential Provider`](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/modules/_aws_sdk_credential_providers.html) +- **v3**: [ + `Cognito Identity Credential Provider`](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/modules/_aws_sdk_credential_providers.html) The [`@aws/credential-providers` package](https://www.npmjs.com/package/@aws-sdk/credential-providers) - provides two credential provider functions, one of which [`fromCognitoIdentity`](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/modules/_aws_sdk_credential_providers.html) + provides two credential provider functions, one of which [ + `fromCognitoIdentity`](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/modules/_aws_sdk_credential_providers.html) takes an identity ID and calls `cognitoIdentity:GetCredentialsForIdentity`, while the other - [`fromCognitoIdentityPool`](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/modules/_aws_sdk_credential_providers.html) + [ + `fromCognitoIdentityPool`](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/modules/_aws_sdk_credential_providers.html) takes an identity pool ID, calls `cognitoIdentity:GetId` on the first invocation, and then calls`fromCognitoIdentity`. Subsequent invocations of the latter do not re-invoke GetId - The provider implements the "Simplified Flow" described in the [Cognito developer guide](https://docs.aws.amazon.com/cognito/latest/developerguide/authentication-flow.html). + The provider implements the "Simplified Flow" described in + the [Cognito developer guide](https://docs.aws.amazon.com/cognito/latest/developerguide/authentication-flow.html). The "Classic Flow" which involves calling `cognito:GetOpenIdToken` and then calling `sts:AssumeRoleWithWebIdentity` is - NOT supported. Please open a [feature request](https://github.com/aws/aws-sdk-js-v3/issues/new?assignees=&labels=feature-request&template=---feature-request.md&title=) + NOT supported. Please open + a [feature request](https://github.com/aws/aws-sdk-js-v3/issues/new?assignees=&labels=feature-request&template=---feature-request.md&title=) to us if you need it. ```javascript @@ -326,8 +393,10 @@ Load credentials from Cognito Identity service, normally used in browsers. Represents credentials received from the metadata service on an EC2 instance. -- **v2**: [`EC2MetadataCredentials`](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/CognitoIdentityCredentials.html) -- **v3**: [`fromInstanceMetadata`](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/modules/_aws_sdk_credential_providers.html): +- **v2**: [ + `EC2MetadataCredentials`](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/CognitoIdentityCredentials.html) +- **v3**: [ + `fromInstanceMetadata`](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/modules/_aws_sdk_credential_providers.html): Creates a credential provider that will source credentials from the EC2 Instance Metadata Service. ```javascript @@ -348,8 +417,10 @@ Represents credentials received from specified URL. This provider will request t URI specified by the `AWS_CONTAINER_CREDENTIALS_RELATIVE_URI` or the `AWS_CONTAINER_CREDENTIALS_FULL_URI` environment variable. -- **v2**: `ECSCredentials` or [`RemoteCredentials`](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/RemoteCredentials.html). -- **v3**: [`fromContainerMetadata`](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/modules/_aws_sdk_credential_providers.html) +- **v2**: `ECSCredentials` or [ + `RemoteCredentials`](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/RemoteCredentials.html). +- **v3**: [ + `fromContainerMetadata`](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/modules/_aws_sdk_credential_providers.html) creates a credential provider that will source credentials from the ECS Container Metadata Service. ```javascript @@ -375,18 +446,22 @@ variable. - **v2**: [`SAMLCredentials`](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/SAMLCredentials.html) represents credentials retrieved from STS SAML support. -- **v3**: **Not available**. Please open a [feature request](https://github.com/aws/aws-sdk-js-v3/issues/new?assignees=&labels=feature-request&template=---feature-request.md&title=) +- **v3**: **Not available**. Please open + a [feature request](https://github.com/aws/aws-sdk-js-v3/issues/new?assignees=&labels=feature-request&template=---feature-request.md&title=) to us if you need it. ### Shared Credential File Credentials Loads credentials from shared credentials file (defaulting to `~/.aws/credentials` or defined by the `AWS_SHARED_CREDENTIALS_FILE` environment variable). This file is supported across different AWS SDKs and tools. You can -refer to the [shared config and credentials files document](https://docs.aws.amazon.com/sdkref/latest/guide/creds-config-files.html) +refer to +the [shared config and credentials files document](https://docs.aws.amazon.com/sdkref/latest/guide/creds-config-files.html) for more information. -- **v2**: [`SharedIniFileCredentials`](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/SharedIniFileCredentials.html) -- **v3**: [`fromIni`](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/modules/_aws_sdk_credential_providers.html). +- **v2**: [ + `SharedIniFileCredentials`](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/SharedIniFileCredentials.html) +- **v3**: [ + `fromIni`](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/modules/_aws_sdk_credential_providers.html). ```javascript import { fromIni } from "@aws-sdk/credential-providers"; @@ -410,8 +485,10 @@ for more information. Retrieves credentials using OIDC token from a file on disk. It's commonly used in EKS. -- **v2**: [`TokenFileWebIdentityCredentials`](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/TokenFileWebIdentityCredentials.html). -- **v3**: [`fromTokenFile`](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-credential-providers/#fromtokenfile) +- **v2**: [ + `TokenFileWebIdentityCredentials`](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/TokenFileWebIdentityCredentials.html). +- **v3**: [ + `fromTokenFile`](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-credential-providers/#fromtokenfile) ```javascript import { fromTokenFile } from "@aws-sdk/credential-providers"; // ES6 import @@ -433,8 +510,10 @@ Retrieves credentials using OIDC token from a file on disk. It's commonly used i Retrieves credentials from STS web identity federation support. -- **v2**: [`WebIdentityCredentials`](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/WebIdentityCredentials.html) -- **v3**: [`fromWebToken`](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/modules/_aws_sdk_credential_provider_web_identity.html#fromwebtoken-1) +- **v2**: [ + `WebIdentityCredentials`](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/WebIdentityCredentials.html) +- **v3**: [ + `fromWebToken`](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/modules/_aws_sdk_credential_provider_web_identity.html#fromwebtoken-1) ```javascript import { fromWebToken } from "@aws-sdk/credential-providers"; // ES6 import @@ -454,35 +533,50 @@ Retrieves credentials from STS web identity federation support. ## S3 Multipart Upload -In v2, the S3 client has the `ManagedUpload` class that contains an [`upload()`](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/S3.html#upload-property) -operation that supports uploading large objects with [multipart upload feature offered by S3](https://docs.aws.amazon.com/AmazonS3/latest/userguide/mpuoverview.html). +In v2, the S3 client has the `ManagedUpload` class that contains an [ +`upload()`](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/S3.html#upload-property) +operation that supports uploading large objects +with [multipart upload feature offered by S3](https://docs.aws.amazon.com/AmazonS3/latest/userguide/mpuoverview.html). In v3, [`@aws-sdk/lib-storage` package](https://github.com/aws/aws-sdk-js-v3/blob/main/lib/lib-storage) is available. It supports all the features offered in v2 `upload()`, and supports both Node.js and browsers runtime. ## S3 Presigned URL -In v2, the S3 client contains [`getSignedUrl()`](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/S3.html#getSignedUrl-property) -and [`getSignedUrlPromise()`](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/S3.html#getSignedUrlPromise-property) +In v2, the S3 client contains [ +`getSignedUrl()`](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/S3.html#getSignedUrl-property) +and [ +`getSignedUrlPromise()`](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/S3.html#getSignedUrlPromise-property) operations to generate an URL that users can use to upload or download objects from S3. -In v3, [`@aws-sdk/s3-request-presigner` package](https://github.com/aws/aws-sdk-js-v3/tree/main/packages/s3-request-presigner) -is available. You don't have to differentiate `getSignedUrl()` and `getSignedUrlPromise()` any more. We also have [a blog](https://aws.amazon.com/blogs/developer/generate-presigned-url-modular-aws-sdk-javascript/) +In v3, [ +`@aws-sdk/s3-request-presigner` package](https://github.com/aws/aws-sdk-js-v3/tree/main/packages/s3-request-presigner) +is available. You don't have to differentiate `getSignedUrl()` and `getSignedUrlPromise()` any more. We also +have [a blog](https://aws.amazon.com/blogs/developer/generate-presigned-url-modular-aws-sdk-javascript/) discussing the details of this package. ## S3 Global Client (Region Redirects) -S3 client in v3 supports S3 global client, or following region redirects, if an incorrect region is passed and a subsequent `PermanentRedirect` (status 301) error is thrown. You can use the [`followRegionRedirects`](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-middleware-sdk-s3/Interface/S3InputConfig/) flag in the client config to make the S3 client follow region redirects and support its function as a global client. Note that this can result in additional latency as failed requests are retried with a corrected region when receiving a `PermanentRedirect` error with status 301. This feature should only be used as a last resort if you do not know the region of your bucket(s) ahead of time. +S3 client in v3 supports S3 global client, or following region redirects, if an incorrect region is passed and a +subsequent `PermanentRedirect` (status 301) error is thrown. You can use the [ +`followRegionRedirects`](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-middleware-sdk-s3/Interface/S3InputConfig/) +flag in the client config to make the S3 client follow region redirects and support its function as a global client. +Note that this can result in additional latency as failed requests are retried with a corrected region when receiving a +`PermanentRedirect` error with status 301. This feature should only be used as a last resort if you do not know the +region of your bucket(s) ahead of time. ## DynamoDB Document Client ### Basic Usage of DynamoDB Document Client in v3 -- In v2, you can use the [`AWS.DynamoDB.DocumentClient` class](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/DynamoDB/DocumentClient.html) - to call DynamoDB API with native JavaScript types like Array, Number, and Object. It thus simplifies working with items +- In v2, you can use the [ + `AWS.DynamoDB.DocumentClient` class](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/DynamoDB/DocumentClient.html) + to call DynamoDB API with native JavaScript types like Array, Number, and Object. It thus simplifies working with + items in Amazon DynamoDB by abstracting away the notion of attribute values. -- In v3, the equivalent [`@aws-sdk/lib-dynamodb`](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/modules/_aws_sdk_lib_dynamodb.html) +- In v3, the equivalent [ + `@aws-sdk/lib-dynamodb`](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/modules/_aws_sdk_lib_dynamodb.html) is available. It's similar to normal service clients from v3 SDK, with the difference that it takes a basic DynamoDB client in its constructor. @@ -515,7 +609,9 @@ await ddbDocClient.send( - In v2, `undefined` values in objects were automatically omitted during the marshalling process to DynamoDB. -- In v3, the default marshalling behavior in @aws-sdk/lib-dynamodb has changed: objects with `undefined` values are no longer omitted. To align with v2's functionality, developers must explicitly set the `removeUndefinedValues` to `true` in the `marshallOptions` of the DynamoDBDocumentClient. +- In v3, the default marshalling behavior in @aws-sdk/lib-dynamodb has changed: objects with `undefined` values are no + longer omitted. To align with v2's functionality, developers must explicitly set the `removeUndefinedValues` to `true` + in the `marshallOptions` of the DynamoDBDocumentClient. Example: @@ -545,12 +641,14 @@ await ddbDocClient.send( ); ``` -More examples and configurations are available in the [package README](https://github.com/aws/aws-sdk-js-v3/blob/main/lib/lib-dynamodb/README.md). +More examples and configurations are available in +the [package README](https://github.com/aws/aws-sdk-js-v3/blob/main/lib/lib-dynamodb/README.md). ## Waiters In v2, all waiters are bound to the service client class, you need to specify in waiter's input which designed state the -client will be waiting for. For example, you need to [call `waitFor("bucketExists")`](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/S3.html#bucketExists-waiter) +client will be waiting for. For example, you need to [call +`waitFor("bucketExists")`](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/S3.html#bucketExists-waiter) to wait for a newly created bucket to be ready. In v3, you don't need to import waiters if your application doesn't need one. Moreover, you can import only the waiter @@ -569,34 +667,44 @@ await client.send(command); await waitUntilBucketExists({ client, maxWaitTime: 60 }, { Bucket }); ``` -You can find everything of how to configure the waiters in the [blog post of waiters in v3 SDK](https://aws.amazon.com/blogs/developer/waiters-in-modular-aws-sdk-for-javascript/). +You can find everything of how to configure the waiters in +the [blog post of waiters in v3 SDK](https://aws.amazon.com/blogs/developer/waiters-in-modular-aws-sdk-for-javascript/). ## CloudFront Signer -In v2, you can sign the request to access restricted CloudFront distributions with [`AWS.CloudFront.Signer`](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/CloudFront/Signer.html). +In v2, you can sign the request to access restricted CloudFront distributions with [ +`AWS.CloudFront.Signer`](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/CloudFront/Signer.html). -In v3, you have the same utilities provided in the [`@aws-sdk/cloudfront-signer`](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/modules/_aws_sdk_cloudfront_signer.html) package. +In v3, you have the same utilities provided in the [ +`@aws-sdk/cloudfront-signer`](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/modules/_aws_sdk_cloudfront_signer.html) +package. ## RDS Signer -In v2, you can generate the auth token to an RDS database using [`AWS.RDS.Signer`](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/RDS/Signer.html). +In v2, you can generate the auth token to an RDS database using [ +`AWS.RDS.Signer`](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/RDS/Signer.html). -In v3, the similar utility class is available in [`@aws-sdk/rds-signer` package](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/modules/_aws_sdk_rds_signer.html). +In v3, the similar utility class is available in [ +`@aws-sdk/rds-signer` package](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/modules/_aws_sdk_rds_signer.html). ## Polly Signer -In v2, you can generate a signed URL to the speech synthesized by AWS Polly service with [`AWS.Polly.Presigner` class](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Polly/Presigner.html). +In v2, you can generate a signed URL to the speech synthesized by AWS Polly service with [ +`AWS.Polly.Presigner` class](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Polly/Presigner.html). -In v3, the similar utility function is available in [`@aws-sdk/polly-request-presigner` package](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/modules/_aws_sdk_polly_request_presigner.html) +In v3, the similar utility function is available in [ +`@aws-sdk/polly-request-presigner` package](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/modules/_aws_sdk_polly_request_presigner.html) ## Notes on Specific Service Clients ### Amazon S3 -Streaming vs. buffered responses: the JSv3 SDK prefers not to buffer potentially large responses. This is commonly encountered in S3's GetObject operation, which returned a `Buffer` in JSv2, but +Streaming vs. buffered responses: the JSv3 SDK prefers not to buffer potentially large responses. This is commonly +encountered in S3's GetObject operation, which returned a `Buffer` in JSv2, but returns a `Stream` in JSv3. -For Node.js, you must consume the stream or garbage collect the client or its request handler to keep the connections open to new traffic by freeing sockets. +For Node.js, you must consume the stream or garbage collect the client or its request handler to keep the connections +open to new traffic by freeing sockets. ```ts // v2 @@ -612,7 +720,8 @@ const str = await get.Body.transformToString(); // consumes the stream. // a string or byte array. ``` -Please see also the section on **socket exhaustion** here: https://github.com/aws/aws-sdk-js-v3/blob/main/supplemental-docs/CLIENTS.md#request-handler-requesthandler +Please see also the section on **socket exhaustion** +here: https://github.com/aws/aws-sdk-js-v3/blob/main/supplemental-docs/CLIENTS.md#request-handler-requesthandler ### AWS Lambda @@ -682,7 +791,8 @@ it was possible to supply a custom `QueueUrl` which would override the SQS Clien #### Mutli-region messages -You should use one client per region in v3. The AWS Region is meant to be initialized at the client level and not changed between requests. +You should use one client per region in v3. The AWS Region is meant to be initialized at the client level and not +changed between requests. ```ts import { SQS } from "@aws-sdk/client-sqs";