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

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,199 @@
+// 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, amplifyUuid } 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,
+	ProviderOptions,
+	PublishResponse,
+	PublishedEvent,
+	SubscriptionObserver,
+} from './types';
+
+// Keeps a list of open channels in the websocket
+const openChannels = new Set<string>();
+
+/**
+ * @experimental API may change in future versions
+ *
+ * Establish a WebSocket connection to an Events channel
+ *
+ * @example
+ * const channel = await events.connect("default/channel")
+ *
+ * channel.subscribe({
+ *   next: (data) => { console.log(data) },
+ *   error: (err) => { console.error(err) },
+ * })
+ *
+ * @example // authMode override
+ * const channel = await events.connect("default/channel", { authMode: "userPool" })
+ *
+ * @param channel - channel path; `<namespace>/<channel>`
+ * @param options - request overrides: `authMode`, `authToken`
+ *
+ */
+async function connect(
+	channel: string,
+	options?: EventsOptions,
+): Promise<EventsChannel> {
+	const providerOptions: ProviderOptions = configure();
+
+	providerOptions.authenticationType = normalizeAuth(
+		options?.authMode,
+		providerOptions.authenticationType,
+	);
+	providerOptions.apiKey = options?.apiKey || providerOptions.apiKey;
+	providerOptions.authToken = options?.authToken || providerOptions.authToken;
+
+	await eventProvider.connect(providerOptions);
+
+	const channelId = amplifyUuid();
+	openChannels.add(channelId);
+
+	let _subscription: Subscription;
+
+	const sub = (
+		observer: SubscriptionObserver<any>,
+		subOptions?: EventsOptions,
+	): Subscription => {
+		if (!openChannels.has(channelId)) {
+			throw new Error('Channel is closed');
+		}
+		const subscribeOptions = { ...providerOptions, query: channel };
+		subscribeOptions.authenticationType = normalizeAuth(
+			subOptions?.authMode,
+			subscribeOptions.authenticationType,
+		);
+		subscribeOptions.apiKey = subOptions?.apiKey || subscribeOptions.apiKey;
+		subscribeOptions.authToken =
+			subOptions?.authToken || subscribeOptions.authToken;
+
+		_subscription = eventProvider
+			.subscribe(subscribeOptions)
+			.subscribe(observer);
+
+		return _subscription;
+	};
+
+	const pub = async (
+		event: DocumentType,
+		pubOptions?: EventsOptions,
+	): Promise<any> => {
+		if (!openChannels.has(channelId)) {
+			throw new Error('Channel is closed');
+		}
+		const publishOptions = {
+			...providerOptions,
+			query: channel,
+			variables: event,
+		};
+		publishOptions.authenticationType = normalizeAuth(
+			pubOptions?.authMode,
+			publishOptions.authenticationType,
+		);
+		publishOptions.apiKey = pubOptions?.apiKey || publishOptions.apiKey;
+		publishOptions.authToken =
+			pubOptions?.authToken || publishOptions.authToken;
+
+		return eventProvider.publish(publishOptions);
+	};
+
+	const close = async () => {
+		_subscription && _subscription.unsubscribe();
+		openChannels.delete(channelId);
+		setTimeout(() => {
+			if (openChannels.size === 0) {
+				eventProvider.closeIfNoActiveSubscription();
+			}
+		}, 1000);
+	};
+
+	return {
+		subscribe: sub,
+		close,
+		publish: pub,
+	};
+}
+
+/**
+ * @experimental API may change in future versions
+ *
+ * Publish events to a channel via HTTP request
+ *
+ * @example
+ * await events.post("default/channel", { some: "event" })
+ *
+ * @example // event batching
+ * await events.post("default/channel", [{ some: "event" }, { some: "event2" }])
+ *
+ * @example // authMode override
+ * await events.post("default/channel", { some: "event" }, { authMode: "userPool" })
+ *
+ * @param channel - channel path; `<namespace>/<channel>`
+ * @param event - JSON-serializable value or an array of values
+ * @param options - request overrides: `authMode`, `authToken`
+ *
+ * @returns void on success
+ * @throws on error
+ */
+async function post(
+	channel: string,
+	event: DocumentType | DocumentType[],
+	options?: EventsOptions,
+): Promise<void | PublishedEvent[]> {
+	const providerOptions: ProviderOptions = configure();
+	providerOptions.authenticationType = normalizeAuth(
+		options?.authMode,
+		providerOptions.authenticationType,
+	);
+	providerOptions.apiKey = options?.apiKey || providerOptions.apiKey;
+	providerOptions.authToken = options?.authToken || providerOptions.authToken;
+
+	// trailing slash required in publish
+	const normalizedChannelName = channel[0] === '/' ? channel : `/${channel}`;
+
+	const publishOptions = {
+		...providerOptions,
+		query: normalizedChannelName,
+		variables: serializeEvents(event),
+	};
+
+	const abortController = new AbortController();
+
+	const res = await appsyncRequest<PublishResponse>(
+		Amplify,
+		publishOptions,
+		{},
+		abortController,
+	);
+
+	if (res.failed?.length > 0) {
+		return res.failed;
+	}
+}
+
+/**
+ * @experimental API may change in future versions
+ *
+ * Close WebSocket connection, disconnect listeners and reconnect observers
+ *
+ * @example
+ * await events.closeAll()
+ *
+ * @returns void on success
+ * @throws on error
+ */
+async function closeAll(): Promise<void> {
+	await eventProvider.close();
+}
+
+export { connect, post, closeAll };

package/src/internals/events/types.ts

@@ -0,0 +1,109 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { Subscription } from 'rxjs';
+import type {
+	DocumentType,
+	GraphQLAuthMode,
+} from '@aws-amplify/core/internals/utils';
+
+export interface SubscriptionObserver<T> {
+	next(value: T): void;
+	error(errorValue: any): void;
+}
+
+export interface EventsChannel {
+	/**
+	 * @experimental API may change in future versions
+	 *
+	 * Subscribe to Events
+	 *
+	 * @example
+	 * const channel = await events.connect("default/channel")
+	 *
+	 * channel.subscribe({
+	 *   next: (data) => { console.log(data) },
+	 *   error: (err) => { console.error(err) },
+	 * })
+	 *
+	 * @example // authMode override
+	 * channel.subscribe({
+	 *   next: (data) => { console.log(data) },
+	 *   error: (err) => { console.error(err) },
+	 * }, { authMode: 'userPool' })
+	 *
+	 * @param observer - observer callback handlers
+	 * `{ next: () => {}, error: () => {}}`
+	 *
+	 * @param options - subscribe overrides: `authMode`, `authToken`
+	 *
+	 */
+	subscribe(
+		observer: SubscriptionObserver<any>,
+		subOptions?: EventsOptions,
+	): Subscription;
+	/**
+	 * @experimental API may change in future versions
+	 *
+	 * Publish events to a channel via WebSocket
+	 *
+	 * @example
+	 * const channel = await events.connect("default/channel")
+	 *
+	 * await channel.publish({ some: "data" });
+	 *
+	 * @example // event batching
+	 * await channel.publish("default/channel", [{ some: "event" }, { some: "event2" }])
+	 *
+	 * @example // authMode override
+	 * await channel.publish({ some: "data" }, { authMode: "userPool" });
+	 *
+	 * @param event - JSON-serializable value or an array of values
+	 * @param pubOptions - request overrides: `authMode`, `authToken`
+	 *
+	 * @returns void on success
+	 * @throws on error
+	 */
+	publish(event: DocumentType, pubOptions?: EventsOptions): Promise<any>;
+	/**
+	 * @experimental API may change in future versions
+	 *
+	 * Close channel and any active subscriptions
+	 *
+	 * @example
+	 * const channel = await events.connect("default/channel")
+	 *
+	 * channel.close()
+	 *
+	 */
+	close(): void;
+}
+
+export type ResolvedGraphQLAuthModes = Exclude<GraphQLAuthMode, 'identityPool'>;
+
+export interface EventsOptions {
+	authMode?: GraphQLAuthMode;
+	authToken?: string;
+	apiKey?: string;
+}
+
+export interface PublishedEvent {
+	identifier: string;
+	index: number;
+}
+
+export interface PublishResponse {
+	failed: PublishedEvent[];
+	successful: PublishedEvent[];
+}
+
+interface EventsConfigure {
+	appSyncGraphqlEndpoint: string;
+	region?: string;
+	authenticationType: ResolvedGraphQLAuthModes;
+	apiKey?: string;
+}
+
+export type ProviderOptions = EventsConfigure & {
+	authToken?: string;
+};

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 an 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];
+};

package/src/internals/generateClient.ts

@@ -0,0 +1,120 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+import { Hub } from '@aws-amplify/core';
+import {
+	CustomMutations,
+	CustomQueries,
+	CustomSubscriptions,
+	EnumTypes,
+	ModelTypes,
+	addSchemaToClient,
+} from '@aws-amplify/data-schema/runtime';
+
+import {
+	V6Client,
+	__amplify,
+	__apiKey,
+	__authMode,
+	__authToken,
+	__endpoint,
+	__headers,
+	getInternals,
+} from '../types';
+
+import { isApiGraphQLConfig } from './utils/runtimeTypeGuards/isApiGraphQLProviderConfig';
+import { isConfigureEventWithResourceConfig } from './utils/runtimeTypeGuards/isConfigureEventWithResourceConfig';
+import { cancel, graphql, isCancelError } from './v6';
+import { ClientGenerationParams } from './types';
+
+/**
+ * @private
+ *
+ * Creates a client that can be used to make GraphQL requests, using a provided `AmplifyClassV6`
+ * compatible context object for config and auth fetching.
+ *
+ * @param params
+ * @returns
+ */
+export function generateClient<
+	T extends Record<any, any> = never,
+	Options extends ClientGenerationParams = ClientGenerationParams,
+>(params: Options): V6Client<T, Options> {
+	const client = {
+		[__amplify]: params.amplify,
+		[__authMode]: params.authMode,
+		[__authToken]: params.authToken,
+		[__apiKey]: 'apiKey' in params ? params.apiKey : undefined,
+		[__endpoint]: 'endpoint' in params ? params.endpoint : undefined,
+		[__headers]: params.headers,
+		graphql,
+		cancel,
+		isCancelError,
+		models: emptyProperty as ModelTypes<never>,
+		enums: emptyProperty as EnumTypes<never>,
+		queries: emptyProperty as CustomQueries<never>,
+		mutations: emptyProperty as CustomMutations<never>,
+		subscriptions: emptyProperty as CustomSubscriptions<never>,
+	} as any;
+
+	const apiGraphqlConfig = params.amplify.getConfig().API?.GraphQL;
+
+	if (client[__endpoint]) {
+		if (!client[__authMode]) {
+			throw new Error(
+				'generateClient() requires an explicit `authMode` when `endpoint` is provided.',
+			);
+		}
+		if (client[__authMode] === 'apiKey' && !client[__apiKey]) {
+			throw new Error(
+				"generateClient() requires an explicit `apiKey` when `endpoint` is provided and `authMode = 'apiKey'`.",
+			);
+		}
+	}
+
+	if (!client[__endpoint]) {
+		if (isApiGraphQLConfig(apiGraphqlConfig)) {
+			addSchemaToClient(client, apiGraphqlConfig, getInternals);
+		} else {
+			// This happens when the `Amplify.configure()` call gets evaluated after the `generateClient()` call.
+			//
+			// Cause: when the `generateClient()` and the `Amplify.configure()` calls are located in
+			// different source files, script bundlers may randomly arrange their orders in the production
+			// bundle.
+			//
+			// With the current implementation, the `client.models` instance created by `generateClient()`
+			// will be rebuilt on every `Amplify.configure()` call that's provided with a valid GraphQL
+			// provider configuration.
+			//
+			// TODO: revisit, and reverify this approach when enabling multiple clients for multi-endpoints
+			// configuration.
+			generateModelsPropertyOnAmplifyConfigure(client);
+		}
+	}
+
+	return client as any;
+}
+
+const generateModelsPropertyOnAmplifyConfigure = (clientRef: any) => {
+	Hub.listen('core', coreEvent => {
+		if (!isConfigureEventWithResourceConfig(coreEvent.payload)) {
+			return;
+		}
+
+		const apiGraphQLConfig = coreEvent.payload.data.API?.GraphQL;
+
+		if (isApiGraphQLConfig(apiGraphQLConfig)) {
+			addSchemaToClient(clientRef, apiGraphQLConfig, getInternals);
+		}
+	});
+};
+
+const emptyProperty = new Proxy(
+	{},
+	{
+		get() {
+			throw new Error(
+				'Client could not be generated. This is likely due to `Amplify.configure()` not being called prior to `generateClient()` or because the configuration passed to `Amplify.configure()` is missing GraphQL provider configuration.',
+			);
+		},
+	},
+);