ultravisor 1.0.3 → 1.0.8

package/source/services/Ultravisor-Hypervisor.cjs

@@ -14,6 +14,16 @@ class UltravisorHypervisor extends libPictService
 		this._Running = false;
 	}
 
+	/**
+	 * Get a service instance from the fable services map.
+	 */
+	_getService(pTypeName)
+	{
+		return this.fable.servicesMap[pTypeName]
+			? Object.values(this.fable.servicesMap[pTypeName])[0]
+			: null;
+	}
+
 	get schedule()
 	{
 		return this.getSchedule();
@@ -25,46 +35,85 @@ class UltravisorHypervisor extends libPictService
 	}
 
 	/**
-	 * Add a task to the schedule.
+	 * Load the schedule from the persistence provider.
 	 *
-	 * @param {string} pTaskGUID - The task GUID to schedule.
-	 * @param {string} pType - Schedule type (cron, daily, hourly).
-	 * @param {string} pParameters - Schedule parameters (e.g. cron expression).
-	 * @param {function} fCallback - Callback.
+	 * If no provider is registered the in-memory schedule is left as-is.
+	 *
+	 * @param {function} fCallback - fCallback(pError)
 	 */
-	scheduleTask(pTaskGUID, pType, pParameters, fCallback)
+	loadSchedule(fCallback)
 	{
-		let tmpScheduleEntry = {
-			GUID: `sched-task-${pTaskGUID}-${Date.now()}`,
-			TargetType: 'Task',
-			TargetGUID: pTaskGUID,
-			ScheduleType: pType || 'cron',
-			Parameters: pParameters || '0 * * * *',
-			CronExpression: this._resolveScheduleExpression(pType, pParameters),
-			Active: false,
-			CreatedAt: new Date().toISOString()
-		};
+		let tmpPersistence = this._getService('UltravisorSchedulePersistence');
 
-		this._Schedule.push(tmpScheduleEntry);
-		this.log.info(`Ultravisor Hypervisor: scheduled task ${pTaskGUID} as ${tmpScheduleEntry.ScheduleType} (${tmpScheduleEntry.CronExpression})`);
+		if (!tmpPersistence)
+		{
+			this.log.warn('Ultravisor Hypervisor: no schedule persistence provider registered; using in-memory schedule only.');
+			if (typeof(fCallback) === 'function')
+			{
+				return fCallback(null);
+			}
+			return;
+		}
 
-		return fCallback(null, tmpScheduleEntry);
+		tmpPersistence.loadSchedule(
+			(pError, pSchedule) =>
+			{
+				if (pError)
+				{
+					this.log.error(`Ultravisor Hypervisor: failed to load schedule: ${pError.message}`);
+				}
+				else if (Array.isArray(pSchedule) && pSchedule.length > 0)
+				{
+					this._Schedule = pSchedule;
+					this.log.info(`Ultravisor Hypervisor: loaded ${pSchedule.length} schedule entries from persistence.`);
+				}
+
+				if (typeof(fCallback) === 'function')
+				{
+					return fCallback(pError);
+				}
+			});
+	}
+
+	/**
+	 * Persist the current schedule via the registered provider.
+	 *
+	 * Called internally after every mutation.  Fails silently if no
+	 * provider is registered so the Hypervisor works without persistence.
+	 */
+	_persistSchedule()
+	{
+		let tmpPersistence = this._getService('UltravisorSchedulePersistence');
+
+		if (!tmpPersistence)
+		{
+			return;
+		}
+
+		tmpPersistence.saveSchedule(this._Schedule,
+			(pError) =>
+			{
+				if (pError)
+				{
+					this.log.error(`Ultravisor Hypervisor: failed to persist schedule: ${pError.message}`);
+				}
+			});
 	}
 
 	/**
 	 * Add an operation to the schedule.
 	 *
-	 * @param {string} pOperationGUID - The operation GUID to schedule.
+	 * @param {string} pOperationHash - The operation hash to schedule.
 	 * @param {string} pType - Schedule type (cron, daily, hourly).
 	 * @param {string} pParameters - Schedule parameters.
 	 * @param {function} fCallback - Callback.
 	 */
-	scheduleOperation(pOperationGUID, pType, pParameters, fCallback)
+	scheduleOperation(pOperationHash, pType, pParameters, fCallback)
 	{
 		let tmpScheduleEntry = {
-			GUID: `sched-op-${pOperationGUID}-${Date.now()}`,
+			GUID: `sched-op-${pOperationHash}-${Date.now()}`,
 			TargetType: 'Operation',
-			TargetGUID: pOperationGUID,
+			TargetHash: pOperationHash,
 			ScheduleType: pType || 'cron',
 			Parameters: pParameters || '0 * * * *',
 			CronExpression: this._resolveScheduleExpression(pType, pParameters),
@@ -73,7 +122,8 @@ class UltravisorHypervisor extends libPictService
 		};
 
 		this._Schedule.push(tmpScheduleEntry);
-		this.log.info(`Ultravisor Hypervisor: scheduled operation ${pOperationGUID} as ${tmpScheduleEntry.ScheduleType} (${tmpScheduleEntry.CronExpression})`);
+		this.log.info(`Ultravisor Hypervisor: scheduled operation ${pOperationHash} as ${tmpScheduleEntry.ScheduleType} (${tmpScheduleEntry.CronExpression})`);
+		this._persistSchedule();
 
 		return fCallback(null, tmpScheduleEntry);
 	}
@@ -103,10 +153,9 @@ class UltravisorHypervisor extends libPictService
 	 */
 	startSchedule(fCallback)
 	{
-		let tmpCronService = this.fable['Ultravisor-Hypervisor-Event-Cron'];
-		let tmpTaskService = this.fable['Ultravisor-Task'];
-		let tmpOperationService = this.fable['Ultravisor-Operation'];
-		let tmpStateService = this.fable['Ultravisor-Hypervisor-State'];
+		let tmpCronService = this._getService('UltravisorHypervisorEventCron');
+		let tmpStateService = this._getService('UltravisorHypervisorState');
+		let tmpEngine = this._getService('UltravisorExecutionEngine');
 
 		this._Running = true;
 
@@ -124,55 +173,28 @@ class UltravisorHypervisor extends libPictService
 			tmpCronService.start(tmpEntry,
 				(pScheduleEntry) =>
 				{
-					// On tick, execute the target
-					if (pScheduleEntry.TargetType === 'Task')
-					{
-						tmpStateService.getTask(pScheduleEntry.TargetGUID,
-							(pError, pTask) =>
+					// On tick, execute the target operation
+					tmpStateService.getOperation(pScheduleEntry.TargetHash,
+						(pError, pOperation) =>
+						{
+							if (pError)
 							{
-								if (pError)
+								this.log.error(`Ultravisor Hypervisor: scheduled operation ${pScheduleEntry.TargetHash} not found: ${pError.message}`);
+								return;
+							}
+							tmpEngine.executeOperation(pOperation,
+								(pExecError, pContext) =>
 								{
-									this.log.error(`Ultravisor Hypervisor: scheduled task ${pScheduleEntry.TargetGUID} not found: ${pError.message}`);
-									return;
-								}
-								tmpTaskService.executeTask(pTask, {},
-									(pTaskError, pResult) =>
+									if (pExecError)
 									{
-										if (pTaskError)
-										{
-											this.log.error(`Ultravisor Hypervisor: scheduled task execution error: ${pTaskError.message}`);
-										}
-										else
-										{
-											this.log.info(`Ultravisor Hypervisor: scheduled task ${pScheduleEntry.TargetGUID} completed: ${pResult.Status}`);
-										}
-									});
-							});
-					}
-					else if (pScheduleEntry.TargetType === 'Operation')
-					{
-						tmpStateService.getOperation(pScheduleEntry.TargetGUID,
-							(pError, pOperation) =>
-							{
-								if (pError)
-								{
-									this.log.error(`Ultravisor Hypervisor: scheduled operation ${pScheduleEntry.TargetGUID} not found: ${pError.message}`);
-									return;
-								}
-								tmpOperationService.executeOperation(pOperation,
-									(pOpError, pManifest) =>
+										this.log.error(`Ultravisor Hypervisor: scheduled operation execution error: ${pExecError.message}`);
+									}
+									else
 									{
-										if (pOpError)
-										{
-											this.log.error(`Ultravisor Hypervisor: scheduled operation execution error: ${pOpError.message}`);
-										}
-										else
-										{
-											this.log.info(`Ultravisor Hypervisor: scheduled operation ${pScheduleEntry.TargetGUID} completed: ${pManifest.Status}`);
-										}
-									});
-							});
-					}
+										this.log.info(`Ultravisor Hypervisor: scheduled operation ${pScheduleEntry.TargetHash} completed: ${pContext.Status}`);
+									}
+								});
+						});
 				});
 		}
 
@@ -189,7 +211,7 @@ class UltravisorHypervisor extends libPictService
 	 */
 	stopSchedule(fCallback)
 	{
-		let tmpCronService = this.fable['Ultravisor-Hypervisor-Event-Cron'];
+		let tmpCronService = this._getService('UltravisorHypervisorEventCron');
 
 		tmpCronService.stop();
 		this._Running = false;
@@ -199,6 +221,7 @@ class UltravisorHypervisor extends libPictService
 			this._Schedule[i].Active = false;
 		}
 
+		this._persistSchedule();
 		this.log.info(`Ultravisor Hypervisor: schedule stopped.`);
 
 		if (typeof(fCallback) === 'function')
@@ -207,12 +230,98 @@ class UltravisorHypervisor extends libPictService
 		}
 	}
 
+	/**
+	 * Start a single schedule entry by GUID.
+	 */
+	startScheduleEntry(pGUID, fCallback)
+	{
+		let tmpCronService = this._getService('UltravisorHypervisorEventCron');
+		let tmpStateService = this._getService('UltravisorHypervisorState');
+		let tmpEngine = this._getService('UltravisorExecutionEngine');
+
+		for (let i = 0; i < this._Schedule.length; i++)
+		{
+			let tmpEntry = this._Schedule[i];
+
+			if (tmpEntry.GUID === pGUID)
+			{
+				if (tmpEntry.Active)
+				{
+					return fCallback(null, tmpEntry);
+				}
+
+				tmpEntry.Active = true;
+
+				tmpCronService.start(tmpEntry,
+					(pScheduleEntry) =>
+					{
+						tmpStateService.getOperation(pScheduleEntry.TargetHash,
+							(pError, pOperation) =>
+							{
+								if (pError)
+								{
+									this.log.error(`Ultravisor Hypervisor: scheduled operation ${pScheduleEntry.TargetHash} not found: ${pError.message}`);
+									return;
+								}
+								tmpEngine.executeOperation(pOperation,
+									(pExecError, pContext) =>
+									{
+										if (pExecError)
+										{
+											this.log.error(`Ultravisor Hypervisor: scheduled operation execution error: ${pExecError.message}`);
+										}
+										else
+										{
+											this.log.info(`Ultravisor Hypervisor: scheduled operation ${pScheduleEntry.TargetHash} completed: ${pContext.Status}`);
+										}
+									});
+							});
+					});
+
+				this._persistSchedule();
+				this.log.info(`Ultravisor Hypervisor: started schedule entry ${pGUID}`);
+				return fCallback(null, tmpEntry);
+			}
+		}
+
+		return fCallback(new Error(`Schedule entry ${pGUID} not found.`));
+	}
+
+	/**
+	 * Stop a single schedule entry by GUID.
+	 */
+	stopScheduleEntry(pGUID, fCallback)
+	{
+		let tmpCronService = this._getService('UltravisorHypervisorEventCron');
+
+		for (let i = 0; i < this._Schedule.length; i++)
+		{
+			let tmpEntry = this._Schedule[i];
+
+			if (tmpEntry.GUID === pGUID)
+			{
+				if (!tmpEntry.Active)
+				{
+					return fCallback(null, tmpEntry);
+				}
+
+				tmpEntry.Active = false;
+				tmpCronService.stopJob(pGUID);
+				this._persistSchedule();
+				this.log.info(`Ultravisor Hypervisor: stopped schedule entry ${pGUID}`);
+				return fCallback(null, tmpEntry);
+			}
+		}
+
+		return fCallback(new Error(`Schedule entry ${pGUID} not found.`));
+	}
+
 	/**
 	 * Remove a schedule entry by GUID.
 	 */
 	removeScheduleEntry(pGUID, fCallback)
 	{
-		let tmpCronService = this.fable['Ultravisor-Hypervisor-Event-Cron'];
+		let tmpCronService = this._getService('UltravisorHypervisorEventCron');
 
 		for (let i = 0; i < this._Schedule.length; i++)
 		{
@@ -223,6 +332,7 @@ class UltravisorHypervisor extends libPictService
 					tmpCronService.stopJob(pGUID);
 				}
 				this._Schedule.splice(i, 1);
+				this._persistSchedule();
 				this.log.info(`Ultravisor Hypervisor: removed schedule entry ${pGUID}`);
 				return fCallback(null, true);
 			}

package/source/services/Ultravisor-Schedule-Persistence-Base.cjs

@@ -0,0 +1,45 @@
+const libPictService = require('pict-serviceproviderbase');
+
+/**
+ * Base class for schedule persistence providers.
+ *
+ * Defines the interface that all persistence backends must implement.
+ * The default implementations return errors so that downstream providers
+ * that only partially implement the interface get clear feedback.
+ *
+ * To create a custom provider (e.g. remote API), extend this class and
+ * override loadSchedule() and saveSchedule(), then register your class
+ * under the service type 'UltravisorSchedulePersistence'.
+ */
+class UltravisorSchedulePersistenceBase extends libPictService
+{
+	constructor(pPict, pOptions, pServiceHash)
+	{
+		super(pPict, pOptions, pServiceHash);
+
+		this.serviceType = 'UltravisorSchedulePersistenceBase';
+	}
+
+	/**
+	 * Load the schedule from the backing store.
+	 *
+	 * @param {function} fCallback - fCallback(pError, pScheduleArray)
+	 */
+	loadSchedule(fCallback)
+	{
+		return fCallback(new Error('UltravisorSchedulePersistenceBase: loadSchedule() not implemented.'));
+	}
+
+	/**
+	 * Save the full schedule to the backing store.
+	 *
+	 * @param {Array} pSchedule - The schedule array to persist.
+	 * @param {function} fCallback - fCallback(pError)
+	 */
+	saveSchedule(pSchedule, fCallback)
+	{
+		return fCallback(new Error('UltravisorSchedulePersistenceBase: saveSchedule() not implemented.'));
+	}
+}
+
+module.exports = UltravisorSchedulePersistenceBase;

package/source/services/Ultravisor-StateManager.cjs

@@ -0,0 +1,253 @@
+const libPictService = require('pict-serviceproviderbase');
+
+/**
+ * Manages three-level state (Global, Operation, Task) and provides
+ * address resolution through Manyfest.
+ *
+ * Address prefixes:
+ *   Global.X            -> GlobalState.X
+ *   Operation.X         -> OperationState.X
+ *   Task.X              -> TaskOutputs[currentNodeHash].X
+ *   TaskOutput.{Hash}.X -> TaskOutputs[Hash].X
+ *   Output.X            -> Output.X
+ *   Staging.Path        -> StagingPath string
+ */
+class UltravisorStateManager extends libPictService
+{
+	constructor(pPict, pOptions, pServiceHash)
+	{
+		super(pPict, pOptions, pServiceHash);
+
+		this.serviceType = 'UltravisorStateManager';
+
+		this._Manyfest = this.fable.newManyfest();
+	}
+
+	/**
+	 * Resolve an address against the execution context.
+	 *
+	 * @param {string} pAddress - The address to resolve (e.g. 'Operation.InputFilePath').
+	 * @param {object} pExecutionContext - The runtime execution context.
+	 * @param {string} [pCurrentNodeHash] - The current task node's hash (for Task.X resolution).
+	 * @returns {*} The resolved value, or undefined if not found.
+	 */
+	resolveAddress(pAddress, pExecutionContext, pCurrentNodeHash)
+	{
+		if (!pAddress || typeof(pAddress) !== 'string')
+		{
+			return undefined;
+		}
+
+		let tmpDotIndex = pAddress.indexOf('.');
+		let tmpPrefix;
+		let tmpRemainder;
+
+		if (tmpDotIndex > -1)
+		{
+			tmpPrefix = pAddress.substring(0, tmpDotIndex);
+			tmpRemainder = pAddress.substring(tmpDotIndex + 1);
+		}
+		else
+		{
+			tmpPrefix = pAddress;
+			tmpRemainder = '';
+		}
+
+		switch (tmpPrefix)
+		{
+			case 'Global':
+				return this._resolveFromObject(pExecutionContext.GlobalState, tmpRemainder);
+
+			case 'Operation':
+				return this._resolveFromObject(pExecutionContext.OperationState, tmpRemainder);
+
+			case 'Task':
+				if (!pCurrentNodeHash)
+				{
+					this.log.warn(`UltravisorStateManager: resolveAddress for Task.X requires a current node hash.`);
+					return undefined;
+				}
+				return this._resolveFromObject(
+					pExecutionContext.TaskOutputs[pCurrentNodeHash] || {},
+					tmpRemainder);
+
+			case 'TaskOutput':
+			{
+				// TaskOutput.{NodeHash}.{Path}
+				let tmpSecondDot = tmpRemainder.indexOf('.');
+				if (tmpSecondDot < 0)
+				{
+					// Just TaskOutput.{NodeHash} -- return the whole output object
+					return pExecutionContext.TaskOutputs[tmpRemainder] || {};
+				}
+				let tmpNodeHash = tmpRemainder.substring(0, tmpSecondDot);
+				let tmpPath = tmpRemainder.substring(tmpSecondDot + 1);
+				return this._resolveFromObject(
+					pExecutionContext.TaskOutputs[tmpNodeHash] || {},
+					tmpPath);
+			}
+
+			case 'Output':
+				return this._resolveFromObject(pExecutionContext.Output, tmpRemainder);
+
+			case 'Staging':
+				if (tmpRemainder === 'Path' || tmpRemainder === '')
+				{
+					return pExecutionContext.StagingPath || '';
+				}
+				return undefined;
+
+			default:
+				// Fall through: try the full address against OperationState first,
+				// then GlobalState. This allows shorthand like 'InputFilePath'
+				// to resolve from Operation state.
+				let tmpValue = this._resolveFromObject(pExecutionContext.OperationState, pAddress);
+				if (tmpValue !== undefined)
+				{
+					return tmpValue;
+				}
+				return this._resolveFromObject(pExecutionContext.GlobalState, pAddress);
+		}
+	}
+
+	/**
+	 * Set a value at an address in the execution context.
+	 *
+	 * @param {string} pAddress - The address to set (e.g. 'Operation.InputFilePath').
+	 * @param {*} pValue - The value to set.
+	 * @param {object} pExecutionContext - The runtime execution context.
+	 * @param {string} [pCurrentNodeHash] - The current task node's hash (for Task.X).
+	 * @returns {boolean} True if the value was set successfully.
+	 */
+	setAddress(pAddress, pValue, pExecutionContext, pCurrentNodeHash)
+	{
+		if (!pAddress || typeof(pAddress) !== 'string')
+		{
+			return false;
+		}
+
+		let tmpDotIndex = pAddress.indexOf('.');
+		let tmpPrefix;
+		let tmpRemainder;
+
+		if (tmpDotIndex > -1)
+		{
+			tmpPrefix = pAddress.substring(0, tmpDotIndex);
+			tmpRemainder = pAddress.substring(tmpDotIndex + 1);
+		}
+		else
+		{
+			tmpPrefix = pAddress;
+			tmpRemainder = '';
+		}
+
+		switch (tmpPrefix)
+		{
+			case 'Global':
+				return this._setOnObject(pExecutionContext.GlobalState, tmpRemainder, pValue);
+
+			case 'Operation':
+				return this._setOnObject(pExecutionContext.OperationState, tmpRemainder, pValue);
+
+			case 'Task':
+				if (!pCurrentNodeHash)
+				{
+					this.log.warn(`UltravisorStateManager: setAddress for Task.X requires a current node hash.`);
+					return false;
+				}
+				if (!pExecutionContext.TaskOutputs[pCurrentNodeHash])
+				{
+					pExecutionContext.TaskOutputs[pCurrentNodeHash] = {};
+				}
+				return this._setOnObject(
+					pExecutionContext.TaskOutputs[pCurrentNodeHash],
+					tmpRemainder, pValue);
+
+			case 'TaskOutput':
+			{
+				let tmpSecondDot = tmpRemainder.indexOf('.');
+				if (tmpSecondDot < 0)
+				{
+					// Setting the entire TaskOutput for a node
+					pExecutionContext.TaskOutputs[tmpRemainder] = pValue;
+					return true;
+				}
+				let tmpNodeHash = tmpRemainder.substring(0, tmpSecondDot);
+				let tmpPath = tmpRemainder.substring(tmpSecondDot + 1);
+				if (!pExecutionContext.TaskOutputs[tmpNodeHash])
+				{
+					pExecutionContext.TaskOutputs[tmpNodeHash] = {};
+				}
+				return this._setOnObject(
+					pExecutionContext.TaskOutputs[tmpNodeHash],
+					tmpPath, pValue);
+			}
+
+			case 'Output':
+				if (!pExecutionContext.Output)
+				{
+					pExecutionContext.Output = {};
+				}
+				return this._setOnObject(pExecutionContext.Output, tmpRemainder, pValue);
+
+			default:
+				// Default: write to OperationState
+				return this._setOnObject(pExecutionContext.OperationState, pAddress, pValue);
+		}
+	}
+
+	/**
+	 * Build a root data object for Pict template resolution.
+	 * This object can be passed to pict.parseTemplate as the record.
+	 *
+	 * @param {object} pExecutionContext - The runtime execution context.
+	 * @param {*} [pSourceValue] - An optional source value (e.g. for state connection resolution).
+	 * @returns {object} Root data object with all state levels.
+	 */
+	buildTemplateContext(pExecutionContext, pSourceValue)
+	{
+		return {
+			Value: pSourceValue,
+			Global: pExecutionContext.GlobalState || {},
+			Operation: pExecutionContext.OperationState || {},
+			TaskOutput: pExecutionContext.TaskOutputs || {},
+			Output: pExecutionContext.Output || {},
+			Staging: { Path: pExecutionContext.StagingPath || '' }
+		};
+	}
+
+	// --- Internal helpers ---
+
+	_resolveFromObject(pObject, pPath)
+	{
+		if (!pObject || typeof(pObject) !== 'object')
+		{
+			return undefined;
+		}
+
+		if (!pPath || pPath === '')
+		{
+			return pObject;
+		}
+
+		return this._Manyfest.getValueAtAddress(pObject, pPath);
+	}
+
+	_setOnObject(pObject, pPath, pValue)
+	{
+		if (!pObject || typeof(pObject) !== 'object')
+		{
+			return false;
+		}
+
+		if (!pPath || pPath === '')
+		{
+			return false;
+		}
+
+		this._Manyfest.setValueAtAddress(pObject, pPath, pValue);
+		return true;
+	}
+}
+
+module.exports = UltravisorStateManager;