WebSockets: implement a JavaScript object-oriented client API

Replace previous callback based basic client with an easier
to use object-oriented API that further abstracts the low level
details of the WebSockets Server surface messaging protocol.

All built-in web surface demos were updated to use the new API.

share/web_surfaces/shared/components/mixer.js

@@ -0,0 +1,87 @@
+/*
+ * Copyright © 2020 Luciano Iam <lucianito@gmail.com>
+ *
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation; either version 2 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License along
+ * with this program; if not, write to the Free Software Foundation, Inc.,
+ * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
+ */
+
+import { RootComponent } from '../base/component.js';
+import { StateNode } from '../base/protocol.js';
+import { Strip } from './strip.js';
+
+export class Mixer extends RootComponent {
+
+	constructor (channel) {
+		super(channel);
+		this._strips = {};
+		this._ready = false;
+	}
+
+	get ready () {
+		return this._ready;
+	}
+
+	get strips () {
+		return Object.values(this._strips);
+	}
+
+	getStripByName (name) {
+		name = name.trim().toLowerCase();
+		return this.strips.find(strip => strip.name.trim().toLowerCase() == name);
+	}
+
+ 	handle (node, addr, val) {
+ 		if (node.startsWith('strip')) {
+	 		if (node == StateNode.STRIP_DESCRIPTION) {
+	 			this._strips[addr] = new Strip(this, addr, val);
+	 			this.notifyObservers('strips');
+	 		} else {
+	 			const stripAddr = [addr[0]];
+	 			if (stripAddr in this._strips) {
+	 				this._strips[stripAddr].handle(node, addr, val);
+	 			} else {
+	 				return false;
+	 			}
+	 		}
+
+	 		return true;
+ 		}
+
+ 		/*
+		   RECORD_STATE signals all mixer initial state has been sent because
+		   it is the last message to arrive immediately after client connection,
+		   see WebsocketsDispatcher::update_all_nodes() in dispatcher.cc
+		  
+		   For this to work the mixer component needs to receive incoming
+		   messages before the transport component, otherwise the latter would
+		   consume RECORD_STATE.
+		  
+		   Some ideas for a better implementation of mixer readiness detection:
+		
+ 		   - Implement message bundles like OSC to pack all initial state
+ 		     updates into a single unit
+ 		   - Move *_DESCRIPTION messages to single message with val={JSON data},
+ 		     currently val only supports primitive data types
+ 		   - Append a termination or mixer ready message in update_all_nodes(),
+ 		     easiest but the least elegant
+		*/
+		
+		if (!this._ready && (node == StateNode.RECORD_STATE)) {
+ 			this.updateLocal('ready', true);
+		}
+
+ 		return false;
+ 	}
+
+}

share/web_surfaces/shared/components/parameter.js

@@ -0,0 +1,95 @@
+/*
+ * Copyright © 2020 Luciano Iam <lucianito@gmail.com>
+ *
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation; either version 2 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License along
+ * with this program; if not, write to the Free Software Foundation, Inc.,
+ * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
+ */
+
+import { AddressableComponent } from '../base/component.js';
+import { StateNode } from '../base/protocol.js';
+
+class ValueType {
+
+	constructor (rawType) {
+		this._rawType = rawType;
+	}
+
+	get isBoolean () {
+		return this._rawType == 'b';
+	}
+
+	get isInteger () {
+		return this._rawType == 'i';
+	}
+
+	get isDouble () {
+		return this._rawType == 'd';
+	}
+
+}
+
+export class Parameter extends AddressableComponent {
+
+	constructor (parent, addr, desc) {
+		super(parent, addr);
+		this._name = desc[0];
+		this._valueType = new ValueType(desc[1]);
+		this._min = desc[2];
+		this._max = desc[3];
+		this._isLog = desc[4];
+		this._value = 0;
+	}
+
+	get plugin () {
+		return this._parent;
+	}
+
+	get name () {
+		return this._name;
+	}
+
+	get valueType () {
+		return this._valueType;
+	}
+
+	get min () {
+		return this._min;
+	}
+
+	get max () {
+		return this._max;
+	}
+
+	get isLog () {
+		return this._isLog;
+	}
+
+	get value () {
+		return this._value;
+	}
+
+	set value (value) {
+		this.updateRemote('value', value, StateNode.STRIP_PLUGIN_PARAM_VALUE);
+	}
+
+ 	handle (node, addr, val) {
+		if (node == StateNode.STRIP_PLUGIN_PARAM_VALUE) {
+			this.updateLocal('value', val[0]);
+			return true;
+ 		}
+
+ 		return false;
+ 	}
+
+}

share/web_surfaces/shared/components/plugin.js

@@ -0,0 +1,72 @@
+/*
+ * Copyright © 2020 Luciano Iam <lucianito@gmail.com>
+ *
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation; either version 2 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License along
+ * with this program; if not, write to the Free Software Foundation, Inc.,
+ * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
+ */
+
+import { AddressableComponent } from '../base/component.js';
+import { Parameter } from './parameter.js';
+import { StateNode } from '../base/protocol.js';
+
+export class Plugin extends AddressableComponent {
+
+	constructor (parent, addr, desc) {
+		super(parent, addr);
+		this._parameters = {};
+		this._name = desc[0];
+		this._enable = false;
+	}
+
+	get strip () {
+		return this._parent;
+	}
+
+	get parameters () {
+		return Object.values(this._parameters);
+	}
+
+	get name () {
+		return this._name;
+	}
+
+	get enable () {
+		return this._enable;
+	}
+
+	set enable (value) {
+		this.updateRemote('enable', value, StateNode.STRIP_PLUGIN_ENABLE);
+	}
+
+ 	handle (node, addr, val) {
+		if (node.startsWith('strip_plugin_param')) {
+	 		if (node == StateNode.STRIP_PLUGIN_PARAM_DESCRIPTION) {
+	 			this._parameters[addr] = new Parameter(this, addr, val);
+	 			this.notifyObservers('parameters');
+	 		} else {
+	 			if (addr in this._parameters) {
+	 				this._parameters[addr].handle(node, addr, val);
+	 			}
+	 		}
+
+	 		return true;
+ 		} else if (node == StateNode.STRIP_PLUGIN_ENABLE) {
+ 			this.updateLocal('enable', val[0]);
+			return true;
+ 		}
+
+ 		return false;
+ 	}
+
+}

share/web_surfaces/shared/components/strip.js

@@ -0,0 +1,116 @@
+/*
+ * Copyright © 2020 Luciano Iam <lucianito@gmail.com>
+ *
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation; either version 2 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License along
+ * with this program; if not, write to the Free Software Foundation, Inc.,
+ * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
+ */
+
+import { AddressableComponent } from '../base/component.js';
+import { Plugin } from './plugin.js';
+import { StateNode } from '../base/protocol.js';
+
+export class Strip extends AddressableComponent {
+
+	constructor (parent, addr, desc) {
+		super(parent, addr);
+		this._plugins = {};
+		this._name = desc[0];
+		this._isVca = desc[1];
+		this._meter = 0;
+		this._gain = 0;
+		this._pan = 0;
+		this._mute = false;
+	}
+
+	get plugins () {
+		return Object.values(this._plugins);
+	}
+
+	get name () {
+		return this._name;
+	}
+
+	get isVca () {
+		return this._isVca;
+	}
+
+	get meter () {
+		return this._meter;
+	}
+
+	get gain () {
+		return this._gain;
+	}
+
+	set gain (db) {
+		this.updateRemote('gain', db, StateNode.STRIP_GAIN);
+	}
+
+	get pan () {
+		return this._pan;
+	}
+
+	set pan (value) {
+		this.updateRemote('pan', value, StateNode.STRIP_PAN);
+	}
+
+	get mute () {
+		return this._mute;
+	}
+
+	set mute (value) {
+		this.updateRemote('mute', value, StateNode.STRIP_MUTE);
+	}
+
+ 	handle (node, addr, val) {
+ 		if (node.startsWith('strip_plugin')) {
+	 		if (node == StateNode.STRIP_PLUGIN_DESCRIPTION) {
+
+	 			this._plugins[addr] = new Plugin(this, addr, val);
+	 			this.notifyObservers('plugins');
+	 		} else {
+	 			const pluginAddr = [addr[0], addr[1]];
+	 			if (pluginAddr in this._plugins) {
+	 				this._plugins[pluginAddr].handle(node, addr, val);
+	 			} else {
+	 				return false;
+	 			}
+	 		}
+
+	 		return true;
+ 		} else {
+ 			switch (node) {
+ 				case StateNode.STRIP_METER:
+	 				this.updateLocal('meter', val[0]);
+ 					break;
+ 				case StateNode.STRIP_GAIN:
+	 				this.updateLocal('gain', val[0]);
+ 					break;
+  				case StateNode.STRIP_PAN:
+	 				this.updateLocal('pan', val[0]);
+ 					break;
+  				case StateNode.STRIP_MUTE:
+	 				this.updateLocal('mute', val[0]);
+ 					break;
+ 				default:
+ 					return false;
+ 			}
+
+  			return true;
+ 		}
+
+ 		return false;
+ 	}
+
+}

share/web_surfaces/shared/components/transport.js

@@ -0,0 +1,81 @@
+/*
+ * Copyright © 2020 Luciano Iam <lucianito@gmail.com>
+ *
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation; either version 2 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License along
+ * with this program; if not, write to the Free Software Foundation, Inc.,
+ * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
+ */
+
+import { RootComponent } from '../base/component.js';
+import { StateNode } from '../base/protocol.js';
+
+export class Transport extends RootComponent {
+
+	constructor (channel) {
+		super(channel);
+		this._time = 0;
+		this._tempo = 0;
+		this._roll = false;
+		this._record = false;
+	}
+	
+	get time () {
+		return this._time;
+	}
+
+	get tempo () {
+		return this._tempo;
+	}
+
+	set tempo (bpm) {
+		this.updateRemote('tempo', bpm, StateNode.TEMPO);
+	}
+
+	get roll () {
+		return this._roll;
+	}
+
+	set roll (value) {
+		this.updateRemote('roll', value, StateNode.TRANSPORT_ROLL);
+	}
+
+	get record () {
+		return this._record;
+	}
+
+	set record (value) {
+		this.updateRemote('record', value, StateNode.RECORD_STATE);
+	}
+
+ 	handle (node, addr, val) {
+ 		switch (node) {
+ 			case StateNode.TEMPO:
+ 				this.updateLocal('tempo', val[0]);
+ 				break;
+ 			case StateNode.POSITION_TIME:
+ 				this.updateLocal('time', val[0]);
+ 				break;
+ 			case StateNode.TRANSPORT_ROLL:
+ 				this.updateLocal('roll', val[0]);
+ 				break;
+ 			case StateNode.RECORD_STATE:
+ 				this.updateLocal('record', val[0]);
+ 				break;
+ 			default:
+ 				return false;
+ 		}
+
+ 		return true;
+ 	}
+
+}