vimp-engine 0.35.5 → 0.36.0

package/src/client/network/HostHealthPolicy.js

@@ -0,0 +1,307 @@
+// Политика автоматической передачи хоста (host-migration этап 9b): из потока
+// здоровья Worker'а (HostController.onHealth, сэмпл раз в ~1 с), видимости
+// вкладки и наличия беты решает, когда отдать роль бете.
+//
+// - Мягкая перегрузка (среднее tickRate последних сэмплов окна
+//   overloadWindowMs ниже overloadTickRate) — передача, отложенная до
+//   границы раунда (PlannedHandoff defer).
+// - Жёсткая (среднее окна criticalWindowMs ниже criticalTickRate или lostMs
+//   > 0 у lostWindows сэмплов подряд) и скрытая вкладка дольше
+//   hiddenHandoffMs — передача сразу; ждущую границы раунда — ускорить.
+// - Пока своя отложенная передача ждёт границы, а все сэмплы окна
+//   recoverWindowMs выше recoverTickRate (гистерезис над порогом входа) —
+//   отменить её: иначе передача сработала бы вхолостую на границе раунда.
+//
+// Новая передача — только при бете, после minHostTenureMs в роли хоста и
+// autoHandoffCooldownMs с прошлой авто-передачи этой вкладки (с её запуска,
+// при любом исходе). Отмена по нормализации кулдаун возвращает: от мигания
+// защищают гистерезис и окна. Политика живёт дольше роли хоста — кулдаун
+// переживает смену ролей.
+//
+// Без DOM: передачу, часы и таймеры инъектирует владелец
+// (client/session/HandoffFlow.js).
+
+export const AUTO_HANDOFF_REASONS = ['overload', 'hidden'];
+
+// сэмпла нет дольше этого (в интервалах здоровья) — матч стоял, окна заново
+const SAMPLE_GAP_INTERVALS = 2;
+
+const average = values => values.reduce((a, b) => a + b, 0) / values.length;
+
+export default class HostHealthPolicy {
+  /**
+   * @param {Object} options
+   * @param {Object} options.config - lobby.migration.auto.
+   * @param {Object} options.handoff - передача: { start({ reason, defer })
+   *   → boolean, hurry(reason) → boolean, cancelDeferred() → boolean,
+   *   deferredReason() → string|null (причина передачи, ждущей границы) }.
+   * @param {number} [options.healthIntervalMs] - период сэмплов Worker'а.
+   * @param {Function} [options.now] - монотонные часы, мс.
+   * @param {Object} [options.timers] - { setTimeout, clearTimeout } (тесты).
+   */
+  constructor({
+    config,
+    handoff,
+    healthIntervalMs = 1000,
+    now = () => performance.now(),
+    timers = globalThis,
+  }) {
+    this._config = config;
+    this._handoff = handoff;
+    this._intervalMs = healthIntervalMs;
+    this._now = now;
+    this._timers = timers;
+
+    this._hostSince = null;
+    this._successor = false;
+    this._hiddenSince = null;
+    this._hiddenTimer = null;
+    this._lastAutoAt = null;
+    this._cooldownBefore = null;
+    this._samples = [];
+    this._lastSampleAt = null;
+  }
+
+  // число сэмплов в окне длиной ms
+  _count(ms) {
+    return Math.max(1, Math.ceil(ms / this._intervalMs));
+  }
+
+  /**
+   * Вкладка получила или потеряла роль хоста.
+   * @param {boolean} isHost
+   */
+  setHost(isHost) {
+    if (isHost === (this._hostSince !== null)) {
+      return;
+    }
+
+    this._hostSince = isHost ? this._now() : null;
+    this._successor = false;
+    this._resetSamples();
+
+    // роль получена скрытой вкладкой: скрытие отсчитывается от получения
+    if (isHost && this._hiddenSince !== null) {
+      this._hiddenSince = this._hostSince;
+      this._armHiddenTimer();
+    } else if (!isHost) {
+      this._clearHiddenTimer();
+    }
+  }
+
+  // назначена ли бета (successor_assigned)
+  setSuccessor(available) {
+    this._successor = Boolean(available);
+    this._checkHidden();
+  }
+
+  setHidden(hidden) {
+    if (hidden && this._hiddenSince === null) {
+      this._hiddenSince = this._now();
+      this._armHiddenTimer();
+    } else if (!hidden) {
+      this._hiddenSince = null;
+      this._clearHiddenTimer();
+    }
+  }
+
+  // сэмпл здоровья Worker'а
+  addHealth(health) {
+    if (this._hostSince === null || !health) {
+      return;
+    }
+
+    const now = this._now();
+
+    if (
+      this._lastSampleAt !== null &&
+      now - this._lastSampleAt > SAMPLE_GAP_INTERVALS * this._intervalMs
+    ) {
+      this._samples = [];
+    }
+
+    this._lastSampleAt = now;
+    this._samples.push({ tickRate: health.tickRate, lostMs: health.lostMs });
+
+    const keep = Math.max(
+      this._count(this._config.overloadWindowMs),
+      this._count(this._config.criticalWindowMs),
+      this._count(this._config.recoverWindowMs),
+      this._config.lostWindows,
+    );
+
+    if (this._samples.length > keep) {
+      this._samples.splice(0, this._samples.length - keep);
+    }
+
+    this._evaluate();
+  }
+
+  destroy() {
+    this._clearHiddenTimer();
+    this._hostSince = null;
+  }
+
+  _evaluate() {
+    if (this._checkHidden()) {
+      return;
+    }
+
+    if (this._critical()) {
+      this._handOverNow('overload');
+      return;
+    }
+
+    const ownDeferred = AUTO_HANDOFF_REASONS.includes(
+      this._handoff.deferredReason(),
+    );
+
+    if (ownDeferred) {
+      if (this._recovered() && this._handoff.cancelDeferred()) {
+        this._lastAutoAt = this._cooldownBefore;
+      }
+
+      return;
+    }
+
+    if (this._overloaded() && this._mayStart()) {
+      this._start('overload', true);
+    }
+  }
+
+  // скрытая вкладка дольше порога: передача сразу. true — сработало.
+  // Отказ из-за срока роли или кулдауна — повторить, когда они истекут:
+  // у стоящего матча сэмплов, которые перепроверили бы условие, нет
+  _checkHidden() {
+    if (
+      this._hostSince === null ||
+      this._hiddenSince === null ||
+      this._now() - this._hiddenSince < this._config.hiddenHandoffMs
+    ) {
+      return false;
+    }
+
+    if (this._handOverNow('hidden')) {
+      return true;
+    }
+
+    const waitMs = this._blockedForMs();
+
+    if (waitMs > 0 && this._hiddenTimer === null) {
+      this._armHiddenTimer(waitMs);
+    }
+
+    return false;
+  }
+
+  // немедленная передача: ждущую границы — ускорить, иначе начать
+  _handOverNow(reason) {
+    if (!this._enabled() || !this._successor) {
+      return false;
+    }
+
+    if (this._handoff.deferredReason() !== null) {
+      return this._handoff.hurry(reason);
+    }
+
+    return this._mayStart() && this._start(reason, false);
+  }
+
+  _start(reason, defer) {
+    if (!this._handoff.start({ reason, defer })) {
+      return false;
+    }
+
+    this._cooldownBefore = this._lastAutoAt;
+    this._lastAutoAt = this._now();
+
+    return true;
+  }
+
+  _enabled() {
+    return this._config.enabled !== false && this._hostSince !== null;
+  }
+
+  // через сколько истекут срок роли и кулдаун (0 — не мешают)
+  _blockedForMs() {
+    const now = this._now();
+    const tenureLeft = this._hostSince + this._config.minHostTenureMs - now;
+    const cooldownLeft =
+      this._lastAutoAt === null
+        ? 0
+        : this._lastAutoAt + this._config.autoHandoffCooldownMs - now;
+
+    return Math.max(0, tenureLeft, cooldownLeft);
+  }
+
+  _mayStart() {
+    const now = this._now();
+
+    return (
+      this._enabled() &&
+      this._successor &&
+      now - this._hostSince >= this._config.minHostTenureMs &&
+      (this._lastAutoAt === null ||
+        now - this._lastAutoAt >= this._config.autoHandoffCooldownMs)
+    );
+  }
+
+  // последние n сэмплов (null — окно ещё не набрано)
+  _last(n) {
+    return this._samples.length >= n ? this._samples.slice(-n) : null;
+  }
+
+  _overloaded() {
+    const window = this._last(this._count(this._config.overloadWindowMs));
+
+    return (
+      window !== null &&
+      average(window.map(s => s.tickRate)) < this._config.overloadTickRate
+    );
+  }
+
+  _critical() {
+    const window = this._last(this._count(this._config.criticalWindowMs));
+    const lost = this._last(this._config.lostWindows);
+
+    return (
+      (window !== null &&
+        average(window.map(s => s.tickRate)) < this._config.criticalTickRate) ||
+      (lost !== null && lost.every(s => s.lostMs > 0))
+    );
+  }
+
+  _recovered() {
+    const window = this._last(this._count(this._config.recoverWindowMs));
+
+    return (
+      window !== null &&
+      window.every(s => s.tickRate > this._config.recoverTickRate)
+    );
+  }
+
+  _resetSamples() {
+    this._samples = [];
+    this._lastSampleAt = null;
+  }
+
+  _armHiddenTimer(delayMs = this._config.hiddenHandoffMs) {
+    this._clearHiddenTimer();
+
+    if (this._hostSince === null) {
+      return;
+    }
+
+    this._hiddenTimer = this._timers.setTimeout(() => {
+      this._hiddenTimer = null;
+      this._checkHidden();
+    }, delayMs);
+  }
+
+  _clearHiddenTimer() {
+    if (this._hiddenTimer !== null) {
+      this._timers.clearTimeout(this._hiddenTimer);
+      this._hiddenTimer = null;
+    }
+  }
+}

package/src/client/network/HostHealthReporter.js

@@ -0,0 +1,54 @@
+// Отчёт здоровья хоста мастеру (host-migration этап 9c): из сэмплов health
+// Worker'а (раз в ~1 с) не чаще раза в intervalMs уходит host_health с
+// последним сэмплом. Мастер по нему решает, не отдать ли роль бете из-за
+// сетевого лага. Пока матч заморожен, Worker сэмплов не шлёт — отчётов нет,
+// и мастер видит разрыв «непрерывности» лага.
+//
+// Без DOM: отправку, комнату и часы инъектирует владелец
+// (client/session/HostRole.js).
+
+export default class HostHealthReporter {
+  /**
+   * @param {Object} options
+   * @param {Function} options.send - ({ roomId, epoch, tickRate,
+   *   peerRttMedian, peerCount }) отправка мастеру.
+   * @param {Function} options.getRoom - () → { roomId, epoch } | null.
+   * @param {number} options.intervalMs
+   * @param {Function} [options.now] - монотонные часы, мс.
+   */
+  constructor({ send, getRoom, intervalMs, now = () => performance.now() }) {
+    this._send = send;
+    this._getRoom = getRoom;
+    this._intervalMs = intervalMs;
+    this._now = now;
+    this._lastSentAt = null;
+  }
+
+  /**
+   * Сэмпл health Worker'а.
+   * @param {Object} health - { tickRate, peerRttMedian, peerCount, … }.
+   * @returns {boolean} отчёт отправлен.
+   */
+  add(health) {
+    const room = this._getRoom();
+    const now = this._now();
+
+    if (
+      !room ||
+      (this._lastSentAt !== null && now - this._lastSentAt < this._intervalMs)
+    ) {
+      return false;
+    }
+
+    this._lastSentAt = now;
+    this._send({
+      roomId: room.roomId,
+      epoch: room.epoch,
+      tickRate: health.tickRate ?? null,
+      peerRttMedian: health.peerRttMedian ?? null,
+      peerCount: health.peerCount ?? 0,
+    });
+
+    return true;
+  }
+}

package/src/client/network/HostPrewarm.js

@@ -0,0 +1,235 @@
+import { decodeCheckpoint } from '../../lib/checkpointCodec.js';
+import HostController from './HostController.js';
+
+// Прогрев преемника (host-migration этап 6): по первой полной контрольной
+// точке бета готовит комнату так же, как это делает создание комнаты
+// (prepareHostRoom в client/session/hostRoomPrep.js: манифест игры той
+// версии, что в точке, карты мастера, URL worker-бандла), и поднимает
+// HostController в режиме preload —
+// Worker импортировал плагин и скомпилировал wasm, матча нет. Промоушен
+// (этап 7) поднимет в нём матч из точки без ожидания сети.
+/**
+ * Игра точки совпадает с той, что подтвердил мастер (promote.game /
+ * standby_assigned.game): точку шлёт хост — другой игрок, ей нельзя верить.
+ * Мастер без поля game (allowed — null) — проверка пропускается.
+ * @param {{ id: string, version: string }} gameRef - room.game точки.
+ * @param {{ id: string, versions?: string[] }|null} allowed
+ * @returns {boolean}
+ */
+export function isConfirmedGame(gameRef, allowed) {
+  if (!allowed) {
+    return true;
+  }
+
+  return (
+    gameRef.id === allowed.id &&
+    (!Array.isArray(allowed.versions) ||
+      allowed.versions.length === 0 ||
+      allowed.versions.includes(gameRef.version))
+  );
+}
+
+export default class HostPrewarm {
+  /**
+   * @param {Object} options
+   * @param {Function} options.prepareRoom - (settings, gameRef) →
+   *   Promise<{ room, workerUrl, mapsVersion, codeVersion }>; gameRef — { id,
+   *   version } из точки.
+   * @param {Function} [options.createController] - (room, opts) →
+   *   HostController (тесты).
+   * @param {Function} [options.decode] - распаковка точки (тесты).
+   * @param {Object} [options.diagnostics]
+   * @param {Function} [options.onReady] - Worker прогрет (prepared).
+   * @param {Function} [options.onError] - прогрев не удался (Error).
+   */
+  constructor({
+    prepareRoom,
+    createController = (room, opts) => new HostController(room, opts),
+    decode = decodeCheckpoint,
+    diagnostics = null,
+    onReady = null,
+    onError = null,
+  }) {
+    this._prepareRoom = prepareRoom;
+    this._createController = createController;
+    this._decode = decode;
+    this._diagnostics = diagnostics;
+    this._onReady = onReady;
+    this._onError = onError;
+
+    // 'idle' | 'warming' | 'ready' | 'failed' | 'destroyed'
+    this._state = 'idle';
+    this._gameKey = null;
+    // версия, прогрев которой провалился: точки идут 2 раза в секунду, и
+    // повтор на каждую означал бы шторм запросов к мастеру
+    this._failedKey = null;
+    // последний отказ точке: та же причина на следующих точках (2 раза в
+    // секунду) в журнал не идёт
+    this._rejectedKey = null;
+    this._controller = null;
+    this._prepared = null;
+  }
+
+  get state() {
+    return this._state;
+  }
+
+  // прогретый HostController (null — ещё нет)
+  get controller() {
+    return this._state === 'ready' ? this._controller : null;
+  }
+
+  // { room, workerUrl, mapsVersion, codeVersion, gameRef } прогретой комнаты
+  get prepared() {
+    return this._state === 'ready' ? this._prepared : null;
+  }
+
+  /**
+   * Прогрев по точке. Повторный вызов с той же игрой/версией ничего не
+   * делает; смена версии игры в точке (деплой в живой комнате) — прогрев
+   * заново.
+   * @param {Object} checkpoint - запись StandbyReceiver.latest(): { bytes,
+   *   game, … }. game из дескриптора избавляет от распаковки точки (ревью
+   *   F15); без него (хост старше поля) игра читается из самой точки.
+   *   bytes не передаются — копия остаётся у вызывающего.
+   * @param {Object} [options]
+   * @param {{ id: string, versions?: string[] }|null} [options.allowedGame] -
+   *   игра комнаты по данным мастера (standby_assigned.game).
+   * @returns {Promise<void>}
+   */
+  async warm(checkpoint, { allowedGame = null } = {}) {
+    if (this._state === 'destroyed' || this._state === 'warming') {
+      return;
+    }
+
+    let gameRef = checkpoint?.game ?? null;
+
+    if (!gameRef) {
+      // негодная точка — проблема этой точки, а не версии игры: прогретый
+      // Worker остаётся, следующая точка той же версии проверяется как обычно
+      try {
+        const { meta } = await this._decode(checkpoint?.bytes);
+
+        gameRef = meta?.room?.game ?? null;
+      } catch (e) {
+        this._reject('decode', e);
+        return;
+      }
+    }
+
+    if (!gameRef?.id || !gameRef.version) {
+      this._reject('noGame', new Error('checkpoint has no room.game'));
+      return;
+    }
+
+    gameRef = { id: gameRef.id, version: gameRef.version };
+
+    // как и негодная точка — проблема точки: состояние не меняется
+    if (!isConfirmedGame(gameRef, allowedGame)) {
+      this._reject(
+        `foreign:${gameRef.id}@${gameRef.version}`,
+        new Error('checkpoint game is not the room game'),
+      );
+      return;
+    }
+
+    this._rejectedKey = null;
+
+    const gameKey = `${gameRef.id}@${gameRef.version}`;
+
+    if (
+      this._state === 'destroyed' ||
+      gameKey === this._gameKey ||
+      gameKey === this._failedKey
+    ) {
+      return;
+    }
+
+    this._terminate();
+    this._gameKey = gameKey;
+    this._state = 'warming';
+
+    let prepared;
+
+    try {
+      // настройки точки не нужны: игра, карты и dev-режим комнаты беты —
+      // свои, а настройки комнаты промоушен берёт из самой точки (ревью F1)
+      prepared = await this._prepareRoom({}, gameRef);
+    } catch (e) {
+      this._fail(e);
+      return;
+    }
+
+    if (this._state !== 'warming' || this._gameKey !== gameKey) {
+      return; // destroy() или новая версия, пока готовились
+    }
+
+    this._prepared = { ...prepared, gameRef };
+    this._controller = this._createController(prepared.room, {
+      workerUrl: prepared.workerUrl ?? undefined,
+      diagnostics: this._diagnostics ?? undefined,
+      preload: true,
+      onPreloaded: () => {
+        if (this._state === 'warming' && this._gameKey === gameKey) {
+          this._state = 'ready';
+          this._onReady?.(this._prepared);
+        }
+      },
+      onError: msg => {
+        if (this._gameKey === gameKey) {
+          this._fail(new Error(msg?.message || 'preload failed'));
+        }
+      },
+    });
+  }
+
+  /**
+   * Промоушен (host-migration этап 7.4) забирает прогретый Worker: дальше
+   * им владеет вызывающий, destroy() его уже не гасит.
+   * @returns {Object|null} { controller, prepared } или null — прогрева нет.
+   */
+  take() {
+    if (this._state !== 'ready') {
+      return null;
+    }
+
+    const taken = { controller: this._controller, prepared: this._prepared };
+
+    this._controller = null;
+    this._prepared = null;
+    this._state = 'destroyed';
+
+    return taken;
+  }
+
+  // standby_released, уход из комнаты, смена эпохи
+  destroy() {
+    this._terminate();
+    this._state = 'destroyed';
+  }
+
+  // отказ точке — в журнал один раз на причину: хост шлёт точки дважды
+  // в секунду, а состояние прогрева от отказа не меняется
+  _reject(key, error) {
+    if (key === this._rejectedKey) {
+      return;
+    }
+
+    this._rejectedKey = key;
+    this._onError?.(error);
+  }
+
+  _fail(error) {
+    this._terminate();
+    this._state = 'failed';
+    this._failedKey = this._gameKey;
+    this._gameKey = null;
+    this._onError?.(error);
+  }
+
+  _terminate() {
+    this._controller?.destroy();
+    this._controller = null;
+    this._prepared = null;
+  }
+}

package/src/client/network/LoopbackTransport.js

@@ -12,9 +12,13 @@ export default class LoopbackTransport {
    * @param {HostController} controller - мост к Worker'у.
    * @param {string} [socketId] - id соединения хоста-игрока в Worker'е.
    */
-  constructor(controller, socketId = 'local') {
+  // resume — возобновление места в матче (host-migration этап 7.4:
+  // преемник возвращает своего игрока в поднятый им матч): Worker ждёт
+  // RESUME_REQUEST, а 'open' сообщает супервизору, что его пора слать
+  constructor(controller, socketId = 'local', { resume = false } = {}) {
     this._controller = controller;
     this._socketId = socketId;
+    this._resume = resume;
     this._closed = false;
 
     this.publisher = new Publisher();
@@ -25,7 +29,18 @@ export default class LoopbackTransport {
     this._controller.open(this._socketId, {
       onMessage: payload => this.publisher.emit('message', payload),
       onClose: () => this._emitClose(),
+      resume: this._resume,
     });
+
+    // подписчики появляются после connect() (супервизор берёт уже
+    // подключённый транспорт) — 'open' уходит следующей микрозадачей
+    if (this._resume) {
+      queueMicrotask(() => {
+        if (!this._closed) {
+          this.publisher.emit('open');
+        }
+      });
+    }
   }
 
   // отправляет данные хосту (в Worker через роутер главного потока)