feat(storage): introduce preventOverwrite option to uploadData via HeadObject

packages/aws-amplify/package.json

@@ -497,7 +497,7 @@
  "name": "[Storage] uploadData (S3)",
  "path": "./dist/esm/storage/index.mjs",
  "import": "{ uploadData }",
- "limit": "19.94 kB"
+ "limit": "20.05 kB"
  }
  ]
 }

packages/storage/__tests__/providers/s3/apis/uploadData/multipartHandlers.test.ts

@@ -861,6 +861,74 @@ describe('getMultipartUploadHandlers with path', () => {
  expect(mockUploadPart).toHaveBeenCalledTimes(2);
  expect(mockCompleteMultipartUpload).not.toHaveBeenCalled();
  });
+
+ describe('overwrite prevention', () => {
+ beforeEach(() => {
+ mockHeadObject.mockReset();
+ mockUploadPart.mockReset();
+ });
+
+ it('should upload if target key is not found', async () => {
+ expect.assertions(7);
+ const notFoundError = new Error('mock message');
+ notFoundError.name = 'NotFound';
+ mockHeadObject.mockRejectedValueOnce(notFoundError);
+ mockMultipartUploadSuccess();
+
+ const { multipartUploadJob } = getMultipartUploadHandlers({
+ path: testPath,
+ data: new ArrayBuffer(8 * MB),
+ options: { preventOverwrite: true },
+ });
+ await multipartUploadJob();
+
+ expect(mockHeadObject).toHaveBeenCalledTimes(1);
+ await expect(mockHeadObject).toBeLastCalledWithConfigAndInput(
+ expect.objectContaining({
+ credentials,
+ region,
+ }),
+ expect.objectContaining({
+ Bucket: bucket,
+ Key: testPath,
+ }),
+ );
+ expect(mockCreateMultipartUpload).toHaveBeenCalledTimes(1);
+ expect(mockUploadPart).toHaveBeenCalledTimes(2);
+ expect(mockCompleteMultipartUpload).toHaveBeenCalledTimes(1);
+ });
+
+ it('should not upload if target key already exists', async () => {
+ expect.assertions(2);
+ mockHeadObject.mockResolvedValueOnce({
+ ContentLength: 0,
+ $metadata: {},
+ });
+ const { multipartUploadJob } = getMultipartUploadHandlers({
+ path: testPath,
+ data: new ArrayBuffer(8 * MB),
+ options: { preventOverwrite: true },
+ });
+ await expect(multipartUploadJob()).rejects.toThrow(
+ 'At least one of the pre-conditions you specified did not hold',
+ );
+ expect(mockCreateMultipartUpload).not.toHaveBeenCalled();
+ });
+
+ it('should not upload if HeadObject fails with other error', async () => {
+ expect.assertions(2);
+ const accessDeniedError = new Error('mock error');
+ accessDeniedError.name = 'AccessDenied';
+ mockHeadObject.mockRejectedValueOnce(accessDeniedError);
+ const { multipartUploadJob } = getMultipartUploadHandlers({
+ path: testPath,
+ data: new ArrayBuffer(8 * MB),
+ options: { preventOverwrite: true },
+ });
+ await expect(multipartUploadJob()).rejects.toThrow('mock error');
+ expect(mockCreateMultipartUpload).not.toHaveBeenCalled();
+ });
+ });
  });
 
  describe('upload caching', () => {

packages/storage/__tests__/providers/s3/apis/uploadData/putObjectJob.test.ts

@@ -4,7 +4,10 @@
 import { AWSCredentials } from '@aws-amplify/core/internals/utils';
 import { Amplify } from '@aws-amplify/core';
 
-import { putObject } from '../../../../../src/providers/s3/utils/client/s3data';
+import {
+ headObject,
+ putObject,
+} from '../../../../../src/providers/s3/utils/client/s3data';
 import { calculateContentMd5 } from '../../../../../src/providers/s3/utils';
 import { putObjectJob } from '../../../../../src/providers/s3/apis/uploadData/putObjectJob';
 import '../testUtils';
@@ -38,6 +41,7 @@ const credentials: AWSCredentials = {
 const identityId = 'identityId';
 const mockFetchAuthSession = jest.mocked(Amplify.Auth.fetchAuthSession);
 const mockPutObject = jest.mocked(putObject);
+const mockHeadObject = jest.mocked(headObject);
 
 mockFetchAuthSession.mockResolvedValue({
  credentials,
@@ -233,4 +237,79 @@ describe('putObjectJob with path', () => {
  await job();
  expect(calculateContentMd5).toHaveBeenCalledWith('data');
  });
+
+ describe('overwrite prevention', () => {
+ beforeEach(() => {
+ mockHeadObject.mockClear();
+ });
+
+ it('should upload if target key is not found', async () => {
+ expect.assertions(3);
+ const notFoundError = new Error('mock message');
+ notFoundError.name = 'NotFound';
+ mockHeadObject.mockRejectedValueOnce(notFoundError);
+
+ const job = putObjectJob(
+ {
+ path: testPath,
+ data: 'data',
+ options: { preventOverwrite: true },
+ },
+ new AbortController().signal,
+ );
+ await job();
+
+ await expect(mockHeadObject).toBeLastCalledWithConfigAndInput(
+ {
+ credentials,
+ region: 'region',
+ },
+ {
+ Bucket: 'bucket',
+ Key: testPath,
+ },
+ );
+ expect(mockHeadObject).toHaveBeenCalledTimes(1);
+ expect(mockPutObject).toHaveBeenCalledTimes(1);
+ });
+
+ it('should not upload if target key already exists', async () => {
+ expect.assertions(3);
+ mockHeadObject.mockResolvedValueOnce({
+ ContentLength: 0,
+ $metadata: {},
+ });
+ const job = putObjectJob(
+ {
+ path: testPath,
+ data: 'data',
+ options: { preventOverwrite: true },
+ },
+ new AbortController().signal,
+ );
+ await expect(job()).rejects.toThrow(
+ 'At least one of the pre-conditions you specified did not hold',
+ );
+ expect(mockHeadObject).toHaveBeenCalledTimes(1);
+ expect(mockPutObject).not.toHaveBeenCalled();
+ });
+
+ it('should not upload if HeadObject fails with other error', async () => {
+ expect.assertions(3);
+ const accessDeniedError = new Error('mock error');
+ accessDeniedError.name = 'AccessDenied';
+ mockHeadObject.mockRejectedValueOnce(accessDeniedError);
+ const job = putObjectJob(
+ {
+ path: testPath,
+ data: 'data',
+ options: { preventOverwrite: true },
+ },
+ new AbortController().signal,
+ );
+ await expect(job()).rejects.toThrow('mock error');
+ expect(mockHeadObject).toHaveBeenCalledTimes(1);
+ expect(mockPutObject).not.toHaveBeenCalled();
+ });
+ });
 });

packages/storage/src/providers/s3/apis/uploadData/multipart/uploadHandlers.ts

@@ -29,6 +29,7 @@ import {
 } from '../../../utils/client/s3data';
 import { getStorageUserAgentValue } from '../../../utils/userAgent';
 import { logger } from '../../../../../utils';
+import { validateObjectNotExists } from '../validateObjectNotExists';
 
 import { uploadPartExecutor } from './uploadPartExecutor';
 import { getUploadsCacheKey, removeCachedUpload } from './uploadCache';
@@ -92,6 +93,7 @@ export const getMultipartUploadHandlers = (
  contentEncoding,
  contentType = 'application/octet-stream',
  metadata,
+ preventOverwrite,
  onProgress,
  } = uploadDataOptions ?? {};
 
@@ -107,6 +109,13 @@ export const getMultipartUploadHandlers = (
  resolvedAccessLevel = resolveAccessLevel(accessLevel);
  }
 
+ if (preventOverwrite) {
+ await validateObjectNotExists(resolvedS3Config, {
+ Bucket: resolvedBucket,
+ Key: finalKey,
+ });
+ }
+
  if (!inProgressUpload) {
  const { uploadId, cachedParts } = await loadOrCreateMultipartUpload({
  s3Config: resolvedS3Config,

packages/storage/src/providers/s3/apis/uploadData/putObjectJob.ts

@@ -15,6 +15,8 @@ import { putObject } from '../../utils/client/s3data';
 import { getStorageUserAgentValue } from '../../utils/userAgent';
 import { STORAGE_INPUT_KEY } from '../../utils/constants';
 
+import { validateObjectNotExists } from './validateObjectNotExists';
+
 /**
  * Get a function the returns a promise to call putObject API to S3.
  *
@@ -41,10 +43,18 @@ export const putObjectJob =
  contentDisposition,
  contentEncoding,
  contentType = 'application/octet-stream',
+ preventOverwrite,
  metadata,
  onProgress,
  } = uploadDataOptions ?? {};
 
+ if (preventOverwrite) {
+ await validateObjectNotExists(s3Config, {
+ Bucket: bucket,
+ Key: finalKey,
+ });
+ }
+
  const { ETag: eTag, VersionId: versionId } = await putObject(
  {
  ...s3Config,

packages/storage/src/providers/s3/apis/uploadData/validateObjectNotExists.ts

@@ -0,0 +1,25 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { StorageError } from '../../../../errors/StorageError';
+import { ResolvedS3Config } from '../../types/options';
+import { HeadObjectInput, headObject } from '../../utils/client/s3data';
+
+export const validateObjectNotExists = async (
+ s3Config: ResolvedS3Config,
+ input: HeadObjectInput,
+): Promise<void> => {
+ try {
+ await headObject(s3Config, input);
+
+ throw new StorageError({
+ name: 'PreconditionFailed',
+ message: 'At least one of the pre-conditions you specified did not hold',
+ });
+ } catch (error) {
+ const serviceError = error as StorageError;
+ if (serviceError.name !== 'NotFound') {
+ throw error;
+ }
+ }
+};

packages/storage/src/providers/s3/types/options.ts

@@ -169,6 +169,11 @@ export type UploadDataOptions = CommonOptions &
  * @see https://docs.aws.amazon.com/AmazonS3/latest/userguide/UsingMetadata.html#UserMetadata
  */
  metadata?: Record<string, string>;
+ /**
+ * Enforces target key does not already exist in S3 before committing upload.
+ * @default false
+ */
+ preventOverwrite?: boolean;
  };
 
 /** @deprecated Use {@link UploadDataOptionsWithPath} instead. */