@hitchy/plugin-odem-socket.io 0.3.0 → 0.5.0

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

@@ -1,8 +1,7 @@
-"use strict";
+import { promisify } from "node:util";
 
-const { promisify } = require( "node:util" );
-
-module.exports = function() {
+/** */
+export default function() {
 	const api = this;
 
 	const logDebug = api.log( "hitchy:plugin:odem:socket.io:debug" );
@@ -32,7 +31,7 @@ module.exports = function() {
 				const txPerModel = {};
 
 				for ( const [ modelName, model ] of Object.entries( api.models ) ) {
-					if ( api.service.OdemSchema.mayBeExposed( { user: undefined }, model ) ) {
+					if ( api.service.OdemSchema.mayBeExposed( undefined, model ) ) {
 						txPerModel[modelName] = this.broadcastModelNotifications( notifications, namespace, model );
 					}
 				}
@@ -85,10 +84,10 @@ module.exports = function() {
 				const handlers = {
 					created: ( uuid, newRecord, asyncGeneratorFn ) => {
 						asyncGeneratorFn()
-							.then( item => this.namespaceEmit( namespace, Model, {
+							.then( item => this.namespaceEmit( namespace, item, {
 								change: "created",
 								model: Model.name,
-								properties: item.toObject( { serialized: true } ),
+								properties: this.serializeItem( item, false ),
 							}, true ) )
 							.catch( cause => {
 								logError( "broadcasting notification on having created item %s of %s has failed:", uuid, Model.name, cause.stack );
@@ -96,21 +95,22 @@ module.exports = function() {
 					},
 					changed: ( uuid, newRecord, oldRecord, asyncGeneratorFn ) => {
 						asyncGeneratorFn()
-							.then( item => this.namespaceEmit( namespace, Model, {
-								change: "updated",
+							.then( item => this.namespaceEmit( namespace, item, {
+								change: "changed",
 								model: Model.name,
-								properties: item.toObject( { serialized: true } ),
+								properties: this.serializeItem( item, false ),
 							}, true ) )
 							.catch( cause => {
 								logError( "broadcasting notification on having updated item %s of %s has failed:", uuid, Model.name, cause.stack );
 							} );
 					},
-					removed: uuid => {
-						this.namespaceEmit( namespace, Model, {
-							change: "deleted",
-							model: Model.name,
-							properties: { uuid: Model.formatUUID( uuid ) },
-						}, false )
+					removed: ( uuid, lastRecord, asyncGeneratorFn ) => {
+						asyncGeneratorFn()
+							.then( item => this.namespaceEmit( namespace, item, {
+								change: "removed",
+								model: Model.name,
+								properties: { uuid: String( uuid ) },
+							}, false ) )
 							.catch( cause => {
 								logError( "broadcasting notification on having removed item %s of %s has failed:", uuid, Model.name, cause.stack );
 							} );
@@ -181,6 +181,8 @@ module.exports = function() {
 							}
 						}
 
+						// TODO track the whole request instead of just its user to enable the plugin to assign $context to processed model instances
+
 						// pick user eventually injected into mocked request
 						return request.user || undefined;
 					}
@@ -198,14 +200,16 @@ module.exports = function() {
 		 * accessing the changed model and/or its properties.
 		 *
 		 * @param {Server} namespace namespace managing a pool of sockets that have joined the namespace
-		 * @param {class<Hitchy.Plugin.Odem.Model>} Model model of changed item
-		 * @param {{change: string, model: string, properties: Object}} payload raw payload of model-specific notification
+		 * @param {Hitchy.Plugin.Odem.Model} item instance of model notification is related to
+		 * @param {{change: "created"|"changed"|"removed", model: string, properties: Object}} payload raw payload of model-specific notification
 		 * @param {boolean} filterProperties if true, properties need to be filtered per peer based on its authorization
 		 * @returns {Promise<void>} promise resolved when all authorized peers have been notified
 		 */
-		static async namespaceEmit( namespace, Model, payload, filterProperties ) {
+		static async namespaceEmit( namespace, item, payload, filterProperties ) {
 			const hasPluginAuth = Boolean( api.plugins.authentication );
 			const sockets = await namespace.fetchSockets();
+			const Model = item.constructor;
+			const userCache = {};
 
 			logDebug( "forwarding notification to %d socket(s)", sockets.length );
 
@@ -220,46 +224,73 @@ module.exports = function() {
 					return;
 				}
 
-				if ( !OdemSchema.mayBeExposed( { user }, Model ) ) {
-					logDebug( `omit notification to user ${user?.uuid} (${user.name}) at peer ${socket.id} with access on ${Model.name} forbidden by model` );
-					return;
-				}
+				const userId = user?.uuid ?? "(null)";
+				let cached = userCache[userId];
+
+				if ( cached == null ) {
+					cached = userCache[userId] = false;
 
-				let mayRead = OdemSchema.isAdmin( user );
-				let scope = "read";
+					// check connected user's common authorization to access the
+					// notification's model or the instance properties included with
+					// the notification
+					if ( !OdemSchema.mayBeExposed( user, Model ) ) {
+						logDebug( `omit notification to user ${userId} (${user?.name}) at peer ${socket.id} with access on ${Model.name} forbidden by model` );
+						return;
+					}
 
-				if ( !mayRead && hasPluginAuth ) {
-					mayRead = await Authorization.mayAccess( user, `@hitchy.odem.model.${Model.name}.read` );
+					let mayRead = OdemSchema.isAdmin( user );
+					let scope = "read";
 
-					if ( !mayRead ) {
-						mayRead = await Authorization.mayAccess( user, `@hitchy.odem.model.${Model.name}.list` );
-						scope = "list";
+					if ( !mayRead && hasPluginAuth ) {
+						mayRead = await Authorization.mayAccess( user, `@hitchy.odem.model.${Model.name}.read` );
+
+						if ( !mayRead ) {
+							mayRead = await Authorization.mayAccess( user, `@hitchy.odem.model.${Model.name}.list` );
+							scope = "list";
+						}
 					}
-				}
 
-				const prefix = api.utility.case.pascalToKebab( Model.name );
+					// check model's life cycle hook individually controlling
+					// if current socket's user may receive the notification
+					const mayBeNotified = await item.beforeNotify( user, payload.change );
+
+					if ( !mayBeNotified ) {
+						logDebug( `notification to user ${userId} (${user?.name}) at peer ${socket.id} prevented by beforeNotify() of model ${Model.name}` );
+						return;
+					}
 
-				if ( !mayRead ) {
-					// user must not read items of this model -> do not provide any identifier, but basically notify on some change to the model
-					socket.emit( `${prefix}:changed`, { ...payload, properties: {} } );
-					socket.emit( "*:changed", { ...payload, properties: {} } );
-				} else if ( filterProperties ) {
-					const copy = { ...payload };
+					// eventually send the notification ...
+					if ( !mayRead ) {
+						// user must not read items of this model -> do not
+						// provide any identifier, but basically notify on some
+						// (unspecified) change to the model
+						cached = userCache[userId] = { ...payload, properties: {} };
+					} else if ( filterProperties ) {
+						// user may read items of this model, but access to some
+						// properties may be restricted by the model's schema
+						cached = userCache[userId] = {
+							...payload,
+							properties: OdemSchema.filterItem( payload.properties, user, Model, scope ),
+						};
+					} else {
+						// user gets notification with all properties of item
+						cached = userCache[userId] = payload;
+					}
+				}
 
-					copy.properties = OdemSchema.filterItem( copy.properties, { user }, Model, scope );
+				if ( cached ) {
+					// user may receive notification -> emit it eventually
+					const prefix = api.utility.case.pascalToKebab( Model.name );
 
-					socket.emit( `${prefix}:changed`, copy );
-					socket.emit( "*:changed", copy );
-				} else {
-					socket.emit( `${prefix}:changed`, payload );
-					socket.emit( "*:changed", payload );
+					socket.emit( `${prefix}:changed`, cached );
+					socket.emit( "*:changed", cached );
 				}
 			};
 
 			for ( const socket of sockets ) {
 				notifyPeer( socket ).catch( cause => {
 					logError(
-						`notifying peer ${socket.id} on having ${payload.change} item of ${Model.name} has failed:`,
+						`notifying peer ${socket.id} on having ${payload.change} item ${item.uuid} of ${Model.name} has failed:`,
 						cause.stack
 					);
 				} );
@@ -309,7 +340,7 @@ module.exports = function() {
 			}[action];
 
 			if ( !handler ) {
-				logDebug( "ignoring socket-based request for actin %s on model %s due to lack of handler", action, Model.name );
+				logDebug( "ignoring socket-based request for action %s on model %s due to lack of handler", action, Model.name );
 				return;
 			}
 
@@ -344,7 +375,7 @@ module.exports = function() {
 					}
 				}
 
-				if ( !api.service.OdemSchema.mayBeExposed( { user }, Model ) ) {
+				if ( !api.service.OdemSchema.mayBeExposed( user, Model ) ) {
 					throw new Error( "access forbidden by model" );
 				}
 
@@ -353,7 +384,7 @@ module.exports = function() {
 				let filter;
 
 				if ( loadRecords ) {
-					filter = item => api.service.OdemSchema.filterItem( item.toObject( { serialized: true } ), { user }, Model, "list" );
+					filter = item => api.service.OdemSchema.filterItem( this.serializeItem( item, false ), user, Model, "list" );
 				} else {
 					filter = item => ( { uuid: item.uuid } );
 				}
@@ -396,7 +427,7 @@ module.exports = function() {
 					}
 				}
 
-				if ( !api.service.OdemSchema.mayBeExposed( { user }, Model ) ) {
+				if ( !api.service.OdemSchema.mayBeExposed( user, Model ) ) {
 					throw new Error( "access forbidden by model" );
 				}
 
@@ -405,7 +436,7 @@ module.exports = function() {
 				let filter;
 
 				if ( loadRecords ) {
-					filter = item => api.service.OdemSchema.filterItem( item.toObject( { serialized: true } ), { user }, Model, "list" );
+					filter = item => api.service.OdemSchema.filterItem( this.serializeItem( item, false ), user, Model, "list" );
 				} else {
 					filter = item => ( { uuid: item.uuid } );
 				}
@@ -434,7 +465,7 @@ module.exports = function() {
 		 * @returns {Promise<void>} promise settled on request handled
 		 */
 		static async handleCreateRequest( socket, Model, properties, response ) {
-			logDebug( "request for creating %s instance with %j", Model.name, properties );
+			logDebug( "request for creating %s instance with %j", Model.name, reduce( properties ) );
 
 			const { Authorization, OdemSchema } = api.service;
 
@@ -445,17 +476,17 @@ module.exports = function() {
 					throw new Error( "access forbidden" );
 				}
 
-				if ( !OdemSchema.mayBeExposed( { user }, Model ) ) {
+				if ( !OdemSchema.mayBeExposed( user, Model ) ) {
 					throw new Error( "access forbidden by model" );
 				}
 
 				const schema = Model.schema;
-				const filtered = OdemSchema.filterItem( properties, { user }, Model, "create" );
+				const filtered = OdemSchema.filterItem( properties, user, Model, "create" );
 				const instance = new Model();
 
-				for ( const [ propName, propValue ] of Object.entries( filtered ) ) {
+				for ( const propName of Object.keys( filtered ) ) {
 					if ( schema.props.hasOwnProperty( propName ) || schema.computed.hasOwnProperty( propName ) ) {
-						instance[propName] = propValue;
+						instance[propName] = filtered[propName];
 					}
 				}
 
@@ -463,7 +494,7 @@ module.exports = function() {
 
 				response( {
 					success: true,
-					properties: OdemSchema.filterItem( instance.toObject( { serialized: true } ), { user }, Model, "read" ),
+					properties: OdemSchema.filterItem( this.serializeItem( instance, false ), user, Model, "read" ),
 				} );
 			} catch ( error ) {
 				logError( "creating %s instance failed: %s", Model.name, error.stack );
@@ -495,7 +526,7 @@ module.exports = function() {
 					}
 				}
 
-				if ( !api.service.OdemSchema.mayBeExposed( { user }, Model ) ) {
+				if ( !api.service.OdemSchema.mayBeExposed( user, Model ) ) {
 					throw new Error( "access forbidden by model" );
 				}
 
@@ -504,7 +535,7 @@ module.exports = function() {
 
 				response( {
 					success: true,
-					properties: api.service.OdemSchema.filterItem( instance.toObject( { serialized: true } ), { user }, Model, "read" ),
+					properties: api.service.OdemSchema.filterItem( this.serializeItem( instance, true ), user, Model, "read" ),
 				} );
 			} catch ( error ) {
 				logError( "reading %s instance failed: %s", Model.name, error.stack );
@@ -526,7 +557,7 @@ module.exports = function() {
 		 * @returns {Promise<void>} promise settled on request handled
 		 */
 		static async handleUpdateRequest( socket, Model, uuid, properties, response ) {
-			logDebug( "request for updating %s instance %s with %j", Model.name, uuid, properties );
+			logDebug( "request for updating %s instance %s with %j", Model.name, uuid, reduce( properties ) );
 
 			try {
 				const user = await this.getUserForSocket( socket );
@@ -537,12 +568,12 @@ module.exports = function() {
 					}
 				}
 
-				if ( !api.service.OdemSchema.mayBeExposed( { user }, Model ) ) {
+				if ( !api.service.OdemSchema.mayBeExposed( user, Model ) ) {
 					throw new Error( "access forbidden by model" );
 				}
 
 				const schema = Model.schema;
-				const filtered = api.service.OdemSchema.filterItem( properties, { user }, Model, "write" );
+				const filtered = api.service.OdemSchema.filterItem( properties, user, Model, "write" );
 				const instance = new Model( uuid );
 				await instance.load();
 
@@ -556,7 +587,7 @@ module.exports = function() {
 
 				response( {
 					success: true,
-					properties: api.service.OdemSchema.filterItem( instance.toObject( { serialized: true } ), { user }, Model, "read" ),
+					properties: api.service.OdemSchema.filterItem( this.serializeItem( instance, false ), user, Model, "read" ),
 				} );
 			} catch ( error ) {
 				logError( "updating %s instance failed: %s", Model.name, error.stack );
@@ -588,7 +619,7 @@ module.exports = function() {
 					}
 				}
 
-				if ( !api.service.OdemSchema.mayBeExposed( { user }, Model ) ) {
+				if ( !api.service.OdemSchema.mayBeExposed( user, Model ) ) {
 					throw new Error( "access forbidden by model" );
 				}
 
@@ -607,6 +638,47 @@ module.exports = function() {
 				} );
 			}
 		}
+
+		/**
+		 * Serializes provided instance of a model optionally including/excluding
+		 * properties marked as _lazy_.
+		 *
+		 * This method is used to provide reduced sets of properties per item
+		 * on listing/updating items while delivering all properties when
+		 * reading individual items.
+		 *
+		 * @param {Hitchy.Plugin.Odem.Model} item instance of model
+		 * @param {boolean} includeLazyProperties if true, properties marked as lazy in schema of model are included with resulting record
+		 * @returns {object} record of provided item's serialized properties
+		 */
+		static serializeItem( item, includeLazyProperties = false ) {
+			const record = item.toObject( { serialized: true } );
+
+			if ( includeLazyProperties ) {
+				return record;
+			}
+
+			const filtered = {};
+
+			for ( const name of Object.keys( record ) ) {
+				let definition = item.constructor.schema.props[name];
+
+				if ( definition == null ) {
+					definition = item.constructor.schema.computed[name];
+				}
+
+				const lazy = definition?.lazy;
+
+				if ( !lazy ||
+				     ( typeof lazy === "string" && lazy !== "ws" && lazy !== "socket" && lazy !== "websocket" ) ||
+				     ( typeof lazy === "object" && !lazy.ws && !lazy.socket && !lazy.websocket )
+				) {
+					filtered[name] = record[name];
+				}
+			}
+
+			return filtered;
+		}
 	}
 
 	return OdemWebsocketProvider;
@@ -615,7 +687,7 @@ module.exports = function() {
 /**
  * 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
+ * @param {function(any):void} respondFn callback to be invoked for responding to a peer event
  * @returns {void}
  */
 function reject( respondFn ) {
@@ -623,3 +695,42 @@ function reject( respondFn ) {
 		error: "requested action is not available due to runtime configuration",
 	} );
 }
+
+/**
+ * Recursively trims values of provided data.
+ *
+ * @param {*} data data to be trimmed
+ * @param {number} limit number of characters to keep in strings when trimming
+ * @returns {*} provided data trimmed as necessary
+ */
+function reduce( data, limit = 200 ) {
+	if ( Array.isArray( data ) ) {
+		return data.map( item => reduce( item, Math.max( 10, limit / 5 ) ) );
+	}
+
+	if ( data && typeof data === "object" ) {
+		const copy = {};
+
+		for ( const name of Object.keys( data ) ) {
+			copy[name] = reduce( data[name], Math.max( 10, limit / 5 ) );
+		}
+
+		return copy;
+	}
+
+	switch ( typeof data ) {
+		case "function" :
+		case "string" : {
+			const s = String( data );
+
+			if ( s.length > limit ) {
+				return s.substring( 0, limit ) + "…+" + String( limit - s.length );
+			}
+
+			return s;
+		}
+
+		default :
+			return data;
+	}
+}

package/config/socket.js

@@ -1,6 +1,4 @@
-"use strict";
-
-module.exports = {
+export default {
 	socket: {
 		odem: {
 			/**

package/index.js

@@ -1,6 +1,5 @@
-"use strict";
-
-module.exports = function() {
+/** */
+export default function() {
 	const api = this;
 
 	return {

package/package.json

@@ -1,12 +1,13 @@
 {
 	"name": "@hitchy/plugin-odem-socket.io",
-	"version": "0.3.0",
+	"version": "0.5.0",
 	"description": "exposing Hitchy's document-oriented database via websocket",
 	"main": "index.js",
+	"type": "module",
 	"scripts": {
 		"lint": "eslint .",
-		"test": "hitchy-pm odem socket.io auth --exec mocha --ui=tdd 'test/**/*.spec.js'",
-		"coverage": "hitchy-pm odem socket.io auth --exec c8 mocha --ui=tdd 'test/**/*.spec.js'"
+		"test": "hitchy-pm odem socket.io auth --exec mocha --ui=tdd test/**/*.spec.js",
+		"coverage": "hitchy-pm odem socket.io auth --exec c8 mocha --ui=tdd test/**/*.spec.js"
 	},
 	"repository": {
 		"type": "git",
@@ -29,18 +30,24 @@
 		"index.js"
 	],
 	"peerDependencies": {
-		"@hitchy/core": ">=0.8.1",
-		"@hitchy/plugin-odem": ">=0.9.1",
-		"@hitchy/plugin-socket.io": ">=0.1.1"
+		"@hitchy/core": "^1.5.5",
+		"@hitchy/plugin-odem": "^0.14.0",
+		"@hitchy/plugin-socket.io": "^0.1.3"
 	},
 	"devDependencies": {
-		"@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",
+		"@hitchy/server-dev-tools": "^0.9.6",
+		"c8": "^10.1.3",
+		"eslint": "^9.39.2",
+		"eslint-config-cepharum": "^2.0.2",
+		"mocha": "^11.7.5",
 		"should": "^13.2.3",
-		"socket.io-client": "^4.7.5"
+		"socket.io-client": "^4.8.3"
+	},
+	"c8": {
+		"reporter": [
+			"text",
+			"html"
+		],
+		"all": true
 	}
 }

package/readme.md

@@ -59,7 +59,7 @@ socket.on( "connect", () => {
 } );
 ```
 
-> 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. 
+> socket.io requires all arguments to be provided no matter what. Thus, you can not 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.
 
@@ -166,8 +166,12 @@ Last argument is a callback to be invoked with the resulting response from serve
 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.
+* `changed` on notifications about having adjusted one or more properties of an existing instance of model and
+* `removed` on notifications about having removed an existing instance of model.
+
+:::danger Breaking change
+Notification types have changed in v0.5.0 from `updated` to `changed` and from `deleted` to `removed` to match names used on server side.
+:::
 
 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:
 
@@ -175,7 +179,7 @@ In last case the provided set of properties is limited to the instance's UUID. T
 const socket = io( "/hitchy/odem" );
 
 socket.on( "<modelName>:changed", info => {
-    // type of change is in `info.change`, e.g. "updated"
+    // type of change is in `info.change`, e.g. "created", "changed" or "removed"
     // process properties of changed instance in `info.properties`
 } );
 ```