vimp-engine 0.35.6 → 0.36.0

package/src/lib/checkpointCodec.js

@@ -0,0 +1,125 @@
+// Кодек контрольной точки хоста (host-migration этап 5). Изоморфен: Worker
+// браузера, Node ≥ 18 (CompressionStream/DecompressionStream — глобалы) и
+// headless-runner кодируют одинаково.
+//
+// Контейнер до сжатия: [u32 metaLen LE][meta JSON utf-8][байты дампа ядра];
+// весь буфер — gzip. Дамп ядра сам по себе JSON (serialize_state), и без
+// сжатия точка tanks весит ~420 КБ, с ним ~21 КБ (plan/host-migration,
+// spike-results).
+
+import hostDefaults from '../config/hostDefaults.js';
+
+const HEADER_BYTES = 4;
+
+// поток → один Uint8Array; maxBytes — предел накопленного (распаковка чужой
+// точки — защита от «zip-бомбы»: превышение обрывает чтение, а не память)
+async function readAll(stream, maxBytes = Infinity) {
+  const reader = stream.getReader();
+  const chunks = [];
+  let total = 0;
+
+  for (;;) {
+    const { done, value } = await reader.read();
+
+    if (done) {
+      break;
+    }
+
+    total += value.byteLength;
+
+    if (total > maxBytes) {
+      await reader.cancel();
+      throw new Error(`checkpoint exceeds ${maxBytes} bytes unpacked`);
+    }
+
+    chunks.push(value);
+  }
+
+  // новый буфер целиком принадлежит результату: его можно отдать в список
+  // переноса postMessage без копии
+  const out = new Uint8Array(total);
+  let offset = 0;
+
+  for (const chunk of chunks) {
+    out.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+
+  return out;
+}
+
+function pipeBytes(bytes, transform) {
+  return new Blob([bytes]).stream().pipeThrough(transform);
+}
+
+/**
+ * Упаковывает контрольную точку.
+ * @param {Object} meta - JSON-сериализуемая мета (HANDOFF_VERSION 4).
+ * @param {Uint8Array|null} [core] - Дамп ядра; null — мягкий режим.
+ * @returns {Promise<Uint8Array>} gzip-буфер, владеющий своим ArrayBuffer.
+ */
+export async function encodeCheckpoint(meta, core = null) {
+  const metaBytes = new TextEncoder().encode(JSON.stringify(meta));
+  const coreBytes = core ?? new Uint8Array(0);
+  const raw = new Uint8Array(
+    HEADER_BYTES + metaBytes.byteLength + coreBytes.byteLength,
+  );
+
+  new DataView(raw.buffer).setUint32(0, metaBytes.byteLength, true);
+  raw.set(metaBytes, HEADER_BYTES);
+  raw.set(coreBytes, HEADER_BYTES + metaBytes.byteLength);
+
+  return readAll(pipeBytes(raw, new CompressionStream('gzip')));
+}
+
+/**
+ * Распаковывает контрольную точку.
+ * @param {Uint8Array|ArrayBuffer} bytes - Результат encodeCheckpoint.
+ * @param {Object} [options]
+ * @param {number} [options.maxBytes] - Предел распакованного размера.
+ * @returns {Promise<{meta: Object, core: Uint8Array|null}>}
+ * @throws {Error} Битый буфер, превышение предела, нечитаемая мета.
+ */
+export async function decodeCheckpoint(
+  bytes,
+  { maxBytes = hostDefaults.maxCheckpointBytes } = {},
+) {
+  let raw;
+
+  try {
+    raw = await readAll(
+      pipeBytes(bytes, new DecompressionStream('gzip')),
+      maxBytes,
+    );
+  } catch (e) {
+    throw new Error(`checkpoint is corrupted: ${e && e.message}`);
+  }
+
+  if (raw.byteLength < HEADER_BYTES) {
+    throw new Error('checkpoint is corrupted: no header');
+  }
+
+  const metaLen = new DataView(raw.buffer).getUint32(0, true);
+
+  if (HEADER_BYTES + metaLen > raw.byteLength) {
+    throw new Error('checkpoint is corrupted: meta length out of range');
+  }
+
+  let meta;
+
+  try {
+    meta = JSON.parse(
+      new TextDecoder().decode(
+        raw.subarray(HEADER_BYTES, HEADER_BYTES + metaLen),
+      ),
+    );
+  } catch (e) {
+    throw new Error(`checkpoint is corrupted: meta is not JSON`);
+  }
+
+  const core = raw.subarray(HEADER_BYTES + metaLen);
+
+  return { meta, core: core.byteLength ? core.slice() : null };
+}
+
+export default { encode: encodeCheckpoint, decode: decodeCheckpoint };

package/src/lib/clientIp.js

@@ -64,7 +64,10 @@ export function rateLimitKey(ip) {
     return addr;
   }
 
-  return `v6:${groups.slice(0, 4).map(g => parseInt(g, 16).toString(16)).join(':')}::/64`;
+  return `v6:${groups
+    .slice(0, 4)
+    .map(g => parseInt(g, 16).toString(16))
+    .join(':')}::/64`;
 }
 
 // '2001:db8::1' → 8 hex-групп или null, если запись непарсима
@@ -83,7 +86,11 @@ function expandIpv6(addr) {
     return null;
   }
 
-  const groups = [...head, ...Array(halves.length === 2 ? missing : 0).fill('0'), ...tail];
+  const groups = [
+    ...head,
+    ...Array(halves.length === 2 ? missing : 0).fill('0'),
+    ...tail,
+  ];
 
   return groups.every(g => /^[0-9a-f]{1,4}$/i.test(g)) ? groups : null;
 }

package/src/lib/createHostRuntime.js

@@ -17,13 +17,15 @@ import HostGame from '../host/HostGame.js';
 /**
  * Поднимает HostPlugin игры, ядро, SocketManager и HostGame.
  * @param {Object} room - Описание комнаты (game.hostEntryUrl, game.wasmUrl,
- *   game.version, hostSocketId, hostId/hostSecret, seed, переопределения).
+ *   game.version, hostSocketId, roomId/roomSecret/epoch, seed,
+ *   переопределения).
  * @param {Object} [options]
  * @param {Function} [options.loadHostPlugin] - Загрузчик плагина; по умолчанию
  *   динамический import по room.game.hostEntryUrl.
  * @param {Function} [options.createSocketManager] - Фабрика транспорта; по
  *   умолчанию боевой SocketManager (runner подставляет записывающий).
- * @param {Object} [options.hostOptions] - Опции HostGame (onMapChange, handoff).
+ * @param {Object} [options.hostOptions] - Опции HostGame (onMapChange,
+ *   handoff, checkpoint + seqFloor).
  * @param {Function} [options.overrideGameConfig] - Правка собранного конфига
  *   игры перед созданием ядра; в проде не задаётся, нужна отладочному
  *   прогону (сценарий подкручивает networkSendRate и таймеры).
@@ -81,22 +83,109 @@ export async function createHostRuntime(room, options = {}) {
   const host = new HostGame(game, socketManager, core, hostPlugin, {
     hostSocketId: room?.hostSocketId ?? null,
     gameVersion: room.game?.version ?? null,
+    // настройки комнаты едут в контрольной точке (host-migration этап 5):
+    // преемник собирает из них тот же конфиг ядра
+    roomSettings: pickRoomSettings(room),
+    mapsVersion: room?.mapsVersion ?? null,
     // рекордер (этап 6 плана plan/done/ai-debug) кладёт seed в сценарий — без него
     // записанный матч невоспроизводим
     seed,
     ...hostOptions,
   });
 
-  // эстафета Worker'ов несёт уже известные hostId+секрет в room — новый
+  // эстафета Worker'ов несёт уже известные roomId+секрет в room — новый
   // Worker не должен ждать повторного register_host, чтобы возобновить
-  // атрибуцию rank/state-flush; при холодном старте они придут позже
-  if (room?.hostId) {
-    host.setHostId(room.hostId, room.hostSecret);
+  // атрибуцию rank/state-flush; при холодном старте они придут позже.
+  // hostId/hostSecret — те же поля от главного потока до host-migration
+  // этапа 2
+  if (room?.roomId) {
+    host.setRoom({
+      roomId: room.roomId,
+      roomSecret: room.roomSecret,
+      epoch: room.epoch,
+    });
+  } else if (room?.hostId) {
+    host.setRoom({ roomId: room.hostId, roomSecret: room.hostSecret });
   }
 
   return { hostPlugin, game, seed, core, clientCfg, socketManager, host };
 }
 
+/**
+ * Прогрев Worker'а преемника (host-migration этап 6): плагин импортирован и
+ * проверен, wasm скомпилирован — матч не создаётся. Повторный import того же
+ * URL в том же Worker'е берётся из кэша модулей, а скачанный wasm — из
+ * HTTP-кэша, поэтому промоушен (этап 7) не ждёт сети.
+ * @param {Object} room - { game: { id, version, hostEntryUrl, wasmUrl } }.
+ * @param {Object} [options]
+ * @param {Function} [options.loadHostPlugin]
+ * @param {Function} [options.compileWasm] - (url) → Promise; по умолчанию
+ *   WebAssembly.compileStreaming с фолбэком на compile(arrayBuffer).
+ * @returns {Promise<{ hostPlugin: Object, wasmCompiled: boolean }>}
+ */
+export async function preloadHostRuntime(room, options = {}) {
+  const {
+    loadHostPlugin = defaultLoadHostPlugin,
+    compileWasm = defaultCompileWasm,
+  } = options;
+
+  const hostPlugin = await loadHostPlugin(room);
+
+  // та же проверка формы, что при init: битый плагин виден до аварии
+  assertGameConfigShape(hostPlugin);
+
+  let wasmCompiled = false;
+
+  if (room.game?.wasmUrl) {
+    await compileWasm(room.game.wasmUrl);
+    wasmCompiled = true;
+  }
+
+  return { hostPlugin, wasmCompiled };
+}
+
+async function defaultCompileWasm(url) {
+  if (typeof WebAssembly.compileStreaming === 'function') {
+    try {
+      return await WebAssembly.compileStreaming(fetch(url));
+    } catch {
+      // сервер отдал wasm не с application/wasm — компиляция из буфера
+    }
+  }
+
+  const res = await fetch(url);
+
+  if (!res.ok) {
+    throw new Error(`wasm: HTTP ${res.status}`);
+  }
+
+  return WebAssembly.compile(await res.arrayBuffer());
+}
+
+// ровно то, что читают applyRoomOverrides и buildCoreConfig. Без
+// isDevMode: dev-режим решает сборка вкладки, которая поднимает Worker
+// (prepareHostRoom в client/session/hostRoomPrep.js), в точку он не
+// едет
+const ROOM_SETTING_KEYS = [
+  'map',
+  'maxPlayers',
+  'roundTime',
+  'mapTime',
+  'friendlyFire',
+];
+
+function pickRoomSettings(room) {
+  const settings = {};
+
+  for (const key of ROOM_SETTING_KEYS) {
+    if (room?.[key] !== undefined) {
+      settings[key] = room[key];
+    }
+  }
+
+  return settings;
+}
+
 // до onInit движок игру не знает вовсе — только URL её host-бандла из
 // GameManifest
 function defaultLoadHostPlugin(room) {

package/src/lib/formOptions.js

@@ -11,6 +11,8 @@
  */
 export function normalizeOptions(list) {
   return (list || []).map(opt =>
-    opt !== null && typeof opt === 'object' ? opt : { value: opt, label: String(opt) },
+    opt !== null && typeof opt === 'object'
+      ? opt
+      : { value: opt, label: String(opt) },
   );
 }

package/src/lib/gameConfigView.js

@@ -24,6 +24,10 @@ const FIELDS = {
   // карты везёт мастер (room.maps), у игры их может не быть вовсе
   maps: { default: {} },
   currentMap: { default: null },
+  // строка карточки комнаты в лобби: 'map' — имя текущей карты; без поля
+  // карточка ничего не показывает (модули могут задать своё через
+  // deps.lobby.setInfo)
+  lobbyInfo: { default: null },
   // сколько карт попадает в голосование; 1 — минимальный осмысленный набор
   mapsInVote: { default: 1 },
   mapScale: { default: 1 },
@@ -61,6 +65,12 @@ const FIELDS = {
   endlessRound: { default: false },
 
   spectatorTeam: { derive: deriveSpectatorTeam },
+
+  // смена хоста посреди раунда (host-migration этап 5): true — игра
+  // гарантирует, что GameSim::serialize/deserialize и хуки модулей
+  // serializeState/restoreState переносят всё её состояние. Без поля —
+  // мягкий режим: мета переносится, раунд начинается заново
+  'migration.midRound': { default: false },
 };
 
 // Все пути gameConfig, которые движок читает: объявленные игрой поля плюс

package/src/lib/gameId.js

@@ -0,0 +1,13 @@
+// Формат id игры — изоморфно: его проверяет мастер (реестр, раздача, каталог)
+// и клиентский роутер ссылок (client/lib/roomLink.js) до похода в сеть.
+// Значение обязано совпадать с packages/auth/src/config/auth.js:games
+// (см. master/gameRefs.js — он реэкспортирует отсюда)
+export const GAME_ID_PATTERN = /^[a-z][a-z0-9-]{1,30}$/;
+
+/**
+ * @param {*} value
+ * @returns {boolean} Является ли значение корректным id игры.
+ */
+export function isValidGameId(value) {
+  return typeof value === 'string' && GAME_ID_PATTERN.test(value);
+}

package/src/lib/jwt.js

@@ -2,7 +2,9 @@
 function base64UrlToString(segment) {
   const base64 = segment.replace(/-/g, '+').replace(/_/g, '/');
 
-  return atob(base64.padEnd(base64.length + ((4 - (base64.length % 4)) % 4), '='));
+  return atob(
+    base64.padEnd(base64.length + ((4 - (base64.length % 4)) % 4), '='),
+  );
 }
 
 // декодирует base64url-сегмент JWT в байты (подпись — для crypto.subtle.verify)

package/src/lib/loadGamePackage.js

@@ -205,8 +205,8 @@ function warnOnRequiresMismatch(manifest, plugins) {
   // правка ломала бы каждый уже опубликованный пакет. Объявленное пустым
   // (`requires: []`) — это утверждение «ничего не нужно», и оно расходится
   // с манифестом наравне с неполным списком
-  const halves = Object.values(plugins).filter(
-    plugin => Array.isArray(plugin.requires),
+  const halves = Object.values(plugins).filter(plugin =>
+    Array.isArray(plugin.requires),
   );
 
   if (halves.length === 0) {

package/src/lib/resumeKey.js

@@ -0,0 +1,38 @@
+// Секрет возобновления сессии участника (host-migration этап 4): хост выдаёт
+// его после входа в матч (SESSION_DATA), клиент предъявляет в RESUME_REQUEST
+// после обрыва транспорта. Изоморфен — крутится и в Worker'е, и в Node.
+
+// 128 бит — угадать ключ чужого места в разумное время нельзя
+const KEY_BYTES = 16;
+
+/**
+ * @returns {string} Случайный ключ (32 hex-символа).
+ */
+export function createResumeKey() {
+  const bytes = new Uint8Array(KEY_BYTES);
+
+  globalThis.crypto.getRandomValues(bytes);
+
+  return Array.from(bytes, byte => byte.toString(16).padStart(2, '0')).join('');
+}
+
+/**
+ * Сравнение за время, не зависящее от позиции первого расхождения: по
+ * таймингу ответов ключ не подобрать посимвольно.
+ * @param {*} a
+ * @param {*} b
+ * @returns {boolean}
+ */
+export function resumeKeysEqual(a, b) {
+  if (typeof a !== 'string' || typeof b !== 'string' || a.length !== b.length) {
+    return false;
+  }
+
+  let diff = 0;
+
+  for (let i = 0; i < a.length; i += 1) {
+    diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+  }
+
+  return diff === 0;
+}

package/src/lib/roomId.js

@@ -0,0 +1,39 @@
+// Публичный id комнаты (host-migration, этап 2): короткий, стабильный за всю
+// жизнь комнаты (переживает реконнект сигналинга хоста и смену хоста),
+// виден в карточке лобби и в прямой ссылке. Модуль изоморфный: id выдаёт
+// мастер, а клиентский роутер проверяет им ссылку до похода в сеть.
+
+// crockford-base32 в нижнем регистре: без i, l, o, u — их путают с 1, 0 и v
+// при наборе ссылки руками
+const ALPHABET = '0123456789abcdefghjkmnpqrstvwxyz';
+
+// длина — константа модуля, не конфиг: её же проверяет роутер ссылок
+export const ROOM_ID_LENGTH = 8;
+
+const ROOM_ID_PATTERN = /^[0-9a-hjkmnp-tv-z]{8}$/;
+
+/**
+ * Генерирует roomId.
+ * @param {Function} randomBytes - Источник случайных байт (мастер передаёт
+ *   crypto.randomBytes): (n) => Uint8Array|Buffer длиной n.
+ * @returns {string}
+ */
+export function generateRoomId(randomBytes) {
+  const bytes = randomBytes(ROOM_ID_LENGTH);
+  let id = '';
+
+  // 256 делится на 32 нацело — остаток не смещает распределение
+  for (let i = 0; i < ROOM_ID_LENGTH; i += 1) {
+    id += ALPHABET[bytes[i] % ALPHABET.length];
+  }
+
+  return id;
+}
+
+/**
+ * @param {*} value
+ * @returns {boolean} Является ли значение корректным roomId.
+ */
+export function isValidRoomId(value) {
+  return typeof value === 'string' && ROOM_ID_PATTERN.test(value);
+}

package/src/lib/roomSettings.js

@@ -0,0 +1,59 @@
+// Настройки комнаты для холодного перезапуска (host-migration этап 7.6):
+// то, что форма создания комнаты передаёт в HostRole.createRoom
+// (client/session/HostRole.js) и что читает lib/applyRoomOverrides.js. Хост шлёт их в register_host/reclaim_host,
+// мастер хранит санированными и отдаёт преемнику в promote {mode: 'cold'}.
+// Модуль изоморфный: им пользуются и клиент (выборка из room), и мастер
+// (санитизация недоверенного сообщения)
+
+// потолок сериализованных настроек на мастере
+export const ROOM_SETTINGS_MAX_BYTES = 4096;
+
+const MAX_MAP_NAME = 64;
+const MAX_PLAYERS = 64;
+// таймеры раунда/карты (мс): applyRoomOverrides клампит их ещё раз по
+// рамкам игры, здесь — только санитарная граница
+const MAX_TIME_MS = 24 * 60 * 60 * 1000;
+
+const toInt = (value, min, max) =>
+  Number.isFinite(value)
+    ? Math.min(Math.max(Math.trunc(value), min), max)
+    : undefined;
+
+/**
+ * Известные ключи настроек комнаты из недоверенного объекта: числа
+ * клампятся, строки обрезаются, остальное отбрасывается.
+ * @param {*} source
+ * @returns {{ maxPlayers?: number, map?: string, roundTime?: number,
+ *   mapTime?: number, friendlyFire?: boolean }}
+ */
+export function sanitizeRoomSettings(source) {
+  if (!source || typeof source !== 'object') {
+    return {};
+  }
+
+  const settings = {
+    maxPlayers: toInt(source.maxPlayers, 1, MAX_PLAYERS),
+    map:
+      typeof source.map === 'string' && source.map !== ''
+        ? source.map.slice(0, MAX_MAP_NAME)
+        : undefined,
+    roundTime: toInt(source.roundTime, 0, MAX_TIME_MS),
+    mapTime: toInt(source.mapTime, 0, MAX_TIME_MS),
+    friendlyFire:
+      typeof source.friendlyFire === 'boolean'
+        ? source.friendlyFire
+        : undefined,
+  };
+
+  for (const key of Object.keys(settings)) {
+    if (settings[key] === undefined) {
+      delete settings[key];
+    }
+  }
+
+  // известных ключей мало и все короткие — потолок держит формат, если
+  // список когда-нибудь пополнится
+  return JSON.stringify(settings).length > ROOM_SETTINGS_MAX_BYTES
+    ? {}
+    : settings;
+}

package/src/lib/validators.js

@@ -300,6 +300,13 @@ export const clampGameResult = (points, best, maxGameScore) => {
   };
 };
 
+// номер записи результата игры (host-migration 7.7): положительное
+// безопасное целое, иначе null — запись без номера проксируется как раньше,
+// без защиты от повтора. Отклонять её незачем: отказ по содержанию хост
+// считает неустранимым и выбросил бы честные очки
+export const readWriteSeq = value =>
+  Number.isSafeInteger(value) && value > 0 ? value : null;
+
 // Ключ сопоставления ника с глобальным топом. Уникальность users.nick в auth
 // регистронезависимая (миграция 002), поэтому и сравнивать надо так же —
 // иначе «Alice» и «alice» разъедутся. Правило одно, а мест, где по нику

package/tests/fixtures/generations/gen-api3/host/ScriptedManager.js

@@ -112,9 +112,8 @@ export default class ScriptedManager {
   }
 
   getCountForTeam(teamName) {
-    return this._participants
-      .getScripted()
-      .filter(p => p.team === teamName).length;
+    return this._participants.getScripted().filter(p => p.team === teamName)
+      .length;
   }
 
   getCountsPerTeam() {

package/tests/fixtures/generations/gen-api3/host/fakeCore.js

@@ -52,7 +52,12 @@ export default class FakeGameCore {
       lastInputSeq: 0,
     });
 
-    this._events.push({ type: 'panelSet', id: gameId, field: 'energy', value: 100 });
+    this._events.push({
+      type: 'panelSet',
+      id: gameId,
+      field: 'energy',
+      value: 100,
+    });
   }
 
   remove_actor(gameId) {
@@ -63,7 +68,15 @@ export default class FakeGameCore {
     const actor = this._actors.get(gameId);
 
     if (actor) {
-      Object.assign(actor, { x, y, angle, team: teamId, alive: true, vx: 0, vy: 0 });
+      Object.assign(actor, {
+        x,
+        y,
+        angle,
+        team: teamId,
+        alive: true,
+        vx: 0,
+        vy: 0,
+      });
     }
   }
 
@@ -206,11 +219,22 @@ export default class FakeGameCore {
     return false;
   }
 
-  pack_frame(serverTime, seq, hasCamera, camX, camY, forceReset, shake, playerId) {
+  pack_frame(
+    serverTime,
+    seq,
+    hasCamera,
+    camX,
+    camY,
+    forceReset,
+    shake,
+    playerId,
+  ) {
     this._lastFrame = {
       serverTime,
       seq,
-      camera: hasCamera ? [camX, camY, Boolean(forceReset), shake ?? null] : null,
+      camera: hasCamera
+        ? [camX, camY, Boolean(forceReset), shake ?? null]
+        : null,
       playerId,
       body: this._lastBody,
     };
@@ -252,7 +276,9 @@ export default class FakeGameCore {
   // ***** handoff (задел, PLAN.md §6 «открытые вопросы») ***** //
 
   serialize_state() {
-    return new TextEncoder().encode(JSON.stringify([...this._actors.entries()]));
+    return new TextEncoder().encode(
+      JSON.stringify([...this._actors.entries()]),
+    );
   }
 
   deserialize_state(bytes) {

package/tests/fixtures/generations/gen-api3/manifest.json

@@ -11,9 +11,7 @@
   "roomDefaults": {
     "maxPlayers": 4
   },
-  "maps": [
-    "arena"
-  ],
+  "maps": ["arena"],
   "roomForm": [
     {
       "name": "maxPlayers",

package/tests/fixtures/generations/gen-api4/host/ScriptedManager.js

@@ -112,9 +112,8 @@ export default class ScriptedManager {
   }
 
   getCountForTeam(teamName) {
-    return this._participants
-      .getScripted()
-      .filter(p => p.team === teamName).length;
+    return this._participants.getScripted().filter(p => p.team === teamName)
+      .length;
   }
 
   getCountsPerTeam() {