@colyseus/sdk 0.17.0 → 0.17.2

package/src/3rd_party/discord.ts

@@ -0,0 +1,48 @@
+/**
+ * Discord Embedded App SDK
+ * https://github.com/colyseus/colyseus/issues/707
+ *
+ * All URLs must go through the local proxy from
+ * https://<app_id>.discordsays.com/.proxy/<mapped_url>/...
+ *
+ * URL Mapping Examples:
+ *
+ * 1. Using Colyseus Cloud:
+ *   - /colyseus/{subdomain} -> {subdomain}.colyseus.cloud
+ *
+ *   Example:
+ *     const client = new Client("https://xxxx.colyseus.cloud");
+ *
+ * -------------------------------------------------------------
+ *
+ * 2. Using `cloudflared` tunnel:
+ *   - /colyseus/ -> <your-cloudflared-url>.trycloudflare.com
+ *
+ *   Example:
+ *     const client = new Client("https://<your-cloudflared-url>.trycloudflare.com");
+ *
+ * -------------------------------------------------------------
+ *
+ * 3. Providing a manual /.proxy/your-mapping:
+ *   - /your-mapping/ -> your-endpoint.com
+ *
+ *   Example:
+ *     const client = new Client("/.proxy/your-mapping");
+ *
+ */
+export function discordURLBuilder (url: URL): string {
+    const localHostname = window?.location?.hostname || "localhost";
+
+    const remoteHostnameSplitted = url.hostname.split('.');
+    const subdomain = (
+        !url.hostname.includes("trycloudflare.com") && // ignore cloudflared subdomains
+        !url.hostname.includes("discordsays.com") &&  // ignore discordsays.com subdomains
+        remoteHostnameSplitted.length > 2
+    )
+        ? `/${remoteHostnameSplitted[0]}`
+        : '';
+
+    return (url.pathname.startsWith("/.proxy"))
+        ? `${url.protocol}//${localHostname}${subdomain}${url.pathname}${url.search}`
+        : `${url.protocol}//${localHostname}/.proxy/colyseus${subdomain}${url.pathname}${url.search}`;
+}

package/src/Auth.ts

@@ -0,0 +1,177 @@
+import { HTTP } from "./HTTP.ts";
+import { getItem, removeItem, setItem } from "./Storage.ts";
+import { createNanoEvents } from './core/nanoevents.ts';
+
+export interface AuthSettings {
+    path: string;
+    key: string;
+}
+
+export interface PopupSettings {
+    prefix: string;
+    width: number;
+    height: number;
+}
+
+export interface AuthData {
+    user: any;
+    token: string;
+}
+
+export class Auth {
+    settings: AuthSettings = {
+        path: "/auth",
+        key: "colyseus-auth-token",
+    };
+
+    #_initialized = false;
+    #_signInWindow: WindowProxy | null = null;
+    #_events = createNanoEvents();
+
+    protected http: HTTP<any>;
+
+    constructor(http: HTTP<any>) {
+        this.http = http;
+        getItem(this.settings.key, (token: string) => this.token = token);
+    }
+
+    public set token(token: string) {
+        this.http.authToken = token;
+    }
+
+    public get token(): string | undefined {
+        return this.http.authToken;
+    }
+
+    public onChange(callback: (response: AuthData) => void) {
+        const unbindChange = this.#_events.on("change", callback);
+        if (!this.#_initialized) {
+            this.getUserData().then((userData: any) => {
+                this.emitChange({ ...userData, token: this.token });
+
+            }).catch((e) => {
+                // user is not logged in, or service is down
+                this.emitChange({ user: null, token: undefined });
+            });
+        }
+        this.#_initialized = true;
+        return unbindChange;
+    }
+
+    public async getUserData() {
+        if (this.token) {
+            return (await this.http.get(`${this.settings.path}/userdata`)).data;
+        } else {
+            throw new Error("missing auth.token");
+        }
+    }
+
+    public async registerWithEmailAndPassword(email: string, password: string, options?: any) {
+        const data = (await this.http.post(`${this.settings.path}/register`, {
+            body: { email, password, options, },
+        })).data;
+
+        this.emitChange(data as any);
+
+        return data;
+    }
+
+    public async signInWithEmailAndPassword(email: string, password: string) {
+        const data = (await this.http.post(`${this.settings.path}/login`, {
+            body: { email, password, },
+        })).data;
+
+        this.emitChange(data as any);
+
+        return data;
+    }
+
+    public async signInAnonymously(options?: any) {
+        const data = (await this.http.post(`${this.settings.path}/anonymous`, {
+            body: { options, }
+        })).data;
+
+        this.emitChange(data as any);
+
+        return data;
+    }
+
+    public async sendPasswordResetEmail(email: string) {
+        return (await this.http.post(`${this.settings.path}/forgot-password`, {
+            body: { email, }
+        })).data;
+    }
+
+    public async signInWithProvider(providerName: string, settings: Partial<PopupSettings> = {}) {
+        return new Promise((resolve, reject) => {
+            const w = settings.width || 480;
+            const h = settings.height || 768;
+
+            // forward existing token for upgrading
+            const upgradingToken = this.token ? `?token=${this.token}` : "";
+
+            // Capitalize first letter of providerName
+            const title = `Login with ${(providerName[0].toUpperCase() + providerName.substring(1))}`;
+            const url = this.http['sdk']['getHttpEndpoint'](`${(settings.prefix || `${this.settings.path}/provider`)}/${providerName}${upgradingToken}`);
+
+            const left = (screen.width / 2) - (w / 2);
+            const top = (screen.height / 2) - (h / 2);
+
+            this.#_signInWindow = window.open(url, title, 'toolbar=no, location=no, directories=no, status=no, menubar=no, scrollbars=no, resizable=no, copyhistory=no, width=' + w + ', height=' + h + ', top=' + top + ', left=' + left);
+
+            const onMessage = (event: MessageEvent) => {
+                // TODO: it is a good idea to check if event.origin can be trusted!
+                // if (event.origin.indexOf(window.location.hostname) === -1) { return; }
+
+                // require 'user' and 'token' inside received data.
+                if (event.data.user === undefined && event.data.token === undefined) { return; }
+
+                clearInterval(rejectionChecker);
+                this.#_signInWindow?.close();
+                this.#_signInWindow = null;
+
+                window.removeEventListener("message", onMessage);
+
+                if (event.data.error !== undefined) {
+                    reject(event.data.error);
+
+                } else {
+                    resolve(event.data);
+                    this.emitChange(event.data);
+                }
+            }
+
+            const rejectionChecker = setInterval(() => {
+                if (!this.#_signInWindow || this.#_signInWindow.closed) {
+                    this.#_signInWindow = null;
+                    reject("cancelled");
+                    window.removeEventListener("message", onMessage);
+                }
+            }, 200);
+
+            window.addEventListener("message", onMessage);
+        });
+    }
+
+    public async signOut() {
+        // @ts-ignore
+        this.emitChange({ user: null, token: null });
+    }
+
+    private emitChange(authData: Partial<AuthData>) {
+        if (authData.token !== undefined) {
+            this.token = authData.token;
+
+            if (authData.token === null) {
+                removeItem(this.settings.key);
+
+            } else {
+                // store key in localStorage
+                setItem(this.settings.key, authData.token);
+            }
+        }
+
+        this.#_events.emit("change", authData);
+    }
+
+}

package/src/Client.ts

@@ -0,0 +1,459 @@
+import type { matchMaker, SDKTypes, Room as ServerRoom } from '@colyseus/core';
+
+import { CloseCode, ServerError } from './errors/Errors.ts';
+import { Room } from './Room.ts';
+import { SchemaConstructor } from './serializer/SchemaSerializer.ts';
+import { HTTP } from './HTTP.ts';
+import { Auth } from './Auth.ts';
+import { Protocol } from './Protocol.ts';
+import { Connection } from './Connection.ts';
+import { discordURLBuilder } from './3rd_party/discord.ts';
+
+export type JoinOptions = any;
+export type ISeatReservation = matchMaker.ISeatReservation;
+
+export class MatchMakeError extends Error {
+    code: number;
+    constructor(message: string, code: number) {
+        super(message);
+        this.code = code;
+        this.name = "MatchMakeError";
+        Object.setPrototypeOf(this, MatchMakeError.prototype);
+    }
+}
+
+// - React Native does not provide `window.location`
+// - Cocos Creator (Native) does not provide `window.location.hostname`
+const DEFAULT_ENDPOINT = (typeof (window) !== "undefined" &&  typeof (window?.location?.hostname) !== "undefined")
+    ? `${window.location.protocol.replace("http", "ws")}//${window.location.hostname}${(window.location.port && `:${window.location.port}`)}`
+    : "ws://127.0.0.1:2567";
+
+export interface EndpointSettings {
+    hostname: string,
+    secure: boolean,
+    port?: number,
+    pathname?: string,
+    searchParams?: string,
+    protocol?: "ws" | "h3";
+}
+
+export interface ClientOptions {
+    headers?: { [id: string]: string };
+    urlBuilder?: (url: URL) => string;
+    protocol?: "ws" | "h3";
+}
+
+export interface LatencyOptions {
+    /** "ws" for WebSocket, "h3" for WebTransport (default: "ws") */
+    protocol?: "ws" | "h3";
+    /** Number of pings to send (default: 1). Returns the average latency when > 1. */
+    pingCount?: number;
+}
+
+export class ColyseusSDK<ServerType extends SDKTypes = any> {
+    static VERSION = "0.17";
+
+    /**
+     * The HTTP client to make requests to the server.
+     */
+    public http: HTTP<ServerType['~routes']>;
+
+    /**
+     * The authentication module to authenticate into requests and rooms.
+     */
+    public auth: Auth;
+
+    /**
+     * The settings used to connect to the server.
+     */
+    public settings: EndpointSettings;
+
+    protected urlBuilder: (url: URL) => string;
+
+    constructor(
+        settings: string | EndpointSettings = DEFAULT_ENDPOINT,
+        options?: ClientOptions,
+    ) {
+        if (typeof (settings) === "string") {
+
+            //
+            // endpoint by url
+            //
+            const url = (settings.startsWith("/"))
+                ? new URL(settings, DEFAULT_ENDPOINT)
+                : new URL(settings);
+
+            const secure = (url.protocol === "https:" || url.protocol === "wss:");
+            const port = Number(url.port || (secure ? 443 : 80));
+
+            this.settings = {
+                hostname: url.hostname,
+                pathname: url.pathname,
+                port,
+                secure,
+                searchParams: url.searchParams.toString() || undefined,
+            };
+
+        } else {
+            //
+            // endpoint by settings
+            //
+            if (settings.port === undefined) {
+                settings.port = (settings.secure) ? 443 : 80;
+            }
+            if (settings.pathname === undefined) {
+                settings.pathname = "";
+            }
+            this.settings = settings;
+        }
+
+        // make sure pathname does not end with "/"
+        if (this.settings.pathname.endsWith("/")) {
+            this.settings.pathname = this.settings.pathname.slice(0, -1);
+        }
+
+        // specify room connection protocol if provided
+        if (options?.protocol) {
+            this.settings.protocol = options.protocol;
+        }
+
+        this.http = new HTTP(this, {
+            headers: options?.headers || {},
+        });
+        this.auth = new Auth(this.http);
+
+        this.urlBuilder = options?.urlBuilder;
+
+        //
+        // Discord Embedded SDK requires a custom URL builder
+        //
+        if (
+            !this.urlBuilder &&
+            typeof (window) !== "undefined" &&
+            window?.location?.hostname?.includes("discordsays.com")
+        ) {
+            this.urlBuilder = discordURLBuilder;
+            console.log("Colyseus SDK: Discord Embedded SDK detected. Using custom URL builder.");
+        }
+    }
+
+    /**
+     * 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).
+     * @returns The client with the lowest latency.
+     */
+    static async selectByLatency<ServerType extends SDKTypes = any>(
+        endpoints: Array<string | EndpointSettings>,
+        options?: ClientOptions,
+        latencyOptions: LatencyOptions = {}
+    ) {
+        const clients = endpoints.map(endpoint => new ColyseusSDK<ServerType>(endpoint, options));
+
+        const latencies = (await Promise.allSettled(clients.map((client, index) => client.getLatency(latencyOptions).then(latency => {
+            const settings = clients[index].settings;
+            console.log(`🛜 Endpoint Latency: ${latency}ms - ${settings.hostname}:${settings.port}${settings.pathname}`);
+            return [index, latency]
+        }))))
+            .filter((result) => result.status === 'fulfilled')
+            .map(result => result.value);
+
+        if (latencies.length === 0) {
+            throw new Error('All endpoints failed to respond');
+        }
+
+        return clients[latencies.sort((a, b) => a[1] - b[1])[0][0]];
+    }
+
+    // Overload: Use room name from ServerType to infer room type
+    public async joinOrCreate<R extends keyof ServerType['~rooms']>(
+        roomName: R,
+        options?: Parameters<ServerType['~rooms'][R]['~room']['prototype']['onJoin']>[1],
+        rootSchema?: SchemaConstructor<ServerType>
+    ): Promise<Room<ServerType['~rooms'][R]['~room']>>
+    // Overload: Pass RoomType directly to extract state
+    public async joinOrCreate<RoomType extends typeof ServerRoom>(
+        roomName: string,
+        options?: Parameters<RoomType['prototype']['onJoin']>[1],
+        rootSchema?: SchemaConstructor<RoomType['prototype']['state']>
+    ): Promise<Room<RoomType>>
+    // Overload: Pass State type directly
+    public async joinOrCreate<State = any>(
+        roomName: string,
+        options?: JoinOptions,
+        rootSchema?: SchemaConstructor<State>
+    ): Promise<Room<any, State>>
+    // Implementation
+    public async joinOrCreate<T = any>(roomName: string, options: JoinOptions = {}, rootSchema?: SchemaConstructor<T>) {
+        return await this.createMatchMakeRequest<T>('joinOrCreate', roomName, options, rootSchema);
+    }
+
+    // Overload: Use room name from ServerType to infer room type
+    public async create<R extends keyof ServerType['~rooms']>(
+        roomName: R,
+        options?: Parameters<ServerType['~rooms'][R]['~room']['prototype']['onJoin']>[1],
+        rootSchema?: SchemaConstructor<ServerType>
+    ): Promise<Room<ServerType['~rooms'][R]['~room']>>
+    // Overload: Pass RoomType directly to extract state
+    public async create<RoomType extends typeof ServerRoom>(
+        roomName: string,
+        options?: Parameters<RoomType['prototype']['onJoin']>[1],
+        rootSchema?: SchemaConstructor<RoomType['prototype']['state']>
+    ): Promise<Room<RoomType>>
+    // Overload: Pass State type directly
+    public async create<State = any>(
+        roomName: string,
+        options?: JoinOptions,
+        rootSchema?: SchemaConstructor<State>
+    ): Promise<Room<any, State>>
+    // Implementation
+    public async create<T = any>(roomName: string, options: JoinOptions = {}, rootSchema?: SchemaConstructor<T>) {
+        return await this.createMatchMakeRequest<T>('create', roomName, options, rootSchema);
+    }
+
+    // Overload: Use room name from ServerType to infer room type
+    public async join<R extends keyof ServerType['~rooms']>(
+        roomName: R,
+        options?: Parameters<ServerType['~rooms'][R]['~room']['prototype']['onJoin']>[1],
+        rootSchema?: SchemaConstructor<ServerType>
+    ): Promise<Room<ServerType['~rooms'][R]['~room']>>
+    // Overload: Pass RoomType directly to extract state
+    public async join<RoomType extends typeof ServerRoom>(
+        roomName: string,
+        options?: Parameters<RoomType['prototype']['onJoin']>[1],
+        rootSchema?: SchemaConstructor<RoomType['prototype']['state']>
+    ): Promise<Room<RoomType>>
+    // Overload: Pass State type directly
+    public async join<State = any>(
+        roomName: string,
+        options?: JoinOptions,
+        rootSchema?: SchemaConstructor<State>
+    ): Promise<Room<any, State>>
+    // Implementation
+    public async join<T = any>(roomName: string, options: JoinOptions = {}, rootSchema?: SchemaConstructor<T>) {
+        return await this.createMatchMakeRequest<T>('join', roomName, options, rootSchema);
+    }
+
+    // Overload: Use room name from ServerType to infer room type
+    public async joinById<R extends keyof ServerType['~rooms']>(
+        roomName: R,
+        options?: Parameters<ServerType['~rooms'][R]['~room']['prototype']['onJoin']>[1],
+        rootSchema?: SchemaConstructor<ServerType>
+    ): Promise<Room<ServerType['~rooms'][R]['~room']>>
+    // Overload: Pass RoomType directly to extract state
+    public async joinById<RoomType extends typeof ServerRoom>(
+        roomId: string,
+        options?: Parameters<RoomType['prototype']['onJoin']>[1],
+        rootSchema?: SchemaConstructor<RoomType['prototype']['state']>
+    ): Promise<Room<RoomType>>
+    // Overload: Pass State type directly
+    public async joinById<State = any>(
+        roomId: string,
+        options?: JoinOptions,
+        rootSchema?: SchemaConstructor<State>
+    ): Promise<Room<any, State>>
+    // Implementation
+    public async joinById<T = any>(roomId: string, options: JoinOptions = {}, rootSchema?: SchemaConstructor<T>) {
+        return await this.createMatchMakeRequest<T>('joinById', roomId, options, rootSchema);
+    }
+
+    /**
+     * Re-establish connection with a room this client was previously connected to.
+     *
+     * @param reconnectionToken The `room.reconnectionToken` from previously connected room.
+     * @param rootSchema (optional) Concrete root schema definition
+     * @returns Promise<Room>
+     */
+    // Overload: Use room name from ServerType to infer room type
+    public async reconnect<R extends keyof ServerType['~rooms']>(reconnectionToken: string, roomName?: R): Promise<Room<ServerType['~rooms'][R]['~room']>>
+    // Overload: Pass RoomType directly to extract state
+    public async reconnect<RoomType extends typeof ServerRoom>(
+        reconnectionToken: string,
+        rootSchema?: SchemaConstructor<RoomType['prototype']['state']>
+    ): Promise<Room<RoomType>>
+    // Overload: Pass State type directly
+    public async reconnect<State = any>(
+        reconnectionToken: string,
+        rootSchema?: SchemaConstructor<State>
+    ): Promise<Room<any, State>>
+    // Implementation
+    public async reconnect<T = any>(reconnectionToken: string, rootSchema?: SchemaConstructor<T>) {
+        if (typeof (reconnectionToken) === "string" && typeof (rootSchema) === "string") {
+            throw new Error("DEPRECATED: .reconnect() now only accepts 'reconnectionToken' as argument.\nYou can get this token from previously connected `room.reconnectionToken`");
+        }
+        const [roomId, token] = reconnectionToken.split(":");
+		if (!roomId || !token) {
+			throw new Error("Invalid reconnection token format.\nThe format should be roomId:reconnectionToken");
+		}
+        return await this.createMatchMakeRequest<T>('reconnect', roomId, { reconnectionToken: token }, rootSchema);
+    }
+
+    public async consumeSeatReservation<T>(
+        response: ISeatReservation,
+        rootSchema?: SchemaConstructor<T>
+    ): Promise<Room<any, T>> {
+        const room = this.createRoom<T>(response.name, rootSchema);
+        room.roomId = response.roomId;
+        room.sessionId = response.sessionId;
+
+        const options: any = { sessionId: room.sessionId };
+
+        // forward "reconnection token" in case of reconnection.
+        if (response.reconnectionToken) {
+            options.reconnectionToken = response.reconnectionToken;
+        }
+
+        room.connect(
+            this.buildEndpoint(response, options),
+            response,
+            this.http.options.headers
+        );
+
+        return new Promise((resolve, reject) => {
+            const onError = (code, message) => reject(new ServerError(code, message));
+            room.onError.once(onError);
+
+            room['onJoin'].once(() => {
+                room.onError.remove(onError);
+                resolve(room);
+            });
+        });
+    }
+
+    /**
+     * Create a new connection with the server, and measure the latency.
+     * @param options Latency measurement options (protocol, pingCount).
+     */
+    public getLatency(options: LatencyOptions = {}): Promise<number> {
+        const protocol = options.protocol ?? "ws";
+        const pingCount = options.pingCount ?? 1;
+
+        return new Promise<number>((resolve, reject) => {
+            const conn = new Connection(protocol);
+            const latencies: number[] = [];
+            let pingStart = 0;
+
+            conn.events.onopen = () => {
+                pingStart = Date.now();
+                conn.send(new Uint8Array([Protocol.PING]));
+            };
+
+            conn.events.onmessage = (_: MessageEvent) => {
+                latencies.push(Date.now() - pingStart);
+
+                if (latencies.length < pingCount) {
+                    // Send another ping
+                    pingStart = Date.now();
+                    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);
+                }
+            };
+
+            conn.events.onerror = (event: ErrorEvent) => {
+                reject(new ServerError(CloseCode.ABNORMAL_CLOSURE, `Failed to get latency: ${event.message}`));
+            };
+
+            conn.connect(this.getHttpEndpoint());
+        });
+    }
+
+    protected async createMatchMakeRequest<T>(
+        method: string,
+        roomName: string,
+        options: JoinOptions = {},
+        rootSchema?: SchemaConstructor<T>,
+    ) {
+        const httpResponse = await (this.http as HTTP<any>).post(`/matchmake/${method}/${roomName}`, {
+            headers: {
+                'Accept': 'application/json',
+                'Content-Type': 'application/json'
+            },
+            body: options
+        });
+
+        // Handle HTTP error responses
+        if (!httpResponse.ok) {
+            // @ts-ignore
+            throw new MatchMakeError(httpResponse.error.message || httpResponse.error, httpResponse.error.code || httpResponse.status);
+        }
+
+        const response = httpResponse.data as unknown as ISeatReservation;
+
+        // forward reconnection token during "reconnect" methods.
+        if (method === "reconnect") {
+            response.reconnectionToken = options.reconnectionToken;
+        }
+
+        return await this.consumeSeatReservation<T>(response, rootSchema);
+    }
+
+    protected createRoom<T>(roomName: string, rootSchema?: SchemaConstructor<T>) {
+        return new Room<any, T>(roomName, rootSchema);
+    }
+
+    protected buildEndpoint(seatReservation: ISeatReservation, options: any = {}) {
+        let protocol: string = this.settings.protocol || "ws";
+        let searchParams = this.settings.searchParams || "";
+
+        // forward authentication token
+        if (this.http.authToken) {
+            options['_authToken'] = this.http.authToken;
+        }
+
+        // append provided options
+        for (const name in options) {
+            if (!options.hasOwnProperty(name)) {
+                continue;
+            }
+            searchParams += (searchParams ? '&' : '') + `${name}=${options[name]}`;
+        }
+
+        if (protocol === "h3") {
+            protocol = "http";
+        }
+
+        let endpoint = (this.settings.secure)
+            ? `${protocol}s://`
+            : `${protocol}://`;
+
+        if (seatReservation.publicAddress) {
+            endpoint += `${seatReservation.publicAddress}`;
+
+        } else {
+            endpoint += `${this.settings.hostname}${this.getEndpointPort()}${this.settings.pathname}`;
+        }
+
+        const endpointURL = `${endpoint}/${seatReservation.processId}/${seatReservation.roomId}?${searchParams}`;
+        return (this.urlBuilder)
+            ? this.urlBuilder(new URL(endpointURL))
+            : endpointURL;
+    }
+
+    protected getHttpEndpoint(segments: string = '') {
+        const path = segments.startsWith("/") ? segments : `/${segments}`;
+
+        let endpointURL = `${(this.settings.secure) ? "https" : "http"}://${this.settings.hostname}${this.getEndpointPort()}${this.settings.pathname}${path}`;
+
+        if (this.settings.searchParams) {
+            endpointURL += `?${this.settings.searchParams}`;
+        }
+
+        return (this.urlBuilder)
+            ? this.urlBuilder(new URL(endpointURL))
+            : endpointURL;
+    }
+
+    protected getEndpointPort() {
+        return (this.settings.port !== 80 && this.settings.port !== 443)
+            ? `:${this.settings.port}`
+            : "";
+    }
+}
+
+export const Client = ColyseusSDK;
+export type Client = InstanceType<typeof ColyseusSDK>;