@ckeditor/ckeditor5-watchdog 10.0.1 → 17.0.0

package/src/watchdog.js

@@ -1,5 +1,5 @@
 /**
- * @license Copyright (c) 2003-2019, CKSource - Frederico Knabben. All rights reserved.
+ * @license Copyright (c) 2003-2020, CKSource - Frederico Knabben. All rights reserved.
  * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
  */
 
@@ -7,35 +7,30 @@
  * @module watchdog/watchdog
  */
 
-/* globals console, window */
-
-import mix from '@ckeditor/ckeditor5-utils/src/mix';
-import EmitterMixin from '@ckeditor/ckeditor5-utils/src/emittermixin';
-import { throttle, cloneDeepWith, isElement } from 'lodash-es';
-import CKEditorError from '@ckeditor/ckeditor5-utils/src/ckeditorerror';
-import areConnectedThroughProperties from '@ckeditor/ckeditor5-utils/src/areconnectedthroughproperties';
+/* globals window */
 
 /**
- * A watchdog for CKEditor 5 editors.
+ * 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.
  *
- * See the {@glink features/watchdog Watchdog} feature guide to learn the rationale behind it and
- * how to use it.
+ * @private
+ * @abstract
  */
 export default class Watchdog {
 	/**
-	 * @param {Object} [config] The watchdog plugin configuration.
-	 * @param {Number} [config.crashNumberLimit=3] A threshold specifying the number of crashes
-	 * when the watchdog stops restarting the editor in case of errors.
-	 * @param {Number} [config.waitingTime=5000] A minimum amount of milliseconds between saving editor data internally.
+	 * @param {module:watchdog/watchdog~WatchdogConfig} config The watchdog plugin configuration.
 	 */
-	constructor( { crashNumberLimit, waitingTime } = {} ) {
+	constructor( config ) {
 		/**
 		 * An array of crashes saved as an object with the following properties:
 		 *
 		 * * `message`: `String`,
-		 * * `source`: `String`,
-		 * * `lineno`: `String`,
-		 * * `colno`: `String`
+		 * * `stack`: `String`,
+		 * * `date`: `Number`,
+		 * * `filename`: `String | undefined`,
+		 * * `lineno`: `Number | undefined`,
+		 * * `colno`: `Number | undefined`,
 		 *
 		 * @public
 		 * @readonly
@@ -44,339 +39,321 @@ export default class Watchdog {
 		this.crashes = [];
 
 		/**
-		 * Crash number limit (defaults to `3`). After this limit is reached the editor is not restarted by the watchdog.
-		 * This is to prevent an infinite crash loop.
+		 * Specifies the state of the item watched by the watchdog. The state can be one of the following values:
 		 *
-		 * @private
+		 * * `initializing` – Before the first initialization, and after crashes, before the item is ready.
+		 * * `ready` – A state when the user can interact with the item.
+		 * * `crashed` – 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` – A state when the watchdog stops reacting to errors and keeps the item it is watching crashed,
+		 * * `destroyed` – A state when the item is manually destroyed by the user after calling `watchdog.destroy()`.
+		 *
+		 * @public
+		 * @member {'initializing'|'ready'|'crashed'|'crashedPermanently'|'destroyed'} #state
+		 */
+		this.state = 'initializing';
+
+		/**
+		 * @protected
 		 * @type {Number}
+		 * @see module:watchdog/watchdog~WatchdogConfig
 		 */
-		this._crashNumberLimit = crashNumberLimit || 3;
+		this._crashNumberLimit = typeof config.crashNumberLimit === 'number' ? config.crashNumberLimit : 3;
 
 		/**
-		 * Checks if the event error comes from the editor that is handled by the watchdog (by checking the error context)
-		 * and restarts the editor.
+		 * 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
-		 * @type {Function}
+		 * @protected
 		 */
-		this._boundErrorHandler = this._handleGlobalErrorEvent.bind( this );
+		this._now = Date.now;
 
 		/**
-		 * Throttled save method. The `save()` method is called the specified `waitingTime` after `throttledSave()` is called,
-		 * unless a new action happens in the meantime.
-		 *
-		 * @private
-		 * @type {Function}
+		 * @protected
+		 * @type {Number}
+		 * @see module:watchdog/watchdog~WatchdogConfig
 		 */
-		this._throttledSave = throttle( this._save.bind( this ), waitingTime || 5000 );
+		this._minimumNonErrorTimePeriod = typeof config.minimumNonErrorTimePeriod === 'number' ? config.minimumNonErrorTimePeriod : 5000;
 
 		/**
-		 * The current editor instance.
+		 * Checks if the event error comes from the underlying item and restarts the item.
 		 *
 		 * @private
-		 * @type {module:core/editor/editor~Editor}
+		 * @type {Function}
 		 */
-		this._editor = null;
+		this._boundErrorHandler = evt => {
+			// `evt.error` is exposed by EventError while `evt.reason` is available in PromiseRejectionEvent.
+			const error = evt.error || evt.reason;
+
+			// Note that `evt.reason` might be everything that is in the promise rejection.
+			// Similarly everything that is thrown lands in `evt.error`.
+			if ( error instanceof Error ) {
+				this._handleError( error, evt );
+			}
+		};
 
 		/**
-		 * The editor creation method.
+		 * The creation method.
 		 *
-		 * @private
+		 * @protected
 		 * @member {Function} #_creator
 		 * @see #setCreator
 		 */
 
 		/**
-		 * The editor destruction method.
+		 * The destruction method.
 		 *
-		 * @private
+		 * @protected
 		 * @member {Function} #_destructor
 		 * @see #setDestructor
 		 */
 
 		/**
-		 * The latest saved editor data.
+		 * The watched item.
 		 *
-		 * @private
-		 * @member {String} #_data
+		 * @abstract
+		 * @protected
+		 * @member {Object|undefined} #_item
 		 */
 
 		/**
-		 * The last document version.
+		 * The method responsible for restarting the watched item.
 		 *
-		 * @private
-		 * @member {Number} #_lastDocumentVersion
+		 * @abstract
+		 * @protected
+		 * @method #_restart
 		 */
 
 		/**
-		 * The editor source element or data.
+		 * Traverses the error context and the watched item to find out whether the error should
+		 * be handled by the given item.
 		 *
-		 * @private
-		 * @member {HTMLElement|String} #_elementOrData
+		 * @abstract
+		 * @protected
+		 * @method #_isErrorComingFromThisItem
+		 * @param {module:utils/ckeditorerror~CKEditorError} error
 		 */
 
 		/**
-		 * The editor configuration.
+		 * A dictionary of event emitter listeners.
 		 *
 		 * @private
-		 * @member {Object|undefined} #_config
+		 * @type {Object.<String,Array.<Function>>}
 		 */
-	}
+		this._listeners = {};
 
-	/**
-	 * The current editor instance.
-	 *
-	 * @readonly
-	 * @type {module:core/editor/editor~Editor}
-	 */
-	get editor() {
-		return this._editor;
+		if ( !this._restart ) {
+			throw new Error(
+				'The Watchdog class was split into the abstract `Watchdog` class and the `EditorWatchdog` class. ' +
+				'Please, use `EditorWatchdog` if you have used the `Watchdog` class previously.'
+			);
+		}
 	}
 
 	/**
-	 * Sets the function that is responsible for editor creation.
-	 * It expects a function that should return a promise.
-	 *
-	 *		watchdog.setCreator( ( element, config ) => ClassicEditor.create( element, config ) );
+	 * Sets the function that is responsible for creating watched items.
 	 *
-	 * @param {Function} creator
+	 * @param {Function} creator A callback responsible for creating an item. Returns a promise
+	 * that is resolved when the item is created.
 	 */
 	setCreator( creator ) {
 		this._creator = creator;
 	}
 
 	/**
-	 * Sets the function that is responsible for editor destruction.
-	 * It expects a function that should return a promise or `undefined`.
-	 *
-	 *		watchdog.setDestructor( editor => editor.destroy() );
+	 * Sets the function that is responsible for destroying watched items.
 	 *
-	 * @param {Function} destructor
+	 * @param {Function} destructor A callback that takes the item and returns the promise
+	 * to the destroying process.
 	 */
 	setDestructor( destructor ) {
 		this._destructor = destructor;
 	}
 
 	/**
-	 * Creates a watched editor instance using the creator passed to the {@link #setCreator `setCreator()`} method or
-	 * {@link module:watchdog/watchdog~Watchdog.for `Watchdog.for()`} helper.
+	 * Destroys the watchdog and releases the resources.
+	 */
+	destroy() {
+		this._stopErrorHandling();
+
+		this._listeners = {};
+	}
+
+	/**
+	 * Starts listening to a specific event name by registering a callback that will be executed
+	 * whenever an event with a given name fires.
 	 *
-	 * @param {HTMLElement|String} elementOrData
-	 * @param {module:core/editor/editorconfig~EditorConfig} [config]
+	 * Note that this method differs from the CKEditor 5's default `EventEmitterMixin` implementation.
 	 *
-	 * @returns {Promise.<module:watchdog/watchdog~Watchdog>}
+	 * @param {String} eventName The event name.
+	 * @param {Function} callback A callback which will be added to event listeners.
 	 */
-	create( elementOrData, config ) {
-		if ( !this._creator ) {
-			/**
-			 * The watchdog's editor creator is not defined. Define it by using
-			 * {@link module:watchdog/watchdog~Watchdog#setCreator `Watchdog#setCreator()`} or
-			 * the {@link module:watchdog/watchdog~Watchdog.for `Watchdog.for()`} helper.
-			 *
-			 * @error watchdog-creator-not-defined
-			 */
-			throw new CKEditorError(
-				'watchdog-creator-not-defined: The watchdog\'s editor creator is not defined.',
-				null
-			);
-		}
-
-		if ( !this._destructor ) {
-			/**
-			 * The watchdog's editor destructor is not defined. Define it by using
-			 * {@link module:watchdog/watchdog~Watchdog#setDestructor `Watchdog#setDestructor()`} or
-			 * the {@link module:watchdog/watchdog~Watchdog.for `Watchdog.for()`} helper.
-			 *
-			 * @error watchdog-destructor-not-defined
-			 */
-			throw new CKEditorError(
-				'watchdog-destructor-not-defined: The watchdog\'s editor destructor is not defined.',
-				null
-			);
+	on( eventName, callback ) {
+		if ( !this._listeners[ eventName ] ) {
+			this._listeners[ eventName ] = [];
 		}
 
-		this._elementOrData = elementOrData;
-
-		// Clone config because it might be shared within multiple watchdog instances. Otherwise
-		// when an error occurs in one of these editors the watchdog will restart all of them.
-		this._config = cloneDeepWith( config, value => {
-			// Leave DOM references.
-			return isElement( value ) ? value : undefined;
-		} );
-
-		return Promise.resolve()
-			.then( () => this._creator( elementOrData, this._config ) )
-			.then( editor => {
-				this._editor = editor;
-
-				window.addEventListener( 'error', this._boundErrorHandler );
-				this.listenTo( editor.model.document, 'change:data', this._throttledSave );
-
-				this._lastDocumentVersion = editor.model.document.version;
-				this._data = editor.data.get();
-
-				return this;
-			} );
+		this._listeners[ eventName ].push( callback );
 	}
 
 	/**
-	 * Restarts the editor instance. This method is also called whenever an editor error occurs.
-	 * It fires the `restart` event.
+	 * 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.
 	 *
-	 * @fires restart
-	 * @returns {Promise}
+	 * @param {String} eventName The event name.
+	 * @param {Function} callback A callback which will be removed from event listeners.
 	 */
-	restart() {
-		this._throttledSave.flush();
-
-		return Promise.resolve()
-			.then( () => this.destroy() )
-			.catch( err => console.error( 'An error happened during the editor destructing.', err ) )
-			.then( () => {
-				if ( typeof this._elementOrData === 'string' ) {
-					return this.create( this._data, this._config );
-				}
-
-				const updatedConfig = Object.assign( {}, this._config, {
-					initialData: this._data
-				} );
-
-				return this.create( this._elementOrData, updatedConfig );
-			} )
-			.then( () => {
-				this.fire( 'restart' );
-			} );
+	off( eventName, callback ) {
+		this._listeners[ eventName ] = this._listeners[ eventName ]
+			.filter( cb => cb !== callback );
 	}
 
 	/**
-	 * Destroys the current editor instance by using the destructor passed to the {@link #setDestructor `setDestructor()`} method.
+	 * Fires an event with a given event name and arguments.
+	 *
+	 * Note that this method differs from the CKEditor 5's default `EventEmitterMixin` implementation.
 	 *
-	 * @returns {Promise.<module:watchdog/watchdog~Watchdog>}
+	 * @protected
+	 * @param {String} eventName The event name.
+	 * @param  {...*} args Event arguments.
 	 */
-	destroy() {
-		window.removeEventListener( 'error', this._boundErrorHandler );
-		this.stopListening( this._editor.model.document, 'change:data', this._throttledSave );
-
-		return Promise.resolve()
-			.then( () => this._destructor( this._editor ) )
-			.then( () => {
-				this._editor = null;
+	_fire( eventName, ...args ) {
+		const callbacks = this._listeners[ eventName ] || [];
 
-				return this;
-			} );
+		for ( const callback of callbacks ) {
+			callback.apply( this, [ null, ...args ] );
+		}
 	}
 
 	/**
-	 * Saves the editor data, so it can be restored after the crash even if the data cannot be fetched at
-	 * the moment of a crash.
+	 * Starts error handling by attaching global error handlers.
 	 *
-	 * @private
+	 * @protected
 	 */
-	_save() {
-		const version = this._editor.model.document.version;
-
-		// Change may not produce an operation, so the document's version
-		// can be the same after that change.
-		if ( version === this._lastDocumentVersion ) {
-			return;
-		}
+	_startErrorHandling() {
+		window.addEventListener( 'error', this._boundErrorHandler );
+		window.addEventListener( 'unhandledrejection', this._boundErrorHandler );
+	}
 
-		try {
-			this._data = this._editor.data.get();
-			this._lastDocumentVersion = version;
-		} catch ( err ) {
-			console.error(
-				err,
-				'An error happened during restoring editor data. ' +
-				'Editor will be restored from the previously saved data.'
-			);
-		}
+	/**
+	 * Stops error handling by detaching global error handlers.
+	 *
+	 * @protected
+	 */
+	_stopErrorHandling() {
+		window.removeEventListener( 'error', this._boundErrorHandler );
+		window.removeEventListener( 'unhandledrejection', this._boundErrorHandler );
 	}
 
 	/**
-	 * Checks if the event error comes from the editor that is handled by the watchdog (by checking the error context) and
-	 * restarts the editor. It handles {@link module:utils/ckeditorerror~CKEditorError `CKEditorError` errors} only.
+	 * Checks if an error comes from the watched item and restarts it.
+	 * It reacts to {@link module:utils/ckeditorerror~CKEditorError `CKEditorError` errors} only.
 	 *
 	 * @private
 	 * @fires error
-	 * @param {Event} evt Error event.
+	 * @param {Error} error Error.
+	 * @param {ErrorEvent|PromiseRejectionEvent} evt An error event.
 	 */
-	_handleGlobalErrorEvent( evt ) {
-		if ( !evt.error.is || !evt.error.is( 'CKEditorError' ) ) {
-			return;
-		}
-
-		if ( evt.error.context === undefined ) {
-			console.error( 'The error is missing its context and Watchdog cannot restart the proper editor.' );
-
-			return;
-		}
-
-		// In some cases the editor should not be restarted - e.g. in case of the editor initialization.
-		// That's why the `null` was introduced as a correct error context which does cause restarting.
-		if ( evt.error.context === null ) {
-			return;
-		}
+	_handleError( error, evt ) {
+		// @if CK_DEBUG // if ( error.is && error.is( 'CKEditorError' ) && error.context === undefined ) {
+		// @if CK_DEBUG // console.warn( 'The error is missing its context and Watchdog cannot restart the proper item.' );
+		// @if CK_DEBUG // }
 
-		if ( this._isErrorComingFromThisEditor( evt.error ) ) {
+		if ( this._shouldReactToError( error ) ) {
 			this.crashes.push( {
-				message: evt.error.message,
-				source: evt.source,
+				message: error.message,
+				stack: error.stack,
+
+				// `evt.filename`, `evt.lineno` and `evt.colno` are available only in ErrorEvent events
+				filename: evt.filename,
 				lineno: evt.lineno,
-				colno: evt.colno
+				colno: evt.colno,
+				date: this._now()
 			} );
 
-			this.fire( 'error' );
+			const causesRestart = this._shouldRestart();
+
+			this.state = 'crashed';
+			this._fire( 'stateChange' );
+			this._fire( 'error', { error, causesRestart } );
 
-			if ( this.crashes.length <= this._crashNumberLimit ) {
-				this.restart();
+			if ( causesRestart ) {
+				this._restart();
+			} else {
+				this.state = 'crashedPermanently';
+				this._fire( 'stateChange' );
 			}
 		}
 	}
 
 	/**
-	 * Traverses both structures to find out whether the error context is connected
-	 * with the current editor.
+	 * Checks whether an error should be handled by the watchdog.
 	 *
 	 * @private
-	 * @param {module:utils/ckeditorerror~CKEditorError} error
+	 * @param {Error} error An error that was caught by the error handling process.
 	 */
-	_isErrorComingFromThisEditor( error ) {
-		return areConnectedThroughProperties( this._editor, error.context );
+	_shouldReactToError( error ) {
+		return (
+			error.is &&
+			error.is( 'CKEditorError' ) &&
+			error.context !== undefined &&
+
+			// In some cases the watched item should not be restarted - e.g. during the item initialization.
+			// That's why the `null` was introduced as a correct error context which does cause restarting.
+			error.context !== null &&
+
+			// Do not react to errors if the watchdog is in states other than `ready`.
+			this.state === 'ready' &&
+
+			this._isErrorComingFromThisItem( error )
+		);
 	}
 
 	/**
-	 * A shorthand method for creating an instance of the watchdog. For the full usage see the
-	 * {@link ~Watchdog `Watchdog` class description}.
-	 *
-	 * Usage:
+	 * Checks if the watchdog should restart the underlying item.
 	 *
-	 *		const watchdog = Watchdog.for( ClassicEditor );
-	 *
-	 *		watchdog.create( elementOrData, config );
-	 *
-	 * @param {*} Editor The editor class.
+	 * @private
 	 */
-	static for( Editor ) {
-		const watchdog = new Watchdog();
+	_shouldRestart() {
+		if ( this.crashes.length <= this._crashNumberLimit ) {
+			return true;
+		}
+
+		const lastErrorTime = this.crashes[ this.crashes.length - 1 ].date;
+		const firstMeaningfulErrorTime = this.crashes[ this.crashes.length - 1 - this._crashNumberLimit ].date;
 
-		watchdog.setCreator( ( elementOrData, config ) => Editor.create( elementOrData, config ) );
-		watchdog.setDestructor( editor => editor.destroy() );
+		const averageNonErrorTimePeriod = ( lastErrorTime - firstMeaningfulErrorTime ) / this._crashNumberLimit;
 
-		return watchdog;
+		return averageNonErrorTimePeriod > this._minimumNonErrorTimePeriod;
 	}
 
 	/**
-	 * Fired when an error occurs and the watchdog will be restarting the editor.
+	 * Fired when a new {@link module:utils/ckeditorerror~CKEditorError `CKEditorError`} error connected to the watchdog instance occurs
+	 * and the watchdog will react to it.
 	 *
-	 * @event error
-	 */
-
-	/**
-	 * Fired after the watchdog restarts the error in case of a crash or when the `restart()` method was called explicitly.
+	 * 	watchdog.on( 'error', ( evt, { error, causesRestart } ) => {
+	 * 		console.log( 'An error occurred.' );
+	 * 	} );
 	 *
-	 * @event restart
+	 * @event error
 	 */
 }
 
-mix( Watchdog, EmitterMixin );
+/**
+ * The watchdog plugin configuration.
+ *
+ * @typedef {Object} WatchdogConfig
+ *
+ * @property {Number} [crashNumberLimit=3] 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.
+ *
+ * @property {Number} [minimumNonErrorTimePeriod=5000] 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.
+ *
+ * @property {Number} [saveInterval=5000] 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.
+ */