@colyseus/sdk 0.17.41 → 0.17.43

package/dist/debug.js

@@ -3,7 +3,7 @@
 // This software is released under the MIT License.
 // https://opensource.org/license/MIT
 //
-// colyseus.js@0.17.41
+// colyseus.js@0.17.43
 (function (Client_ts, sharedTypes) {
   'use strict';
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colyseus/sdk",
-  "version": "0.17.41",
+  "version": "0.17.43",
   "description": "Colyseus Multiplayer SDK for JavaScript/TypeScript",
   "author": "Endel Dreyer",
   "license": "MIT",
@@ -82,7 +82,7 @@
     "typescript": "^5.9.3",
     "vite": "^5.0.11",
     "vitest": "^2.1.1",
-    "@colyseus/core": "^0.17.41"
+    "@colyseus/core": "^0.17.43"
   },
   "peerDependencies": {
     "@colyseus/core": "0.17.x"

package/src/Client.ts

@@ -38,6 +38,11 @@ export interface LatencyOptions {
     protocol?: "ws" | "h3";
     /** Number of pings to send (default: 1). Returns the average latency when > 1. */
     pingCount?: number;
+    /**
+     * Milliseconds to wait for the measurement before rejecting (default: 1500).
+     * Bounds unreachable/blackholed endpoints so they can't stall selection.
+     */
+    timeout?: number;
 }
 
 export class ColyseusSDK<ServerType extends SDKTypes = any, UserData = any> {
@@ -131,7 +136,7 @@ export class ColyseusSDK<ServerType extends SDKTypes = any, UserData = any> {
      * Select the endpoint with the lowest latency.
      * @param endpoints Array of endpoints to select from.
      * @param options Client options.
-     * @param latencyOptions Latency measurement options (protocol, pingCount).
+     * @param latencyOptions Latency measurement options (protocol, pingCount, timeout) — forwarded to each {@link getLatency} call.
      * @returns The client with the lowest latency.
      */
     static async selectByLatency<ServerType extends SDKTypes = any, UserData = any>(
@@ -313,16 +318,39 @@ export class ColyseusSDK<ServerType extends SDKTypes = any, UserData = any> {
 
     /**
      * Create a new connection with the server, and measure the latency.
-     * @param options Latency measurement options (protocol, pingCount).
+     *
+     * Always settles: resolves with the (average) round-trip time, or rejects on
+     * connection error, server-side close before all pongs arrive, or timeout.
+     *
+     * @param options Latency measurement options (protocol, pingCount, timeout).
      */
     public getLatency(options: LatencyOptions = {}): Promise<number> {
         const protocol = options.protocol ?? "ws";
         const pingCount = options.pingCount ?? 1;
+        const timeout = options.timeout ?? 1500;
 
         return new Promise<number>((resolve, reject) => {
             const conn = new Connection(protocol);
             const latencies: number[] = [];
             let pingStart = 0;
+            let settled = false;
+            let timeoutId: ReturnType<typeof setTimeout>;
+
+            // run exactly once — guards against late events after resolve/reject
+            // (e.g. our own conn.close() firing onclose, or a stray onclose/onerror pair)
+            const settle = (run: () => void) => {
+                if (settled) { return; }
+                settled = true;
+                clearTimeout(timeoutId);
+                try { conn.close(); } catch (e) { /* socket may never have opened */ }
+                run();
+            };
+
+            const fail = (message: string) =>
+                settle(() => reject(new ServerError(CloseCode.ABNORMAL_CLOSURE, `Failed to get latency: ${message}`)));
+
+            // bound blackholed/filtered hosts that never fire onopen/onerror within the OS TCP timeout
+            timeoutId = setTimeout(() => fail(`timed out after ${timeout}ms`), timeout);
 
             conn.events.onopen = () => {
                 pingStart = Date.now();
@@ -338,17 +366,22 @@ export class ColyseusSDK<ServerType extends SDKTypes = any, UserData = any> {
                     conn.send(new Uint8Array([Protocol.PING]));
                 } else {
                     // Done, calculate average and close
-                    conn.close();
                     const average = latencies.reduce((sum, l) => sum + l, 0) / latencies.length;
-                    resolve(average);
+                    settle(() => resolve(average));
                 }
             };
 
-            conn.events.onerror = (event: ErrorEvent) => {
-                reject(new ServerError(CloseCode.ABNORMAL_CLOSURE, `Failed to get latency: ${event.message}`));
-            };
+            // server closed the socket before all pongs arrived — fires without onerror on a clean close
+            conn.events.onclose = (event: any) =>
+                fail(`connection closed${event?.code ? ` (${event.code})` : ""}${event?.reason ? `: ${event.reason}` : ""}`);
 
-            conn.connect(this.getHttpEndpoint());
+            conn.events.onerror = (event: ErrorEvent) => fail(event.message);
+
+            try {
+                conn.connect(this.getHttpEndpoint());
+            } catch (e: any) {
+                fail(e?.message ?? "failed to connect");
+            }
         });
     }
 

package/src/transport/H3Transport.ts

@@ -1,6 +1,69 @@
 import { encode, decode, type Iterator } from '@colyseus/schema';
 import type { ITransport, ITransportEventMap } from "./ITransport.ts";
 
+// 9 bytes is the maximum length of a variable-length integer prefix
+const MAX_LENGTH_PREFIX_BYTES = 9;
+
+/**
+ * Reassembles length-prefixed frames from arbitrary byte chunks.
+ *
+ * A single WebTransport `reader.read()` may:
+ *   - deliver multiple whole frames in one chunk
+ *   - split a frame (or its length prefix) across multiple chunks
+ *
+ * This reassembler buffers partial data across reads so each dispatched
+ * frame is exactly one complete message.
+ */
+export class FrameReassembler {
+    private pending: Uint8Array = new Uint8Array(0);
+
+    push(chunk: Uint8Array | undefined): Uint8Array[] {
+        if (!chunk || chunk.byteLength === 0) { return []; }
+
+        const bytes = (this.pending.byteLength === 0)
+            ? chunk
+            : concatBytes(this.pending, chunk);
+
+        const frames: Uint8Array[] = [];
+        let offset = 0;
+
+        while (offset < bytes.byteLength) {
+            const it: Iterator = { offset };
+            let length: number;
+
+            try {
+                length = decode.number(bytes as any, it);
+            } catch (e) {
+                // length prefix is incomplete — wait for more bytes
+                if (bytes.byteLength - offset <= MAX_LENGTH_PREFIX_BYTES) { break; }
+                throw e;
+            }
+
+            const frameEnd = it.offset + length;
+            if (frameEnd > bytes.byteLength) {
+                // payload is incomplete — wait for more bytes
+                break;
+            }
+
+            frames.push(bytes.subarray(it.offset, frameEnd));
+            offset = frameEnd;
+        }
+
+        this.pending = (offset < bytes.byteLength)
+            ? bytes.slice(offset)
+            : new Uint8Array(0);
+
+        return frames;
+    }
+}
+
+function concatBytes(a: Uint8Array, b: Uint8Array): Uint8Array {
+    const out = new Uint8Array(a.byteLength + b.byteLength);
+    out.set(a, 0);
+    out.set(b, a.byteLength);
+    return out;
+}
+
 export class H3TransportTransport implements ITransport {
     wt: WebTransport;
     isOpen: boolean = false;
@@ -14,6 +77,9 @@ export class H3TransportTransport implements ITransport {
 
     private lengthPrefixBuffer = new Uint8Array(9); // 9 bytes is the maximum length of a length prefix
 
+    private reliableReassembler = new FrameReassembler();
+    private unreliableReassembler = new FrameReassembler();
+
     constructor(events: ITransportEventMap) {
         this.events = events;
     }
@@ -110,19 +176,11 @@ export class H3TransportTransport implements ITransport {
                 //
                 // a single read may contain multiple messages
                 // each message is prefixed with its length
+                // a read may also deliver a partial frame; buffer across reads
                 //
-
-                const messages = result.value;
-                const it: Iterator = { offset: 0 };
-                do {
-                    //
-                    // QUESTION: should we buffer the message in case it's not fully read?
-                    //
-
-                    const length = decode.number(messages as any, it);
-                    this.events.onmessage({ data: messages.subarray(it.offset, it.offset + length) });
-                    it.offset += length;
-                } while (it.offset < messages.length);
+                for (const frame of this.reliableReassembler.push(result.value)) {
+                    this.events.onmessage({ data: frame });
+                }
 
             } catch (e) {
                 if (e.message.indexOf("session is closed") === -1) {
@@ -147,19 +205,11 @@ export class H3TransportTransport implements ITransport {
                 //
                 // a single read may contain multiple messages
                 // each message is prefixed with its length
+                // a read may also deliver a partial frame; buffer across reads
                 //
-
-                const messages = result.value;
-                const it: Iterator = { offset: 0 };
-                do {
-                    //
-                    // QUESTION: should we buffer the message in case it's not fully read?
-                    //
-
-                    const length = decode.number(messages as any, it);
-                    this.events.onmessage({ data: messages.subarray(it.offset, it.offset + length) });
-                    it.offset += length;
-                } while (it.offset < messages.length);
+                for (const frame of this.unreliableReassembler.push(result.value)) {
+                    this.events.onmessage({ data: frame });
+                }
 
             } catch (e) {
                 if (e.message.indexOf("session is closed") === -1) {