Add docs for AwsS3Multipart.

website/src/docs/aws-s3-multipart.md

@@ -0,0 +1,101 @@
+---
+type: docs
+order: 33
+title: "AwsS3Multipart"
+permalink: docs/aws-s3-multipart/
+---
+
+The `AwsS3Multipart` plugin can be used to upload files directly to an S3 bucket using S3's Multipart upload strategy. With this strategy, files are chopped up in parts of 5MB+ each, so they can be uploaded concurrently. It's also very reliable: if a single part fails to upload, only that 5MB has to be retried.
+
+```js
+const AwsS3Multipart = require('uppy/lib/plugins/AwsS3/Multipart')
+uppy.use(AwsS3Multipart, {
+  limit: 4,
+  host: 'https://uppy-server.myapp.net/'
+})
+```
+
+## Options
+
+### limit: 0
+
+The maximum amount of chunks to upload simultaneously. `0` means unlimited.
+
+### host: null
+
+The Uppy Server URL to use to proxy calls to the S3 Multipart API.
+
+### createMultipartUpload(file)
+
+A function that calls the S3 Multipart API to create a new upload. `file` is the file object from Uppy's state. The most relevant keys are `file.name` and `file.type`.
+
+Return a Promise for an object with keys:
+
+ - `uploadId` - The UploadID returned by S3.
+ - `key` - The object key for the file. This needs to be returned to allow it to be different from the `file.name`.
+
+The default implementation calls out to Uppy Server's S3 signing endpoints.
+
+### listParts({ uploadId, key })
+
+A function that calls the S3 Multipart API to list the parts of a file that have already been uploaded. Receives an object with keys:
+
+ - `uploadId` - The UploadID of this Multipart upload.
+ - `key` - The object key of this Multipart upload.
+
+Return a Promise for an array of S3 Part objects, as returned by the S3 Multipart API. Each object has keys:
+
+ - `PartNumber` - The index in the file of the uploaded part.
+ - `Size` - The size of the part in bytes.
+ - `ETag` - The ETag of the part, used to identify it when completing the multipart upload and combining all parts into a single file.
+
+The default implementation calls out to Uppy Server's S3 signing endpoints.
+
+### prepareUploadPart(partData)
+
+A function that generates a signed URL to upload a single part. The `partData` argument is an object with keys:
+
+ - `uploadId` - The UploadID of this Multipart upload.
+ - `key` - The object key in the S3 bucket.
+ - `body` - A [`Blob`](https://developer.mozilla.org/en-US/docs/Web/API/Blob) of this part's contents.
+ - `number` - The index of this part in the file (`PartNumber` in S3 terminology).
+
+Return a Promise for an object with keys:
+
+ - `url` - The presigned URL to upload a part. This can be generated using the S3 SDK like so:
+
+   ```js
+   sdkInstance.getSignedUrl('uploadPart', {
+     Bucket: 'target',
+     Key: partData.key,
+     UploadId: partData.uploadId,
+     PartNumber: partData.number,
+     Body: '', // Empty, because it's uploaded later
+     Expires: Date.now() + 5 * 60 * 1000
+   }, (err, url) => { /* there's the url! */ })
+   ```
+
+### abortMultipartUpload({ uploadId, key })
+
+A function that calls the S3 Multipart API to abort a Multipart upload, and delete all parts that have been uploaded so far. Receives an object with keys:
+
+ - `uploadId` - The UploadID of this Multipart upload.
+ - `key` - The object key of this Multipart upload.
+
+This is typically called when the user cancels an upload. Cancellation cannot fail in Uppy, so the result of this function is ignored.
+
+The default implementation calls out to Uppy Server's S3 signing endpoints.
+
+### completeMultipartUpload({ uploadId, key, parts })
+
+A function that calls the S3 Multipart API to complete a Multipart upload, combining all parts into a single object in the S3 bucket. Receives an object with keys:
+
+ - `uploadId` - The UploadID of this Multipart upload.
+ - `key` - The object key of this Multipart upload.
+ - `parts` - S3-style list of parts, an array of objects with `ETag` and `PartNumber` properties. This can be passed straight to S3's Multipart API.
+
+Return a Promise for an object with properties:
+
+ - `location` - **(Optional)** A publically accessible URL to the object in the S3 bucket.
+
+The default implementation calls out to Uppy Server's S3 signing endpoints.

website/src/docs/aws-s3.md

@@ -9,6 +9,8 @@ The `AwsS3` plugin can be used to upload files directly to an S3 bucket.
 Uploads can be signed using [uppy-server][uppy-server docs] or a custom signing function.
 
 ```js
+const AwsS3 = require('uppy/lib/plugins/AwsS3')
+
 uppy.use(AwsS3, {
   // Options
 })
@@ -16,6 +18,8 @@ uppy.use(AwsS3, {
 
 There are broadly two ways to upload to S3 in a browser. A server can generate a presigned URL for a [PUT upload](https://docs.aws.amazon.com/AmazonS3/latest/API/RESTObjectPUT.html), or a server can generate form data for a [POST upload](https://docs.aws.amazon.com/AmazonS3/latest/API/RESTObjectPOST.html). uppy-server uses a POST upload. See [POST uPloads](#post-uploads) for some caveats if you would like to use POST uploads without uppy-server. See [Generating a presigned upload URL server-side](#example-presigned-url) for an example of a PUT upload.
 
+There is also a separate plugin for S3 Multipart uploads. Multipart in this sense is Amazon's proprietary chunked, resumable upload mechanism for large files. See the [AwsS3Multipart](/docs/aws-s3-multipart) documentation.
+
 ## Options
 
 ### `host`

website/src/docs/transloadit.md

@@ -1,6 +1,6 @@
 ---
 type: docs
-order: 33
+order: 34
 title: "Transloadit"
 permalink: docs/transloadit/
 ---