feat(storage): add support for content disposition and content type in getUrl

packages/aws-amplify/package.json

@@ -479,7 +479,7 @@
 			"name": "[Storage] getUrl (S3)",
 			"path": "./dist/esm/storage/index.mjs",
 			"import": "{ getUrl }",
-			"limit": "15.54 kB"
+			"limit": "15.64 kB"
 		},
 		{
 			"name": "[Storage] list (S3)",
@@ -497,7 +497,7 @@
 			"name": "[Storage] uploadData (S3)",
 			"path": "./dist/esm/storage/index.mjs",
 			"import": "{ uploadData }",
-			"limit": "19.64 kB"
+			"limit": "19.66 kB"
 		}
 	]
 }

packages/storage/__tests__/providers/s3/apis/getUrl.test.ts

@@ -236,6 +236,136 @@ describe('getUrl test with path', () => {
 			},
 		);
 	});
+	describe('Happy cases: With path and Content Disposition, Content Type', () => {
+		const config = {
+			credentials,
+			region,
+			userAgentValue: expect.any(String),
+		};
+		beforeEach(() => {
+			jest.mocked(headObject).mockResolvedValue({
+				ContentLength: 100,
+				ContentType: 'text/plain',
+				ETag: 'etag',
+				LastModified: new Date('01-01-1980'),
+				Metadata: { meta: 'value' },
+				$metadata: {} as any,
+			});
+			jest.mocked(getPresignedGetObjectUrl).mockResolvedValue(mockURL);
+		});
+		afterEach(() => {
+			jest.clearAllMocks();
+		});
+
+		test.each([
+			{
+				path: 'path',
+				expectedKey: 'path',
+				contentDisposition: 'inline; filename="example.txt"',
+				contentType: 'text/plain',
+			},
+			{
+				path: () => 'path',
+				expectedKey: 'path',
+				contentDisposition: {
+					type: 'attachment' as const,
+					filename: 'example.pdf',
+				},
+				contentType: 'application/pdf',
+			},
+		])(
+			'should getUrl with path $path and expectedKey $expectedKey and content disposition and content type',
+			async ({ path, expectedKey, contentDisposition, contentType }) => {
+				const headObjectOptions = {
+					Bucket: bucket,
+					Key: expectedKey,
+				};
+				const { url, expiresAt } = await getUrlWrapper({
+					path,
+					options: {
+						validateObjectExistence: true,
+						contentDisposition,
+						contentType,
+					},
+				});
+				expect(getPresignedGetObjectUrl).toHaveBeenCalledTimes(1);
+				expect(headObject).toHaveBeenCalledTimes(1);
+				await expect(headObject).toBeLastCalledWithConfigAndInput(
+					config,
+					headObjectOptions,
+				);
+				expect({ url, expiresAt }).toEqual({
+					url: mockURL,
+					expiresAt: expect.any(Date),
+				});
+			},
+		);
+	});
+	describe('Error cases: With invalid Content Disposition', () => {
+		const config = {
+			credentials,
+			region,
+			userAgentValue: expect.any(String),
+		};
+		beforeEach(() => {
+			jest.mocked(headObject).mockResolvedValue({
+				ContentLength: 100,
+				ContentType: 'text/plain',
+				ETag: 'etag',
+				LastModified: new Date('01-01-1980'),
+				Metadata: { meta: 'value' },
+				$metadata: {} as any,
+			});
+			jest.mocked(getPresignedGetObjectUrl).mockResolvedValue(mockURL);
+		});
+
+		afterEach(() => {
+			jest.clearAllMocks();
+		});
+
+		test.each([
+			{
+				path: 'path',
+				expectedKey: 'path',
+				contentDisposition: {
+					type: 'invalid' as 'attachment' | 'inline',
+					filename: '"example.txt',
+				},
+			},
+			{
+				path: 'path',
+				expectedKey: 'path',
+				contentDisposition: {
+					type: 'invalid' as 'attachment' | 'inline',
+				},
+			},
+		])(
+			'should ignore for invalid content disposition: $contentDisposition',
+			async ({ path, expectedKey, contentDisposition }) => {
+				const headObjectOptions = {
+					Bucket: bucket,
+					Key: expectedKey,
+				};
+				const { url, expiresAt } = await getUrlWrapper({
+					path,
+					options: {
+						validateObjectExistence: true,
+						contentDisposition,
+					},
+				});
+				expect(getPresignedGetObjectUrl).toHaveBeenCalledTimes(1);
+				expect(headObject).toHaveBeenCalledTimes(1);
+				await expect(headObject).toBeLastCalledWithConfigAndInput(
+					config,
+					headObjectOptions,
+				);
+				expect({ url, expiresAt }).toEqual({
+					url: mockURL,
+					expiresAt: expect.any(Date),
+				});
+			},
+		);
+	});
 	describe('Error cases :  With path', () => {
 		afterAll(() => {
 			jest.clearAllMocks();

packages/storage/__tests__/providers/s3/utils/client/S3/getPresignedGetObjectUrl.test.ts

@@ -70,4 +70,44 @@ describe('serializeGetObjectRequest', () => {
 			}),
 		);
 	});
+
+	it('should return get object API request with disposition and content type', async () => {
+		const actual = await getPresignedGetObjectUrl(
+			{
+				...defaultConfigWithStaticCredentials,
+				signingRegion: defaultConfigWithStaticCredentials.region,
+				signingService: 's3',
+				expiration: 900,
+				userAgentValue: 'UA',
+			},
+			{
+				Bucket: 'bucket',
+				Key: 'key',
+				ResponseContentDisposition: 'attachment; filename="filename.jpg"',
+				ResponseContentType: 'application/pdf',
+			},
+		);
+
+		expect(actual).toEqual(
+			expect.objectContaining({
+				hostname: `bucket.s3.${defaultConfigWithStaticCredentials.region}.amazonaws.com`,
+				pathname: '/key',
+				searchParams: expect.objectContaining({
+					get: expect.any(Function),
+				}),
+			}),
+		);
+
+		expect(actual.searchParams.get('X-Amz-Expires')).toBe('900');
+		expect(actual.searchParams.get('x-amz-content-sha256')).toEqual(
+			expect.any(String),
+		);
+		expect(actual.searchParams.get('response-content-disposition')).toBe(
+			'attachment; filename="filename.jpg"',
+		);
+		expect(actual.searchParams.get('response-content-type')).toBe(
+			'application/pdf',
+		);
+		expect(actual.searchParams.get('x-amz-user-agent')).toBe('UA');
+	});
 });

packages/storage/__tests__/providers/s3/utils/constructContentDisposition.test.ts

@@ -0,0 +1,67 @@
+import { constructContentDisposition } from '../../../../src/providers/s3/utils/constructContentDisposition';
+import { ContentDisposition } from '../../../../src/providers/s3/types/options';
+
+describe('constructContentDisposition', () => {
+	it('should return undefined when input is undefined', () => {
+		expect(constructContentDisposition(undefined)).toBeUndefined();
+	});
+
+	it('should return the input string when given a string', () => {
+		const input = 'inline; filename="example.txt"';
+		expect(constructContentDisposition(input)).toBe(input);
+	});
+
+	it('should construct disposition string with filename when given an object with type and filename', () => {
+		const input: ContentDisposition = {
+			type: 'attachment',
+			filename: 'example.pdf',
+		};
+		expect(constructContentDisposition(input)).toBe(
+			'attachment; filename="example.pdf"',
+		);
+	});
+
+	it('should return only the type when given an object with type but no filename', () => {
+		const input: ContentDisposition = {
+			type: 'inline',
+		};
+		expect(constructContentDisposition(input)).toBe('inline');
+	});
+
+	it('should handle empty string filename', () => {
+		const input: ContentDisposition = {
+			type: 'attachment',
+			filename: '',
+		};
+		expect(constructContentDisposition(input)).toBe('attachment; filename=""');
+	});
+
+	it('should handle filenames with spaces', () => {
+		const input: ContentDisposition = {
+			type: 'attachment',
+			filename: 'my file.txt',
+		};
+		expect(constructContentDisposition(input)).toBe(
+			'attachment; filename="my file.txt"',
+		);
+	});
+
+	it('should handle filenames with special characters', () => {
+		const input: ContentDisposition = {
+			type: 'attachment',
+			filename: 'file"with"quotes.txt',
+		};
+		expect(constructContentDisposition(input)).toBe(
+			'attachment; filename="file"with"quotes.txt"',
+		);
+	});
+
+	// Edge cases
+	it('should return undefined for null input', () => {
+		expect(constructContentDisposition(null as any)).toBeUndefined();
+	});
+
+	it('should return undefined for number input', () => {
+		expect(constructContentDisposition(123 as any)).toBeUndefined();
+	});
+});

packages/storage/src/providers/s3/apis/internal/getUrl.ts

@@ -22,6 +22,7 @@ import {
 	MAX_URL_EXPIRATION,
 	STORAGE_INPUT_KEY,
 } from '../../utils/constants';
+import { constructContentDisposition } from '../../utils/constructContentDisposition';
 
 import { getProperties } from './getProperties';
 
@@ -74,6 +75,14 @@ export const getUrl = async (
 			{
 				Bucket: bucket,
 				Key: finalKey,
+				...(getUrlOptions?.contentDisposition && {
+					ResponseContentDisposition: constructContentDisposition(
+						getUrlOptions.contentDisposition,
+					),
+				}),
+				...(getUrlOptions?.contentType && {
+					ResponseContentType: getUrlOptions.contentType,
+				}),
 			},
 		),
 		expiresAt: new Date(Date.now() + urlExpirationInSec * 1000),

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

@@ -3,10 +3,11 @@
 
 import { StorageAccessLevel } from '@aws-amplify/core';
 
-import { ResolvedS3Config } from '../../../types/options';
+import { ContentDisposition, ResolvedS3Config } from '../../../types/options';
 import { StorageUploadDataPayload } from '../../../../../types';
 import { Part, createMultipartUpload } from '../../../utils/client';
 import { logger } from '../../../../../utils';
+import { constructContentDisposition } from '../../../utils/constructContentDisposition';
 
 import {
 	cacheMultipartUpload,
@@ -22,7 +23,7 @@ interface LoadOrCreateMultipartUploadOptions {
 	keyPrefix?: string;
 	key: string;
 	contentType?: string;
-	contentDisposition?: string;
+	contentDisposition?: string | ContentDisposition;
 	contentEncoding?: string;
 	metadata?: Record<string, string>;
 	size?: number;
@@ -102,7 +103,7 @@ export const loadOrCreateMultipartUpload = async ({
 				Bucket: bucket,
 				Key: finalKey,
 				ContentType: contentType,
-				ContentDisposition: contentDisposition,
+				ContentDisposition: constructContentDisposition(contentDisposition),
 				ContentEncoding: contentEncoding,
 				Metadata: metadata,
 			},

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

@@ -14,6 +14,7 @@ import { ItemWithKey, ItemWithPath } from '../../types/outputs';
 import { putObject } from '../../utils/client';
 import { getStorageUserAgentValue } from '../../utils/userAgent';
 import { STORAGE_INPUT_KEY } from '../../utils/constants';
+import { constructContentDisposition } from '../../utils/constructContentDisposition';
 
 /**
  * Get a function the returns a promise to call putObject API to S3.
@@ -57,7 +58,7 @@ export const putObjectJob =
 				Key: finalKey,
 				Body: data,
 				ContentType: contentType,
-				ContentDisposition: contentDisposition,
+				ContentDisposition: constructContentDisposition(contentDisposition),
 				ContentEncoding: contentEncoding,
 				Metadata: metadata,
 				ContentMD5: isObjectLockEnabled

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

@@ -19,6 +19,15 @@ interface CommonOptions {
 	useAccelerateEndpoint?: boolean;
 }
 
+/**
+ * Represents the content disposition of a file.
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Disposition
+ */
+export interface ContentDisposition {
+	type: 'attachment' | 'inline';
+	filename?: string;
+}
+
 /** @deprecated This may be removed in the next major version. */
 type ReadOptions =
 	| {
@@ -119,6 +128,19 @@ export type GetUrlOptions = CommonOptions & {
 	 * @default 900 (15 minutes)
 	 */
 	expiresIn?: number;
+	/**
+	 * The default content-disposition header value of the file when downloading it.
+	 *   If a string is provided, it will be used as-is.
+	 *   If an object is provided, it will be used to construct the header value
+	 *   based on the ContentDisposition type definition.
+	 * @see https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Disposition
+	 */
+	contentDisposition?: ContentDisposition | string;
+	/**
+	 * The content-type header value of the file when downloading it.
+	 * @see https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Type
+	 */
+	contentType?: string;
 };
 
 /** @deprecated Use {@link GetUrlOptionsWithPath} instead. */
@@ -140,9 +162,12 @@ export type UploadDataOptions = CommonOptions &
 	TransferOptions & {
 		/**
 		 * The default content-disposition header value of the file when downloading it.
+		 *   If a string is provided, it will be used as-is.
+		 *   If an object is provided, it will be used to construct the header value
+		 *   based on the ContentDisposition type definition.
 		 * @see https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Disposition
 		 */
-		contentDisposition?: string;
+		contentDisposition?: ContentDisposition | string;
 		/**
 		 * The default content-encoding header value of the file when downloading it.
 		 * @see https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Encoding