@triformine/nexis-sdk 0.1.0 → 0.1.1

package/dist/esm/client.js

@@ -0,0 +1,719 @@
+import { applyPatch, computeStateChecksum, parsePatchPayload, parseSnapshotPayload } from "./patch";
+import { JsonCodec, MsgpackCodec, codecFor } from "./codec";
+import { RpcClient, UnknownRidError } from "./rpc";
+const DEFAULT_VERSION = 1;
+const DEFAULT_RECONNECT_INITIAL_DELAY_MS = 250;
+const DEFAULT_RECONNECT_MAX_DELAY_MS = 3_000;
+const DEFAULT_RECONNECT_MAX_ATTEMPTS = 20;
+function normalizeConnectOptions(options) {
+    const reconnectInitialDelayMs = Math.max(50, options.reconnectInitialDelayMs ?? DEFAULT_RECONNECT_INITIAL_DELAY_MS);
+    const reconnectMaxDelayMs = Math.max(reconnectInitialDelayMs, options.reconnectMaxDelayMs ?? DEFAULT_RECONNECT_MAX_DELAY_MS);
+    const reconnectMaxAttempts = Math.max(1, options.reconnectMaxAttempts ?? DEFAULT_RECONNECT_MAX_ATTEMPTS);
+    return {
+        ...options,
+        codecs: options.codecs ?? [
+            "msgpack",
+            "json"
+        ],
+        autoJoinMatchedRoom: options.autoJoinMatchedRoom ?? false,
+        autoReconnect: options.autoReconnect ?? true,
+        reconnectInitialDelayMs,
+        reconnectMaxDelayMs,
+        reconnectMaxAttempts
+    };
+}
+function readCodecName(message) {
+    const payload = message.p;
+    if (payload && typeof payload === "object" && "codec" in payload && payload.codec === "msgpack") {
+        return "msgpack";
+    }
+    return "json";
+}
+function readSessionId(message) {
+    const payload = message.p;
+    if (payload && typeof payload === "object" && "session_id" in payload && typeof payload.session_id === "string") {
+        return payload.session_id;
+    }
+    return undefined;
+}
+function readErrorReason(message) {
+    const payload = message.p;
+    if (payload && typeof payload === "object" && "reason" in payload && typeof payload.reason === "string") {
+        return payload.reason;
+    }
+    return "server returned error";
+}
+function isStringArray(value) {
+    return Array.isArray(value) && value.every((item)=>typeof item === "string");
+}
+function deepEqual(left, right) {
+    return JSON.stringify(left) === JSON.stringify(right);
+}
+function toJsonValue(bytes) {
+    let binary = "";
+    for (const value of bytes){
+        binary += String.fromCharCode(value);
+    }
+    return btoa(binary);
+}
+function fromJsonValue(value) {
+    if (typeof value !== "string") {
+        return null;
+    }
+    try {
+        const decoded = atob(value);
+        const bytes = new Uint8Array(decoded.length);
+        for(let i = 0; i < decoded.length; i += 1){
+            bytes[i] = decoded.charCodeAt(i);
+        }
+        return bytes;
+    } catch  {
+        return null;
+    }
+}
+function readRoomMessagePayload(payload) {
+    if (!payload || typeof payload !== "object") {
+        return null;
+    }
+    const type = payload.type;
+    if (typeof type !== "string" && typeof type !== "number") {
+        return null;
+    }
+    const data = payload.data;
+    return {
+        type,
+        data
+    };
+}
+export function parseMatchFoundPayload(payload) {
+    if (!payload || typeof payload !== "object") {
+        return null;
+    }
+    const room = payload.room;
+    const roomType = payload.room_type;
+    const size = payload.size;
+    const participants = payload.participants;
+    if (typeof room !== "string" || typeof roomType !== "string" || typeof size !== "number" || !Number.isFinite(size) || !isStringArray(participants)) {
+        return null;
+    }
+    return {
+        room,
+        roomType,
+        size,
+        participants
+    };
+}
+export class NexisRoom {
+    client;
+    id;
+    onStateChange;
+    constructor(client, roomId){
+        this.client = client;
+        this.id = roomId;
+        this.onStateChange = this.buildStateChangeSubscription();
+    }
+    get state() {
+        return this.client.getRoomState(this.id);
+    }
+    send(type, message) {
+        this.client.sendRoomMessage(this.id, type, message);
+    }
+    sendBytes(type, bytes) {
+        const normalized = bytes instanceof Uint8Array ? bytes : Uint8Array.from(bytes);
+        this.client.sendRoomMessageBytes(this.id, type, normalized);
+    }
+    onMessage(type, callback) {
+        return this.client.onRoomMessage(this.id, type, callback);
+    }
+    buildStateChangeSubscription() {
+        const subscribe = (callback)=>this.client.onRoomState(this.id, callback);
+        subscribe.once = (callback)=>this.client.onRoomStateOnce(this.id, callback);
+        subscribe.select = (path, callback)=>this.client.onRoomStateSelect(this.id, path, callback);
+        return subscribe;
+    }
+}
+export class NexisClient {
+    socket;
+    url;
+    connectOptions;
+    rpc = new RpcClient();
+    codec;
+    eventHandlers = new Map();
+    stateHandlers = new Set();
+    roomStateHandlers = new Map();
+    roomStateSelectors = new Map();
+    roomMessageHandlers = new Map();
+    roomStates = new Map();
+    roomSeq = new Map();
+    roomChecksum = new Map();
+    sessionId;
+    autoJoinMatchedRoom;
+    reconnecting = false;
+    disposed = false;
+    constructor(url, socket, codec, sessionId, options){
+        this.url = url;
+        this.socket = socket;
+        this.codec = codec;
+        this.sessionId = sessionId;
+        this.connectOptions = options;
+        this.autoJoinMatchedRoom = options.autoJoinMatchedRoom;
+        this.attachSocket(socket);
+    }
+    static connect(url, options) {
+        const resolved = normalizeConnectOptions(options);
+        return NexisClient.openSocketAndHandshake(url, resolved, resolved.sessionId).then(({ socket, codec, sessionId })=>new NexisClient(url, socket, codec, sessionId, resolved));
+    }
+    close() {
+        this.disposed = true;
+        this.socket.close();
+    }
+    attachSocket(socket) {
+        this.socket = socket;
+        this.socket.addEventListener("message", (event)=>{
+            void this.onRawMessage(event.data);
+        });
+        this.socket.addEventListener("close", ()=>{
+            this.rpc.rejectAll(new Error("socket closed"));
+            if (!this.disposed && this.connectOptions.autoReconnect) {
+                void this.tryReconnect();
+            }
+        });
+    }
+    async tryReconnect() {
+        if (this.reconnecting || this.disposed) {
+            return;
+        }
+        this.reconnecting = true;
+        this.dispatchEvent({
+            v: DEFAULT_VERSION,
+            t: "reconnect.start",
+            p: {
+                session_id: this.sessionId
+            }
+        });
+        let attempt = 0;
+        let delayMs = this.connectOptions.reconnectInitialDelayMs;
+        while(!this.disposed && attempt < this.connectOptions.reconnectMaxAttempts){
+            attempt += 1;
+            await NexisClient.wait(delayMs);
+            try {
+                const reconnect = await NexisClient.openSocketAndHandshake(this.url, this.connectOptions, this.sessionId);
+                this.codec = reconnect.codec;
+                this.sessionId = reconnect.sessionId ?? this.sessionId;
+                this.attachSocket(reconnect.socket);
+                this.dispatchEvent({
+                    v: DEFAULT_VERSION,
+                    t: "reconnect.ok",
+                    p: {
+                        attempt,
+                        session_id: this.sessionId
+                    }
+                });
+                this.reconnecting = false;
+                return;
+            } catch  {
+                this.dispatchEvent({
+                    v: DEFAULT_VERSION,
+                    t: "reconnect.retry",
+                    p: {
+                        attempt
+                    }
+                });
+            }
+            delayMs = Math.min(delayMs * 2, this.connectOptions.reconnectMaxDelayMs);
+        }
+        this.reconnecting = false;
+        this.dispatchEvent({
+            v: DEFAULT_VERSION,
+            t: "reconnect.failed",
+            p: {
+                session_id: this.sessionId
+            }
+        });
+    }
+    getSessionId() {
+        return this.sessionId;
+    }
+    room(roomId) {
+        return new NexisRoom(this, roomId);
+    }
+    async joinOrCreate(roomType, options) {
+        const roomId = typeof options?.roomId === "string" ? options.roomId : undefined;
+        const response = await this.sendRPC("room.join_or_create", {
+            roomType,
+            roomId,
+            options
+        }, roomId);
+        if (response && typeof response === "object" && typeof response.room === "string") {
+            return this.room(response.room);
+        }
+        if (roomId) {
+            return this.room(roomId);
+        }
+        return this.room(`${roomType}:default`);
+    }
+    listRooms(roomType) {
+        return this.sendRPC("room.list", roomType ? {
+            roomType
+        } : {});
+    }
+    enqueueMatchmaking(roomType, size = 2) {
+        return this.sendRPC("matchmaking.enqueue", {
+            roomType,
+            size
+        });
+    }
+    dequeueMatchmaking() {
+        return this.sendRPC("matchmaking.dequeue", {});
+    }
+    onStateChange(callback) {
+        this.stateHandlers.add(callback);
+        return ()=>this.stateHandlers.delete(callback);
+    }
+    onEvent(type, callback) {
+        const handlers = this.eventHandlers.get(type) ?? new Set();
+        handlers.add(callback);
+        this.eventHandlers.set(type, handlers);
+        return ()=>{
+            const current = this.eventHandlers.get(type);
+            if (!current) {
+                return;
+            }
+            current.delete(callback);
+            if (current.size === 0) {
+                this.eventHandlers.delete(type);
+            }
+        };
+    }
+    onMatchFound(callback) {
+        return this.onEvent("match.found", (message)=>{
+            const parsed = parseMatchFoundPayload(message.p);
+            if (!parsed) {
+                return;
+            }
+            callback(parsed, message);
+        });
+    }
+    sendRPC(type, payload, room) {
+        const { message, promise } = this.rpc.createRequest(type, payload, room);
+        this.sendEnvelope(message);
+        return promise;
+    }
+    getRoomState(roomId) {
+        return this.roomStates.get(roomId) ?? {};
+    }
+    sendRoomMessage(roomId, type, data) {
+        this.sendEnvelope({
+            v: DEFAULT_VERSION,
+            t: "room.message",
+            room: roomId,
+            p: {
+                type: String(type),
+                data
+            }
+        });
+    }
+    sendRoomMessageBytes(roomId, type, data) {
+        this.sendEnvelope({
+            v: DEFAULT_VERSION,
+            t: "room.message.bytes",
+            room: roomId,
+            p: {
+                type: String(type),
+                data_b64: toJsonValue(data)
+            }
+        });
+    }
+    onRoomMessage(roomId, type, callback) {
+        const key = String(type);
+        const byType = this.roomMessageHandlers.get(roomId) ?? new Map();
+        const handlers = byType.get(key) ?? new Set();
+        handlers.add(callback);
+        byType.set(key, handlers);
+        this.roomMessageHandlers.set(roomId, byType);
+        return ()=>{
+            const roomHandlers = this.roomMessageHandlers.get(roomId);
+            if (!roomHandlers) {
+                return;
+            }
+            const typeHandlers = roomHandlers.get(key);
+            if (!typeHandlers) {
+                return;
+            }
+            typeHandlers.delete(callback);
+            if (typeHandlers.size === 0) {
+                roomHandlers.delete(key);
+            }
+            if (roomHandlers.size === 0) {
+                this.roomMessageHandlers.delete(roomId);
+            }
+        };
+    }
+    onRoomState(roomId, callback) {
+        const handlers = this.roomStateHandlers.get(roomId) ?? new Set();
+        handlers.add(callback);
+        this.roomStateHandlers.set(roomId, handlers);
+        if (this.roomStates.has(roomId)) {
+            callback(this.roomStates.get(roomId) ?? {});
+        }
+        return ()=>{
+            const current = this.roomStateHandlers.get(roomId);
+            if (!current) {
+                return;
+            }
+            current.delete(callback);
+            if (current.size === 0) {
+                this.roomStateHandlers.delete(roomId);
+            }
+        };
+    }
+    onRoomStateOnce(roomId, callback) {
+        let disposed = false;
+        const off = this.onRoomState(roomId, (state)=>{
+            if (disposed) {
+                return;
+            }
+            disposed = true;
+            off();
+            callback(state);
+        });
+        return ()=>{
+            disposed = true;
+            off();
+        };
+    }
+    onRoomStateSelect(roomId, path, callback) {
+        const normalizedPath = path.startsWith("/") ? path.slice(1) : path;
+        const currentState = this.getRoomState(roomId);
+        const registration = {
+            path: normalizedPath,
+            callback,
+            lastValue: currentState[normalizedPath]
+        };
+        const selectors = this.roomStateSelectors.get(roomId) ?? new Set();
+        selectors.add(registration);
+        this.roomStateSelectors.set(roomId, selectors);
+        return ()=>{
+            const current = this.roomStateSelectors.get(roomId);
+            if (!current) {
+                return;
+            }
+            current.delete(registration);
+            if (current.size === 0) {
+                this.roomStateSelectors.delete(roomId);
+            }
+        };
+    }
+    sendEnvelope(message) {
+        const bytes = this.codec.encode(message);
+        this.socket.send(bytes);
+    }
+    dispatchEvent(message) {
+        const handlers = this.eventHandlers.get(message.t);
+        if (!handlers) {
+            return;
+        }
+        for (const handler of handlers){
+            handler(message);
+        }
+    }
+    dispatchState(roomId, nextState, prevState) {
+        for (const handler of this.stateHandlers){
+            handler(nextState);
+        }
+        const roomHandlers = this.roomStateHandlers.get(roomId);
+        if (roomHandlers) {
+            for (const handler of roomHandlers){
+                handler(nextState);
+            }
+        }
+        const selectors = this.roomStateSelectors.get(roomId);
+        if (selectors) {
+            for (const registration of selectors){
+                const nextValue = nextState[registration.path];
+                const prevValue = prevState[registration.path];
+                if (!deepEqual(nextValue, prevValue)) {
+                    registration.lastValue = nextValue;
+                    registration.callback(nextValue, nextState);
+                }
+            }
+        }
+    }
+    dispatchRoomMessage(message) {
+        if (!message.room) {
+            return;
+        }
+        const payload = readRoomMessagePayload(message.p);
+        if (!payload) {
+            return;
+        }
+        const byType = this.roomMessageHandlers.get(message.room);
+        if (!byType) {
+            return;
+        }
+        const handlers = byType.get(String(payload.type));
+        if (!handlers) {
+            return;
+        }
+        for (const handler of handlers){
+            handler(payload.data, message);
+        }
+    }
+    async onRawMessage(raw) {
+        const bytes = await NexisClient.toBytes(raw);
+        if (!bytes) {
+            return;
+        }
+        let message;
+        try {
+            message = this.codec.decode(bytes);
+        } catch  {
+            return;
+        }
+        if (message.t === "rpc.response") {
+            try {
+                this.rpc.resolveResponse(message);
+            } catch (error) {
+                if (error instanceof UnknownRidError) {
+                    this.dispatchEvent({
+                        v: DEFAULT_VERSION,
+                        t: "error",
+                        p: {
+                            reason: error.message
+                        }
+                    });
+                    return;
+                }
+                throw error;
+            }
+            return;
+        }
+        if (message.t === "state.snapshot") {
+            if (!message.room) {
+                return;
+            }
+            const snapshot = parseSnapshotPayload(message.p);
+            if (!snapshot) {
+                return;
+            }
+            const computedChecksum = await computeStateChecksum(snapshot.state);
+            if (snapshot.checksum && snapshot.checksum !== computedChecksum) {
+                this.sendEnvelope({
+                    v: DEFAULT_VERSION,
+                    t: "state.resync",
+                    room: message.room,
+                    p: {
+                        since: this.roomSeq.get(message.room) ?? 0
+                    }
+                });
+                return;
+            }
+            const checksum = snapshot.checksum ?? computedChecksum;
+            const prevState = this.roomStates.get(message.room) ?? {};
+            this.roomStates.set(message.room, snapshot.state);
+            this.roomSeq.set(message.room, snapshot.seq);
+            this.roomChecksum.set(message.room, checksum);
+            this.dispatchState(message.room, snapshot.state, prevState);
+            this.sendEnvelope({
+                v: DEFAULT_VERSION,
+                t: "state.ack",
+                room: message.room,
+                p: {
+                    seq: snapshot.seq,
+                    checksum
+                }
+            });
+            return;
+        }
+        if (message.t === "state.patch") {
+            if (!message.room) {
+                return;
+            }
+            const parsedPatch = parsePatchPayload(message.p);
+            if (!parsedPatch) {
+                return;
+            }
+            const currentSeq = this.roomSeq.get(message.room) ?? 0;
+            const patchSeq = parsedPatch.seq > 0 ? parsedPatch.seq : currentSeq + 1;
+            if (patchSeq <= currentSeq) {
+                return;
+            }
+            if (patchSeq > currentSeq + 1) {
+                this.sendEnvelope({
+                    v: DEFAULT_VERSION,
+                    t: "state.resync",
+                    room: message.room,
+                    p: {
+                        since: currentSeq
+                    }
+                });
+                return;
+            }
+            const currentState = this.roomStates.get(message.room) ?? {};
+            const nextState = applyPatch(currentState, parsedPatch.ops);
+            let localChecksum;
+            if (parsedPatch.checksum) {
+                localChecksum = await computeStateChecksum(nextState);
+                if (parsedPatch.checksum !== localChecksum) {
+                    this.sendEnvelope({
+                        v: DEFAULT_VERSION,
+                        t: "state.resync",
+                        room: message.room,
+                        p: {
+                            since: currentSeq,
+                            checksum: this.roomChecksum.get(message.room)
+                        }
+                    });
+                    return;
+                }
+            }
+            this.roomStates.set(message.room, nextState);
+            this.roomSeq.set(message.room, patchSeq);
+            if (parsedPatch.checksum) {
+                this.roomChecksum.set(message.room, parsedPatch.checksum);
+            } else if (localChecksum) {
+                this.roomChecksum.set(message.room, localChecksum);
+            }
+            this.dispatchState(message.room, nextState, currentState);
+            this.sendEnvelope({
+                v: DEFAULT_VERSION,
+                t: "state.ack",
+                room: message.room,
+                p: parsedPatch.checksum ? {
+                    seq: patchSeq,
+                    checksum: this.roomChecksum.get(message.room)
+                } : {
+                    seq: patchSeq
+                }
+            });
+            return;
+        }
+        if (this.autoJoinMatchedRoom && message.t === "match.found") {
+            const parsed = parseMatchFoundPayload(message.p);
+            if (parsed) {
+                void this.joinOrCreate(parsed.roomType, {
+                    roomId: parsed.room
+                }).catch(()=>undefined);
+            }
+        }
+        if (message.t === "room.message" && message.room) {
+            this.dispatchRoomMessage(message);
+        }
+        this.dispatchEvent(message);
+    }
+    static openSocketAndHandshake(url, options, sessionIdOverride) {
+        const socket = new WebSocket(url);
+        const jsonCodec = new JsonCodec();
+        const msgpackCodec = new MsgpackCodec();
+        return new Promise((resolve, reject)=>{
+            let settled = false;
+            const handshakeSessionId = sessionIdOverride ?? options.sessionId;
+            const onOpen = ()=>{
+                const handshake = {
+                    v: DEFAULT_VERSION,
+                    codecs: options.codecs,
+                    project_id: options.projectId?.trim() || "anonymous",
+                    token: options.token?.trim() || "",
+                    session_id: handshakeSessionId
+                };
+                socket.send(JSON.stringify(handshake));
+            };
+            const onError = ()=>{
+                finishReject(new Error("socket connection failed"));
+            };
+            const onClose = ()=>{
+                finishReject(new Error("socket closed before handshake"));
+            };
+            const onMessage = async (event)=>{
+                try {
+                    const message = await NexisClient.decodeHandshakeMessage(event.data, jsonCodec, msgpackCodec);
+                    if (!message) {
+                        return;
+                    }
+                    if (message.t === "error") {
+                        finishReject(new Error(readErrorReason(message)));
+                        return;
+                    }
+                    if (message.t !== "handshake.ok") {
+                        return;
+                    }
+                    const negotiatedCodec = readCodecName(message);
+                    const sessionId = readSessionId(message) ?? handshakeSessionId;
+                    finishResolve({
+                        socket,
+                        codec: codecFor(negotiatedCodec),
+                        sessionId
+                    });
+                } catch (error) {
+                    finishReject(new Error(`handshake decode failed: ${String(error)}`));
+                }
+            };
+            const cleanup = ()=>{
+                socket.removeEventListener("open", onOpen);
+                socket.removeEventListener("error", onError);
+                socket.removeEventListener("close", onClose);
+                socket.removeEventListener("message", onMessage);
+            };
+            const finishResolve = (result)=>{
+                if (settled) {
+                    return;
+                }
+                settled = true;
+                cleanup();
+                resolve(result);
+            };
+            const finishReject = (error)=>{
+                if (settled) {
+                    return;
+                }
+                settled = true;
+                cleanup();
+                reject(error);
+            };
+            socket.addEventListener("open", onOpen);
+            socket.addEventListener("error", onError);
+            socket.addEventListener("close", onClose);
+            socket.addEventListener("message", onMessage);
+        });
+    }
+    static wait(ms) {
+        return new Promise((resolve)=>setTimeout(resolve, ms));
+    }
+    static async decodeHandshakeMessage(raw, jsonCodec, msgpackCodec) {
+        if (typeof raw === "string") {
+            return JSON.parse(raw);
+        }
+        const bytes = await NexisClient.toBytes(raw);
+        if (!bytes) {
+            return null;
+        }
+        try {
+            return msgpackCodec.decode(bytes);
+        } catch  {
+            return jsonCodec.decode(bytes);
+        }
+    }
+    static async toBytes(raw) {
+        if (raw instanceof Uint8Array) {
+            return raw;
+        }
+        if (raw instanceof ArrayBuffer) {
+            return new Uint8Array(raw);
+        }
+        if (raw instanceof Blob) {
+            return new Uint8Array(await raw.arrayBuffer());
+        }
+        if (typeof raw === "string") {
+            return new TextEncoder().encode(raw);
+        }
+        return null;
+    }
+}
+export async function connect(url, options) {
+    return NexisClient.connect(url, options);
+}
+export function decodeRoomBytes(payload) {
+    return fromJsonValue(payload);
+}
+
+//# sourceMappingURL=client.js.map