@jgengine/ws 0.8.0 → 0.10.0

package/dist/hostRouter.js

@@ -1,7 +1,7 @@
-import { decidePoseSync } from "@jgengine/core/multiplayer/presenceModel";
+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, subscriptionKey, } from "./protocol.js";
+import { decodeWsClientMessage, encodeWsMessage, inspectWsDecodeFailure, subscriptionKey, } from "./protocol.js";
 export const DEFAULT_POSE_RULES = {
     maxSpeed: 12,
     maxVerticalOffset: 3,
@@ -24,8 +24,12 @@ export function createHostRouter(options) {
     const host = options.host;
     const now = options.now ?? Date.now;
     const poseRules = options.poseRules ?? DEFAULT_POSE_RULES;
-    const authenticate = options.authenticate ?? (({ userId }) => userId);
+    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();
@@ -135,12 +139,22 @@ export function createHostRouter(options) {
             broadcastVoice(serverId, key.slice(prefix.length));
         }
     };
-    const handleChatSend = (connection, message) => {
+    const requireMembership = async (connection, id, serverId) => {
         const userId = connection.userId;
         if (userId === null) {
-            replyError(connection, message.id, "Not authenticated");
-            return;
+            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");
@@ -234,28 +248,19 @@ export function createHostRouter(options) {
         }
     };
     const unsubscribeHost = host.subscribe(onHostEvent);
-    const handlePose = (connection, serverId, pose) => {
+    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 current = rows.get(connection.userId);
-        if (current === undefined) {
-            rows.set(connection.userId, {
-                position: { x: pose.x, y: pose.y, z: pose.z },
-                rotationY: pose.rotationY,
-                rotationPitch: pose.rotationPitch,
-                lastSeenAtMs: timestamp,
-                appearance: pose.appearance,
-            });
-            historyFor(serverId).record(connection.userId, timestamp, { x: pose.x, y: pose.y, z: pose.z });
-            broadcastPresence(serverId);
-            return;
-        }
+        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) {
+        if (decision.changed || decision.refreshKeepAlive || appearanceChanged || !hadRow) {
             rows.set(connection.userId, {
                 position: decision.position,
                 rotationY: decision.rotationY,
@@ -265,8 +270,9 @@ export function createHostRouter(options) {
             });
             historyFor(serverId).record(connection.userId, timestamp, decision.position);
         }
-        if (decision.changed || appearanceChanged)
+        if (decision.changed || appearanceChanged || !hadRow) {
             broadcastPresence(serverId);
+        }
     };
     const dropPresence = (connection) => {
         if (connection.userId === null)
@@ -289,18 +295,36 @@ export function createHostRouter(options) {
     };
     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") {
-            handlePose(connection, message.serverId, message.pose);
+            await handlePose(connection, message.serverId, message.pose);
             return;
         }
         if (connection.userId === null) {
@@ -317,6 +341,7 @@ export function createHostRouter(options) {
                         serverId: message.serverId,
                         attributes: message.attributes,
                     });
+                    connection.joinedServers.add(result.serverId);
                     reply(connection, message.id, result);
                     return;
                 }
@@ -326,6 +351,8 @@ export function createHostRouter(options) {
                         gameId: message.gameId,
                         code: message.code,
                     });
+                    if (result !== null)
+                        connection.joinedServers.add(result.serverId);
                     reply(connection, message.id, result);
                     return;
                 }
@@ -340,6 +367,7 @@ export function createHostRouter(options) {
                 }
                 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);
@@ -366,10 +394,12 @@ export function createHostRouter(options) {
                     return;
                 }
                 case "chatSend": {
-                    handleChatSend(connection, message);
+                    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;
@@ -379,6 +409,8 @@ export function createHostRouter(options) {
                     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);
@@ -387,6 +419,8 @@ export function createHostRouter(options) {
                     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");
@@ -398,6 +432,13 @@ export function createHostRouter(options) {
                     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);
@@ -414,19 +455,49 @@ export function createHostRouter(options) {
             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() };
+            const connection = {
+                transport,
+                userId: null,
+                subscriptions: new Set(),
+                joinedServers: new Set(),
+                queue: Promise.resolve(),
+            };
             connections.add(connection);
             return {
                 handleRaw: (raw) => {
-                    const message = decodeWsClientMessage(typeof raw === "string" ? raw : String(raw));
-                    if (message === null)
-                        return;
-                    void handleMessage(connection, message);
+                    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);
                 },

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+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";
+export * from "./worldHost.js";

package/dist/index.js

@@ -0,0 +1,11 @@
+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";
+export * from "./worldHost.js";

package/dist/peer.js

@@ -93,7 +93,11 @@ export function createPeerHost(options) {
         });
     if (ownsHost)
         host.start();
-    const router = createHostRouter({ ...options.router, host });
+    const router = createHostRouter({
+        allowAnonymous: true,
+        ...options.router,
+        host,
+    });
     const backend = createWsBackend({
         userId: options.userId,
         token: options.token,

package/dist/protocol.d.ts

@@ -173,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

@@ -35,15 +35,39 @@ 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);
     if (message === null)

package/dist/readsHandler.d.ts

@@ -1,6 +1,7 @@
 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;
@@ -8,5 +9,7 @@ export type ReadsHandlerOptions = {
         gameId: string;
         limit?: number;
     }) => Promise<ServerListing[]>;
+    authenticate?: ReadsAuthenticate;
+    allowPublicProfiles?: boolean;
 };
 export declare function createReadsHandler(options: ReadsHandlerOptions): ReadsHandler;

package/dist/readsHandler.js

@@ -7,6 +7,7 @@ function json(body, status = 200) {
 }
 export function createReadsHandler(options) {
     const basePath = (options.basePath ?? "/api").replace(/\/$/, "");
+    const allowPublicProfiles = options.allowPublicProfiles === true;
     let persistence = null;
     const getPersistence = () => {
         persistence ??=
@@ -21,9 +22,18 @@ export function createReadsHandler(options) {
         if (request.method !== "GET") {
             return json({ error: "method not allowed" }, 405);
         }
-        const segments = url.pathname.slice(basePath.length).split("/").filter(Boolean).map(decodeURIComponent);
+        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) {
@@ -31,7 +41,7 @@ export function createReadsHandler(options) {
                 return json(await options.listOpenServers({ gameId, limit }));
             }
             const records = await (await getPersistence()).listServers(gameId);
-            return json(toOpenServerListings(records.map(toServerListing), limit));
+            return json(toOpenServerListings(records.map((record) => toServerListing(record)), limit));
         }
         if (head === "leaderboard" && tail !== undefined && segments.length === 2) {
             const scope = url.searchParams.get("scope") ?? "global";
@@ -50,6 +60,15 @@ export function createReadsHandler(options) {
             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

package/dist/worldHost.d.ts

@@ -0,0 +1,26 @@
+import type { HostedWorldSession } from "@jgengine/core/runtime/hostedWorldSession";
+import type { GameHost } from "./host.js";
+/** Config for {@link createWorldGameHost}: how to resolve a hosted world's authoritative session per server. */
+export interface WorldGameHostOptions {
+    /**
+     * Resolve (or lazily build) the authoritative {@link HostedWorldSession} for a server — called once per new
+     * `serverId`. Return `null` for an unknown game. Bind the game's definition + content here.
+     */
+    session(args: {
+        gameId: string;
+        serverId: string;
+    }): HostedWorldSession | null;
+    now?: () => number;
+}
+/** A {@link GameHost} whose worlds run on `HostedWorldSession`s; `tick` advances them and re-broadcasts on change. */
+export interface WorldGameHost extends GameHost {
+    /** Advance every live world by `dtSeconds` and emit a `server` change for each whose revision moved. */
+    tick(dtSeconds: number): void;
+}
+/**
+ * The GameContext-loop counterpart of the reducer `createGameHost`: a structural {@link GameHost} that serves each
+ * world's full `WorldSnapshot` as `serverState`, so the existing ws router, `createWsBackend`, and the shell's
+ * `attachWorldSync` carry host-authoritative GameContext worlds with zero changes to any of them. The harness owns
+ * the tick cadence (call {@link WorldGameHost.tick} on an interval); commands and joins broadcast immediately.
+ */
+export declare function createWorldGameHost(options: WorldGameHostOptions): WorldGameHost;

package/dist/worldHost.js

@@ -0,0 +1,119 @@
+import { INPUT_COMMAND } from "@jgengine/core/runtime/hostedGameRunner";
+/**
+ * The GameContext-loop counterpart of the reducer `createGameHost`: a structural {@link GameHost} that serves each
+ * world's full `WorldSnapshot` as `serverState`, so the existing ws router, `createWsBackend`, and the shell's
+ * `attachWorldSync` carry host-authoritative GameContext worlds with zero changes to any of them. The harness owns
+ * the tick cadence (call {@link WorldGameHost.tick} on an interval); commands and joins broadcast immediately.
+ */
+export function createWorldGameHost(options) {
+    const live = new Map();
+    const listeners = new Set();
+    const now = options.now ?? (() => Date.now());
+    function emit(event) {
+        for (const listener of listeners)
+            listener(event);
+    }
+    function ensure(gameId, serverId) {
+        const existing = live.get(serverId);
+        if (existing !== undefined)
+            return existing;
+        const session = options.session({ gameId, serverId });
+        if (session === null)
+            return null;
+        const entry = { gameId, session };
+        live.set(serverId, entry);
+        return entry;
+    }
+    function tickAll(dtSeconds) {
+        for (const [serverId, entry] of live) {
+            const before = entry.session.revision();
+            entry.session.tick(dtSeconds);
+            if (entry.session.revision() !== before)
+                emit({ type: "server", serverId });
+        }
+    }
+    return {
+        async joinServer({ userId, gameId, serverId }) {
+            const id = serverId ?? gameId;
+            const entry = ensure(gameId, id);
+            if (entry === null)
+                throw new Error(`no hosted world for game "${gameId}"`);
+            const isNew = !entry.session.members().includes(userId);
+            entry.session.join(userId, isNew);
+            emit({ type: "server", serverId: id });
+            emit({ type: "player", serverId: id, userId });
+            return { serverId: id, isNew };
+        },
+        async leaveServer({ userId, serverId }) {
+            const entry = live.get(serverId);
+            if (entry === undefined)
+                return;
+            entry.session.leave(userId);
+            emit({ type: "server", serverId });
+        },
+        async runCommand({ userId, serverId, command, input }) {
+            const entry = live.get(serverId);
+            if (entry === undefined)
+                return { ok: false, reason: "no-server" };
+            if (command === INPUT_COMMAND) {
+                entry.session.input(userId, input);
+                return { ok: true };
+            }
+            const before = entry.session.revision();
+            const result = entry.session.command(userId, command, input);
+            if (result.status === "rejected")
+                return { ok: false, reason: result.reason };
+            if (result.status === "unknown-command")
+                return { ok: false, reason: "unknown-command" };
+            if (entry.session.revision() !== before)
+                emit({ type: "server", serverId });
+            return { ok: true };
+        },
+        async isMember({ userId, serverId }) {
+            return live.get(serverId)?.session.members().includes(userId) ?? false;
+        },
+        async getServerView({ serverId }) {
+            const entry = live.get(serverId);
+            if (entry === undefined)
+                return null;
+            return {
+                serverId,
+                gameId: entry.gameId,
+                revision: entry.session.revision(),
+                memberUserIds: [...entry.session.members()],
+                serverState: entry.session.runner().snapshot(),
+                updatedAt: now(),
+            };
+        },
+        async getPlayerView() {
+            return null;
+        },
+        async getFeed() {
+            return [];
+        },
+        async pushFeedEntry() { },
+        async browseServers() {
+            return [];
+        },
+        async joinByCode() {
+            return null;
+        },
+        async listOpenServers() {
+            return [];
+        },
+        tick: tickAll,
+        async tickOnce() {
+            tickAll(0);
+            return { ticked: live.size, saved: 0 };
+        },
+        async flushAll() {
+            return 0;
+        },
+        start() { },
+        async stop() { },
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => listeners.delete(listener);
+        },
+    };
+}