@jgengine/ws 0.7.0 → 0.9.0

package/dist/peer.js

@@ -0,0 +1,241 @@
+import { createGameHost, memoryPersistence } from "./host.js";
+import { createHostRouter, loopbackPipe } from "./hostRouter.js";
+import { createWsBackend } from "./createWsBackend.js";
+const DEFAULT_ICE_GATHER_TIMEOUT_MS = 2_000;
+function isRecord(value) {
+    return typeof value === "object" && value !== null;
+}
+export function encodePeerSignal(payload) {
+    const base64 = btoa(JSON.stringify(payload));
+    return base64.replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+export function decodePeerSignal(code) {
+    try {
+        const base64 = code.replace(/-/g, "+").replace(/_/g, "/");
+        const padded = base64 + "=".repeat((4 - (base64.length % 4)) % 4);
+        const parsed = JSON.parse(atob(padded));
+        if (!isRecord(parsed))
+            return null;
+        if (parsed.type !== "offer" && parsed.type !== "answer")
+            return null;
+        if (typeof parsed.sdp !== "string")
+            return null;
+        return { type: parsed.type, sdp: parsed.sdp };
+    }
+    catch {
+        return null;
+    }
+}
+function waitForIceGathering(pc, timeoutMs) {
+    if (pc.iceGatheringState === "complete")
+        return Promise.resolve();
+    return new Promise((resolve) => {
+        let settled = false;
+        const finish = () => {
+            if (settled)
+                return;
+            settled = true;
+            pc.onicegatheringstatechange = null;
+            clearTimeout(timer);
+            resolve();
+        };
+        pc.onicegatheringstatechange = () => {
+            if (pc.iceGatheringState === "complete")
+                finish();
+        };
+        const timer = setTimeout(finish, timeoutMs);
+    });
+}
+function localDescriptionOrThrow(pc) {
+    const description = pc.localDescription;
+    if (description === null)
+        throw new Error("No local description");
+    return description;
+}
+function bindDataChannelPipe(channel, handlers) {
+    if (channel.readyState === "open") {
+        queueMicrotask(() => handlers.onOpen());
+    }
+    else {
+        channel.onopen = () => handlers.onOpen();
+    }
+    channel.onmessage = (event) => {
+        handlers.onMessage(typeof event.data === "string" ? event.data : String(event.data));
+    };
+    channel.onclose = () => handlers.onClose();
+}
+function guestPipeFactory(channel) {
+    let bound = false;
+    return (handlers) => {
+        if (bound) {
+            queueMicrotask(() => handlers.onClose());
+            return { send: () => undefined, close: () => undefined };
+        }
+        bound = true;
+        bindDataChannelPipe(channel, handlers);
+        return {
+            send: (data) => {
+                if (channel.readyState !== "open")
+                    return;
+                channel.send(data);
+            },
+            close: () => channel.close(),
+        };
+    };
+}
+export function createPeerHost(options) {
+    const ownsHost = options.host === undefined;
+    const host = options.host ??
+        createGameHost({
+            runtimes: options.runtimes,
+            persistence: options.persistence ?? memoryPersistence(),
+            tickMs: options.tickMs,
+        });
+    if (ownsHost)
+        host.start();
+    const router = createHostRouter({
+        allowAnonymous: true,
+        ...options.router,
+        host,
+    });
+    const backend = createWsBackend({
+        userId: options.userId,
+        token: options.token,
+        pipe: loopbackPipe(router),
+    });
+    const configuration = options.rtc?.configuration ?? {};
+    const iceGatherTimeoutMs = options.rtc?.iceGatherTimeoutMs ?? DEFAULT_ICE_GATHER_TIMEOUT_MS;
+    const peerConnections = new Set();
+    const accept = async (offerCode) => {
+        const payload = decodePeerSignal(offerCode);
+        if (payload === null)
+            throw new Error("Invalid signal code");
+        const pc = new RTCPeerConnection(configuration);
+        peerConnections.add(pc);
+        pc.ondatachannel = (event) => {
+            const channel = event.channel;
+            const connection = router.connect({
+                send: (data) => {
+                    if (channel.readyState === "open")
+                        channel.send(data);
+                },
+                close: () => channel.close(),
+            });
+            channel.onmessage = (messageEvent) => {
+                connection.handleRaw(typeof messageEvent.data === "string" ? messageEvent.data : String(messageEvent.data));
+            };
+            channel.onclose = () => connection.close();
+        };
+        await pc.setRemoteDescription({ type: payload.type, sdp: payload.sdp });
+        const answer = await pc.createAnswer();
+        await pc.setLocalDescription(answer);
+        await waitForIceGathering(pc, iceGatherTimeoutMs);
+        const description = localDescriptionOrThrow(pc);
+        return encodePeerSignal({ type: "answer", sdp: description.sdp });
+    };
+    return {
+        backend,
+        host,
+        router,
+        accept,
+        close: () => {
+            for (const pc of peerConnections)
+                pc.close();
+            peerConnections.clear();
+            backend.close();
+            router.close();
+            if (ownsHost)
+                void host.stop();
+        },
+    };
+}
+export function createPeerGuest(options) {
+    const configuration = options.rtc?.configuration ?? {};
+    const iceGatherTimeoutMs = options.rtc?.iceGatherTimeoutMs ?? DEFAULT_ICE_GATHER_TIMEOUT_MS;
+    const pc = new RTCPeerConnection(configuration);
+    const channel = pc.createDataChannel("jg");
+    const backend = createWsBackend({
+        userId: options.userId,
+        token: options.token,
+        pipe: guestPipeFactory(channel),
+    });
+    return {
+        backend,
+        offer: async () => {
+            const offerDescription = await pc.createOffer();
+            await pc.setLocalDescription(offerDescription);
+            await waitForIceGathering(pc, iceGatherTimeoutMs);
+            const description = localDescriptionOrThrow(pc);
+            return encodePeerSignal({ type: "offer", sdp: description.sdp });
+        },
+        connect: async (answerCode) => {
+            const payload = decodePeerSignal(answerCode);
+            if (payload === null)
+                throw new Error("Invalid signal code");
+            await pc.setRemoteDescription({ type: payload.type, sdp: payload.sdp });
+        },
+        close: () => {
+            backend.close();
+            pc.close();
+        },
+    };
+}
+function isSignalEnvelope(value) {
+    return (isRecord(value) &&
+        (value.t === "offer" || value.t === "answer") &&
+        typeof value.id === "string" &&
+        typeof value.code === "string");
+}
+export function broadcastChannelSignaling(room) {
+    const channel = new BroadcastChannel(room);
+    const pendingAnswers = new Map();
+    let currentAnswer = null;
+    channel.onmessage = (event) => {
+        const envelope = event.data;
+        if (!isSignalEnvelope(envelope))
+            return;
+        if (envelope.t === "offer") {
+            const answer = currentAnswer;
+            if (answer === null)
+                return;
+            void answer(envelope.code).then((answerCode) => {
+                channel.postMessage({ t: "answer", id: envelope.id, code: answerCode });
+            });
+            return;
+        }
+        const resolve = pendingAnswers.get(envelope.id);
+        if (resolve === undefined)
+            return;
+        pendingAnswers.delete(envelope.id);
+        resolve(envelope.code);
+    };
+    return {
+        publishOffer: (offerCode) => {
+            const id = crypto.randomUUID();
+            return new Promise((resolve) => {
+                pendingAnswers.set(id, resolve);
+                channel.postMessage({ t: "offer", id, code: offerCode });
+            });
+        },
+        onOffer: (answer) => {
+            currentAnswer = answer;
+            return () => {
+                if (currentAnswer === answer)
+                    currentAnswer = null;
+            };
+        },
+        close: () => {
+            pendingAnswers.clear();
+            channel.close();
+        },
+    };
+}
+export function announcePeerHost(host, signaling) {
+    return signaling.onOffer(host.accept);
+}
+export async function joinPeerSession(guest, signaling) {
+    const offerCode = await guest.offer();
+    const answerCode = await signaling.publishOffer(offerCode);
+    await guest.connect(answerCode);
+    return guest.backend;
+}

package/dist/pipe.d.ts

@@ -0,0 +1,11 @@
+export type TransportPipe = {
+    send: (data: string) => void;
+    close: () => void;
+};
+export type TransportPipeHandlers = {
+    onOpen: () => void;
+    onMessage: (data: string) => void;
+    onClose: () => void;
+};
+export type TransportPipeFactory = (handlers: TransportPipeHandlers) => TransportPipe;
+export declare function webSocketPipe(url: string, webSocketFactory?: (url: string) => WebSocket): TransportPipeFactory;

package/dist/pipe.js

@@ -0,0 +1,16 @@
+export function webSocketPipe(url, webSocketFactory = (target) => new WebSocket(target)) {
+    return (handlers) => {
+        const socket = webSocketFactory(url);
+        socket.onopen = () => handlers.onOpen();
+        socket.onmessage = (event) => handlers.onMessage(typeof event.data === "string" ? event.data : String(event.data));
+        socket.onclose = () => handlers.onClose();
+        return {
+            send: (data) => {
+                if (socket.readyState !== 1)
+                    return;
+                socket.send(data);
+            },
+            close: () => socket.close(),
+        };
+    };
+}

package/dist/protocol.d.ts

@@ -1,25 +1,27 @@
-import type { GameRuntimePlayerView, GameRuntimeServerView, JoinServerResult, TransportRunCommandResult } from "@jgengine/core/runtime/transport";
+import type { GameRuntimePlayerView, GameRuntimeServerView, JoinServerResult, PresencePoseRow, TransportRunCommandResult } from "@jgengine/core/runtime/transport";
+import type { PlayerPose } from "@jgengine/core/multiplayer/poseSyncGate";
 import type { SessionAttributes } from "@jgengine/core/runtime/hostPersistence";
 import type { MatchFilter, SessionListing } from "@jgengine/core/multiplayer/matchmaking";
 export declare const WS_PROTOCOL_VERSION = 1;
-export type WsChannel = "server" | "player" | "feed" | "presence";
-export type WsPose = {
-    x: number;
-    y: number;
-    z: number;
-    rotationY: number;
-    rotationPitch: number;
+export type WsChannel = "server" | "player" | "feed" | "presence" | "chat" | "voice";
+/** Client-set cosmetic/state tags carried alongside a pose (skin, mount, emote, ...). Primitive values only. */
+export type WsAppearance = Record<string, string | number | boolean>;
+export type WsPose = PlayerPose & {
+    appearance?: WsAppearance;
 };
-export type WsPresenceRow = {
+export type WsPresenceRow = PresencePoseRow & {
+    appearance?: WsAppearance;
+};
+export type WsChatMessage = {
+    id: string;
+    channelId: string;
+    fromUserId: string;
+    body: string;
+    at: number;
+};
+export type WsVoiceParticipant = {
     userId: string;
-    position: {
-        x: number;
-        y: number;
-        z: number;
-    };
-    rotationY: number;
-    rotationPitch: number;
-    lastSeenAt: number;
+    streamId?: string;
 };
 export type WsClientMessage = {
     v: 1;
@@ -85,6 +87,33 @@ export type WsClientMessage = {
     t: "pose";
     serverId: string;
     pose: WsPose;
+} | {
+    v: 1;
+    t: "chatSend";
+    id: number;
+    serverId: string;
+    channelId: string;
+    body: string;
+} | {
+    v: 1;
+    t: "voiceJoin";
+    id: number;
+    serverId: string;
+    channelId: string;
+    streamId?: string;
+} | {
+    v: 1;
+    t: "voiceLeave";
+    id: number;
+    serverId: string;
+    channelId: string;
+} | {
+    v: 1;
+    t: "voicePublish";
+    id: number;
+    serverId: string;
+    channelId: string;
+    streamId: string;
 };
 export type WsUpdateMessage = {
     v: 1;
@@ -111,6 +140,20 @@ export type WsUpdateMessage = {
     channel: "presence";
     serverId: string;
     data: WsPresenceRow[];
+} | {
+    v: 1;
+    t: "update";
+    channel: "chat";
+    serverId: string;
+    action: string;
+    data: WsChatMessage[];
+} | {
+    v: 1;
+    t: "update";
+    channel: "voice";
+    serverId: string;
+    action: string;
+    data: WsVoiceParticipant[];
 };
 export type WsServerMessage = {
     v: 1;
@@ -130,6 +173,11 @@ export type WsRunCommandResult = TransportRunCommandResult;
 export type WsBrowseResult = SessionListing[];
 export type WsJoinByCodeResult = JoinServerResult | null;
 export declare function encodeWsMessage(message: WsClientMessage | WsServerMessage): string;
+export type WsDecodeFailure = {
+    reason: string;
+    id?: number;
+};
+export declare function inspectWsDecodeFailure(raw: unknown): WsDecodeFailure;
 export declare function decodeWsClientMessage(raw: unknown): WsClientMessage | null;
 export declare function decodeWsServerMessage(raw: unknown): WsServerMessage | null;
 export declare function subscriptionKey(channel: WsChannel, serverId: string, action?: string): string;

package/dist/protocol.js

@@ -24,15 +24,49 @@ function parseVersioned(raw) {
     return parsed;
 }
 function isWsChannel(value) {
-    return value === "server" || value === "player" || value === "feed" || value === "presence";
+    return (value === "server" ||
+        value === "player" ||
+        value === "feed" ||
+        value === "presence" ||
+        value === "chat" ||
+        value === "voice");
+}
+function isAppearance(value) {
+    return (isRecord(value) &&
+        Object.values(value).every((v) => typeof v === "string" || typeof v === "number" || typeof v === "boolean"));
+}
+function isFiniteNumber(value) {
+    return typeof value === "number" && Number.isFinite(value);
 }
 function isPose(value) {
     return (isRecord(value) &&
-        typeof value.x === "number" &&
-        typeof value.y === "number" &&
-        typeof value.z === "number" &&
-        typeof value.rotationY === "number" &&
-        typeof value.rotationPitch === "number");
+        isFiniteNumber(value.x) &&
+        isFiniteNumber(value.y) &&
+        isFiniteNumber(value.z) &&
+        isFiniteNumber(value.rotationY) &&
+        isFiniteNumber(value.rotationPitch) &&
+        (value.appearance === undefined || isAppearance(value.appearance)));
+}
+export function inspectWsDecodeFailure(raw) {
+    if (typeof raw !== "string")
+        return { reason: "Invalid message framing" };
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return { reason: "Invalid JSON" };
+    }
+    if (!isRecord(parsed))
+        return { reason: "Invalid message" };
+    const id = typeof parsed.id === "number" ? parsed.id : undefined;
+    if (parsed.v !== WS_PROTOCOL_VERSION) {
+        return { reason: "Protocol version mismatch", id };
+    }
+    if (typeof parsed.t !== "string") {
+        return { reason: "Invalid message type", id };
+    }
+    return { reason: "Malformed message", id };
 }
 export function decodeWsClientMessage(raw) {
     const message = parseVersioned(raw);
@@ -89,6 +123,33 @@ export function decodeWsClientMessage(raw) {
             return typeof message.serverId === "string" && isPose(message.pose)
                 ? message
                 : null;
+        case "chatSend":
+            return typeof message.id === "number" &&
+                typeof message.serverId === "string" &&
+                typeof message.channelId === "string" &&
+                typeof message.body === "string"
+                ? message
+                : null;
+        case "voiceJoin":
+            return typeof message.id === "number" &&
+                typeof message.serverId === "string" &&
+                typeof message.channelId === "string" &&
+                (message.streamId === undefined || typeof message.streamId === "string")
+                ? message
+                : null;
+        case "voiceLeave":
+            return typeof message.id === "number" &&
+                typeof message.serverId === "string" &&
+                typeof message.channelId === "string"
+                ? message
+                : null;
+        case "voicePublish":
+            return typeof message.id === "number" &&
+                typeof message.serverId === "string" &&
+                typeof message.channelId === "string" &&
+                typeof message.streamId === "string"
+                ? message
+                : null;
         default:
             return null;
     }

package/dist/readsHandler.d.ts

@@ -0,0 +1,15 @@
+import type { HostPersistence, ServerListing } from "@jgengine/core/runtime/hostPersistence";
+export type ReadsPersistence = Pick<HostPersistence, "listServers" | "loadProfile" | "getLeaderboardTop" | "getLeaderboardProfile">;
+export type ReadsHandler = (request: Request) => Promise<Response>;
+export type ReadsAuthenticate = (request: Request) => Promise<string | null> | string | null;
+export type ReadsHandlerOptions = {
+    persistence: ReadsPersistence | (() => Promise<ReadsPersistence>);
+    basePath?: string;
+    listOpenServers?: (args: {
+        gameId: string;
+        limit?: number;
+    }) => Promise<ServerListing[]>;
+    authenticate?: ReadsAuthenticate;
+    allowPublicProfiles?: boolean;
+};
+export declare function createReadsHandler(options: ReadsHandlerOptions): ReadsHandler;

package/dist/readsHandler.js

@@ -0,0 +1,84 @@
+import { toOpenServerListings, toServerListing } from "@jgengine/core/runtime/hostPersistence";
+function isScope(value) {
+    return value === "global" || value === "server" || value === "profile";
+}
+function json(body, status = 200) {
+    return Response.json(body, { status });
+}
+export function createReadsHandler(options) {
+    const basePath = (options.basePath ?? "/api").replace(/\/$/, "");
+    const allowPublicProfiles = options.allowPublicProfiles === true;
+    let persistence = null;
+    const getPersistence = () => {
+        persistence ??=
+            typeof options.persistence === "function" ? options.persistence() : Promise.resolve(options.persistence);
+        return persistence;
+    };
+    return async (request) => {
+        const url = new URL(request.url);
+        if (url.pathname !== basePath && !url.pathname.startsWith(`${basePath}/`)) {
+            return json({ error: "not found" }, 404);
+        }
+        if (request.method !== "GET") {
+            return json({ error: "method not allowed" }, 405);
+        }
+        let segments;
+        try {
+            segments = url.pathname.slice(basePath.length).split("/").filter(Boolean).map(decodeURIComponent);
+        }
+        catch {
+            return json({ error: "malformed path" }, 400);
+        }
+        const gameId = url.searchParams.get("gameId") ?? "";
+        const limitParam = url.searchParams.get("limit");
+        if (limitParam !== null && !Number.isFinite(Number(limitParam))) {
+            return json({ error: "limit must be a number" }, 400);
+        }
+        const limit = limitParam === null ? undefined : Number(limitParam);
+        const [head, tail] = segments;
+        if (head === "servers" && tail === undefined) {
+            if (options.listOpenServers !== undefined) {
+                return json(await options.listOpenServers({ gameId, limit }));
+            }
+            const records = await (await getPersistence()).listServers(gameId);
+            return json(toOpenServerListings(records.map((record) => toServerListing(record)), limit));
+        }
+        if (head === "leaderboard" && tail !== undefined && segments.length === 2) {
+            const scope = url.searchParams.get("scope") ?? "global";
+            if (!isScope(scope)) {
+                return json({ error: "scope must be global | server | profile" }, 400);
+            }
+            return json(await (await getPersistence()).getLeaderboardTop({
+                gameId,
+                stat: tail,
+                scope,
+                serverId: url.searchParams.get("serverId") ?? undefined,
+                limit,
+            }));
+        }
+        if (head === "leaderboard-profile" && tail !== undefined && segments.length === 2) {
+            return json(await (await getPersistence()).getLeaderboardProfile({ gameId, userId: tail }));
+        }
+        if (head === "profile" && tail !== undefined && segments.length === 2) {
+            if (!allowPublicProfiles) {
+                if (options.authenticate === undefined) {
+                    return json({ error: "unauthorized" }, 401);
+                }
+                const actorUserId = await options.authenticate(request);
+                if (actorUserId === null || actorUserId !== tail) {
+                    return json({ error: "unauthorized" }, 401);
+                }
+            }
+            const profile = await (await getPersistence()).loadProfile({ userId: tail, gameId });
+            return json(profile === null
+                ? null
+                : {
+                    userId: profile.userId,
+                    gameId: profile.gameId,
+                    playerState: profile.playerState,
+                    updatedAt: profile.updatedAt,
+                });
+        }
+        return json({ error: "not found" }, 404);
+    };
+}

package/dist/socketIoPipe.d.ts

@@ -0,0 +1,14 @@
+import { type WsBackend, type WsBackendOptions } from "./createWsBackend.js";
+import type { TransportPipeFactory } from "./pipe.js";
+export type SocketIoLikeSocket = {
+    connected: boolean;
+    on: (event: string, listener: (payload: string) => void) => unknown;
+    off: (event: string, listener: (payload: string) => void) => unknown;
+    send: (data: string) => unknown;
+    disconnect: () => unknown;
+};
+export declare function socketIoPipe(socket: SocketIoLikeSocket): TransportPipeFactory;
+export type SocketIoBackendOptions = Omit<WsBackendOptions, "url" | "pipe" | "webSocketFactory"> & {
+    socket: SocketIoLikeSocket;
+};
+export declare function createSocketIoBackend(options: SocketIoBackendOptions): WsBackend;

package/dist/socketIoPipe.js

@@ -0,0 +1,49 @@
+import { createWsBackend } from "./createWsBackend.js";
+export function socketIoPipe(socket) {
+    return (handlers) => {
+        let closed = false;
+        const onConnect = () => {
+            if (closed)
+                return;
+            handlers.onOpen();
+        };
+        const onMessage = (payload) => {
+            if (closed)
+                return;
+            handlers.onMessage(typeof payload === "string" ? payload : String(payload));
+        };
+        const onDisconnect = () => {
+            if (closed)
+                return;
+            handlers.onClose();
+        };
+        socket.on("connect", onConnect);
+        socket.on("message", onMessage);
+        socket.on("disconnect", onDisconnect);
+        if (socket.connected) {
+            queueMicrotask(() => {
+                if (!closed)
+                    handlers.onOpen();
+            });
+        }
+        return {
+            send: (data) => {
+                if (!socket.connected)
+                    return;
+                socket.send(data);
+            },
+            close: () => {
+                if (closed)
+                    return;
+                closed = true;
+                socket.off("connect", onConnect);
+                socket.off("message", onMessage);
+                socket.off("disconnect", onDisconnect);
+            },
+        };
+    };
+}
+export function createSocketIoBackend(options) {
+    const { socket, ...rest } = options;
+    return createWsBackend({ ...rest, pipe: socketIoPipe(socket) });
+}