@signe/room 2.8.3 → 2.9.2

package/package.json

@@ -1,9 +1,15 @@
 {
   "name": "@signe/room",
-  "version": "2.8.3",
-  "description": "",
+  "version": "2.9.2",
+  "description": "PartyKit room primitives with synchronized state, sessions, guards, and HTTP handlers.",
   "main": "./dist/index.js",
-  "keywords": [],
+  "keywords": [
+    "partykit",
+    "realtime",
+    "websocket",
+    "cloudflare",
+    "typescript"
+  ],
   "author": "Samuel Ronce",
   "type": "module",
   "exports": {
@@ -17,7 +23,7 @@
     "dset": "^3.1.3",
     "partysocket": "^1.0.1",
     "zod": "^3.23.8",
-    "@signe/sync": "2.8.3"
+    "@signe/sync": "2.9.2"
   },
   "publishConfig": {
     "access": "public"

package/readme.md

@@ -69,13 +69,61 @@ 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:
 
 ```ts
 import { z } from "zod";
-import { Room, Request, RequestGuard, ServerResponse } from "@signe/room";
+import { Guard, Room, Request, ServerResponse } from "@signe/room";
 
 @Room({
   path: "api"
@@ -121,11 +169,12 @@ class ApiRoom {
 }
 ```
 
-Request handler methods receive these parameters:
-1. `req`: The original Party.Request object
-2. `body`: The validated request body (if validation schema was provided)
-3. `params`: An object containing any path parameters
-4. `room`: The Party.Room instance
+Request handler methods receive:
+
+1. `req`: the original `Party.Request`, extended with `req.params` and
+   `req.data` when a validation schema is provided.
+2. `res`: a `ServerResponse` helper for JSON, text, redirects, and common
+   error responses.
 
 You can return:
 - A Response object for complete control

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/jwt.ts

@@ -132,9 +132,7 @@ export class JWTAuth {
         };
 
         // Encode header and payload
-        // @ts-expect-error - TS doesn't have a built-in TextEncoder
         const encodedHeader: string = this.base64UrlEncode(this.encoder.encode(JSON.stringify(header)));
-        //   @ts-expect-error - TS doesn't have a built-in TextEncoder
         const encodedPayload: string = this.base64UrlEncode(this.encoder.encode(JSON.stringify(fullPayload)));
 
         // Create signature base
@@ -174,9 +172,7 @@ export class JWTAuth {
 
         // Decode header and payload
         try {
-            // @ts-expect-error - TS doesn't have a built-in TextDecoder
             const header: JWTHeader = JSON.parse(this.decoder.decode(this.base64UrlDecode(encodedHeader)));
-            // @ts-expect-error - TS doesn't have a built-in TextDecoder
             const payload: JWTPayload = JSON.parse(this.decoder.decode(this.base64UrlDecode(encodedPayload)));
 
             // Check algorithm
@@ -214,4 +210,4 @@ export class JWTAuth {
             throw new Error('Token verification failed: Unknown error');
         }
     }
-}
+}

package/src/server.ts

@@ -615,7 +615,10 @@ export class Server implements Party.Server {
       return;
     }
 
-    const sessionExpiryTime = subRoom.constructor.sessionExpiryTime;
+    const sessionExpiryTime =
+      subRoom.sessionExpiryTime ??
+      subRoom.constructor.sessionExpiryTime ??
+      5 * 60 * 1000;
     await this.garbageCollector({ sessionExpiryTime });
 
     // Check room guards
@@ -801,36 +804,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)
+      );
     }
   }
 
@@ -1275,9 +1292,7 @@ export class Server implements Party.Server {
 
     const url = new URL(req.url);
     const method = req.method;
-    let pathname = url.pathname;
-
-    pathname = '/' + pathname.split('/').slice(4).join('/');
+    const pathname = this.normalizeRequestPath(url.pathname);
 
     // Check each registered handler
     for (const [routeKey, handler] of requestHandlers.entries()) {
@@ -1311,16 +1326,18 @@ export class Server implements Party.Server {
         if (handler.bodyValidation && ['POST', 'PUT', 'PATCH'].includes(method)) {
           try {
             const contentType = req.headers.get('content-type') || '';
-            if (contentType.includes('application/json')) {
-              const body = await req.json();
-              const validation = handler.bodyValidation.safeParse(body);
-              if (!validation.success) {
-                return res.badRequest("Invalid request body", {
-                  details: validation.error
-                });
-              }
-              bodyData = validation.data;
+            if (!contentType.includes('application/json')) {
+              return res.badRequest("Content-Type must be application/json");
+            }
+
+            const body = await req.json();
+            const validation = handler.bodyValidation.safeParse(body);
+            if (!validation.success) {
+              return res.badRequest("Invalid request body", {
+                details: validation.error
+              });
             }
+            bodyData = validation.data;
           } catch (error) {
             return res.badRequest("Failed to parse request body");
           }
@@ -1358,14 +1375,7 @@ export class Server implements Party.Server {
    * @returns {boolean} True if the paths match
    */
   private pathMatches(requestPath: string, handlerPath: string): boolean {
-    // Convert handler path pattern to regex
-    // Replace :param with named capture groups
-    const pathRegexString = handlerPath
-      .replace(/\//g, '\\/') // Escape slashes
-      .replace(/:([^\/]+)/g, '([^/]+)'); // Convert :params to capture groups
-
-    const pathRegex = new RegExp(`^${pathRegexString}`);
-    return pathRegex.test(requestPath);
+    return this.pathPatternToRegex(handlerPath).test(requestPath);
   }
 
   /**
@@ -1387,12 +1397,7 @@ export class Server implements Party.Server {
       }
     });
 
-    // Extract parameter values from request path
-    const pathRegexString = handlerPath
-      .replace(/\//g, '\\/') // Escape slashes
-      .replace(/:([^\/]+)/g, '([^/]+)'); // Convert :params to capture groups
-
-    const pathRegex = new RegExp(`^${pathRegexString}`);
+    const pathRegex = this.pathPatternToRegex(handlerPath);
     const matches = requestPath.match(pathRegex);
 
     if (matches && matches.length > 1) {
@@ -1405,6 +1410,28 @@ export class Server implements Party.Server {
     return params;
   }
 
+  private normalizeRequestPath(pathname: string): string {
+    const parts = pathname.split('/').filter(Boolean);
+    if (parts[0] === 'parties' && parts.length >= 3) {
+      const routePath = parts.slice(3).join('/');
+      return routePath ? `/${routePath}` : '/';
+    }
+
+    return pathname || '/';
+  }
+
+  private pathPatternToRegex(handlerPath: string): RegExp {
+    const segments = handlerPath.split('/').map(segment => {
+      if (segment.startsWith(':')) {
+        return '([^/]+)';
+      }
+
+      return segment.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    });
+
+    return new RegExp(`^${segments.join('/')}$`);
+  }
+
   /**
    * @method handleShardRequest
    * @private

package/src/world.ts

@@ -1,10 +1,9 @@
 import { signal } from "@signe/reactive";
-import { Room, Action, Guard, Request } from "./decorators";
+import { Room, Guard, Request } from "./decorators";
 import { sync, id, persist } from "@signe/sync";
 import { z } from "zod";
 import * as Party from "./types/party";
 import { guardManageWorld } from "./world.guard";
-import { response } from "./utils";
 import { RoomInterceptorPacket, RoomOnJoin } from "./interfaces";
 import { ServerResponse } from "./request/response";
 
@@ -24,14 +23,8 @@ const RoomConfigSchema = z.object({
   maxShards: z.number().int().positive().optional(),
 });
 
-const RegisterShardSchema = z.object({
-  shardId: z.string(),
-  roomId: z.string(),
-  url: z.string().url(),
-  maxConnections: z.number().int().positive(),
-});
-
 const UpdateShardStatsSchema = z.object({
+  shardId: z.string(),
   connections: z.number().int().min(0),
   status: z.enum(['active', 'maintenance', 'draining']).optional(),
 });
@@ -139,8 +132,15 @@ export class WorldRoom implements RoomInterceptorPacket, RoomOnJoin {
     method: 'POST',
   })
   @Guard([guardManageWorld])
-  async registerRoom(req: Party.Request) {
-    const roomConfig: z.infer<typeof RoomConfigSchema> = await req.json();
+  async registerRoom(req: Party.Request, res?: ServerResponse) {
+    const roomConfigResult = RoomConfigSchema.safeParse(await req.json());
+    if (!roomConfigResult.success) {
+      return res?.badRequest("Invalid room configuration", {
+        details: roomConfigResult.error
+      });
+    }
+
+    const roomConfig = roomConfigResult.data;
     const roomId = roomConfig.name;
     
     if (!this.rooms()[roomId]) {
@@ -178,7 +178,14 @@ export class WorldRoom implements RoomInterceptorPacket, RoomOnJoin {
   })
   @Guard([guardManageWorld])
   async updateShardStats(req: Party.Request, res: ServerResponse) {
-    const body: { shardId: string; connections: number; status: ShardStatus } = await req.json();
+    const bodyResult = UpdateShardStatsSchema.safeParse(await req.json());
+    if (!bodyResult.success) {
+      return res.badRequest("Invalid shard statistics", {
+        details: bodyResult.error
+      });
+    }
+
+    const body = bodyResult.data;
     const { shardId, connections, status } = body;
     const shard = this.shards()[shardId];
 
@@ -199,7 +206,14 @@ export class WorldRoom implements RoomInterceptorPacket, RoomOnJoin {
   })
   @Guard([guardManageWorld])
   async scaleRoom(req: Party.Request, res: ServerResponse) {
-    const data: z.infer<typeof ScaleRoomSchema> = await req.json();
+    const dataResult = ScaleRoomSchema.safeParse(await req.json());
+    if (!dataResult.success) {
+      return res.badRequest("Invalid scale request", {
+        details: dataResult.error
+      });
+    }
+
+    const data = dataResult.data;
     const { targetShardCount, shardTemplate, roomId } = data;
     
     // Validate room exists
@@ -235,11 +249,6 @@ export class WorldRoom implements RoomInterceptorPacket, RoomOnJoin {
         })
         .slice(0, previousShardCount - targetShardCount);
       
-      // Remove the selected shards
-      const shardsToKeep = roomShards.filter(
-        shard => !shardsToRemove.some(s => s.id === shard.id)
-      );
-      
       // Update shards
       for (const shard of shardsToRemove) {
         delete this.shards()[shard.id];
@@ -448,4 +457,4 @@ export class WorldRoom implements RoomInterceptorPacket, RoomOnJoin {
     this.shards()[shardId] = newShard;
     return newShard;
   }
-}
+}