@jgengine/ws 0.7.0 → 0.9.0

package/dist/hostRouter.js

@@ -0,0 +1,564 @@
+import { decidePoseSync, spawnPresenceState } from "@jgengine/core/multiplayer/presenceModel";
+import { createPositionHistory } from "@jgengine/core/multiplayer/lagCompensation";
+import { createChatRateLimiter, DEFAULT_CHAT_BODY_LENGTH, DEFAULT_CHAT_HISTORY_LIMIT, DEFAULT_CHAT_RATE_LIMIT, } from "@jgengine/core/game/chat";
+import { decodeWsClientMessage, encodeWsMessage, inspectWsDecodeFailure, subscriptionKey, } from "./protocol.js";
+export const DEFAULT_POSE_RULES = {
+    maxSpeed: 12,
+    maxVerticalOffset: 3,
+    minElapsedSec: 0.05,
+    maxElapsedSec: 0.5,
+    keepAliveRefreshMs: 10_000,
+};
+function appearanceEqual(a, b) {
+    if (a === b)
+        return true;
+    if (a === undefined || b === undefined)
+        return false;
+    const aKeys = Object.keys(a);
+    const bKeys = Object.keys(b);
+    if (aKeys.length !== bKeys.length)
+        return false;
+    return aKeys.every((key) => a[key] === b[key]);
+}
+export function createHostRouter(options) {
+    const host = options.host;
+    const now = options.now ?? Date.now;
+    const poseRules = options.poseRules ?? DEFAULT_POSE_RULES;
+    const allowAnonymous = options.allowAnonymous === true;
+    const singleSession = options.singleSession !== false;
+    const authenticate = options.authenticate ??
+        (allowAnonymous ? ({ userId }) => userId : null);
+    const connections = new Set();
+    const sessionsByUserId = new Map();
+    const presence = new Map();
+    const positionHistoryMs = options.positionHistoryMs ?? 1_000;
+    const histories = new Map();
+    const historyFor = (serverId) => {
+        let history = histories.get(serverId);
+        if (history === undefined) {
+            history = createPositionHistory({ historyMs: positionHistoryMs });
+            histories.set(serverId, history);
+        }
+        return history;
+    };
+    const send = (connection, message) => {
+        connection.transport.send(encodeWsMessage(message));
+    };
+    const reply = (connection, id, result) => {
+        send(connection, { v: 1, t: "reply", id, ok: true, result });
+    };
+    const replyError = (connection, id, reason) => {
+        send(connection, { v: 1, t: "reply", id, ok: false, reason });
+    };
+    const presenceRows = (serverId) => {
+        const rows = presence.get(serverId);
+        if (rows === undefined)
+            return [];
+        return [...rows.entries()].map(([userId, pose]) => ({
+            userId,
+            position: pose.position,
+            rotationY: pose.rotationY,
+            rotationPitch: pose.rotationPitch ?? 0,
+            lastSeenAt: pose.lastSeenAtMs ?? 0,
+            appearance: pose.appearance,
+        }));
+    };
+    const broadcastPresence = (serverId) => {
+        const key = subscriptionKey("presence", serverId);
+        const data = presenceRows(serverId);
+        for (const connection of connections) {
+            if (!connection.subscriptions.has(key))
+                continue;
+            send(connection, { v: 1, t: "update", channel: "presence", serverId, data });
+        }
+    };
+    const chatRings = new Map();
+    const chatLimiter = createChatRateLimiter(options.chatRateLimit ?? DEFAULT_CHAT_RATE_LIMIT);
+    const chatHistoryLimit = options.chatHistoryLimit ?? DEFAULT_CHAT_HISTORY_LIMIT;
+    const chatMaxBodyLength = options.chatMaxBodyLength ?? DEFAULT_CHAT_BODY_LENGTH;
+    let chatCounter = 0;
+    const chatRing = (serverId, channelId) => {
+        const key = `${serverId}|${channelId}`;
+        let ring = chatRings.get(key);
+        if (ring === undefined) {
+            ring = [];
+            chatRings.set(key, ring);
+        }
+        return ring;
+    };
+    const broadcastChat = (serverId, channelId) => {
+        const key = subscriptionKey("chat", serverId, channelId);
+        const data = chatRing(serverId, channelId).slice();
+        for (const connection of connections) {
+            if (!connection.subscriptions.has(key))
+                continue;
+            send(connection, { v: 1, t: "update", channel: "chat", serverId, action: channelId, data });
+        }
+    };
+    const voiceRosters = new Map();
+    const voiceRoster = (serverId, channelId) => {
+        const key = `${serverId}|${channelId}`;
+        let roster = voiceRosters.get(key);
+        if (roster === undefined) {
+            roster = new Map();
+            voiceRosters.set(key, roster);
+        }
+        return roster;
+    };
+    const voiceParticipants = (serverId, channelId) => [...voiceRoster(serverId, channelId).values()].map((participant) => ({ ...participant }));
+    const broadcastVoice = (serverId, channelId) => {
+        const key = subscriptionKey("voice", serverId, channelId);
+        const data = voiceParticipants(serverId, channelId);
+        for (const connection of connections) {
+            if (!connection.subscriptions.has(key))
+                continue;
+            send(connection, { v: 1, t: "update", channel: "voice", serverId, action: channelId, data });
+        }
+    };
+    const dropVoice = (connection) => {
+        if (connection.userId === null)
+            return;
+        for (const [key, roster] of voiceRosters) {
+            if (!roster.delete(connection.userId))
+                continue;
+            if (roster.size === 0)
+                voiceRosters.delete(key);
+            const [serverId, channelId] = key.split("|");
+            broadcastVoice(serverId, channelId);
+        }
+    };
+    const dropVoiceForServer = (userId, serverId) => {
+        const prefix = `${serverId}|`;
+        for (const [key, roster] of voiceRosters) {
+            if (!key.startsWith(prefix))
+                continue;
+            if (!roster.delete(userId))
+                continue;
+            if (roster.size === 0)
+                voiceRosters.delete(key);
+            broadcastVoice(serverId, key.slice(prefix.length));
+        }
+    };
+    const requireMembership = async (connection, id, serverId) => {
+        const userId = connection.userId;
+        if (userId === null) {
+            replyError(connection, id, "Not authenticated");
+            return null;
+        }
+        if (!(await host.isMember({ userId, serverId }))) {
+            replyError(connection, id, "Not a member of this server");
+            return null;
+        }
+        return userId;
+    };
+    const handleChatSend = async (connection, message) => {
+        const userId = await requireMembership(connection, message.id, message.serverId);
+        if (userId === null)
+            return;
+        const body = message.body.trim();
+        if (body.length === 0) {
+            replyError(connection, message.id, "empty message");
+            return;
+        }
+        if (body.length > chatMaxBodyLength) {
+            replyError(connection, message.id, "message too long");
+            return;
+        }
+        const timestamp = now();
+        if (!chatLimiter.allow(`${userId}|${message.serverId}`, timestamp)) {
+            replyError(connection, message.id, "rate limited");
+            return;
+        }
+        chatCounter += 1;
+        const entry = {
+            id: `msg_${chatCounter}`,
+            channelId: message.channelId,
+            fromUserId: userId,
+            body,
+            at: timestamp,
+        };
+        const ring = chatRing(message.serverId, message.channelId);
+        ring.push(entry);
+        if (ring.length > chatHistoryLimit)
+            ring.splice(0, ring.length - chatHistoryLimit);
+        reply(connection, message.id, null);
+        broadcastChat(message.serverId, message.channelId);
+    };
+    const pushSubscription = async (connection, channel, serverId, action) => {
+        if (connection.userId === null)
+            return;
+        if (channel === "server") {
+            const data = await host.getServerView({ userId: connection.userId, serverId });
+            send(connection, { v: 1, t: "update", channel, serverId, data });
+        }
+        else if (channel === "player") {
+            const data = await host.getPlayerView({ userId: connection.userId, serverId });
+            send(connection, { v: 1, t: "update", channel, serverId, data });
+        }
+        else if (channel === "feed") {
+            const data = await host.getFeed({ userId: connection.userId, serverId, action: action ?? "" });
+            send(connection, { v: 1, t: "update", channel, serverId, action: action ?? "", data });
+        }
+        else if (channel === "chat") {
+            const channelId = action ?? "";
+            send(connection, {
+                v: 1,
+                t: "update",
+                channel,
+                serverId,
+                action: channelId,
+                data: chatRing(serverId, channelId).slice(),
+            });
+        }
+        else if (channel === "voice") {
+            const channelId = action ?? "";
+            send(connection, {
+                v: 1,
+                t: "update",
+                channel,
+                serverId,
+                action: channelId,
+                data: voiceParticipants(serverId, channelId),
+            });
+        }
+        else {
+            send(connection, { v: 1, t: "update", channel, serverId, data: presenceRows(serverId) });
+        }
+    };
+    const onHostEvent = (event) => {
+        for (const connection of connections) {
+            if (connection.userId === null)
+                continue;
+            if (event.type === "server") {
+                if (connection.subscriptions.has(subscriptionKey("server", event.serverId))) {
+                    void pushSubscription(connection, "server", event.serverId);
+                }
+            }
+            else if (event.type === "player") {
+                if (connection.userId === event.userId &&
+                    connection.subscriptions.has(subscriptionKey("player", event.serverId))) {
+                    void pushSubscription(connection, "player", event.serverId);
+                }
+            }
+            else {
+                if (connection.subscriptions.has(subscriptionKey("feed", event.serverId, event.action))) {
+                    void pushSubscription(connection, "feed", event.serverId, event.action);
+                }
+            }
+        }
+    };
+    const unsubscribeHost = host.subscribe(onHostEvent);
+    const handlePose = async (connection, serverId, pose) => {
+        if (connection.userId === null)
+            return;
+        if (!(await host.isMember({ userId: connection.userId, serverId })))
+            return;
+        const rows = presence.get(serverId) ?? new Map();
+        presence.set(serverId, rows);
+        const timestamp = now();
+        const hadRow = rows.has(connection.userId);
+        const current = rows.get(connection.userId) ?? spawnPresenceState(undefined, timestamp, poseRules);
+        const decision = decidePoseSync(current, { position: { x: pose.x, y: pose.y, z: pose.z }, rotationY: pose.rotationY, rotationPitch: pose.rotationPitch }, poseRules, timestamp);
+        const appearanceChanged = pose.appearance !== undefined && !appearanceEqual(pose.appearance, current.appearance);
+        if (decision.changed || decision.refreshKeepAlive || appearanceChanged || !hadRow) {
+            rows.set(connection.userId, {
+                position: decision.position,
+                rotationY: decision.rotationY,
+                rotationPitch: decision.rotationPitch,
+                lastSeenAtMs: timestamp,
+                appearance: pose.appearance ?? current.appearance,
+            });
+            historyFor(serverId).record(connection.userId, timestamp, decision.position);
+        }
+        if (decision.changed || appearanceChanged || !hadRow) {
+            broadcastPresence(serverId);
+        }
+    };
+    const dropPresence = (connection) => {
+        if (connection.userId === null)
+            return;
+        for (const [serverId, rows] of presence) {
+            if (rows.delete(connection.userId)) {
+                if (rows.size === 0)
+                    presence.delete(serverId);
+                broadcastPresence(serverId);
+            }
+        }
+    };
+    const dropPresenceForServer = (userId, serverId) => {
+        const rows = presence.get(serverId);
+        if (rows === undefined || !rows.delete(userId))
+            return;
+        if (rows.size === 0)
+            presence.delete(serverId);
+        broadcastPresence(serverId);
+    };
+    const handleMessage = async (connection, message) => {
+        if (message.t === "hello") {
+            if (connection.userId !== null) {
+                replyError(connection, message.id, "Already authenticated");
+                return;
+            }
+            if (authenticate === null) {
+                replyError(connection, message.id, "Not authenticated");
+                connection.transport.close();
+                return;
+            }
+            const userId = await authenticate({ userId: message.userId, token: message.token });
+            if (userId === null) {
+                replyError(connection, message.id, "Not authenticated");
+                connection.transport.close();
+                return;
+            }
+            if (singleSession) {
+                const previous = sessionsByUserId.get(userId);
+                if (previous !== undefined && previous !== connection) {
+                    sessionsByUserId.delete(userId);
+                    previous.userId = null;
+                    previous.transport.close();
+                }
+                sessionsByUserId.set(userId, connection);
+            }
+            connection.userId = userId;
+            reply(connection, message.id, { userId });
+            return;
+        }
+        if (message.t === "pose") {
+            await handlePose(connection, message.serverId, message.pose);
+            return;
+        }
+        if (connection.userId === null) {
+            replyError(connection, message.id, "Not authenticated");
+            return;
+        }
+        const userId = connection.userId;
+        try {
+            switch (message.t) {
+                case "join": {
+                    const result = await host.joinServer({
+                        userId,
+                        gameId: message.gameId,
+                        serverId: message.serverId,
+                        attributes: message.attributes,
+                    });
+                    connection.joinedServers.add(result.serverId);
+                    reply(connection, message.id, result);
+                    return;
+                }
+                case "joinByCode": {
+                    const result = await host.joinByCode({
+                        userId,
+                        gameId: message.gameId,
+                        code: message.code,
+                    });
+                    if (result !== null)
+                        connection.joinedServers.add(result.serverId);
+                    reply(connection, message.id, result);
+                    return;
+                }
+                case "browse": {
+                    const result = await host.browseServers({
+                        gameId: message.gameId,
+                        filter: message.filter,
+                        limit: message.limit,
+                    });
+                    reply(connection, message.id, result);
+                    return;
+                }
+                case "leave": {
+                    await host.leaveServer({ userId, serverId: message.serverId });
+                    connection.joinedServers.delete(message.serverId);
+                    dropPresenceForServer(userId, message.serverId);
+                    dropVoiceForServer(userId, message.serverId);
+                    reply(connection, message.id, null);
+                    return;
+                }
+                case "runCommand": {
+                    const result = await host.runCommand({
+                        userId,
+                        serverId: message.serverId,
+                        command: message.command,
+                        input: message.input,
+                    });
+                    reply(connection, message.id, result);
+                    return;
+                }
+                case "pushFeed": {
+                    await host.pushFeedEntry({
+                        userId,
+                        serverId: message.serverId,
+                        action: message.action,
+                        entry: message.entry,
+                    });
+                    reply(connection, message.id, null);
+                    return;
+                }
+                case "chatSend": {
+                    await handleChatSend(connection, message);
+                    return;
+                }
+                case "voiceJoin": {
+                    if ((await requireMembership(connection, message.id, message.serverId)) === null)
+                        return;
+                    const participant = { userId };
+                    if (message.streamId !== undefined)
+                        participant.streamId = message.streamId;
+                    voiceRoster(message.serverId, message.channelId).set(userId, participant);
+                    reply(connection, message.id, null);
+                    broadcastVoice(message.serverId, message.channelId);
+                    return;
+                }
+                case "voiceLeave": {
+                    if ((await requireMembership(connection, message.id, message.serverId)) === null)
+                        return;
+                    const roster = voiceRoster(message.serverId, message.channelId);
+                    const removed = roster.delete(userId);
+                    reply(connection, message.id, null);
+                    if (removed)
+                        broadcastVoice(message.serverId, message.channelId);
+                    return;
+                }
+                case "voicePublish": {
+                    if ((await requireMembership(connection, message.id, message.serverId)) === null)
+                        return;
+                    const participant = voiceRoster(message.serverId, message.channelId).get(userId);
+                    if (participant === undefined) {
+                        replyError(connection, message.id, "not in this voice channel");
+                        return;
+                    }
+                    participant.streamId = message.streamId;
+                    reply(connection, message.id, null);
+                    broadcastVoice(message.serverId, message.channelId);
+                    return;
+                }
+                case "subscribe": {
+                    if ((message.channel === "chat" ||
+                        message.channel === "voice" ||
+                        message.channel === "presence") &&
+                        !(await host.isMember({ userId, serverId: message.serverId }))) {
+                        replyError(connection, message.id, "Not a member of this server");
+                        return;
+                    }
+                    connection.subscriptions.add(subscriptionKey(message.channel, message.serverId, message.action));
+                    reply(connection, message.id, null);
+                    await pushSubscription(connection, message.channel, message.serverId, message.action);
+                    return;
+                }
+                case "unsubscribe": {
+                    connection.subscriptions.delete(subscriptionKey(message.channel, message.serverId, message.action));
+                    reply(connection, message.id, null);
+                    return;
+                }
+            }
+        }
+        catch (error) {
+            replyError(connection, message.id, error instanceof Error ? error.message : "Internal error");
+        }
+    };
+    const leaveJoinedServers = (connection) => {
+        if (connection.userId === null)
+            return;
+        const userId = connection.userId;
+        const servers = [...connection.joinedServers];
+        connection.joinedServers.clear();
+        for (const serverId of servers) {
+            void host.leaveServer({ userId, serverId }).catch(() => undefined);
+        }
+    };
+    return {
+        connect: (transport) => {
+            const connection = {
+                transport,
+                userId: null,
+                subscriptions: new Set(),
+                joinedServers: new Set(),
+                queue: Promise.resolve(),
+            };
+            connections.add(connection);
+            return {
+                handleRaw: (raw) => {
+                    connection.queue = connection.queue
+                        .then(async () => {
+                        const text = typeof raw === "string" ? raw : String(raw);
+                        const message = decodeWsClientMessage(text);
+                        if (message === null) {
+                            const failure = inspectWsDecodeFailure(text);
+                            if (failure.id !== undefined) {
+                                replyError(connection, failure.id, failure.reason);
+                            }
+                            return;
+                        }
+                        await handleMessage(connection, message);
+                    })
+                        .catch(() => undefined);
+                },
+                close: () => {
+                    if (connection.userId !== null && sessionsByUserId.get(connection.userId) === connection) {
+                        sessionsByUserId.delete(connection.userId);
+                    }
+                    connections.delete(connection);
+                    leaveJoinedServers(connection);
+                    dropPresence(connection);
+                    dropVoice(connection);
+                },
+            };
+        },
+        rewind: ({ serverId, atMs }) => {
+            const history = histories.get(serverId);
+            if (history === undefined)
+                return [];
+            const positions = [];
+            for (const userId of history.entities()) {
+                const sample = history.sampleAt(userId, atMs);
+                if (sample !== null) {
+                    positions.push({ userId, x: sample.x, y: sample.y, z: sample.z });
+                }
+            }
+            return positions;
+        },
+        close: () => {
+            unsubscribeHost();
+            connections.clear();
+        },
+    };
+}
+export function loopbackPipe(router) {
+    return (handlers) => {
+        let open = true;
+        const connection = router.connect({
+            send: (data) => {
+                if (!open)
+                    return;
+                queueMicrotask(() => {
+                    if (open)
+                        handlers.onMessage(data);
+                });
+            },
+            close: () => {
+                if (!open)
+                    return;
+                open = false;
+                connection.close();
+                queueMicrotask(() => handlers.onClose());
+            },
+        });
+        queueMicrotask(() => {
+            if (open)
+                handlers.onOpen();
+        });
+        return {
+            send: (data) => {
+                if (!open)
+                    return;
+                queueMicrotask(() => connection.handleRaw(data));
+            },
+            close: () => {
+                if (!open)
+                    return;
+                open = false;
+                connection.close();
+                queueMicrotask(() => handlers.onClose());
+            },
+        };
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+export * from "./createWsBackend.js";
+export * from "./host.js";
+export * from "./hostRouter.js";
+export * from "./httpReads.js";
+export * from "./peer.js";
+export * from "./pipe.js";
+export * from "./protocol.js";
+export * from "./readsHandler.js";
+export * from "./socketIoPipe.js";
+export * from "./voiceChannel.js";

package/dist/index.js

@@ -0,0 +1,10 @@
+export * from "./createWsBackend.js";
+export * from "./host.js";
+export * from "./hostRouter.js";
+export * from "./httpReads.js";
+export * from "./peer.js";
+export * from "./pipe.js";
+export * from "./protocol.js";
+export * from "./readsHandler.js";
+export * from "./socketIoPipe.js";
+export * from "./voiceChannel.js";

package/dist/peer.d.ts

@@ -0,0 +1,53 @@
+import type { GameRuntime } from "@jgengine/core/runtime/gameRuntime";
+import type { HostPersistence } from "@jgengine/core/runtime/hostPersistence";
+import { type GameHost } from "./host.js";
+import { type HostRouter, type HostRouterOptions } from "./hostRouter.js";
+import { type WsBackend } from "./createWsBackend.js";
+export type PeerSignalPayload = {
+    type: "offer" | "answer";
+    sdp: string;
+};
+export declare function encodePeerSignal(payload: PeerSignalPayload): string;
+export declare function decodePeerSignal(code: string): PeerSignalPayload | null;
+export type PeerRtcOptions = {
+    configuration?: RTCConfiguration;
+    iceGatherTimeoutMs?: number;
+};
+export type PeerHostOptions = {
+    userId: string;
+    token?: string;
+    host?: GameHost;
+    runtimes?: GameRuntime[];
+    persistence?: HostPersistence;
+    tickMs?: number;
+    router?: Omit<HostRouterOptions, "host">;
+    rtc?: PeerRtcOptions;
+};
+export type PeerHost = {
+    backend: WsBackend;
+    host: GameHost;
+    router: HostRouter;
+    accept: (offerCode: string) => Promise<string>;
+    close: () => void;
+};
+export declare function createPeerHost(options: PeerHostOptions): PeerHost;
+export type PeerGuestOptions = {
+    userId: string;
+    token?: string;
+    rtc?: PeerRtcOptions;
+};
+export type PeerGuest = {
+    backend: WsBackend;
+    offer: () => Promise<string>;
+    connect: (answerCode: string) => Promise<void>;
+    close: () => void;
+};
+export declare function createPeerGuest(options: PeerGuestOptions): PeerGuest;
+export type PeerSignaling = {
+    publishOffer: (offerCode: string) => Promise<string>;
+    onOffer: (answer: (offerCode: string) => Promise<string>) => () => void;
+    close: () => void;
+};
+export declare function broadcastChannelSignaling(room: string): PeerSignaling;
+export declare function announcePeerHost(host: PeerHost, signaling: PeerSignaling): () => void;
+export declare function joinPeerSession(guest: PeerGuest, signaling: PeerSignaling): Promise<WsBackend>;