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/base/channel.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 { Message } from './protocol.js';
+
+export class MessageChannel {
+
+	constructor (host) {
+		// https://developer.mozilla.org/en-US/docs/Web/API/URL/host
+		this._host = host;
+		this._pending = null;
+	}
+
+	async open () {
+		return new Promise((resolve, reject) => {
+			this._socket = new WebSocket(`ws://${this._host}`);
+
+			this._socket.onclose = () => this.onClose();
+
+			this._socket.onerror = (error) => this.onError(error);
+
+			this._socket.onmessage = (event) => {
+				const msg = Message.fromJsonText(event.data);
+
+				if (this._pending && (this._pending.nodeAddrId == msg.nodeAddrId)) {
+					this._pending.resolve(msg);
+					this._pending = null;
+				} else {
+					this.onMessage(msg, true);
+				}
+			};
+
+			this._socket.onopen = resolve;
+		});
+	}
+
+	close () {
+		this._socket.close();
+
+		if (this._pending) {
+			this._pending.reject(Error('MessageChannel: socket closed awaiting response'));
+			this._pending = null;
+		}
+	}
+
+	send (msg) {
+		if (this._socket) {
+			this._socket.send(msg.toJsonText());
+			this.onMessage(msg, false);
+		} else {
+			this.onError(Error('MessageChannel: cannot call send() before open()'));
+		}
+	}
+
+	async sendAndReceive (msg) {
+		return new Promise((resolve, reject) => {
+			this._pending = {resolve: resolve, reject: reject, nodeAddrId: msg.nodeAddrId};
+			this.send(msg);
+		});
+	}
+
+	onClose () {}
+	onError (error) {}
+	onMessage (msg, inbound) {}
+
+}

share/web_surfaces/shared/base/component.js

@@ -0,0 +1,93 @@
+/*
+ * 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 { Message } from './protocol.js';
+import { Observable } from './observable.js';
+
+export class Component extends Observable {
+
+ 	constructor (parent) {
+ 		super();
+ 		this._parent = parent;
+ 	}
+
+ 	get channel () {
+ 		return this._parent.channel;
+ 	}
+
+	on (property, callback) {
+		this.addObserver(property, (self) => callback(self[property]));
+	}
+
+ 	send (node, addr, val) {
+		this.channel.send(new Message(node, addr, val));
+ 	}
+
+ 	handle (node, addr, val) {
+ 		return false;
+ 	}
+
+ 	handleMessage (msg) {
+		return this.handle(msg.node, msg.addr, msg.val);
+	}
+
+	updateLocal (property, value) {
+		this['_' + property] = value;
+		this.notifyObservers(property);
+	}
+
+	updateRemote (property, value, node, addr) {
+		this['_' + property] = value;
+		this.send(node, addr || [], [value]);
+	}
+
+}
+
+export class RootComponent extends Component {
+
+	constructor (channel) {
+		super(null);
+		this._channel = channel;
+	}
+
+ 	get channel () {
+ 		return this._channel;
+ 	}
+
+}
+
+export class AddressableComponent extends Component {
+
+	constructor (parent, addr) {
+		super(parent);
+		this._addr = addr;
+	}
+ 	
+ 	get addr () {
+ 		return this._addr;
+ 	}
+
+ 	get addrId () {
+ 		return this._addr.join('-');
+ 	}
+
+	updateRemote (property, value, node) {
+		super.updateRemote(property, value, node, this.addr);
+	}
+
+}

share/web_surfaces/shared/base/observable.js

@@ -0,0 +1,64 @@
+/*
+ * 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.
+ */
+
+export class Observable {
+
+	constructor () {
+		this._observers = {};
+	}
+
+	addObserver (property, observer) {
+		// property=undefined means the caller is interested in observing all properties
+		if (!(property in this._observers)) {
+			this._observers[property] = [];
+		}
+
+		this._observers[property].push(observer);
+	}
+
+	removeObserver (property, observer) {
+		// property=undefined means the caller is not interested in any property anymore
+		if (typeof(property) == 'undefined') {
+			for (const property in this._observers) {
+				this.removeObserver(property, observer);
+			}
+		} else {
+			const index = this._observers[property].indexOf(observer);
+
+			if (index > -1) {
+				this._observers[property].splice(index, 1);
+			}
+		}
+	}
+
+	notifyObservers (property) {
+		// always notify observers that observe all properties
+		if (undefined in this._observers) {
+			for (const observer of this._observers[undefined]) {
+				observer(this, property);
+			}
+		}
+
+		if (property in this._observers) {
+			for (const observer of this._observers[property]) {
+				observer(this);
+			}
+		}
+	}
+
+}

share/web_surfaces/shared/base/protocol.js

@@ -0,0 +1,88 @@
+/*
+ * 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.
+ */
+
+export const JSON_INF = 1.0e+128;
+
+export const StateNode = Object.freeze({
+	TEMPO:                          'tempo',
+	POSITION_TIME:                  'position_time',
+	TRANSPORT_ROLL:                 'transport_roll',
+	RECORD_STATE:                   'record_state',
+	STRIP_DESCRIPTION:              'strip_description',
+	STRIP_METER:                    'strip_meter',
+	STRIP_GAIN:                     'strip_gain',
+	STRIP_PAN:                      'strip_pan',
+	STRIP_MUTE:                     'strip_mute',
+	STRIP_PLUGIN_DESCRIPTION:       'strip_plugin_description',
+	STRIP_PLUGIN_ENABLE:            'strip_plugin_enable',
+	STRIP_PLUGIN_PARAM_DESCRIPTION: 'strip_plugin_param_description',
+	STRIP_PLUGIN_PARAM_VALUE:       'strip_plugin_param_value'
+});
+
+export class Message {
+
+	constructor (node, addr, val) {
+		this.node = node;
+		this.addr = addr;
+		this.val = [];
+
+		for (const i in val) {
+			if (val[i] >= JSON_INF) {
+				this.val.push(Infinity);
+			} else if (val[i] <= -JSON_INF) {
+				this.val.push(-Infinity);
+			} else {
+				this.val.push(val[i]);
+			}
+		}
+	}
+
+	static nodeAddrId (node, addr) {
+		return [node].concat(addr || []).join('_');
+	}
+
+	static fromJsonText (jsonText) {
+		let rawMsg = JSON.parse(jsonText);
+		return new Message(rawMsg.node, rawMsg.addr || [], rawMsg.val);
+	}
+
+	toJsonText () {
+		let val = [];
+
+		for (const i in this.val) {
+			if (this.val[i] == Infinity) {
+				val.push(JSON_INF);
+			} else if (this.val[i] == -Infinity) {
+				val.push(-JSON_INF);
+			} else {
+				val.push(this.val[i]);
+			}
+		}
+		
+		return JSON.stringify({node: this.node, addr: this.addr, val: val});
+	}
+
+	get nodeAddrId () {
+		return Message.nodeAddrId(this.node, this.addr);
+	}
+
+	toString () {
+		return `${this.node} (${this.addr}) = ${this.val}`;
+	}
+
+}