Skip to content

Commit 62b584f

Browse files
committed
docs: add instructions for identifying byte stream response fields
1 parent 8db3b98 commit 62b584f

File tree

1 file changed

+21
-3
lines changed

1 file changed

+21
-3
lines changed

supplemental-docs/EFFECTIVE_PRACTICES.md

Lines changed: 21 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -197,7 +197,8 @@ console.log(getObjectResponse.$metadata.httpStatusCode);
197197
// ⚠️ byte stream is unhandled, leaving a socket in use.
198198
```
199199

200-
Although the API call is performed and you have access to response, the connection will remain open until the byte stream, or payload, is read or discarded.
200+
Although the API call is performed, and you have access to response, the connection will remain open until the byte
201+
stream, or payload, is read or discarded.
201202
Not doing so will leave the connection open, and in Node.js this can lead to a condition we call socket exhaustion. In
202203
the worst cases this can cause your application to slow, leak memory, and/or deadlock.
203204

@@ -231,6 +232,21 @@ if (case1) {
231232
}
232233
```
233234

235+
To identify _which_ operations contain byte stream response payloads, refer to our API documentation. In the
236+
"Example Syntax" section of each operation's API reference page, the field that constitutes a byte stream will be marked
237+
as such:
238+
239+
```ts
240+
// { // GetObjectOutput
241+
// Body: "<SdkStream>", // see \@smithy/types -> StreamingBlobPayloadOutputTypes
242+
// ... other fields ...
243+
// };
244+
```
245+
246+
in the same way
247+
as [GetObjectCommand](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/client/s3/command/GetObjectCommand/).
248+
The byte stream field will always be a top-level property of the response object.
249+
234250
### (4) Allow more time to establish connections when making requests cross-region
235251

236252
This is outside the AWS SDK interfaces but an important consideration when making cross-region requests in AWS when
@@ -246,7 +262,8 @@ The default value of 250ms may be too low for some cross-region pairs within AWS
246262
opposite sides of the world, or simply in conditions of low network speed. This may manifest as an `AggregateError` with
247263
code `ETIMEDOUT` in Node.js.
248264

249-
To increase this value within your application, use a `node` launch parameter such as `--network-family-autoselection-attempt-timeout=500` or
265+
To increase this value within your application, use a `node` launch parameter such as
266+
`--network-family-autoselection-attempt-timeout=500` or
250267
the `node:net` API:
251268

252269
```ts
@@ -255,4 +272,5 @@ import net from "node:net";
255272
net.setDefaultAutoSelectFamilyAttemptTimeout(500);
256273
```
257274

258-
The content of this item is based on the author's reading of this reported issue: https://github.com/nodejs/node/issues/54359.
275+
The content of this item is based on the author's reading of this reported
276+
issue: https://github.com/nodejs/node/issues/54359.

0 commit comments

Comments
 (0)