@uppy/aws-s3: add endpoint option

docs/uploader/aws-s3-multipart.mdx

@@ -41,8 +41,8 @@ milliseconds on uploading.
 
 **In short**
 
-- We recommend the default value of [`shouldUseMultipart`][], which enable multipart uploads only
-  for large files.
+- We recommend the default value of [`shouldUseMultipart`][], which enable
+  multipart uploads only for large files.
 - If you prefer to have less overhead (+20% upload speed) you can use temporary
   S3 credentials with [`getTemporarySecurityCredentials`][]. This means users
   get a single token which allows them to do bucket operations for longer,
@@ -166,7 +166,7 @@ import '@uppy/dashboard/dist/style.min.css';
 const uppy = new Uppy()
 	.use(Dashboard, { inline: true, target: 'body' })
 	.use(AwsS3, {
-		companionUrl: 'https://companion.uppy.io',
+		endpoint: 'https://companion.uppy.io',
 	});
 ```
 
@@ -179,8 +179,8 @@ const uppy = new Uppy()
 A boolean, or a function that returns a boolean which is called for each file
 that is uploaded with the corresponding `UppyFile` instance as argument.
 
-By default, all files with a `file.size` ≤ 100 MiB will be uploaded in a single chunk, all files
-larger than that as multipart.
+By default, all files with a `file.size` ≤ 100 MiB will be uploaded in a
+single chunk, all files larger than that as multipart.
 
 Here’s how to use it:
 
@@ -215,9 +215,10 @@ uploaded.
 
 :::
 
-#### `companionUrl`
+#### `endpoint`
 
-URL to a [Companion](/docs/companion) instance (`string`, default: `null`).
+URL to a [Companion](/docs/companion) or Companion-like instance (`string`,
+default: `null`).
 
 #### `companionHeaders`
 
@@ -245,10 +246,10 @@ disable automatic retries, and fail instantly if any chunk fails to upload.
 A function that returns the minimum chunk size to use when uploading the given
 file as multipart.
 
-For multipart uploads, chunks are sent in batches to
-have presigned URLs generated with [`signPart()`](#signpartfile-partdata). To
-reduce the amount of requests for large files, you can choose a larger chunk
-size, at the cost of having to re-upload more data if one chunk fails to upload.
+For multipart uploads, chunks are sent in batches to have presigned URLs
+generated with [`signPart()`](#signpartfile-partdata). To reduce the amount of
+requests for large files, you can choose a larger chunk size, at the cost of
+having to re-upload more data if one chunk fails to upload.
 
 S3 requires a minimum chunk size of 5MiB, and supports at most 10,000 chunks per
 multipart upload. If `getChunkSize()` returns a size that’s too small, Uppy will
@@ -432,7 +433,7 @@ upload sources), you can pass a boolean:
 ```js
 uppy.use(AwsS3, {
 	// This is an example using Companion:
-	companionUrl: 'http://companion.uppy.io',
+	endpoint: 'http://companion.uppy.io',
 	getTemporarySecurityCredentials: true,
 	shouldUseMultipart: (file) => file.size > 100 * 2 ** 20,
 });
@@ -454,6 +455,12 @@ uppy.use(AwsS3, {
 });
 ```
 
+#### `companionUrl`
+
+Alias for [`endpoint`](#endpoint).
+
+</details>
+
 [`gettemporarysecuritycredentials`]: #gettemporarysecuritycredentialsoptions
 [`shouldusemultipart`]: #shouldusemultipartfile
 [companion docs]: /docs/companion

packages/@uppy/aws-s3/src/index.test.ts

@@ -29,7 +29,7 @@ describe('AwsS3Multipart', () => {
       core.use(AwsS3Multipart)
       const awsS3Multipart = core.getPlugin('AwsS3Multipart')!
 
-      const err = 'Expected a `companionUrl` option'
+      const err = 'Expected a `endpoint` option'
       const file = {}
       const opts = {}
 
@@ -337,6 +337,7 @@ describe('AwsS3Multipart', () => {
 
     it('companionHeader is updated before uploading file', async () => {
       awsS3Multipart.setOptions({
+        endpoint: 'http://localhost',
         companionHeaders: {
           authorization: newToken,
         },
@@ -368,6 +369,7 @@ describe('AwsS3Multipart', () => {
           Body
         >
         awsS3Multipart.setOptions({
+          endpoint: 'http://localhost',
           companionHeaders: {
             authorization: newToken,
           },

packages/@uppy/aws-s3/src/index.ts

@@ -142,8 +142,15 @@
   ETag?: string
 }
 
-type AWSS3WithCompanion = {
-  companionUrl: string
+type AWSS3WithCompanion = (
+  | {
+      /** @deprecated use `endpoint` instead */
+      companionUrl: string
+    }
+  | {
+      endpoint: string
+    }
+) & {
   companionHeaders?: Record<string, string>
   companionCookiesRule?: string
   getTemporarySecurityCredentials?: true
@@ -337,8 +344,7 @@
     // We need the `as any` here because of the dynamic default options.
     this.type = 'uploader'
     this.id = this.opts.id || 'AwsS3Multipart'
-    // TODO: only initiate `RequestClient` is `companionUrl` is defined.
-    this.#client = new RequestClient(uppy, opts as any)
+    this.#setClient(opts)
 
     const dynamicDefaultOptions = {
       createMultipartUpload: this.createMultipartUpload,
@@ -388,9 +394,36 @@
     return this.#client
   }
 
+  #setClient(opts?: Partial<AwsS3MultipartOptions<M, B>>) {
+    if (
+      opts == null ||
+      !(
+        'endpoint' in opts ||
+        'companionUrl' in opts ||
+        'companionHeaders' in opts ||
+        'companionCookiesRule' in opts ||
+        'companionKeysParams' in opts
+      )
+    )
+      return
+    if (opts.endpoint) {
+      // eslint-disable-next-line no-param-reassign
+      opts = { ...this.opts, companionUrl: opts.endpoint }
+    } else if (opts.companionUrl) {
+      this.uppy.log(
+        '`companionUrl` option is deprecated in @uppy/aws-s3, use `endpoint` instead.',
+        'warning',
+      )
+      // eslint-disable-next-line no-param-reassign
+      opts = this.opts
+    }
+    this.#client = new RequestClient(this.uppy, opts as any)
+  }
+
   setOptions(newOptions: Partial<AwsS3MultipartOptions<M, B>>): void {
     this.#companionCommunicationQueue.setOptions(newOptions)
     super.setOptions(newOptions)
+    this.#setClient(newOptions)
     this.#setCompanionHeaders()
   }
 
@@ -418,11 +451,10 @@
     }
   }
 
-  // TODO: make this a private method in the next major
-  assertHost(method: string): void {
-    if (!this.opts.companionUrl) {
+  #assertHost(method: string): void {
+    if (!this.#client) {
       throw new Error(
-        `Expected a \`companionUrl\` option containing a Companion address, or if you are not using Companion, a custom \`${method}\` implementation.`,
+        `Expected a \`endpoint\` option containing a URL, or if you are not using Companion, a custom \`${method}\` implementation.`,
       )
     }
   }
@@ -431,7 +463,7 @@
     file: UppyFile<M, B>,
     signal?: AbortSignal,
   ): Promise<UploadResult> {
-    this.assertHost('createMultipartUpload')
+    this.#assertHost('createMultipartUpload')
     throwIfAborted(signal)
 
     const allowedMetaFields = getAllowedMetaFields(
@@ -459,7 +491,7 @@
     oldSignal?: AbortSignal,
   ): Promise<AwsS3Part[]> {
     signal ??= oldSignal // eslint-disable-line no-param-reassign
-    this.assertHost('listParts')
+    this.#assertHost('listParts')
     throwIfAborted(signal)
 
     const filename = encodeURIComponent(key)
@@ -474,7 +506,7 @@
     oldSignal?: AbortSignal,
   ): Promise<B> {
     signal ??= oldSignal // eslint-disable-line no-param-reassign
-    this.assertHost('completeMultipartUpload')
+    this.#assertHost('completeMultipartUpload')
     throwIfAborted(signal)
 
     const filename = encodeURIComponent(key)
@@ -496,7 +528,7 @@
     if (this.#cachedTemporaryCredentials == null) {
       // We do not await it just yet, so concurrent calls do not try to override it:
       if (this.opts.getTemporarySecurityCredentials === true) {
-        this.assertHost('getTemporarySecurityCredentials')
+        this.#assertHost('getTemporarySecurityCredentials')
         this.#cachedTemporaryCredentials = this.#client
           .get<AwsS3STSResponse>('s3/sts', options)
           .then(assertServerError)
@@ -559,7 +591,7 @@
     file: UppyFile<M, B>,
     { uploadId, key, partNumber, signal }: SignPartOptions,
   ): Promise<AwsS3UploadParameters> {
-    this.assertHost('signPart')
+    this.#assertHost('signPart')
     throwIfAborted(signal)
 
     if (uploadId == null || key == null || partNumber == null) {
@@ -584,7 +616,7 @@
     oldSignal?: AbortSignal, // TODO: remove in next major
   ): Promise<void> {
     signal ??= oldSignal // eslint-disable-line no-param-reassign
-    this.assertHost('abortMultipartUpload')
+    this.#assertHost('abortMultipartUpload')
 
     const filename = encodeURIComponent(key)
     const uploadIdEnc = encodeURIComponent(uploadId)
@@ -922,7 +954,7 @@
   }
 
   #setCompanionHeaders = () => {
-    this.#client.setCompanionHeaders(this.opts.companionHeaders)
+    this.#client?.setCompanionHeaders(this.opts.companionHeaders)
   }
 
   #setResumableUploadsCapability = (boolean: boolean) => {