@signe/room 1.4.2 → 2.0.0

package/examples/game/app/components/Room.tsx

@@ -0,0 +1,158 @@
+import { useState, useEffect, useRef } from "react";
+import { connectionWorld } from '../../../../../sync/src/client';
+import { RoomSchema } from "../../shared/room.schema";
+import { effect } from "@signe/reactive";
+
+export default function Room() {
+  const [isConnected, setIsConnected] = useState(false);
+  const [isConnecting, setIsConnecting] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const [roomId, setRoomId] = useState("quiz");
+  const [count, setCount] = useState(0);
+  const socketRef = useRef<any>(null);
+  const roomRef = useRef<any>(null);
+
+  const connectToRoom = async () => {
+    setIsConnecting(true);
+    setError(null);
+    
+    try {
+      // Initialize room schema
+      roomRef.current = new RoomSchema();
+      
+      // Connect to the room through the World service with auto-creation enabled
+      socketRef.current = await connectionWorld({
+        worldUrl: 'http://localhost:1999',
+        roomId: roomId,
+        autoCreate: true // Enable auto-creation of room and shards
+      }, roomRef.current);
+      
+      // Listen for disconnection events
+      socketRef.current.on('disconnect', () => {
+        setIsConnected(false);
+        setError('Disconnected from server');
+      });
+
+      effect(() => {
+        if (roomRef.current) {
+          setCount(roomRef.current.count());
+        }
+      });
+      
+      setIsConnected(true);
+    } catch (err) {
+      console.error('Connection error:', err);
+      setError(`Failed to connect to the room: ${err instanceof Error ? err.message : String(err)}`);
+    } finally {
+      setIsConnecting(false);
+    }
+  };
+
+  const disconnectFromRoom = () => {
+    if (socketRef.current) {
+      socketRef.current.close();
+      socketRef.current = null;
+    }
+    roomRef.current = null;
+    setIsConnected(false);
+  };
+  
+  // Clean up on component unmount
+  useEffect(() => {
+    return () => {
+      if (socketRef.current) {
+        socketRef.current.close();
+      }
+    };
+  }, []);
+
+  // Styles
+  const buttonStyles = {
+    backgroundColor: isConnected ? "#f43f5e" : "#2563eb",
+    borderRadius: "9999px",
+    border: "none",
+    color: "white",
+    fontSize: "0.95rem",
+    cursor: "pointer",
+    padding: "1rem 3rem",
+    margin: "1rem 0rem",
+    disabled: isConnecting
+  };
+
+  const inputStyles = {
+    padding: "0.75rem 1rem",
+    borderRadius: "0.5rem",
+    border: "1px solid #ccc",
+    fontSize: "0.95rem",
+    width: "100%",
+    maxWidth: "300px",
+    margin: "0.5rem 0"
+  };
+
+  const containerStyles = {
+    display: "flex",
+    flexDirection: "column" as "column",
+    alignItems: "center",
+    justifyContent: "center",
+    padding: "2rem",
+    gap: "1rem"
+  };
+
+  return (
+    <div style={containerStyles}>
+      <h1>Room Connection</h1>
+      
+      {error && (
+        <div style={{ color: "red", margin: "1rem 0" }}>
+          {error}
+        </div>
+      )}
+      
+      {!isConnected ? (
+        <>
+          <div style={{ marginBottom: "1rem", width: "100%", maxWidth: "300px" }}>
+            <label htmlFor="roomId" style={{ display: "block", marginBottom: "0.5rem" }}>
+              Room ID:
+            </label>
+            <input
+              id="roomId"
+              type="text"
+              value={roomId}
+              onChange={(e) => setRoomId(e.target.value)}
+              style={inputStyles}
+              placeholder="Enter room ID"
+              disabled={isConnecting}
+            />
+          </div>
+          
+          <button 
+            style={buttonStyles} 
+            onClick={connectToRoom}
+            disabled={isConnecting || !roomId.trim()}
+          >
+            {isConnecting ? "Connecting..." : "Connect to Room"}
+          </button>
+        </>
+      ) : (
+        <>
+          <div style={{ marginBottom: "1rem" }}>
+            <span style={{ fontWeight: "bold" }}>Connected to room: </span>
+            <span>{roomId}</span>
+          </div>
+          
+          <div style={{ marginBottom: "2rem" }}>
+            <span>Count: {count}</span>
+            <button className="btn btn-primary" onClick={() => socketRef.current.emit('increment')}>Increment</button>
+          </div>
+          
+          <button 
+            style={buttonStyles} 
+            onClick={disconnectFromRoom}
+          >
+            Leave Room
+          </button>
+        </>
+      )}
+    </div>
+  );
+} 

package/examples/game/party/server.ts

@@ -1,9 +1,10 @@
-import { Server } from '../../../src';
+import { Server, WorldRoom } from '../../../src';
 import type * as Party from "../../../src/types/party";
 import { GameRoom } from "./game.room";
 
 export default class MainServer extends Server {
   rooms = [
-    GameRoom 
+    GameRoom ,
+    WorldRoom
   ]
 }

package/examples/game/party/shard.ts

@@ -0,0 +1,5 @@
+import { Shard } from '../../../src';
+
+export default class MyShard extends Shard {
+
+}

package/examples/game/partykit.json

@@ -2,7 +2,11 @@
   "$schema": "https://www.partykit.io/schema.json",
   "name": "signe",
   "main": "party/server.ts",
-  "compatibilityDate": "2024-06-09",
+  "compatibilityDate": "2025-02-04",
+  "parties": {
+    "shard": "party/shard.ts",
+    "world": "party/server.ts"
+  },
   "serve": {
     "path": "public",
     "build": "app/client.tsx"

package/package.json

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

package/readme.md

@@ -13,6 +13,7 @@ npm install @signe/room @signe/reactive @signe/sync
 - 🔄 Automatic state synchronization across clients
 - 👥 Built-in user management with customizable player classes
 - 🎮 Action-based message handling with type safety
+- 🌐 HTTP request routing with path parameters
 - 🔐 Flexible authentication and authorization system
 - 🛡️ Guard system for room and action-level security
 - 🎯 Full TypeScript support
@@ -58,7 +59,7 @@ export default class GameServer extends Server {
 }
 ```
 
-## Action 
+## Action 
 
 An action is a function that is called when a client sends a message to the server.
 
@@ -68,6 +69,69 @@ 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
 
+## 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 } from "@signe/room";
+
+@Room({
+  path: "api"
+})
+class ApiRoom {
+  @sync() gameState = signal("waiting");
+  @users(Player) players = signal({});
+  @sync() scores = signal([]);
+
+  // Handle GET requests
+  @Request({ path: "/status" })
+  getStatus(req: Party.Request) {
+    return {
+      status: "online",
+      players: Object.keys(this.players()).length,
+      gameState: this.gameState(),
+    };
+  }
+
+  // Handle requests with path parameters
+  @Request({ path: "/players/:id" })
+  getPlayer(req: Party.Request, body: any, params: { id: string }) {
+    const player = this.players()[params.id];
+    if (!player) {
+      return new Response(JSON.stringify({ error: "Player not found" }), { status: 404 });
+    }
+    return player;
+  }
+
+  // Handle POST requests with body validation
+  @Request(
+    { path: "/scores", method: "POST" },
+    z.object({ 
+      playerId: z.string(),
+      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 };
+  }
+}
+```
+
+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
+
+You can return:
+- A Response object for complete control
+- An object that will be serialized as JSON
+- A string that will be returned as text/plain
+
 ## Advanced Features
 
 ### Room Configuration
@@ -111,6 +175,12 @@ class AdminRoom {
   async deleteUser(admin: Player, userId: string) {
     // Only authenticated admins can execute this
   }
+  
+  @Request({ path: "/admin/users", method: "DELETE" })
+  @RequestGuard([isAdmin]) // Applied only to this request handler
+  async deleteUserViaHttp(req: Party.Request) {
+    // Only authenticated admins can access this endpoint
+  }
 }
 ```
 
@@ -176,13 +246,167 @@ class GameRoom {
 }
 ```
 
+### Connecting to World Service
+
+The World Service provides optimal room and shard assignment for distributed applications. It handles load balancing and allows clients to connect to the most appropriate server.
+
+#### Environment Variables
+
+To use the Signe room system, you need to configure two essential environment variables:
+
+```env
+# Required for JWT authentication
+AUTH_JWT_SECRET=a-string-secret-at-least-256-bits-long
+
+# Required for secure communication between shards
+SHARD_SECRET=your_shard_secret
+```
+
+These secrets should be strong, unique values and kept secure.
+
+#### Server Configuration
+
+To use the World service, you need to:
+
+1. Add `WorldRoom` to your server:
+
+```ts
+import { Server, WorldRoom } from '@signe/room';
+
+export default class MainServer extends Server {
+  rooms = [
+    GameRoom,
+    WorldRoom // Add WorldRoom to enable World service
+  ]
+}
+```
+
+2. Configure your `partykit.json` file:
+
+```json
+{
+  "$schema": "https://www.partykit.io/schema.json",
+  "name": "yourapp",
+  "main": "party/server.ts",
+  "compatibilityDate": "2025-02-04",
+  "parties": {
+    "shard": "party/shard.ts", // Shard implementation
+    "world": "party/server.ts" // World service implementation
+  }
+}
+```
+
+#### Client Connection
+
+On the client side, use the `connectionWorld` function to connect to your room through the World service:
+
+```js
+import { connectionWorld } from '@signe/sync/client';
+
+// Initialize your room instance
+const room = new YourRoomSchema();
+
+// Connect through the World service
+const connection = await connectionWorld({
+  worldUrl: 'https://your-app-url.com', // Your application URL
+  roomId: 'unique-room-id',             // Room identifier
+  worldId: 'your-world-id',             // Optional, defaults to 'world-default'
+  autoCreate: true,                     // Auto-create room if it doesn't exist
+  retryCount: 3,                        // Number of connection attempts
+  retryDelay: 1000,                     // Delay between retries in ms
+  socketOptions: {                      // Optional PartySocket configuration
+    protocols: ['your-protocol']
+  }
+}, room);
+
+// Listen for events
+connection.on('customEvent', (data) => {
+  console.log('Received custom event:', data);
+});
+
+// Send events to the room
+connection.emit('increment', { value: 1 });
+
+// Close the connection when done
+connection.close();
+```
+
+For connecting to a standard room (not through World service), use the `connectionRoom` function:
+
+```js
+import { connectionRoom } from '@signe/sync/client';
+
+// Initialize your room instance
+const room = new YourRoomSchema();
+
+// Connect directly to a room
+const connection = await connectionRoom({
+  host: window.location.origin,
+  room: 'your-room-name',
+  party: 'your-party-name', // Optional, defaults to main party
+  query: {} // Optional query parameters
+}, room);
+
+// For connecting to a World room with authentication
+const worldConnection = await connectionRoom({
+  host: window.location.origin,
+  room: 'world-default',
+  party: 'world',
+  query: {
+    // Use pre-generated JWT token for authentication
+    'world-auth-token': 'your-jwt-token'
+  }
+}, worldRoom);
+```
+
+The `connectionWorld` function:
+1. Queries the World service to find the optimal shard for the requested room
+2. Establishes a WebSocket connection to the assigned shard
+3. Returns a connection object with methods for sending and receiving messages
+
+This approach offers several benefits:
+- Automatic load balancing across multiple servers
+- Simplified connection management
+- Built-in retry logic for reliability
+- Room creation on demand
+
+### Packet Interception
+
+You can implement the `interceptorPacket` method in your room to inspect and modify packets before they're sent to users:
+
+```ts
+class GameRoom {
+  // Intercept packets before they're sent to users
+  async interceptorPacket(user: Player, packet: any, conn: Party.Connection) {
+    // Modify the packet based on user-specific logic
+    if (user.role === 'spectator') {
+      delete modifiedPacket.secretData;
+      return modifiedPacket;
+    }
+    
+    // Return null to prevent the packet from being sent to this user
+    if (user.isBlocked) {
+      return null;
+    }
+    
+    // Return the packet as is or with modifications
+    return packet;
+  }
+}
+```
+
+The `interceptorPacket` method allows you to:
+- Modify packets on a per-user basis before they're sent
+- Return a modified packet to change what the user receives
+- Return `null` to prevent the packet from being sent to that user
+- Implement user-specific filtering or censoring of data
+
 ### Lifecycle Hooks
 
 Rooms provide several lifecycle hooks:
 
 ```ts
 class GameRoom {
-  async onCreate()
   async onJoin(player: Player, conn: Connection, ctx: ConnectionContext) {}
   async onLeave(player: Player, conn: Connection) {}
 }

package/src/decorators.ts

@@ -1,7 +1,7 @@
 import type * as Party from "./types/party"
 import type { z } from "zod"
-type GuardFn = (sender: Party.Connection, value: any) => boolean | Promise<boolean>;
-type RoomGuardFn = (conn: Party.Connection, ctx: Party.ConnectionContext) => boolean | Promise<boolean>;
+type GuardFn = (sender: Party.Connection, value: any | Party.Request, room: Party.Room) => boolean | Promise<boolean | Response>;
+type RoomGuardFn = (conn: Party.Connection, ctx: Party.ConnectionContext, room: Party.Room) => boolean | Promise<boolean | Response>;
 
 export function Action(name: string, bodyValidation?: z.ZodSchema) {
   return function (target: any, propertyKey: string) {
@@ -15,6 +15,38 @@ export function Action(name: string, bodyValidation?: z.ZodSchema) {
   };
 }
 
+/**
+ * Request decorator for handling HTTP requests with path and method routing
+ * @param options Configuration for the HTTP request handler
+ * @param bodyValidation Optional Zod schema for request body validation
+ */
+export interface RequestOptions {
+  path: string;
+  method?: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'OPTIONS' | 'HEAD';
+}
+
+export function Request(options: RequestOptions, bodyValidation?: z.ZodSchema) {
+  return function (target: any, propertyKey: string) {
+    if (!target.constructor._requestMetadata) {
+      target.constructor._requestMetadata = new Map();
+    }
+    
+    // Format the path to ensure it starts with a slash
+    const path = options.path.startsWith('/') ? options.path : `/${options.path}`;
+    const method = options.method || 'GET';
+    
+    // Create a unique key for this route using method and path
+    const routeKey = `${method}:${path}`;
+    
+    target.constructor._requestMetadata.set(routeKey, {
+      key: propertyKey,
+      path,
+      method,
+      bodyValidation,
+    });
+  };
+}
+
 export interface RoomOptions {
   path: string;
   maxUsers?: number;

package/src/index.ts

@@ -1,4 +1,7 @@
 export * from './decorators';
 export { ClientIo, MockConnection, ServerIo } from './mock';
 export { Server } from './server';
-export * from './testing';
+export * from './testing';
+export * from './shard';
+export * from './world';
+export * from './interfaces';

package/src/interfaces.ts

@@ -0,0 +1,13 @@
+import * as Party from "./types/party";
+
+export interface RoomInterceptorPacket {
+  interceptorPacket(user: any, obj: any, conn: Party.Connection): Promise<any> | null | any;
+}
+
+export interface RoomOnJoin {
+  onJoin(user: any, conn: Party.Connection, ctx: Party.ConnectionContext): Promise<any> | null | any;
+}
+
+export interface RoomOnLeave {
+  onLeave(user: any, conn: Party.Connection, ctx: Party.ConnectionContext): Promise<any> | null | any;
+}