Request Body Handler

The request body handler is used by all API calls that have a HTTP request body. This includes the query APIs requests that use POST with application/x-www-form-urlencoded and the s3.put() requests.

While for the query APIs this handler is not exposed as it handles stuff automatically, the s3.put() low level method requires this functionality. The reason is the number of choices.

In order to enable specific behaviors of the request body handling, you need to pass as argument one of the following:

• the false handler - passing a value that evaluates to the boolean false as handler turns off the request body. Requests without bodies such as GET, HEAD, and DELETE automatically use this handler. For the PUT requests, you may use this handler when creating a new bucket into the default us-east-1 region without writing more data to the socket.
• the String handler - basically the provided string is used as the request body itself. Internally it is used by the query APIs to send their query parameters as part of the POST body. The PUT method of the S3 API makes the content of this string to be the file content if you put an object. The library handles the string as 'utf8' which is the default node.js encoding for HTTP's request.write(chunk) when typeof chunk === 'string'. If the String contains the Unicode escape sequences, the surrogate pairs may be tricky. Refer to this article for more information. In order to handle a different String encoding, use the Buffer handler. Always use the Buffer handler with binary data.
• the Buffer handler - passing a Buffer instance as the handler turns on this behavior. The contents of the buffer are going to be the contents of the S3 object. The s3.putBuffer() helper wraps this handler for more usability.
• the Stream handler - passing a Readable Stream instance as the handler turns on this behavior. The contents of the readable stream are going to be the contents of the S3 object. The s3.putStream() helper wraps this handler for more usability. However, you should be very careful about the S3 limitations regarding the lack of chunked transfer. The s3.putStream() page has all the required information about this issue. In order to have reliable operation (eg: not missing any data events), the stream must be passed in a paused state aka calling the Stream.pause() method for the Readable Stream instance. The library resumes the stream before piping it to the HTTP request Writable Stream.
• the file handler - if none of the above handlers matches, you need to invoke the PUT method with the following object as body handler: {file: '/path/to/file.ext'}. The s3.putFile() helper wraps this handler for more usability. Check the s3.putFile() page for more information regarding how this handler works. You may also pass options directly to the underlying fs.ReadStream. The byte range is inclusive for both passed values. For example, you may send just a byte range like this: {file: '/path/to/file.ext', options: {start: 0, end: 99}}. In this example, the request sends just the first 100 bytes of the input file. Usually you don't need this feature. The S3 Multipart Upload API uses it for the file parts splitting.

If the library fails to identify the file handler, which is the default if the others aren't used, then an error is thrown.