@aws-amplify/api-graphql 4.4.1 → 4.4.2-events.538dd9f.0

package/src/Providers/constants.ts

@@ -36,9 +36,9 @@ export enum MESSAGE_TYPES {
 	GQL_START_ACK = 'start_ack',
 	/**
 	 * Server -> Client message.
-	 * This message type is for subscription message from AWS AppSync RealTime
+	 * This message type is for subscription message from AWS AppSync RealTime or Events
 	 */
-	GQL_DATA = 'data',
+	DATA = 'data',
 	/**
 	 * Server -> Client message.
 	 * This message type helps the client to know is still receiving messages from AWS AppSync RealTime
@@ -59,6 +59,36 @@ export enum MESSAGE_TYPES {
 	 * This message type is for sending error messages from AWS AppSync RealTime to the client
 	 */
 	GQL_ERROR = 'error', // Server -> Client
+	/**
+	 * Client -> Server message.
+	 * This message type is for registering subscriptions with Events
+	 */
+	EVENT_SUBSCRIBE = 'subscribe',
+	/**
+	 * Client -> Server message.
+	 * This message type is for publishing a message with Events
+	 */
+	EVENT_PUBLISH = 'publish',
+	/**
+	 * Server -> Client message.
+	 * Server acknowledges successful subscription
+	 */
+	EVENT_SUBSCRIBE_ACK = 'subscribe_success',
+	/**
+	 * Server -> Client message.
+	 * Server acknowledges successful publish
+	 */
+	EVENT_PUBLISH_ACK = 'publish_success',
+	/**
+	 * Client -> Server message.
+	 * This message type is for unregister subscriptions with AWS AppSync RealTime
+	 */
+	EVENT_STOP = 'unsubscribe',
+	/**
+	 * Server -> Client message.
+	 * This is the ack response from AWS AppSync Events to EVENT_STOP message
+	 */
+	EVENT_COMPLETE = 'unsubscribe_success',
 }
 
 export enum SUBSCRIPTION_STATUS {

package/src/index.ts

@@ -1,7 +1,12 @@
 // Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
 // SPDX-License-Identifier: Apache-2.0
 
+import * as events from './internals/events';
+
+export { events };
+
 export { GraphQLAPI, GraphQLAPIClass, graphqlOperation } from './GraphQLAPI';
 export * from './types';
 
 export { CONNECTION_STATE_CHANGE } from './Providers/constants';
+export * from './internals/events/types';

package/src/internals/InternalGraphQLAPI.ts

@@ -12,7 +12,6 @@ import { AmplifyClassV6 } from '@aws-amplify/core';
 import {
 	AmplifyUrl,
 	CustomUserAgentDetails,
-	GraphQLAuthMode,
 	getAmplifyUserAgent,
 } from '@aws-amplify/core/internals/utils';
 import { isCancelError as isCancelErrorREST } from '@aws-amplify/api-rest';
@@ -30,17 +29,11 @@ import { AWSAppSyncRealTimeProvider } from '../Providers/AWSAppSyncRealTimeProvi
 import { GraphQLOperation, GraphQLOptions, GraphQLResult } from '../types';
 import { resolveConfig, resolveLibraryOptions } from '../utils';
 import { repackageUnauthorizedError } from '../utils/errors/repackageAuthError';
-import {
-	NO_API_KEY,
-	NO_AUTH_TOKEN_HEADER,
-	NO_ENDPOINT,
-	NO_SIGNED_IN_USER,
-	NO_VALID_AUTH_TOKEN,
-	NO_VALID_CREDENTIALS,
-} from '../utils/errors/constants';
+import { NO_ENDPOINT } from '../utils/errors/constants';
 import { GraphQLApiError, createGraphQLResultWithError } from '../utils/errors';
 
 import { isGraphQLResponseWithErrors } from './utils/runtimeTypeGuards/isGraphQLResponseWithErrors';
+import { headerBasedAuth } from './graphqlAuth';
 
 const USER_AGENT_HEADER = 'x-amz-user-agent';
 
@@ -72,80 +65,6 @@ export class InternalGraphQLAPIClass {
 		return 'InternalGraphQLAPI';
 	}
 
-	private async _headerBasedAuth(
-		amplify: AmplifyClassV6,
-		authMode: GraphQLAuthMode,
-		additionalHeaders: Record<string, string> = {},
-	) {
-		const { apiKey } = resolveConfig(amplify);
-
-		let headers = {};
-
-		switch (authMode) {
-			case 'apiKey':
-				if (!apiKey) {
-					throw new GraphQLApiError(NO_API_KEY);
-				}
-				headers = {
-					'X-Api-Key': apiKey,
-				};
-				break;
-			case 'iam': {
-				const session = await amplify.Auth.fetchAuthSession();
-				if (session.credentials === undefined) {
-					throw new GraphQLApiError(NO_VALID_CREDENTIALS);
-				}
-				break;
-			}
-			case 'oidc':
-			case 'userPool': {
-				let token: string | undefined;
-
-				try {
-					token = (
-						await amplify.Auth.fetchAuthSession()
-					).tokens?.accessToken.toString();
-				} catch (e) {
-					// fetchAuthSession failed
-					throw new GraphQLApiError({
-						...NO_SIGNED_IN_USER,
-						underlyingError: e,
-					});
-				}
-
-				// `fetchAuthSession()` succeeded but didn't return `tokens`.
-				// This may happen when unauthenticated access is enabled and there is
-				// no user signed in.
-				if (!token) {
-					throw new GraphQLApiError(NO_VALID_AUTH_TOKEN);
-				}
-
-				headers = {
-					Authorization: token,
-				};
-				break;
-			}
-			case 'lambda':
-				if (
-					typeof additionalHeaders === 'object' &&
-					!additionalHeaders.Authorization
-				) {
-					throw new GraphQLApiError(NO_AUTH_TOKEN_HEADER);
-				}
-
-				headers = {
-					Authorization: additionalHeaders.Authorization,
-				};
-				break;
-			case 'none':
-				break;
-			default:
-				break;
-		}
-
-		return headers;
-	}
-
 	/**
 	 * to get the operation type
 	 * @param operation
@@ -252,6 +171,7 @@ export class InternalGraphQLAPIClass {
 		authToken?: string,
 	): Promise<GraphQLResult<T>> {
 		const {
+			apiKey,
 			region,
 			endpoint: appSyncGraphqlEndpoint,
 			customEndpoint,
@@ -303,29 +223,22 @@ export class InternalGraphQLAPIClass {
 			};
 		}
 
-		// TODO: Figure what we need to do to remove `!`'s.
+		const authHeaders = await headerBasedAuth(
+			amplify,
+			authMode,
+			apiKey,
+			additionalCustomHeaders,
+		);
+
 		const headers = {
-			...(!customEndpoint &&
-				(await this._headerBasedAuth(
-					amplify,
-					authMode!,
-					additionalCustomHeaders,
-				))),
+			...(!customEndpoint && authHeaders),
 			/**
 			 * Custom endpoint headers.
 			 * If there is both a custom endpoint and custom region present, we get the headers.
 			 * If there is a custom endpoint but no region, we return an empty object.
 			 * If neither are present, we return an empty object.
 			 */
-			...((customEndpoint &&
-				(customEndpointRegion
-					? await this._headerBasedAuth(
-							amplify,
-							authMode!,
-							additionalCustomHeaders,
-						)
-					: {})) ||
-				{}),
+			...((customEndpoint && (customEndpointRegion ? authHeaders : {})) || {}),
 			// Custom headers included in Amplify configuration options:
 			...(customHeaders &&
 				(await customHeaders({
@@ -378,9 +291,9 @@ export class InternalGraphQLAPIClass {
 		let response: any;
 
 		try {
-			// See the inline doc of the REST `post()` API for possible errors to be thrown.
-			// As these errors are catastrophic they should be caught and handled by GraphQL
-			// API consumers.
+			// 	// // See the inline doc of the REST `post()` API for possible errors to be thrown.
+			// 	// // As these errors are catastrophic they should be caught and handled by GraphQL
+			// 	// // API consumers.
 			const { body: responseBody } = await this._api.post(amplify, {
 				url: new AmplifyUrl(endpoint),
 				options: {

package/src/internals/events/appsyncRequest.ts

@@ -0,0 +1,169 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+import { AmplifyClassV6 } from '@aws-amplify/core';
+import {
+	AmplifyUrl,
+	CustomUserAgentDetails,
+	GraphQLAuthMode,
+	getAmplifyUserAgent,
+} from '@aws-amplify/core/internals/utils';
+import { post } from '@aws-amplify/api-rest/internals';
+import {
+	CustomHeaders,
+	RequestOptions,
+} from '@aws-amplify/data-schema/runtime';
+
+import { resolveLibraryOptions } from '../../utils';
+import { repackageUnauthorizedError } from '../../utils/errors/repackageAuthError';
+import { headerBasedAuth } from '../graphqlAuth';
+import { isGraphQLResponseWithErrors } from '../utils/runtimeTypeGuards/isGraphQLResponseWithErrors';
+
+const USER_AGENT_HEADER = 'x-amz-user-agent';
+
+interface GqlRequestOptions {
+	apiKey?: string;
+	region?: string;
+	appSyncGraphqlEndpoint: string;
+	authenticationType: GraphQLAuthMode;
+	query: string;
+	variables: string[];
+	authToken?: string;
+}
+
+// This is effectively a copy of InternalGraphQLAPI.ts._graphql(...)
+// Our existing unit tests are tightly coupled to the implementation, so i was unable to refactor
+// and extend _graphql() without having to change a bunch of tests as well... which in turn reduces confidence
+// that this feature will _not affect_ GQL behavior.
+export async function appsyncRequest<T = any>(
+	amplify: AmplifyClassV6,
+	options: GqlRequestOptions,
+	additionalHeaders: CustomHeaders = {},
+	abortController: AbortController,
+	customUserAgentDetails?: CustomUserAgentDetails,
+): Promise<T> {
+	const {
+		region,
+		appSyncGraphqlEndpoint: endpoint,
+		authenticationType: authMode,
+		query,
+		variables,
+	} = options;
+
+	if (!endpoint) {
+		throw new Error('No endpoint');
+	}
+
+	const { withCredentials } = resolveLibraryOptions(amplify);
+
+	const headers = await requestHeaders(
+		amplify,
+		options,
+		additionalHeaders,
+		customUserAgentDetails,
+	);
+
+	const body = {
+		channel: query as string,
+		events: variables,
+	};
+
+	const signingServiceInfo = ['apiKey', 'none'].includes(authMode)
+		? undefined
+		: {
+				service: 'appsync',
+				region,
+			};
+
+	const { body: responseBody } = await post(amplify, {
+		url: new AmplifyUrl(endpoint),
+		options: {
+			headers,
+			body,
+			signingServiceInfo,
+			withCredentials,
+		},
+		abortController,
+	});
+
+	const response = await responseBody.json();
+
+	if (isGraphQLResponseWithErrors(response)) {
+		throw repackageUnauthorizedError(response);
+	}
+
+	return response as T;
+}
+
+/**
+ * Computes all the necessary HTTP headers for the request based on:
+ * 1. Operation-level header options
+ * 2. Amplify.configure custom headers
+ * 3. AuthZ headers for explicit auth mode specified for operation ?? default auth mode in config
+ *
+ * @returns HTTP request headers key/value
+ */
+async function requestHeaders(
+	amplify: AmplifyClassV6,
+	options: GqlRequestOptions,
+	additionalHeaders: CustomHeaders,
+	customUserAgentDetails?: CustomUserAgentDetails,
+) {
+	const {
+		apiKey,
+		appSyncGraphqlEndpoint: endpoint,
+		authenticationType: authMode,
+		query,
+		variables,
+		authToken,
+	} = options;
+
+	const { headers: customHeadersFn } = resolveLibraryOptions(amplify);
+
+	let additionalCustomHeaders: Record<string, string>;
+
+	if (typeof additionalHeaders === 'function') {
+		const requestOptions: RequestOptions = {
+			method: 'POST',
+			url: new AmplifyUrl(endpoint).toString(),
+			queryString: query,
+		};
+
+		additionalCustomHeaders = await additionalHeaders(requestOptions);
+	} else {
+		additionalCustomHeaders = additionalHeaders;
+	}
+
+	// if an authorization header is set, have the operation-level authToken take precedence
+	if (authToken) {
+		additionalCustomHeaders = {
+			...additionalCustomHeaders,
+			Authorization: authToken,
+		};
+	}
+
+	const authHeaders = await headerBasedAuth(
+		amplify,
+		authMode,
+		apiKey,
+		additionalCustomHeaders,
+	);
+
+	const customHeaders =
+		customHeadersFn &&
+		(await customHeadersFn({
+			query,
+			variables: variables as any,
+		}));
+
+	const headers = {
+		...authHeaders,
+		// Custom headers included in Amplify configuration options:
+		...customHeaders,
+		// Custom headers from individual requests or API client configuration:
+		...additionalCustomHeaders,
+		// User agent headers:
+		[USER_AGENT_HEADER]: getAmplifyUserAgent(customUserAgentDetails),
+	};
+
+	return headers;
+}

package/src/internals/events/index.ts

@@ -0,0 +1,138 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { Subscription } from 'rxjs';
+import { Amplify } from '@aws-amplify/core';
+import { DocumentType } from '@aws-amplify/core/internals/utils';
+
+import { AppSyncEventProvider as eventProvider } from '../../Providers/AWSAppSyncEventsProvider';
+
+import { appsyncRequest } from './appsyncRequest';
+import { configure, normalizeAuth, serializeEvents } from './utils';
+import type {
+	EventsChannel,
+	EventsOptions,
+	PublishResponse,
+	PublishedEvent,
+	SubscriptionObserver,
+} from './types';
+
+/**
+ * Establish a WebSocket connection to an Events channel
+ *
+ */
+async function connect(
+	channelName: string,
+	options?: EventsOptions,
+): Promise<EventsChannel> {
+	const providerOptions = configure();
+
+	providerOptions.authenticationType = normalizeAuth(
+		options?.authMode,
+		providerOptions.authenticationType,
+	);
+
+	await eventProvider.connect(providerOptions);
+
+	let _subscription: Subscription;
+
+	const sub = (
+		observer: SubscriptionObserver<any>,
+		subOptions?: EventsOptions,
+	): Subscription => {
+		const subscribeOptions = { ...providerOptions, query: channelName };
+		subscribeOptions.authenticationType = normalizeAuth(
+			subOptions?.authMode,
+			subscribeOptions.authenticationType,
+		);
+
+		_subscription = eventProvider
+			.subscribe(subscribeOptions)
+			.subscribe(observer);
+
+		return _subscription;
+	};
+
+	// WS publish is not enabled in the service yet. It will be a follow up feature
+	const _pub = async (
+		event: DocumentType,
+		pubOptions?: EventsOptions,
+	): Promise<any> => {
+		const publishOptions = {
+			...providerOptions,
+			query: channelName,
+			variables: event,
+		};
+		publishOptions.authenticationType = normalizeAuth(
+			pubOptions?.authMode,
+			publishOptions.authenticationType,
+		);
+
+		return eventProvider.publish(publishOptions);
+	};
+
+	const close = () => {
+		_subscription && _subscription.unsubscribe();
+	};
+
+	return {
+		/**
+		 * Subscribe to incoming events
+		 */
+		subscribe: sub,
+		/**
+		 * Close channel and any active subscriptions
+		 */
+		close,
+		// publish: pub,
+	};
+}
+
+/**
+ * Publish events to a channel via REST request
+ *
+ * @param channelName - publish destination
+ * @param event - JSON-serializable value or an array of values
+ * @param options
+ */
+async function post(
+	channelName: string,
+	event: DocumentType | DocumentType[],
+	options?: EventsOptions,
+): Promise<void | PublishedEvent[]> {
+	const providerOptions = configure();
+	providerOptions.authenticationType = normalizeAuth(
+		options?.authMode,
+		providerOptions.authenticationType,
+	);
+
+	// trailing slash required in publish
+	const normalizedChannelName =
+		channelName[0] === '/' ? channelName : `/${channelName}`;
+
+	const publishOptions = {
+		...providerOptions,
+		query: normalizedChannelName,
+		variables: serializeEvents(event),
+		authToken: options?.authToken,
+	};
+
+	const abortController = new AbortController();
+
+	const res = await appsyncRequest<PublishResponse>(
+		Amplify,
+		publishOptions,
+		{},
+		abortController,
+	);
+
+	if (res.failed?.length > 0) {
+		return res.failed;
+	}
+}
+
+function closeAll(): void {
+	eventProvider.close();
+}
+
+export { connect, post, closeAll };

package/src/internals/events/types.ts

@@ -0,0 +1,35 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { Subscription } from 'rxjs';
+import type { GraphQLAuthMode } from '@aws-amplify/core/internals/utils';
+
+export interface SubscriptionObserver<T> {
+	next(value: T): void;
+	error(errorValue: any): void;
+}
+
+export interface EventsChannel {
+	subscribe(
+		observer: SubscriptionObserver<any>,
+		subOptions?: EventsOptions,
+	): Subscription;
+	close(): void;
+}
+
+export type ResolvedGraphQLAuthModes = Exclude<GraphQLAuthMode, 'identityPool'>;
+
+export interface EventsOptions {
+	authMode?: GraphQLAuthMode;
+	authToken?: string;
+}
+
+export interface PublishedEvent {
+	identifier: string;
+	index: number;
+}
+
+export interface PublishResponse {
+	failed: PublishedEvent[];
+	successful: PublishedEvent[];
+}

package/src/internals/events/utils.ts

@@ -0,0 +1,77 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+import { Amplify } from '@aws-amplify/core';
+import {
+	DocumentType,
+	GraphQLAuthMode,
+} from '@aws-amplify/core/internals/utils';
+
+import type { ResolvedGraphQLAuthModes } from './types';
+
+export const normalizeAuth = (
+	explicitAuthMode: GraphQLAuthMode | undefined,
+	defaultAuthMode: ResolvedGraphQLAuthModes,
+): ResolvedGraphQLAuthModes => {
+	if (!explicitAuthMode) {
+		return defaultAuthMode;
+	}
+
+	if (explicitAuthMode === 'identityPool') {
+		return 'iam';
+	}
+
+	return explicitAuthMode;
+};
+
+export const configure = () => {
+	const config = Amplify.getConfig();
+
+	const eventsConfig = config.API?.Events;
+
+	if (!eventsConfig) {
+		throw new Error(
+			'Amplify configuration is missing. Have you called Amplify.configure()?',
+		);
+	}
+
+	const configAuthMode = normalizeAuth(eventsConfig.defaultAuthMode, 'apiKey');
+
+	const options = {
+		appSyncGraphqlEndpoint: eventsConfig.endpoint,
+		region: eventsConfig.region,
+		authenticationType: configAuthMode,
+		apiKey: eventsConfig.apiKey,
+	};
+
+	return options;
+};
+
+/**
+ * Event API expects and array of JSON strings
+ *
+ * @param events - JSON-serializable value or an array of values
+ * @returns array of JSON strings
+ */
+export const serializeEvents = (
+	events: DocumentType | DocumentType[],
+): string[] => {
+	if (Array.isArray(events)) {
+		return events.map((ev, idx) => {
+			const eventJson = JSON.stringify(ev);
+			if (eventJson === undefined) {
+				throw new Error(
+					`Event must be a valid JSON value. Received ${ev} at index ${idx}`,
+				);
+			}
+
+			return eventJson;
+		});
+	}
+
+	const eventJson = JSON.stringify(events);
+	if (eventJson === undefined) {
+		throw new Error(`Event must be a valid JSON value. Received ${events}`);
+	}
+
+	return [eventJson];
+};