@signe/room 2.10.0 → 3.0.1

package/src/world.ts

@@ -27,11 +27,14 @@ const RoomConfigSchema = z.object({
 const RegisterShardSchema = z.object({
   shardId: z.string(),
   roomId: z.string(),
+  worldId: z.string().optional(),
   url: z.string().url(),
   maxConnections: z.number().int().positive(),
 });
 
 const UpdateShardStatsSchema = z.object({
+  shardId: z.string(),
+  worldId: z.string().optional(),
   connections: z.number().int().min(0),
   status: z.enum(['active', 'maintenance', 'draining']).optional(),
 });
@@ -59,6 +62,7 @@ class RoomConfig {
 class ShardInfo {
   @id() id: string;
   @sync() roomId = signal("");
+  @sync() worldId = signal("");
   @sync() url = signal("");
   @sync({
     persist: false
@@ -95,8 +99,7 @@ export class WorldRoom implements RoomInterceptorPacket, RoomOnJoin {
     if (!SHARD_SECRET) {
       throw new Error("SHARD_SECRET env variable is not set");
     }
-    // TODO
-    //setTimeout(() => this.cleanupInactiveShards(), 60000);
+    this.scheduleInactiveShardCleanup();
   }
 
   async onJoin(user: any, conn: Party.Connection, ctx: Party.ConnectionContext) {
@@ -115,6 +118,15 @@ export class WorldRoom implements RoomInterceptorPacket, RoomOnJoin {
   }
 
   // Helper methods
+  private getWorldId() {
+    return this.room.id;
+  }
+
+  private scheduleInactiveShardCleanup() {
+    const timeoutId = setTimeout(() => this.cleanupInactiveShards(), 60000);
+    timeoutId?.unref?.();
+  }
+
   private cleanupInactiveShards() {
     const now = Date.now();
     const timeout = 5 * 60 * 1000; // 5 minutes timeout
@@ -130,7 +142,15 @@ export class WorldRoom implements RoomInterceptorPacket, RoomOnJoin {
     });
 
     // Schedule next cleanup
-    setTimeout(() => this.cleanupInactiveShards(), 60000);
+    this.scheduleInactiveShardCleanup();
+  }
+
+  private removeShard(shardId: string) {
+    delete this.shards()[shardId];
+  }
+
+  private shouldCompleteDrain(shard: ShardInfo) {
+    return shard.status() === 'draining' && shard.currentConnections() === 0;
   }
 
   // Actions
@@ -139,8 +159,19 @@ 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 parseResult = RoomConfigSchema.safeParse(await req.json());
+    if (!parseResult.success) {
+      return res?.badRequest("Invalid room configuration", {
+        details: parseResult.error
+      });
+    }
+
+    const roomConfig = parseResult.data;
+    if (roomConfig.maxShards !== undefined && roomConfig.minShards > roomConfig.maxShards) {
+      return res?.badRequest("minShards cannot be greater than maxShards");
+    }
+
     const roomId = roomConfig.name;
 
     if (!this.rooms()[roomId]) {
@@ -170,6 +201,8 @@ export class WorldRoom implements RoomInterceptorPacket, RoomOnJoin {
       room.minShards.set(roomConfig.minShards);
       room.maxShards.set(roomConfig.maxShards);
     }
+
+    await this.ensureMinShards(roomId);
   }
 
   @Request({
@@ -178,7 +211,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 parseResult = UpdateShardStatsSchema.safeParse(await req.json());
+    if (!parseResult.success) {
+      return res.badRequest("Invalid shard stats", {
+        details: parseResult.error
+      });
+    }
+
+    const body = parseResult.data;
     const { shardId, connections, status } = body;
     const shard = this.shards()[shardId];
 
@@ -186,11 +226,19 @@ export class WorldRoom implements RoomInterceptorPacket, RoomOnJoin {
       return res.notFound(`Shard ${shardId} not found`);
     }
 
+    if (body.worldId && body.worldId !== this.getWorldId()) {
+      return res.badRequest(`Shard ${shardId} belongs to world ${body.worldId}, not ${this.getWorldId()}`);
+    }
+
     shard.currentConnections.set(connections);
     if (status) {
       shard.status.set(status);
     }
     shard.lastHeartbeat.set(Date.now());
+
+    if (this.shouldCompleteDrain(shard)) {
+      this.removeShard(shard.id);
+    }
   }
 
   @Request({
@@ -199,7 +247,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 parseResult = ScaleRoomSchema.safeParse(await req.json());
+    if (!parseResult.success) {
+      return res.badRequest("Invalid scale room request", {
+        details: parseResult.error
+      });
+    }
+
+    const data = parseResult.data;
     const { targetShardCount, shardTemplate, roomId } = data;
 
     // Validate room exists
@@ -223,8 +278,8 @@ export class WorldRoom implements RoomInterceptorPacket, RoomOnJoin {
 
     // Handle scaling down
     if (targetShardCount < previousShardCount) {
-      // Find candidates for removal (prioritize draining or low-connection shards)
-      const shardsToRemove = [...roomShards]
+      // Find drain candidates (prioritize already-draining or low-connection shards)
+      const shardsToDrain = [...roomShards]
         .sort((a, b) => {
           // Prioritize draining status
           if (a.status() === 'draining' && b.status() !== 'draining') return -1;
@@ -235,14 +290,12 @@ 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];
+      // Complete empty drains immediately, otherwise stop routing new clients there.
+      for (const shard of shardsToDrain) {
+        shard.status.set('draining');
+        if (this.shouldCompleteDrain(shard)) {
+          this.removeShard(shard.id);
+        }
       }
 
       return;
@@ -368,11 +421,24 @@ export class WorldRoom implements RoomInterceptorPacket, RoomOnJoin {
       }
     }
 
-    // Get active shards
-    const activeShards = roomShards
-      .filter(shard => shard && shard.status() === 'active');
+    // Get active shards with available capacity
+    let activeShards = this.getAvailableShards(roomShards);
 
     if (activeShards.length === 0) {
+      if (autoCreate && this.canCreateShard(room, roomShards.length)) {
+        const newShard = await this.createShard(roomId);
+        if (newShard) {
+          return {
+            shardId: newShard.id,
+            url: newShard.url()
+          };
+        }
+      }
+
+      if (roomShards.some(shard => shard.status() === 'active')) {
+        return { error: `No shard capacity available for room ${roomId}` };
+      }
+
       return { error: `No active shards available for room ${roomId}` };
     }
 
@@ -412,6 +478,18 @@ export class WorldRoom implements RoomInterceptorPacket, RoomOnJoin {
     };
   }
 
+  private getAvailableShards(shards: ShardInfo[]) {
+    return shards.filter(shard =>
+      shard
+      && shard.status() === 'active'
+      && shard.currentConnections() < shard.maxConnections()
+    );
+  }
+
+  private canCreateShard(room: RoomConfig, currentShardCount: number) {
+    return room.maxShards() === undefined || currentShardCount < room.maxShards()!;
+  }
+
   // Private methods
   private async createShard(
     roomId: string,
@@ -425,7 +503,8 @@ export class WorldRoom implements RoomInterceptorPacket, RoomOnJoin {
     }
 
     // Generate shard ID
-    const shardId = `${roomId}:${Date.now()}-${Math.floor(Math.random() * 10000)}`;
+    const worldId = this.getWorldId();
+    const shardId = `${roomId}:${worldId}:${Date.now()}-${Math.floor(Math.random() * 10000)}`;
 
     // Generate URL from template
     const template = urlTemplate || this.defaultShardUrlTemplate();
@@ -438,6 +517,7 @@ export class WorldRoom implements RoomInterceptorPacket, RoomOnJoin {
     const newShard = new ShardInfo();
     newShard.id = shardId;
     newShard.roomId.set(roomId);
+    newShard.worldId.set(worldId);
     newShard.url.set(url);
     newShard.maxConnections.set(max);
     newShard.currentConnections.set(0);
@@ -448,4 +528,24 @@ export class WorldRoom implements RoomInterceptorPacket, RoomOnJoin {
     this.shards()[shardId] = newShard;
     return newShard;
   }
+
+  private async ensureMinShards(roomId: string) {
+    const room = this.rooms()[roomId];
+    if (!room) {
+      return;
+    }
+
+    const currentShardCount = Object.values(this.shards())
+      .filter(shard => shard.roomId() === roomId)
+      .length;
+    const targetShardCount = room.minShards();
+
+    if (currentShardCount >= targetShardCount) {
+      return;
+    }
+
+    for (let i = currentShardCount; i < targetShardCount; i++) {
+      await this.createShard(roomId);
+    }
+  }
 }

package/tests/storage-restore.spec.ts

@@ -0,0 +1,122 @@
+import { describe, expect, it } from "vitest";
+import { signal } from "@signe/reactive";
+import { sync, users } from "@signe/sync";
+import { Room, Server, ServerIo } from "../src";
+
+class Item {
+  id = signal("");
+}
+
+class Player {
+  items = signal<any[]>([]);
+}
+
+describe("storage restore hooks", () => {
+  it("allows a room to hydrate the persisted root snapshot before load", async () => {
+    @Room({ path: "demo" })
+    class DemoRoom {
+      @sync()
+      title = signal("");
+
+      onStorageRestore({ snapshot }: { snapshot: any }) {
+        return {
+          ...snapshot,
+          title: `${snapshot.title}:hydrated`,
+        };
+      }
+    }
+
+    class DemoServer extends Server {
+      rooms = [DemoRoom];
+    }
+
+    const io = new ServerIo("demo");
+    await io.storage.put("state:title", "saved");
+
+    const server = new DemoServer(io as any);
+    await server.onStart();
+
+    expect((server.subRoom as any).title()).toBe("saved:hydrated");
+  });
+
+  it("allows a room to hydrate persisted user snapshots before load", async () => {
+    @Room({ path: "demo" })
+    class DemoRoom {
+      @users(Player)
+      players = signal<Record<string, Player>>({});
+
+      async onUserStorageRestore({ userSnapshot, user }: { userSnapshot: any; user?: Player }) {
+        return {
+          ...userSnapshot,
+          items: userSnapshot.items.map((entry: any) => {
+            const item = new Item();
+            item.id.set(entry.id);
+            return item;
+          }),
+          usedHelperInstance: user instanceof Player,
+        };
+      }
+    }
+
+    class DemoServer extends Server {
+      rooms = [DemoRoom];
+    }
+
+    const io = new ServerIo("demo");
+    await io.storage.put("state:players.public-1.items", [{ id: "potion" }]);
+
+    const server = new DemoServer(io as any);
+    await server.onStart();
+
+    const restoredPlayer = (server.subRoom as any).players()["public-1"];
+    expect(restoredPlayer).toBeInstanceOf(Player);
+    expect(restoredPlayer.items()[0]).toBeInstanceOf(Item);
+    expect(restoredPlayer.items()[0].id()).toBe("potion");
+    expect((restoredPlayer as any).usedHelperInstance).toBe(true);
+  });
+
+  it("compacts persisted delete markers when loading room storage", async () => {
+    @Room({ path: "demo" })
+    class DemoRoom {
+      @sync()
+      items = signal<Record<string, number>>({});
+    }
+
+    class DemoServer extends Server {
+      rooms = [DemoRoom];
+    }
+
+    const io = new ServerIo("demo");
+    await io.storage.put("state:items.a", "$delete");
+
+    const server = new DemoServer(io as any);
+    await server.onStart();
+
+    const storageEntries = await io.storage.list({ prefix: "state:" });
+    expect(storageEntries.get("state:items.a")).toBeUndefined();
+    expect(storageEntries.get("state:.")).toEqual({ items: {} });
+  });
+
+  it("compacts runtime deletes instead of leaving delete markers in storage", async () => {
+    @Room({ path: "demo" })
+    class DemoRoom {
+      @sync()
+      items = signal<Record<string, number>>({ a: 1, b: 2 });
+    }
+
+    class DemoServer extends Server {
+      rooms = [DemoRoom];
+    }
+
+    const io = new ServerIo("demo");
+    const server = new DemoServer(io as any);
+    await server.onStart();
+
+    delete (server.subRoom as any).items().a;
+    await new Promise((resolve) => setTimeout(resolve, 0));
+
+    const storageEntries = await io.storage.list({ prefix: "state:" });
+    expect(storageEntries.get("state:items.a")).toBeUndefined();
+    expect(storageEntries.get("state:.")).toEqual({ items: { b: 2 } });
+  });
+});

package/examples/game/.vscode/launch.json

@@ -1,11 +0,0 @@
-{
-  "configurations": [
-    {
-      "type": "node",
-      "request": "attach",
-      "name": "PartyKit debugger",
-      "address": "localhost",
-      "port": 9229
-    }
-  ]
-}

package/examples/game/.vscode/settings.json

@@ -1,11 +0,0 @@
-{
-  "files.associations": {
-    "partykit.json": "jsonc"
-  },
-  "json.schemas": [
-    {
-      "fileMatch": ["partykit.json"],
-      "url": "https://www.partykit.io/schema.json"
-    }
-  ]
-}

package/examples/game/README.md

@@ -1,40 +0,0 @@
-# 🎈 game
-
-Welcome to the party, pal!
-
-This is a [Partykit](https://partykit.io) project, which lets you create real-time collaborative applications with minimal coding effort.
-
-This is the **React starter** which pairs a PartyKit server with a React client.
-
-Refer to our docs for more information: https://github.com/partykit/partykit/blob/main/README.md. For more help, reach out to us on [Discord](https://discord.gg/g5uqHQJc3z), [GitHub](https://github.com/partykit/partykit), or [Twitter](https://twitter.com/partykit_io).
-
-## Usage
-
-You can start developing by running `npm run dev` and opening [http://localhost:1999](http://localhost:1999) in your browser. When you're ready, you can deploy your application on to the PartyKit cloud with `npm run deploy`.
-
-## Finding your way around
-
-[`party/server.ts`](./party/server.ts) is the server-side code, which is responsible for handling WebSocket events and HTTP requests.
-
-It implements a simple counter that can be incremented by any connected client. The latest state is broadcast to all connected clients.
-
-> [!NOTE]
-> The full Server API is available at [Party.Server in the PartyKit docs](https://docs.partykit.io/reference/partyserver-api/)
-
-[`app/client.tsx`](./src/client.ts) is the entrypoint to client-side code.
-
-[`app/components/Counter.tsx`](./src/components/Counter.tsx) connects to the server, sends `increment` events on the WebSocket, and listens for updates.
-
-> [!NOTE]
-> The client-side reference can be found at [PartySocket in the PartyKit docs](https://docs.partykit.io/reference/partysocket-api/)
-
-As a client-side React app, the app could be hosted every. During development, for convenience, the server serves the client-side code as well.
-
-This is achieved with the optional `serve` property in the [`partykit.json`](./partykit.json) config file.
-
-> [!NOTE]
-> Learn about PartyKit config under [Configuration in the PartyKit docs](https://docs.partykit.io/reference/partykit-configuration/)
-
-## Next Steps
-
-Learn about deploying PartyKit applications in the [Deployment guide of the PartyKit docs](https://docs.partykit.io/guides/deploying-your-partykit-server/).

package/examples/game/app/client.tsx

@@ -1,15 +0,0 @@
-import { createRoot } from "react-dom/client";
-import  Admin  from "./components/Admin";
-import "./styles.css";
-import Room from "./components/Room";
-
-
-function App() {
-  return (
-    <main>
-      <Room />
-    </main>
-  );
-}
-
-createRoot(document.getElementById("app")!).render(<App />);