@hitchy/plugin-odem-socket.io 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022 cepharum GmbH
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/api/services/odem/websocket-provider.js

@@ -0,0 +1,272 @@
+"use strict";
+
+module.exports = function() {
+	const api = this;
+
+	const logDebug = api.log( "hitchy:odem:socket.io:debug" );
+	const logError = api.log( "hitchy:odem:socket.io:error" );
+
+	/**
+	 * Implements API for controlling and monitoring server-side ODM via
+	 * websocket.
+	 */
+	class OdemWebsocketProvider {
+		/**
+		 * Integrates this provider with server-side websocket.
+		 *
+		 * @returns {void}
+		 */
+		static start() {
+			api.once( "websocket", io => {
+				const namespace = io.of( "/hitchy/odem" );
+
+				for ( const modelName of Object.keys( api.models ) ) {
+					const model = api.models[modelName];
+
+					this.manageModel( namespace, modelName, model );
+				}
+			} );
+		}
+
+		/**
+		 * Initializes manager for controlling and monitoring named model via
+		 * provided server-side websocket.
+		 *
+		 * @param {Server} io server-side websocket
+		 * @param {string} modelName name of model to manage
+		 * @param {class<Hitchy.Plugin.Odem.Model>} model ODM-based model instance to manage
+		 * @returns {void}
+		 */
+		static manageModel( io, modelName, model ) {
+			const { crud, notifications } = api.config.socket.odem;
+
+			this.handleModelRequests( crud, io, modelName, model );
+			this.forwardModelNotifications( notifications, io, modelName, model );
+		}
+
+		/**
+		 * Registers listeners for handling client-side events requesting
+		 * model-related actions.
+		 *
+		 * @param {boolean} enabled true if command handling is enabled in configuration
+		 * @param {Server} io server-side websocket
+		 * @param {string} modelName name of model to manage
+		 * @param {class<Hitchy.Plugin.Odem.Model>} model ODM-based model instance to manage
+		 * @returns {void}
+		 */
+		static handleModelRequests( enabled, io, modelName, model ) {
+			const prefix = api.utility.case.pascalToKebab( modelName );
+
+			if ( !enabled ) {
+				logDebug( "disabling socket-based action requests for model %s (%s)", modelName, prefix );
+
+				io.on( "connection", socket => {
+					socket
+						.on( `${prefix}:list`, ( _, __, ___, response ) => reject( response ) )
+						.on( `${prefix}:find`, ( _, __, ___, ____, response ) => reject( response ) )
+						.on( `${prefix}:create`, ( _, __, response ) => reject( response ) )
+						.on( `${prefix}:read`, ( _, __, response ) => reject( response ) )
+						.on( `${prefix}:update`, ( _, __, ___, response ) => reject( response ) )
+						.on( `${prefix}:delete`, ( _, __, response ) => reject( response ) );
+				} );
+
+				return;
+			}
+
+			logDebug( "enabling socket-based action requests for model %s (%s)", modelName, prefix );
+
+			io.on( "connection", socket => {
+				socket
+					.on( `${prefix}:list`, async( sessionId, queryOptions, uuidsOnly, response ) => {
+						logError( "request for listing %s instances w/ queryOptions %j and uuidsOnly %j", modelName, queryOptions, uuidsOnly );
+
+						try {
+							const meta = {};
+							const items = await model.list( queryOptions, { loadRecords: !uuidsOnly, metaCollector: meta } );
+
+							response( {
+								success: true,
+								count: meta.count,
+								items: items.map( item => ( uuidsOnly ? { uuid: item.uuid } : item.toObject( { serialized: true } ) ) ),
+							} );
+						} catch ( error ) {
+							logError( "listing %s instances failed: %s", modelName, error.stack );
+
+							response( {
+								error: error.message,
+							} );
+						}
+					} )
+					.on( `${prefix}:find`, async( sessionId, query, queryOptions, uuidsOnly, response ) => {
+						logError( "request for finding %s instances matching %j w/ queryOptions %j and uuidsOnly %j", modelName, query, queryOptions, uuidsOnly );
+
+						try {
+							const meta = {};
+							const items = await model.find( query, queryOptions, { loadRecords: !uuidsOnly, metaCollector: meta } );
+
+							response( {
+								success: true,
+								count: meta.count,
+								items: items.map( item => ( uuidsOnly ? { uuid: item.uuid } : item.toObject( { serialized: true } ) ) ),
+							} );
+						} catch ( error ) {
+							logError( "finding %s instances matching %j failed: %s", modelName, error.stack );
+
+							response( {
+								error: error.message,
+							} );
+						}
+					} )
+					.on( `${prefix}:create`, async( sessionId, properties, response ) => {
+						logError( "request for creating %s instance with %j", modelName, properties );
+
+						try {
+							const schema = model.schema;
+							const instance = new model; // eslint-disable-line new-cap
+
+							for ( const propName of Object.keys( properties ) ) {
+								if ( schema.props.hasOwnProperty( propName ) ||
+								     schema.computed.hasOwnProperty( propName ) ) {
+									instance[propName] = properties[propName];
+								}
+							}
+
+							await instance.save();
+
+							response( {
+								success: true,
+								properties: instance.toObject( { serialized: true } ),
+							} );
+						} catch ( error ) {
+							logError( "creating %s instance failed: %s", modelName, error.stack );
+
+							response( {
+								error: error.message,
+							} );
+						}
+					} )
+					.on( `${prefix}:read`, async( sessionId, uuid, response ) => {
+						logError( "request for reading %s instance %s", modelName, uuid );
+
+						try {
+							const instance = new model( uuid ); // eslint-disable-line new-cap
+							await instance.load();
+
+							response( {
+								success: true,
+								properties: instance.toObject( { serialized: true } ),
+							} );
+						} catch ( error ) {
+							logError( "reading %s instance failed: %s", modelName, error.stack );
+
+							response( {
+								error: error.message,
+							} );
+						}
+					} )
+					.on( `${prefix}:update`, async( sessionId, uuid, properties, response ) => {
+						logError( "request for updating %s instance %s with %j", modelName, uuid, properties );
+
+						try {
+							const instance = new model( uuid ); // eslint-disable-line new-cap
+							await instance.load();
+
+							for ( const propName of Object.keys( properties ) ) {
+								if ( model.schema.props.hasOwnProperty( propName ) || model.schema.computed.hasOwnProperty( propName ) ) {
+									instance[propName] = properties[propName];
+								}
+							}
+
+							await instance.save();
+
+							response( {
+								success: true,
+								properties: instance.toObject( { serialized: true } ),
+							} );
+						} catch ( error ) {
+							logError( "updating %s instance failed: %s", modelName, error.stack );
+
+							response( {
+								error: error.message,
+							} );
+						}
+					} )
+					.on( `${prefix}:delete`, async( sessionId, uuid, response ) => {
+						logError( "request for deleting %s instance %s", modelName, uuid );
+
+						try {
+							const instance = new model( uuid ); // eslint-disable-line new-cap
+							await instance.remove();
+
+							response( {
+								success: true,
+								properties: { uuid },
+							} );
+						} catch ( error ) {
+							logError( "deleting %s instance %s failed: %s", modelName, uuid, error.stack );
+
+							response( {
+								error: error.message,
+							} );
+						}
+					} );
+			} );
+		}
+
+		/**
+		 * Sets up listeners for model-related notifications in ODM and forwards
+		 * them as broadcast events to connected clients.
+		 *
+		 * @param {boolean} enabled true if command handling is enabled in configuration
+		 * @param {Server} io server-side websocket
+		 * @param {string} modelName name of model to manage
+		 * @param {class<Hitchy.Plugin.Odem.Model>} model ODM-based model instance to manage
+		 * @returns {void}
+		 */
+		static forwardModelNotifications( enabled, io, modelName, model ) {
+			if ( enabled ) {
+				const prefix = api.utility.case.pascalToKebab( modelName );
+
+				model.notifications
+					.on( "created", async( uuid, newRecord, asyncGeneratorFn ) => {
+						const event = {
+							change: "created",
+							properties: ( await asyncGeneratorFn() ).toObject( { serialized: true } ),
+						};
+
+						io.emit( `${prefix}:changed`, event );
+					} )
+					.on( "changed", async( uuid, newRecord, oldRecord, asyncGeneratorFn ) => {
+						const event = {
+							change: "updated",
+							properties: ( await asyncGeneratorFn() ).toObject( { serialized: true } ),
+						};
+
+						io.emit( `${prefix}:changed`, event );
+					} )
+					.on( "removed", uuid => {
+						const event = {
+							change: "deleted",
+							properties: { uuid: model.formatUUID( uuid ) },
+						};
+
+						io.emit( `${prefix}:changed`, event );
+					} );
+			}
+		}
+	}
+
+	return OdemWebsocketProvider;
+};
+
+/**
+ * Commonly responds to action requests in case of having disabled them.
+ *
+ * @param {function(response: any):void} respondFn callback to be invoked for responding to a peer event
+ * @returns {void}
+ */
+function reject( respondFn ) {
+	respondFn( {
+		error: "requested action is not available due to runtime configuration",
+	} );
+}

package/config/socket.js

@@ -0,0 +1,22 @@
+"use strict";
+
+module.exports = {
+	socket: {
+		odem: {
+			/**
+			 * Controls if server-side socket is handling client-side requests
+			 * for creating, reading, updating and deleting (CRUD) model items.
+			 *
+			 * Currently, this is false by default due to the lack of obeying
+			 * authorization control.
+			 */
+			crud: false,
+
+			/**
+			 * Controls if server-side socket is broadcasting events on
+			 * notifications emitted by either server-side model on change.
+			 */
+			notifications: true,
+		},
+	},
+};

package/hitchy.json

@@ -0,0 +1,8 @@
+{
+	"role": "odm-provider-websocket",
+	"appendFolders": false,
+	"dependencies": [
+		"odm",
+		"websocket"
+	]
+}

package/index.js

@@ -0,0 +1,11 @@
+"use strict";
+
+module.exports = function() {
+	const api = this;
+
+	return {
+		initialize() {
+			api.services.OdemWebsocketProvider.start();
+		},
+	};
+};

package/package.json

@@ -0,0 +1,47 @@
+{
+	"name": "@hitchy/plugin-odem-socket.io",
+	"version": "0.1.0",
+	"description": "exposing Hitchy's ODM via websocket",
+	"main": "index.js",
+	"scripts": {
+		"lint": "eslint .",
+		"test": "hitchy-pm odem socket.io --exec mocha --ui=tdd 'test/**/*.spec.js*'",
+		"coverage": "hitchy-pm odem socket.io --exec c8 mocha --ui=tdd 'test/**/*.spec.js*'"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://gitlab.com/hitchy/plugin-odem-socket.io.git"
+	},
+	"keywords": [
+		"Hitchy",
+		"socket.io",
+		"ODM"
+	],
+	"author": "cepharum GmbH",
+	"license": "MIT",
+	"bugs": {
+		"url": "https://gitlab.com/hitchy/plugin-odem-socket.io/issues"
+	},
+	"homepage": "https://gitlab.com/hitchy/plugin-odem-socket.io#readme",
+	"files": [
+		"api",
+		"config",
+		"hitchy.json",
+		"index.js"
+	],
+	"peerDependencies": {
+		"@hitchy/core": ">=0.7.2",
+		"@hitchy/plugin-odem": ">=0.7.1",
+		"@hitchy/plugin-socket.io": ">=0.1.0"
+	},
+	"devDependencies": {
+		"@hitchy/server-dev-tools": "^0.4.3",
+		"c8": "^7.11.2",
+		"eslint": "^8.14.0",
+		"eslint-config-cepharum": "^1.0.12",
+		"eslint-plugin-promise": "^6.0.0",
+		"mocha": "^9.2.2",
+		"should": "^13.2.3",
+		"socket.io-client": "^4.5.0"
+	}
+}

package/readme.md

@@ -0,0 +1,166 @@
+# @hitchy/plugin-odem-socket.io
+
+_exposing Hitchy's ODM via websocket_
+
+## License
+
+[MIT](LICENSE)
+
+## Installation
+
+```bash
+npm i @hitchy/plugin-odem-socket.io
+```
+
+This plugin relies on additional plugins to be installed as well:
+
+```bash
+npm i @hitchy/plugin-odem @hitchy/plugin-socket.io
+```
+
+
+## Usage
+
+### Basics
+
+This plugin is establishing an API via websocket for controlling and monitoring models of server-side ODM. Relying on particular features of [socket.io](https://socket.io/), this API is exposed in [namespace](https://socket.io/docs/v4/namespaces/) `/hitchy/odem`. 
+
+For every server-side model, request listeners and/or notification broadcasters are set up. Either model's name is converted into its kebab-case variant and used as colon-separated prefix in event names emitted either by the server or by a client. 
+
+> In the following sections, the placeholder `<modelName>` is used instead of that kebab-case variant of a model's name.
+
+### Control API
+
+> **Attention!**
+> 
+> As of v0.1.0, the control API is disabled by default due to the lack of having authorization checks implemented on server-side. You have to enable it explicitly by setting runtime configuration parameter `config.socket.odem.crud` which defaults to `false`.
+
+All action events listed in this section are to be sent by a client. The server is setting up listeners and directly responds to either received event. Thus, the common pattern on client side looks like this:
+
+```javascript
+const socket = io( "/hitchy/odem" );
+
+socket.on( "connect", () => {
+    socket.emit( actionName, sessionId, arg1, arg2, arg3, response => {
+        // process the response here
+    } );
+} );
+```
+
+> socket.io requires all arguments to be provided no matter what. Thus, you can't omit any of the arguments given in examples below but have to provide values assumed to be default, at least. 
+
+The following code excerpts are focusing on the inner part of emitting an action event and processing the response.
+
+In all these examples, a _sessionId_ is given. This is the current user's session ID usually found in a cookie set by a preceding HTTP request to authenticate the user. It is required on all requests to re-authenticate the user and to apply authorization checks to either request. It is okay to provide `null` here, however this might cause requests to be rejected based on server-side configuration.
+
+#### &lt;modelName>:list
+
+This request is the websocket variant of [Model.list()](https://odem.hitchy.org/api/model.html#model-list). 
+
+First argument following the session ID is forwarded as first argument to [Model.list()](https://odem.hitchy.org/api/model.html#model-list). The following argument is a boolean controlling if resulting list should provide UUID per listed match, only.
+
+```javascript
+socket.emit( "<modelName>:list", sessionId, { limit: 10 }, false, response => {
+    // - check for `response.success` or `response.error`
+    // - process total count of items in `response.count`
+    // - process requested excerpt of items in `response.items`
+} );
+```
+
+The `response` is an object consisting of truthy property `success` on success or `error` message in case of a failure. On success, property `count` is providing total count of matches and `items` is the list of matching items' properties.
+
+#### &lt;modelName>:find
+
+This request is searching for instances of selected model matching some query. It is invoking [Model.find()](https://odem.hitchy.org/api/model.html#model-find) internally passing the first two arguments following the session ID as-is. The third argument is limited to a boolean controlling whether only UUIDs should be listed or not.
+
+```javascript
+socket.emit( "<modelName>:find", sessionId, {}, { limit: 10 }, true, response => {
+    // - check for `response.success` or `response.error`
+    // - process total count of items in `response.count`
+    // - process requested excerpt of items in `response.items`
+} );
+```
+
+The `response` is an object consisting of truthy property `success` on success or `error` message in case of a failure. On success, property `count` is providing total count of matches and `items` is the selected excerpt from that list of matching items' each given by its properties including its UUID.
+
+#### &lt;modelName>:create
+
+This request is creating another instance of selected model assigning provided properties as initial values. Properties of instance to create are provided in event argument following the session ID.
+
+```javascript
+socket.emit( "<modelName>:create", sessionId, { title: "important things" }, response => {
+    // - check for `response.success` or `response.error`
+    // - process properties of eventually created instance in `response.properties`
+    // - created instance's UUID is available as `response.properties.uuid`
+} );
+```
+
+The `response` is an object consisting of truthy property `success` on success or `error` message in case of a failure. On success, `properties` of created instance are returned. These may be different from provided ones due to server-side constraints.
+
+#### &lt;modelName>:read
+
+This request is fetching a single instance's properties.
+
+```javascript
+socket.emit( "<modelName>:create", sessionId, "12345678-1234-1234-1234-123456789012", response => {
+    // - check for `response.success` or `response.error`
+    // - process properties of fetched instance in `response.properties`
+} );
+```
+
+The `response` is an object consisting of truthy property `success` on success or `error` message in case of a failure. On success, `properties` of selected instance are returned.
+
+#### &lt;modelName>:update
+
+This request is updating an existing instance of model. Following the session ID, the selected item's UUID and the values per property to be assigned are provided in follow-up arguments.
+
+```javascript
+socket.emit( "<modelName>:update", sessionId, "12345678-1234-1234-1234-123456789012", { prio: 1 }, response => {
+    // - check for `response.success` or `response.error`
+    // - process properties of eventually created instance in `response.properties`
+    // - created instance's UUID is available as `response.properties.uuid`
+} );
+```
+
+The `response` is an object consisting of truthy property `success` on success or `error` message in case of a failure. On success, `properties` of updated instance are returned. These may be different from provided ones due to server-side constraints.
+
+#### &lt;modelName>:delete
+
+This request is eventually completing the CRUD-support of this API by deleting an existing instance of model selected by its UUID in first argument.
+
+```javascript
+socket.emit( "<modelName>:delete", sessionId, "12345678-1234-1234-1234-123456789012", response => {
+    // - check for `response.success` or `response.error`
+    // - process properties of eventually created instance in `response.properties`
+    // - created instance's UUID is available as `response.properties.uuid`
+} );
+```
+
+The `response` is an object consisting of truthy property `success` on success or `error` message in case of a failure. On success, `properties` of updated instance are returned.
+
+
+### Notifications
+
+[ODM notifications](https://odem.hitchy.org/api/model.html#model-notifications) are forwarded as broadcast events named `<modelName>:changed`. Either event consists of 
+
+- a type of change and 
+- the changed item's properties (limited to its UUID on deletion).
+
+The type of change is
+
+* `created` on notifications about having created another instance of model,
+* `updated` on notifications about having adjusted one or more properties of an existing instance of model and
+* `deleted` on notifications about having removed an existing instance of model.
+
+In last case the provided set of properties is limited to the instance's UUID. The common pattern on client-side for listening to server-side notifications looks like this:
+
+```javascript
+const socket = io( "/hitchy/odem" );
+
+socket.on( "<modelName>:changed", info => {
+    // type of change is in `info.change`, e.g. "updated"
+    // process properties of changed instance in `info.properties`
+} );
+```
+
+> There may be server-side restriction applying per event or per instance of model, thus some or all notifications might be omitted.