feat(storage): getProperties API

packages/predictions/package.json

@@ -74,7 +74,7 @@
 			"name": "Predictions (Identify provider)",
 			"path": "./lib-esm/index.js",
 			"import": "{ Amplify, Predictions, AmazonAIIdentifyPredictionsProvider }",
-			"limit": "104.5 kB"
+			"limit": "105 kB"
 		},
 		{
 			"name": "Predictions (Interpret provider)",

packages/storage/__tests__/Storage-unit-test.ts

@@ -44,6 +44,10 @@ class TestCustomProvider implements StorageProvider {
 		return Promise.resolve({ newKey: 'get' });
 	}
 
+	getProperties(key: string, options?: CustomProviderConfig) {
+		return Promise.resolve({ newKey: 'getProperties' });
+	}
+
 	put(key: string, object: any, config: CustomProviderConfig) {
 		return Promise.resolve({ newKey: 'put' });
 	}

packages/storage/__tests__/providers/AWSS3Provider-unit-test.ts

@@ -8,6 +8,7 @@ import {
 	ListObjectsV2Command,
 	CreateMultipartUploadCommand,
 	UploadPartCommand,
+	HeadObjectCommand,
 } from '@aws-sdk/client-s3';
 import { S3RequestPresigner } from '@aws-sdk/s3-request-presigner';
 
@@ -52,6 +53,14 @@ S3Client.prototype.send = jest.fn(async command => {
 			Contents: [resultObj],
 			IsTruncated: false,
 		};
+	} else if (command instanceof HeadObjectCommand) {
+		return {
+			ContentLength: '100',
+			ContentType: 'text/plain',
+			ETag: 'etag',
+			LastModified: 'lastmodified',
+			Metadata: { key: 'value' },
+		};
 	}
 	return 'data';
 });
@@ -519,6 +528,7 @@ describe('StorageProvider test', () => {
 					return Promise.resolve(credentials);
 				});
 			});
+
 			test('get existing object with validateObjectExistence option', async () => {
 				expect.assertions(5);
 				const options_with_validateObjectExistence = Object.assign(
@@ -556,11 +566,6 @@ describe('StorageProvider test', () => {
 
 			test('get non-existing object with validateObjectExistence option', async () => {
 				expect.assertions(2);
-				jest.spyOn(Credentials, 'get').mockImplementationOnce(() => {
-					return new Promise((res, rej) => {
-						res({});
-					});
-				});
 				const dispatchSpy = jest.spyOn(StorageUtils, 'dispatchStorageEvent');
 				jest
 					.spyOn(S3Client.prototype, 'send')
@@ -586,6 +591,63 @@ describe('StorageProvider test', () => {
 		});
 	});
 
+	describe('getProperties test', () => {
+		beforeEach(() => {
+			jest.spyOn(Credentials, 'get').mockImplementationOnce(() => {
+				return Promise.resolve(credentials);
+			});
+		});
+
+		test('getProperties successfully', async () => {
+			expect.assertions(4);
+			const spyon = jest.spyOn(S3Client.prototype, 'send');
+			const dispatchSpy = jest.spyOn(StorageUtils, 'dispatchStorageEvent');
+			const metadata = { key: 'value' };
+			expect(await storage.getProperties('key')).toEqual({
+				contentLength: '100',
+				contentType: 'text/plain',
+				eTag: 'etag',
+				lastModified: 'lastmodified',
+				metadata,
+			});
+			expect(dispatchSpy).toHaveBeenCalledTimes(1);
+			expect(dispatchSpy).toBeCalledWith(
+				false,
+				'getProperties',
+				{ method: 'getProperties', result: 'success' },
+				null,
+				'getProperties successful for key'
+			);
+			expect(spyon.mock.calls[0][0].input).toEqual({
+				Bucket: 'bucket',
+				Key: 'public/key',
+			});
+			spyon.mockClear();
+		});
+
+		test('get properties of non-existing object', async () => {
+			expect.assertions(2);
+			const dispatchSpy = jest.spyOn(StorageUtils, 'dispatchStorageEvent');
+			jest
+				.spyOn(S3Client.prototype, 'send')
+				.mockImplementationOnce(async params => {
+					throw { $metadata: { httpStatusCode: 404 }, name: 'NotFound' };
+				});
+			try {
+				await storage.getProperties('invalid_key');
+			} catch (error) {
+				expect(error.$metadata.httpStatusCode).toBe(404);
+				expect(dispatchSpy).toBeCalledWith(
+					false,
+					'getProperties',
+					{ method: 'getProperties', result: 'failed' },
+					null,
+					'invalid_key not found'
+				);
+			}
+		});
+	});
+
 	describe('put test', () => {
 		afterEach(() => {
 			jest.clearAllMocks();

packages/storage/src/Storage.ts

@@ -23,6 +23,8 @@ import {
 	StorageListOutput,
 	StorageCopyOutput,
 	UploadTask,
+	StorageGetPropertiesConfig,
+	StorageGetPropertiesOutput,
 } from './types';
 import axios, { CancelTokenSource } from 'axios';
 import { PutObjectCommandInput } from '@aws-sdk/client-s3';
@@ -307,6 +309,25 @@ export class Storage {
 		return axios.isCancel(error);
 	}
 
+	public getProperties<T extends StorageProvider | { [key: string]: any }>(
+		key: string,
+		config?: StorageGetPropertiesConfig<T>
+	): StorageGetPropertiesOutput<T> {
+		const provider = config?.provider || DEFAULT_PROVIDER;
+		const prov = this._pluggables.find(
+			pluggable => pluggable.getProviderName() === provider
+		);
+		if (prov === undefined) {
+			logger.debug('No plugin found with providerName', provider);
+			throw new Error('No plugin found with providerName');
+		}
+		const cancelTokenSource = this.getCancellableTokenSource();
+		const responsePromise = prov.getProperties(key, {
+			...config,
+		});
+		this.updateRequestToBeCancellable(responsePromise, cancelTokenSource);
+		return responsePromise as StorageGetPropertiesOutput<T>;
+	}
 	/**
 	 * Put a file in storage bucket specified to configure method
 	 * @param key - key of the object

packages/storage/src/providers/AWSS3Provider.ts

@@ -21,6 +21,7 @@ import {
 	GetObjectCommandInput,
 	ListObjectsV2Request,
 	HeadObjectCommand,
+	HeadObjectCommandInput,
 } from '@aws-sdk/client-s3';
 import { formatUrl } from '@aws-sdk/util-format-url';
 import { createRequest } from '@aws-sdk/util-create-request';
@@ -49,6 +50,8 @@ import {
 	UploadTask,
 	S3ClientOptions,
 	S3ProviderListOutput,
+	S3ProviderGetPropertiesOutput,
+	S3ProviderGetPropertiesConfig,
 } from '../types';
 import { StorageErrorStrings } from '../common/StorageErrorStrings';
 import { dispatchStorageEvent } from '../common/StorageUtils';
@@ -449,7 +452,7 @@ export class AWSS3Provider implements StorageProvider {
 		}
 		if (validateObjectExistence) {
 			const headObjectCommand = new HeadObjectCommand(params);
-			
+
 			try {
 				await s3.send(headObjectCommand);
 			} catch (error) {
@@ -498,6 +501,87 @@ export class AWSS3Provider implements StorageProvider {
 		}
 	}
 
+	/**
+	 * Get Properties of the object
+	 *
+	 * @param {string} key - key of the object
+	 * @param {S3ProviderGetPropertiesConfig} [config] - Optional configuration for the underlying S3 command
+	 * @return {Promise<S3ProviderGetPropertiesOutput>} - A promise resolves to contentType,
+	 * contentLength, eTag, lastModified, metadata
+	 */
+	public async getProperties(
+		key: string,
+		config?: S3ProviderGetPropertiesConfig
+	): Promise<S3ProviderGetPropertiesOutput> {
+		const credentialsOK = await this._ensureCredentials();
+		if (!credentialsOK || !this._isWithCredentials(this._config)) {
+			throw new Error(StorageErrorStrings.NO_CREDENTIALS);
+		}
+		const opt = Object.assign({}, this._config, config);
+		const {
+			bucket,
+			track = false,
+			SSECustomerAlgorithm,
+			SSECustomerKey,
+			SSECustomerKeyMD5,
+		} = opt;
+		const prefix = this._prefix(opt);
+		const final_key = prefix + key;
+		const emitter = new events.EventEmitter();
+		const s3 = this._createNewS3Client(opt, emitter);
+		logger.debug(`getProperties ${key} from ${final_key}`);
+
+		const params: HeadObjectCommandInput = {
+			Bucket: bucket,
+			Key: final_key,
+		};
+
+		if (SSECustomerAlgorithm) {
+			params.SSECustomerAlgorithm = SSECustomerAlgorithm;
+		}
+		if (SSECustomerKey) {
+			params.SSECustomerKey = SSECustomerKey;
+		}
+		if (SSECustomerKeyMD5) {
+			params.SSECustomerKeyMD5 = SSECustomerKeyMD5;
+		}
+		// See: https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/clients/client-s3/classes/headobjectcommand.html
+
+		const headObjectCommand = new HeadObjectCommand(params);
+		try {
+			const response = await s3.send(headObjectCommand);
+			const getPropertiesResponse: S3ProviderGetPropertiesOutput = {
+				contentLength: response.ContentLength,
+				contentType: response.ContentType,
+				eTag: response.ETag,
+				lastModified: response.LastModified,
+				metadata: response.Metadata,
+			};
+			dispatchStorageEvent(
+				track,
+				'getProperties',
+				{ method: 'getProperties', result: 'success' },
+				null,
+				`getProperties successful for ${key}`
+			);
+			return getPropertiesResponse;
+		} catch (error) {
+			if (error.$metadata.httpStatusCode === 404) {
+				dispatchStorageEvent(
+					track,
+					'getProperties',
+					{
+						method: 'getProperties',
+						result: 'failed',
+					},
+					null,
+					`${key} not found`
+				);
+			}
+			throw error;
+		}
+	}
+
 	/**
 	 * Put a file in S3 bucket specified to configure method
 	 * @param key - key of the object

packages/storage/src/types/AWSS3Provider.ts

@@ -5,6 +5,7 @@ import {
 	CopyObjectRequest,
 	_Object,
 	DeleteObjectCommandOutput,
+	HeadObjectRequest,
 } from '@aws-sdk/client-s3';
 import { StorageOptions, StorageAccessLevel } from './Storage';
 import {
@@ -51,6 +52,12 @@ export type S3ProviderGetConfig = CommonStorageOptions & {
 	validateObjectExistence?: boolean;
 };
 
+export type S3ProviderGetPropertiesConfig = CommonStorageOptions & {
+	SSECustomerAlgorithm?: HeadObjectRequest['SSECustomerAlgorithm'];
+	SSECustomerKey?: HeadObjectRequest['SSECustomerKey'];
+	SSECustomerKeyMD5?: HeadObjectRequest['SSECustomerKeyMD5'];
+};
+
 export type S3ProviderGetOuput<T> = T extends { download: true }
 	? GetObjectCommandOutput
 	: string;
@@ -173,6 +180,14 @@ export type S3ProviderCopyOutput = {
 	key: string;
 };
 
+export type S3ProviderGetPropertiesOutput = {
+	contentType: string;
+	contentLength: number;
+	eTag: string;
+	lastModified: Date;
+	metadata: Record<string, string>;
+};
+
 export type PutResult = {
 	key: string;
 };

packages/storage/src/types/Provider.ts

@@ -20,6 +20,9 @@ export interface StorageProvider {
 	// get object/pre-signed url from storage
 	get(key: string, options?): Promise<string | Object>;
 
+	// get properties of object
+	getProperties(key: string, options?): Promise<Object>;
+
 	// upload storage object
 	put(key: string, object, options?): Promise<Object> | UploadTask;
 
@@ -52,4 +55,10 @@ export interface StorageProviderWithCopy extends StorageProvider {
 	): Promise<any>;
 }
 
-export type StorageProviderApi = 'copy' | 'get' | 'put' | 'remove' | 'list';
+export type StorageProviderApi =
+	| 'copy'
+	| 'get'
+	| 'put'
+	| 'remove'
+	| 'list'
+	| 'getProperties';

packages/storage/src/types/Storage.ts

@@ -15,6 +15,7 @@ import {
 	S3ProviderListOutput,
 	S3ProviderCopyOutput,
 	S3ProviderPutOutput,
+	S3ProviderGetPropertiesOutput,
 } from '../';
 
 type Tail<T extends any[]> = ((...t: T) => void) extends (
@@ -87,6 +88,14 @@ export type StorageGetConfig<T extends Record<string, any>> =
 				T
 		  >;
 
+export type StorageGetPropertiesConfig<T extends Record<string, any>> =
+	T extends StorageProvider
+		? StorageOperationConfig<T, 'getProperties'>
+		: StorageOperationConfigMap<
+				StorageOperationConfig<AWSS3Provider, 'getProperties'>,
+				T
+		  >;
+
 export type StoragePutConfig<T extends Record<string, any>> =
 	T extends StorageProvider
 		? StorageOperationConfig<T, 'put'>
@@ -168,6 +177,12 @@ export type StorageCopyOutput<T> = PickProviderOutput<
 	'copy'
 >;
 
+export type StorageGetPropertiesOutput<T> = PickProviderOutput<
+	Promise<S3ProviderGetPropertiesOutput>,
+	T,
+	'getProperties'
+>;
+
 /**
  * Utility type to allow custom provider to use any config keys, if provider is set to AWSS3 then it should use
  * AWSS3Provider's config.