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

package/src/GraphQLAPI.ts

@@ -0,0 +1,97 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+import { AmplifyClassV6 } from '@aws-amplify/core';
+import {
+	ApiAction,
+	Category,
+	CustomUserAgentDetails,
+} from '@aws-amplify/core/internals/utils';
+import {
+	CustomHeaders,
+	INTERNAL_USER_AGENT_OVERRIDE,
+} from '@aws-amplify/data-schema/runtime';
+import { Observable } from 'rxjs';
+
+import { GraphQLOptions, GraphQLResult } from './types';
+import { InternalGraphQLAPIClass } from './internals/InternalGraphQLAPI';
+
+function isGraphQLOptionsWithOverride(
+	options: GraphQLOptions,
+): options is GraphQLOptions & {
+	[INTERNAL_USER_AGENT_OVERRIDE]: CustomUserAgentDetails;
+} {
+	return INTERNAL_USER_AGENT_OVERRIDE in options;
+}
+
+export const graphqlOperation = (
+	query: any,
+	variables = {},
+	authToken?: string,
+) => ({
+	query,
+	variables,
+	authToken,
+});
+
+/**
+ * Export Cloud Logic APIs
+ */
+export class GraphQLAPIClass extends InternalGraphQLAPIClass {
+	public getModuleName() {
+		return 'GraphQLAPI';
+	}
+
+	/**
+	 * Executes a GraphQL operation
+	 *
+	 * @param options - GraphQL Options
+	 * @param [additionalHeaders] - headers to merge in after any `libraryConfigHeaders` set in the config
+	 * @returns An Observable if the query is a subscription query, else a promise of the graphql result.
+	 */
+	graphql<T = any>(
+		amplify: AmplifyClassV6 | (() => Promise<AmplifyClassV6>),
+		options: GraphQLOptions,
+		additionalHeaders?: CustomHeaders,
+	): Observable<GraphQLResult<T>> | Promise<GraphQLResult<T>> {
+		const userAgentDetails: CustomUserAgentDetails = {
+			category: Category.API,
+			action: ApiAction.GraphQl,
+		};
+
+		if (isGraphQLOptionsWithOverride(options)) {
+			const {
+				[INTERNAL_USER_AGENT_OVERRIDE]: internalUserAgentOverride,
+				...cleanOptions
+			} = options;
+
+			return super.graphql(amplify, cleanOptions, additionalHeaders, {
+				...userAgentDetails,
+				...internalUserAgentOverride,
+			});
+		}
+
+		return super.graphql(amplify, options, additionalHeaders, {
+			...userAgentDetails,
+		});
+	}
+
+	/**
+	 * Checks to see if an error thrown is from an api request cancellation
+	 * @param error - Any error
+	 * @returns A boolean indicating if the error was from an api request cancellation
+	 */
+	isCancelError(error: any): boolean {
+		return super.isCancelError(error);
+	}
+
+	/**
+	 * Cancels an inflight request. Only applicable for graphql queries and mutations
+	 * @param {any} request - request to cancel
+	 * @returns A boolean indicating if the request was cancelled
+	 */
+	cancel(request: Promise<any>, message?: string): boolean {
+		return super.cancel(request, message);
+	}
+}
+
+export const GraphQLAPI = new GraphQLAPIClass();

package/src/Providers/AWSAppSyncEventsProvider/index.ts

@@ -0,0 +1,218 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+import {
+	CustomUserAgentDetails,
+	DocumentType,
+	GraphQLAuthMode,
+	USER_AGENT_HEADER,
+	getAmplifyUserAgent,
+} from '@aws-amplify/core/internals/utils';
+import { CustomHeaders } from '@aws-amplify/data-schema/runtime';
+
+import { DEFAULT_KEEP_ALIVE_TIMEOUT, MESSAGE_TYPES } from '../constants';
+import { AWSWebSocketProvider } from '../AWSWebSocketProvider';
+import { awsRealTimeHeaderBasedAuth } from '../AWSWebSocketProvider/authHeaders';
+import { serializeEvents } from '../../internals/events/utils';
+
+// resolved/actual AuthMode values. identityPool gets resolves to IAM upstream in InternalGraphQLAPI._graphqlSubscribe
+type ResolvedGraphQLAuthModes = Exclude<GraphQLAuthMode, 'identityPool'>;
+
+interface AWSAppSyncEventProviderOptions {
+	appSyncGraphqlEndpoint?: string;
+	authenticationType?: ResolvedGraphQLAuthModes;
+	query?: string;
+	variables?: DocumentType;
+	apiKey?: string;
+	region?: string;
+	libraryConfigHeaders?(): Promise<Record<string, unknown> | Headers>;
+	additionalHeaders?: CustomHeaders;
+	additionalCustomHeaders?: Record<string, string>;
+	authToken?: string;
+}
+
+interface DataPayload {
+	id: string;
+	event: string;
+	type: string;
+}
+
+interface DataResponse {
+	id: string;
+	payload: string;
+	type: string;
+}
+
+const PROVIDER_NAME = 'AWSAppSyncEventsProvider';
+const WS_PROTOCOL_NAME = 'aws-appsync-event-ws';
+const CONNECT_URI = ''; // events does not expect a connect uri
+
+export class AWSAppSyncEventProvider extends AWSWebSocketProvider {
+	constructor() {
+		super({
+			providerName: PROVIDER_NAME,
+			wsProtocolName: WS_PROTOCOL_NAME,
+			connectUri: CONNECT_URI,
+		});
+		this.allowNoSubscriptions = true;
+	}
+
+	getProviderName() {
+		return PROVIDER_NAME;
+	}
+
+	public async connect(options: AWSAppSyncEventProviderOptions) {
+		return super.connect(options);
+	}
+
+	public subscribe(
+		options?: AWSAppSyncEventProviderOptions,
+		customUserAgentDetails?: CustomUserAgentDetails,
+	) {
+		return super.subscribe(options, customUserAgentDetails).pipe();
+	}
+
+	public async publish(
+		options: AWSAppSyncEventProviderOptions,
+		customUserAgentDetails?: CustomUserAgentDetails,
+	) {
+		return super.publish(options, customUserAgentDetails);
+	}
+
+	public closeIfNoActiveSubscription() {
+		this._closeSocketIfRequired();
+	}
+
+	protected async _prepareSubscriptionPayload({
+		options,
+		subscriptionId,
+		customUserAgentDetails,
+		additionalCustomHeaders,
+		libraryConfigHeaders,
+		publish,
+	}: {
+		options: AWSAppSyncEventProviderOptions;
+		subscriptionId: string;
+		customUserAgentDetails: CustomUserAgentDetails | undefined;
+		additionalCustomHeaders: Record<string, string>;
+		libraryConfigHeaders: Record<string, string>;
+		publish?: boolean;
+	}): Promise<string> {
+		const {
+			appSyncGraphqlEndpoint,
+			authenticationType,
+			query,
+			apiKey,
+			region,
+			variables,
+		} = options;
+
+		const data = {
+			channel: query,
+			events: variables !== undefined ? serializeEvents(variables) : undefined,
+		};
+		const serializedData = JSON.stringify(data);
+
+		const headers = {
+			...(await awsRealTimeHeaderBasedAuth({
+				apiKey,
+				appSyncGraphqlEndpoint,
+				authenticationType,
+				payload: serializedData,
+				canonicalUri: '',
+				region,
+				additionalCustomHeaders,
+			})),
+			...libraryConfigHeaders,
+			...additionalCustomHeaders,
+			[USER_AGENT_HEADER]: getAmplifyUserAgent(customUserAgentDetails),
+		};
+
+		const subscriptionMessage = {
+			id: subscriptionId,
+			channel: query,
+			events: variables !== undefined ? serializeEvents(variables) : undefined,
+			authorization: {
+				...headers,
+			},
+			payload: {
+				events:
+					variables !== undefined ? serializeEvents(variables) : undefined,
+				channel: query,
+				extensions: {
+					authorization: {
+						...headers,
+					},
+				},
+			},
+			type: publish
+				? MESSAGE_TYPES.EVENT_PUBLISH
+				: MESSAGE_TYPES.EVENT_SUBSCRIBE,
+		};
+
+		const serializedSubscriptionMessage = JSON.stringify(subscriptionMessage);
+
+		return serializedSubscriptionMessage;
+	}
+
+	protected _handleSubscriptionData(
+		message: MessageEvent,
+	): [boolean, DataResponse] {
+		this.logger.debug(
+			`subscription message from AWS AppSync Events: ${message.data}`,
+		);
+
+		const {
+			id = '',
+			event: payload,
+			type,
+		}: DataPayload = JSON.parse(String(message.data));
+
+		const {
+			observer = null,
+			query = '',
+			variables = {},
+		} = this.subscriptionObserverMap.get(id) || {};
+
+		this.logger.debug({ id, observer, query, variables });
+
+		if (type === MESSAGE_TYPES.DATA && payload) {
+			const deserializedEvent = JSON.parse(payload);
+			if (observer) {
+				observer.next({ id, type, event: deserializedEvent });
+			} else {
+				this.logger.debug(`observer not found for id: ${id}`);
+			}
+
+			return [true, { id, type, payload: deserializedEvent }];
+		}
+
+		return [false, { id, type, payload }];
+	}
+
+	protected _unsubscribeMessage(subscriptionId: string): {
+		id: string;
+		type: string;
+	} {
+		return {
+			id: subscriptionId,
+			type: MESSAGE_TYPES.EVENT_STOP,
+		};
+	}
+
+	protected _extractConnectionTimeout(data: Record<string, any>): number {
+		const { connectionTimeoutMs = DEFAULT_KEEP_ALIVE_TIMEOUT } = data;
+
+		return connectionTimeoutMs;
+	}
+
+	protected _extractErrorCodeAndType(data: Record<string, any>): {
+		errorCode: number;
+		errorType: string;
+	} {
+		const { errors: [{ errorType = '', errorCode = 0 } = {}] = [] } = data;
+
+		return { errorCode, errorType };
+	}
+}
+
+export const AppSyncEventProvider = new AWSAppSyncEventProvider();

package/src/Providers/AWSAppSyncRealTimeProvider/index.ts

@@ -0,0 +1,185 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import {
+	CustomUserAgentDetails,
+	DocumentType,
+	GraphQLAuthMode,
+	USER_AGENT_HEADER,
+	getAmplifyUserAgent,
+} from '@aws-amplify/core/internals/utils';
+import { CustomHeaders } from '@aws-amplify/data-schema/runtime';
+
+import { DEFAULT_KEEP_ALIVE_TIMEOUT, MESSAGE_TYPES } from '../constants';
+import { AWSWebSocketProvider } from '../AWSWebSocketProvider';
+import { awsRealTimeHeaderBasedAuth } from '../AWSWebSocketProvider/authHeaders';
+
+// resolved/actual AuthMode values. identityPool gets resolves to IAM upstream in InternalGraphQLAPI._graphqlSubscribe
+type ResolvedGraphQLAuthModes = Exclude<GraphQLAuthMode, 'identityPool'>;
+
+export interface AWSAppSyncRealTimeProviderOptions {
+	appSyncGraphqlEndpoint?: string;
+	authenticationType?: ResolvedGraphQLAuthModes;
+	query?: string;
+	variables?: DocumentType;
+	apiKey?: string;
+	region?: string;
+	libraryConfigHeaders?(): Promise<Record<string, unknown> | Headers>;
+	additionalHeaders?: CustomHeaders;
+	additionalCustomHeaders?: Record<string, string>;
+	authToken?: string;
+}
+
+interface DataObject extends Record<string, unknown> {
+	data: Record<string, unknown>;
+}
+
+interface DataPayload {
+	id: string;
+	payload: DataObject;
+	type: string;
+}
+
+const PROVIDER_NAME = 'AWSAppSyncRealTimeProvider';
+const WS_PROTOCOL_NAME = 'graphql-ws';
+const CONNECT_URI = '/connect';
+
+export class AWSAppSyncRealTimeProvider extends AWSWebSocketProvider {
+	constructor() {
+		super({
+			providerName: PROVIDER_NAME,
+			wsProtocolName: WS_PROTOCOL_NAME,
+			connectUri: CONNECT_URI,
+		});
+	}
+
+	getProviderName() {
+		return PROVIDER_NAME;
+	}
+
+	public subscribe(
+		options?: AWSAppSyncRealTimeProviderOptions,
+		customUserAgentDetails?: CustomUserAgentDetails,
+	) {
+		return super.subscribe(options, customUserAgentDetails);
+	}
+
+	protected async _prepareSubscriptionPayload({
+		options,
+		subscriptionId,
+		customUserAgentDetails,
+		additionalCustomHeaders,
+		libraryConfigHeaders,
+	}: {
+		options: AWSAppSyncRealTimeProviderOptions;
+		subscriptionId: string;
+		customUserAgentDetails: CustomUserAgentDetails | undefined;
+		additionalCustomHeaders: Record<string, string>;
+		libraryConfigHeaders: Record<string, string>;
+	}): Promise<string> {
+		const {
+			appSyncGraphqlEndpoint,
+			authenticationType,
+			query,
+			variables,
+			apiKey,
+			region,
+		} = options;
+		const data = {
+			query,
+			variables,
+		};
+		const serializedData = JSON.stringify(data);
+
+		const headers = {
+			...(await awsRealTimeHeaderBasedAuth({
+				apiKey,
+				appSyncGraphqlEndpoint,
+				authenticationType,
+				payload: serializedData,
+				canonicalUri: '',
+				region,
+				additionalCustomHeaders,
+			})),
+			...libraryConfigHeaders,
+			...additionalCustomHeaders,
+			[USER_AGENT_HEADER]: getAmplifyUserAgent(customUserAgentDetails),
+		};
+
+		const subscriptionMessage = {
+			id: subscriptionId,
+			payload: {
+				data: serializedData,
+				extensions: {
+					authorization: {
+						...headers,
+					},
+				},
+			},
+			type: MESSAGE_TYPES.GQL_START,
+		};
+
+		const serializedSubscriptionMessage = JSON.stringify(subscriptionMessage);
+
+		return serializedSubscriptionMessage;
+	}
+
+	protected _handleSubscriptionData(
+		message: MessageEvent,
+	): [boolean, DataPayload] {
+		this.logger.debug(
+			`subscription message from AWS AppSync RealTime: ${message.data}`,
+		);
+
+		const { id = '', payload, type } = JSON.parse(String(message.data));
+
+		const {
+			observer = null,
+			query = '',
+			variables = {},
+		} = this.subscriptionObserverMap.get(id) || {};
+
+		this.logger.debug({ id, observer, query, variables });
+
+		if (type === MESSAGE_TYPES.DATA && payload && payload.data) {
+			if (observer) {
+				observer.next(payload);
+			} else {
+				this.logger.debug(`observer not found for id: ${id}`);
+			}
+
+			return [true, { id, type, payload }];
+		}
+
+		return [false, { id, type, payload }];
+	}
+
+	protected _unsubscribeMessage(subscriptionId: string): {
+		id: string;
+		type: string;
+	} {
+		return {
+			id: subscriptionId,
+			type: MESSAGE_TYPES.GQL_STOP,
+		};
+	}
+
+	protected _extractConnectionTimeout(data: Record<string, any>): number {
+		const {
+			payload: { connectionTimeoutMs = DEFAULT_KEEP_ALIVE_TIMEOUT } = {},
+		} = data;
+
+		return connectionTimeoutMs;
+	}
+
+	protected _extractErrorCodeAndType(data: any): {
+		errorCode: number;
+		errorType: string;
+	} {
+		const {
+			payload: { errors: [{ errorType = '', errorCode = 0 } = {}] = [] } = {},
+		} = data;
+
+		return { errorCode, errorType };
+	}
+}

package/src/Providers/AWSWebSocketProvider/appsyncUrl.ts

@@ -0,0 +1,152 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { RequestOptions } from '@aws-amplify/data-schema/runtime';
+import {
+	AmplifyUrl,
+	AmplifyUrlSearchParams,
+} from '@aws-amplify/core/internals/utils';
+
+import { AWSAppSyncRealTimeProviderOptions } from '../AWSAppSyncRealTimeProvider';
+
+const protocol = 'wss://';
+const standardDomainPattern =
+	/^https:\/\/\w{26}\.appsync-api\.\w{2}(?:(?:-\w{2,})+)-\d\.amazonaws.com(?:\.cn)?\/graphql$/i;
+const eventDomainPattern =
+	/^https:\/\/\w{26}\.\w+-api\.\w{2}(?:(?:-\w{2,})+)-\d\.amazonaws.com(?:\.cn)?\/event$/i;
+const customDomainPath = '/realtime';
+
+export const isCustomDomain = (url: string): boolean => {
+	return url.match(standardDomainPattern) === null;
+};
+
+const isEventDomain = (url: string): boolean =>
+	url.match(eventDomainPattern) !== null;
+
+export const getRealtimeEndpointUrl = (
+	appSyncGraphqlEndpoint: string | undefined,
+): URL => {
+	let realtimeEndpoint = appSyncGraphqlEndpoint ?? '';
+
+	if (isEventDomain(realtimeEndpoint)) {
+		realtimeEndpoint = realtimeEndpoint
+			.concat(customDomainPath)
+			.replace('ddpg-api', 'grt-gamma')
+			.replace('appsync-api', 'appsync-realtime-api');
+	} else if (isCustomDomain(realtimeEndpoint)) {
+		realtimeEndpoint = realtimeEndpoint.concat(customDomainPath);
+	} else {
+		realtimeEndpoint = realtimeEndpoint
+			.replace('appsync-api', 'appsync-realtime-api')
+			.replace('gogi-beta', 'grt-beta')
+			.replace('ddpg-api', 'grt-gamma');
+	}
+
+	realtimeEndpoint = realtimeEndpoint
+		.replace('https://', protocol)
+		.replace('http://', protocol);
+
+	return new AmplifyUrl(realtimeEndpoint);
+};
+
+/**
+ * Strips out `Authorization` header if present
+ */
+const extractNonAuthHeaders = (
+	headers?: AWSAppSyncRealTimeProviderOptions['additionalCustomHeaders'],
+): Record<string, string> => {
+	if (!headers) {
+		return {};
+	}
+
+	if ('Authorization' in headers) {
+		const { Authorization: _, ...nonAuthHeaders } = headers;
+
+		return nonAuthHeaders;
+	}
+
+	return headers;
+};
+
+/**
+ *
+ * @param headers - http headers
+ * @returns uri-encoded query parameters derived from custom headers
+ */
+export const queryParamsFromCustomHeaders = (
+	headers?: AWSAppSyncRealTimeProviderOptions['additionalCustomHeaders'],
+): URLSearchParams => {
+	const nonAuthHeaders = extractNonAuthHeaders(headers);
+
+	const params = new AmplifyUrlSearchParams();
+
+	Object.entries(nonAuthHeaders).forEach(([k, v]) => {
+		params.append(k, v);
+	});
+
+	return params;
+};
+
+/**
+ * Normalizes AppSync realtime endpoint URL
+ *
+ * @param appSyncGraphqlEndpoint - AppSync endpointUri from config
+ * @param urlParams - URLSearchParams
+ * @returns fully resolved string realtime endpoint URL
+ */
+export const realtimeUrlWithQueryString = (
+	appSyncGraphqlEndpoint: string | undefined,
+	urlParams: URLSearchParams,
+): string => {
+	const realtimeEndpointUrl = getRealtimeEndpointUrl(appSyncGraphqlEndpoint);
+
+	// preserves any query params a customer might manually set in the configuration
+	const existingParams = new AmplifyUrlSearchParams(realtimeEndpointUrl.search);
+
+	for (const [k, v] of urlParams.entries()) {
+		existingParams.append(k, v);
+	}
+
+	realtimeEndpointUrl.search = existingParams.toString();
+
+	return realtimeEndpointUrl.toString();
+};
+
+// TODO: move to separate file?
+export const additionalHeadersFromOptions = async (
+	options: AWSAppSyncRealTimeProviderOptions,
+) => {
+	const {
+		appSyncGraphqlEndpoint,
+		query,
+		libraryConfigHeaders = () => ({}),
+		additionalHeaders = {},
+		authToken,
+	} = options;
+
+	let additionalCustomHeaders = {};
+	const _libraryConfigHeaders = await libraryConfigHeaders();
+
+	if (typeof additionalHeaders === 'function') {
+		const requestOptions: RequestOptions = {
+			url: appSyncGraphqlEndpoint || '',
+			queryString: query || '',
+		};
+		additionalCustomHeaders = await additionalHeaders(requestOptions);
+	} else {
+		additionalCustomHeaders = additionalHeaders;
+	}
+
+	// if an authorization header is set, have the explicit, operation-level authToken take precedence
+	if (authToken) {
+		additionalCustomHeaders = {
+			...additionalCustomHeaders,
+			Authorization: authToken,
+		};
+	}
+
+	return {
+		additionalCustomHeaders,
+		libraryConfigHeaders: _libraryConfigHeaders,
+	};
+};