@aws-amplify/api-rest 3.5.6-unstable.7762f1a.0 → 4.0.0

package/src/internals/server.ts

@@ -0,0 +1,37 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+import {
+	AmplifyServer,
+	getAmplifyServerContext,
+} from '@aws-amplify/core/internals/adapter-core';
+
+import { post as internalPost } from '../apis/common/internalPost';
+import { InternalPostInput } from '../types';
+
+/**
+ * Internal-only REST POST handler to send GraphQL request to given endpoint. By default, it will use IAM to authorize
+ * the request. In some auth modes, the IAM auth has to be disabled. Here's how to set up the request auth correctly:
+ * * If auth mode is 'iam', you MUST NOT set 'authorization' header and 'x-api-key' header, since it would disable IAM
+ *   auth. You MUST also set 'input.options.signingServiceInfo' option.
+ *   * The including 'input.options.signingServiceInfo.service' and 'input.options.signingServiceInfo.region' are
+ *     optional. If omitted, the signing service and region will be inferred from url.
+ * * If auth mode is 'none', you MUST NOT set 'options.signingServiceInfo' option.
+ * * If auth mode is 'apiKey', you MUST set 'x-api-key' custom header.
+ * * If auth mode is 'oidc' or 'lambda' or 'userPool', you MUST set 'authorization' header.
+ *
+ * To make the internal post cancellable, you must also call `updateRequestToBeCancellable()` with the promise from
+ * internal post call and the abort controller supplied to the internal post call.
+ *
+ * @internal
+ */
+export const post = (
+	contextSpec: AmplifyServer.ContextSpec,
+	input: InternalPostInput
+) => {
+	return internalPost(getAmplifyServerContext(contextSpec).amplify, input);
+};
+
+export {
+	cancel,
+	updateRequestToBeCancellable,
+} from '../apis/common/internalPost';

package/src/server.ts

@@ -0,0 +1,5 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+export { isCancelError } from './errors/CanceledError';
+export { get, post, put, del, head, patch } from './apis/server';

package/src/types/index.ts

@@ -1,63 +1,114 @@
 // Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
 // SPDX-License-Identifier: Apache-2.0
+import { DocumentType } 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<Omit<RestApiOptionsBase, 'body'>>;
+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<Omit<RestApiResponse, 'body'>>;
+export type HeadOperation = Operation<Omit<RestApiResponse, 'body'>>;
 
 /**
- * RestClient instance options
+ * @internal
  */
-export class RestClientOptions {
-	/** AWS credentials */
-	credentials: AWSCredentials;
-
+export type RestApiOptionsBase = {
+	headers?: Headers;
+	queryParams?: Record<string, string>;
+	body?: DocumentType | FormData;
 	/**
-	 * Lookup key of AWS credentials.
-	 * If credentials not provided then lookup from sessionStorage.
-	 * Default 'awsCredentials'
+	 * 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}
 	 */
-	credentials_key: string;
+	withCredentials?: boolean;
+};
+
+type Headers = Record<string, string>;
+
+/**
+ * Type representing an operation that can be canceled.
+ *
+ * @internal
+ */
+export type Operation<Response> = {
+	response: Promise<Response>;
+	cancel: (abortMessage?: string) => void;
+};
 
-	/** Additional headers for all requests send by this client. e.g. user-agent */
-	headers: object;
+type ResponsePayload = {
+	blob: () => Promise<Blob>;
+	json: () => Promise<DocumentType>;
+	text: () => Promise<string>;
+};
 
-	constructor() {
-		this.credentials_key = 'awsCredentials';
-		this.headers = {};
-	}
+/**
+ * Basic response type of REST API.
+ *
+ * @internal
+ */
+export interface RestApiResponse {
+	body: ResponsePayload;
+	statusCode: number;
+	headers: Headers;
 }
 
 /**
- * AWS credentials needed for RestClient
+ * @internal
  */
-export class AWSCredentials {
+export type ApiInput<Options> = {
 	/**
-	 * Secret Access Key
-	 *
-	 * [Access Key ID and Secret Access Key]
-	 * (http://docs.aws.amazon.com/general/latest/gr/aws-sec-cred-types.html#access-keys-and-secret-access-keys)
+	 * Name of the REST API configured in Amplify singleton.
 	 */
-	secretAccessKey: string;
-
+	apiName: string;
 	/**
-	 * Access Key ID
-	 *
-	 * [Access Key ID and Secret Access Key]
-	 * (http://docs.aws.amazon.com/general/latest/gr/aws-sec-cred-types.html#access-keys-and-secret-access-keys)
+	 * Path of the REST API.
 	 */
-	accessKeyId: string;
-
-	/** Access Token of current session */
-	sessionToken: string;
-}
-
-// TODO: remove this once unauth creds are figured out
-export interface apiOptions {
-	headers: object;
-	endpoints: object;
-	credentials?: object;
-}
+	path: string;
+	/**
+	 * Options to overwrite the REST API call behavior.
+	 */
+	options?: Options;
+};
 
-export type ApiInfo = {
-	endpoint: string;
-	region?: string;
-	service?: string;
-	custom_header?: () => { [key: string]: string };
+/**
+ * Input type to invoke REST POST API from GraphQl client.
+ * @internal
+ */
+export type InternalPostInput = {
+	// Resolved GraphQl endpoint url
+	url: URL;
+	options?: RestApiOptionsBase & {
+		/**
+		 * 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;
 };

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,94 @@
+// 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
+): Promise<HttpResponse>;
+
+/**
+ * Create a cancellable operation conforming to the external REST API interface.
+ * @internal
+ */
+export function createCancellableOperation(
+	handler: (signal: AbortSignal) => Promise<HttpResponse>
+): Operation<HttpResponse>;
+
+/**
+ * @internal
+ */
+export function createCancellableOperation(
+	handler:
+		| ((signal: AbortSignal) => Promise<HttpResponse>)
+		| (() => Promise<HttpResponse>),
+	abortController?: AbortController
+): Operation<HttpResponse> | Promise<HttpResponse> {
+	const isInternalPost = (
+		handler:
+			| ((signal: AbortSignal) => Promise<HttpResponse>)
+			| (() => Promise<HttpResponse>)
+	): handler is () => Promise<HttpResponse> => !!abortController;
+
+	// For creating a cancellable operation for public REST APIs, we need to create an AbortController
+	// internally. Whereas for internal POST APIs, we need to accept in the AbortController from the
+	// callers.
+	const publicApisAbortController = new AbortController();
+	const publicApisAbortSignal = publicApisAbortController.signal;
+	const internalPostAbortSignal = abortController?.signal;
+
+	const job = async () => {
+		try {
+			const response = await (isInternalPost(handler)
+				? handler()
+				: handler(publicApisAbortSignal));
+
+			if (response.statusCode >= 300) {
+				throw await parseRestApiServiceError(response)!;
+			}
+			return response;
+		} catch (error: any) {
+			const abortSignal = internalPostAbortSignal ?? publicApisAbortSignal;
+			if (error.name === 'AbortError' || abortSignal?.aborted === true) {
+				const canceledError = new CanceledError({
+					...(abortSignal.reason ? { message: abortSignal.reason } : undefined),
+					underlyingError: error,
+				});
+				logger.debug(error);
+				throw canceledError;
+			}
+			logger.debug(error);
+			throw error;
+		}
+	};
+
+	if (isInternalPost(handler)) {
+		return job();
+	} else {
+		const cancel = (abortMessage?: string) => {
+			if (publicApisAbortSignal.aborted === true) {
+				return;
+			}
+			publicApisAbortController.abort(abortMessage);
+			// Abort reason is not widely support enough across runtimes and and browsers, so we set it
+			// if it is not already set.
+			if (abortMessage && publicApisAbortSignal.reason !== abortMessage) {
+				type AbortSignalWithReasonSupport = Omit<AbortSignal, 'reason'> & {
+					reason?: string;
+				};
+				(publicApisAbortSignal as AbortSignalWithReasonSupport)['reason'] =
+					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 { resolveCredentials } from './resolveCredentials';
+export { parseSigningInfo } from './parseSigningInfo';
+export { parseRestApiServiceError } from './serviceError';
+export { resolveApiUrl } from './resolveApiUrl';
+export { logger } from './logger';

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/normalizeHeaders.ts

@@ -0,0 +1,10 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+export const normalizeHeaders = (headers?: Record<string, string>) => {
+	const normalizedHeaders: Record<string, string> = {};
+	for (const key in headers) {
+		normalizedHeaders[key.toLowerCase()] = headers[key];
+	}
+	return normalizedHeaders;
+};

package/src/utils/parseSigningInfo.ts

@@ -0,0 +1,52 @@
+// 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,51 @@
+// 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 {
+		const url = new AmplifyUrl(urlStr + path);
+		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/resolveCredentials.ts

@@ -0,0 +1,17 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { AmplifyClassV6 } from '@aws-amplify/core';
+import { RestApiValidationErrorCode, assertValidationError } from '../errors';
+
+/**
+ * @internal
+ */
+export const resolveCredentials = async (amplify: AmplifyClassV6) => {
+	const { credentials } = await amplify.Auth.fetchAuthSession();
+	assertValidationError(
+		!!credentials && !!credentials.accessKeyId && !!credentials.secretAccessKey,
+		RestApiValidationErrorCode.NoCredentials
+	);
+	return credentials;
+};

package/src/utils/serviceError.ts

@@ -0,0 +1,35 @@
+// 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,
+} from '@aws-amplify/core/internals/aws-client-utils';
+import { RestApiError } from '../errors';
+
+/**
+ * Internal-only method to create a new RestApiError from a service error.
+ *
+ * @internal
+ */
+export const buildRestApiServiceError = (error: Error): RestApiError => {
+	const restApiError = new RestApiError({
+		name: error?.name,
+		message: error.message,
+		underlyingError: error,
+	});
+	return restApiError;
+};
+
+export const parseRestApiServiceError = async (
+	response?: HttpResponse
+): Promise<(RestApiError & MetadataBearer) | undefined> => {
+	const parsedError = await parseJsonError(response);
+	if (!parsedError) {
+		// Response is not an error.
+		return;
+	}
+	return Object.assign(buildRestApiServiceError(parsedError), {
+		$metadata: parsedError.$metadata,
+	});
+};

package/lib/.tsbuildinfo

@@ -1,3 +0,0 @@
-{
-  "version": "3.8.3"
-}

package/lib/RestAPI.d.ts

@@ -1,108 +0,0 @@
-/**
- * Export Cloud Logic APIs
- */
-export declare class RestAPIClass {
-    /**
-     * @private
-     */
-    private _options;
-    private _api;
-    Credentials: import("@aws-amplify/core").CredentialsClass;
-    /**
-     * Initialize Rest API with AWS configuration
-     * @param {Object} options - Configuration object for API
-     */
-    constructor(options: any);
-    getModuleName(): string;
-    /**
-     * Configure API part with aws configurations
-     * @param {Object} config - Configuration of the API
-     * @return {Object} - The current configuration
-     */
-    configure(options: any): any;
-    /**
-     * Create an instance of API for the library
-     * @return - A promise of true if Success
-     */
-    createInstance(): boolean;
-    /**
-     * Make a GET request
-     * @param {string} apiName - The api name of the request
-     * @param {string} path - The path of the request
-     * @param {json} [init] - Request extra params
-     * @return {Promise} - A promise that resolves to an object with response status and JSON data, if successful.
-     */
-    get(apiName: any, path: any, init: any): Promise<any>;
-    /**
-     * Make a POST request
-     * @param {string} apiName - The api name of the request
-     * @param {string} path - The path of the request
-     * @param {json} [init] - Request extra params
-     * @return {Promise} - A promise that resolves to an object with response status and JSON data, if successful.
-     */
-    post(apiName: any, path: any, init: any): Promise<any>;
-    /**
-     * Make a PUT request
-     * @param {string} apiName - The api name of the request
-     * @param {string} path - The path of the request
-     * @param {json} [init] - Request extra params
-     * @return {Promise} - A promise that resolves to an object with response status and JSON data, if successful.
-     */
-    put(apiName: any, path: any, init: any): Promise<any>;
-    /**
-     * Make a PATCH request
-     * @param {string} apiName - The api name of the request
-     * @param {string} path - The path of the request
-     * @param {json} [init] - Request extra params
-     * @return {Promise} - A promise that resolves to an object with response status and JSON data, if successful.
-     */
-    patch(apiName: any, path: any, init: any): Promise<any>;
-    /**
-     * Make a DEL request
-     * @param {string} apiName - The api name of the request
-     * @param {string} path - The path of the request
-     * @param {json} [init] - Request extra params
-     * @return {Promise} - A promise that resolves to an object with response status and JSON data, if successful.
-     */
-    del(apiName: any, path: any, init: any): Promise<any>;
-    /**
-     * Make a HEAD request
-     * @param {string} apiName - The api name of the request
-     * @param {string} path - The path of the request
-     * @param {json} [init] - Request extra params
-     * @return {Promise} - A promise that resolves to an object with response status and JSON data, if successful.
-     */
-    head(apiName: any, path: any, init: any): Promise<any>;
-    /**
-     * Checks to see if an error thrown is from an api request cancellation
-     * @param {any} error - Any error
-     * @return {boolean} - A boolean indicating if the error was from an api request cancellation
-     */
-    isCancel(error: any): boolean;
-    /**
-     * Cancels an inflight request
-     * @param {any} request - request to cancel
-     * @return {boolean} - A boolean indicating if the request was cancelled
-     */
-    cancel(request: Promise<any>, message?: string): boolean;
-    /**
-     * Check if the request has a corresponding cancel token in the WeakMap.
-     * @params request - The request promise
-     * @return if the request has a corresponding cancel token.
-     */
-    hasCancelToken(request: Promise<any>): boolean;
-    /**
-     * Getting endpoint for API
-     * @param {string} apiName - The name of the api
-     * @return {string} - The endpoint of the api
-     */
-    endpoint(apiName: any): Promise<string>;
-    /**
-     * Getting endpoint info for API
-     * @param {string} apiName - The name of the api
-     * @param {string} path - The path of the api that is going to accessed
-     * @return {ApiInfo} - The endpoint information for that api-name
-     */
-    private getEndpointInfo;
-}
-export declare const RestAPI: RestAPIClass;