@prismicio/simulator 0.1.0

package/src/channel/ChannelEmitter.ts

@@ -0,0 +1,278 @@
+import {
+	ExtractSuccessResponseMessage,
+	InternalEmitterRequestType,
+	InternalEmitterTransactions,
+	InternalReceiverRequestType,
+	SuccessResponseMessage,
+	TransactionsHandlers,
+	UnknownRequestMessage,
+	UnknownResponseMessage,
+	UnknownTransaction,
+} from "./types";
+
+import {
+	ChannelNotSetError,
+	ConnectionTimeoutError,
+	NotReadyError,
+} from "./errors";
+
+import {
+	ChannelNetwork,
+	ChannelNetworkOptions,
+	PostRequestOptions,
+} from "./ChannelNetwork";
+import { AllChannelReceiverOptions } from "./ChannelReceiver";
+import {
+	createErrorResponseMessage,
+	createSuccessResponseMessage,
+	isRequestMessage,
+	validateMessage,
+} from "./messages";
+
+export type ChannelEmitterOptions = {
+	connectTimeout: number;
+};
+
+export const channelEmitterDefaultOptions: ChannelEmitterOptions &
+	Partial<ChannelNetworkOptions> = {
+	connectTimeout: 20000,
+	requestIDPrefix: "emitter-",
+};
+
+export type AllChannelEmitterOptions = ChannelEmitterOptions &
+	ChannelNetworkOptions;
+
+export abstract class ChannelEmitter<
+	TReceiverTransactions extends Record<string, UnknownTransaction> = Record<
+		string,
+		never
+	>,
+	TOptions extends Record<string, unknown> = Record<string, unknown>,
+	TReceiverOptions extends Record<string, unknown> = Record<string, unknown>,
+> extends ChannelNetwork<
+	TReceiverTransactions,
+	ChannelEmitterOptions & TOptions
+> {
+	private _target: HTMLIFrameElement;
+	private _channel: MessageChannel | null = null;
+	protected get channel(): MessageChannel {
+		if (!this._channel) {
+			throw new ChannelNotSetError();
+		}
+
+		return this._channel;
+	}
+	protected set channel(channel: MessageChannel | null) {
+		this._channel = channel;
+
+		// Update port automatically
+		if (this._channel) {
+			this.port = this._channel.port1;
+		} else {
+			this.port = null;
+		}
+	}
+	private _receiverReady = "";
+	private _receiverReadyCallback: (() => Promise<void>) | null = null;
+	private _connected = false;
+	public get connected(): boolean {
+		return this._connected;
+	}
+
+	constructor(
+		target: HTMLIFrameElement,
+		requestHandlers: TransactionsHandlers<TReceiverTransactions>,
+		options: Partial<AllChannelEmitterOptions> & TOptions,
+	) {
+		super(requestHandlers, { ...channelEmitterDefaultOptions, ...options });
+
+		this._target = target;
+
+		window.addEventListener("message", (event) => {
+			this._onPublicMessage(event);
+		});
+	}
+
+	/**
+	 * Initiates connection to receiver
+	 *
+	 * @param receiverOptions - Options to configure the receiver with
+	 * @param newOrigin - Indicates to the emitter that we're connecting to a new
+	 *   origin
+	 *
+	 * @returns Success connect message
+	 */
+	connect(
+		receiverOptions: InternalEmitterTransactions<
+			AllChannelReceiverOptions & TReceiverOptions
+		>["connect"]["request"]["data"] = {},
+		newOrigin = false,
+	): Promise<SuccessResponseMessage> {
+		// Disconnect first
+		this.disconnect();
+		// If changing origin we'll need to wait for receiver to be ready again
+		if (newOrigin) {
+			this._receiverReady = "";
+		}
+
+		// Handshake promise
+		return new Promise<SuccessResponseMessage>((resolve, reject) => {
+			// Wait for target to be loaded
+			this._target.addEventListener(
+				"load",
+				() => {
+					// Throw if target doesn't allow access to content window
+					if (!this._target.contentWindow) {
+						return reject(new Error("Target window is not available"));
+					}
+
+					const receiverReadyTimeout = setTimeout(() => {
+						reject(new ConnectionTimeoutError());
+					}, this.options.connectTimeout);
+
+					// Connect to target once ready
+					const receiverReadyCallback = async (): Promise<void> => {
+						// Clear receiver ready timeout
+						clearTimeout(receiverReadyTimeout);
+
+						// Create new message channel (set up port automatically)
+						// This is done here to prevent transferable objects neutering
+						// when calling `connect()` multiple times
+						this.channel = new MessageChannel();
+
+						// Conclude handshake by sending message channel port to target
+						const request = this.createRequestMessage(
+							InternalEmitterRequestType.Connect,
+							receiverOptions,
+						);
+						const response = await this.postRequest<
+							InternalEmitterTransactions<
+								AllChannelReceiverOptions & TReceiverOptions
+							>["connect"]["request"],
+							InternalEmitterTransactions<
+								AllChannelReceiverOptions & TReceiverOptions
+							>["connect"]["response"]
+						>(request, (request) => {
+							// Target content window is checked in previous statement
+							// eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+							this._target.contentWindow!.postMessage(request, "*", [
+								this.channel.port2,
+							]);
+						});
+
+						// Finish by aknowledging ready
+						this.postResponse(
+							createSuccessResponseMessage(this._receiverReady, undefined),
+							(response) => {
+								// Target content window is checked in previous statement
+								// eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+								this._target.contentWindow!.postMessage(response, "*");
+							},
+						);
+
+						// If post request succeed, we're connected
+						this._connected = true;
+
+						resolve(response);
+					};
+
+					if (this._receiverReady) {
+						// If receiver is already ready, send port immediately
+						receiverReadyCallback();
+					} else {
+						// Else wait for receiver to be ready
+						this._receiverReadyCallback = receiverReadyCallback;
+					}
+				},
+				{ once: true },
+			);
+		});
+	}
+
+	/**
+	 * Destroys current connection to receiver if any
+	 */
+	disconnect(): void {
+		this._connected = false;
+		this.channel = null;
+	}
+
+	/**
+	 * Handles public messages
+	 */
+	private async _onPublicMessage(event: MessageEvent<unknown>): Promise<void> {
+		// Return is event is not from target
+		if (event.source !== this._target.contentWindow) {
+			return;
+		}
+
+		try {
+			const message = validateMessage(event.data);
+
+			if (isRequestMessage(message)) {
+				if (this.options.debug) {
+					// eslint-disable-next-line no-console
+					console.debug(event.data);
+				}
+
+				switch (message.type) {
+					case InternalReceiverRequestType.Ready:
+						this._receiverReady = message.requestID;
+
+						// If emitter is waiting for receiver to be ready
+						if (this._receiverReadyCallback) {
+							// We don't await the promise directly as we need to clear the callback first
+							const receiverReadyCallbackPromise =
+								this._receiverReadyCallback();
+
+							this._receiverReadyCallback = null;
+
+							await receiverReadyCallbackPromise;
+						}
+						break;
+
+					default:
+						this.postResponse(
+							createErrorResponseMessage(message.requestID, undefined),
+							(response) => {
+								(event.source as WindowProxy).postMessage(
+									response,
+									event.origin,
+								);
+							},
+						);
+						break;
+				}
+			} else {
+				// No response messages are expected on public channel
+			}
+		} catch (error) {
+			if (error instanceof TypeError) {
+				// Ignore unknown messages
+			} else {
+				throw error;
+			}
+		}
+	}
+
+	protected postFormattedRequest<
+		TRequest extends UnknownRequestMessage,
+		TResponse extends UnknownResponseMessage,
+	>(
+		type: TRequest["type"],
+		data?: TRequest["data"],
+		options: PostRequestOptions = {},
+	): Promise<ExtractSuccessResponseMessage<TResponse>> {
+		if (!this._connected) {
+			throw new NotReadyError(
+				"Emitter is not connected, use `ChannelEmitter.connect()` first",
+			);
+		}
+
+		return this.postRequest(
+			this.createRequestMessage(type, data),
+			undefined,
+			options,
+		);
+	}
+}

package/src/channel/ChannelNetwork.ts

@@ -0,0 +1,216 @@
+import {
+	ExtractErrorResponseMessage,
+	ExtractSuccessResponseMessage,
+	RequestMessage,
+	TransactionsHandlers,
+	UnknownRequestMessage,
+	UnknownResponseMessage,
+	UnknownTransaction,
+} from "./types";
+
+import {
+	PortNotSetError,
+	RequestTimeoutError,
+	ResponseError,
+	TooManyConcurrentRequestsError,
+} from "./errors";
+
+import {
+	createErrorResponseMessage,
+	createRequestMessage,
+	createSuccessResponseMessage,
+	isRequestMessage,
+	isSuccessResponseMessage,
+	validateMessage,
+} from "./messages";
+
+export type PostRequestOptions = {
+	timeout?: number;
+};
+
+export type ChannelNetworkOptions = {
+	debug: boolean;
+	maximumRequestConcurrency: number;
+	defaultTimeout: number;
+	requestIDPrefix: string;
+};
+
+export const channelNetworkDefaultOptions: ChannelNetworkOptions = {
+	debug: false,
+	maximumRequestConcurrency: 20,
+	defaultTimeout: 5000,
+	requestIDPrefix: "channel-",
+};
+
+export abstract class ChannelNetwork<
+	TPartnerTransactions extends Record<string, UnknownTransaction> = Record<
+		string,
+		never
+	>,
+	TOptions extends Record<string, unknown> = Record<string, unknown>,
+> {
+	public requestHandlers: TransactionsHandlers<TPartnerTransactions>;
+	public options: ChannelNetworkOptions & TOptions;
+
+	private _port: MessagePort | null = null;
+	protected get port(): MessagePort {
+		if (!this._port) {
+			throw new PortNotSetError();
+		}
+
+		return this._port;
+	}
+	protected set port(port: MessagePort | null) {
+		// Destroy old port
+		if (this._port) {
+			this._port.onmessage = null;
+		}
+
+		this._port = port;
+		if (this._port) {
+			this._port.onmessage = this.onMessage.bind(this);
+		}
+	}
+
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any
+	private _pendingRequests: Map<string, (response: any) => void> = new Map();
+
+	constructor(
+		requestHandlers: TransactionsHandlers<TPartnerTransactions>,
+		options: Partial<ChannelNetworkOptions> & TOptions,
+	) {
+		this.requestHandlers = requestHandlers;
+		this.options = { ...channelNetworkDefaultOptions, ...options };
+	}
+
+	public createRequestMessage<TType extends string = string, TData = undefined>(
+		type: TType,
+		data: TData,
+	): RequestMessage<TType, TData> {
+		return createRequestMessage(type, data, this.options.requestIDPrefix);
+	}
+
+	protected async onMessage(event: MessageEvent<unknown>): Promise<void> {
+		if (this.options.debug) {
+			// eslint-disable-next-line no-console
+			console.debug(event.data);
+		}
+
+		try {
+			const message = validateMessage(event.data);
+
+			if (isRequestMessage(message)) {
+				if (!this.requestHandlers[message.type]) {
+					this.postResponse(
+						createErrorResponseMessage(message.requestID, undefined, 501),
+					);
+				} else {
+					try {
+						// TODO: Figure out why type cannot be inferred on its own anymore
+						const response = await this.requestHandlers[message.type](message, {
+							success: createSuccessResponseMessage.bind(
+								this,
+								message.requestID,
+							) as Parameters<
+								(typeof this.requestHandlers)[string]
+							>[1]["success"],
+							error: createErrorResponseMessage.bind(
+								this,
+								message.requestID,
+							) as Parameters<
+								(typeof this.requestHandlers)[string]
+							>[1]["error"],
+						});
+
+						this.postResponse(response);
+					} catch (error) {
+						this.postResponse(
+							createErrorResponseMessage(message.requestID, error, 500),
+						);
+					}
+				}
+			} else {
+				if (!this._pendingRequests.has(message.requestID)) {
+					console.error(
+						`Unknown request ID received in response: ${JSON.stringify(
+							message,
+						)}`,
+					);
+				} else {
+					// Pending requests are checked in previous statement
+					// eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+					this._pendingRequests.get(message.requestID)!(message);
+					this._pendingRequests.delete(message.requestID);
+				}
+			}
+		} catch (error) {
+			if (error instanceof TypeError) {
+				console.warn(error.message);
+			} else {
+				// Should not be possible, but who knows :shrug:
+				throw error;
+			}
+		}
+	}
+
+	protected postRequest<
+		TRequest extends UnknownRequestMessage,
+		TResponse extends UnknownResponseMessage,
+	>(
+		request: TRequest,
+		postMessage = (request: TRequest): void => this.port.postMessage(request),
+		options: PostRequestOptions = {},
+	): Promise<ExtractSuccessResponseMessage<TResponse>> {
+		if (this.options.debug) {
+			// eslint-disable-next-line no-console
+			console.debug(request);
+		}
+
+		if (this._pendingRequests.size >= this.options.maximumRequestConcurrency) {
+			throw new TooManyConcurrentRequestsError(request);
+		}
+
+		return new Promise<ExtractSuccessResponseMessage<TResponse>>(
+			(resolve, reject) => {
+				const requestTimeout = setTimeout(() => {
+					if (this._pendingRequests.has(request.requestID)) {
+						this._pendingRequests.delete(request.requestID);
+					}
+					reject(new RequestTimeoutError(request));
+				}, options.timeout || this.options.defaultTimeout);
+
+				this._pendingRequests.set(
+					request.requestID,
+					(response: TResponse): void => {
+						clearTimeout(requestTimeout);
+
+						isSuccessResponseMessage(response)
+							? resolve(response as ExtractSuccessResponseMessage<TResponse>)
+							: reject(
+									new ResponseError(
+										response as ExtractErrorResponseMessage<TResponse>,
+									),
+							  );
+					},
+				);
+
+				postMessage(request);
+			},
+		);
+	}
+
+	protected postResponse<TResponse extends UnknownResponseMessage>(
+		response: TResponse,
+		postMessage = (response: TResponse): void =>
+			this.port.postMessage(response),
+	): TResponse {
+		if (this.options.debug) {
+			// eslint-disable-next-line no-console
+			console.debug(response);
+		}
+
+		postMessage(response);
+
+		return response;
+	}
+}

package/src/channel/ChannelReceiver.ts

@@ -0,0 +1,184 @@
+import {
+	ExtractSuccessResponseMessage,
+	InternalEmitterRequestType,
+	InternalEmitterTransactions,
+	InternalReceiverRequestType,
+	RequestMessage,
+	ResponseMessage,
+	SuccessResponseMessage,
+	TransactionsHandlers,
+	UnknownRequestMessage,
+	UnknownResponseMessage,
+	UnknownTransaction,
+} from "./types";
+
+import { NotReadyError } from "./errors";
+
+import {
+	ChannelNetwork,
+	ChannelNetworkOptions,
+	PostRequestOptions,
+} from "./ChannelNetwork";
+import {
+	createErrorResponseMessage,
+	createSuccessResponseMessage,
+	isRequestMessage,
+	validateMessage,
+} from "./messages";
+
+export type ChannelReceiverOptions = {
+	readyTimeout: number;
+};
+
+export const channelReceiverDefaultOptions: ChannelReceiverOptions &
+	Partial<ChannelNetworkOptions> = {
+	readyTimeout: 20000,
+	requestIDPrefix: "receiver-",
+};
+
+export type AllChannelReceiverOptions = ChannelReceiverOptions &
+	ChannelNetworkOptions;
+
+export abstract class ChannelReceiver<
+	TEmitterTransactions extends Record<string, UnknownTransaction> = Record<
+		string,
+		never
+	>,
+	TOptions extends Record<string, unknown> = Record<string, unknown>,
+> extends ChannelNetwork<
+	TEmitterTransactions,
+	ChannelReceiverOptions & TOptions
+> {
+	private _ready = false;
+
+	constructor(
+		requestHandlers: TransactionsHandlers<TEmitterTransactions>,
+		options: Partial<AllChannelReceiverOptions> & TOptions,
+	) {
+		super(requestHandlers, { ...channelReceiverDefaultOptions, ...options });
+
+		window.addEventListener("message", (event) => {
+			this._onPublicMessage(event);
+		});
+	}
+
+	/**
+	 * Tells the emitter that receiver is ready
+	 */
+	public async ready(): Promise<SuccessResponseMessage> {
+		if (window.parent === window) {
+			throw new Error("Receiver is currently not embedded as an iframe");
+		}
+
+		this._ready = false;
+
+		const request = this.createRequestMessage(
+			InternalReceiverRequestType.Ready,
+			undefined,
+		);
+
+		const response = await this.postRequest<
+			RequestMessage<InternalReceiverRequestType.Ready>,
+			ResponseMessage
+		>(
+			request,
+			(request) => {
+				window.parent.postMessage(request, "*");
+			},
+			{
+				timeout: this.options.readyTimeout,
+			},
+		);
+
+		this._ready = true;
+
+		return response;
+	}
+
+	/**
+	 * Handles public messages
+	 */
+	private _onPublicMessage(event: MessageEvent<unknown>): void {
+		try {
+			const message = validateMessage(event.data);
+
+			if (isRequestMessage(message)) {
+				if (this.options.debug) {
+					// eslint-disable-next-line no-console
+					console.debug(event.data);
+				}
+
+				switch (message.type) {
+					case InternalEmitterRequestType.Connect:
+						// Set port
+						this.port = event.ports[0];
+
+						// Update options
+						const { data } =
+							message as InternalEmitterTransactions["connect"]["request"];
+						this.options = {
+							...this.options,
+							...data,
+							// Ensure core options remain the same
+							debug: this.options.debug,
+							requestIDPrefix: this.options.requestIDPrefix,
+							readyTimeout: this.options.readyTimeout,
+						};
+
+						const response = createSuccessResponseMessage(
+							message.requestID,
+							undefined,
+						);
+
+						this.postResponse(response);
+						break;
+
+					default:
+						this.postResponse(
+							createErrorResponseMessage(message.requestID, undefined),
+							(response) => {
+								(event.source as WindowProxy).postMessage(
+									response,
+									event.origin,
+								);
+							},
+						);
+						break;
+				}
+			} else {
+				// Forward response messages to default message handler if necessary
+				if (!this._ready) {
+					this.onMessage(event);
+				}
+			}
+		} catch (error) {
+			if (error instanceof TypeError) {
+				// Ignore unknown messages
+			} else {
+				// Should not be possible, but who knows :shrug:
+				throw error;
+			}
+		}
+	}
+
+	protected postFormattedRequest<
+		TRequest extends UnknownRequestMessage,
+		TResponse extends UnknownResponseMessage,
+	>(
+		type: TRequest["type"],
+		data?: TRequest["data"],
+		options: PostRequestOptions = {},
+	): Promise<ExtractSuccessResponseMessage<TResponse>> {
+		if (!this._ready) {
+			throw new NotReadyError(
+				"Receiver is not ready, use `ChannelReceiver.ready()` first",
+			);
+		}
+
+		return this.postRequest(
+			this.createRequestMessage(type, data),
+			undefined,
+			options,
+		);
+	}
+}