@jgengine/ws 0.9.0 → 0.11.0

package/README.md

@@ -1,3 +1,3 @@
 # @jgengine/ws
 
-Browser-safe WebSocket client backend for [JGengine](https://github.com/Noisemaker111/jgengine): protocol codec, `createWsBackend`, `createHttpReads`. AGPL-3.0-only.
+Browser-safe WebSocket client backend for [JGengine](https://github.com/Noisemaker111/jgengine): protocol codec, `createWsBackend`, `createHttpReads`. Apache-2.0.

package/dist/commandMiddleware.d.ts

@@ -0,0 +1,62 @@
+import type { CommandRejection } from "@jgengine/core/commands/commandRegistry";
+/** A host-side op the command middleware pipeline can gate: pose sync, `runCommand`, join/joinByCode, browse, or voice join/leave/publish. */
+export type HostCommandOp = "pose" | "runCommand" | "join" | "browse" | "voice";
+/** A sliding-window rate limit: at most `count` calls per `perMs` window. */
+export type CommandRateLimit = {
+    count: number;
+    perMs: number;
+};
+/** Per-op rate limits. An op with no entry (or an undefined `limits`) is unlimited. */
+export type CommandLimits = Partial<Record<HostCommandOp, CommandRateLimit>>;
+/** Recommended per-op limits a host can opt into via `limits: DEFAULT_COMMAND_LIMITS`. Rate limiting is off unless `limits` is set. */
+export declare const DEFAULT_COMMAND_LIMITS: CommandLimits;
+/** A declared `runCommand` name's input validator, run before the command reaches the game host. */
+export type CommandCatalogEntry = {
+    validate?: (input: unknown) => CommandRejection | null;
+};
+/** Declared `runCommand` names and their input validators. When set, any `runCommand` name absent from this catalog is rejected as unknown. */
+export type CommandCatalog = Record<string, CommandCatalogEntry>;
+/** Per-command authorization hook: return `false` to reject. Defaults to allow-all when omitted. */
+export type CommandAuthorize = (args: {
+    userId: string;
+    op: HostCommandOp;
+    serverId?: string;
+    command?: string;
+}) => boolean | Promise<boolean>;
+/** A composable per-connection/per-op sliding-window rate limiter. */
+export type CommandRateLimiter = {
+    allow: (connection: object, op: HostCommandOp, atMs: number) => boolean;
+};
+/** Creates a sliding-window rate limiter keyed by connection identity and op; ops absent from `limits` are always allowed. */
+export declare function createCommandRateLimiter(limits: CommandLimits): CommandRateLimiter;
+/** Validates a `runCommand` input against a declared catalog. `undefined` catalog means "no declarations" — everything passes through unchanged. */
+export declare function validateCommandInput(catalog: CommandCatalog | undefined, command: string, input: unknown): CommandRejection | null;
+/** Config for {@link createCommandMiddleware}: the same `limits`/`authorize`/`validate` fields accepted by `HostRouterOptions`. */
+export type CommandMiddlewareOptions = {
+    limits?: CommandLimits;
+    authorize?: CommandAuthorize;
+    validate?: CommandCatalog;
+};
+/** One op attempt to run through the middleware pipeline: which connection, which op, and (for `runCommand`) the command name/input. */
+export type CommandGateArgs = {
+    connection: object;
+    userId: string;
+    op: HostCommandOp;
+    atMs: number;
+    serverId?: string;
+    command?: string;
+    input?: unknown;
+};
+/** The pipeline's verdict for one {@link CommandGateArgs}: allowed, or rejected with a client-facing reason. */
+export type CommandGateDecision = {
+    allow: true;
+} | {
+    allow: false;
+    reason: string;
+};
+/** A composable rate-limit → validate → authorize pipeline the host router runs before dispatching pose/runCommand/join/browse/voice ops. Every stage defaults to a no-op, so an unconfigured router behaves exactly as before. */
+export type CommandMiddleware = {
+    check: (args: CommandGateArgs) => Promise<CommandGateDecision>;
+};
+/** Builds the composed command middleware pipeline from game-intent config: `limits`, `validate`, `authorize`. */
+export declare function createCommandMiddleware(options: CommandMiddlewareOptions): CommandMiddleware;

package/dist/commandMiddleware.js

@@ -0,0 +1,66 @@
+/** Recommended per-op limits a host can opt into via `limits: DEFAULT_COMMAND_LIMITS`. Rate limiting is off unless `limits` is set. */
+export const DEFAULT_COMMAND_LIMITS = {
+    pose: { count: 60, perMs: 1_000 },
+    runCommand: { count: 30, perMs: 1_000 },
+    join: { count: 5, perMs: 10_000 },
+    browse: { count: 10, perMs: 5_000 },
+    voice: { count: 20, perMs: 1_000 },
+};
+/** Creates a sliding-window rate limiter keyed by connection identity and op; ops absent from `limits` are always allowed. */
+export function createCommandRateLimiter(limits) {
+    const windows = new WeakMap();
+    return {
+        allow(connection, op, atMs) {
+            const limit = limits[op];
+            if (limit === undefined)
+                return true;
+            let perOp = windows.get(connection);
+            if (perOp === undefined) {
+                perOp = new Map();
+                windows.set(connection, perOp);
+            }
+            const cutoff = atMs - limit.perMs;
+            const stamps = (perOp.get(op) ?? []).filter((stamp) => stamp > cutoff);
+            if (stamps.length >= limit.count) {
+                perOp.set(op, stamps);
+                return false;
+            }
+            stamps.push(atMs);
+            perOp.set(op, stamps);
+            return true;
+        },
+    };
+}
+/** Validates a `runCommand` input against a declared catalog. `undefined` catalog means "no declarations" — everything passes through unchanged. */
+export function validateCommandInput(catalog, command, input) {
+    if (catalog === undefined)
+        return null;
+    const declared = catalog[command];
+    if (declared === undefined)
+        return { reason: `Unknown command: ${command}` };
+    return declared.validate?.(input) ?? null;
+}
+/** Builds the composed command middleware pipeline from game-intent config: `limits`, `validate`, `authorize`. */
+export function createCommandMiddleware(options) {
+    const limiter = createCommandRateLimiter(options.limits ?? {});
+    const catalog = options.validate;
+    const authorize = options.authorize;
+    return {
+        async check({ connection, userId, op, atMs, serverId, command, input }) {
+            if (!limiter.allow(connection, op, atMs)) {
+                return { allow: false, reason: `Rate limited: ${op}` };
+            }
+            if (op === "runCommand" && command !== undefined) {
+                const rejection = validateCommandInput(catalog, command, input);
+                if (rejection !== null)
+                    return { allow: false, reason: rejection.reason };
+            }
+            if (authorize !== undefined) {
+                const authorized = await authorize({ userId, op, serverId, command });
+                if (!authorized)
+                    return { allow: false, reason: `Not authorized: ${op}` };
+            }
+            return { allow: true };
+        },
+    };
+}

package/dist/createWsBackend.js

@@ -11,6 +11,16 @@ const DEFAULT_POSE_TUNING = {
 const DEFAULT_RPC_TIMEOUT_MS = 15_000;
 const DEFAULT_RECONNECT_DELAY_MS = 1_000;
 const DEFAULT_MAX_RECONNECT_DELAY_MS = 30_000;
+const WS_OP_ID_FIELD = "__jgWsOpId";
+const RESERVED_INPUT_COMMAND = "engine.input";
+function isPlainRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function stampOpId(command, opId, input) {
+    if (command === RESERVED_INPUT_COMMAND || !isPlainRecord(input))
+        return input;
+    return { ...input, [WS_OP_ID_FIELD]: opId };
+}
 export function createWsBackend(options) {
     const now = options.now ?? Date.now;
     const baseReconnectDelayMs = options.reconnectDelayMs ?? DEFAULT_RECONNECT_DELAY_MS;
@@ -31,6 +41,7 @@ export function createWsBackend(options) {
     let closed = false;
     let wantConnection = false;
     let nextId = 1;
+    let nextOpId = 1;
     let reconnectAttempt = 0;
     let reconnectTimer = null;
     const pending = new Map();
@@ -273,6 +284,7 @@ export function createWsBackend(options) {
             await request((id) => ({ v: 1, t: "leave", id, serverId: args.serverId }));
         },
         async runCommand(args) {
+            const opId = String(nextOpId++);
             try {
                 const result = await request((id) => ({
                     v: 1,
@@ -280,7 +292,7 @@ export function createWsBackend(options) {
                     id,
                     serverId: args.serverId,
                     command: args.command,
-                    input: args.input,
+                    input: stampOpId(args.command, opId, args.input),
                 }));
                 return result;
             }

package/dist/host.d.ts

@@ -2,6 +2,7 @@ import type { GameRuntime } from "@jgengine/core/runtime/gameRuntime";
 import type { HostPersistence, ServerListing, SessionAttributes } from "@jgengine/core/runtime/hostPersistence";
 import type { MatchFilter, SessionListing } from "@jgengine/core/multiplayer/matchmaking";
 import type { GameRuntimePlayerView, GameRuntimeServerView, JoinServerResult, TransportRunCommandResult } from "@jgengine/core/runtime/transport";
+/** A change notification emitted by a `GameHost` for a server, player, or feed mutation. */
 export type HostChangeEvent = {
     type: "server";
     serverId: string;
@@ -14,6 +15,7 @@ export type HostChangeEvent = {
     serverId: string;
     action: string;
 };
+/** Configuration for {@link createGameHost}, including persistence, tick rate, and game runtimes. */
 export type GameHostOptions = {
     runtimes?: GameRuntime[];
     persistence: HostPersistence;
@@ -23,12 +25,14 @@ export type GameHostOptions = {
     createServerId?: () => string;
     allowedFeedActions?: readonly string[];
 };
+/** A transport-agnostic authoritative game server host that manages sessions, ticking, and persistence. */
 export type GameHost = {
     joinServer: (args: {
         userId: string;
         gameId: string;
         serverId?: string;
         attributes?: SessionAttributes;
+        code?: string;
     }) => Promise<JoinServerResult>;
     browseServers: (args: {
         gameId: string;
@@ -86,5 +90,9 @@ export type GameHost = {
     stop: () => Promise<void>;
     subscribe: (listener: (event: HostChangeEvent) => void) => () => void;
 };
+/** Max recently-applied `runCommand` op IDs retained per (serverId, userId), oldest evicted first. */
+export declare const OP_LEDGER_LIMIT = 64;
+/** Creates a `GameHost` that runs game servers over the given persistence and runtimes. */
 export declare function createGameHost(options: GameHostOptions): GameHost;
+/** Creates an in-memory `HostPersistence` implementation, useful for tests and ephemeral hosts. */
 export declare function memoryPersistence(now?: () => number): HostPersistence;

package/dist/host.js

@@ -1,6 +1,6 @@
 import { createGameRuntime } from "@jgengine/core/runtime/gameRuntime";
 import { applyLeaderboardRows, buildHydratePlayers, planServerPersist, profileLeaderboardStats, shouldAutoSave, topLeaderboardRows, toOpenServerListings, toServerListing, trimFeedEntries, } from "@jgengine/core/runtime/hostPersistence";
-import { browseSessions, findByJoinCode } from "@jgengine/core/multiplayer/matchmaking";
+import { browseSessions, findByJoinCode, normalizeJoinCode } from "@jgengine/core/multiplayer/matchmaking";
 import { createFeedWriteGate, validateFeedWrite, } from "@jgengine/core/multiplayer/feedWriteGate";
 import { clearDirtyFlags, createEmptyServerRow, splitProfilePlayer } from "@jgengine/core/runtime/snapshot";
 const builtinCommands = {
@@ -9,6 +9,23 @@ const builtinCommands = {
         apply: (snapshot) => snapshot,
     },
 };
+/** Max recently-applied `runCommand` op IDs retained per (serverId, userId), oldest evicted first. */
+export const OP_LEDGER_LIMIT = 64;
+const WS_OP_ID_FIELD = "__jgWsOpId";
+function unwrapOpEnvelope(input) {
+    if (typeof input !== "object" || input === null || Array.isArray(input))
+        return null;
+    const record = input;
+    const opId = record[WS_OP_ID_FIELD];
+    if (typeof opId !== "string")
+        return null;
+    const { [WS_OP_ID_FIELD]: _opId, ...rest } = record;
+    return { opId, input: rest };
+}
+function opLedgerKey(serverId, userId) {
+    return `${serverId}|${userId}`;
+}
+/** Creates a `GameHost` that runs game servers over the given persistence and runtimes. */
 export function createGameHost(options) {
     const now = options.now ?? Date.now;
     const tickMs = options.tickMs ?? 1_000;
@@ -34,10 +51,30 @@ export function createGameHost(options) {
         for (const listener of listeners)
             listener(event);
     };
-    let queue = Promise.resolve();
-    const enqueue = (operation) => {
-        const run = queue.then(operation);
-        queue = run.catch(() => undefined);
+    const opLedgers = new Map();
+    const findAppliedOp = (serverId, userId, opId) => opLedgers.get(opLedgerKey(serverId, userId))?.find((entry) => entry.opId === opId)?.result;
+    const rememberAppliedOp = (serverId, userId, opId, result) => {
+        const key = opLedgerKey(serverId, userId);
+        const entries = opLedgers.get(key) ?? [];
+        entries.push({ opId, result });
+        if (entries.length > OP_LEDGER_LIMIT)
+            entries.shift();
+        opLedgers.set(key, entries);
+    };
+    const forgetOpLedger = (serverId, userId) => {
+        opLedgers.delete(opLedgerKey(serverId, userId));
+    };
+    const roomQueues = new Map();
+    const enqueueRoom = (roomId, operation) => {
+        const previous = roomQueues.get(roomId) ?? Promise.resolve();
+        const run = previous.then(operation);
+        const settled = run.catch(() => undefined);
+        roomQueues.set(roomId, settled);
+        void settled.finally(() => {
+            if (roomQueues.get(roomId) === settled) {
+                roomQueues.delete(roomId);
+            }
+        });
         return run;
     };
     const hydrate = async (record) => {
@@ -110,34 +147,39 @@ export function createGameHost(options) {
         };
     };
     let interval = null;
-    const tickOnce = () => enqueue(async () => {
+    const tickOnce = async () => {
         const timestamp = now();
-        let ticked = 0;
-        let saved = 0;
-        for (const entry of live.values()) {
+        const outcomes = await Promise.all([...live.values()].map((entry) => enqueueRoom(entry.record.serverId, async () => {
             if (entry.record.status !== "running")
-                continue;
+                return { ticked: 0, saved: 0 };
             if (entry.record.memberUserIds.length === 0)
-                continue;
+                return { ticked: 0, saved: 0 };
             const elapsedMs = timestamp - entry.record.tickAnchorMs;
             if (elapsedMs < tickMs)
-                continue;
+                return { ticked: 0, saved: 0 };
             const runtime = resolveRuntime(entry.record.gameId);
             const before = entry.snapshot.revision;
             entry.snapshot = runtime.tick(entry.snapshot, elapsedMs / 1_000);
             entry.record = { ...entry.record, tickAnchorMs: timestamp, updatedAt: timestamp };
-            ticked += 1;
             if (entry.snapshot.revision !== before) {
                 markMutated(entry);
                 emit({ type: "server", serverId: entry.record.serverId });
             }
+            let saved = 0;
             if (shouldAutoSave(entry.record.save, entry.record.dirtyAt, entry.record.lastSavedAt, timestamp)) {
                 await flushServer(entry);
-                saved += 1;
+                saved = 1;
             }
+            return { ticked: 1, saved };
+        })));
+        let ticked = 0;
+        let saved = 0;
+        for (const outcome of outcomes) {
+            ticked += outcome.ticked;
+            saved += outcome.saved;
         }
         return { ticked, saved };
-    });
+    };
     const collectListings = async (gameId, options = {}) => {
         const byId = new Map();
         for (const record of await persistence.listServers(gameId)) {
@@ -165,69 +207,88 @@ export function createGameHost(options) {
         }));
     };
     const host = {
-        joinServer: (args) => enqueue(async () => {
-            const timestamp = now();
-            const runtime = resolveRuntime(args.gameId);
-            let entry = args.serverId === undefined ? null : await getLive(args.serverId);
-            if (args.serverId !== undefined && entry === null) {
-                throw new Error("Server not found");
-            }
-            if (entry !== null && entry.record.gameId !== args.gameId) {
-                throw new Error("Server belongs to a different game");
-            }
-            if (entry === null) {
-                const attributes = args.attributes;
-                const record = {
-                    serverId: createServerId(),
-                    gameId: args.gameId,
+        joinServer: (args) => {
+            const joinOperation = async () => {
+                const timestamp = now();
+                const runtime = resolveRuntime(args.gameId);
+                let entry = args.serverId === undefined ? null : await getLive(args.serverId);
+                if (args.serverId !== undefined && entry === null) {
+                    throw new Error("Server not found");
+                }
+                if (entry !== null && entry.record.gameId !== args.gameId) {
+                    throw new Error("Server belongs to a different game");
+                }
+                if (entry !== null &&
+                    entry.record.visibility === "private" &&
+                    !entry.record.memberUserIds.includes(args.userId)) {
+                    const requiredCode = entry.record.joinCode;
+                    const matches = requiredCode !== undefined &&
+                        args.code !== undefined &&
+                        normalizeJoinCode(args.code) === normalizeJoinCode(requiredCode);
+                    if (!matches) {
+                        throw new Error("Server is private");
+                    }
+                }
+                if (entry === null) {
+                    const attributes = args.attributes;
+                    const record = {
+                        serverId: createServerId(),
+                        gameId: args.gameId,
+                        status: "running",
+                        memberUserIds: [],
+                        slotsPerServer: defaultSlots,
+                        save: runtime.save,
+                        serverState: createEmptyServerRow(),
+                        sessionPlayers: {},
+                        revision: 0,
+                        tickAnchorMs: timestamp,
+                        createdAt: timestamp,
+                        updatedAt: timestamp,
+                        ...(attributes?.label !== undefined ? { label: attributes.label } : {}),
+                        ...(attributes?.mode !== undefined ? { mode: attributes.mode } : {}),
+                        ...(attributes?.visibility !== undefined ? { visibility: attributes.visibility } : {}),
+                        ...(attributes?.joinCode !== undefined ? { joinCode: attributes.joinCode } : {}),
+                        ...(attributes?.tags !== undefined ? { tags: attributes.tags } : {}),
+                    };
+                    entry = await hydrate(record);
+                }
+                const { record } = entry;
+                if (record.memberUserIds.length >= record.slotsPerServer &&
+                    !record.memberUserIds.includes(args.userId)) {
+                    throw new Error("Server is full");
+                }
+                const profile = await persistence.loadProfile({ userId: args.userId, gameId: args.gameId });
+                const isNew = profile === null;
+                entry.record = {
+                    ...record,
+                    memberUserIds: record.memberUserIds.includes(args.userId)
+                        ? record.memberUserIds
+                        : [...record.memberUserIds, args.userId],
                     status: "running",
-                    memberUserIds: [],
-                    slotsPerServer: defaultSlots,
-                    save: runtime.save,
-                    serverState: createEmptyServerRow(),
-                    sessionPlayers: {},
-                    revision: 0,
-                    tickAnchorMs: timestamp,
-                    createdAt: timestamp,
                     updatedAt: timestamp,
-                    ...(attributes?.label !== undefined ? { label: attributes.label } : {}),
-                    ...(attributes?.mode !== undefined ? { mode: attributes.mode } : {}),
-                    ...(attributes?.visibility !== undefined ? { visibility: attributes.visibility } : {}),
-                    ...(attributes?.joinCode !== undefined ? { joinCode: attributes.joinCode } : {}),
-                    ...(attributes?.tags !== undefined ? { tags: attributes.tags } : {}),
+                    dirtyAt: timestamp,
                 };
-                entry = await hydrate(record);
-            }
-            const { record } = entry;
-            if (record.memberUserIds.length >= record.slotsPerServer &&
-                !record.memberUserIds.includes(args.userId)) {
-                throw new Error("Server is full");
-            }
-            const profile = await persistence.loadProfile({ userId: args.userId, gameId: args.gameId });
-            const isNew = profile === null;
-            entry.record = {
-                ...record,
-                memberUserIds: record.memberUserIds.includes(args.userId)
-                    ? record.memberUserIds
-                    : [...record.memberUserIds, args.userId],
-                status: "running",
-                updatedAt: timestamp,
-                dirtyAt: timestamp,
+                entry.snapshot = runtime.joinPlayer(entry.snapshot, args.userId, isNew);
+                await flushServer(entry);
+                emit({ type: "server", serverId: entry.record.serverId });
+                emit({ type: "player", serverId: entry.record.serverId, userId: args.userId });
+                return { serverId: entry.record.serverId, isNew };
             };
-            entry.snapshot = runtime.joinPlayer(entry.snapshot, args.userId, isNew);
-            await flushServer(entry);
-            emit({ type: "server", serverId: entry.record.serverId });
-            emit({ type: "player", serverId: entry.record.serverId, userId: args.userId });
-            return { serverId: entry.record.serverId, isNew };
-        }),
+            return args.serverId === undefined ? joinOperation() : enqueueRoom(args.serverId, joinOperation);
+        },
         browseServers: async (args) => browseSessions(await collectListings(args.gameId), args.filter ?? {}, { limit: args.limit }),
         joinByCode: async (args) => {
             const match = findByJoinCode(await collectListings(args.gameId, { includeJoinCode: true }), args.code);
             if (match === null)
                 return null;
-            return host.joinServer({ userId: args.userId, gameId: args.gameId, serverId: match.serverId });
+            return host.joinServer({
+                userId: args.userId,
+                gameId: args.gameId,
+                serverId: match.serverId,
+                code: args.code,
+            });
         },
-        leaveServer: (args) => enqueue(async () => {
+        leaveServer: (args) => enqueueRoom(args.serverId, async () => {
             const entry = await getLive(args.serverId);
             if (entry === null)
                 return;
@@ -249,12 +310,13 @@ export function createGameHost(options) {
             };
             entry.snapshot = { ...entry.snapshot, players };
             await persistence.saveServer(entry.record);
+            forgetOpLedger(args.serverId, args.userId);
             if (memberUserIds.length === 0) {
                 live.delete(entry.record.serverId);
             }
             emit({ type: "server", serverId: args.serverId });
         }),
-        runCommand: (args) => enqueue(async () => {
+        runCommand: (args) => enqueueRoom(args.serverId, async () => {
             const entry = await getLive(args.serverId);
             if (entry === null) {
                 return { ok: false, reason: "Server not found" };
@@ -262,16 +324,28 @@ export function createGameHost(options) {
             if (!entry.record.memberUserIds.includes(args.userId)) {
                 return { ok: false, reason: "Not a member of this server" };
             }
+            const envelope = unwrapOpEnvelope(args.input);
+            if (envelope !== null) {
+                const applied = findAppliedOp(args.serverId, args.userId, envelope.opId);
+                if (applied !== undefined)
+                    return applied;
+            }
+            const commandInput = envelope !== null ? envelope.input : args.input;
             const runtime = resolveRuntime(entry.record.gameId);
-            const result = runtime.runCommand(entry.snapshot, args.userId, args.command, args.input);
-            if (!result.ok) {
-                return { ok: false, reason: result.reason };
+            const result = runtime.runCommand(entry.snapshot, args.userId, args.command, commandInput);
+            const outcome = result.ok
+                ? { ok: true }
+                : { ok: false, reason: result.reason };
+            if (result.ok) {
+                entry.snapshot = result.snapshot;
+                markMutated(entry);
+                emit({ type: "server", serverId: args.serverId });
+                emit({ type: "player", serverId: args.serverId, userId: args.userId });
             }
-            entry.snapshot = result.snapshot;
-            markMutated(entry);
-            emit({ type: "server", serverId: args.serverId });
-            emit({ type: "player", serverId: args.serverId, userId: args.userId });
-            return { ok: true };
+            if (envelope !== null) {
+                rememberAppliedOp(args.serverId, args.userId, envelope.opId, outcome);
+            }
+            return outcome;
         }),
         isMember: async (args) => {
             const entry = await getLive(args.serverId);
@@ -327,7 +401,7 @@ export function createGameHost(options) {
                 return [];
             return persistence.loadFeed({ serverId: args.serverId, action: args.action });
         },
-        pushFeedEntry: (args) => enqueue(async () => {
+        pushFeedEntry: (args) => enqueueRoom(args.serverId, async () => {
             const allowed = validateFeedWrite(feedWriteGate, args.action);
             if (!allowed.ok) {
                 throw new Error(allowed.reason);
@@ -342,26 +416,29 @@ export function createGameHost(options) {
         listOpenServers: async (args) => {
             const byId = new Map();
             for (const record of await persistence.listServers(args.gameId)) {
+                if ((record.visibility ?? "public") === "private")
+                    continue;
                 byId.set(record.serverId, toServerListing(record));
             }
             for (const entry of live.values()) {
                 if (entry.record.gameId !== args.gameId)
                     continue;
+                if ((entry.record.visibility ?? "public") === "private")
+                    continue;
                 byId.set(entry.record.serverId, toServerListing(entry.record));
             }
             return toOpenServerListings(byId.values(), args.limit);
         },
         tickOnce,
-        flushAll: () => enqueue(async () => {
-            let saved = 0;
-            for (const entry of live.values()) {
+        flushAll: async () => {
+            const outcomes = await Promise.all([...live.values()].map((entry) => enqueueRoom(entry.record.serverId, async () => {
                 if (entry.record.dirtyAt === undefined)
-                    continue;
+                    return 0;
                 await flushServer(entry);
-                saved += 1;
-            }
-            return saved;
-        }),
+                return 1;
+            })));
+            return outcomes.reduce((total, saved) => total + saved, 0);
+        },
         start: () => {
             if (interval !== null)
                 return;
@@ -374,13 +451,12 @@ export function createGameHost(options) {
                 clearInterval(interval);
                 interval = null;
             }
-            await enqueue(async () => {
-                for (const entry of live.values()) {
-                    if (entry.record.dirtyAt === undefined)
-                        continue;
-                    await flushServer(entry);
-                }
-            });
+            await Promise.all(roomQueues.values());
+            await Promise.all([...live.values()].map((entry) => enqueueRoom(entry.record.serverId, async () => {
+                if (entry.record.dirtyAt === undefined)
+                    return;
+                await flushServer(entry);
+            })));
         },
         subscribe: (listener) => {
             listeners.add(listener);
@@ -389,6 +465,7 @@ export function createGameHost(options) {
     };
     return host;
 }
+/** Creates an in-memory `HostPersistence` implementation, useful for tests and ephemeral hosts. */
 export function memoryPersistence(now = Date.now) {
     const servers = new Map();
     const profiles = new Map();

package/dist/hostRouter.d.ts

@@ -1,5 +1,6 @@
 import type { PoseSyncRules } from "@jgengine/core/multiplayer/presenceModel";
 import { type ChatRateLimit } from "@jgengine/core/game/chat";
+import { type CommandAuthorize, type CommandCatalog, type CommandLimits } from "./commandMiddleware.js";
 import type { GameHost } from "./host.js";
 import type { TransportPipeFactory } from "./pipe.js";
 export type HostRouterAuthenticate = (args: {
@@ -16,6 +17,12 @@ export type HostRouterOptions = {
     chatRateLimit?: ChatRateLimit;
     chatHistoryLimit?: number;
     chatMaxBodyLength?: number;
+    /** Per-op rate limits for pose/runCommand/join/browse/voice. Omit (default) for no rate limiting; pass {@link DEFAULT_COMMAND_LIMITS} or a custom {@link CommandLimits} to opt in. */
+    limits?: CommandLimits;
+    /** Per-command authorization hook; defaults to allow-all. */
+    authorize?: CommandAuthorize;
+    /** Declared `runCommand` names and input validators. Omit (default) to pass every command through unchanged; set to reject unknown command names and validate declared ones. */
+    validate?: CommandCatalog;
     now?: () => number;
 };
 export type HostRouterTransport = {
@@ -26,6 +33,7 @@ export type HostRouterConnection = {
     handleRaw: (raw: unknown) => void;
     close: () => void;
 };
+/** A player's interpolated position sampled from history at a past timestamp. */
 export type RewoundPosition = {
     userId: string;
     x: number;
@@ -41,5 +49,7 @@ export type HostRouter = {
     close: () => void;
 };
 export declare const DEFAULT_POSE_RULES: PoseSyncRules;
+/** Cap on frames queued behind a connection's in-flight message; beyond this a flood gets rejected instead of piling up unbounded promises. */
+export declare const MAX_QUEUED_MESSAGES = 64;
 export declare function createHostRouter(options: HostRouterOptions): HostRouter;
 export declare function loopbackPipe(router: HostRouter): TransportPipeFactory;