Best Practices for Handling Input Streams of responseBody in a Custom Client Using SdkHttpClient (#4624)

Author: joviegas

docs/BestPractices.md

@@ -21,6 +21,13 @@ This is because the input stream is a direct stream of data from the HTTP connec
 reused until all data from the stream has been read and the stream is closed. If these rules are not followed, the client can 
 run out of resources by allocating too many open, but unused, HTTP connections.
 
+### Close input streams of responseBody() from Custom Client based on SdkHttpClient
+While implementing custom clients from  `SdkHttpClient` interface
+- Close the [responseBody](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/HttpExecuteResponse.html#responseBody()) Input Stream: Always close the "responseBody" input stream to release the HTTP Connection, even when handling error responses.
+- SDK Requirement: The SDK requires the closing of the input stream to manage HTTP connections effectively.
+- Handling Error Responses: Even in the case of error responses, the SDK client creates an input stream for reading error data.
+- Consistent Practice: Ensure that consumers close the input stream in the "responseBody" attribute for both success and error cases.
+
 ### Tune HTTP configurations based on performance tests
 
 The SDK provides a set of [default http configurations] that apply to general use cases. Customers are recommended to tune the configurations for their applications based on their use cases.

http-client-spi/src/main/java/software/amazon/awssdk/http/HttpExecuteResponse.java

@@ -38,7 +38,13 @@ public SdkHttpResponse httpResponse() {
     }
 
     /**
-     * @return The {@link ContentStreamProvider}.
+     * /** Get the {@link AbortableInputStream} associated with this response.
+     *
+     * <p>Always close the "responseBody" input stream to release the underlying HTTP connection.
+     * Even for error responses, the SDK creates an input stream for reading error data. It is essential to close the input stream
+     * in the "responseBody" attribute for both success and error cases.
+     *
+     * @return An {@link Optional} containing the {@link AbortableInputStream} if available.
      */
     public Optional<AbortableInputStream> responseBody() {
         return responseBody;