@dra2020/baseclient 1.0.0

package/lib/ot-js/otclientengine.ts

@@ -0,0 +1,327 @@
+// Shared libraries
+import * as LogAbstract from "../logabstract/all";
+
+import * as OT from "./ottypes";
+import * as OTC from "./otcomposite";
+import * as OTE from "./otengine";
+
+export class OTClientEngine extends OTE.OTEngine
+{
+	// Data members
+	clientID: string;
+	resourceID: string;
+	isNeedAck: boolean;
+	isNeedResend: boolean;
+  bReadOnly: boolean;
+	clientSequenceNo: number;
+	stateServer: OTC.OTCompositeResource;
+	stateLocal: OTC.OTCompositeResource;
+  valCache: any;
+  prefailCache: any;
+
+	actionAllClient: OTC.OTCompositeResource;
+	actionAllPendingClient: OTC.OTCompositeResource;
+	actionSentClient: OTC.OTCompositeResource;
+	actionSentClientOriginal: OTC.OTCompositeResource;
+	actionServerInterposedSentClient: OTC.OTCompositeResource;
+
+	// Constructor
+	constructor(ilog: LogAbstract.ILog, rid: string, cid: string)
+		{
+      super(ilog);
+
+			this.resourceID = rid;
+			this.clientID = cid;
+			this.initialize();
+      this.bReadOnly = false;
+      this.valCache = {};
+		}
+
+	initialize(): void
+		{
+      if (this.prefailCache === undefined && this.clientSequenceNo > 0)
+        this.prefailCache = this.valCache;
+			this.clientSequenceNo = 0;
+			this.isNeedAck = false;
+			this.isNeedResend = false;
+			this.actionAllClient = new OTC.OTCompositeResource(this.resourceID, this.clientID);
+			this.actionAllPendingClient = new OTC.OTCompositeResource(this.resourceID, this.clientID);
+			this.actionSentClient = new OTC.OTCompositeResource(this.resourceID, this.clientID);
+			this.actionSentClientOriginal = new OTC.OTCompositeResource(this.resourceID, this.clientID);
+			this.actionServerInterposedSentClient = new OTC.OTCompositeResource(this.resourceID, this.clientID);
+			this.stateServer = new OTC.OTCompositeResource(this.resourceID, this.clientID);
+			this.stateLocal = new OTC.OTCompositeResource(this.resourceID, this.clientID);
+		}
+
+	// Members
+	serverClock(): number
+		{
+			return this.stateServer.clock;
+		}
+
+  rid(): string
+    {
+      return this.resourceID;
+    }
+
+  cid(): string
+    {
+      return this.resourceID;
+    }
+
+  toPartialValue(resourceName: string): any
+    {
+      return this.valCache[resourceName];
+    }
+
+	toValue(): any
+		{
+			return this.valCache;
+		}
+
+  toPrefailValue(): any
+    {
+      return this.prefailCache;
+    }
+
+  clearPrefail(): void
+    {
+      delete this.prefailCache;
+    }
+
+  setReadOnly(b: boolean): void
+    {
+      if (b != this.bReadOnly)
+      {
+        this.bReadOnly = b;
+        if (this.bReadOnly)
+          this.failbackToServerState();
+      }
+    }
+
+  startLocalEdit(): OTC.OTCompositeResource
+    {
+      return new OTC.OTCompositeResource(this.resourceID, this.clientID);
+    }
+
+	isPending(): boolean
+		{
+			return this.isNeedResend || !this.actionAllPendingClient.isEmpty();
+		}
+
+	getPending(): OTC.OTCompositeResource
+		{
+			if (!this.isNeedResend && this.actionAllPendingClient.isEmpty())
+				return null;
+			else
+			{
+				// If "isNeedResend" I need to send the exact same event (instead of aggregating all pending)
+				// because the server might have actually received and processed the event and I just didn't
+				// receive acknowledgement. If I merge that event into others I'll lose ability to distinguish
+				// that. Eventually when I re-establish communication with server I will get that event response
+				// and can then move on.
+				if (! this.isNeedResend)
+				{
+					this.actionSentClient = this.actionAllPendingClient.copy();
+          //console.log(`ClientEngine:getPending: bump sequence count from ${this.clientSequenceNo}`);
+					this.actionSentClient.clientSequenceNo = this.clientSequenceNo++;
+					this.actionAllPendingClient.empty();
+				}
+				this.actionSentClient.clock = this.stateServer.clock;
+				this.actionSentClientOriginal = this.actionSentClient.copy();
+				this.actionServerInterposedSentClient.empty();
+				this.isNeedAck = true;
+				this.isNeedResend = false;
+				return this.actionSentClient.copy();
+			}
+		}
+
+	// When I fail to send, I need to reset to resend the event again
+	resetPending(): void
+		{
+			if (this.isNeedAck)
+			{
+				this.isNeedAck = false;
+				this.isNeedResend = true;
+        //console.log('otclientengine: resetPending');
+			}
+      //else
+       // console.log('otclientengine: resetPending ignored because isNeedAck false');
+		}
+
+	// When I don't accurately have server state - will then refresh from server
+	failbackToInitialState(): void
+		{
+      console.log('otclientengine: failbackToInitialState');
+      if (this.prefailCache === undefined)
+        this.prefailCache = this.valCache;
+			this.initialize();
+		}
+
+	// When I have server state but my state got mixed up
+	failbackToServerState(): void
+		{
+      console.log('otclientengine: failbackToServerState');
+      if (this.prefailCache === undefined)
+        this.prefailCache = this.valCache;
+			this.stateLocal = this.stateServer.copy();
+			this.isNeedAck = false;
+			this.actionSentClient.empty();
+			this.actionSentClientOriginal.empty();
+			this.actionServerInterposedSentClient.empty();
+			this.actionAllPendingClient.empty();
+			this.actionAllClient.empty();
+      this.valCache = this.stateLocal.toValue();
+      this.emit('state');
+		}
+
+	//
+	// Function: OTClientEngine.addRemote
+	//
+	// Description:
+	//	This function is really where the action is in managing the dynamic logic of applying OT. This is run
+	//	on each end point and handles the events received from the server. This includes server acknowledgements
+	//	(both success and failure) of locally generated events as well as all the events generated from other
+	//	clients.
+	//
+	//	The key things that happen here are:
+	//		1. Track server state.
+	//		2. Respond to server acknowledgement of locally generated events. This also includes validation
+	//			(with failback code) in case where server transformed my event in a way that was inconsistent
+	//			with what I expected (due to insert collision that arose due to multiple independent events).
+	//		3. Transform the incoming event (by local events) so it can be applied to local state.
+	//		4. Transform pending local events so they can be dispatched to the service once the service
+	//			is ready for another event.
+	//
+
+	addRemote(orig: OTC.OTCompositeResource): void
+		{
+			// Reset if server forces restart
+			if (orig.clock == OTC.clockInitialValue)
+			{
+				this.failbackToInitialState();
+				return;
+			}
+
+			// Reset if server restarted and we don't sync up
+			if (orig.clock < 0)
+			{
+				// If server didn't lose anything I can just keep going...
+				if (this.stateServer.clock+1 == -orig.clock)
+					orig.clock = - orig.clock
+				else
+				{
+					this.failbackToInitialState();
+					return;
+				}
+			}
+
+			// Ignore if I've seen this event already
+			if (orig.clock <= this.serverClock())
+			{
+				return;
+			}
+
+			let bMine: boolean = orig.clientID == this.clientID;
+			let bResend: boolean = bMine && orig.clock == OTC.clockFailureValue;
+			let a: OTC.OTCompositeResource = orig.copy();
+
+			if (bResend)
+			{
+				// Service failed my request. Retry with currently outstanding content.
+				this.resetPending();
+				return;
+			}
+
+			try
+			{
+				// Track server state and clock
+				this.stateServer.compose(a);
+
+				if (bMine)
+				{
+					// Validate that I didn't run into unresolvable conflict
+					if (! this.actionServerInterposedSentClient.isEmpty())
+					{
+						this.actionSentClientOriginal.transform(this.actionServerInterposedSentClient, true);
+						if (! this.actionSentClient.effectivelyEqual(this.actionSentClientOriginal))
+						{
+							this.failbackToServerState();
+						}
+					}
+
+					// I don't need to apply to local state since it has already been applied - this is just an ack.
+					this.isNeedAck = false;
+					this.actionSentClient.empty();
+					this.actionSentClientOriginal.empty();
+					this.actionServerInterposedSentClient.empty();
+					this.actionAllClient = this.actionAllPendingClient.copy();
+				}
+				else
+				{
+					// Transform server action to apply locally by transforming by all pending client actions
+					a.transform(this.actionAllClient, false);
+
+					// And then compose with local state
+					this.stateLocal.compose(a);
+
+					// Transform pending client by server action so it is rooted off the server state.
+					// This ensures that I can convert the next server action I receive.
+					this.actionAllClient.transform(orig, true);
+
+					// Transform server action to be after previously sent client action and then
+					// transform the unsent actions so they are ready to be sent.
+					let aServerTransformed: OTC.OTCompositeResource = orig.copy();
+					aServerTransformed.transform(this.actionSentClient, false);
+					this.actionAllPendingClient.transform(aServerTransformed, true);
+
+					// And then transform the sent client action so ready to be used for transforming next server event
+					this.actionSentClient.transform(orig, true);
+
+					// Track server operations interposed between a sent action
+					if (this.isNeedAck)
+						this.actionServerInterposedSentClient.compose(orig);
+
+          // Let clients know
+          this.valCache = this.stateLocal.toValue();
+          this.emit('state');
+				}
+			}
+			catch (err)
+			{
+        this.ilog.error("OTClientEngine.addRemote: unexpected exception: " + err);
+				this.failbackToInitialState();
+			}
+		}
+
+	//
+	// Function: addLocalEdit
+	//
+	// Description:
+	//	This is the logic for adding an action to the local state. The logic is straight-forward
+	//	as we need to track:
+	//		1. The composed set of unacknowledged locally generated events.
+	//		2. The composed set of unsent locally generated events (queued until sent event is acknowledged).
+	//		3. The local state.
+	//		4. An undo operation.
+	//
+	addLocalEdit(orig: OTC.OTCompositeResource): void
+		{
+      if (! this.bReadOnly)
+      {
+        try
+        {
+          this.actionAllClient.compose(orig);
+          this.actionAllPendingClient.compose(orig);
+          this.stateLocal.compose(orig);
+          this.valCache = this.stateLocal.toValue();
+          this.emit('state');
+        }
+        catch (err)
+        {
+          this.ilog.error("OTClientEngine.addLocalEdit: unexpected exception: " + err);
+          this.failbackToInitialState();
+        }
+      }
+		}
+};

package/lib/ot-js/otcomposite.ts

@@ -0,0 +1,247 @@
+import * as OT from "./ottypes";
+import * as OTA from "./otarray";
+import * as OTM from "./otmap";
+import * as OTC from "./otcounter";
+
+export const clockInitialValue: number = -1;		// Initial value
+export const clockTerminateValue: number = -2;		// Terminal action from client.
+export const clockRandomizeValue: number = -3;		// Fill in with random data.
+export const clockFailureValue: number = -4;		// Server failed to apply
+export const clockInitializeValue: number = -5;		// Used to initialize client to a specific string value.
+export const clockUndoValue: number = -6;			// Used to indicate we should generate an undo event.
+export const clockSeenValue: number = -7;			// Server has already seen this event
+
+export class OTCompositeResource extends OT.OTResourceBase
+{
+	resourceID: string;
+	clientID: string;
+	clock: number;
+	clientSequenceNo: number;
+	static typeRegistry: any;
+
+	constructor(rid: string, cid: string)
+		{
+			super('root', 'composite');
+			this.resourceID = rid;
+			this.clientID = cid;
+			this.clock = clockInitialValue;
+			this.clientSequenceNo = 0;
+		}
+
+	static registerType(underlyingType: string, factory: (resourceName: string) => OT.OTResourceBase): void
+		{
+			if (OTCompositeResource.typeRegistry == null)
+				OTCompositeResource.typeRegistry = { };
+			OTCompositeResource.typeRegistry[underlyingType] = factory;
+		}
+
+	findResource(rname: string, utype: string = '', bConstruct: boolean = false): OT.IOTResource
+		{
+			for (let i: number = this.length-1; i >= 0; i--)
+				if (this.edits[i].resourceName === rname)
+					return this.edits[i];
+			if (bConstruct)
+			{
+				let edit: OT.IOTResource = OTCompositeResource.constructResource(rname, utype);
+				this.edits.push(edit);
+				return edit;
+			}
+			else
+				return null;
+		}
+
+  map(rid: string): OTM.OTMapResource
+    {
+      return this.findResource(rid, 'map', true) as OTM.OTMapResource;
+    }
+
+  array(rid: string): OTA.OTArrayResource
+    {
+      return this.findResource(rid, 'array', true) as OTA.OTArrayResource;
+    }
+
+  counter(rid: string): OTC.OTCounterResource
+    {
+      return this.findResource(rid, 'counter', true) as OTC.OTCounterResource;
+    }
+
+	garbageCollect(map: any): boolean
+		{
+			if (map)
+			{
+				let bDirty: boolean = false;
+				for (let i: number = this.length-1; i >= 0; i--)
+				{
+					if (map[this.edits[i].resourceName] === undefined)
+					{
+						this.edits.splice(i, 1);
+						bDirty = true;
+					}
+				}
+				return bDirty;
+			}
+			else
+				return false;	// If no resource map, we don't garbage collect
+		}
+
+	isEmpty(): boolean
+		{
+			// Canonical empty is an empty edits array, but an array of empty edits is always considered empty
+			for (let i: number = 0; i < this.length; i++)
+				if (! this.edits[i].isEmpty())
+					return false;
+			return true;
+		}
+
+	// Copy an instance
+	copy(): OTCompositeResource
+		{
+			let c: OTCompositeResource = new OTCompositeResource(this.resourceID, this.clientID);
+			c.clock = this.clock;
+			c.clientSequenceNo = this.clientSequenceNo;
+			for (let i: number = 0; i < this.length; i++)
+				c.edits.push(this.edits[i].copy());
+			return c;
+		}
+
+	// Test whether two operations are effectively equivalent
+	effectivelyEqual(rhs: OTCompositeResource): boolean
+		{
+			// This should really be a structural error
+			if (this.length != rhs.length)
+				return false;
+			for (let i: number = 0; i < this.length; i++)
+			{
+				let lhsEdit: OT.IOTResource = this.edits[i];
+				let rhsEdit: OT.IOTResource = rhs.findResource(lhsEdit.resourceName);
+
+				if ((rhsEdit == null && !lhsEdit.isEmpty()) || ! lhsEdit.effectivelyEqual(rhsEdit))
+					return false;
+			}
+			return true;
+		}
+
+	// Core OT algorithm for this type
+	transform(rhs: OTCompositeResource, bPriorIsService: boolean): void
+		{
+			for (let i: number = 0; i < rhs.length; i++)
+			{
+				let rhsEdit: OT.IOTResource = rhs.edits[i];
+				let lhsEdit: OT.IOTResource = this.findResource(rhsEdit.resourceName, rhsEdit.underlyingType, false);
+				if (lhsEdit)
+					lhsEdit.transform(rhsEdit, bPriorIsService);
+			}
+		}
+
+	// compose two edit actions
+	compose(rhs: OTCompositeResource): void 			// throws on error
+		{
+			for (let i: number = 0; i < rhs.length; i++)
+			{
+				let rhsEdit: OT.IOTResource = rhs.edits[i];
+
+				let lhsEdit: OT.IOTResource = this.findResource(rhsEdit.resourceName, rhsEdit.underlyingType, !rhsEdit.isEmpty());
+				if (lhsEdit)
+					lhsEdit.compose(rhsEdit);
+			}
+
+			this.clock = rhs.clock;
+			this.clientSequenceNo = rhs.clientSequenceNo;
+		}
+
+	// apply this edit to an existing value, returning new value (if underlying type is mutable, may modify input)
+	// For composite, takes array of values, returns array of results, one for each underlying resource.
+	apply(runningValue: any): any
+		{
+			if (runningValue == null)
+				runningValue = { };
+			for (let i: number = 0; i < this.length; i++)
+			{
+				let e: OT.IOTResource = this.edits[i];
+				runningValue[e.resourceName] = e.apply(runningValue[e.resourceName]);
+			}
+			return runningValue;
+		}
+
+  toPartialValue(resourceName: string): any
+    {
+      let e = this.edits.find(e => e.resourceName === resourceName);
+      return e ? e.apply(null) : null;
+    }
+
+	toValue(): any
+		{
+			return this.apply(null);
+		}
+
+	minimize(): void
+		{
+			for (let i: number = 0; i < this.length; i++)
+				this.edits[i].minimize();
+		}
+
+	static constructResource(rname: string, utype: string): OT.IOTResource
+		{
+			if (OTCompositeResource.typeRegistry == null)
+			{
+				//throw "OTCompositeResource.constructResource: no registered factories";
+				// This is only place where Composite type knows of other types - could hoist to outer level
+				OTCompositeResource.registerType('string', OTA.OTStringResource.factory);
+				OTCompositeResource.registerType('array', OTA.OTArrayResource.factory);
+				OTCompositeResource.registerType('map', OTM.OTMapResource.factory);
+				OTCompositeResource.registerType('counter', OTC.OTCounterResource.factory);
+			}
+
+			let factory: (resourceName: string) => OT.OTResourceBase = OTCompositeResource.typeRegistry[utype];
+			if (factory == null)
+				throw "OTCompositeResource.constructResource: no registered factory for " + utype;
+			return factory(rname);
+		}
+
+	// Deserialization
+	static constructFromObject(o: any): OTCompositeResource
+		{
+			let cedit: OTCompositeResource = new OTCompositeResource("", "");
+			if (o['resourceID'] !== undefined)
+				cedit.resourceID = o['resourceID'];
+			if (o['clientID'] !== undefined)
+				cedit.clientID = o['clientID'];
+			if (o['clock'] !== undefined)
+				cedit.clock = Number(o['clock']);
+			if (o['clientSequenceNo'] !== undefined)
+				cedit.clientSequenceNo = Number(o['clientSequenceNo']);
+			if (o['edits'] !== undefined)
+			{
+				let arrEdits: any = o['edits'];
+				for (let i: number = 0; i < arrEdits.length; i++)
+				{
+					let a: any = arrEdits[i];
+					let rname: string = a['resourceName'];
+					let utype: string = a['underlyingType'];
+					let edit: OT.IOTResource = this.constructResource(rname, utype);
+					edit.edits = a['edits'];
+					cedit.edits.push(edit);
+				}
+			}
+			return cedit;
+		}
+
+	// Serialization
+	toJSON(): any
+		{
+			let o: any = {
+				"resourceID": this.resourceID,
+				"clientID": this.clientID,
+				"clock": this.clock,
+				"clientSequenceNo": this.clientSequenceNo,
+				"edits": [] };
+			for (let i: number = 0; i < this.length; i++)
+			{
+				let edit: OT.IOTResource = this.edits[i];
+				let oEdit: any = { "resourceName": edit.resourceName, "underlyingType": edit.underlyingType, "edits": edit.edits };
+				o["edits"].push(oEdit);
+			}
+			return o;
+		}
+
+}

package/lib/ot-js/otcounter.ts

@@ -0,0 +1,145 @@
+import * as OT from "./ottypes";
+
+// This implements OT for a simple map of counters. Instead of a new value replacing the 
+// keyed value, values are added together. This allows a simple accumulating counter.
+// Possible future additions:
+//	Add additional semantics for how the values accumulate. Examples from DropBox's datastore API
+//	included "min" and "max" as alternate rules to "sum".
+//
+
+export const OpCounterAdd = 1;
+export const OpCounterDel = 2;
+export type CounterEdit = [ number, string, any ];	// Op, Key, Value
+
+export class OTCounterResource extends OT.OTResourceBase
+{
+	constructor(rid: string)
+		{
+			super(rid, 'counter');
+		}
+	static factory(rid: string): OTCounterResource { return new OTCounterResource(rid); }
+
+	// copy an instance
+	copy(): OTCounterResource
+		{
+			let c: OTCounterResource = new OTCounterResource(this.resourceName);
+			for (let i: number = 0; i < this.length; i++)
+			{
+				let e: CounterEdit = this.edits[i];
+				c.edits.push([ e[0], e[1], e[2] ]);
+			}
+			return c;
+		}
+
+	// Test whether two operations are effectively equivalent
+	effectivelyEqual(rhs: OTCounterResource): boolean
+		{
+			// This should really be a structural error
+			if (this.length != rhs.length)
+				return false;
+
+			// This checks for exact structural equivalency. Really the ordering shouldn't matter for Counter so
+			// an improvement to this algorithm would be to be more robust to ordering differences.
+			for (let i: number = 0; i < this.length; i++)
+			{
+				let e1: CounterEdit = this.edits[i];
+				let e2: CounterEdit = rhs.edits[i];
+				if (e1[0] != e2[0] || e1[1] != e2[1] || e1[2] != e2[2])
+					return false;
+			}
+			return true;
+		}
+
+	// Core OT algorithm for this type
+	transform(prior: OTCounterResource, bPriorIsService: boolean): void
+		{
+			// Last wins - if I'm last, my adds and deletes are all preserved
+			if (bPriorIsService)
+				return;
+
+			// Deletes in prior will delete mine. Implement by loading up properties rather than
+			// using N^2 lookup through Edits array.
+			let myEdits: any = this.toObject();
+			let bEdited: boolean = false;
+
+			// Now delete any that are deleted by prior.
+			for (let i: number = 0; i < prior.length; i++)
+			{
+				let eP: CounterEdit = prior.edits[i];
+				if (eP[0] == OpCounterDel)
+				{
+					delete myEdits[eP[1]];
+					bEdited = true;
+				}
+			}
+
+			// Now restore edit array from edited object
+			if (bEdited)
+				this.fromObject(myEdits);
+		}
+
+	// compose two edit actions
+	compose(rhs: OTCounterResource): void 			// throws on error
+		{
+			let lhsKeys: any = this.toObject();
+			let rhsKeys: any = rhs.toObject();
+			for (let i: number = 0; i < rhs.length; i++)
+			{
+				let eR: CounterEdit = rhs.edits[i];
+				let eL: CounterEdit = lhsKeys[eR[1]];
+				if (eL === undefined)
+					lhsKeys[eR[1]] = [ eR[0], eR[1], eR[2] ];
+				else
+					eL[2] += eR[2];
+			}
+			this.fromObject(lhsKeys);
+		}
+
+	apply(startValue: any): any
+		{
+			if (startValue == null)
+				startValue = { };
+			for (let i: number = 0; i < this.length; i++)
+			{
+				let e: CounterEdit = this.edits[i];
+				switch (e[0])
+				{
+					case OpCounterAdd:
+						if (startValue[e[1]] === undefined)
+							startValue[e[1]] = e[2];
+						else
+							startValue[e[1]] += e[2];
+						break;
+					case OpCounterDel:
+						delete startValue[e[1]];
+						break;
+				}
+			}
+			return startValue;
+		}
+
+	minimize(): any
+		{
+			// No-op
+		}
+
+	loadObject(o: any): any
+		{
+			for (let i: number = 0; i < this.length; i++)
+				o[(this.edits[i])[1]] = this.edits[i];
+			return o;
+		}
+
+	toObject(): any
+		{
+			return this.loadObject({ });
+		}
+
+	fromObject(o: any): void
+		{
+			this.edits = [];
+			for (var p in o)
+				if (o.hasOwnProperty(p))
+					this.edits.push(o[p]);
+		}
+}