@iebh/tera-fy 1.14.2 → 1.15.0

package/lib/terafy.client.js

@@ -1,5 +1,5 @@
 import {diff} from 'just-diff';
-import {cloneDeep, merge} from 'lodash-es';
+import {cloneDeep} from 'lodash-es';
 import Mitt from 'mitt';
 import {nanoid} from 'nanoid';
 import ProjectFile from './projectFile.js';
@@ -17,11 +17,12 @@ export default class TeraFy {
 	* Various settings to configure behaviour
 	*
 	* @type {Object}
+	* @property {String} session Unique session signature for this instance of TeraFy, used to sign server messages, if falsy `getEntropicString(16)` is used to populate
 	* @property {Boolean} devMode Operate in Dev-Mode - i.e. force outer refresh when encountering an existing TeraFy instance
 	* @property {Number} verbosity Verbosity level, the higher the more chatty TeraFY will be. Set to zero to disable all `debug()` call output
 	* @property {'detect'|'parent'|'child'|'popup'} mode How to communicate with TERA. 'parent' assumes that the parent of the current document is TERA, 'child' spawns an iFrame and uses TERA there, 'detect' tries parent and switches to `modeFallback` if communication fails
 	* @property {String} modeFallback Method to use when all method detection fails
-	* @property {Object<Object<Object>>} modeOverrides Settings to merge when in specific, named modes
+	* @property {Object<Object<Function>>} modeOverrides Functions to run when switching to specific modes, these are typically used to augment config. Called as `(config:Object)`
 	* @property {Number} modeTimeout How long entities have in 'detect' mode to identify themselves
 	* @property {String} siteUrl The TERA URL to connect to
 	* @property {String} restrictOrigin URL to restrict communications to
@@ -31,15 +32,19 @@ export default class TeraFy {
 	* @property {Array<String|Array<String>>} [debugPaths] List of paths (in either dotted or array notation) to enter debugging mode if a change is detected in dev mode e.g. `{debugPaths: ['foo.bar.baz']}`. This really slows down state writes so should only be used for debugging
 	*/
 	settings = {
+		session: null,
 		devMode: true,
 		verbosity: 1,
 		mode: 'detect',
 		modeTimeout: 300,
 		modeFallback: 'child', // ENUM: 'child' (use iframes), 'popup' (use popup windows)
 		modeOverrides: {
-			child: { // When we're in child mode assume a local dev environment and use the dev.tera-tools.com site instead to work around CORS restrictions
-				siteUrl: 'https://dev.tera-tools.com/embed',
-				restrictOrigin: '*',
+			child(config) { // When we're in child mode assume a local dev environment and use the dev.tera-tools.com site instead to work around CORS restrictions
+				if (config.siteUrl == 'https://tera-tools.com/embed') { // Only if we're using the default URL...
+					config.siteUrl = 'https://dev.tera-tools.com/embed'; // Repoint URL to dev site
+				} else { // If we're using some weird upstream allow all origins for postMessage
+					config.restrictOrigin = '*'; // Allow all upstream iframes
+				}
 			},
 		},
 		siteUrl: 'https://tera-tools.com/embed',
@@ -312,6 +317,13 @@ export default class TeraFy {
 	}
 
 
+	/**
+	* Transmit a patch to the remote server
+	* This function also enters debugging mode if any of the `settings.debugPaths` are operated on
+	*
+	* @param {Array} patch Patch to apply
+	* @returns {Promise} A promise which resolves when the operation has completed
+	*/
 	applyProjectStatePatch(patch) {
 		if (this.settings.devMode && this.settings.debugPaths) {
 			if (!Array.isArray(this.settings.debugPaths)) throw new Error('teraFyClient.settings.debugPaths should be either null or an Array<String>');
@@ -328,7 +340,9 @@ export default class TeraFy {
 			}
 		}
 
-		return this.rpc('applyProjectStatePatch', patch);
+		return this.rpc('applyProjectStatePatch', patch, {
+			session: this.settings.session,
+		});
 	}
 
 
@@ -373,7 +387,8 @@ export default class TeraFy {
 
 		const context = this;
 		return this.init.promise = Promise.resolve()
-			.then(()=> this.debug('INFO', 4, '[0/6] Init', this.settings.siteUrl))
+			.then(()=> this.settings.session ||= 'tfy-' + this.getEntropicString(16))
+			.then(()=> this.debug('INFO', 4, '[0/6] Init', 'Session', this.settings.session, 'against', this.settings.siteUrl))
 			.then(()=> { // Init various options for optimized access
 				if (!this.settings.devMode) return; // Not in dev mode
 				this.settings.debugPaths =
@@ -390,10 +405,12 @@ export default class TeraFy {
 			.then(()=> this.detectMode())
 			.then(mode => {
 				this.debug('INFO', 4, '[1/6] Setting client mode to', mode);
-				merge(this.settings, {
-					mode,
-					...this.settings.modeOverrides[mode], // Merge specific modeOverrides over the top of settings
-				});
+				this.settings.mode = mode;
+
+				if (this.settings.modeOverrides[mode]) {
+					this.debug('INFO', 4, '[1/6] Applying specific config overrides for mode', mode);
+					return this.settings.modeOverrides[mode](this.settings);
+				}
 			})
 			.then(()=> this.debug('INFO', 4, '[2/6] Injecting comms + styles + methods'))
 			.then(()=> Promise.all([
@@ -493,7 +510,7 @@ export default class TeraFy {
 
 			case 'parent':
 				this.debug('INFO', 2, 'Using TERA window parent');
-				break;
+				return Promise.resolve();
 
 			case 'popup':
 				this.debug('INFO', 2, 'Injecting TERA site as a popup window');
@@ -863,6 +880,22 @@ export default class TeraFy {
 		this.debug('INFO', 2, 'Request focus', {isFocused});
 		globalThis.document.body.classList.toggle('tera-fy-focus', isFocused === 'toggle' ? undefined : isFocused);
 	}
+
+
+
+	/**
+	* Generate random entropic character string in Base64
+	*
+	* @param {Number} [maxLength=32] Maximum lengh of the genrated string
+	* @returns {String}
+	*/
+	getEntropicString(maxLength = 32) {
+		const array = new Uint32Array(4);
+		window.crypto.getRandomValues(array);
+		return btoa(String.fromCharCode(...new Uint8Array(array.buffer)))
+			.replace(/[+/]/g, '') // Remove + and / characters
+			.slice(0, maxLength) // Trim
+	}
 	// }}}
 
 	// Stub documentation carried over from ./terafy.server.js {{{
@@ -1341,6 +1374,14 @@ export default class TeraFy {
 	*/
 
 
+	/**
+	* Trigger a fatal error, killing the outer TERA site
+	*
+	* @function uiDie
+	* @param {String} [text] Text to display
+	*/
+
+
 	/**
 	* Display, update or dispose of windows for long running tasks
 	* All options are cumulative - i.e. they are merged with other options previously provided

package/lib/terafy.server.js

@@ -878,12 +878,29 @@ export default class TeraFyServer {
 	* Apply a computed `just-diff` patch to the current project state
 	*
 	* @param {Object} patch Patch to apply
+	*
+	* @param {Object} [options] Additional options to mutate behaviour
+	* @param {String} [options.session] The transmitting session, if available. Avoids that session recieving a patch downwards after this one
+	*
 	* @returns {Promise} A promise which resolves when the operation has completed
 	*/
-	applyProjectStatePatch(patch) {
+	applyProjectStatePatch(patch, options) {
 		if (!app.service('$projects').active) throw new Error('No active project to patch');
 		this.debug('INFO', 1, 'Applying', patch.length, 'project state patch', patch);
-		diffApply(app.service('$projects').active, patch);
+
+		let $projects = app.service('$projects');
+		diffApply($projects.active, patch);
+
+		// Populate information about the last patch
+		$projects.active.lastPatch = {
+			date: (new Date).toJSON(),
+			user: app.service('$auth').user.id,
+			...(options?.session && { // Have session info?
+				session: options.session,
+			}),
+			patches: patch.length,
+		};
+		this.debug('INFO', 3, 'Applied patch to lastPatch status', $projects.active.lastPatch);
 
 		return Promise.resolve();
 	}
@@ -1504,6 +1521,17 @@ export default class TeraFyServer {
 	}
 
 
+	/**
+	* Trigger a fatal error, killing the outer TERA site
+	*
+	* @function uiDie
+	* @param {String} [text] Text to display
+	*/
+	uiDie(text) {
+		window.die(text);
+	}
+
+
 	/**
 	* Display, update or dispose of windows for long running tasks
 	* All options are cumulative - i.e. they are merged with other options previously provided

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iebh/tera-fy",
-  "version": "1.14.2",
+  "version": "1.15.0",
   "description": "TERA website worker",
   "scripts": {
     "dev": "esbuild --platform=browser --format=esm --bundle lib/terafy.client.js --outfile=dist/terafy.js --minify --serve --servedir=.",

package/plugins/vue2.js

@@ -1,4 +1,4 @@
-import {cloneDeep, isPlainObject} from 'lodash-es';
+import {cloneDeep, debounce, isPlainObject} from 'lodash-es';
 import TeraFyPluginBase from './base.js';
 
 /**
@@ -45,7 +45,9 @@ export default class TeraFyPluginVue2 extends TeraFyPluginBase {
 	* @param {String} [options.componentKey] Key within the component to attach the state. Defaults to a random string
 	* @param {Boolean} [options.autoRequire=true] Run `requireProject()` automatically before continuing
 	* @param {String|Boolean} [options.bindKey='project'] If set, creates the binding also as the specified key within the main Tera object, if falsy just returns the observable
+	* @param {Boolean} [options.read=true] Allow remote reactivity - update the local state when the server changes
 	* @param {Boolean} [options.write=true] Allow local reactivity to writes - send these to the server
+	* @param {Object} [options.throttle] Lodash debounce options + `wait` key used to throttle all writes, set to falsy to disable
 	*
 	* @returns {Promie<VueObservable<Object>>} A Vue.Observable object representing the project state
 	*/
@@ -54,7 +56,14 @@ export default class TeraFyPluginVue2 extends TeraFyPluginBase {
 			component: null,
 			componentKey: null,
 			autoRequire: true,
+			read: true,
 			write: true,
+			throttle: {
+				wait: 200,
+				maxWait: 2000,
+				leading: false,
+				trailing: true,
+			},
 			...options,
 		};
 
@@ -89,11 +98,17 @@ export default class TeraFyPluginVue2 extends TeraFyPluginBase {
 				settings.component[settings.componentKey] = stateObservable;
 
 				// Watch for remote changes and update
-				let skipUpdate = 0; // How many subsequent WRITE operations to ignore (set when reading)
 				if (settings.read) {
 					this.events.on(`update:projects/${stateObservable.id}`, newState => {
-						skipUpdate++; // Skip next update as we're updating our own state anyway
+						if (
+							newState?.lastPatch?.session // Last state change had a session worth noting
+							&& newState.lastPatch.session == this.settings.session  // The last state update was made FROM INSIDE THE BUILDING! BUWHAHAHA!
+						)
+							return; // Discard it, we don't care
+
+						// Everything else - patch the remote state locally
 						this.debug('INFO', 5, 'Update Vue2 Remote->Local', {new: newState, old: stateObservable});
+
 						this.merge(stateObservable, newState);
 					});
 				}
@@ -107,19 +122,19 @@ export default class TeraFyPluginVue2 extends TeraFyPluginBase {
 					//       snapshot
 					let oldVal = cloneDeep(snapshot);
 
+					// Function to handle the state update (can be debounced)
+					let watchHandle = newVal => {
+						this.debug('INFO', 5, 'Update Vue2 Local->Remote', {new: newVal, old: oldVal});
+						this.createProjectStatePatch(newVal, oldVal);
+						oldVal = cloneDeep(snapshot);
+					};
+
 					settings.component.$watch(
-						settings.componentKey,
-						newVal => {
-							if (skipUpdate > 0) {
-								skipUpdate--;
-								return;
-							}
-
-							this.debug('INFO', 5, 'Update Vue2 Local->Remote', {new: newVal, old: oldVal});
-							this.createProjectStatePatch(newVal, oldVal);
-							oldVal = cloneDeep(snapshot);
-						},
-						{
+						settings.componentKey, // State to watch
+						settings.throttle // Pointer to watchHandle which takes the new state (optionally throttled)
+							? debounce(watchHandle, settings.throttle.wait, settings.throttle)
+							: watchHandle,
+						{ // Watch options
 							deep: true,
 						},
 					);

package/plugins/vue3.js

@@ -1,4 +1,4 @@
-import {cloneDeep} from 'lodash-es';
+import {cloneDeep, debounce} from 'lodash-es';
 import TeraFyPluginBase from './base.js';
 import {reactive, watch} from 'vue';
 
@@ -33,6 +33,7 @@ export default class TeraFyPluginVue extends TeraFyPluginBase {
 	* @param {Boolean} [options.autoRequire=true] Run `requireProject()` automatically before continuing
 	* @param {Boolean} [options.read=true] Allow remote reactivity - update the local state when the server changes
 	* @param {Boolean} [options.write=true] Allow local reactivity to writes - send these to the server
+	* @param {Object} [options.throttle] Lodash debounce options + `wait` key used to throttle all writes, set to falsy to disable
 	*
 	* @returns {Promie<Reactive<Object>>} A reactive object representing the project state
 	*/
@@ -41,6 +42,12 @@ export default class TeraFyPluginVue extends TeraFyPluginBase {
 			autoRequire: true,
 			read: true,
 			write: true,
+			throttle: {
+				wait: 200,
+				maxWait: 2000,
+				leading: false,
+				trailing: true,
+			},
 			...options,
 		};
 
@@ -53,10 +60,15 @@ export default class TeraFyPluginVue extends TeraFyPluginBase {
 				let stateReactive = reactive(snapshot);
 
 				// Watch for remote changes and update
-				let skipUpdate = 0; // How many subsequent WRITE operations to ignore (set when reading)
 				if (settings.read) {
 					this.events.on(`update:projects/${stateReactive.id}`, newState => {
-						skipUpdate++; // Skip next update as we're updating our own state anyway
+						if (
+							newState?.lastPatch?.session // Last state change had a session worth noting
+							&& newState.lastPatch.session == this.settings.session  // The last state update was made FROM INSIDE THE BUILDING! BUWHAHAHA!
+						)
+							return; // Discard it, we don't care
+
+						// Everything else - patch the remote state locally
 						Object.assign(stateReactive, newState);
 					});
 				}
@@ -69,18 +81,18 @@ export default class TeraFyPluginVue extends TeraFyPluginBase {
 					//       snapshot
 					let oldVal = cloneDeep(snapshot);
 
+					// Function to handle the state update (can be debounced)
+					let watchHandle = newVal => {
+						this.createProjectStatePatch(newVal, oldVal);
+						oldVal = cloneDeep(newVal); // Update old state the the last seen value
+					};
+
 					watch(
-						stateReactive,
-						newVal => {
-							if (skipUpdate > 0) {
-								skipUpdate--;
-								return;
-							}
-
-							this.createProjectStatePatch(newVal, oldVal);
-							oldVal = cloneDeep(newVal); // Update old state the the last seen value
-						},
-						{
+						stateReactive, // State to watch
+						settings.throttle // Pointer to watchHandle which takes the new state (optionally throttled)
+							? debounce(watchHandle, settings.throttle.wait, settings.throttle)
+							: watchHandle,
+						{ // Watch options
 							deep: true,
 						},
 					);