@signe/room 2.10.0 → 3.0.1

package/readme.md

@@ -104,7 +104,10 @@ class GameRoom {
     message: { action: string; value: unknown },
     conn: Party.Connection
   ) {
-    console.warn("Unhandled action", message.action, message.value, conn.id);
+    console.warn("Unhandled action", message.action, message.value, {
+      connectionId: conn.id,
+      sessionId: conn.sessionId,
+    });
   }
 }
 ```
@@ -182,10 +185,57 @@ You can return:
 
 ## Advanced Features
 
+### User Sessions and Reconnects
+
+Rooms use the WebSocket `id` query parameter as the private session id
+(`privateId`). Each active WebSocket still receives its own unique
+`conn.id`; the stable session id is available as `conn.sessionId`. The
+corresponding `publicId` is the key used in `@users()` collections. Query
+parameters such as a display name are user data only; they do not identify the
+session.
+
+Identifier summary:
+
+| Identifier | Meaning | Stability |
+| --- | --- | --- |
+| `conn.id` | Unique WebSocket connection id | New for every active socket |
+| `conn.sessionId` | Private session id from the WebSocket `id` query parameter | Stable across reconnects and shared by tabs using the same `id` |
+| `publicId` | User id stored in `@users()` collections | Stable for the restored session |
+
+Use `conn.id` when you need to address or exclude one physical WebSocket, for
+example `room.broadcast(message, [conn.id])`. Use `conn.sessionId` when you
+need to read, restore, transfer, or log the private user session.
+
+Pass a stable `id` when connecting if a browser refresh or reconnect should
+restore the same user. If `id` is omitted, each connection creates a new
+session and therefore a new user entry. To implement logout, remove or rotate
+the stored id before reconnecting.
+
+Multiple active WebSockets can use the same session id. They share the same
+`publicId`, receive broadcasts independently, and the user is marked offline
+only after the last connection for that session closes.
+
+```ts
+import { connectionRoom } from "@signe/sync/client";
+
+const sessionId =
+  localStorage.getItem("room-session-id") ?? crypto.randomUUID();
+
+localStorage.setItem("room-session-id", sessionId);
+
+await connectionRoom({
+  host: window.location.origin,
+  room: "your-room-name",
+  party: "main",
+  id: sessionId,
+}, roomInstance);
+```
+
 ### Session Transfer
 
 You can transfer a user's session from one room to another using `$sessionTransfer`.
-This preserves the same session id (privateId) across rooms.
+This is an advanced use of the same session mechanism and preserves the same
+private session id (`privateId`) across rooms.
 
 Server-side (inside a room or action):
 
@@ -249,6 +299,47 @@ const hydrated = { ...snapshot, items };
 load(user, hydrated, true);
 ```
 
+### Storage Restore Hydration
+
+Room storage is loaded automatically when a room starts. If persisted snapshots
+contain complex values that must become runtime instances again, implement
+`onStorageRestore` or `onUserStorageRestore` on the room.
+
+Use `onStorageRestore` to transform the full room snapshot before it is loaded:
+
+```ts
+class GameRoom {
+  async onStorageRestore({ snapshot, room, legacy }) {
+    return {
+      ...snapshot,
+      status: snapshot.status ?? "waiting",
+    };
+  }
+}
+```
+
+Use `onUserStorageRestore` to transform each persisted entry in the room's
+`@users()` collection. The hook receives a fresh user helper instance so you can
+reuse instance methods to hydrate nested data before the snapshot is loaded.
+
+```ts
+class GameRoom {
+  @users(Player) players = signal({});
+
+  async onUserStorageRestore({ userSnapshot, user, publicId }) {
+    return {
+      ...userSnapshot,
+      items: await user.resolveItems(userSnapshot.items),
+      skills: await user.resolveSkills(userSnapshot.skills),
+    };
+  }
+}
+```
+
+Returning `undefined` keeps the original snapshot unchanged. The `legacy` flag is
+`true` only when loading data from the pre-`state:` storage layout during
+automatic migration.
+
 ### Room Configuration
 
 The `@Room` decorator accepts various configuration options:
@@ -435,6 +526,8 @@ class GameRoom {
 
 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.
 
+Use this setup when one logical room may need to accept clients through one or more shard parties. A `WorldRoom` keeps the room and shard registry, while each `Shard` proxies client WebSocket and HTTP traffic to the main room server.
+
 #### Environment Variables
 
 To use the Signe room system, you need to configure two essential environment variables:
@@ -447,7 +540,7 @@ AUTH_JWT_SECRET=a-string-secret-at-least-256-bits-long
 SHARD_SECRET=your_shard_secret
 ```
 
-These secrets should be strong, unique values and kept secure.
+These secrets should be strong, unique values and kept secure. `SHARD_SECRET` is used for shard-to-world stats updates and shard-to-main-server traffic. A request or WebSocket connection that claims to come from a shard must include this secret.
 
 #### Server Configuration
 
@@ -474,6 +567,34 @@ import { Shard } from '@signe/room';
 export default class ShardServer extends Shard {}
 ```
 
+By default, a shard belongs to `world-default`. For a multi-world deployment, the shard can resolve its world from the shard id generated by `WorldRoom`, from constructor options, or from environment variables:
+
+```ts
+import { Shard, type Party } from '@signe/room';
+
+export default class EuShardServer extends Shard {
+  constructor(room: Party.Room) {
+    super(room, {
+      worldId: 'world-eu'
+    });
+  }
+}
+```
+
+If you let `WorldRoom` create shard metadata, shard ids use this format:
+
+```txt
+{roomId}:{worldId}:{uniqueShardId}
+```
+
+For example:
+
+```txt
+match-123:world-eu:1710000000000-4821
+```
+
+The `Shard` class can read `world-eu` from that id and report stats back to the matching world.
+
 3. Configure your `partykit.json` file:
 
 ```json
@@ -489,6 +610,85 @@ export default class ShardServer extends Shard {}
 }
 ```
 
+#### Multi-World Setup
+
+`WorldRoom` uses the dynamic path `world-{worldId}`. This means these are separate world instances:
+
+```txt
+/parties/world/world-default
+/parties/world/world-eu
+/parties/world/world-us
+```
+
+Each world owns its own room registry, shard registry, load-balancing counters, shard heartbeats, and inactive shard cleanup. A shard should report to exactly one world.
+
+When a client connects through a specific world, pass the same `worldId` to `connectionWorld()`:
+
+```js
+const euConnection = await connectionWorld({
+  host: 'https://your-app-url.com',
+  room: 'match-123',
+  worldId: 'world-eu',
+  autoCreate: true
+}, room);
+```
+
+For an admin connection to a world room, use the world id as the room id:
+
+```js
+const worldConnection = await connectionRoom({
+  host: window.location.origin,
+  room: 'world-eu',
+  party: 'world',
+  query: {
+    'world-auth-token': 'your-jwt-token'
+  }
+}, worldRoom);
+```
+
+#### World Admin Authorization
+
+World management endpoints and world-room WebSocket connections require a JWT signed with `AUTH_JWT_SECRET`. The token must include a `worlds` claim listing the world ids that the operator can access:
+
+```json
+{
+  "sub": "operator-1",
+  "worlds": ["world-default", "world-eu"]
+}
+```
+
+Use `["*"]` for a global operator:
+
+```json
+{
+  "sub": "admin",
+  "worlds": ["*"]
+}
+```
+
+Tokens without a `worlds` claim, or without the current world id in that claim, are rejected even when the JWT signature is valid. Admin clients can pass the token either with an `Authorization: Bearer <token>` header or with the `world-auth-token` query parameter:
+
+```js
+await fetch('/parties/world/world-eu/register-room', {
+  method: 'POST',
+  headers: {
+    Authorization: `Bearer ${token}`,
+    'Content-Type': 'application/json'
+  },
+  body: JSON.stringify({
+    name: 'match-123',
+    balancingStrategy: 'round-robin',
+    public: true,
+    maxPlayersPerShard: 50
+  })
+});
+```
+
+The same `worldId` must be used consistently by:
+- the client request to `connectionWorld()`;
+- the `WorldRoom` party id;
+- the shard metadata/id or shard constructor option.
+
 #### Client Connection
 
 On the client side, use the `connectionWorld` function to connect to your room through the World service:
@@ -503,7 +703,7 @@ const room = new YourRoomSchema();
 const connection = await connectionWorld({
   host: 'https://your-app-url.com', // Your application URL
   room: 'unique-room-id',             // Room identifier
-  worldId: 'your-world-id',             // Optional, defaults to 'world-default'
+  worldId: 'world-eu',                 // 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
@@ -528,11 +728,14 @@ import { connectionRoom } from '@signe/sync/client';
 
 // Initialize your room instance
 const room = new YourRoomSchema();
+const sessionId = localStorage.getItem('room-session-id') ?? crypto.randomUUID();
+localStorage.setItem('room-session-id', sessionId);
 
 // Connect directly to a room
 const connection = await connectionRoom({
   host: window.location.origin,
   room: 'your-room-name',
+  id: sessionId,
   party: 'your-party-name', // Optional, defaults to main party
   query: {} // Optional query parameters
 }, room);
@@ -560,6 +763,32 @@ This approach offers several benefits:
 - Built-in retry logic for reliability
 - Room creation on demand
 
+#### Shard Lifecycle Notes
+
+World tracks each shard with:
+- `roomId`: the logical room served by the shard;
+- `worldId`: the world that owns the shard;
+- `url`: the shard connection target returned to clients;
+- `currentConnections`: the latest reported connection count;
+- `maxConnections`: the configured shard capacity;
+- `status`: `active`, `maintenance`, or `draining`;
+- `lastHeartbeat`: the latest stats update timestamp.
+
+The built-in balancing strategies only consider active shards with available capacity (`currentConnections < maxConnections`):
+- `round-robin`: rotates through available shards;
+- `least-connections`: picks the available shard with the lowest reported connection count;
+- `random`: picks a random available shard.
+
+If every active shard is full and `autoCreate` is enabled, the world creates another shard when the room has not reached `maxShards`. If no capacity is available and the room cannot create another shard, `/connect` returns a capacity error.
+
+Shard stats are updated when connections change and through periodic forced heartbeats. Inactive shards are removed after the world cleanup timeout.
+
+When a shard is marked `draining`, the world stops assigning new clients to it. Existing WebSocket clients remain connected to that shard. Once the shard reports `currentConnections: 0`, the world removes it from the shard registry automatically. Scaling down uses the same flow: empty candidate shards are removed immediately, while occupied candidate shards are marked `draining` and removed later when they become empty.
+
+Current limitations:
+- Draining does not migrate connected clients; it waits for them to disconnect naturally.
+- The world registry is held in room state; use deployment-specific persistence if your topology requires an external global registry.
+
 ### Packet Interception
 
 You can implement the `interceptorPacket` method in your room to inspect and modify packets before they're sent to users:
@@ -641,6 +870,191 @@ connection.close();
 
 > https://docs.partykit.io/reference/partyserver-api/#partyconnection
 
+## Node.js adapter
+
+`@signe/room/node` runs a room server in a standard single-process Node.js
+application. It is useful for local development, self-hosting, Express/Fastify
+style integrations, Vite dev servers, and tests that do not need PartyKit.
+
+```ts
+import { createServer } from "node:http";
+import { WebSocketServer } from "ws";
+import { Action, Request, Room, Server } from "@signe/room";
+import { createMemoryNodeRoomStorage, createNodeRoomTransport } from "@signe/room/node";
+import { signal } from "@signe/reactive";
+import { sync } from "@signe/sync";
+
+@Room({ path: "demo" })
+class CounterRoom {
+  @sync() count = signal(0);
+
+  @Action("increment")
+  increment(_user: unknown, value: { amount?: number }) {
+    this.count.update((count) => count + (value.amount ?? 1));
+  }
+
+  @Request({ path: "/count" })
+  getCount() {
+    return { count: this.count() };
+  }
+}
+
+class CounterServer extends Server {
+  rooms = [CounterRoom];
+}
+
+const storage = createMemoryNodeRoomStorage();
+
+const transport = createNodeRoomTransport(CounterServer, {
+  partiesPath: "/parties/main",
+  storage,
+});
+
+const server = createServer((req, res) => {
+  void transport.handleNodeRequest(req, res);
+});
+
+const wsServer = new WebSocketServer({ noServer: true });
+
+server.on("upgrade", (request, socket, head) => {
+  transport.handleUpgrade(wsServer, request, socket, head);
+});
+
+server.listen(3000);
+```
+
+HTTP requests use the same PartyKit-style room path:
+
+```bash
+curl http://localhost:3000/parties/main/demo/count
+```
+
+WebSocket clients connect to the room URL and send normal action packets:
+
+```js
+const socket = new WebSocket("ws://localhost:3000/parties/main/demo");
+
+socket.send(JSON.stringify({
+  action: "increment",
+  value: { amount: 1 }
+}));
+```
+
+For middleware frameworks, pass a `next` callback. Requests that do not match
+the configured parties path are delegated to `next`.
+
+```ts
+app.use((req, res, next) => {
+  void transport.handleNodeRequest(req, res, next);
+});
+```
+
+Room-to-room requests are available through `room.context.parties`:
+
+```ts
+const response = await this.room.context.parties.main
+  .get("other-room")
+  .fetch("/count");
+```
+
+The Node adapter stores room state in memory by default. The package also
+provides explicit memory and SQLite storage providers.
+
+Use `createMemoryNodeRoomStorage()` when you want to keep a reference to the
+memory backend, inspect it, clear it, or save a snapshot for a later process
+restart.
+
+```ts
+const storage = createMemoryNodeRoomStorage();
+
+const transport = createNodeRoomTransport(CounterServer, {
+  storage,
+});
+
+const snapshot = storage.snapshot();
+const restoredStorage = createMemoryNodeRoomStorage({ snapshot });
+```
+
+Use `createSqliteNodeRoomStorage()` when you want room storage persisted in a
+SQLite database. This helper uses Node's built-in `node:sqlite` module.
+
+```ts
+import {
+  createNodeRoomTransport,
+  createSqliteNodeRoomStorage,
+} from "@signe/room/node";
+
+const transport = createNodeRoomTransport(CounterServer, {
+  storage: createSqliteNodeRoomStorage({
+    databasePath: "./rooms.sqlite",
+  }),
+});
+```
+
+The SQLite helper enables `PRAGMA busy_timeout = 5000` and `PRAGMA journal_mode
+= WAL` by default to make development servers more tolerant of short-lived
+write contention. You can override those defaults with `busyTimeoutMs`,
+`journalMode`, and `busyRetries`.
+
+Room state is stored as incremental `state:` entries. When a persisted delete is
+encountered, the server compacts the room state by materializing the current
+snapshot and removing durable delete markers. This keeps long-running SQLite
+storage from accumulating `"$delete"` tombstones after objects or users are
+removed.
+
+To create your own storage backend, implement the key-value methods used by
+`@signe/room`: `get`, `put`, `delete`, and `list`, then return it from a storage
+provider.
+
+```ts
+import type { NodeRoomStorage, NodeRoomStorageProvider } from "@signe/room/node";
+
+class MyStorage implements NodeRoomStorage {
+  async get<T = unknown>(key: string): Promise<T | undefined> {
+    // Read from your database
+  }
+
+  async put<T = unknown>(key: string, value: T): Promise<void> {
+    // Write to your database
+  }
+
+  async delete(key: string): Promise<void | boolean> {
+    // Delete from your database
+  }
+
+  async list<T = unknown>(): Promise<Map<string, T>> {
+    // Return all key/value entries for the room
+  }
+}
+
+const storage: NodeRoomStorageProvider = {
+  getStorage(namespace, roomId) {
+    return new MyStorage(namespace, roomId);
+  },
+};
+
+const transport = createNodeRoomTransport(CounterServer, {
+  storage,
+});
+```
+
+To create your own Node transport integration, use the low-level methods exposed
+by `createNodeRoomTransport()`:
+
+- `transport.fetch(requestOrPath, init?)` for runtimes using Web
+  `Request`/`Response`;
+- `transport.handleNodeRequest(req, res, next?)` for Node HTTP middleware;
+- `transport.handleUpgrade(wsServer, request, socket, head)` for `ws`
+  WebSocket upgrades;
+- `transport.acceptWebSocket(webSocket, request)` when your framework already
+  accepted the WebSocket and you only need to attach it to a room.
+
+The first Node adapter version targets single-process Node.js only; clustering,
+multi-process coordination, Cloudflare Durable Objects, Bun WebSocket, and
+uWebSockets.js support are outside this adapter.
+
+See `packages/room/examples/node` for a runnable HTTP + WebSocket example.
+
 ## Testing
 
 ```ts