@signe/room 1.4.1 → 2.0.0

package/dist/index.d.ts

@@ -1,19 +1,20 @@
-import { Request as Request$1, DurableObjectStorage, WebSocket, DurableObjectState, AnalyticsEngineDataset, VectorizeIndex, R2Bucket, KVNamespace } from '@cloudflare/workers-types';
+import { Request as Request$2, DurableObjectStorage, WebSocket, DurableObjectState, AnalyticsEngineDataset, VectorizeIndex, R2Bucket, KVNamespace } from '@cloudflare/workers-types';
 import { z } from 'zod';
+import * as _signe_reactive from '@signe/reactive';
 
 type AssetFetcher = {
     fetch(path: string): Promise<Response | null>;
 };
 type StandardRequest = globalThis.Request;
-interface Request extends Request$1 {
+interface Request$1 extends Request$2 {
 }
-type ReturnRequest = StandardRequest | Request$1;
+type ReturnRequest = StandardRequest | Request$2;
 /** Per-party key-value storage */
 interface Storage$1 extends DurableObjectStorage {
 }
 /** Connection metadata only available when the connection is made */
 type ConnectionContext = {
-    request: Request$1;
+    request: Request$2;
 };
 type Stub = {
     /** @deprecated Use `await socket()` instead */
@@ -151,7 +152,7 @@ type Server$1 = {
     /**
      * Called when a HTTP request is made to the room URL.
      */
-    onRequest?(req: Request): Response | Promise<Response>;
+    onRequest?(req: Request$1): Response | Promise<Response>;
     /**
      * Called when an alarm is triggered. Use Party.storage.setAlarm to set an alarm.
      *
@@ -171,9 +172,19 @@ type ServerOptions = {
     hibernate?: boolean;
 };
 
-type GuardFn = (sender: Connection, value: any) => boolean | Promise<boolean>;
-type RoomGuardFn = (conn: Connection, ctx: ConnectionContext) => boolean | Promise<boolean>;
+type GuardFn = (sender: Connection, value: any | Request$1, room: Room$1) => boolean | Promise<boolean | Response>;
+type RoomGuardFn = (conn: Connection, ctx: ConnectionContext, room: Room$1) => boolean | Promise<boolean | Response>;
 declare function Action(name: string, bodyValidation?: z.ZodSchema): (target: any, propertyKey: string) => void;
+/**
+ * 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
+ */
+interface RequestOptions {
+    path: string;
+    method?: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'OPTIONS' | 'HEAD';
+}
+declare function Request(options: RequestOptions, bodyValidation?: z.ZodSchema): (target: any, propertyKey: string) => void;
 interface RoomOptions {
     path: string;
     maxUsers?: number;
@@ -244,6 +255,8 @@ declare class Server implements Server$1 {
       */
     get isHibernate(): boolean;
     get roomStorage(): Storage$1;
+    send(conn: Connection, obj: any, subRoom: any): Promise<void>;
+    broadcast(obj: any, subRoom: any): void;
     /**
      * @method onStart
      * @async
@@ -315,6 +328,7 @@ declare class Server implements Server$1 {
     private saveSession;
     private updateSessionConnection;
     private deleteSession;
+    onConnectClient(conn: Connection, ctx: ConnectionContext): Promise<void>;
     /**
      * @method onConnect
      * @async
@@ -332,23 +346,64 @@ declare class Server implements Server$1 {
      * ```
      */
     onConnect(conn: Connection, ctx: ConnectionContext): Promise<void>;
+    /**
+     * @method onConnectShard
+     * @private
+     * @param {Party.Connection} conn - The connection object for the new shard.
+     * @param {Party.ConnectionContext} ctx - The context of the shard connection.
+     * @description Handles a new shard connection, setting up the necessary state.
+     * @returns {void}
+     */
+    onConnectShard(conn: Connection, ctx: ConnectionContext): void;
     /**
      * @method onMessage
      * @async
-     * @param {string} message - The message received from a user.
+     * @param {string} message - The message received from a user or shard.
      * @param {Party.Connection} sender - The connection object of the sender.
-     * @description Processes incoming messages and triggers corresponding actions in the sub-room.
+     * @description Processes incoming messages, handling differently based on if sender is shard or client.
      * @returns {Promise<void>}
-     *
-     * @example
-     * ```typescript
-     * server.onMessage = async (message, sender) => {
-     *   await server.onMessage(message, sender);
-     *   console.log("Message processed from:", sender.id);
-     * };
-     * ```
      */
     onMessage(message: string, sender: Connection): Promise<void>;
+    /**
+     * @method handleShardMessage
+     * @private
+     * @async
+     * @param {string} message - The message received from a shard.
+     * @param {Party.Connection} shardConnection - The connection object of the shard.
+     * @description Processes messages from shards, extracting client information.
+     * @returns {Promise<void>}
+     */
+    private handleShardMessage;
+    /**
+     * @method handleShardClientConnect
+     * @private
+     * @async
+     * @param {Object} message - The client connection message from a shard.
+     * @param {Party.Connection} shardConnection - The connection object of the shard.
+     * @description Handles a new client connection via a shard.
+     * @returns {Promise<void>}
+     */
+    private handleShardClientConnect;
+    /**
+     * @method handleShardClientMessage
+     * @private
+     * @async
+     * @param {Object} message - The client message from a shard.
+     * @param {Party.Connection} shardConnection - The connection object of the shard.
+     * @description Handles a message from a client via a shard.
+     * @returns {Promise<void>}
+     */
+    private handleShardClientMessage;
+    /**
+     * @method handleShardClientDisconnect
+     * @private
+     * @async
+     * @param {Object} message - The client disconnection message from a shard.
+     * @param {Party.Connection} shardConnection - The connection object of the shard.
+     * @description Handles a client disconnection via a shard.
+     * @returns {Promise<void>}
+     */
+    private handleShardClientDisconnect;
     /**
      * @method onClose
      * @async
@@ -367,7 +422,70 @@ declare class Server implements Server$1 {
     onClose(conn: Connection): Promise<void>;
     onAlarm(): Promise<void>;
     onError(connection: Connection, error: Error): Promise<void>;
-    onRequest(req: Request): Promise<Response>;
+    /**
+     * @method onRequest
+     * @async
+     * @param {Party.Request} req - The HTTP request to handle
+     * @description Handles HTTP requests, either directly from clients or forwarded by shards
+     * @returns {Promise<Response>} The response to return to the client
+     */
+    onRequest(req: Request$1): Promise<Response>;
+    /**
+     * @method handleDirectRequest
+     * @private
+     * @async
+     * @param {Party.Request} req - The HTTP request received directly from a client
+     * @description Processes requests received directly from clients
+     * @returns {Promise<Response>} The response to return to the client
+     */
+    private handleDirectRequest;
+    /**
+     * @method tryMatchRequestHandler
+     * @private
+     * @async
+     * @param {Party.Request} req - The HTTP request to handle
+     * @param {Object} subRoom - The room instance
+     * @description Attempts to match the request to a registered @Request handler
+     * @returns {Promise<Response | null>} The response or null if no handler matched
+     */
+    private tryMatchRequestHandler;
+    /**
+     * @method pathMatches
+     * @private
+     * @param {string} requestPath - The path from the request
+     * @param {string} handlerPath - The path pattern from the handler
+     * @description Checks if a request path matches a handler path pattern
+     * @returns {boolean} True if the paths match
+     */
+    private pathMatches;
+    /**
+     * @method extractPathParams
+     * @private
+     * @param {string} requestPath - The path from the request
+     * @param {string} handlerPath - The path pattern from the handler
+     * @description Extracts path parameters from the request path based on the handler pattern
+     * @returns {Object} An object containing the path parameters
+     */
+    private extractPathParams;
+    /**
+     * @method handleShardRequest
+     * @private
+     * @async
+     * @param {Party.Request} req - The HTTP request forwarded by a shard
+     * @param {string | null} shardId - The ID of the shard that forwarded the request
+     * @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 handleShardRequest;
+    /**
+     * @method createEnhancedRequest
+     * @private
+     * @param {Party.Request} originalReq - The original request received from the shard
+     * @param {string | null} originalClientIp - The original client IP, if available
+     * @description Creates an enhanced request object that preserves the original client context
+     * @returns {Party.Request} The enhanced request object
+     */
+    private createEnhancedRequest;
 }
 
 declare class Storage {
@@ -389,16 +507,24 @@ declare class MockPartyClient {
     _trigger(event: any, data: any): void;
     send(data: any): Promise<void>;
 }
+declare class MockContext {
+    room: MockPartyRoom;
+    parties: {
+        main: Map<string, any>;
+    };
+    constructor(room: MockPartyRoom, options?: any);
+}
 declare class MockPartyRoom {
     id?: string;
     clients: Map<string, MockPartyClient>;
     storage: Storage;
+    context: MockContext;
     env: {};
-    constructor(id?: string);
+    constructor(id?: string, options?: any);
     connection(server: Server): Promise<MockPartyClient>;
     broadcast(data: any): void;
     getConnection(id: string): MockPartyClient;
-    getConnections(): Map<string, MockPartyClient>;
+    getConnections(): MockConnection[];
     clear(): void;
 }
 declare class MockConnection {
@@ -414,6 +540,50 @@ declare class MockConnection {
 declare const ServerIo: typeof MockPartyRoom;
 declare const ClientIo: typeof MockPartyClient;
 
+interface PartyWebSocket {
+    send: (data: string | ArrayBufferLike | Blob | ArrayBufferView) => void;
+    addEventListener: (type: string, listener: (event: any) => void) => void;
+    close: () => void;
+}
+interface ShardOptions {
+    worldUrl?: string;
+    worldId?: string;
+    statsInterval?: number;
+}
+declare class Shard {
+    private room;
+    ws: PartyWebSocket;
+    connectionMap: Map<string, Connection<unknown>>;
+    mainServerStub: any;
+    worldUrl: string | null;
+    worldId: string;
+    lastReportedConnections: number;
+    statsInterval: number;
+    statsIntervalId: any;
+    constructor(room: Room$1);
+    onStart(): Promise<void>;
+    private startPeriodicStatsUpdates;
+    private stopPeriodicStatsUpdates;
+    onConnect(conn: Connection, ctx: ConnectionContext): void;
+    onMessage(message: string | ArrayBuffer | ArrayBufferView, sender: Connection): void;
+    onClose(conn: Connection): void;
+    updateWorldStats(): Promise<boolean>;
+    /**
+     * @method onRequest
+     * @async
+     * @param {Party.Request} req - The HTTP request to handle
+     * @description Forwards HTTP requests to the main server, preserving client context
+     * @returns {Promise<Response>} The response from the main server
+     */
+    onRequest(req: Request$1): Promise<Response>;
+    /**
+     * @method onAlarm
+     * @async
+     * @description Executed periodically, used to perform maintenance tasks
+     */
+    onAlarm(): Promise<void>;
+}
+
 /**
  * @description Test the room with a mock server and client
  * @param Room - The room class to test
@@ -441,10 +611,76 @@ declare const ClientIo: typeof MockPartyClient;
  */
 declare function testRoom(Room: any, options?: {
     hibernate?: boolean;
+    shard?: boolean;
+    env?: Record<string, string>;
 }): Promise<{
-    server: Server;
+    server: Server | Shard;
     room: any;
     createClient: () => Promise<MockPartyClient>;
 }>;
+declare function request(room: Server, path: string, options?: {
+    method: 'GET' | 'POST' | 'PUT' | 'DELETE';
+    body?: any;
+    headers?: Record<string, string>;
+}): Promise<Response>;
+
+interface RoomInterceptorPacket {
+    interceptorPacket(user: any, obj: any, conn: Connection): Promise<any> | null | any;
+}
+interface RoomOnJoin {
+    onJoin(user: any, conn: Connection, ctx: ConnectionContext): Promise<any> | null | any;
+}
+interface RoomOnLeave {
+    onLeave(user: any, conn: Connection, ctx: ConnectionContext): Promise<any> | null | any;
+}
+
+type BalancingStrategy = 'round-robin' | 'least-connections' | 'random';
+type ShardStatus = 'active' | 'maintenance' | 'draining';
+declare class RoomConfig {
+    id: string;
+    name: _signe_reactive.WritableSignal<string>;
+    balancingStrategy: _signe_reactive.WritableSignal<BalancingStrategy>;
+    public: _signe_reactive.WritableSignal<boolean>;
+    maxPlayersPerShard: _signe_reactive.WritableSignal<number>;
+    minShards: _signe_reactive.WritableSignal<number>;
+    maxShards: _signe_reactive.WritableSignal<number>;
+}
+declare class ShardInfo {
+    id: string;
+    roomId: _signe_reactive.WritableSignal<string>;
+    url: _signe_reactive.WritableSignal<string>;
+    currentConnections: _signe_reactive.WritableSignal<number>;
+    maxConnections: _signe_reactive.WritableSignal<number>;
+    status: _signe_reactive.WritableSignal<ShardStatus>;
+    lastHeartbeat: _signe_reactive.WritableSignal<number>;
+}
+declare class WorldRoom implements RoomInterceptorPacket, RoomOnJoin {
+    private room;
+    rooms: _signe_reactive.WritableObjectSignal<Record<string, RoomConfig>>;
+    shards: _signe_reactive.WritableObjectSignal<Record<string, ShardInfo>>;
+    rrCounters: _signe_reactive.WritableObjectSignal<Record<string, number>>;
+    defaultShardUrlTemplate: _signe_reactive.WritableSignal<string>;
+    defaultMaxConnectionsPerShard: _signe_reactive.WritableSignal<number>;
+    constructor(room: Room$1);
+    onJoin(user: any, conn: Connection, ctx: ConnectionContext): Promise<void>;
+    interceptorPacket(_: any, obj: any, conn: Connection): any;
+    private cleanupInactiveShards;
+    registerRoom(req: Request$1): Promise<void>;
+    updateShardStats(req: Request$1): Promise<{
+        error: string;
+    }>;
+    scaleRoom(req: Request$1): Promise<{
+        error: string;
+        roomId?: undefined;
+        currentShardCount?: undefined;
+    } | {
+        error: string;
+        roomId: string;
+        currentShardCount: number;
+    }>;
+    connect(req: Request$1): Promise<Response>;
+    private findOptimalShard;
+    private createShard;
+}
 
-export { Action, ClientIo, Guard, MockConnection, Room, RoomGuard, type RoomOptions, Server, ServerIo, testRoom };
+export { Action, ClientIo, Guard, MockConnection, Request, type RequestOptions, Room, RoomGuard, type RoomInterceptorPacket, type RoomOnJoin, type RoomOnLeave, type RoomOptions, Server, ServerIo, Shard, type ShardOptions, WorldRoom, request, testRoom };