@signe/room 2.8.2 → 2.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@signe/room",
-  "version": "2.8.2",
+  "version": "2.9.0",
   "description": "",
   "main": "./dist/index.js",
   "keywords": [],
@@ -17,7 +17,7 @@
     "dset": "^3.1.3",
     "partysocket": "^1.0.1",
     "zod": "^3.23.8",
-    "@signe/sync": "2.8.2"
+    "@signe/sync": "2.9.0"
   },
   "publishConfig": {
     "access": "public"

package/readme.md

@@ -69,6 +69,54 @@ Function have to be decorated with the `@Action` decorator and  have 3 parameter
 - The second parameter is the value of the action
 - The third parameter is the Party.Connection instance
 
+### Unhandled actions
+
+If you want to catch any valid WebSocket message whose `action` is not registered
+with `@Action(...)`, you can use `@UnhandledAction()`.
+
+The fallback handler receives:
+
+- The first parameter is the player instance
+- The second parameter is the full message object: `{ action, value }`
+- The third parameter is the `Party.Connection` instance
+
+```ts
+import { Action, Guard, Room, UnhandledAction } from "@signe/room";
+
+function isAuthenticated(conn: Party.Connection, value: any, room: Party.Room) {
+  return !!conn.state?.publicId;
+}
+
+@Room({
+  path: "game",
+})
+class GameRoom {
+  @Action("move")
+  move(player: any, value: { x: number; y: number }) {
+    player.x.set(value.x);
+    player.y.set(value.y);
+  }
+
+  @UnhandledAction()
+  @Guard([isAuthenticated])
+  onUnhandledAction(
+    player: any,
+    message: { action: string; value: unknown },
+    conn: Party.Connection
+  ) {
+    console.warn("Unhandled action", message.action, message.value, conn.id);
+  }
+}
+```
+
+Notes:
+
+- `@UnhandledAction()` is only called if the incoming message matches the expected
+  WebSocket shape `{ action, value }`
+- If a matching `@Action("...")` exists, it always has priority over
+  `@UnhandledAction()`
+- You can combine `@UnhandledAction()` with `@Guard(...)`
+
 ## HTTP Request Handling
 
 The `@Request` decorator allows you to handle HTTP requests with specific routes and methods:

package/src/decorators.ts

@@ -15,6 +15,18 @@ export function Action(name: string, bodyValidation?: z.ZodSchema) {
   };
 }
 
+/**
+ * Fallback decorator for handling websocket messages whose action
+ * does not match any registered @Action decorator.
+ */
+export function UnhandledAction() {
+  return function (target: any, propertyKey: string) {
+    target.constructor._unhandledActionMetadata = {
+      key: propertyKey,
+    };
+  };
+}
+
 /**
  * Request decorator for handling HTTP requests with path and method routing
  * @param options Configuration for the HTTP request handler
@@ -98,4 +110,4 @@ export function Guard(guards: GuardFn[]) {
     }
     target.constructor['_actionGuards'].set(propertyKey, guards);
   };
-}
+}

package/src/server.ts

@@ -801,36 +801,50 @@ export class Server implements Party.Server {
     }
 
     const actions = subRoom.constructor["_actionMetadata"];
-    if (actions) {
-      const signal = this.getUsersProperty(subRoom);
-      const { publicId } = sender.state as any;
-      const user = signal?.()[publicId];
-      const actionName = actions.get(result.data.action);
-      if (actionName) {
+    const signal = this.getUsersProperty(subRoom);
+    const { publicId } = sender.state as any;
+    const user = signal?.()[publicId];
+    const actionName = actions?.get(result.data.action);
+    if (actionName) {
+
+      // Check all guards if they exist
+      const guards = subRoom.constructor['_actionGuards']?.get(actionName.key) || [];
+      for (const guard of guards) {
+        const isAuthorized = await guard(sender, result.data.value, this.room);
+        if (!isAuthorized) {
+          return;
+        }
+      }
 
-        // Check all guards if they exist
-        const guards = subRoom.constructor['_actionGuards']?.get(actionName.key) || [];
-        for (const guard of guards) {
-          const isAuthorized = await guard(sender, result.data.value);
-          if (!isAuthorized) {
-            return;
-          }
+      // Validate action body if a validation schema is defined
+      if (actionName.bodyValidation) {
+        const bodyResult = actionName.bodyValidation.safeParse(
+          result.data.value
+        );
+        if (!bodyResult.success) {
+          return;
         }
+      }
+      // Execute the action
+      await awaitReturn(
+        subRoom[actionName.key](user, result.data.value, sender)
+      );
+      return;
+    }
 
-        // Validate action body if a validation schema is defined
-        if (actionName.bodyValidation) {
-          const bodyResult = actionName.bodyValidation.safeParse(
-            result.data.value
-          );
-          if (!bodyResult.success) {
-            return;
-          }
+    const unhandledAction = subRoom.constructor["_unhandledActionMetadata"];
+    if (unhandledAction) {
+      const guards = subRoom.constructor['_actionGuards']?.get(unhandledAction.key) || [];
+      for (const guard of guards) {
+        const isAuthorized = await guard(sender, result.data, this.room);
+        if (!isAuthorized) {
+          return;
         }
-        // Execute the action
-        await awaitReturn(
-          subRoom[actionName.key](user, result.data.value, sender)
-        );
       }
+
+      await awaitReturn(
+        subRoom[unhandledAction.key](user, result.data, sender)
+      );
     }
   }
 
@@ -1195,14 +1209,14 @@ export class Server implements Party.Server {
               })
             )) ?? userSnapshot;
           
+          // Add user to signal before loading to avoid syncing non-serializable instances
+          signal()[publicId] = user;
+
           // Load user data from snapshot
           load(user, hydratedSnapshot, true);
           
-          // Add user to signal
-          signal()[publicId] = user;
-
           // Save user snapshot to storage
-          await this.room.storage.put(`${usersPropName}.${publicId}`, hydratedSnapshot);
+          await this.room.storage.put(`${usersPropName}.${publicId}`, userSnapshot);
         }
       }