@colyseus/sdk 0.17.1 → 0.17.2

package/src/errors/Errors.ts

@@ -0,0 +1,29 @@
+export enum CloseCode {
+    NORMAL_CLOSURE = 1000,
+    GOING_AWAY = 1001,
+    NO_STATUS_RECEIVED = 1005,
+    ABNORMAL_CLOSURE = 1006,
+
+    CONSENTED = 4000,
+    SERVER_SHUTDOWN = 4001,
+    WITH_ERROR = 4002,
+    DEVMODE_RESTART = 4010
+}
+
+export class ServerError extends Error {
+  public code: number;
+
+  constructor(code: number, message: string) {
+    super(message);
+
+    this.name = "ServerError";
+    this.code = code;
+  }
+}
+
+export class AbortError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "AbortError";
+  }
+}

package/src/index.ts

@@ -0,0 +1,18 @@
+import './legacy';
+
+export { ColyseusSDK, Client, MatchMakeError, type JoinOptions, type EndpointSettings, type ClientOptions, type ISeatReservation as SeatReservation } from './Client.ts';
+export { Protocol, ErrorCode } from './Protocol.ts';
+export { Room, type RoomAvailable } from './Room.ts';
+export { Auth, type AuthSettings, type PopupSettings } from "./Auth.ts";
+export { ServerError, CloseCode } from './errors/Errors.ts';
+
+/*
+ * Serializers
+ */
+import { SchemaSerializer, getStateCallbacks } from "./serializer/SchemaSerializer.ts";
+import { NoneSerializer } from "./serializer/NoneSerializer.ts";
+import { registerSerializer } from './serializer/Serializer.ts';
+
+export { registerSerializer, SchemaSerializer, getStateCallbacks };
+registerSerializer('schema', SchemaSerializer);
+registerSerializer('none', NoneSerializer);

package/src/legacy.ts

@@ -0,0 +1,29 @@
+//
+// Polyfills for legacy environments
+//
+
+/*
+ * Support Android 4.4.x
+ */
+if (!ArrayBuffer.isView) {
+    ArrayBuffer.isView = (a: any): a is ArrayBufferView => {
+        return a !== null && typeof (a) === 'object' && a.buffer instanceof ArrayBuffer;
+    };
+}
+
+// Define globalThis if not available.
+// https://github.com/colyseus/colyseus.js/issues/86
+if (
+    typeof (globalThis) === "undefined" &&
+    typeof (window) !== "undefined"
+) {
+    // @ts-ignore
+    window['globalThis'] = window;
+}
+
+// Cocos Creator does not provide "FormData"
+// Define a dummy implementation so it doesn't crash
+if (typeof(FormData) === "undefined") {
+    // @ts-ignore
+    globalThis['FormData'] = class {};
+}

package/src/serializer/FossilDeltaSerializer.ts

@@ -0,0 +1,39 @@
+/*
+
+// Dependencies:
+// "@gamestdio/state-listener": "^3.1.0",
+// "fossil-delta": "^1.0.0",
+
+import { Serializer } from "./Serializer";
+
+import { StateContainer } from '@gamestdio/state-listener';
+import * as fossilDelta from 'fossil-delta';
+import * as msgpack from '../msgpack';
+
+export class FossilDeltaSerializer<State= any> implements Serializer<State> {
+    api: StateContainer<State> = new StateContainer<State>({} as State);
+    protected previousState: any;
+
+    getState(): State {
+        return this.api.state;
+    }
+
+    setState(encodedState: any): void {
+        this.previousState = new Uint8Array(encodedState);
+        this.api.set(msgpack.decode(this.previousState));
+    }
+
+    patch(binaryPatch) {
+        // apply patch
+        this.previousState = new Uint8Array(fossilDelta.apply(this.previousState, binaryPatch));
+
+        // trigger update callbacks
+        this.api.set(msgpack.decode(this.previousState));
+    }
+
+    teardown() {
+        this.api.removeAllListeners();
+    }
+}
+
+*/

package/src/serializer/NoneSerializer.ts

@@ -0,0 +1,9 @@
+import type { Serializer } from "./Serializer.ts";
+
+export class NoneSerializer<T = any> implements Serializer<T> {
+    setState(rawState: any): void {}
+    getState() { return null; }
+    patch(patches) {}
+    teardown() { }
+    handshake(bytes: Uint8Array) {}
+}

package/src/serializer/SchemaSerializer.ts

@@ -0,0 +1,61 @@
+import { Schema, Decoder, Reflection, Iterator, getDecoderStateCallbacks } from "@colyseus/schema";
+import type { Serializer } from "./Serializer.ts";
+import type { Room } from "../Room.ts";
+
+export type SchemaConstructor<T = Schema> = new (...args: any[]) => T;
+
+//
+// TODO: use a schema interface, which even having duplicate definitions, it could be used to get the callback proxy.
+//
+// ```ts
+//     export type SchemaCallbackProxy<RoomState> = (<T extends ISchema>(instance: T) => CallbackProxy<T>);
+//     export function getStateCallbacks<T extends ISchema>(room: Room<T>) {
+// ```
+//
+export function getStateCallbacks<T>(room: Room<any, T>) {
+    try {
+        // SchemaSerializer
+        // @ts-ignore
+        return getDecoderStateCallbacks<T>((room['serializer'] as unknown as SchemaSerializer<T>).decoder);
+    } catch (e) {
+        // NoneSerializer
+        return undefined;
+    }
+}
+
+export class SchemaSerializer<T extends Schema = any> implements Serializer<T> {
+    state: T;
+    decoder: Decoder<T>;
+
+    setState(encodedState: Uint8Array, it?: Iterator) {
+        this.decoder.decode(encodedState, it);
+    }
+
+    getState() {
+        return this.state;
+    }
+
+    patch(patches: Uint8Array, it?: Iterator) {
+        return this.decoder.decode(patches, it);
+    }
+
+    teardown() {
+        this.decoder.root.clearRefs();
+    }
+
+    handshake(bytes: Uint8Array, it?: Iterator) {
+        if (this.state) {
+            //
+            // TODO: validate definitions against concreate this.state instance
+            //
+            Reflection.decode(bytes, it); // no-op
+
+            this.decoder = new Decoder(this.state);
+
+        } else {
+            // initialize reflected state from server
+            this.decoder = Reflection.decode(bytes, it);
+            this.state = this.decoder.state;
+        }
+    }
+}

package/src/serializer/Serializer.ts

@@ -0,0 +1,23 @@
+import type { Iterator } from "@colyseus/schema";
+
+export interface Serializer<State> {
+    setState(data: Uint8Array, it?: Iterator): void;
+    getState(): State;
+
+    patch(data: Uint8Array, it?: Iterator): void;
+    teardown(): void;
+
+    handshake?(bytes: Uint8Array, it?: any): void;
+}
+
+const serializers: { [id: string]: any } = {};
+
+export function registerSerializer (id: string, serializer: any) {
+    serializers[id] = serializer;
+}
+
+export function getSerializer (id: string) {
+    const serializer = serializers[id];
+    if (!serializer) { throw new Error("missing serializer: " + id); }
+    return serializer;
+}

package/src/transport/H3Transport.ts

@@ -0,0 +1,199 @@
+import { encode, decode, type Iterator } from '@colyseus/schema';
+import type { ITransport, ITransportEventMap } from "./ITransport.ts";
+
+export class H3TransportTransport implements ITransport {
+    wt: WebTransport;
+    isOpen: boolean = false;
+    events: ITransportEventMap;
+
+    reader: ReadableStreamDefaultReader;
+    writer: WritableStreamDefaultWriter;
+
+    unreliableReader: ReadableStreamDefaultReader<Uint8Array>;
+    unreliableWriter: WritableStreamDefaultWriter<Uint8Array>;
+
+    private lengthPrefixBuffer = new Uint8Array(9); // 9 bytes is the maximum length of a length prefix
+
+    constructor(events: ITransportEventMap) {
+        this.events = events;
+    }
+
+    public connect(url: string, options: any = {}) {
+        const wtOpts: WebTransportOptions = options.fingerprint && ({
+            // requireUnreliable: true,
+            // congestionControl: "default", // "low-latency" || "throughput"
+
+            serverCertificateHashes: [{
+                algorithm: 'sha-256',
+                value: new Uint8Array(options.fingerprint).buffer
+            }]
+        }) || undefined;
+
+        this.wt = new WebTransport(url, wtOpts);
+
+        this.wt.ready.then((e) => {
+            console.log("WebTransport ready!", e)
+            this.isOpen = true;
+
+            this.unreliableReader = this.wt.datagrams.readable.getReader();
+            this.unreliableWriter = this.wt.datagrams.writable.getWriter();
+
+            const incomingBidi = this.wt.incomingBidirectionalStreams.getReader();
+            incomingBidi.read().then((stream) => {
+                this.reader = stream.value.readable.getReader();
+                this.writer = stream.value.writable.getWriter();
+
+                // immediately write room/sessionId for establishing the room connection
+                this.sendSeatReservation(options.roomId, options.sessionId, options.reconnectionToken, options.skipHandshake);
+
+                // start reading incoming data
+                this.readIncomingData();
+                this.readIncomingUnreliableData();
+
+            }).catch((e) => {
+                console.error("failed to read incoming stream", e);
+                console.error("TODO: close the connection");
+            });
+
+            // this.events.onopen(e);
+        }).catch((e: WebTransportCloseInfo) => {
+            // this.events.onerror(e);
+            // this.events.onclose({ code: e.closeCode, reason: e.reason });
+            console.log("WebTransport not ready!", e)
+            this._close();
+        });
+
+        this.wt.closed.then((e: WebTransportCloseInfo) => {
+            console.log("WebTransport closed w/ success", e)
+            this.events.onclose({ code: e.closeCode, reason: e.reason });
+
+        }).catch((e: WebTransportCloseInfo) => {
+            console.log("WebTransport closed w/ error", e)
+            this.events.onerror(e);
+            this.events.onclose({ code: e.closeCode, reason: e.reason });
+        }).finally(() => {
+            this._close();
+        });
+    }
+
+    public send(data: Buffer | Uint8Array): void {
+        const prefixLength = encode.number(this.lengthPrefixBuffer as any, data.length, { offset: 0 });
+        const dataWithPrefixedLength = new Uint8Array(prefixLength + data.length);
+        dataWithPrefixedLength.set(this.lengthPrefixBuffer.subarray(0, prefixLength), 0);
+        dataWithPrefixedLength.set(data, prefixLength);
+        this.writer.write(dataWithPrefixedLength);
+    }
+
+    public sendUnreliable(data: Buffer | Uint8Array): void {
+        const prefixLength = encode.number(this.lengthPrefixBuffer as any, data.length, { offset: 0 });
+        const dataWithPrefixedLength = new Uint8Array(prefixLength + data.length);
+        dataWithPrefixedLength.set(this.lengthPrefixBuffer.subarray(0, prefixLength), 0);
+        dataWithPrefixedLength.set(data, prefixLength);
+        this.unreliableWriter.write(dataWithPrefixedLength);
+    }
+
+    public close(code?: number, reason?: string) {
+        try {
+            this.wt.close({ closeCode: code, reason: reason });
+        } catch (e) {
+            console.error(e);
+        }
+    }
+
+    protected async readIncomingData() {
+        let result: ReadableStreamReadResult<Uint8Array>;
+
+        while (this.isOpen) {
+            try {
+                result = await this.reader.read();
+
+                //
+                // a single read may contain multiple messages
+                // each message is prefixed with its length
+                //
+
+                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);
+
+            } catch (e) {
+                if (e.message.indexOf("session is closed") === -1) {
+                    console.error("H3Transport: failed to read incoming data", e);
+                }
+                break;
+            }
+
+            if (result.done) {
+                break;
+            }
+        }
+    }
+
+    protected async readIncomingUnreliableData() {
+        let result: ReadableStreamReadResult<Uint8Array>;
+
+        while (this.isOpen) {
+            try {
+                result = await this.unreliableReader.read();
+
+                //
+                // a single read may contain multiple messages
+                // each message is prefixed with its length
+                //
+
+                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);
+
+            } catch (e) {
+                if (e.message.indexOf("session is closed") === -1) {
+                    console.error("H3Transport: failed to read incoming data", e);
+                }
+                break;
+            }
+
+            if (result.done) {
+                break;
+            }
+        }
+    }
+
+    protected sendSeatReservation (roomId: string, sessionId: string, reconnectionToken?: string, skipHandshake?: boolean) {
+        const it: Iterator = { offset: 0 };
+        const bytes: number[] = [];
+
+        encode.string(bytes, roomId, it);
+        encode.string(bytes, sessionId, it);
+
+        if (reconnectionToken) {
+            encode.string(bytes, reconnectionToken, it);
+        }
+
+        if (skipHandshake) {
+            encode.boolean(bytes, 1, it);
+        }
+
+        this.writer.write(new Uint8Array(bytes).buffer);
+    }
+
+    protected _close() {
+        this.isOpen = false;
+    }
+
+}

package/src/transport/ITransport.ts

@@ -0,0 +1,18 @@
+export interface ITransportEventMap {
+    onopen?: ((ev: any) => any) | null;
+    onmessage?: ((ev: any) => any) | null;
+    onclose?: ((ev: any) => any) | null;
+    onerror?: ((ev: any) => any) | null;
+}
+
+export interface ITransportConstructor {
+    new (events: ITransportEventMap): ITransport;
+}
+
+export interface ITransport {
+    isOpen: boolean;
+    send(data: Buffer | Uint8Array): void;
+    sendUnreliable(data: Buffer | Uint8Array): void;
+    connect(url: string, options?: any): void;
+    close(code?: number, reason?: string): void;
+}

package/src/transport/WebSocketTransport.ts

@@ -0,0 +1,53 @@
+import NodeWebSocket from "ws";
+import type { ITransport, ITransportEventMap } from "./ITransport.ts";
+
+const WebSocket = globalThis.WebSocket || NodeWebSocket;
+
+export class WebSocketTransport implements ITransport {
+    ws: WebSocket | NodeWebSocket;
+    protocols?: string | string[];
+
+    events: ITransportEventMap;
+
+    constructor(events: ITransportEventMap) {
+        this.events = events;
+    }
+
+    public send(data: Buffer | Uint8Array): void {
+        this.ws.send(data);
+    }
+
+    public sendUnreliable(data: Uint8Array): void {
+        console.warn("colyseus.js: The WebSocket transport does not support unreliable messages");
+    }
+
+    /**
+     * @param url URL to connect to
+     * @param headers custom headers to send with the connection (only supported in Node.js. Web Browsers do not allow setting custom headers)
+     */
+    public connect(url: string, headers?: any): void {
+        try {
+            // Node or Bun environments (supports custom headers)
+            this.ws = new WebSocket(url, { headers, protocols: this.protocols });
+
+        } catch (e) {
+            // browser environment (custom headers not supported)
+            this.ws = new WebSocket(url, this.protocols);
+        }
+
+        this.ws.binaryType = 'arraybuffer';
+        this.ws.onopen = this.events.onopen;
+        this.ws.onmessage = this.events.onmessage;
+        this.ws.onclose = this.events.onclose;
+        this.ws.onerror = this.events.onerror;
+    }
+
+    public close(code?: number, reason?: string) {
+        this.ws.close(code, reason);
+    }
+
+    get isOpen() {
+        return this.ws.readyState === WebSocket.OPEN;
+    }
+
+}