@aws-amplify/core 5.3.2-unstable.ffe65ea.1 → 5.4.0

package/src/clients/internal/composeTransferHandler.ts

@@ -0,0 +1,89 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import {
+	Middleware,
+	MiddlewareHandler,
+	TransferHandler,
+	Request as RequestBase,
+	Response as ResponseBase,
+} from '../types';
+
+/**
+ * Compose a transfer handler with a core transfer handler and a list of middleware.
+ * @param coreHandler Core transfer handler
+ * @param middleware	List of middleware
+ * @returns A transfer handler whose option type is the union of the core
+ * 	transfer handler's option type and the middleware's option type.
+ * @internal
+ */
+export const composeTransferHandler =
+	<
+		MiddlewareOptionsArr extends any[] = [],
+		Request extends RequestBase = RequestBase,
+		Response extends ResponseBase = ResponseBase,
+		CoreHandler extends TransferHandler<
+			Request,
+			Response,
+			any
+		> = TransferHandler<Request, Response, {}>
+	>(
+		coreHandler: CoreHandler,
+		middleware: OptionToMiddleware<Request, Response, MiddlewareOptionsArr>
+	) =>
+	(
+		request: Request,
+		options: MergeNoConflictKeys<
+			[...MiddlewareOptionsArr, InferOptionTypeFromTransferHandler<CoreHandler>]
+		>
+	) => {
+		const context = {};
+		let composedHandler: MiddlewareHandler<Request, Response> = (
+			request: Request
+		) => coreHandler(request, options);
+		for (let i = middleware.length - 1; i >= 0; i--) {
+			const m = middleware[i];
+			const resolvedMiddleware = m(options);
+			composedHandler = resolvedMiddleware(composedHandler, context);
+		}
+		return composedHandler(request);
+	};
+
+/**
+ * Type to convert a middleware option type to a middleware type with the given
+ * option type.
+ */
+type OptionToMiddleware<
+	Request extends RequestBase,
+	Response extends ResponseBase,
+	Options extends any[]
+> = Options extends []
+	? []
+	: Options extends [infer LastOption]
+	? [Middleware<Request, Response, LastOption>]
+	: Options extends [infer FirstOption, ...infer RestOptions]
+	? [
+			Middleware<Request, Response, FirstOption>,
+			...OptionToMiddleware<Request, Response, RestOptions>
+	  ]
+	: never;
+
+/**
+ * Type to intersect multiple types if they have no conflict keys.
+ */
+type MergeNoConflictKeys<Options extends any[]> = Options extends [
+	infer OnlyOption
+]
+	? OnlyOption
+	: Options extends [infer FirstOption, infer SecondOption]
+	? FirstOption & SecondOption
+	: Options extends [infer FirstOption, ...infer RestOptions]
+	? FirstOption & MergeNoConflictKeys<RestOptions>
+	: never;
+
+/**
+ * Type to infer the option type of a transfer handler type.
+ */
+type InferOptionTypeFromTransferHandler<
+	T extends TransferHandler<any, any, any>
+> = Parameters<T>[1];

package/src/clients/middleware/retry/defaultRetryDecider.ts

@@ -0,0 +1,54 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { HttpResponse, ErrorParser } from '../../types';
+import { isClockSkewError } from '../../utils/isClockSkewError';
+
+/**
+ * Get retry decider function
+ * @param errorParser Function to load JavaScript error from HTTP response
+ */
+export const getRetryDecider =
+	(errorParser: ErrorParser) =>
+	async (response?: HttpResponse, error?: Error): Promise<boolean> => {
+		const { name: errorCode } = error ?? (await errorParser(response)) ?? {};
+		const statusCode = response?.statusCode;
+		return (
+			isConnectionError(error) ||
+			isThrottlingError(statusCode, errorCode) ||
+			isClockSkewError(errorCode) ||
+			isServerSideError(statusCode, errorCode)
+		);
+	};
+
+// reference: https://github.com/aws/aws-sdk-js-v3/blob/ab0e7be36e7e7f8a0c04834357aaad643c7912c3/packages/service-error-classification/src/constants.ts#L22-L37
+const THROTTLING_ERROR_CODES = [
+	'BandwidthLimitExceeded',
+	'EC2ThrottledException',
+	'LimitExceededException',
+	'PriorRequestNotComplete',
+	'ProvisionedThroughputExceededException',
+	'RequestLimitExceeded',
+	'RequestThrottled',
+	'RequestThrottledException',
+	'SlowDown',
+	'ThrottledException',
+	'Throttling',
+	'ThrottlingException',
+	'TooManyRequestsException',
+];
+
+const TIMEOUT_ERROR_CODES = [
+	'TimeoutError',
+	'RequestTimeout',
+	'RequestTimeoutException',
+];
+
+const isThrottlingError = (statusCode?: number, errorCode?: string) =>
+	statusCode === 429 || THROTTLING_ERROR_CODES.includes(errorCode);
+
+const isConnectionError = (error?: Error) => error?.name === 'Network error';
+
+const isServerSideError = (statusCode?: number, errorCode?: string) =>
+	[500, 502, 503, 504].includes(statusCode) ||
+	TIMEOUT_ERROR_CODES.includes(errorCode);

package/src/clients/middleware/retry/index.ts

@@ -0,0 +1,6 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+export { RetryOptions, retryMiddleware } from './middleware';
+export { jitteredBackoff } from './jitteredBackoff';
+export { getRetryDecider } from './defaultRetryDecider';

package/src/clients/middleware/retry/jitteredBackoff.ts

@@ -0,0 +1,16 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import type { RetryOptions } from './middleware';
+// TODO: [v6] The separate retry utility is used by Data packages now and will replaced by retry middleware.
+import { jitteredBackoff as jitteredBackoffUtil } from '../../../Util/Retry';
+
+const DEFAULT_MAX_DELAY_MS = 5 * 60 * 1000;
+
+export const jitteredBackoff: RetryOptions['computeDelay'] = attempt => {
+	const delayFunction = jitteredBackoffUtil(DEFAULT_MAX_DELAY_MS);
+	const delay = delayFunction(attempt);
+	// The delayFunction returns false when the delay is greater than the max delay(5 mins).
+	// In this case, the retry middleware will delay 5 mins instead, as a ceiling of the delay.
+	return delay === false ? DEFAULT_MAX_DELAY_MS : delay;
+};

package/src/clients/middleware/retry/middleware.ts

@@ -0,0 +1,133 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { MetadataBearer } from '@aws-sdk/types';
+import {
+	MiddlewareContext,
+	MiddlewareHandler,
+	Request,
+	Response,
+} from '../../types/core';
+
+const DEFAULT_RETRY_ATTEMPTS = 3;
+
+/**
+ * Configuration of the retry middleware
+ */
+export interface RetryOptions<TResponse = Response> {
+	/**
+	 * Function to decide if the request should be retried.
+	 *
+	 * @param response Optional response of the request.
+	 * @param error Optional error thrown from previous attempts.
+	 * @returns True if the request should be retried.
+	 */
+	retryDecider: (response?: TResponse, error?: unknown) => Promise<boolean>;
+	/**
+	 * Function to compute the delay in milliseconds before the next retry based
+	 * on the number of attempts.
+	 * @param attempt Current number of attempts, including the first attempt.
+	 * @returns Delay in milliseconds.
+	 */
+	computeDelay: (attempt: number) => number;
+	/**
+	 * Maximum number of retry attempts, starting from 1. Defaults to 3.
+	 */
+	maxAttempts?: number;
+	/**
+	 * Optional AbortSignal to abort the retry attempts.
+	 */
+	abortSignal?: AbortSignal;
+}
+
+/**
+ * Retry middleware
+ */
+export const retryMiddleware = <TInput = Request, TOutput = Response>({
+	maxAttempts = DEFAULT_RETRY_ATTEMPTS,
+	retryDecider,
+	computeDelay,
+	abortSignal,
+}: RetryOptions<TOutput>) => {
+	if (maxAttempts < 1) {
+		throw new Error('maxAttempts must be greater than 0');
+	}
+	return (
+		next: MiddlewareHandler<TInput, TOutput>,
+		context: MiddlewareContext
+	) =>
+		async function retryMiddleware(request: TInput) {
+			let error: Error;
+			let attemptsCount = context.attemptsCount ?? 0;
+			let response: TOutput;
+			while (!abortSignal?.aborted && attemptsCount < maxAttempts) {
+				error = undefined;
+				response = undefined;
+				try {
+					response = await next(request);
+				} catch (e) {
+					error = e;
+				}
+				// context.attemptsCount may be updated after calling next handler which may retry the request by itself.
+				attemptsCount =
+					context.attemptsCount > attemptsCount
+						? context.attemptsCount
+						: attemptsCount + 1;
+				context.attemptsCount = attemptsCount;
+				if (await retryDecider(response, error)) {
+					if (!abortSignal?.aborted && attemptsCount < maxAttempts) {
+						// prevent sleep for last attempt or cancelled request;
+						const delay = computeDelay(attemptsCount);
+						await cancellableSleep(delay, abortSignal);
+					}
+					continue;
+				} else if (response) {
+					updateMetadataAttempts(response, attemptsCount);
+					return response;
+				} else {
+					updateMetadataAttempts(error, attemptsCount);
+					throw error;
+				}
+			}
+			throw abortSignal?.aborted
+				? new Error('Request aborted')
+				: error ?? new Error('Retry attempts exhausted');
+		};
+};
+
+const cancellableSleep = (timeoutMs: number, abortSignal?: AbortSignal) => {
+	if (abortSignal?.aborted) {
+		return Promise.resolve();
+	}
+	let timeoutId;
+	let sleepPromiseResolveFn;
+	const sleepPromise = new Promise<void>(resolve => {
+		sleepPromiseResolveFn = resolve;
+		timeoutId = setTimeout(resolve, timeoutMs);
+	});
+	abortSignal?.addEventListener('abort', function cancelSleep(event) {
+		clearTimeout(timeoutId);
+		abortSignal?.removeEventListener('abort', cancelSleep);
+		sleepPromiseResolveFn();
+	});
+	return sleepPromise;
+};
+
+/**
+ * Check if the response is a contains `$metadata` property.
+ *
+ * @internal Amplify internal use only
+ */
+export const isMetadataBearer = (
+	response: unknown
+): response is MetadataBearer => typeof response?.['$metadata'] === 'object';
+
+const updateMetadataAttempts = (
+	nextHandlerOutput: Object,
+	attempts: number
+) => {
+	if (isMetadataBearer(nextHandlerOutput)) {
+		nextHandlerOutput.$metadata.attempts = attempts;
+	}
+	nextHandlerOutput['$metadata'] = { attempts };
+};

package/src/clients/middleware/signing/index.ts

@@ -0,0 +1,4 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+export { signingMiddleware, SigningOptions } from './middleware';

package/src/clients/middleware/signing/middleware.ts

@@ -0,0 +1,65 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import {
+	Credentials,
+	HttpRequest,
+	HttpResponse,
+	MiddlewareHandler,
+} from '../../types';
+import { isClockSkewError } from '../../utils/isClockSkewError';
+import { signRequest } from './signer/signatureV4';
+import { getSkewCorrectedDate } from './utils/getSkewCorrectedDate';
+import { getUpdatedSystemClockOffset } from './utils/getUpdatedSystemClockOffset';
+
+/**
+ * Configuration of the signing middleware
+ */
+export interface SigningOptions {
+	credentials: Credentials;
+	region: string;
+	service: string;
+}
+
+/**
+ * Middleware that SigV4 signs request with AWS credentials, and correct system clock offset.
+ */
+export const signingMiddleware = ({
+	credentials,
+	region,
+	service,
+}: SigningOptions) => {
+	let currentSystemClockOffset;
+	return (next: MiddlewareHandler<HttpRequest, HttpResponse>) =>
+		async function signingMiddleware(request: HttpRequest) {
+			currentSystemClockOffset = currentSystemClockOffset ?? 0;
+			const signRequestOptions = {
+				credentials,
+				signingDate: getSkewCorrectedDate(currentSystemClockOffset),
+				signingRegion: region,
+				signingService: service,
+			};
+			const signedRequest = await signRequest(request, signRequestOptions);
+			try {
+				const response = await next(signedRequest);
+				return response;
+			} catch (error) {
+				const dateString = shouldUseServerTime(error)
+					? error.ServerTime
+					: getDateHeader(error.$response);
+				if (dateString) {
+					currentSystemClockOffset = getUpdatedSystemClockOffset(
+						Date.parse(dateString),
+						currentSystemClockOffset
+					);
+				}
+				throw error;
+			}
+		};
+};
+
+const shouldUseServerTime = ({ ServerTime, Code }: any): boolean =>
+	ServerTime && isClockSkewError(Code);
+
+const getDateHeader = ({ headers }: any = {}): string | undefined =>
+	headers?.date ?? headers?.Date;

package/src/clients/middleware/signing/utils/extendedEncodeURIComponent.ts

@@ -0,0 +1,21 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * Wraps encodeURIComponent to encode additional characters to fully adhere to RFC 3986.
+ * @see https://github.com/aws/aws-sdk-js-v3/blob/86b432c464150069678b25ff88d57c2ca26e75a2/packages/smithy-client/src/extended-encode-uri-component.ts#L7
+ *
+ * @param uri URI string to encode
+ * @returns RFC 3986 encoded string
+ *
+ * @internal
+ */
+export const extendedEncodeURIComponent = (uri: string): string => {
+	// Match characters normally not encoded by `encodeURIComponent`
+	const extendedCharacters = /[!'()*]/g;
+
+	return encodeURIComponent(uri).replace(extendedCharacters, hexEncode);
+};
+
+const hexEncode = (c: string) =>
+	`%${c.charCodeAt(0).toString(16).toUpperCase()}`;

package/src/clients/middleware/signing/utils/getSkewCorrectedDate.ts

@@ -0,0 +1,14 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * Returns a `Date` that is corrected for clock skew.
+ *
+ * @param systemClockOffset The offset of the system clock in milliseconds.
+ *
+ * @returns `Date` representing the current time adjusted by the system clock offset.
+ *
+ * @internal
+ */
+export const getSkewCorrectedDate = (systemClockOffset: number): Date =>
+	new Date(Date.now() + systemClockOffset);

package/src/clients/middleware/signing/utils/getUpdatedSystemClockOffset.ts

@@ -0,0 +1,22 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { isClockSkewed } from './isClockSkewed';
+
+/**
+ * Returns the difference between clock time and the current system time if clock is skewed.
+ *
+ * @param clockTimeInMilliseconds Clock time in milliseconds.
+ * @param currentSystemClockOffset Current system clock offset in milliseconds.
+ *
+ * @internal
+ */
+export const getUpdatedSystemClockOffset = (
+	clockTimeInMilliseconds: number,
+	currentSystemClockOffset: number
+): number => {
+	if (isClockSkewed(clockTimeInMilliseconds, currentSystemClockOffset)) {
+		return clockTimeInMilliseconds - Date.now();
+	}
+	return currentSystemClockOffset;
+};

package/src/clients/middleware/signing/utils/isClockSkewed.ts

@@ -0,0 +1,26 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { getSkewCorrectedDate } from './getSkewCorrectedDate';
+
+// 5 mins in milliseconds. Ref: https://github.com/aws/aws-sdk-js-v3/blob/6c0f44fab30a1bb2134af47362a31332abc3666b/packages/middleware-signing/src/utils/isClockSkewed.ts#L10
+const SKEW_WINDOW = 5 * 60 * 1000;
+
+/**
+ * Checks if the provided date is within the skew window of 5 minutes.
+ *
+ * @param clockTimeInMilliseconds Time to check for skew in milliseconds.
+ * @param clockOffsetInMilliseconds Offset to check clock against in milliseconds.
+ *
+ * @returns True if skewed. False otherwise.
+ *
+ * @internal
+ */
+export const isClockSkewed = (
+	clockTimeInMilliseconds: number,
+	clockOffsetInMilliseconds: number
+): boolean =>
+	Math.abs(
+		getSkewCorrectedDate(clockOffsetInMilliseconds).getTime() -
+			clockTimeInMilliseconds
+	) >= SKEW_WINDOW;

package/src/clients/middleware/userAgent/index.ts

@@ -0,0 +1,4 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+export { userAgentMiddleware, UserAgentOptions } from './middleware';

package/src/clients/middleware/userAgent/middleware.ts

@@ -0,0 +1,41 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { HttpRequest, HttpResponse } from '../../types/http';
+import { Middleware } from '../../types/core';
+
+export interface UserAgentOptions {
+	userAgentHeader?: string;
+	userAgentValue?: string;
+}
+
+/**
+ * Middleware injects user agent string to specified header(default to 'x-amz-user-agent'),
+ * if the header is not set already.
+ *
+ * TODO: incorporate new user agent design
+ */
+export const userAgentMiddleware: Middleware<
+	HttpRequest,
+	HttpResponse,
+	UserAgentOptions
+> =
+	({
+		userAgentHeader = 'x-amz-user-agent',
+		userAgentValue = '',
+	}: UserAgentOptions) =>
+	next => {
+		return async function userAgentMiddleware(request) {
+			if (userAgentValue.trim().length === 0) {
+				const result = await next(request);
+				return result;
+			} else {
+				const headerName = userAgentHeader.toLowerCase();
+				request.headers[headerName] = request.headers[headerName]
+					? `${request.headers[headerName]} ${userAgentValue}`
+					: userAgentValue;
+				const response = await next(request);
+				return response;
+			}
+		};
+	};

package/src/clients/serde/index.ts

@@ -0,0 +1,5 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+export { parseMetadata } from './responseInfo';
+export { parseJsonBody, parseJsonError } from './json';

package/src/clients/serde/json.ts

@@ -0,0 +1,51 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { ErrorParser, HttpResponse } from '../types';
+import { parseMetadata } from './responseInfo';
+
+/**
+ * Utility functions for serializing and deserializing of JSON protocol in general(including: REST-JSON, JSON-RPC, etc.)
+ */
+
+/**
+ * Error parser for AWS JSON protocol.
+ */
+export const parseJsonError: ErrorParser = async (response?: HttpResponse) => {
+	if (!response || response.statusCode < 300) {
+		return;
+	}
+	const body = await parseJsonBody(response);
+	const sanitizeErrorCode = (rawValue: string | number): string => {
+		const [cleanValue] = rawValue.toString().split(/[\,\:]+/);
+		if (cleanValue.includes('#')) {
+			return cleanValue.split('#')[1];
+		}
+		return cleanValue;
+	};
+	const code = sanitizeErrorCode(
+		response.headers['x-amzn-errortype'] ??
+			body.code ??
+			body.__type ??
+			'UnknownError'
+	);
+	const message = body.message ?? body.Message ?? 'Unknown error';
+	const error = new Error(message);
+	return Object.assign(error, {
+		name: code,
+		$metadata: parseMetadata(response),
+	});
+};
+
+/**
+ * Parse JSON response body to JavaScript object.
+ */
+export const parseJsonBody = async (response: HttpResponse): Promise<any> => {
+	if (!response.body) {
+		throw new Error('Missing response payload');
+	}
+	const output = await response.body.json();
+	return Object.assign(output, {
+		$metadata: parseMetadata(response),
+	});
+};

package/src/clients/serde/responseInfo.ts

@@ -0,0 +1,20 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { ResponseMetadata } from '@aws-sdk/types';
+import { isMetadataBearer } from '../middleware/retry/middleware';
+import { HttpResponse } from '../types/http';
+
+export const parseMetadata = (response: HttpResponse): ResponseMetadata => {
+	const { headers, statusCode } = response;
+	return {
+		...(isMetadataBearer(response) ? response.$metadata : {}),
+		httpStatusCode: statusCode,
+		requestId:
+			headers['x-amzn-requestid'] ??
+			headers['x-amzn-request-id'] ??
+			headers['x-amz-request-id'],
+		extendedRequestId: headers['x-amz-id-2'],
+		cfId: headers['x-amz-cf-id'],
+	};
+};

package/src/clients/types/aws.ts

@@ -1,6 +1,27 @@
 // Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
 // SPDX-License-Identifier: Apache-2.0
 
+import { Endpoint } from './core';
+import { HttpResponse } from './http';
+
 export type { Credentials } from '@aws-sdk/types';
 
 export type SourceData = string | ArrayBuffer | ArrayBufferView;
+
+/**
+ * Basic option type for endpoint resolvers. It contains region only.
+ */
+export type EndpointResolverOptions = { region: string };
+
+export interface ServiceClientOptions {
+	region: string;
+	endpointResolver: (options: EndpointResolverOptions) => Endpoint;
+}
+
+/**
+ * parse errors from given response. If no error code is found, return undefined.
+ * This function is protocol-specific (e.g. JSON, XML, etc.)
+ */
+export type ErrorParser = (
+	response?: HttpResponse
+) => Promise<Error | undefined>;

package/src/clients/types/core.ts

@@ -12,6 +12,46 @@ export interface Request {
 export interface Response {
 	body: unknown;
 }
+
+export interface TransferHandler<
+	Input extends Request,
+	Output extends Response,
+	TransferOptions
+> {
+	(request: Input, options: TransferOptions): Promise<Output>;
+}
+
+/**
+ * A slimmed down version of the AWS SDK v3 middleware handler, only handling instantiated requests
+ */
+export type MiddlewareHandler<Input, Output> = (
+	request: Input
+) => Promise<Output>;
+
+/**
+ * The context object to store states across the middleware chain.
+ */
+export type MiddlewareContext = {
+	/**
+	 * The number of times the request has been attempted. This is set by retry middleware
+	 */
+	attemptsCount?: number;
+};
+
+type ConfiguredMiddleware<Input extends Request, Output extends Response> = (
+	next: MiddlewareHandler<Input, Output>,
+	context: MiddlewareContext
+) => MiddlewareHandler<Input, Output>;
+
+/**
+ * A slimmed down version of the AWS SDK v3 middleware, only handling tasks after Serde.
+ */
+export type Middleware<
+	Input extends Request,
+	Output extends Response,
+	MiddlewareOptions
+> = (options: MiddlewareOptions) => ConfiguredMiddleware<Input, Output>;
+
 export interface Endpoint {
 	url: URL;
 }