@hitchy/plugin-odem-socket.io 0.2.2 → 0.2.4

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

@@ -7,8 +7,8 @@ module.exports = function() {
 	const logError = api.log( "hitchy:odem:socket.io:error" );
 
 	/**
-	 * Implements API for controlling and monitoring server-side ODM via
-	 * websocket.
+	 * Implements API for controlling and monitoring server-side
+	 * document-oriented database via websocket.
 	 */
 	class OdemWebsocketProvider {
 		/**
@@ -18,33 +18,47 @@ module.exports = function() {
 		 */
 		static start() {
 			api.once( "websocket", io => {
+				const { crud, notifications } = api.config.socket.odem;
+
 				const namespace = io.of( "/hitchy/odem" );
 
+				const txPerModel = {};
+
+				for ( const [ modelName, model ] of Object.entries( api.models ) ) {
+					txPerModel[modelName] = this.broadcastModelNotifications( notifications, namespace, modelName, model );
+				}
+
 				namespace.on( "connection", socket => {
-					for ( const modelName of Object.keys( api.models ) ) {
-						const model = api.models[modelName];
+					const rxPerModel = {};
 
-						this.manageModel( namespace, socket, modelName, model );
+					for ( const [ modelName, model ] of Object.entries( api.models ) ) {
+						rxPerModel[modelName] = this.handleModelRequests( crud, socket, modelName, model );
 					}
+
+					socket.once( "disconnect", () => {
+						for ( const [ modelName, handlers ] of Object.entries( rxPerModel ) ) {
+							for ( const [ eventName, handler ] of Object.entries( handlers ) ) {
+								const prefix = api.utility.case.pascalToKebab( modelName );
+
+								socket.off( `${prefix}:${eventName}`, handler );
+							}
+						}
+					} );
 				} );
-			} );
-		}
 
-		/**
-		 * Initializes manager for controlling and monitoring named model via
-		 * provided server-side websocket.
-		 *
-		 * @param {Server} io server-side websocket
-		 * @param {WebSocket} socket socket representing established incoming connection
-		 * @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, socket, modelName, model ) {
-			const { crud, notifications } = api.config.socket.odem;
+				api.once( "close", () => {
+					namespace.disconnectSockets( true );
 
-			this.handleModelRequests( crud, socket, modelName, model );
-			this.forwardModelNotifications( notifications, io, modelName, model );
+					for ( const [ modelName, model ] of Object.entries( api.models ) ) {
+						const handlers = txPerModel[modelName];
+
+						model.notifications
+							.off( "created", handlers.created )
+							.off( "changed", handlers.changed )
+							.off( "removed", handlers.removed );
+					}
+				} );
+			} );
 		}
 
 		/**
@@ -54,8 +68,8 @@ module.exports = function() {
 		 * @param {boolean} enabled true if command handling is enabled in configuration
 		 * @param {WebSocket} socket socket representing established incoming connection
 		 * @param {string} modelName name of model to manage
-		 * @param {class<Hitchy.Plugin.Odem.Model>} model ODM-based model instance to manage
-		 * @returns {void}
+		 * @param {class<Hitchy.Plugin.Odem.Model>} model model instance based on document-oriented database to manage
+		 * @returns {Object<string,function>} map of registered handler functions
 		 */
 		static handleModelRequests( enabled, socket, modelName, model ) {
 			const prefix = api.utility.case.pascalToKebab( modelName );
@@ -63,194 +77,302 @@ module.exports = function() {
 			if ( !enabled ) {
 				logDebug( "disabling socket-based action requests for model %s (%s)", modelName, prefix );
 
+				const handlers = {
+					list: ( _, __, ___, response ) => reject( response ),
+					find: ( _, __, ___, ____, response ) => reject( response ),
+					create: ( _, __, response ) => reject( response ),
+					read: ( _, __, response ) => reject( response ),
+					update: ( _, __, ___, response ) => reject( response ),
+					delete: ( _, __, response ) => reject( response ),
+				};
+
 				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;
+					.on( `${prefix}:list`, handlers.list )
+					.on( `${prefix}:find`, handlers.find )
+					.on( `${prefix}:create`, handlers.create )
+					.on( `${prefix}:read`, handlers.read )
+					.on( `${prefix}:update`, handlers.update )
+					.on( `${prefix}:delete`, handlers.delete );
+
+				return handlers;
 			}
 
 			logDebug( "enabling socket-based action requests for model %s (%s)", modelName, prefix );
 
-			socket
-				.on( `${prefix}:list`, async( sessionId, queryOptions, loadRecords, response ) => {
-					logDebug( "request for listing %s instances w/ queryOptions %j and loadRecords %j", modelName, queryOptions, Boolean( loadRecords ) );
-
-					try {
-						const meta = {};
-						const items = await model.list( queryOptions, { loadRecords: Boolean( loadRecords ), metaCollector: meta } );
-
-						response( {
-							success: true,
-							count: meta.count,
-							items: items.map( item => ( loadRecords ? item.toObject( { serialized: true } ) : { uuid: item.uuid } ) ),
-						} );
-					} catch ( error ) {
-						logError( "listing %s instances failed: %s", modelName, error.stack );
-
-						response( {
-							error: error.message,
-						} );
-					}
-				} )
-				.on( `${prefix}:find`, async( sessionId, query, queryOptions, loadRecords, response ) => {
-					logDebug( "request for finding %s instances matching %j w/ queryOptions %j and uuidsOnly %j", modelName, query, queryOptions, Boolean( loadRecords ) );
-
-					try {
-						const meta = {};
-						const items = await model.find( query, queryOptions, { loadRecords: Boolean( loadRecords ), metaCollector: meta } );
-
-						response( {
-							success: true,
-							count: meta.count,
-							items: items.map( item => ( loadRecords ? item.toObject( { serialized: true } ) : { uuid: item.uuid } ) ),
-						} );
-					} catch ( error ) {
-						logError( "finding %s instances matching %j failed: %s", modelName, error.stack );
-
-						response( {
-							error: error.message,
-						} );
-					}
-				} )
-				.on( `${prefix}:create`, async( sessionId, properties, response ) => {
-					logDebug( "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();
+			const handlers = {
+				list: ( ...args ) => this.handleListRequest( modelName, model, ...args ),
+				find: ( ...args ) => this.handleFindRequest( modelName, model, ...args ),
+				create: ( ...args ) => this.handleCreateRequest( modelName, model, ...args ),
+				read: ( ...args ) => this.handleReadRequest( modelName, model, ...args ),
+				update: ( ...args ) => this.handleUpdateRequest( modelName, model, ...args ),
+				delete: ( ...args ) => this.handleDeleteRequest( modelName, model, ...args ),
+			};
 
-						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 ) => {
-					logDebug( "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 ) => {
-					logDebug( "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 ) => {
-					logDebug( "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,
-						} );
-					}
-				} );
+			socket
+				.on( `${prefix}:list`, handlers.list )
+				.on( `${prefix}:find`, handlers.find )
+				.on( `${prefix}:create`, handlers.create )
+				.on( `${prefix}:read`, handlers.read )
+				.on( `${prefix}:update`, handlers.update )
+				.on( `${prefix}:delete`, handlers.delete );
+
+			return handlers;
 		}
 
 		/**
-		 * Sets up listeners for model-related notifications in ODM and forwards
-		 * them as broadcast events to connected clients.
+		 * Sets up listeners for model-related notifications in
+		 * document-oriented database 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 {Server} namespace namespace managing a list of server-side sockets with common prefix
 		 * @param {string} modelName name of model to manage
-		 * @param {class<Hitchy.Plugin.Odem.Model>} model ODM-based model instance to manage
-		 * @returns {void}
+		 * @param {class<Hitchy.Plugin.Odem.Model>} model model instance of document-oriented database to manage
+		 * @returns {Object<string,function>} map of registered handler functions
 		 */
-		static forwardModelNotifications( enabled, io, modelName, model ) {
+		static broadcastModelNotifications( enabled, namespace, modelName, model ) {
 			if ( enabled ) {
 				const prefix = api.utility.case.pascalToKebab( modelName );
 
-				model.notifications
-					.on( "created", async( uuid, newRecord, asyncGeneratorFn ) => {
+				const handlers = {
+					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 ) => {
+						namespace.emit( `${prefix}:changed`, event );
+					},
+					changed: async( uuid, newRecord, oldRecord, asyncGeneratorFn ) => {
 						const event = {
 							change: "updated",
 							properties: ( await asyncGeneratorFn() ).toObject( { serialized: true } ),
 						};
 
-						io.emit( `${prefix}:changed`, event );
-					} )
-					.on( "removed", uuid => {
+						namespace.emit( `${prefix}:changed`, event );
+					},
+					removed: uuid => {
 						const event = {
 							change: "deleted",
 							properties: { uuid: model.formatUUID( uuid ) },
 						};
 
-						io.emit( `${prefix}:changed`, event );
-					} );
+						namespace.emit( `${prefix}:changed`, event );
+					},
+				};
+
+				model.notifications
+					.on( "created", handlers.created )
+					.on( "changed", handlers.changed )
+					.on( "removed", handlers.removed );
+
+				return handlers;
+			}
+
+			return {};
+		}
+
+		/**
+		 * Handles incoming request for listing items of a model.
+		 *
+		 * @param {string} modelName name of model
+		 * @param {string} model named server-side model
+		 * @param {string} sessionId client-provided session ID
+		 * @param {Hitchy.Odem.ListOptions} queryOptions client-provided options for listing items
+		 * @param {boolean} loadRecords if true, whole records shall be fetched per item
+		 * @param {function} response callback to invoke with response
+		 * @returns {Promise<void>} promise settled on request handled
+		 */
+		static async handleListRequest( modelName, model, sessionId, queryOptions, loadRecords, response ) {
+			logDebug( "request for listing %s instances w/ queryOptions %j and loadRecords %j", modelName, queryOptions, Boolean( loadRecords ) );
+
+			try {
+				const meta = {};
+				const items = await model.list( queryOptions, { loadRecords: Boolean( loadRecords ), metaCollector: meta } );
+
+				response( {
+					success: true,
+					count: meta.count,
+					items: items.map( item => ( loadRecords ? item.toObject( { serialized: true } ) : { uuid: item.uuid } ) ),
+				} );
+			} catch ( error ) {
+				logError( "listing %s instances failed: %s", modelName, error.stack );
+
+				response( {
+					error: error.message,
+				} );
+			}
+		}
+
+		/**
+		 * Handles incoming request for finding items of a model matching some
+		 * provided query.
+		 *
+		 * @param {string} modelName name of model
+		 * @param {string} model named server-side model
+		 * @param {string} sessionId client-provided session ID
+		 * @param {Hitchy.Odem.Query} query client-provided constraints to be met by returned items
+		 * @param {Hitchy.Odem.ListOptions} queryOptions client-provided options for listing items
+		 * @param {boolean} loadRecords if true, whole records shall be fetched per item
+		 * @param {function} response callback to invoke with response
+		 * @returns {Promise<void>} promise settled on request handled
+		 */
+		static async handleFindRequest( modelName, model, sessionId, query, queryOptions, loadRecords, response ) {
+			logDebug( "request for finding %s instances matching %j w/ queryOptions %j and uuidsOnly %j", modelName, query, queryOptions, Boolean( loadRecords ) );
+
+			try {
+				const meta = {};
+				const items = await model.find( query, queryOptions, { loadRecords: Boolean( loadRecords ), metaCollector: meta } );
+
+				response( {
+					success: true,
+					count: meta.count,
+					items: items.map( item => ( loadRecords ? item.toObject( { serialized: true } ) : { uuid: item.uuid } ) ),
+				} );
+			} catch ( error ) {
+				logError( "finding %s instances matching %j failed: %s", modelName, error.stack );
+
+				response( {
+					error: error.message,
+				} );
+			}
+		}
+
+		/**
+		 * Handles incoming request for creating item of a model.
+		 *
+		 * @param {string} modelName name of model
+		 * @param {string} model named server-side model
+		 * @param {string} sessionId client-provided session ID
+		 * @param {Hitchy.Odem.ListOptions} properties properties of item to create
+		 * @param {function} response callback to invoke with response
+		 * @returns {Promise<void>} promise settled on request handled
+		 */
+		static async handleCreateRequest( modelName, model, sessionId, properties, response ) {
+			logDebug( "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,
+				} );
+			}
+		}
+
+		/**
+		 * Handles incoming request for reading properties of a single item.
+		 *
+		 * @param {string} modelName name of item's model
+		 * @param {string} model named server-side model
+		 * @param {string} sessionId client-provided session ID
+		 * @param {string} uuid client-provided UUID of item to read
+		 * @param {function} response callback to invoke with response
+		 * @returns {Promise<void>} promise settled on request handled
+		 */
+		static async handleReadRequest( modelName, model, sessionId, uuid, response ) {
+			logDebug( "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,
+				} );
+			}
+		}
+
+		/**
+		 * Handles incoming request for adjusting properties of a single item.
+		 *
+		 * @param {string} modelName name of item's model
+		 * @param {string} model named server-side model
+		 * @param {string} sessionId client-provided session ID
+		 * @param {string} uuid client-provided UUID of item to modify
+		 * @param {Object} properties client-provided properties of item replacing its existing ones
+		 * @param {function} response callback to invoke with response
+		 * @returns {Promise<void>} promise settled on request handled
+		 */
+		static async handleUpdateRequest( modelName, model, sessionId, uuid, properties, response ) {
+			logDebug( "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,
+				} );
+			}
+		}
+
+		/**
+		 * Handles incoming request for removing a model's item.
+		 *
+		 * @param {string} modelName name of item's model
+		 * @param {string} model named server-side model
+		 * @param {string} sessionId client-provided session ID
+		 * @param {string} uuid client-provided UUID of item to remove
+		 * @param {function} response callback to invoke with response
+		 * @returns {Promise<void>} promise settled on request handled
+		 */
+		static async handleDeleteRequest( modelName, model, sessionId, uuid, response ) {
+			logDebug( "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,
+				} );
 			}
 		}
 	}

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@hitchy/plugin-odem-socket.io",
-	"version": "0.2.2",
-	"description": "exposing Hitchy's ODM via websocket",
+	"version": "0.2.4",
+	"description": "exposing Hitchy's document-oriented database via websocket",
 	"main": "index.js",
 	"scripts": {
 		"lint": "eslint .",
@@ -14,8 +14,7 @@
 	},
 	"keywords": [
 		"Hitchy",
-		"socket.io",
-		"ODM"
+		"socket.io"
 	],
 	"author": "cepharum GmbH",
 	"license": "MIT",
@@ -30,18 +29,18 @@
 		"index.js"
 	],
 	"peerDependencies": {
-		"@hitchy/core": ">=0.7.2",
-		"@hitchy/plugin-odem": ">=0.7.1",
-		"@hitchy/plugin-socket.io": ">=0.1.0"
+		"@hitchy/core": ">=0.8.1",
+		"@hitchy/plugin-odem": ">=0.7.8",
+		"@hitchy/plugin-socket.io": ">=0.1.1"
 	},
 	"devDependencies": {
-		"@hitchy/server-dev-tools": "^0.4.5",
-		"c8": "^8.0.1",
-		"eslint": "^8.47.0",
-		"eslint-config-cepharum": "^1.0.13",
-		"eslint-plugin-promise": "^6.1.1",
-		"mocha": "^10.2.0",
+		"@hitchy/server-dev-tools": "^0.4.9",
+		"c8": "^10.1.2",
+		"eslint": "^8.57.0",
+		"eslint-config-cepharum": "^1.0.14",
+		"eslint-plugin-promise": "^7.1.0",
+		"mocha": "^10.7.3",
 		"should": "^13.2.3",
-		"socket.io-client": "^4.7.2"
+		"socket.io-client": "^4.7.5"
 	}
 }

package/readme.md

@@ -1,6 +1,6 @@
 # @hitchy/plugin-odem-socket.io
 
-_exposing Hitchy's ODM via websocket_
+_exposing Hitchy's document-oriented database via websocket_
 
 ## License
 
@@ -29,7 +29,7 @@ npm i @hitchy/plugin-odem @hitchy/plugin-socket.io
 
 ### 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`. 
+This plugin is establishing an API via websocket for controlling and monitoring models of server-side document-oriented database. 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. 
 
@@ -156,7 +156,7 @@ Last argument is a callback to be invoked with the resulting response from serve
 
 ### Notifications
 
-[ODM notifications](https://odem.hitchy.org/api/model.html#model-notifications) are forwarded as broadcast events named `<modelName>:changed`. Either event consists of 
+[notifications of the document-oriented database](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).