@ckeditor/ckeditor5-watchdog 0.0.0-internal-20241017.0

package/dist/watchdog.d.ts

@@ -0,0 +1,233 @@
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @module watchdog/watchdog
+ */
+import type { CKEditorError } from 'ckeditor5/src/utils.js';
+import type { EditorWatchdogRestartEvent } from './editorwatchdog.js';
+import type { ContextWatchdogItemErrorEvent, ContextWatchdogItemRestartEvent } from './contextwatchdog.js';
+/**
+ * An abstract watchdog class that handles most of the error handling process and the state of the underlying component.
+ *
+ * See the {@glink features/watchdog Watchdog feature guide} to learn the rationale behind it and how to use it.
+ *
+ * @internal
+ */
+export default abstract class Watchdog {
+    /**
+     * An array of crashes saved as an object with the following properties:
+     *
+     * * `message`: `String`,
+     * * `stack`: `String`,
+     * * `date`: `Number`,
+     * * `filename`: `String | undefined`,
+     * * `lineno`: `Number | undefined`,
+     * * `colno`: `Number | undefined`,
+     */
+    readonly crashes: Array<{
+        message: string;
+        stack?: string;
+        date: number;
+        filename?: string;
+        lineno?: number;
+        colno?: number;
+    }>;
+    /**
+     * Specifies the state of the item watched by the watchdog. The state can be one of the following values:
+     *
+     * * `initializing` &ndash; Before the first initialization, and after crashes, before the item is ready.
+     * * `ready` &ndash; A state when the user can interact with the item.
+     * * `crashed` &ndash; A state when an error occurs. It quickly changes to `initializing` or `crashedPermanently`
+     * depending on how many and how frequent errors have been caught recently.
+     * * `crashedPermanently` &ndash; A state when the watchdog stops reacting to errors and keeps the item it is watching crashed,
+     * * `destroyed` &ndash; A state when the item is manually destroyed by the user after calling `watchdog.destroy()`.
+     */
+    state: WatchdogState;
+    /**
+     * @see module:watchdog/watchdog~WatchdogConfig
+     */
+    private _crashNumberLimit;
+    /**
+     * Returns the result of the `Date.now()` call. It can be overridden in tests to mock time as some popular
+     * approaches like `sinon.useFakeTimers()` do not work well with error handling.
+     */
+    private _now;
+    /**
+     * @see module:watchdog/watchdog~WatchdogConfig
+     */
+    private _minimumNonErrorTimePeriod;
+    /**
+     * Checks if the event error comes from the underlying item and restarts the item.
+     */
+    private _boundErrorHandler;
+    /**
+     * The method responsible for restarting the watched item.
+     */
+    protected abstract _restart(): Promise<unknown>;
+    /**
+     * Traverses the error context and the watched item to find out whether the error should
+     * be handled by the given item.
+     *
+     * @internal
+     */
+    abstract _isErrorComingFromThisItem(error: CKEditorError): boolean;
+    /**
+     * The watched item.
+     *
+     * @internal
+     */
+    abstract get _item(): unknown;
+    /**
+     * A dictionary of event emitter listeners.
+     */
+    private _listeners;
+    /**
+     * @param {module:watchdog/watchdog~WatchdogConfig} config The watchdog plugin configuration.
+     */
+    constructor(config: WatchdogConfig);
+    /**
+     * Destroys the watchdog and releases the resources.
+     */
+    destroy(): void;
+    /**
+     * Starts listening to a specific event name by registering a callback that will be executed
+     * whenever an event with a given name fires.
+     *
+     * Note that this method differs from the CKEditor 5's default `EventEmitterMixin` implementation.
+     *
+     * @param eventName The event name.
+     * @param callback A callback which will be added to event listeners.
+     */
+    on<K extends keyof EventMap>(eventName: K, callback: EventCallback<K>): void;
+    /**
+     * Stops listening to the specified event name by removing the callback from event listeners.
+     *
+     * Note that this method differs from the CKEditor 5's default `EventEmitterMixin` implementation.
+     *
+     * @param eventName The event name.
+     * @param callback A callback which will be removed from event listeners.
+     */
+    off(eventName: keyof EventMap, callback: unknown): void;
+    /**
+     * Fires an event with a given event name and arguments.
+     *
+     * Note that this method differs from the CKEditor 5's default `EventEmitterMixin` implementation.
+     */
+    protected _fire<K extends keyof EventMap>(eventName: K, ...args: EventArgs<K>): void;
+    /**
+     * Starts error handling by attaching global error handlers.
+     */
+    protected _startErrorHandling(): void;
+    /**
+     * Stops error handling by detaching global error handlers.
+     */
+    protected _stopErrorHandling(): void;
+    /**
+     * Checks if an error comes from the watched item and restarts it.
+     * It reacts to {@link module:utils/ckeditorerror~CKEditorError `CKEditorError` errors} only.
+     *
+     * @fires error
+     * @param error Error.
+     * @param evt An error event.
+     */
+    private _handleError;
+    /**
+     * Checks whether an error should be handled by the watchdog.
+     *
+     * @param error An error that was caught by the error handling process.
+     */
+    private _shouldReactToError;
+    /**
+     * Checks if the watchdog should restart the underlying item.
+     */
+    private _shouldRestart;
+}
+/**
+ * Fired when a new {@link module:utils/ckeditorerror~CKEditorError `CKEditorError`} error connected to the watchdog instance occurs
+ * and the watchdog will react to it.
+ *
+ * ```ts
+ * watchdog.on( 'error', ( evt, { error, causesRestart } ) => {
+ * 	console.log( 'An error occurred.' );
+ * } );
+ * ```
+ *
+ * @eventName ~Watchdog#error
+ */
+export type WatchdogErrorEvent = {
+    name: 'error';
+    args: [WatchdogErrorEventData];
+};
+/**
+ * The `error` event data.
+ */
+export type WatchdogErrorEventData = {
+    error: Error;
+    causesRestart: boolean;
+};
+/**
+ * Fired when the watchdog state changed.
+ *
+ * @eventName ~Watchdog#stateChange
+ */
+export type WatchdogStateChangeEvent = {
+    name: 'stateChange';
+    args: [];
+};
+/**
+ * The map of watchdog events.
+ */
+export interface EventMap {
+    stateChange: WatchdogStateChangeEvent;
+    error: WatchdogErrorEvent;
+    restart: EditorWatchdogRestartEvent;
+    itemError: ContextWatchdogItemErrorEvent;
+    itemRestart: ContextWatchdogItemRestartEvent;
+}
+/**
+ * Utility type that gets the arguments type for the given event.
+ */
+export type EventArgs<K extends keyof EventMap> = EventMap[K]['args'];
+/**
+ * Utility type that gets the callback type for the given event.
+ */
+export type EventCallback<K extends keyof EventMap> = (evt: null, ...args: EventArgs<K>) => void;
+/**
+ * The watchdog plugin configuration.
+ */
+export interface WatchdogConfig {
+    /**
+     * A threshold specifying the number of watched item crashes
+     * when the watchdog stops restarting the item in case of errors.
+     * After this limit is reached and the time between the last errors is shorter than `minimumNonErrorTimePeriod`,
+     * the watchdog changes its state to `crashedPermanently` and it stops restarting the item. This prevents an infinite restart loop.
+     *
+     * @default 3
+     */
+    crashNumberLimit?: number;
+    /**
+     * An average number of milliseconds between the last watched item errors
+     * (defaults to 5000). When the period of time between errors is lower than that and the `crashNumberLimit` is also reached,
+     * the watchdog changes its state to `crashedPermanently` and it stops restarting the item. This prevents an infinite restart loop.
+     *
+     * @default 5000
+     */
+    minimumNonErrorTimePeriod?: number;
+    /**
+     * A minimum number of milliseconds between saving the editor data internally (defaults to 5000).
+     * Note that for large documents this might impact the editor performance.
+     *
+     * @default 5000
+     */
+    saveInterval?: number;
+}
+/**
+ * Specifies the state of the item watched by the watchdog.
+ */
+export type WatchdogState = 'initializing' | 'ready' | 'crashed' | 'crashedPermanently' | 'destroyed';

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@ckeditor/ckeditor5-watchdog",
+  "version": "0.0.0-internal-20241017.0",
+  "description": "A watchdog feature for CKEditor 5 editors. It keeps a CKEditor 5 editor instance running.",
+  "keywords": [
+    "ckeditor",
+    "ckeditor5",
+    "ckeditor 5",
+    "ckeditor5-lib",
+    "ckeditor5-dll"
+  ],
+  "type": "module",
+  "main": "src/index.js",
+  "dependencies": {
+    "lodash-es": "4.17.21"
+  },
+  "author": "CKSource (http://cksource.com/)",
+  "license": "GPL-2.0-or-later",
+  "homepage": "https://ckeditor.com/ckeditor-5",
+  "bugs": "https://github.com/ckeditor/ckeditor5/issues",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ckeditor/ckeditor5.git",
+    "directory": "packages/ckeditor5-watchdog"
+  },
+  "files": [
+    "dist",
+    "lang",
+    "src/**/*.js",
+    "src/**/*.d.ts",
+    "theme",
+    "ckeditor5-metadata.json",
+    "CHANGELOG.md"
+  ],
+  "types": "src/index.d.ts"
+}

package/src/augmentation.d.ts

@@ -0,0 +1,15 @@
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+import type { EditorData } from './editorwatchdog.js';
+declare module '@ckeditor/ckeditor5-core' {
+    interface EditorConfig {
+        /**
+         * The temporary property that is used for passing data to the plugin which restores the editor state.
+         *
+         * @internal
+         */
+        _watchdogInitialData?: EditorData;
+    }
+}

package/src/augmentation.js

@@ -0,0 +1,5 @@
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+export {};

package/src/contextwatchdog.d.ts

@@ -0,0 +1,333 @@
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @module watchdog/contextwatchdog
+ */
+import type { Context, Editor, EditorConfig, ContextConfig } from 'ckeditor5/src/core.js';
+import type { ArrayOrItem, CKEditorError } from 'ckeditor5/src/utils.js';
+import Watchdog, { type WatchdogConfig, type WatchdogState } from './watchdog.js';
+import EditorWatchdog, { type EditorCreatorFunction } from './editorwatchdog.js';
+/**
+ * A watchdog for the {@link module:core/context~Context} class.
+ *
+ * See the {@glink features/watchdog Watchdog feature guide} to learn the rationale behind it and
+ * how to use it.
+ */
+export default class ContextWatchdog<TContext extends Context = Context> extends Watchdog {
+    /**
+     * A map of internal watchdogs for added items.
+     */
+    protected _watchdogs: Map<string, EditorWatchdog<Editor>>;
+    /**
+     * The watchdog configuration.
+     */
+    private readonly _watchdogConfig;
+    /**
+     * The current context instance.
+     */
+    private _context;
+    /**
+     * Context properties (nodes/references) that are gathered during the initial context creation
+     * and are used to distinguish the origin of an error.
+     */
+    private _contextProps;
+    /**
+     * An action queue, which is used to handle async functions queuing.
+     */
+    private _actionQueues;
+    /**
+     * The configuration for the {@link module:core/context~Context}.
+     */
+    private _contextConfig?;
+    /**
+     * The creation method.
+     *
+     * @see #setCreator
+     */
+    protected _creator: (config: ContextConfig) => Promise<TContext>;
+    /**
+     * The destruction method.
+     *
+     * @see #setDestructor
+     */
+    protected _destructor: (context: Context) => Promise<unknown>;
+    /**
+     * The watched item.
+     */
+    _item: unknown;
+    /**
+     * The context watchdog class constructor.
+     *
+     * ```ts
+     * const watchdog = new ContextWatchdog( Context );
+     *
+     * await watchdog.create( contextConfiguration );
+     *
+     * await watchdog.add( item );
+     * ```
+     *
+     * See the {@glink features/watchdog Watchdog feature guide} to learn more how to use this feature.
+     *
+     * @param Context The {@link module:core/context~Context} class.
+     * @param watchdogConfig The watchdog configuration.
+     */
+    constructor(Context: {
+        create(...args: any): Promise<TContext>;
+    }, watchdogConfig?: WatchdogConfig);
+    /**
+     * Sets the function that is responsible for the context creation.
+     * It expects a function that should return a promise (or `undefined`).
+     *
+     * ```ts
+     * watchdog.setCreator( config => Context.create( config ) );
+     * ```
+     */
+    setCreator(creator: (config: ContextConfig) => Promise<TContext>): void;
+    /**
+     * Sets the function that is responsible for the context destruction.
+     * Overrides the default destruction function, which destroys only the context instance.
+     * It expects a function that should return a promise (or `undefined`).
+     *
+     * ```ts
+     * watchdog.setDestructor( context => {
+     * 	// Do something before the context is destroyed.
+     *
+     * 	return context
+     * 		.destroy()
+     * 		.then( () => {
+     * 			// Do something after the context is destroyed.
+     * 		} );
+     * } );
+     * ```
+     */
+    setDestructor(destructor: (context: Context) => Promise<unknown>): void;
+    /**
+     * The context instance. Keep in mind that this property might be changed when the context watchdog restarts,
+     * so do not keep this instance internally. Always operate on the `ContextWatchdog#context` property.
+     */
+    get context(): Context | null;
+    /**
+     * Initializes the context watchdog. Once it is created, the watchdog takes care about
+     * recreating the context and the provided items, and starts the error handling mechanism.
+     *
+     * ```ts
+     * await watchdog.create( {
+     * 	plugins: []
+     * } );
+     * ```
+     *
+     * @param contextConfig The context configuration. See {@link module:core/context~Context}.
+     */
+    create(contextConfig?: ContextConfig): Promise<unknown>;
+    /**
+     * Returns an item instance with the given `itemId`.
+     *
+     * ```ts
+     * const editor1 = watchdog.getItem( 'editor1' );
+     * ```
+     *
+     * @param itemId The item ID.
+     * @returns The item instance or `undefined` if an item with a given ID has not been found.
+     */
+    getItem(itemId: string): unknown;
+    /**
+     * Gets the state of the given item. See {@link #state} for a list of available states.
+     *
+     * ```ts
+     * const editor1State = watchdog.getItemState( 'editor1' );
+     * ```
+     *
+     * @param itemId Item ID.
+     * @returns The state of the item.
+     */
+    getItemState(itemId: string): WatchdogState;
+    /**
+     * Adds items to the watchdog. Once created, instances of these items will be available using the {@link #getItem} method.
+     *
+     * Items can be passed together as an array of objects:
+     *
+     * ```ts
+     * await watchdog.add( [ {
+     * 	id: 'editor1',
+     * 	type: 'editor',
+     * 	sourceElementOrData: document.querySelector( '#editor' ),
+     * 	config: {
+     * 		plugins: [ Essentials, Paragraph, Bold, Italic ],
+     * 		toolbar: [ 'bold', 'italic', 'alignment' ]
+     * 	},
+     * 	creator: ( element, config ) => ClassicEditor.create( element, config )
+     * } ] );
+     * ```
+     *
+     * Or one by one as objects:
+     *
+     * ```ts
+     * await watchdog.add( {
+     * 	id: 'editor1',
+     * 	type: 'editor',
+     * 	sourceElementOrData: document.querySelector( '#editor' ),
+     * 	config: {
+     * 		plugins: [ Essentials, Paragraph, Bold, Italic ],
+     * 		toolbar: [ 'bold', 'italic', 'alignment' ]
+     * 	},
+     * 	creator: ( element, config ) => ClassicEditor.create( element, config )
+     * ] );
+     * ```
+     *
+     * Then an instance can be retrieved using the {@link #getItem} method:
+     *
+     * ```ts
+     * const editor1 = watchdog.getItem( 'editor1' );
+     * ```
+     *
+     * Note that this method can be called multiple times, but for performance reasons it is better
+     * to pass all items together.
+     *
+     * @param itemConfigurationOrItemConfigurations An item configuration object or an array of item configurations.
+     */
+    add(itemConfigurationOrItemConfigurations: ArrayOrItem<WatchdogItemConfiguration>): Promise<unknown>;
+    /**
+     * Removes and destroys item(s) with given ID(s).
+     *
+     * ```ts
+     * await watchdog.remove( 'editor1' );
+     * ```
+     *
+     * Or
+     *
+     * ```ts
+     * await watchdog.remove( [ 'editor1', 'editor2' ] );
+     * ```
+     *
+     * @param itemIdOrItemIds Item ID or an array of item IDs.
+     */
+    remove(itemIdOrItemIds: ArrayOrItem<string>): Promise<unknown>;
+    /**
+     * Destroys the context watchdog and all added items.
+     * Once the context watchdog is destroyed, new items cannot be added.
+     *
+     * ```ts
+     * await watchdog.destroy();
+     * ```
+     */
+    destroy(): Promise<unknown>;
+    /**
+     * Restarts the context watchdog.
+     */
+    protected _restart(): Promise<unknown>;
+    /**
+     * Initializes the context watchdog.
+     */
+    private _create;
+    /**
+     * Destroys the context instance and all added items.
+     */
+    private _destroy;
+    /**
+     * Returns the watchdog for a given item ID.
+     *
+     * @param itemId Item ID.
+     */
+    protected _getWatchdog(itemId: string): Watchdog;
+    /**
+     * Checks whether an error comes from the context instance and not from the item instances.
+     *
+     * @internal
+     */
+    _isErrorComingFromThisItem(error: CKEditorError): boolean;
+}
+/**
+ * Fired after the watchdog restarts the context and the added items because of a crash.
+ *
+ * ```ts
+ * watchdog.on( 'restart', () => {
+ * 	console.log( 'The context has been restarted.' );
+ * } );
+ * ```
+ *
+ * @eventName ~ContextWatchdog#restart
+ */
+export type ContextWatchdogRestartEvent = {
+    name: 'restart';
+    args: [];
+    return: undefined;
+};
+/**
+ * Fired when a new error occurred in one of the added items.
+ *
+ * ```ts
+ * watchdog.on( 'itemError', ( evt, { error, itemId } ) => {
+ * 	console.log( `An error occurred in an item with the '${ itemId }' ID.` );
+ * } );
+ * ```
+ *
+ * @eventName ~ContextWatchdog#itemError
+ */
+export type ContextWatchdogItemErrorEvent = {
+    name: 'itemError';
+    args: [ContextWatchdogItemErrorEventData];
+    return: undefined;
+};
+/**
+ * The `itemError` event data.
+ */
+export type ContextWatchdogItemErrorEventData = {
+    itemId: string;
+    error: Error;
+};
+/**
+ * Fired after an item has been restarted.
+ *
+ * ```ts
+ * 	watchdog.on( 'itemRestart', ( evt, { itemId } ) => {
+ *		console.log( 'An item with with the '${ itemId }' ID has been restarted.' );
+ * 	} );
+ * ```
+ *
+ * @eventName ~ContextWatchdog#itemRestart
+ */
+export type ContextWatchdogItemRestartEvent = {
+    name: 'itemRestart';
+    args: [ContextWatchdogItemRestartEventData];
+    return: undefined;
+};
+/**
+ * The `itemRestart` event data.
+ */
+export type ContextWatchdogItemRestartEventData = {
+    itemId: string;
+};
+/**
+ * The watchdog item configuration interface.
+ */
+export interface WatchdogItemConfiguration {
+    /**
+     * id A unique item identificator.
+     */
+    id: string;
+    /**
+     * The type of the item to create. At the moment, only `'editor'` is supported.
+     */
+    type: 'editor';
+    /**
+     * A function that initializes the item (the editor). The function takes editor initialization arguments
+     * and should return a promise. For example: `( el, config ) => ClassicEditor.create( el, config )`.
+     */
+    creator: EditorCreatorFunction;
+    /**
+     * A function that destroys the item instance (the editor). The function
+     * takes an item and should return a promise. For example: `editor => editor.destroy()`
+     */
+    destructor?: (editor: Editor) => Promise<unknown>;
+    /**
+     * The source element or data that will be passed
+     * as the first argument to the `Editor.create()` method.
+     */
+    sourceElementOrData: string | HTMLElement;
+    /**
+     * An editor configuration.
+     */
+    config: EditorConfig;
+}