vimp-engine 0.7.2 → 0.8.0

package/src/client/network/InlineHostBridge.js

@@ -0,0 +1,152 @@
+import wsports from '../../config/wsports.js';
+import { createHostRuntime } from '../../lib/createHostRuntime.js';
+import { offlinePlayerData } from '../../lib/offlinePlayerData.js';
+import PortMachine from '../../host/PortMachine.js';
+import { createGuestIdentity } from '../../host/identity.js';
+
+// Замена HostController для solo-режима (Этап 2 плана standalone-sdk): тот же
+// интерфейс, который дёргает LoopbackTransport (open/send/disconnect), но
+// вместо Worker'а хост крутится в этом же потоке.
+//
+// Почему inline, а не Worker: HostPlugin принципиально непередаваем в Worker
+// (postMessage не несёт функции), а standalone SDK получает от репозитория
+// игры именно живой объект плагина. Прод-путь (хост в Worker'е) не меняется —
+// расхождение dev/prod осознанное, см. plan/standalone-sdk/README.md.
+//
+// Мастера в этом контуре нет: личность гостевая (ник из формы, identity.js),
+// профиль offline-заглушкой (lib/offlinePlayerData.js).
+
+const PS_TECH_INFORM_DATA = wsports.server.TECH_INFORM_DATA;
+
+export default class InlineHostBridge {
+  /**
+   * @param {Object} room - Описание комнаты (game.wasmUrl, hostSocketId, …).
+   * @param {Object} deps
+   * @param {Object} deps.hostPlugin - Живой HostPlugin игры.
+   * @param {Function} [deps.onMapChange] - Уведомление о смене карты.
+   */
+  constructor(room, { hostPlugin, onMapChange } = {}) {
+    // socketId → { onMessage, onClose } транспорта
+    this._clients = new Map();
+    this._runtime = null;
+    this._portMachine = null;
+    this._destroyed = false;
+
+    // хост поднимается асинхронно (ядро игры + WASM): open() до готовности
+    // потерял бы хендшейк, поэтому вызывающий обязан дождаться ready
+    this.ready = this._init(room, { hostPlugin, onMapChange });
+  }
+
+  /**
+   * Новое соединение клиента: регистрация обработчиков и старт хендшейка.
+   * @param {string} socketId
+   * @param {Object} handlers - { onMessage, onClose }.
+   */
+  open(socketId, handlers) {
+    this._assertReady();
+    this._clients.set(socketId, handlers);
+    this._portMachine.connect(socketId);
+  }
+
+  /**
+   * Кадр клиента хосту (wire-строка [port, payload]).
+   * @param {string} socketId
+   * @param {string} data
+   */
+  send(socketId, data) {
+    this._assertReady();
+    this._portMachine.message(socketId, data);
+  }
+
+  /**
+   * Отключение клиента.
+   * @param {string} socketId
+   */
+  disconnect(socketId) {
+    if (!this._clients.delete(socketId)) {
+      return;
+    }
+
+    this._portMachine.disconnect(socketId);
+  }
+
+  /**
+   * Останов матча: таймеры хоста держали бы вкладку живой и после выхода.
+   * @returns {Promise} Завершение teardown хоста.
+   */
+  destroy() {
+    this._destroyed = true;
+    this._clients.clear();
+
+    // ready может быть ещё в полёте — без ожидания хост поднялся бы уже
+    // после teardown и остался бы во вкладке со своим игровым циклом
+    return this.ready.catch(() => {}).then(() => this._runtime?.host.destroy());
+  }
+
+  async _init(room, { hostPlugin, onMapChange }) {
+    const runtime = await createHostRuntime(room, {
+      // плагин уже живой объект — динамического import'а по URL нет
+      loadHostPlugin: async () => hostPlugin,
+      hostOptions: {
+        playerDataFetch: offlinePlayerData(),
+        onMapChange,
+      },
+    });
+
+    // stop() успел прийти раньше готовности: поднятый хост нужно погасить
+    // здесь, иначе его таймеры останутся во вкладке навсегда
+    if (this._destroyed) {
+      await runtime.host.destroy();
+      return;
+    }
+
+    this._runtime = runtime;
+
+    this._portMachine = new PortMachine({
+      host: runtime.host,
+      socketManager: runtime.socketManager,
+      clientCfg: runtime.clientCfg,
+      authSchema: runtime.hostPlugin.authSchema,
+      makeSocket: socketId => this._makeSocket(socketId),
+      identity: createGuestIdentity(),
+    });
+  }
+
+  // хост поднимается асинхронно: без ready порт-машины ещё нет, и вызов
+  // упал бы сырым TypeError на null. После destroy() порт-машина остаётся, но
+  // хост уже погашен — кадр создал бы участника без таймеров матча
+  _assertReady() {
+    if (this._destroyed) {
+      throw new Error('InlineHostBridge: the host is destroyed');
+    }
+
+    if (!this._portMachine) {
+      throw new Error('InlineHostBridge: await ready first');
+    }
+  }
+
+  // wire-сокет пользователя: кладёт кадр прямо в onMessage транспорта —
+  // ровно те же форматы, что makeWorkerSocket отправляет постмесседжем
+  _makeSocket(socketId) {
+    return {
+      send: (port, data) =>
+        this._deliver(socketId, JSON.stringify([port, data])),
+
+      sendBinary: buffer => this._deliver(socketId, buffer),
+
+      // причина закрытия доставляется отдельным TECH_INFORM до закрытия —
+      // как в Worker'е (порядок гарантирован синхронной доставкой)
+      close: (code, data) => {
+        if (data !== undefined) {
+          this._deliver(socketId, JSON.stringify([PS_TECH_INFORM_DATA, data]));
+        }
+
+        this._clients.get(socketId)?.onClose();
+      },
+    };
+  }
+
+  _deliver(socketId, payload) {
+    this._clients.get(socketId)?.onMessage(payload);
+  }
+}

package/src/client/network/LoopbackTransport.js

@@ -0,0 +1,51 @@
+import Publisher from '../../lib/Publisher.js';
+
+// Транспорт хоста-игрока: та же вкладка играет в собственной комнате без
+// WebRTC. Реализует интерфейс WebRtcManager (publisher c 'message'/'close',
+// send/close), но данные ходят через HostController → Worker постмесседжами
+// (postMessage-loopback). Для клиентского кода транспорт прозрачен.
+//
+// Флаг reliable игнорируется: loopback доставляет всё надёжно и по порядку
+// (разделение meta/state актуально только для реального WebRTC).
+export default class LoopbackTransport {
+  /**
+   * @param {HostController} controller - мост к Worker'у.
+   * @param {string} [socketId] - id соединения хоста-игрока в Worker'е.
+   */
+  constructor(controller, socketId = 'local') {
+    this._controller = controller;
+    this._socketId = socketId;
+    this._closed = false;
+
+    this.publisher = new Publisher();
+  }
+
+  // поднимает loopback-соединение (аналог WebRtcManager.connect)
+  connect() {
+    this._controller.open(this._socketId, {
+      onMessage: payload => this.publisher.emit('message', payload),
+      onClose: () => this._emitClose(),
+    });
+  }
+
+  // отправляет данные хосту (в Worker через роутер главного потока)
+  send(data) {
+    if (!this._closed) {
+      this._controller.send(this._socketId, data);
+    }
+  }
+
+  close() {
+    this._emitClose();
+  }
+
+  _emitClose() {
+    if (this._closed) {
+      return;
+    }
+
+    this._closed = true;
+    this._controller.disconnect(this._socketId);
+    this.publisher.emit('close');
+  }
+}

package/src/client/network/SignalingClient.js

@@ -0,0 +1,146 @@
+import Publisher from '../../lib/Publisher.js';
+
+// Клиент сигнального WebSocket мастер-сервера (src/master/SignalingServer.js).
+// Только координация установки P2P: приём welcome (id соединения + iceServers),
+// обмен SDP-офферами/ответами и ICE-кандидатами, сигнальный ping/pong, жалобы.
+// Игровой трафик идёт по WebRTC-каналам (WebRtcManager), не через мастер.
+//
+// Входящие сообщения ретранслируются подписчикам через Publisher по полю type;
+// welcome дополнительно кэширует id/iceServers. Транспорт WebSocket инъекций
+// ради тестируемости — фабрика по умолчанию использует глобальный WebSocket.
+export default class SignalingClient {
+  constructor(url, socketFactory = u => new WebSocket(u)) {
+    this._url = url;
+    this._socketFactory = socketFactory;
+
+    this._ws = null;
+    this._id = null;
+    this._iceServers = [];
+
+    this.publisher = new Publisher();
+  }
+
+  get id() {
+    return this._id;
+  }
+
+  get iceServers() {
+    return this._iceServers;
+  }
+
+  get connected() {
+    return this._ws !== null && this._ws.readyState === this._ws.OPEN;
+  }
+
+  // открывает соединение; событие 'welcome' — после приёма welcome от мастера
+  connect() {
+    if (this._ws) {
+      return;
+    }
+
+    const ws = this._socketFactory(this._url);
+
+    this._ws = ws;
+
+    ws.onopen = () => this.publisher.emit('open');
+    ws.onerror = () => this.publisher.emit('socketError');
+
+    ws.onclose = event => {
+      this._ws = null;
+      this.publisher.emit('close', event);
+    };
+
+    ws.onmessage = event => this._onMessage(event.data);
+  }
+
+  // клиент → SDP-оффер конкретному хосту
+  sendOffer(hostId, sdp) {
+    this._send({ type: 'webrtc_offer', hostId, sdp });
+  }
+
+  // хост → регистрация комнаты у мастера (ответ — событие 'host_registered').
+  // token — Bearer identity-токен хостера (server-rating этап 2): без него
+  // мастер отклоняет регистрацию, т.к. не может атрибутировать комнату и
+  // проверить рейтинг хостера
+  registerHost({ name, maxPlayers, mapName, gameId, gameVersion, token }) {
+    this._send({
+      type: 'register_host',
+      name,
+      maxPlayers,
+      mapName,
+      gameId,
+      gameVersion,
+      token,
+    });
+  }
+
+  // хост → актуализация комнаты (заодно heartbeat)
+  updateHost({ currentPlayers, mapName } = {}) {
+    this._send({ type: 'update_host', currentPlayers, mapName });
+  }
+
+  // хост → SDP-ответ конкретному клиенту
+  sendAnswer(clientId, sdp) {
+    this._send({ type: 'webrtc_answer', clientId, sdp });
+  }
+
+  // хост → pong на сигнальный ping клиента (замер задержки в лобби)
+  pongHost(clientId, pingId) {
+    this._send({ type: 'pong_host', clientId, pingId });
+  }
+
+  // обмен ICE-кандидатами (targetId — hostId со стороны клиента)
+  sendIceCandidate(targetId, candidate) {
+    this._send({ type: 'ice_candidate', targetId, candidate });
+  }
+
+  // сигнальный ping хосту (замер приблизительный: клиент→мастер→хост)
+  pingHost(hostId, pingId) {
+    this._send({ type: 'ping_host', hostId, pingId });
+  }
+
+  // /like·/unlike напрямую мастеру (минуя хоста-читера), server-rating
+  // этап 2: reason — причина (обязательна), token — Bearer identity-токен
+  // голосующего
+  likeHost(hostId, reason, token) {
+    this._send({ type: 'like_host', hostId, reason, token });
+  }
+
+  unlikeHost(hostId, reason, token) {
+    this._send({ type: 'unlike_host', hostId, reason, token });
+  }
+
+  close() {
+    if (this._ws) {
+      this._ws.close();
+      this._ws = null;
+    }
+  }
+
+  _onMessage(raw) {
+    let msg;
+
+    try {
+      msg = JSON.parse(raw);
+    } catch (e) {
+      return;
+    }
+
+    if (!msg || typeof msg.type !== 'string') {
+      return;
+    }
+
+    if (msg.type === 'welcome') {
+      this._id = msg.id;
+      this._iceServers = msg.iceServers || [];
+    }
+
+    this.publisher.emit(msg.type, msg);
+  }
+
+  _send(message) {
+    if (this.connected) {
+      this._ws.send(JSON.stringify(message));
+    }
+  }
+}

package/src/client/network/WebRtcManager.js

@@ -0,0 +1,147 @@
+import Publisher from '../../lib/Publisher.js';
+
+// Транспорт P2P-соединения клиента с браузерным хостом. Заменяет игровой
+// WebSocket: два RTCDataChannel вместо одного сокета.
+//
+// - meta  (reliable-ordered)      — весь JSON-протокол [portId, payload] и
+//                                    бинарные кадры с одноразовыми событиями;
+// - state (unreliable-unordered)  — чисто позиционные бинарные кадры, их
+//                                    потерю компенсирует следующий кадр.
+//
+// Классификация кадров meta/state — на стороне хоста при упаковке. Клиент лишь
+// принимает данные из обоих каналов и отдаёт их одним потоком (событие
+// 'message'), как раньше делал ws.onmessage. Исходящие сообщения клиента —
+// управляющие, идут по reliable-каналу meta.
+//
+// Клиент — инициатор (offerer): создаёт каналы и оффер, обменивается с хостом
+// SDP/ICE через сигнальный WebSocket (SignalingClient). RTCPeerConnection
+// инъектируется фабрикой ради тестируемости.
+export default class WebRtcManager {
+  constructor(signaling, { iceServers, peerFactory } = {}) {
+    this._signaling = signaling;
+    this._iceServers = iceServers || signaling.iceServers;
+    this._peerFactory =
+      peerFactory || (config => new RTCPeerConnection(config));
+
+    this._pc = null;
+    this._meta = null;
+    this._state = null;
+    this._hostId = null;
+    this._openChannels = 0;
+    this._closed = false;
+
+    this.publisher = new Publisher();
+
+    // подписки на сигнальные ответы конкретно этого соединения
+    this._signaling.publisher.on('webrtc_answer', 'onAnswer', this);
+    this._signaling.publisher.on('ice_candidate', 'onRemoteCandidate', this);
+  }
+
+  // инициирует установку соединения с хостом
+  async connect(hostId) {
+    this._hostId = hostId;
+
+    const pc = this._peerFactory({ iceServers: this._iceServers });
+
+    this._pc = pc;
+
+    // meta открывает канал, отправляемый по надёжному упорядоченному потоку
+    this._meta = pc.createDataChannel('meta', { ordered: true });
+    this._meta.binaryType = 'arraybuffer';
+
+    // state — ненадёжный неупорядоченный (позиционные кадры)
+    this._state = pc.createDataChannel('state', {
+      ordered: false,
+      maxRetransmits: 0,
+    });
+    this._state.binaryType = 'arraybuffer';
+
+    this._wireChannel(this._meta);
+    this._wireChannel(this._state);
+
+    pc.onicecandidate = event => {
+      if (event.candidate) {
+        this._signaling.sendIceCandidate(hostId, event.candidate);
+      }
+    };
+
+    pc.onconnectionstatechange = () => {
+      const st = pc.connectionState;
+
+      // 'disconnected' транзиентен (может восстановиться) — не рвём;
+      // реальный обрыв доведёт до 'failed' или закроет каналы (onclose)
+      if (st === 'failed' || st === 'closed') {
+        this._emitClose();
+      }
+    };
+
+    const offer = await pc.createOffer();
+
+    await pc.setLocalDescription(offer);
+
+    this._signaling.sendOffer(hostId, pc.localDescription);
+  }
+
+  // приём SDP-ответа хоста (подписка на сигнальный канал)
+  async onAnswer(msg) {
+    if (!this._pc || msg.hostId !== this._hostId) {
+      return;
+    }
+
+    await this._pc.setRemoteDescription(msg.sdp);
+  }
+
+  // приём удалённого ICE-кандидата (от хоста)
+  async onRemoteCandidate(msg) {
+    if (!this._pc || msg.fromId !== this._hostId) {
+      return;
+    }
+
+    try {
+      await this._pc.addIceCandidate(msg.candidate);
+    } catch (e) {
+      // кандидат до setRemoteDescription или дубль — не критично
+    }
+  }
+
+  // отправляет данные хосту; управляющие сообщения клиента — по meta
+  send(data, reliable = true) {
+    const channel = reliable ? this._meta : this._state;
+
+    if (channel && channel.readyState === 'open') {
+      channel.send(data);
+    }
+  }
+
+  close() {
+    this._emitClose();
+  }
+
+  _wireChannel(channel) {
+    channel.onopen = () => {
+      this._openChannels += 1;
+
+      // оба канала открыты — транспорт готов (как ws.onopen)
+      if (this._openChannels === 2) {
+        this.publisher.emit('open');
+      }
+    };
+
+    channel.onmessage = event => this.publisher.emit('message', event.data);
+    channel.onclose = () => this._emitClose();
+  }
+
+  _emitClose() {
+    if (this._closed) {
+      return;
+    }
+
+    this._closed = true;
+
+    if (this._pc) {
+      this._pc.close();
+    }
+
+    this.publisher.emit('close');
+  }
+}

package/src/client/network/WebSocketTransport.js

@@ -0,0 +1,78 @@
+import Publisher from '../../lib/Publisher.js';
+
+// Третий транспорт клиента (Этап 2 плана standalone-sdk): прямой WebSocket к
+// dedicated-серверу. Интерфейсный близнец WebRtcManager и LoopbackTransport —
+// publisher с 'message'/'close', connect/send/close, — поэтому клиентский код
+// про него не знает.
+//
+// Отличия от WebRTC, которые надо держать в голове (см. docs/en/network.md):
+// разделения meta/state тут нет, флаг reliable игнорируется. Значит PING/PONG
+// идут надёжным каналом (замер RTT становится замером TCP-пути), а бэкпрешер
+// вместо дропа позиционных кадров живёт на серверной стороне.
+
+// WebSocket.OPEN: константа класса, а не инстанса — у фейкового сокета в
+// тестах её может не быть вовсе
+const WS_OPEN = 1;
+
+export default class WebSocketTransport {
+  /**
+   * @param {string} url - Адрес игрового WebSocket.
+   * @param {Object} [options]
+   * @param {Function} [options.socketFactory] - Фабрика сокета (тесты).
+   */
+  constructor(url, { socketFactory = u => new WebSocket(u) } = {}) {
+    this._url = url;
+    this._socketFactory = socketFactory;
+    this._ws = null;
+    this._closed = false;
+
+    this.publisher = new Publisher();
+  }
+
+  connect() {
+    this._ws = this._socketFactory(this._url);
+
+    // обязательно: клиент различает кадр снапшота и JSON-порт по
+    // `data instanceof ArrayBuffer`, а дефолтный браузерный WS отдаёт Blob
+    this._ws.binaryType = 'arraybuffer';
+
+    this._ws.onopen = () => this.publisher.emit('open');
+    this._ws.onmessage = event => this.publisher.emit('message', event.data);
+    // код закрытия уезжает подписчику: политические отказы сервера (лимит
+    // подключений, таймаут хендшейка) клиент лечить перезагрузкой не должен —
+    // см. handleDisconnect в main.js
+    this._ws.onclose = event => this._emitClose(event?.code);
+    // ошибка сокета всегда сопровождается close — отдельного события наружу
+    // не даём, иначе клиент погасил бы матч дважды
+    this._ws.onerror = () => {};
+  }
+
+  /**
+   * @param {string|ArrayBuffer} data - Кадр.
+   * @param {boolean} [reliable] - Игнорируется: у WebSocket нет уровней
+   *   надёжности, всё едет надёжно и по порядку.
+   */
+  send(data) {
+    if (this._ws && this._ws.readyState === WS_OPEN) {
+      this._ws.send(data);
+    }
+  }
+
+  close() {
+    if (this._closed) {
+      return;
+    }
+
+    this._ws?.close();
+    this._emitClose();
+  }
+
+  _emitClose(code) {
+    if (this._closed) {
+      return;
+    }
+
+    this._closed = true;
+    this.publisher.emit('close', code);
+  }
+}

package/src/client/network/policyClose.js

@@ -0,0 +1,54 @@
+// Отказы по политике: коды закрытия, которыми dedicated-сервер отбивает
+// соединение (`src/dedicated/main.js` — invalidOrigin, handshakeTimeout,
+// tooManyConnections) и которыми порт-машина отбивает полную комнату
+// (`src/host/PortMachine.js` — roomFull). Числа берутся из общей карты
+// `src/config/closeCodes.js`, чтобы серверные контуры и клиент не разъехались
+// молча; тест модуля требует явного решения по каждому коду карты.
+//
+// Клиенту от кода нужны два разных ответа, и совпадают они не всегда, поэтому
+// знание разведено на два экспорта (review-4.md, R4-2):
+//
+//   - перезагружаться ли. Ни на одном из этих кодов перезагрузка не помогает:
+//     лимит частоты подключений съел бы ей же очередное соединение, таймаут
+//     хендшейка запустился бы заново, origin страницы не меняется вовсе, а
+//     слот в полной комнате перезагрузка не освобождает. Брошенная вкладка
+//     перезагружалась бы вечно, а ждущий слот игрок за 30 витков сам упёрся бы
+//     в лимит подключений и получил бы чужую причину отказа;
+//   - какой текст показать. Тексты запасные: `handleDisconnect` берёт их
+//     только тогда, когда сервер причину не прислал сам (`terminalInformShown`
+//     — `client/main.js`). Полная комната, например, приезжает с причиной от
+//     порт-машины (TECH_INFORM перед `close`), и она всегда побеждает —
+//     запись 4006 ниже отработает, только если тот кадр не доехал. Тексты
+//     здесь, а не в `techInformList`: список переопределяет игра, и движковый
+//     индекс дал бы у неё «Unknown error».
+
+import closeCodes from '../../config/closeCodes.js';
+
+const { invalidOrigin, roomFull, handshakeTimeout, tooManyConnections } =
+  closeCodes;
+
+const NO_RELOAD_CLOSE_CODES = new Set([
+  invalidOrigin,
+  roomFull,
+  handshakeTimeout,
+  tooManyConnections,
+]);
+
+export const POLICY_CLOSE_INFORMS = {
+  [invalidOrigin]:
+    'This page is not allowed by the game server. Check the address you opened.',
+  [roomFull]: 'The room is full. Try again later.',
+  [handshakeTimeout]:
+    'Idle connection closed before the match started. Reload the page when you are ready to play.',
+  [tooManyConnections]:
+    'Too many connections from your address. Wait a minute and reload the page.',
+};
+
+/**
+ * @param {number} [closeCode] - Код закрытия транспорта. Его отдаёт только
+ *   WebSocket-транспорт (dedicated); в P2P и solo кода нет вовсе.
+ * @returns {boolean} Уместна ли перезагрузка страницы после разрыва.
+ */
+export function shouldReloadAfterClose(closeCode) {
+  return !NO_RELOAD_CLOSE_CODES.has(closeCode);
+}

package/src/client/network/workerSupport.js

@@ -0,0 +1,34 @@
+// Фича-детект модульных Worker'ов (Этап 6.3): нет classic-фолбэка (запретил
+// бы ESM и потребовал инлайн WASM, см. PLAN.md риск №5) — вместо него честная
+// ошибка при «Создать сервер», join остаётся доступен. Конструктор Worker не
+// бросает исключение на неизвестной опции `type`, поэтому используется
+// классический трюк: геттер `type` читают только реализации, которые умеют
+// module-воркеры — на остальных `supported` останется false. URL пробного
+// воркера — `blob:`, а не `data:`, чтобы не нарушать CSP `worker-src 'self'
+// blob:'` (data: там не разрешён и браузер блокирует создание воркера).
+export function supportsModuleWorker() {
+  let supported = false;
+  let probeUrl;
+
+  try {
+    probeUrl = URL.createObjectURL(new Blob([''], { type: 'text/javascript' }));
+
+    const worker = new Worker(probeUrl, {
+      get type() {
+        supported = true;
+
+        return 'module';
+      },
+    });
+
+    worker.terminate();
+  } catch (e) {
+    supported = false;
+  } finally {
+    if (probeUrl) {
+      URL.revokeObjectURL(probeUrl);
+    }
+  }
+
+  return supported;
+}