alchemymvc 1.3.15 → 1.3.17

package/lib/class/task.js

@@ -1,19 +1,36 @@
-var running = alchemy.shared('Task.running', 'Array');
+const running = alchemy.shared('Task.running', 'Array'),
+      HISTORY_DOC = Symbol('history_document'),
+      PAUSE_PLEDGE = Symbol('pause_pledge'),
+      RUNNING_PLEDGE = Symbol('running_pledge'),
+      STATUS = Symbol('status'),
+      STARTING = 0,
+      STARTED = 1,
+      PAUSED = 2,
+      STOPPED = 3;
 
 /**
  * The base "Task" class
  *
- * @author   Jelle De Loecker   <jelle@develry.be>
+ * @author   Jelle De Loecker   <jelle@elevenways.be>
  * @since    0.3.0
  * @version  0.5.0
  */
-var Task = Function.inherits('Alchemy.Base', function Task() {
+const Task = Function.inherits('Alchemy.Base', 'Alchemy.Task', function Task() {
 
 	// When this command started executing
-	this.started = null;
+	this.started_at = null;
 
 	// When this command stopped executing
-	this.stopped = null;
+	this.stopped_at = null;
+
+	// The current status
+	this[STATUS] = STARTING;
+
+	// Optional pause pledge
+	this[PAUSE_PLEDGE] = null;
+
+	// The main running pledge
+	this[RUNNING_PLEDGE] = null;
 
 	// Caught error
 	this.error = null;
@@ -24,12 +41,65 @@ var Task = Function.inherits('Alchemy.Base', function Task() {
 
 	// Status reports
 	this.reports = [];
+
+	// The payload/settings
+	this.payload = null;
+
+	// The origin AlchemyTask document
+	this.alchemy_task_document = null;
+
+	// The AlchemyTaskHistory document
+	this[HISTORY_DOC] = null;
+});
+
+/**
+ * Add a forced cron schedule:
+ * this task will always run at the given time
+ *
+ * @author   Jelle De Loecker   <jelle@elevenways.be>
+ * @since    1.3.17
+ * @version  1.3.17
+ *
+ * @param    {String}   cron_schedule
+ * @param    {Object}   settings
+ */
+Task.setStatic(function addForcedCronSchedule(cron_schedule, settings) {
+
+	cron_schedule = new Classes.Alchemy.Cron(cron_schedule);
+
+	if (!this.forced_cron_schedules) {
+		this.forced_cron_schedules = [];
+	}
+
+	this.forced_cron_schedules.push({cron_schedule, settings});
+});
+
+/**
+ * Add a fallback cron schedule:
+ * this task will run at the given time if no other schedule is found
+ *
+ * @author   Jelle De Loecker   <jelle@elevenways.be>
+ * @since    1.3.17
+ * @version  1.3.17
+ *
+ * @param    {String}   cron_schedule
+ * @param    {Object}   settings
+ */
+Task.setStatic(function addFallbackCronSchedule(cron_schedule, settings) {
+
+	cron_schedule = new Classes.Alchemy.Cron(cron_schedule);
+
+	if (!this.fallback_cron_schedules) {
+		this.fallback_cron_schedules = [];
+	}
+
+	this.fallback_cron_schedules.push({cron_schedule, settings});
 });
 
 /**
  * Each command has a configuration schema
  *
- * @author   Jelle De Loecker   <jelle@develry.be>
+ * @author   Jelle De Loecker   <jelle@elevenways.be>
  * @since    0.3.0
  * @version  0.5.0
  */
@@ -89,10 +159,49 @@ Task.setProperty('static_description', '');
  */
 Task.setProperty('force_description_callback', false);
 
+/**
+ * Has this task started?
+ *
+ * @author   Jelle De Loecker <jelle@elevenways.be>
+ * @since    1.3.17
+ * @version  1.3.17
+ *
+ * @type     {Boolean}
+ */
+Task.setProperty(function has_started() {
+	return this[STATUS] > STARTING;
+});
+
+/**
+ * Has this task been paused?
+ *
+ * @author   Jelle De Loecker <jelle@elevenways.be>
+ * @since    1.3.17
+ * @version  1.3.17
+ *
+ * @type     {Boolean}
+ */
+Task.setProperty(function is_paused() {
+	return this[STATUS] == PAUSED;
+});
+
+/**
+ * Has this task stopped?
+ *
+ * @author   Jelle De Loecker <jelle@elevenways.be>
+ * @since    1.3.17
+ * @version  1.3.17
+ *
+ * @type     {Boolean}
+ */
+Task.setProperty(function has_stopped() {
+	return this[STATUS] == STOPPED;
+});
+
 /**
  * Return the basic record for JSON
  *
- * @author   Jelle De Loecker <jelle@develry.be>
+ * @author   Jelle De Loecker <jelle@elevenways.be>
  * @since    0.3.0
  * @version  1.0.0
  */
@@ -117,250 +226,288 @@ Task.setMethod(function toJSON() {
 /**
  * Callback with a nice description
  *
- * @author   Jelle De Loecker   <jelle@develry.be>
+ * @author   Jelle De Loecker   <jelle@elevenways.be>
  * @since    0.3.0
- * @version  0.3.0
+ * @version  1.3.17
  *
- * @param    {Function}   callback
+ * @return   {Promise<String>}
  */
-Task.setMethod(function getDescription(callback) {
-
-	var that = this;
+Task.setMethod(async function getDescription() {
 
 	// If there is a static description, that should be returned
 	if (this.static_description && !this.force_description_callback) {
-		return callback(null, this.static_description);
+		return this.static_description;
 	}
 
-	return this._getDescription(function gotDescription(err, description) {
-
-		if (err) {
-			return callback(err);
-		}
+	let description = await this._getDescription();
+	this.description = description;
 
-		that.description = description;
-		return callback(null, description);
-	});
+	return description;
 });
 
 /**
  * Callback with a nice description,
  * should be modified upon extension
  *
- * @author   Jelle De Loecker   <jelle@develry.be>
+ * @author   Jelle De Loecker   <jelle@elevenways.be>
  * @since    0.3.0
  * @version  0.3.0
  *
- * @param    {Function}   callback
+ * @return   {Promise<String>}
  */
-Task.setMethod(function _getDescription(callback) {
-	callback(null, this.constructor.title || this.name);
+Task.setMethod(async function _getDescription() {
+	return this.constructor.title || this.name;
 });
 
 /**
- * The function to execute, needs to be overridden
+ * The main function to execute. Should not be called directly.
+ * Needs to be overridden by child classes.
  *
- * @author   Jelle De Loecker   <jelle@develry.be>
+ * @author   Jelle De Loecker   <jelle@elevenways.be>
  * @since    0.5.0
- * @version  0.5.0
+ * @version  1.3.17
+ */
+Task.setMethod(async function executor() {
+	throw new Error('Task ' + this.constructor.title + ' has no executor function!');
+});
+
+/**
+ * Set the payload/settings
+ *
+ * @author   Jelle De Loecker   <jelle@elevenways.be>
+ * @since    1.3.17
+ * @version  1.3.17
  *
  * @param    {Object}   payload    User provided data
- * @param    {Object}   callback
  */
-Task.setMethod(function execute(payload, callback) {
-	if (!callback) {
-		callback = Function.thrower;
-	}
+Task.setMethod(function setPayload(payload) {
+	this.payload = payload;
+});
 
-	callback(new Error('Task ' + this.constructor.title + ' has no executable function!'));
+/**
+ * Set the original AlchemyTask document
+ *
+ * @author   Jelle De Loecker   <jelle@elevenways.be>
+ * @since    1.3.17
+ * @version  1.3.17
+ *
+ * @param    {Document.AlchemyTask}   doc
+ */
+Task.setMethod(function setAlchemyTaskDocument(doc) {
+	this.alchemy_task_document = doc;
+});
+
+/**
+ * Set the AlchemyTaskHistory document
+ *
+ * @author   Jelle De Loecker   <jelle@elevenways.be>
+ * @since    1.3.17
+ * @version  1.3.17
+ *
+ * @param    {Document.AlchemyTaskHistory}   doc
+ */
+Task.setMethod(function setAlchemyTaskHistoryDocument(doc) {
+	this[HISTORY_DOC] = doc;
 });
 
 /**
  * Start executing the command
  *
- * @author   Jelle De Loecker   <jelle@develry.be>
+ * @author   Jelle De Loecker   <jelle@elevenways.be>
  * @since    0.3.0
- * @version  0.5.0
+ * @version  1.3.17
  *
  * @param    {Object}   payload    User provided data
- * @param    {Object}   callback
  */
-Task.setMethod(function start(payload, callback) {
-
-	var that = this,
-	    run_id = String(alchemy.ObjectId());
+Task.setMethod(async function start(payload) {
 
-	if (typeof payload == 'function') {
-		callback = payload;
-		payload = {};
+	if (this.has_started) {
+		throw new Error('Task ' + this.constructor.title + ' has already started!');
 	}
 
-	if (typeof callback != 'function') {
-		callback = Function.thrower;
+	if (payload) {
+		this.setPayload(payload);
 	}
 
-	if (!payload) {
-		payload = {};
+	const History = Model.get('AlchemyTaskHistory');
+
+	this[STATUS] = STARTED;
+	this[RUNNING_PLEDGE] = new Pledge();
+
+	let document = this[HISTORY_DOC];
+
+	if (!document) {
+		document = History.createDocument();
+		document.type = this.constructor.type_path || this.constructor.type_name;
+		document.alchemy_task_id = this.alchemy_task_document?.$pk;
+		document.process_id = process.pid;
+		this[HISTORY_DOC] = document;
 	}
 
-	// Store the payload
-	this.payload = payload;
+	let started_at = new Date();
+	document.settings = this.payload;
+	document.started_at = started_at;
+	document.is_running = true;
 
 	// Register this command as running
 	running.push(this);
 
+	await document.save();
+
 	// Set the id
-	this.id = run_id;
+	this.id = String(document.$pk);
 
 	// Set the start time
-	this.started = Date.now();
+	this.started = started_at.getTime();
 
-	// Actually execute the command
-	this.execute(payload, function done(err, result) {
+	let result;
 
-		var report;
-
-		// Catch manua stop requests
+	try {
+		result = await this.executor();
+	} catch (err) {
 		if (err == 'stopped') {
-			that.report('stopped', 'Stopped');
-			return callback(null);
+			this.report('stopped', 'Stopped');
+			return;
 		}
 
-		if (err) {
+		// Set the error
+		this.error = err;
 
-			// Set the error
-			that.error = err;
+		// Report failed
+		let report = this.report('failed');
+		report.error = err;
 
-			// Report failed
-			report = that.report('failed');
-			report.error = err;
+		throw err;
+	}
 
-			return callback(err);
-		}
+	// If the command hasn't been manually stopped,
+	// report it as done
+	if (!this.manual_stop_end) {
+		this.report('done');
+	}
 
-		// If the command hasn't been manually stopped,
-		// report it as done
-		if (!that.manual_stop_end) {
-			that.report('done');
-		}
+	document.ended_at = new Date();
+	document.is_running = false;
+	await document.save();
 
-		callback(null, result);
-	});
+	this[RUNNING_PLEDGE].resolve(result);
+
+	return result;
 });
 
 /**
  * Stop the running command
  *
- * @author   Jelle De Loecker   <jelle@develry.be>
+ * @author   Jelle De Loecker   <jelle@elevenways.be>
  * @since    0.3.0
- * @version  0.3.0
- *
- * @param    {Object}   callback
+ * @version  1.3.17
  */
-Task.setMethod(function stop(callback) {
-
-	var that = this;
-
-	if (!callback) {
-		callback = Function.thrower;
-	}
+Task.setMethod(async function stop() {
 
 	// Set time when manual stop was requested
 	this.manual_stop_start = Date.now();
 	this.need_stop = true;
 
 	if (typeof this.doStop == 'function') {
-		return this.doStop(function stopped(err) {
-
-			if (err) {
-				return callback(err);
-			}
-
-			that.manual_stop_end = Date.now();
-			callback(null);
-		});
-	} else {
-		callback();
+		let result = await this.doStop();
+		this.manual_stop_end = Date.now();
+		return result;
 	}
 });
 
 /**
  * Pause the running command
  *
- * @author   Jelle De Loecker   <jelle@develry.be>
+ * @author   Jelle De Loecker   <jelle@elevenways.be>
  * @since    0.3.0
- * @version  0.3.0
- *
- * @param    {Object}   callback
+ * @version  1.3.17
  */
-Task.setMethod(function pause(callback) {
+Task.setMethod(function pause() {
 
-	var that = this;
+	// Do nothing if already paused
+	if (this.is_paused) {
+		return;
+	}
 
-	if (!callback) {
-		callback = Function.thrower;
+	// If this has stopped, throw an error
+	if (this.has_stopped) {
+		throw new Error('Unable to pause a task that has already stopped');
 	}
 
-	// Indicate this command needs to be paused
-	this.pause_requested = true;
+	this[PAUSE_PLEDGE] = new Pledge();
+	this[STATUS] = PAUSED;
 
 	if (typeof this.doPause == 'function') {
-		return this.doPause(function paused(err) {
-
-			if (err) {
-				return callback(err);
-			}
-
-			callback(null);
-		});
-	} else {
-		callback();
+		return this.doPause();
 	}
 });
 
 /**
- * Resule the paused command
+ * Resume this task if it has been paused
  *
- * @author   Jelle De Loecker   <jelle@develry.be>
+ * @author   Jelle De Loecker   <jelle@elevenways.be>
  * @since    0.3.0
- * @version  0.3.0
- *
- * @param    {Object}   callback
+ * @version  1.3.17
  */
-Task.setMethod(function resume(callback) {
-
-	var that = this;
+Task.setMethod(function resume() {
 
-	if (!callback) {
-		callback = Function.thrower;
+	if (!this.is_paused) {
+		return;
 	}
 
-	// Indicate this command needs to be resumed
-	this.pause_requested = false;
-	this.resume_requested = true;
+	if (this.has_stopped) {
+		throw new Error('Unable to resume a task that has already stopped');
+	}
 
 	if (typeof this.doResume == 'function') {
-		return this.doResume(function resumed(err) {
+		this.doResume();
+	}
 
-			if (err) {
-				return callback(err);
-			}
+	// If there is a pause pledge, resolve it
+	if (this[PAUSE_PLEDGE]) {
+		this[PAUSE_PLEDGE].resolve();
+		this[PAUSE_PLEDGE] = null;
+	}
 
-			callback(null);
-		});
-	} else {
-		callback();
+	// Set the status back to `started`
+	this[STATUS] = STARTED;
+});
+
+/**
+ * Get a parameter from the payload by the given name
+ *
+ * @author   Jelle De Loecker   <jelle@elevenways.be>
+ * @since    1.3.17
+ * @version  1.3.17
+ */
+Task.setMethod(function getParam(name) {
+	return this.payload?.[name];
+});
+
+/**
+ * Wait for the pause to resolve
+ *
+ * @author   Jelle De Loecker   <jelle@elevenways.be>
+ * @since    1.3.17
+ * @version  1.3.17
+ */
+Task.setMethod(function waitUntilResumed() {
+
+	if (!this.is_paused || this.has_stopped) {
+		return false;
 	}
+
+	return this[PAUSE_PLEDGE];
 });
 
 /**
  * Report command progress
  *
- * @author   Jelle De Loecker   <jelle@develry.be>
+ * @author   Jelle De Loecker   <jelle@elevenways.be>
  * @since    0.3.0
- * @version  0.3.0
+ * @version  1.3.17
  *
- * @param    {Number}   percentage    Percentage that is done
+ * @param    {Number}   percentage    Percentage that is done as a decimal (between 0 & 1)
  * @param    {String}   type          The type of status
  *
  * @return   {Object}
@@ -381,6 +528,10 @@ Task.setMethod(function report(percentage, type) {
 		this.paused = false;
 	}
 
+	if (typeof percentage == 'number') {
+		percentage = Math.round(percentage * 10000) / 100;
+	}
+
 	report = this.reports.last();
 
 	if (type == null) {
@@ -436,9 +587,10 @@ Task.setMethod(function report(percentage, type) {
 });
 
 /**
- * Report progress, Janeway hooks into this
+ * Report progress, Janeway monkey-patches this method
+ * and uses it to display the progress bar.
  *
- * @author   Jelle De Loecker   <jelle@develry.be>
+ * @author   Jelle De Loecker   <jelle@elevenways.be>
  * @since    0.5.0
  * @version  0.5.0
  *
@@ -452,7 +604,7 @@ Task.setMethod(function reportProgress(value, label) {
 /**
  * Log command messages
  *
- * @author   Jelle De Loecker   <jelle@develry.be>
+ * @author   Jelle De Loecker   <jelle@elevenways.be>
  * @since    0.3.0
  * @version  0.3.0
  */
@@ -475,7 +627,7 @@ Task.setMethod(function log() {
 /**
  * Start executing a task
  *
- * @author   Jelle De Loecker   <jelle@develry.be>
+ * @author   Jelle De Loecker   <jelle@elevenways.be>
  * @since    0.3.0
  * @version  0.5.0
  *