@signe/room 2.0.0 → 2.0.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@signe/room",
-  "version": "2.0.0",
+  "version": "2.0.1",
   "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.0.0"
+    "@signe/sync": "2.0.1"
   },
   "publishConfig": {
     "access": "public"

package/readme.md

@@ -75,7 +75,7 @@ The `@Request` decorator allows you to handle HTTP requests with specific routes
 
 ```ts
 import { z } from "zod";
-import { Room, Request, RequestGuard } from "@signe/room";
+import { Room, Request, RequestGuard, ServerResponse } from "@signe/room";
 
 @Room({
   path: "api"
@@ -97,10 +97,10 @@ class ApiRoom {
 
   // Handle requests with path parameters
   @Request({ path: "/players/:id" })
-  getPlayer(req: Party.Request, body: any, params: { id: string }) {
-    const player = this.players()[params.id];
+  getPlayer(req: Party.Request, res: ServerResponse) {
+    const player = this.players()[req.params.id];
     if (!player) {
-      return new Response(JSON.stringify({ error: "Player not found" }), { status: 404 });
+      return res.notFound("Player not found");
     }
     return player;
   }
@@ -113,10 +113,10 @@ class ApiRoom {
       score: z.number().min(0)
     })
   )
-  @RequestGuard([isAuthenticated])
-  submitScore(req: Party.Request, body: { playerId: string; score: number }) {
-    this.scores.update(scores => [...scores, body]);
-    return { success: true };
+  @Guard([isAuthenticated])
+  submitScore(req: Party.Request, res: ServerResponse) {
+    this.scores.update(scores => [...scores, req.data]);
+    return res.success({ success: true });
   }
 }
 ```
@@ -177,7 +177,7 @@ class AdminRoom {
   }
   
   @Request({ path: "/admin/users", method: "DELETE" })
-  @RequestGuard([isAdmin]) // Applied only to this request handler
+  @Guard([isAdmin]) // Applied only to this request handler
   async deleteUserViaHttp(req: Party.Request) {
     // Only authenticated admins can access this endpoint
   }
@@ -281,7 +281,15 @@ export default class MainServer extends Server {
 }
 ```
 
-2. Configure your `partykit.json` file:
+2. Add `Shard` to your server in `party/shard.ts`:
+
+```ts
+import { Shard } from '@signe/room';
+
+export default class ShardServer extends Shard {}
+```
+
+3. Configure your `partykit.json` file:
 
 ```json
 {

package/src/index.ts

@@ -4,4 +4,5 @@ export { Server } from './server';
 export * from './testing';
 export * from './shard';
 export * from './world';
-export * from './interfaces';
+export * from './interfaces';
+export * from './request/response';

package/src/request/cors.ts

@@ -0,0 +1,54 @@
+export function cors(res: Response, options: CorsOptions = {}) {
+  const newHeaders = new Headers(res.headers);
+  
+  // Set default CORS headers
+  newHeaders.set('Access-Control-Allow-Origin', options.origin || '*');
+  
+  if (options.credentials) {
+    newHeaders.set('Access-Control-Allow-Credentials', 'true');
+  }
+  
+  if (options.exposedHeaders && options.exposedHeaders.length) {
+    newHeaders.set('Access-Control-Expose-Headers', options.exposedHeaders.join(', '));
+  }
+  
+  // Handle preflight requests
+  if (options.methods && options.methods.length) {
+    newHeaders.set('Access-Control-Allow-Methods', options.methods.join(', '));
+  } else {
+    newHeaders.set('Access-Control-Allow-Methods', 'GET, POST, PUT, DELETE, PATCH, OPTIONS');
+  }
+  
+  if (options.allowedHeaders && options.allowedHeaders.length) {
+    newHeaders.set('Access-Control-Allow-Headers', options.allowedHeaders.join(', '));
+  } else {
+    newHeaders.set('Access-Control-Allow-Headers', 'Content-Type, Authorization, X-Requested-With');
+  }
+  
+  if (options.maxAge) {
+    newHeaders.set('Access-Control-Max-Age', options.maxAge.toString());
+  }
+  
+  return new Response(res.body, {
+    status: res.status,
+    headers: newHeaders
+  });
+}
+
+export interface CorsOptions {
+  origin?: string;
+  methods?: string[];
+  allowedHeaders?: string[];
+  exposedHeaders?: string[];
+  credentials?: boolean;
+  maxAge?: number;
+}
+
+/**
+ * Creates a CORS interceptor with the specified options
+ * @param options CORS configuration options
+ * @returns An interceptor function that can be used with ServerResponse
+ */
+export function createCorsInterceptor(options: CorsOptions = {}): (res: Response) => Response {
+  return (res: Response) => cors(res, options);
+}

package/src/request/response.ts

@@ -0,0 +1,228 @@
+export class ServerResponse {
+    private interceptors: ((res: Response) => Promise<Response> | Response)[];
+    private statusCode: number = 200;
+    private responseBody: any = {};
+    private responseHeaders: Record<string, string> = {
+        'Content-Type': 'application/json'
+    };
+
+    /**
+     * Creates a new ServerResponse instance
+     * @param interceptors Array of interceptor functions that can modify the response
+     */
+    constructor(interceptors: ((res: Response) => Promise<Response> | Response)[] = []) {
+        this.interceptors = interceptors;
+    }
+
+    /**
+     * Sets the status code for the response
+     * @param code HTTP status code
+     * @returns this instance for chaining
+     */
+    status(code: number): ServerResponse {
+        this.statusCode = code;
+        return this;
+    }
+
+    /**
+     * Sets the response body and returns this instance (chainable method)
+     * 
+     * @param body Response body
+     * @returns this instance for chaining
+     */
+    body(body: any): ServerResponse {
+        this.responseBody = body;
+        return this;
+    }
+
+    /**
+     * Adds a header to the response
+     * @param name Header name
+     * @param value Header value
+     * @returns this instance for chaining
+     */
+    header(name: string, value: string): ServerResponse {
+        this.responseHeaders[name] = value;
+        return this;
+    }
+
+    /**
+     * Adds multiple headers to the response
+     * @param headers Object containing headers
+     * @returns this instance for chaining
+     */
+    setHeaders(headers: Record<string, string>): ServerResponse {
+        this.responseHeaders = { ...this.responseHeaders, ...headers };
+        return this;
+    }
+
+    /**
+     * Add an interceptor to the chain
+     * @param interceptor Function that takes a Response and returns a modified Response
+     * @returns this instance for chaining
+     */
+    use(interceptor: (res: Response) => Promise<Response> | Response): ServerResponse {
+        this.interceptors.push(interceptor);
+        return this;
+    }
+
+    /**
+     * Builds and returns the Response object after applying all interceptors
+     * @returns Promise<Response> The final Response object
+     * @private Internal method used by terminal methods
+     */
+    private async buildResponse(): Promise<Response> {
+        // Create initial response
+        let response = new Response(JSON.stringify(this.responseBody), {
+            status: this.statusCode,
+            headers: this.responseHeaders
+        });
+
+        // Apply all interceptors sequentially
+        for (const interceptor of this.interceptors) {
+            try {
+                const interceptedResponse = interceptor(response);
+                if (interceptedResponse instanceof Promise) {
+                    response = await interceptedResponse;
+                } else {
+                    response = interceptedResponse;
+                }
+            } catch (error) {
+                console.error('Error in interceptor:', error);
+                // Continue with the current response if an interceptor fails
+            }
+        }
+
+        return response;
+    }
+
+    /**
+     * Sets the response body to the JSON-stringified version of the provided value
+     * and sends the response (terminal method)
+     * 
+     * @param body Response body to be JSON stringified
+     * @returns Promise<Response> The final Response object
+     */
+    async json(body: any): Promise<Response> {
+        this.responseBody = body;
+        this.responseHeaders['Content-Type'] = 'application/json';
+        return this.buildResponse();
+    }
+
+    /**
+     * Sends the response with the current configuration (terminal method)
+     * 
+     * @param body Optional body to set before sending
+     * @returns Promise<Response> The final Response object
+     */
+    async send(body?: any): Promise<Response> {
+        if (body !== undefined) {
+            this.responseBody = body;
+        }
+        return this.buildResponse();
+    }
+
+    /**
+     * Sends a plain text response (terminal method)
+     * 
+     * @param text Text to send
+     * @returns Promise<Response> The final Response object
+     */
+    async text(text: string): Promise<Response> {
+        this.responseBody = text;
+        this.responseHeaders['Content-Type'] = 'text/plain';
+        
+        // Create a text response without JSON stringifying the body
+        let response = new Response(text, {
+            status: this.statusCode,
+            headers: this.responseHeaders
+        });
+        
+        // Apply interceptors
+        for (const interceptor of this.interceptors) {
+            try {
+                const interceptedResponse = interceptor(response);
+                if (interceptedResponse instanceof Promise) {
+                    response = await interceptedResponse;
+                } else {
+                    response = interceptedResponse;
+                }
+            } catch (error) {
+                console.error('Error in interceptor:', error);
+            }
+        }
+        
+        return response;
+    }
+
+    /**
+     * Redirects to the specified URL (terminal method)
+     * 
+     * @param url URL to redirect to
+     * @param statusCode HTTP status code (default: 302)
+     * @returns Promise<Response> The final Response object
+     */
+    async redirect(url: string, statusCode: number = 302): Promise<Response> {
+        this.statusCode = statusCode;
+        this.responseHeaders['Location'] = url;
+        return this.buildResponse();
+    }
+
+    /**
+     * Creates a success response with status 200
+     * @param body Response body
+     * @returns Promise<Response> The final Response object
+     */
+    async success(body: any = {}): Promise<Response> {
+        return this.status(200).json(body);
+    }
+
+    /**
+     * Creates an error response with status 400
+     * @param message Error message
+     * @param details Additional error details
+     * @returns Promise<Response> The final Response object
+     */
+    async badRequest(message: string, details: any = {}): Promise<Response> {
+        return this.status(400).json({
+            error: message,
+            ...details
+        });
+    }
+
+    /**
+     * Creates an error response with status 403
+     * @param message Error message
+     * @returns Promise<Response> The final Response object
+     */
+    async notPermitted(message: string = "Not permitted"): Promise<Response> {
+        return this.status(403).json({ error: message });
+    }
+
+    /**
+     * Creates an error response with status 401
+     * @param message Error message
+     * @returns Promise<Response> The final Response object
+     */
+    async unauthorized(message: string = "Unauthorized"): Promise<Response> {
+        return this.status(401).json({ error: message });
+    }
+
+    /**
+     * Creates an error response with status 404
+     * @param message Error message
+     * @returns Promise<Response> The final Response object
+     */
+    async notFound(message: string = "Not found"): Promise<Response> {
+        return this.status(404).json({ error: message });
+    }
+
+    /**
+     * Creates an error response with status 500
+     * @param message Error message
+     * @returns Promise<Response> The final Response object
+     */
+    async serverError(message: string = "Internal Server Error"): Promise<Response> {
+        return this.status(500).json({ error: message });
+    }
+}

package/src/server.ts

@@ -16,6 +16,8 @@ import {
   isClass,
   throttle,
 } from "./utils";
+import { ServerResponse } from "./request/response";
+import { createCorsInterceptor } from "./request/cors";
 
 const Message = z.object({
   action: z.string(),
@@ -843,13 +845,16 @@ export class Server implements Party.Server {
     // Check if the request is coming from a shard
     const isFromShard = req.headers.has('x-forwarded-by-shard');
     const shardId = req.headers.get('x-shard-id');
+    const res = new ServerResponse([
+      createCorsInterceptor()
+    ]);
 
     if (isFromShard) {
-      return this.handleShardRequest(req, shardId);
+      return this.handleShardRequest(req, res, shardId);
     }
 
     // Handle regular client request
-    return this.handleDirectRequest(req);
+    return this.handleDirectRequest(req, res);
   }
 
   /**
@@ -860,35 +865,27 @@ export class Server implements Party.Server {
    * @description Processes requests received directly from clients
    * @returns {Promise<Response>} The response to return to the client
    */
-  private async handleDirectRequest(req: Party.Request): Promise<Response> {
+  private async handleDirectRequest(req: Party.Request, res: ServerResponse): Promise<Response> {
     const subRoom = await this.getSubRoom();
-    const res = (body: any, status: number) => {
-      return new Response(JSON.stringify(body), { status });
-    };
-
     if (!subRoom) {
-      return res({
-        error: "Not found"
-      }, 404);
+      return res.notFound();
     }
 
     // First try to match using the registered @Request handlers
-    const response = await this.tryMatchRequestHandler(req, subRoom);
+    const response = await this.tryMatchRequestHandler(req, res, subRoom);
     if (response) {
       return response;
     }
 
     // Fall back to the legacy onRequest method if no handler matched
-    const legacyResponse = await awaitReturn(subRoom["onRequest"]?.(req, this.room));
+    const legacyResponse = await awaitReturn(subRoom["onRequest"]?.(req, res));
     if (!legacyResponse) {
-      return res({
-        error: "Not found"
-      }, 404);
+      return res.notFound();
     }
     if (legacyResponse instanceof Response) {
       return legacyResponse;
     }
-    return res(legacyResponse, 200);
+    return res.success(legacyResponse);
   }
 
   /**
@@ -900,7 +897,7 @@ export class Server implements Party.Server {
    * @description Attempts to match the request to a registered @Request handler
    * @returns {Promise<Response | null>} The response or null if no handler matched
    */
-  private async tryMatchRequestHandler(req: Party.Request, subRoom: any): Promise<Response | null> {
+  private async tryMatchRequestHandler(req: Party.Request, res: ServerResponse, subRoom: any): Promise<Response | null> {
     const requestHandlers = subRoom.constructor["_requestMetadata"];
     if (!requestHandlers) {
       return null;
@@ -935,7 +932,7 @@ export class Server implements Party.Server {
             return isAuthorized;
           }
           if (!isAuthorized) {
-            return new Response(JSON.stringify({ error: "Unauthorized" }), { status: 403 });
+            return res.notPermitted();
           }
         }
 
@@ -948,44 +945,33 @@ export class Server implements Party.Server {
               const body = await req.json();
               const validation = handler.bodyValidation.safeParse(body);
               if (!validation.success) {
-                return new Response(
-                  JSON.stringify({ error: "Invalid request body", details: validation.error }),
-                  { status: 400 }
-                );
+                return res.badRequest("Invalid request body", {
+                  details: validation.error
+                });
               }
               bodyData = validation.data;
             }
           } catch (error) {
-            return new Response(
-              JSON.stringify({ error: "Failed to parse request body" }),
-              { status: 400 }
-            );
+            return res.badRequest("Failed to parse request body");
           }
         }
 
         // Execute the handler method
         try {
+          req['data'] = bodyData;
+          req['params'] = params;
           const result = await awaitReturn(
-            subRoom[handler.key](req, bodyData, params, this.room)
+            subRoom[handler.key](req, res)
           );
 
           if (result instanceof Response) {
             return result;
           }
 
-          return new Response(
-            typeof result === 'string' ? result : JSON.stringify(result),
-            {
-              status: 200,
-              headers: { 'Content-Type': typeof result === 'string' ? 'text/plain' : 'application/json' }
-            }
-          );
+          return res.success(result);
         } catch (error) {
           console.error('Error executing request handler:', error);
-          return new Response(
-            JSON.stringify({ error: "Internal server error" }),
-            { status: 500 }
-          );
+          return res.serverError();
         }
       }
     }
@@ -1058,11 +1044,11 @@ export class Server implements Party.Server {
    * @description Processes requests forwarded by shards, preserving client context
    * @returns {Promise<Response>} The response to return to the shard (which will forward it to the client)
    */
-  private async handleShardRequest(req: Party.Request, shardId: string | null): Promise<Response> {
+  private async handleShardRequest(req: Party.Request, res: ServerResponse, shardId: string | null): Promise<Response> {
     const subRoom = await this.getSubRoom();
 
     if (!subRoom) {
-      return new Response(JSON.stringify({ error: "Not found" }), { status: 404 });
+      return res.notFound();
     }
 
     // Create a context that preserves original client information
@@ -1071,26 +1057,26 @@ export class Server implements Party.Server {
 
     try {
       // First try to match using the registered @Request handlers
-      const response = await this.tryMatchRequestHandler(enhancedReq, subRoom);
+      const response = await this.tryMatchRequestHandler(enhancedReq, res, subRoom);
       if (response) {
         return response;
       }
 
       // Fall back to the legacy onRequest handler
-      const legacyResponse = await awaitReturn(subRoom["onRequest"]?.(enhancedReq, this.room));
+      const legacyResponse = await awaitReturn(subRoom["onRequest"]?.(enhancedReq, res));
 
       if (!legacyResponse) {
-        return new Response(JSON.stringify({ error: "Not found" }), { status: 404 });
+        return res.notFound();
       }
 
       if (legacyResponse instanceof Response) {
         return legacyResponse;
       }
 
-      return new Response(JSON.stringify(legacyResponse), { status: 200 });
+      return res.success(legacyResponse);
     } catch (error) {
       console.error(`Error processing request from shard ${shardId}:`, error);
-      return new Response(JSON.stringify({ error: "Internal server error" }), { status: 500 });
+      return res.serverError();
     }
   }
 

package/src/world.ts

@@ -6,6 +6,7 @@ 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";
 
 // Types definitions
 type BalancingStrategy = 'round-robin' | 'least-connections' | 'random';
@@ -173,13 +174,13 @@ export class WorldRoom implements RoomInterceptorPacket, RoomOnJoin {
     method: 'POST',
   })
   @Guard([guardManageWorld])
-  async updateShardStats(req: Party.Request) {
+  async updateShardStats(req: Party.Request, res: ServerResponse) {
     const body: { shardId: string; connections: number; status: ShardStatus } = await req.json();
     const { shardId, connections, status } = body;
     const shard = this.shards()[shardId];
 
     if (!shard) {
-      return { error: `Shard ${shardId} not found` };
+      return res.notFound(`Shard ${shardId} not found`);
     }
     
     shard.currentConnections.set(connections);
@@ -194,14 +195,14 @@ export class WorldRoom implements RoomInterceptorPacket, RoomOnJoin {
     method: 'POST',
   })
   @Guard([guardManageWorld])
-  async scaleRoom(req: Party.Request) {
+  async scaleRoom(req: Party.Request, res: ServerResponse) {
     const data: z.infer<typeof ScaleRoomSchema> = await req.json();
     const { targetShardCount, shardTemplate, roomId } = data;
     
     // Validate room exists
     const room = this.rooms()[roomId];
     if (!room) {
-      return { error: `Room ${roomId} does not exist` };
+      return res.notFound(`Room ${roomId} does not exist`);
     }
     
     const roomShards = Object.values(this.shards())
@@ -211,11 +212,10 @@ export class WorldRoom implements RoomInterceptorPacket, RoomOnJoin {
     
     // Check max shards constraint
     if (room.maxShards() !== undefined && targetShardCount > room.maxShards()!) {
-      return {
-        error: `Cannot scale beyond maximum allowed shards (${room.maxShards()})`,
+      return res.badRequest(`Cannot scale beyond maximum allowed shards (${room.maxShards()})`, {
         roomId,
         currentShardCount: previousShardCount
-      };
+      });
     }
     
     // Handle scaling down
@@ -268,7 +268,7 @@ export class WorldRoom implements RoomInterceptorPacket, RoomOnJoin {
     path: 'connect',
     method: 'POST',
   })
-  async connect(req: Party.Request) {
+  async connect(req: Party.Request, res: ServerResponse) {
     try {
       // Extract request data
       let data: { roomId: string; autoCreate?: boolean };
@@ -277,17 +277,17 @@ export class WorldRoom implements RoomInterceptorPacket, RoomOnJoin {
         // Handle potential empty body or malformed JSON
         const body = await req.text();
         if (!body || body.trim() === '') {
-          return response(400, { error: "Request body is empty" });
+          return res.badRequest("Request body is empty");
         }
         
         data = JSON.parse(body);
       } catch (parseError) {
-        return response(400, { error: "Invalid JSON in request body" });
+        return res.badRequest("Invalid JSON in request body");
       }
       
       // Verify roomId is provided
       if (!data.roomId) {
-        return response(400, { error: "roomId parameter is required" });
+        return res.badRequest("roomId parameter is required");
       }
       
       // Determine if auto-creation is enabled (default to true)
@@ -298,18 +298,18 @@ export class WorldRoom implements RoomInterceptorPacket, RoomOnJoin {
  
       // Check for errors
       if ('error' in result) {
-        return response(404, { error: result.error });
+        return res.notFound(result.error);
       }
       
       // Return shard information to the client
-      return response(200, {
+      return res.success({
         success: true,
         shardId: result.shardId,
         url: result.url
       });
     } catch (error) {
       console.error('Error connecting to shard:', error);
-      return response(500, { error: "Internal server error", details: error instanceof Error ? error.message : String(error) });
+      return res.serverError();
     }
   }