transloadit: expand on resume: false reasons

packages/@uppy/transloadit/src/index.js

@@ -704,7 +704,14 @@ module.exports = class Transloadit extends Plugin {
     } else {
       this.uppy.use(Tus, {
         // Disable tus-js-client fingerprinting, otherwise uploading the same file at different times
-        // will upload to the same Assembly.
+        // will upload to an outdated Assembly, and we won't get socket events for it.
+        //
+        // To resume a Transloadit upload, we need to reconnect to the websocket, and the state that's
+        // required to do that is not saved by tus-js-client's fingerprinting. We need the tus URL,
+        // the Assembly URL, and the WebSocket URL, at least. We also need to know _all_ the files that
+        // were added to the Assembly, so we can properly complete it. All that state is handled by
+        // Golden Retriever. So, Golden Retriever is required to do resumability with the Transloadit plugin,
+        // and we disable Tus's default resume implementation to prevent bad behaviours.
         resume: false,
         // Disable Companion's retry optimisation; we need to change the endpoint on retry
         // so it can't just reuse the same tus.Upload instance server-side.

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

@@ -83,7 +83,7 @@ A function that generates a signed URL to upload a single part. Receives the `fi
 
 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:
+ - `url` - The presigned URL to upload a part. This can be generated on the server using the S3 SDK like so:
 
    ```js
    sdkInstance.getSignedUrl('uploadPart', {
@@ -133,7 +133,7 @@ While the Uppy AWS S3 plugin uses `POST` requests while uploading files to an S3
 <CORSRule>
   <!-- Change from POST to PUT if you followed the docs for the AWS S3 plugin ... -->
   <AllowedMethod>PUT</AllowedMethod>
-  
+
   <!-- ... keep the existing MaxAgeSeconds and AllowedHeader lines and your other stuff ... -->
 
   <!-- ... and don't forget to add this tag. -->