vimp-engine 0.7.2 → 0.8.0

package/src/host/identity.js

@@ -0,0 +1,100 @@
+// Стратегии идентичности хоста: как порт-машина (PortMachine.js) узнаёт,
+// под каким ником участник входит в комнату. Прод-лобби доверяет только
+// подписанному identity-токену центрального auth-сервиса; standalone- и
+// dedicated-контуры мастера не имеют вовсе и пускают гостей по нику из формы.
+//
+// Контракт стратегии:
+//   { params: Array, errorField: string, resolve(data, socketId): Promise<string> }
+// params доклеиваются к authSchema.params игры (и в форму клиента, и в
+// validateAuth), resolve возвращает проверенный ник или бросает.
+
+import { verifyIdentityToken } from '../lib/jwt.js';
+import { isValidName } from '../lib/validators.js';
+
+/**
+ * Прод-лобби: ник берётся из claim проверенного identity-токена (Этап B3).
+ * @param {Object} deps
+ * @param {string} deps.jwksUrl - URL JWKS (прокси мастера).
+ * @param {string} deps.issuer - ожидаемый iss токена.
+ * @returns {Object} Стратегия идентичности.
+ */
+export function createTokenIdentity({ jwksUrl, issuer }) {
+  // JWKS central auth-сервиса, проксированный мастером (Этап B3), кэшируется
+  // на время жизни стратегии — ключ меняется только при ротации
+  let jwksPromise = null;
+
+  const getJwks = () => {
+    if (!jwksPromise) {
+      jwksPromise = fetch(jwksUrl).then(res => {
+        if (!res.ok) {
+          throw new Error(`jwks: HTTP ${res.status}`);
+        }
+
+        return res.json();
+      });
+
+      // сбой не должен закэшироваться навсегда — следующий вход попробует снова
+      jwksPromise.catch(() => {
+        jwksPromise = null;
+      });
+    }
+
+    return jwksPromise;
+  };
+
+  return {
+    // токен не поле игровой формы — в authSchema его нет, и validateAuth
+    // его не касается: подпись авторитетнее любой схемы
+    params: [],
+    errorField: 'token',
+
+    // проверяет identity-токен клиента: подпись RS256 по JWKS мастера,
+    // issuer, срок годности — возвращает проверенный ник или бросает.
+    // Свободный ввод имени в игре не источник ника: он берётся из claim
+    async resolve(data) {
+      const jwks = await getJwks();
+      const payload = await verifyIdentityToken(data.token, { jwks, issuer });
+
+      return payload.nick;
+    },
+  };
+}
+
+/**
+ * Гостевой вход (standalone/dedicated): ник — поле формы, которое хост
+ * валидирует сам движковым isValidName, без кода игры.
+ *
+ * Ограничение (принимается осознанно): гостевые ники не уникальны и не
+ * защищены от подмены — центральной идентичности в этом контуре нет.
+ * @param {Object} [options]
+ * @param {string} [options.fallbackPrefix] - префикс ника-заглушки.
+ * @returns {Object} Стратегия идентичности.
+ */
+export function createGuestIdentity({ fallbackPrefix = 'Player_' } = {}) {
+  return {
+    params: [
+      {
+        name: 'name',
+        value: '',
+        options: {
+          control: 'text',
+          label: 'Name',
+          validator: 'isValidName',
+          storage: 'playerName',
+          required: true,
+          maxlength: 15,
+        },
+      },
+    ],
+    errorField: 'name',
+
+    // fallback нужен не форме (её ввод отсекает validateAuth по тому же
+    // isValidName), а прямым вызовам стратегии — гость без ника всё равно
+    // должен получить имя, под которым его увидят остальные
+    async resolve(data, socketId) {
+      return isValidName(data?.name)
+        ? data.name
+        : `${fallbackPrefix}${String(socketId).slice(0, 4)}`;
+    },
+  };
+}

package/src/lib/clientIp.js

@@ -0,0 +1,39 @@
+// Адрес клиента для rate-limit'ов серверных контуров.
+//
+// `X-Forwarded-For` для этого не годится: Nginx деплоя ставит его через
+// `$proxy_add_x_forwarded_for` (.github/deployment/install-system.sh), то есть
+// ДОПИСЫВАЕТ реальный адрес к тому, что прислал клиент. Первый элемент списка
+// задаёт сам клиент — на нём лимит и обходится (свой заголовок на каждое
+// соединение), и выбирается чужой бакет (заголовок с адресом жертвы закрывает
+// ей вход). Тот же Nginx перезаписывает `X-Real-IP` значением `$remote_addr`,
+// поэтому за прокси доверяем только ему, а без прокси — адресу сокета.
+
+// один раз на процесс: предупреждение о прокси без X-Real-IP на каждое
+// соединение превратилось бы в лог-флуд
+let proxyHeaderWarned = false;
+
+/**
+ * @param {Object} req - Запрос (http.IncomingMessage или express Request).
+ * @param {Object} [options]
+ * @param {boolean} [options.trustProxy] - Стоит ли перед процессом обратный
+ *   прокси, перезаписывающий `X-Real-IP` (в этом репозитории — прод-Nginx).
+ * @returns {string} Адрес клиента или '' (сокет уже разорван).
+ */
+export function clientIp(req, { trustProxy = false } = {}) {
+  const header = trustProxy ? req.headers['x-real-ip'] : undefined;
+
+  // за прокси без X-Real-IP ключом станет адрес самого прокси — один общий
+  // бакет на всех клиентов сразу: правило «одна комната на IP» пустило бы
+  // одну комнату на весь мастер, а лимит пингов стал бы общим. Падать на
+  // первом запросе нельзя (сервер должен подняться), молчать — тоже
+  if (trustProxy && !header && !proxyHeaderWarned) {
+    proxyHeaderWarned = true;
+    console.warn(
+      '[clientIp] trustProxy is on but no X-Real-IP header arrived: every ' +
+        "client now keys on the proxy's own address, one shared rate-limit " +
+        'bucket. Check `proxy_set_header X-Real-IP $remote_addr`.',
+    );
+  }
+
+  return String(header || req.socket?.remoteAddress || '').trim();
+}

package/src/lib/loadGamePackage.js

@@ -0,0 +1,122 @@
+import { access, readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { assertEngineApiCompatible } from './gamePlugin.js';
+
+// Загрузка пакета игры в Node по его собранному dist/ (Этап 4 плана
+// standalone-sdk). В браузере плагин грузится по URL из GameManifest мастера;
+// в Node URL-ов нет — оба Node-контура (headless-runner devtools/pluginLoader.js
+// и dedicated-сервер) читают манифест с диска и импортируют половины плагина
+// как обычные модули. Модуль живёт в lib/, а не в devtools/: прод-сервер не
+// должен зависеть от отладочного контура (граница из CLAUDE.md).
+//
+// entries.wasmNode — node-сборка ядра игры (конвенция core/pkg-node,
+// docs/ai/02-packaging.md). Для боевой игры она обязательна: без ядра
+// авторитетную симуляцию крутить нечем.
+
+/**
+ * @param {string} distDir - Каталог собранного пакета игры (с manifest.json)
+ *   или прямой путь к файлу манифеста.
+ * @param {Object} [options]
+ * @param {string} [options.core] - Путь к node-сборке ядра, перекрывающий
+ *   entries.wasmNode манифеста.
+ * @returns {Promise<Object>} { id, manifest, hostPlugin, clientPlugin, wasmUrl,
+ *   distDir, manifestPath }.
+ */
+export async function loadGamePackage(distDir, { core = null } = {}) {
+  // манифест под нестандартным именем нужен headless-прогону (--game
+  // <path>/manifest-variant.json); dedicated-сервер всегда даёт каталог
+  const manifestPath = distDir.endsWith('.json')
+    ? path.resolve(distDir)
+    : path.join(path.resolve(distDir), 'manifest.json');
+  const baseDir = path.dirname(manifestPath);
+  const manifest = JSON.parse(await readFile(manifestPath, 'utf8'));
+
+  assertEngineApiCompatible(manifest);
+
+  const { assetsBase } = manifest;
+  const hostPlugin = await importDefault(
+    baseDir,
+    manifest.entries.host,
+    assetsBase,
+  );
+  const clientPlugin = await importDefault(
+    baseDir,
+    manifest.entries.client,
+    assetsBase,
+  );
+
+  assertPluginMatchesManifest(manifest, {
+    host: hostPlugin,
+    client: clientPlugin,
+  });
+
+  const nodeCore = core ?? manifest.entries.wasmNode ?? null;
+
+  if (!nodeCore) {
+    throw new Error(
+      `${manifestPath}: no node build of the core — add entries.wasmNode ` +
+        `to the manifest (core/pkg-node) or pass --core <path>`,
+    );
+  }
+
+  const corePath = path.resolve(baseDir, nodeCore);
+
+  // манифест объявляет поле, но опубликованный пакет мог не довезти файл
+  // (ignore-правила срезают каталог внутри files) — без этой проверки отказ
+  // приходит сырым ERR_MODULE_NOT_FOUND из резолвера
+  try {
+    await access(corePath);
+  } catch {
+    throw new Error(
+      `${manifestPath}: entries.wasmNode points at '${nodeCore}', but ` +
+        `${corePath} does not exist — the game package was published ` +
+        `without its node core (npm run core:build:node) or pass --core <path>`,
+    );
+  }
+
+  return {
+    id: manifest.id,
+    manifest,
+    hostPlugin,
+    clientPlugin,
+    wasmUrl: pathToFileURL(corePath).href,
+    distDir: baseDir,
+    manifestPath,
+  };
+}
+
+// зеркало lib/gamePlugin.js:loadClientPlugin — манифест мог быть пересобран
+// без dist/: прогон на старом плагине даёт зелёный вердикт о том, чего в
+// сборке уже нет
+function assertPluginMatchesManifest(manifest, plugins) {
+  for (const [half, plugin] of Object.entries(plugins)) {
+    if (plugin.engineApi !== manifest.engineApi) {
+      throw new Error(
+        `game "${manifest.id}": ${half} plugin engineApi ` +
+          `v${plugin.engineApi} does not match manifest engineApi ` +
+          `v${manifest.engineApi} — stale dist/`,
+      );
+    }
+  }
+}
+
+function importDefault(baseDir, entry, assetsBase) {
+  const file = path.resolve(baseDir, stripBase(entry, assetsBase));
+
+  return import(pathToFileURL(file).href).then(module => module.default);
+}
+
+// entries.host/client — URL-ы, какими их видит браузер (`assetsBase` + путь
+// внутри пакета). На диске этой базе соответствует каталог манифеста,
+// поэтому абсолютный URL сначала обрезается до пути внутри пакета — иначе
+// path.resolve увёл бы в корень файловой системы.
+function stripBase(entry, assetsBase) {
+  if (assetsBase && entry.startsWith(assetsBase)) {
+    return entry.slice(assetsBase.length);
+  }
+
+  return entry.replace(/^\/+/, '');
+}
+
+export default loadGamePackage;

package/src/lib/offlinePlayerData.js

@@ -0,0 +1,18 @@
+// Профиль участника в контуре без мастера и auth-сервиса (headless-прогон,
+// standalone SDK, dedicated-сервер). Это не заглушка ради тишины: пустой
+// профиль и есть корректное состояние такого матча, а настоящий fetch по
+// относительному URL вне браузерной вкладки просто не разрешается.
+
+/**
+ * Фабрика fetchImpl для HostGame (hostOptions.playerDataFetch): любой запрос
+ * профиля отвечает дефолтами вместо сети — вместе с сетевыми вызовами уходят
+ * предупреждения PlayerDataSync и его ретраи.
+ * @returns {Function} fetchImpl, отдающий { rank: 0, state: null }.
+ */
+export function offlinePlayerData() {
+  return async () => ({
+    ok: true,
+    status: 200,
+    json: async () => ({ rank: 0, state: null }),
+  });
+}

package/src/standalone/index.js

@@ -0,0 +1,125 @@
+import { assertEngineApiCompatible } from '../lib/gamePlugin.js';
+import { setBootConfig } from '../client/boot.js';
+import { ensureGameShell } from '../client/views/gameShell.js';
+
+// Standalone SDK (Этап 3 плана standalone-sdk): единственная точка входа для
+// репозитория игры — `npm run dev` открывает вкладку с работающим матчем без
+// мастера, без OAuth и без экрана лобби.
+//
+// Отличия от прода (осознанные, см. plan/standalone-sdk/README.md):
+//   - хост крутится в главном потоке (inline), а не в Worker'е: HostPlugin
+//     непередаваем постмесседжем, а SDK получает живой объект плагина;
+//   - личность гостевая (ник из формы или из playerName), рейтинг и
+//     сохранение состояния выключены;
+//   - мастера нет вовсе: манифест игры собирается в памяти, каталог карт и
+//     эстафета Worker'ов не участвуют, WebRTC и module-worker'ы не нужны.
+
+/**
+ * Поднимает матч во вкладке: каркас интерфейса, inline-хост и клиент движка.
+ * @param {Object} options
+ * @param {Object} options.hostPlugin - Живой HostPlugin игры.
+ * @param {Object} options.clientPlugin - Живой ClientPlugin игры.
+ * @param {string} options.wasmUrl - URL web-сборки ядра игры (?url-импорт).
+ * @param {HTMLElement} [options.container] - Точка монтирования каркаса И
+ *   канвасов; обязана быть полноэкранной и `position: relative`.
+ * @param {string} [options.assetsBase] - База ассетов игры (звуки берутся из
+ *   `${assetsBase}sounds/`).
+ * @param {string} [options.playerName] - Задан → вход без формы авторизации.
+ * @param {string} [options.playerModel] - Модель игрока (поле authSchema).
+ * @param {Object} [options.auth] - Прочие поля авторизации игры.
+ * @param {Array} [options.startupVotes] - Ответы на initialVote, например
+ *   `[['teamChange', 'team1']]`; без них участник остаётся наблюдателем.
+ * @param {Array<string>} [options.startupCommands] - Чат-команды игры после
+ *   голосований, например `['/bot 4']`.
+ * @param {Object} [options.room] - Переопределения комнаты (map, maxPlayers,
+ *   roundTime, friendlyFire, seed).
+ * @param {boolean} [options.devMode] - room.isDevMode: рекордер и хостовый
+ *   CONSOLE-лог.
+ * @returns {Promise<Object>} `{ stop() }` — останов матча.
+ */
+export async function startStandaloneGame({
+  hostPlugin,
+  clientPlugin,
+  wasmUrl,
+  container = document.body,
+  assetsBase = '/',
+  playerName,
+  playerModel,
+  auth = {},
+  startupVotes = [],
+  startupCommands = [],
+  room = {},
+  devMode = false,
+} = {}) {
+  requireOption(hostPlugin, 'hostPlugin');
+  requireOption(clientPlugin, 'clientPlugin');
+  requireOption(wasmUrl, 'wasmUrl');
+
+  // несовпадение ENGINE_API_VERSION иначе всплыло бы где-то в середине
+  // хендшейка непрозрачной ошибкой
+  assertEngineApiCompatible(hostPlugin);
+  assertEngineApiCompatible(clientPlugin);
+
+  ensureGameShell(container);
+
+  setBootConfig({
+    mode: 'solo',
+    container,
+    manifest: buildManifest(hostPlugin, { wasmUrl, assetsBase }),
+    clientPlugin,
+    hostPlugin,
+    room: {
+      ...hostPlugin.gameConfig.roomDefaults,
+      ...room,
+      isDevMode: devMode,
+    },
+    autoAuth: playerName
+      ? pruneUndefined({ name: playerName, model: playerModel, ...auth })
+      : null,
+    startupVotes,
+    startupCommands,
+  });
+
+  // конфиг загрузки задан — дальше работает обычный клиент движка в
+  // solo-режиме (import динамический: main.js исполняется при импорте)
+  const client = await import('../client/main.js');
+
+  return {
+    stop() {
+      client.stopGame();
+    },
+  };
+}
+
+// незаданное поле — это «взять дефолт схемы», а не «отправить undefined»:
+// JSON.stringify ключ с undefined выбрасывает, и хост отвечает
+// 'Property is missing' (main.js накрывает autoAuth поверх дефолтов схемы)
+function pruneUndefined(source) {
+  return Object.fromEntries(
+    Object.entries(source).filter(([, value]) => value !== undefined),
+  );
+}
+
+// манифест-подобный объект в памяти: мастера нет, а клиент читает из
+// манифеста id/version, entries.wasm и assetsBase. entries.client/host не
+// нужны — оба плагина уже живые объекты
+function buildManifest(hostPlugin, { wasmUrl, assetsBase }) {
+  const { gameConfig } = hostPlugin;
+
+  return {
+    id: hostPlugin.id,
+    engineApi: hostPlugin.engineApi,
+    version: 'dev',
+    title: gameConfig.title ?? hostPlugin.id,
+    entries: { wasm: wasmUrl },
+    assetsBase,
+    maps: { version: 'dev', list: Object.keys(gameConfig.maps) },
+    roomDefaults: gameConfig.roomDefaults,
+  };
+}
+
+function requireOption(value, name) {
+  if (value === undefined || value === null) {
+    throw new Error(`startStandaloneGame: "${name}" is required`);
+  }
+}