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

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

@@ -31,7 +31,7 @@ export default 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 );
 					}
 				}
@@ -84,7 +84,7 @@ export default 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: this.serializeItem( item, false ),
@@ -95,8 +95,8 @@ export default 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: this.serializeItem( item, false ),
 							}, true ) )
@@ -104,12 +104,13 @@ export default function() {
 								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: String( 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 );
 							} );
@@ -180,6 +181,8 @@ export default 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;
 					}
@@ -197,14 +200,16 @@ export default 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 );
 
@@ -219,46 +224,73 @@ export default 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];
 
-				let mayRead = OdemSchema.isAdmin( user );
-				let scope = "read";
+				if ( cached == null ) {
+					cached = userCache[userId] = false;
 
-				if ( !mayRead && hasPluginAuth ) {
-					mayRead = await Authorization.mayAccess( user, `@hitchy.odem.model.${Model.name}.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 ) {
-						mayRead = await Authorization.mayAccess( user, `@hitchy.odem.model.${Model.name}.list` );
-						scope = "list";
+					let mayRead = OdemSchema.isAdmin( user );
+					let scope = "read";
+
+					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 ( !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 };
+					if ( !mayBeNotified ) {
+						logDebug( `notification to user ${userId} (${user?.name}) at peer ${socket.id} prevented by beforeNotify() of model ${Model.name}` );
+						return;
+					}
 
-					copy.properties = OdemSchema.filterItem( copy.properties, { user }, Model, scope );
+					// 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;
+					}
+				}
 
-					socket.emit( `${prefix}:changed`, copy );
-					socket.emit( "*:changed", copy );
-				} else {
-					socket.emit( `${prefix}:changed`, payload );
-					socket.emit( "*:changed", payload );
+				if ( cached ) {
+					// user may receive notification -> emit it eventually
+					const prefix = api.utility.case.pascalToKebab( Model.name );
+
+					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
 					);
 				} );
@@ -308,7 +340,7 @@ export default 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;
 			}
 
@@ -343,7 +375,7 @@ export default function() {
 					}
 				}
 
-				if ( !api.service.OdemSchema.mayBeExposed( { user }, Model ) ) {
+				if ( !api.service.OdemSchema.mayBeExposed( user, Model ) ) {
 					throw new Error( "access forbidden by model" );
 				}
 
@@ -352,7 +384,7 @@ export default function() {
 				let filter;
 
 				if ( loadRecords ) {
-					filter = item => api.service.OdemSchema.filterItem( this.serializeItem( item, false ), { user }, Model, "list" );
+					filter = item => api.service.OdemSchema.filterItem( this.serializeItem( item, false ), user, Model, "list" );
 				} else {
 					filter = item => ( { uuid: item.uuid } );
 				}
@@ -395,7 +427,7 @@ export default function() {
 					}
 				}
 
-				if ( !api.service.OdemSchema.mayBeExposed( { user }, Model ) ) {
+				if ( !api.service.OdemSchema.mayBeExposed( user, Model ) ) {
 					throw new Error( "access forbidden by model" );
 				}
 
@@ -404,7 +436,7 @@ export default function() {
 				let filter;
 
 				if ( loadRecords ) {
-					filter = item => api.service.OdemSchema.filterItem( this.serializeItem( item, false ), { user }, Model, "list" );
+					filter = item => api.service.OdemSchema.filterItem( this.serializeItem( item, false ), user, Model, "list" );
 				} else {
 					filter = item => ( { uuid: item.uuid } );
 				}
@@ -444,12 +476,12 @@ export default 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 of Object.keys( filtered ) ) {
@@ -462,7 +494,7 @@ export default function() {
 
 				response( {
 					success: true,
-					properties: OdemSchema.filterItem( this.serializeItem( instance, false ), { 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 );
@@ -494,7 +526,7 @@ export default function() {
 					}
 				}
 
-				if ( !api.service.OdemSchema.mayBeExposed( { user }, Model ) ) {
+				if ( !api.service.OdemSchema.mayBeExposed( user, Model ) ) {
 					throw new Error( "access forbidden by model" );
 				}
 
@@ -503,7 +535,7 @@ export default function() {
 
 				response( {
 					success: true,
-					properties: api.service.OdemSchema.filterItem( this.serializeItem( instance, 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 );
@@ -536,12 +568,12 @@ export default 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();
 
@@ -555,7 +587,7 @@ export default function() {
 
 				response( {
 					success: true,
-					properties: api.service.OdemSchema.filterItem( this.serializeItem( instance, false ), { 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 );
@@ -587,7 +619,7 @@ export default function() {
 					}
 				}
 
-				if ( !api.service.OdemSchema.mayBeExposed( { user }, Model ) ) {
+				if ( !api.service.OdemSchema.mayBeExposed( user, Model ) ) {
 					throw new Error( "access forbidden by model" );
 				}
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@hitchy/plugin-odem-socket.io",
-	"version": "0.4.0",
+	"version": "0.5.0",
 	"description": "exposing Hitchy's document-oriented database via websocket",
 	"main": "index.js",
 	"type": "module",
@@ -30,18 +30,24 @@
 		"index.js"
 	],
 	"peerDependencies": {
-		"@hitchy/core": "1.x",
-		"@hitchy/plugin-odem": "0.13.x",
-		"@hitchy/plugin-socket.io": "0.1.x"
+		"@hitchy/core": "^1.5.5",
+		"@hitchy/plugin-odem": "^0.14.0",
+		"@hitchy/plugin-socket.io": "^0.1.3"
 	},
 	"devDependencies": {
-		"@hitchy/server-dev-tools": "^0.8.6",
+		"@hitchy/server-dev-tools": "^0.9.6",
 		"c8": "^10.1.3",
-		"eslint": "^9.23.0",
+		"eslint": "^9.39.2",
 		"eslint-config-cepharum": "^2.0.2",
-		"eslint-plugin-promise": "^7.2.1",
-		"mocha": "^11.1.0",
+		"mocha": "^11.7.5",
 		"should": "^13.2.3",
-		"socket.io-client": "^4.8.1"
+		"socket.io-client": "^4.8.3"
+	},
+	"c8": {
+		"reporter": [
+			"text",
+			"html"
+		],
+		"all": true
 	}
 }

package/readme.md

@@ -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`
 } );
 ```