@aws-amplify/api-rest 0.0.0-unstable-1ca644b-20260128091132

package/src/types/index.ts

@@ -0,0 +1,138 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+import {
+	DocumentType,
+	RESTAuthMode,
+	RetryStrategy,
+} from '@aws-amplify/core/internals/utils';
+
+export type GetInput = ApiInput<RestApiOptionsBase>;
+export type PostInput = ApiInput<RestApiOptionsBase>;
+export type PutInput = ApiInput<RestApiOptionsBase>;
+export type PatchInput = ApiInput<RestApiOptionsBase>;
+export type DeleteInput = ApiInput<RestApiOptionsBase>;
+export type HeadInput = ApiInput<Omit<RestApiOptionsBase, 'body'>>;
+
+export type GetOperation = Operation<RestApiResponse>;
+export type PostOperation = Operation<RestApiResponse>;
+export type PutOperation = Operation<RestApiResponse>;
+export type PatchOperation = Operation<RestApiResponse>;
+export type DeleteOperation = Operation<RestApiResponse>;
+export type HeadOperation = Operation<Omit<RestApiResponse, 'body'>>;
+
+/**
+ * @internal
+ */
+export interface RestApiOptionsBase {
+	headers?: Headers;
+	queryParams?: Record<string, string>;
+	body?: DocumentType | FormData;
+	/**
+	 * Option controls whether or not cross-site Access-Control requests should be made using credentials
+	 * such as cookies, authorization headers or TLS client certificates. It has no effect on same-origin requests.
+	 * If set to `true`, the request will include credentials such as cookies, authorization headers, TLS
+	 * client certificates, and so on. Moreover the response cookies will also be set.
+	 * If set to `false`, the cross-site request will not include credentials, and the response cookies from a different
+	 * domain will be ignored.
+	 *
+	 * @default false
+	 * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest/withCredentials}
+	 */
+	withCredentials?: boolean;
+	/**
+	 * Retry strategy for the REST API calls. It will take precedence over REST `retryStrategy` in Amplify configuration libraryOptions.
+	 *
+	 * @default ` { strategy: 'jittered-exponential-backoff' } `
+	 */
+	retryStrategy?: RetryStrategy;
+	defaultAuthMode?: RESTAuthMode;
+	/**
+	 * custom timeout in milliseconds.
+	 */
+	timeout?: number;
+}
+
+type Headers = Record<string, string>;
+
+/**
+ * Type representing an operation that can be canceled.
+ *
+ * @internal
+ */
+export interface Operation<Response> {
+	response: Promise<Response>;
+	cancel(abortMessage?: string): void;
+}
+
+interface ResponsePayload {
+	blob(): Promise<Blob>;
+	json(): Promise<DocumentType>;
+	text(): Promise<string>;
+}
+
+/**
+ * Basic response type of REST API.
+ *
+ * @internal
+ */
+export interface RestApiResponse {
+	body: ResponsePayload;
+	statusCode: number;
+	headers: Headers;
+}
+
+/**
+ * @internal
+ */
+export interface ApiInput<Options> {
+	/**
+	 * Name of the REST API configured in Amplify singleton.
+	 */
+	apiName: string;
+	/**
+	 * Path of the REST API.
+	 */
+	path: string;
+	/**
+	 * Options to overwrite the REST API call behavior.
+	 */
+	options?: Options;
+}
+
+/**
+ * Input type to invoke REST POST API from GraphQl client.
+ * @internal
+ */
+export interface InternalPostInput {
+	// Resolved GraphQl endpoint url
+	url: URL;
+	options?: Omit<RestApiOptionsBase, 'retryStrategy'> & {
+		/**
+		 * Internal-only option for GraphQL client to provide the IAM signing service and region.
+		 * * If auth mode is 'iam', you MUST set this value.
+		 * * If auth mode is 'none', you MUST NOT set this value;
+		 * * If auth mode is 'apiKey' or 'oidc' or 'lambda' or 'userPool' because associated
+		 *   headers are provided, this value is ignored.
+		 */
+		signingServiceInfo?: {
+			service?: string;
+			region?: string;
+		};
+	};
+	/**
+	 * The abort controller to cancel the in-flight POST request.
+	 * Required if you want to make the internal post request cancellable. To make the internal post cancellable, you
+	 * must also call `updateRequestToBeCancellable()` with the promise from internal post call and the abort
+	 * controller.
+	 */
+	abortController?: AbortController;
+}
+
+/**
+ * Type for signingServiceInfo which enable IAM auth as well as overwrite the IAM signing info.
+ * @internal
+ */
+export interface SigningServiceInfo {
+	service?: string;
+	region?: string;
+}

package/src/utils/constants.ts

@@ -0,0 +1,15 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+export const DEFAULT_REST_IAM_SIGNING_SERVICE = 'execute-api';
+
+export const DEFAULT_APPSYNC_API_SERVICE = 'appsync-api';
+
+export const DEFAULT_IAM_SIGNING_REGION = 'us-east-1';
+
+/**
+ * The REST endpoints generated by API Gateway
+ * @see {@link https://docs.aws.amazon.com/general/latest/gr/apigateway.html#apigateway_region_data_plane}
+ */
+export const APIG_HOSTNAME_PATTERN =
+	/^.+\.([a-z0-9-]+)\.([a-z0-9-]+)\.amazonaws\.com/;

package/src/utils/createCancellableOperation.ts

@@ -0,0 +1,108 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { HttpResponse } from '@aws-amplify/core/internals/aws-client-utils';
+
+import { CanceledError } from '../errors';
+import { Operation } from '../types';
+
+import { parseRestApiServiceError } from './serviceError';
+import { logger } from './logger';
+
+/**
+ * Create a cancellable operation conforming to the internal POST API interface.
+ * @internal
+ */
+export function createCancellableOperation(
+	handler: () => Promise<HttpResponse>,
+	abortController: AbortController,
+	operationType: 'internal',
+	timeout?: number,
+): Promise<HttpResponse>;
+
+/**
+ * Create a cancellable operation conforming to the external REST API interface.
+ * @internal
+ */
+export function createCancellableOperation(
+	handler: () => Promise<HttpResponse>,
+	abortController: AbortController,
+	operationType: 'public',
+	timeout?: number,
+): Operation<HttpResponse>;
+
+/**
+ * @internal
+ */
+export function createCancellableOperation(
+	handler: () => Promise<HttpResponse>,
+	abortController: AbortController,
+	operationType: 'public' | 'internal',
+	timeout?: number,
+): Operation<HttpResponse> | Promise<HttpResponse> {
+	const abortSignal = abortController.signal;
+	let abortReason: string;
+	if (timeout != null) {
+		if (timeout < 0) {
+			throw new Error('Timeout must be a non-negative number');
+		}
+		setTimeout(() => {
+			abortReason = 'TimeoutError';
+			abortController.abort(abortReason);
+		}, timeout);
+	}
+
+	const job = async () => {
+		try {
+			const response = await handler();
+
+			if (response.statusCode >= 300) {
+				throw await parseRestApiServiceError(response)!;
+			}
+
+			return response;
+		} catch (error: any) {
+			if (error.name === 'AbortError' || abortSignal?.aborted === true) {
+				// Check if timeout caused the abort
+				const isTimeout = abortReason && abortReason === 'TimeoutError';
+
+				if (isTimeout) {
+					const timeoutError = new Error(`Request timeout after ${timeout}ms`);
+					timeoutError.name = 'TimeoutError';
+					logger.debug(timeoutError);
+					throw timeoutError;
+				} else {
+					const message = abortReason ?? abortSignal.reason;
+					const canceledError = new CanceledError({
+						...(message && { message }),
+						underlyingError: error,
+						recoverySuggestion:
+							'The API request was explicitly canceled. If this is not intended, validate if you called the `cancel()` function on the API request erroneously.',
+					});
+					logger.debug(canceledError);
+					throw canceledError;
+				}
+			}
+			logger.debug(error);
+			throw error;
+		}
+	};
+
+	if (operationType === 'internal') {
+		return job();
+	} else {
+		const cancel = (abortMessage?: string) => {
+			if (abortSignal.aborted === true) {
+				return;
+			}
+			abortController.abort(abortMessage);
+			// If abort reason is not supported, set a scoped reasons instead. The reason property inside an
+			// AbortSignal is a readonly property and trying to set it would throw an error.
+			if (abortMessage && abortSignal.reason !== abortMessage) {
+				abortReason = abortMessage;
+			}
+		};
+
+		return { response: job(), cancel };
+	}
+}

package/src/utils/index.ts

@@ -0,0 +1,9 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+export { createCancellableOperation } from './createCancellableOperation';
+export { parseSigningInfo } from './parseSigningInfo';
+export { parseRestApiServiceError } from './serviceError';
+export { resolveApiUrl } from './resolveApiUrl';
+export { resolveLibraryOptions } from './resolveLibraryOptions';
+export { logger } from './logger';

package/src/utils/isIamAuthApplicable.ts

@@ -0,0 +1,44 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { HttpRequest } from '@aws-amplify/core/internals/aws-client-utils';
+
+import { SigningServiceInfo } from '../types';
+
+/**
+ * Determines if IAM authentication should be applied for a GraphQL request.
+ *
+ * This function checks the `headers` of the HTTP request to determine if IAM authentication
+ * is applicable. IAM authentication is considered applicable if there is no `authorization`
+ * header, no `x-api-key` header, and `signingServiceInfo` is provided.
+ *
+ * @param request - The HTTP request object containing headers.
+ * @param signingServiceInfo - Optional signing service information,
+ * including service and region.
+ * @returns A boolean `true` if IAM authentication should be applied.
+ *
+ * @internal
+ */
+export const isIamAuthApplicableForGraphQL = (
+	{ headers }: HttpRequest,
+	signingServiceInfo?: SigningServiceInfo,
+) => !headers.authorization && !headers['x-api-key'] && !!signingServiceInfo;
+
+/**
+ * Determines if IAM authentication should be applied for a REST request.
+ *
+ * This function checks the `headers` of the HTTP request to determine if IAM authentication
+ * is applicable. IAM authentication is considered applicable if there is no `authorization`
+ * header and `signingServiceInfo` is provided.
+ *
+ * @param request - The HTTP request object containing headers.
+ * @param signingServiceInfo - Optional signing service information,
+ * including service and region.
+ * @returns A boolean `true` if IAM authentication should be applied.
+ *
+ * @internal
+ */
+export const isIamAuthApplicableForRest = (
+	{ headers }: HttpRequest,
+	signingServiceInfo?: SigningServiceInfo,
+) => !headers.authorization && !!signingServiceInfo;

package/src/utils/logger.ts

@@ -0,0 +1,6 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { ConsoleLogger } from '@aws-amplify/core';
+
+export const logger = new ConsoleLogger('RestApis');

package/src/utils/parseSigningInfo.ts

@@ -0,0 +1,53 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { AmplifyClassV6 } from '@aws-amplify/core';
+
+import {
+	APIG_HOSTNAME_PATTERN,
+	DEFAULT_IAM_SIGNING_REGION,
+	DEFAULT_REST_IAM_SIGNING_SERVICE,
+} from './constants';
+
+/**
+ * Infer the signing service and region from the given URL, and for REST API only, from the Amplify configuration.
+ * It supports raw API Gateway endpoint and AppSync endpoint.
+ *
+ * @internal
+ */
+export const parseSigningInfo = (
+	url: URL,
+	restApiOptions?: {
+		amplify: AmplifyClassV6;
+		apiName: string;
+	},
+) => {
+	const {
+		service: signingService = DEFAULT_REST_IAM_SIGNING_SERVICE,
+		region: signingRegion = DEFAULT_IAM_SIGNING_REGION,
+	} =
+		restApiOptions?.amplify.getConfig()?.API?.REST?.[restApiOptions?.apiName] ??
+		{};
+	const { hostname } = url;
+	const [, service, region] = APIG_HOSTNAME_PATTERN.exec(hostname) ?? [];
+	if (service === DEFAULT_REST_IAM_SIGNING_SERVICE) {
+		// The configured endpoint is an API Gateway endpoint
+		// @see: https://docs.aws.amazon.com/apigateway/latest/developerguide/how-to-call-api.html
+		return {
+			service,
+			region: region ?? signingRegion,
+		};
+	} else if (service === 'appsync-api') {
+		// AppSync endpoint is internally supported because GraphQL operation will send request using POST handler.
+		// example: https://xxxx.appsync-api.us-east-1.amazonaws.com/graphql
+		return {
+			service: 'appsync',
+			region: region ?? signingRegion,
+		};
+	} else {
+		return {
+			service: signingService,
+			region: signingRegion,
+		};
+	}
+};

package/src/utils/resolveApiUrl.ts

@@ -0,0 +1,59 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { AmplifyClassV6 } from '@aws-amplify/core';
+import {
+	AmplifyUrl,
+	AmplifyUrlSearchParams,
+} from '@aws-amplify/core/internals/utils';
+
+import {
+	RestApiError,
+	RestApiValidationErrorCode,
+	assertValidationError,
+	validationErrorMap,
+} from '../errors';
+
+/**
+ * Resolve the REST API request URL by:
+ * 1. Loading the REST API endpoint from the Amplify configuration with corresponding API name.
+ * 2. Appending the path to the endpoint.
+ * 3. Merge the query parameters from path and the queryParameter argument which is taken from the public REST API
+ *   options.
+ * 4. Validating the resulting URL string.
+ *
+ * @internal
+ */
+export const resolveApiUrl = (
+	amplify: AmplifyClassV6,
+	apiName: string,
+	path: string,
+	queryParams?: Record<string, string>,
+): URL => {
+	const urlStr = amplify.getConfig()?.API?.REST?.[apiName]?.endpoint;
+	assertValidationError(!!urlStr, RestApiValidationErrorCode.InvalidApiName);
+	try {
+		let url: URL;
+		if (AmplifyUrl.canParse(urlStr + path)) {
+			url = new AmplifyUrl(urlStr + path);
+		} else {
+			url = new AmplifyUrl(urlStr + path, location?.origin);
+		}
+
+		if (queryParams) {
+			const mergedQueryParams = new AmplifyUrlSearchParams(url.searchParams);
+			Object.entries(queryParams).forEach(([key, value]) => {
+				mergedQueryParams.set(key, value);
+			});
+			url.search = new AmplifyUrlSearchParams(mergedQueryParams).toString();
+		}
+
+		return url;
+	} catch (error) {
+		throw new RestApiError({
+			name: RestApiValidationErrorCode.InvalidApiName,
+			...validationErrorMap[RestApiValidationErrorCode.InvalidApiName],
+			recoverySuggestion: `Please make sure the REST endpoint URL is a valid URL string. Got ${urlStr}`,
+		});
+	}
+};

package/src/utils/resolveHeaders.ts

@@ -0,0 +1,36 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+export const resolveHeaders = (
+	headers?: Record<string, string>,
+	body?: unknown,
+) => {
+	const normalizedHeaders: Record<string, string> = {};
+	for (const key in headers) {
+		normalizedHeaders[key.toLowerCase()] = headers[key];
+	}
+	if (body) {
+		const contentType = normalizedHeaders['content-type'];
+		const isJsonCompatible =
+			contentType &&
+			(contentType.startsWith('application/json') ||
+				(contentType.startsWith('application/') &&
+					contentType.includes('+json')));
+
+		if (!isJsonCompatible) {
+			normalizedHeaders['content-type'] = 'application/json; charset=UTF-8';
+		}
+
+		if (body instanceof FormData) {
+			/**
+			 * If body is a FormData we should not allow setting content-type.
+			 * It's because runtime HTTP handlers(xhr, fetch, undici, node-fetch,
+			 * etc.) will modify the content-type value when setting multipart
+			 * boundary.
+			 */
+			delete normalizedHeaders['content-type'];
+		}
+	}
+
+	return normalizedHeaders;
+};

package/src/utils/resolveLibraryOptions.ts

@@ -0,0 +1,14 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { AmplifyClassV6 } from '@aws-amplify/core';
+
+/**
+ * @internal
+ */
+export const resolveLibraryOptions = (amplify: AmplifyClassV6) => {
+	const retryStrategy = amplify.libraryOptions?.API?.REST?.retryStrategy;
+	const defaultAuthMode = amplify.libraryOptions?.API?.REST?.defaultAuthMode;
+
+	return { retryStrategy, defaultAuthMode };
+};

package/src/utils/serviceError.ts

@@ -0,0 +1,109 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+import { MetadataBearer } from '@aws-sdk/types';
+import {
+	HttpResponse,
+	parseJsonError as parseAwsJsonError,
+} from '@aws-amplify/core/internals/aws-client-utils';
+import { ApiErrorResponse } from '@aws-amplify/core/internals/utils';
+
+import { RestApiError } from '../errors';
+
+/**
+ * Parses both AWS and non-AWS error responses coming from the users' backend code.
+ * * AWS errors generated by the AWS services(e.g. API Gateway, Bedrock). They can be Signature errors,
+ *   ClockSkew errors, etc. These responses will be parsed to errors with proper name and message from the AWS
+ *   services.
+ * * non-AWS errors thrown by the user code. They can contain any headers or body. Users need to access the
+ *   error.response to get the headers and body and parse them accordingly. The JS error name and message will
+ *   be `UnknownError` and `Unknown error` respectively.
+ */
+export const parseRestApiServiceError = async (
+	response?: HttpResponse,
+): Promise<(RestApiError & MetadataBearer) | undefined> => {
+	if (!response) {
+		// Response is not considered an error.
+		return;
+	}
+	const parsedAwsError = await parseAwsJsonError(stubErrorResponse(response));
+	if (!parsedAwsError) {
+		// Response is not considered an error.
+	} else {
+		const bodyText = await response.body?.text();
+
+		return buildRestApiError(parsedAwsError, {
+			statusCode: response.statusCode,
+			headers: response.headers,
+			body: bodyText,
+		});
+	}
+};
+
+/**
+ * The response object needs to be stub here because the parseAwsJsonError assumes the response body to be valid JSON.
+ * Although this is true for AWS services, it is not true for responses from user's code. Once the response body is
+ * unwrapped as JSON(and fail), it cannot be read as text again. Therefore, we need to stub the response body here to
+ * make sure we can read the error response body as a JSON, and may fall back to read as text if it is not a valid JSON.
+ */
+const stubErrorResponse = (response: HttpResponse): HttpResponse => {
+	let bodyTextPromise: Promise<string> | undefined;
+	const bodyProxy = new Proxy(response.body, {
+		get(target, prop, receiver) {
+			if (prop === 'json') {
+				// For potential AWS errors, error parser will try to parse the body as JSON first.
+				return async () => {
+					if (!bodyTextPromise) {
+						bodyTextPromise = target.text();
+					}
+					try {
+						return JSON.parse(await bodyTextPromise!);
+					} catch (error) {
+						// If response body is not a valid JSON, we stub it to be an empty object and eventually parsed
+						// as an unknown error
+						return {};
+					}
+				};
+			} else if (prop === 'text') {
+				// For non-AWS errors, users can access the body as a string as a fallback.
+				return async () => {
+					if (!bodyTextPromise) {
+						bodyTextPromise = target.text();
+					}
+
+					return bodyTextPromise;
+				};
+			} else {
+				return Reflect.get(target, prop, receiver);
+			}
+		},
+	});
+	const responseProxy = new Proxy(response, {
+		get(target, prop, receiver) {
+			if (prop === 'body') {
+				return bodyProxy;
+			} else {
+				return Reflect.get(target, prop, receiver);
+			}
+		},
+	});
+
+	return responseProxy;
+};
+
+/**
+ * Utility to create a new RestApiError from a service error.
+ */
+const buildRestApiError = (
+	error: Error & MetadataBearer,
+	response?: ApiErrorResponse,
+): RestApiError & MetadataBearer => {
+	const restApiError = new RestApiError({
+		name: error?.name,
+		message: error.message,
+		underlyingError: error,
+		response,
+	});
+
+	// $metadata is only required for backwards compatibility.
+	return Object.assign(restApiError, { $metadata: error.$metadata });
+};