@colyseus/core 0.17.51 → 0.17.53

package/src/MatchMaker.ts

@@ -2,7 +2,7 @@ import { EventEmitter } from 'events';
 
 import { requestFromIPC, subscribeIPC, subscribeWithTimeout } from './IPC.ts';
 
-import { type Type, Deferred, generateId, merge, retry, MAX_CONCURRENT_CREATE_ROOM_WAIT_TIME, REMOTE_ROOM_SHORT_TIMEOUT, type MethodName, type RemoteRoomCallReturn } from './utils/Utils.ts';
+import { type Type, Deferred, generateId, merge, retry, MAX_CONCURRENT_CREATE_ROOM_WAIT_TIME, REMOTE_ROOM_SHORT_TIMEOUT, SWEPT_CHECK_INTERVAL, SWEPT_RECEIPT_TTL, type MethodName, type RemoteRoomCallReturn } from './utils/Utils.ts';
 import { isDevMode, cacheRoomHistory, getPreviousProcessId, getRoomRestoreListKey, reloadFromCache } from './utils/DevMode.ts';
 
 import { RegisteredHandler } from './matchmaker/RegisteredHandler.ts';
@@ -174,6 +174,8 @@ export async function accept(isStandalone: boolean = false) {
      * (`stats.excludeProcess()`) by mistake due to health-check failure
      */
     stats.setAutoPersistInterval();
+
+    startSweptCheck();
   }
 
   state = MatchMakerState.READY;
@@ -774,6 +776,9 @@ export async function gracefullyShutdown(): Promise<any> {
   // unsubscribe from process id channel
   presence.unsubscribe(getProcessChannel());
 
+  // only now: rooms may take minutes to drain, and must stay joinable meanwhile
+  clearInterval(sweptCheckInterval);
+
   // make sure all rooms are disposed
   return Promise.all(disconnectAll(
     (isDevMode)
@@ -1026,13 +1031,24 @@ export function healthCheckProcessId(processId: string) {
       resolve(true)
 
     } catch (e) {
-      // process failed to respond - remove it from stats
       logger.debug(`❌ Process '${processId}' failed to respond. Cleaning it up.`);
-      await stats.excludeProcess(processId);
 
-      // clean-up possibly stale room ids
-      if (!isDevMode) {
-        await removeRoomsByProcessId(processId);
+      try {
+        // stop placing new rooms on it. if it is still alive, it re-adds itself
+        // the next time it persists its stats.
+        await stats.excludeProcess(processId);
+
+        // clean-up possibly stale room ids
+        if (!isDevMode) {
+          await removeRoomsByProcessId(processId);
+
+          // receipt goes AFTER the removal: written before, a merely stalled
+          // process could restore its listings ahead of the delete
+          await presence.setex(getProcessSweptKey(processId), '1', SWEPT_RECEIPT_TTL);
+        }
+
+      } catch (e) {
+        debugMatchMaking(e); // presence/driver failing must not leave the caller hanging
       }
 
       resolve(false);
@@ -1056,6 +1072,68 @@ async function removeRoomsByProcessId(processId: string) {
   await driver.cleanup(processId);
 }
 
+let sweptCheckInterval: NodeJS.Timeout | undefined;
+let isCheckingSwept = false;
+
+function startSweptCheck() {
+  clearInterval(sweptCheckInterval); // accept() may be called more than once
+
+  sweptCheckInterval = setInterval(async () => {
+    if (isCheckingSwept) { return; } // a slow presence would stack them up
+    isCheckingSwept = true;
+
+    try {
+      await restoreIfSwept();
+
+    } catch (e) {
+      debugMatchMaking(e); // a failed presence call must not crash the process
+
+    } finally {
+      isCheckingSwept = false;
+    }
+  }, SWEPT_CHECK_INTERVAL);
+
+  sweptCheckInterval.unref(); // don't keep the process running just for this
+}
+
+/**
+ * A peer that failed to reach this process removed our room listings, and
+ * left a receipt. If we are reading it, we were only stalled: re-create them.
+ */
+async function restoreIfSwept() {
+  if (!await presence.exists(getProcessSweptKey())) { return; }
+
+  // consume before restoring: a removal landing mid-restore leaves a new receipt
+  await presence.del(getProcessSweptKey());
+  await restoreMissingRoomCaches();
+}
+
+/**
+ * Re-create the listings of rooms running on this process that are missing
+ * from the driver.
+ *
+ * Peers remove a process's listings when they believe it is dead. If this
+ * process was only stalled, its rooms are still running, and without their
+ * listings nobody could join them anymore.
+ */
+export async function restoreMissingRoomCaches() {
+  const roomIds = Object.keys(rooms);
+  if (roomIds.length === 0) { return; }
+
+  // one lookup per room: 0.17 drivers have no batch lookup, and this only runs after a sweep
+  const listed = await Promise.all(roomIds.map((roomId) => driver.has(roomId)));
+
+  const missing = roomIds
+    .filter((_, i) => !listed[i])
+    .map((roomId) => rooms[roomId])
+    .filter((room) =>
+      room?.['_internalState'] === RoomInternalState.CREATED // still here, not disposing
+    );
+
+  debugMatchMaking('restoring %s missing room listing(s)', missing.length);
+  await Promise.all(missing.map((room) => driver.persist(room['_listing'], true)));
+}
+
 async function createRoomReferences(room: Room, init: boolean = false): Promise<boolean> {
   rooms[room.roomId] = room;
 
@@ -1212,3 +1290,7 @@ function getConcurrencyHashKey(roomName: string) {
 function getProcessChannel(id: string = processId) {
   return `p:${id}`;
 }
+
+function getProcessSweptKey(id: string = processId) {
+  return `swept:${id}`;
+}

package/src/Transport.ts

@@ -132,7 +132,18 @@ export interface Client<T extends { userData?: any, auth?: any, messages?: Recor
   reconnectionToken: string;
 
   // TODO: move these to ClientPrivate
+  /**
+   * Send raw bytes over the transport's reliable channel.
+   *
+   * The transport owns `data` from this call on: it may write it later (a
+   * socket with backpressure, permessage-deflate), so callers never mutate it
+   * afterwards. The same `data` may be handed to several clients.
+   */
   raw(data: Uint8Array | Buffer, options?: ISendOptions, cb?: (err?: Error) => void): void;
+  /**
+   * {@link raw}, or held until the client finishes joining (or until after the
+   * next patch, with `afterNextPatch`). Owns `data` the same way {@link raw} does.
+   */
   enqueueRaw(data: Uint8Array | Buffer, options?: ISendOptions): void;
 
   /**

package/src/presence/LocalPresence.ts

@@ -106,6 +106,8 @@ export class LocalPresence implements Presence {
     }
 
     public del(key: string) {
+        clearTimeout(this.timeouts[key]); // a pending expiry would wipe whatever is set next
+        delete this.timeouts[key];
         delete this.keys[key];
         delete this.data[key];
         delete this.hash[key];

package/src/serializer/SchemaSerializer.ts

@@ -41,23 +41,38 @@ export class SchemaSerializer<T extends Schema> implements Serializer<T> {
   public getFullState(client?: Client) {
     if (this.needFullEncode || this.encoder.root.changes.next !== undefined) {
       this.sharedOffsetCache = { offset: 1 };
-      this.fullEncodeCache = this.encoder.encodeAll(this.sharedOffsetCache, this.fullEncodeBuffer);
+      // copy: the next full encode reuses the buffer (slice(): a pooled Buffer would pin 8KB)
+      this.fullEncodeCache = this.encoder.encodeAll(this.sharedOffsetCache, this.fullEncodeBuffer).slice();
+      this.fitFullEncodeBuffer(this.sharedOffsetCache.offset);
       this.needFullEncode = false;
     }
 
     if (this.hasFilters && client?.view) {
-      return this.encoder.encodeAllView(
-        client.view,
-        this.sharedOffsetCache.offset,
-        { ...this.sharedOffsetCache },
-        this.fullEncodeBuffer
-      );
+      const it = { ...this.sharedOffsetCache };
+      const encoded = this.encoder.encodeAllView(client.view, this.sharedOffsetCache.offset, it, this.fullEncodeBuffer);
+      this.fitFullEncodeBuffer(it.offset);
+      return encoded;
 
     } else {
       return this.fullEncodeCache;
     }
   }
 
+  /**
+   * Grow {@link fullEncodeBuffer} once an encode outgrew it. The encoder grows
+   * a buffer it is handed for that one encode only, so otherwise every full
+   * encode overflows again and per-view encodes read a truncated shared part.
+   *
+   * `byteLength` is the iterator's final offset, not the returned length:
+   * before @colyseus/schema 4.0.27, a per-view encode that overflows returns
+   * its bytes cut short at the old buffer size.
+   */
+  protected fitFullEncodeBuffer(byteLength: number) {
+    if (byteLength <= this.fullEncodeBuffer.byteLength) { return; }
+    this.fullEncodeBuffer = new Uint8Array(byteLength + Encoder.BUFFER_SIZE);
+    this.fullEncodeBuffer.set(this.fullEncodeCache);
+  }
+
   public applyPatches(clients: Client[]) {
     let numClients = clients.length;
 
@@ -119,6 +134,9 @@ export class SchemaSerializer<T extends Schema> implements Serializer<T> {
     const encodedChanges = this.encoder.encode(it);
 
     if (!this.hasFilters) {
+      // copy once for all clients: a transport may still hold it after the next encode (see Client.raw)
+      const frame = Buffer.from(encodedChanges);
+
       while (numClients--) {
         const client = clients[numClients];
 
@@ -129,7 +147,7 @@ export class SchemaSerializer<T extends Schema> implements Serializer<T> {
           continue;
         }
 
-        client.raw(encodedChanges);
+        client.raw(frame);
       }
 
     } else {
@@ -154,7 +172,7 @@ export class SchemaSerializer<T extends Schema> implements Serializer<T> {
         // allow to pass the same encoded view for multiple clients
         if (encodedView === undefined) {
           encodedView = (view === SHARED_VIEW)
-            ? encodedChanges
+            ? Buffer.from(encodedChanges) // encodeView already returns a copy
             : this.encoder.encodeView(client.view, sharedOffset, it);
           this.encodedViews.set(view, encodedView);
         }

package/src/utils/Utils.ts

@@ -44,6 +44,12 @@ export type RemoteRoomCallReturn<
 export const REMOTE_ROOM_SHORT_TIMEOUT = Number(process.env.COLYSEUS_PRESENCE_SHORT_TIMEOUT || 2000);
 export const MAX_CONCURRENT_CREATE_ROOM_WAIT_TIME = Number(process.env.COLYSEUS_MAX_CONCURRENT_CREATE_ROOM_WAIT_TIME || 0.5);
 
+// a peer that removes this process's room listings leaves a receipt. this
+// process looks for it every INTERVAL (ms) and restores them. the TTL (seconds)
+// only bounds what dead processes leave behind.
+export const SWEPT_CHECK_INTERVAL = Number(process.env.COLYSEUS_SWEPT_CHECK_INTERVAL || 5000);
+export const SWEPT_RECEIPT_TTL = Number(process.env.COLYSEUS_SWEPT_RECEIPT_TTL || 600);
+
 export function generateId(length: number = 9) {
   return nanoid(length);
 }