vimp-engine 0.34.8 → 0.35.1

package/src/client/lib/diagnostics.js

@@ -0,0 +1,456 @@
+// Журнал клиентских ошибок (plan/client-reports, этап 3): неперехваченные
+// ошибки и отклонения страницы, ошибки Worker'а хоста, нарушения CSP и явные
+// warn/capture плагинов уходят на свой же бокс (POST /client-reports), а тот
+// пересылает их в центральный журнал.
+//
+// Репортёр не должен стать новым источником падений и шума: каждая
+// публичная функция глушит свои исключения, повтор известной ошибки — только
+// счётчик, разных ошибок за сессию не больше maxKeysPerSession, отправка —
+// пачками с дельтами счётчиков: первая через 2 с, следующие не чаще раза в
+// 10 с. console.* не перехватывается осознанно: там шум и случайные данные в
+// аргументах.
+
+// обрезки — те же числа, что у приёма на боксе (stage_2.md, контракт)
+const MAX_MESSAGE = 500;
+const MAX_STACK = 4000;
+const MAX_CODE = 64;
+const MAX_DETAILS_BYTES = 2048;
+
+// пачка: не больше 10 записей (лимит бокса) и заметно меньше его 16 КБ тела
+const MAX_BATCH_ITEMS = 10;
+const MAX_BATCH_BYTES = 15000;
+const SHRUNK_STACK = 1000;
+
+const CODE_RE = /^[a-z0-9][a-z0-9._-]{0,63}$/i;
+
+// кадр стека с позицией «:строка:колонка» — он и различает одинаковые
+// сообщения из разных мест
+const FRAME_RE = /:\d+:\d+/;
+
+// расширения браузера игрока внедряют скрипты и стили — их нарушения CSP
+// утопили бы журнал в чужом шуме
+const EXTENSION_PREFIXES = [
+  'chrome-extension:',
+  'moz-extension:',
+  'safari-extension:',
+  'safari-web-extension:',
+];
+
+// служебные значения blockedURI — не URL, берутся как есть
+const CSP_KEYWORDS = new Set(['', 'inline', 'eval', 'wasm-eval', 'data', 'blob']);
+
+const encoder = new TextEncoder();
+
+function byteLength(str) {
+  return encoder.encode(str).length;
+}
+
+function makeSessionId() {
+  try {
+    if (typeof crypto !== 'undefined' && crypto.randomUUID) {
+      return crypto.randomUUID();
+    }
+  } catch {
+    // нет безопасного контекста — ниже фолбэк
+  }
+
+  return (
+    Math.random().toString(16).slice(2) + Math.random().toString(16).slice(2)
+  );
+}
+
+function safeString(value) {
+  try {
+    return String(value);
+  } catch {
+    return '[unprintable]';
+  }
+}
+
+function topFrame(stack) {
+  if (!stack) {
+    return '';
+  }
+
+  return stack.split('\n').find(line => FRAME_RE.test(line))?.trim() ?? '';
+}
+
+// снимок деталей: простой объект ≤ 2048 байт JSON, иначе пометка усечения
+function normalizeDetails(details) {
+  if (details === null || details === undefined) {
+    return null;
+  }
+
+  try {
+    const json = JSON.stringify(details);
+
+    if (
+      typeof details !== 'object' ||
+      json === undefined ||
+      byteLength(json) > MAX_DETAILS_BYTES
+    ) {
+      return { truncated: true };
+    }
+
+    return JSON.parse(json);
+  } catch {
+    return { truncated: true };
+  }
+}
+
+// URL без query и hash: в них бывают токены и прочие личные данные
+function stripUrl(value) {
+  const str = typeof value === 'string' ? value : '';
+
+  if (CSP_KEYWORDS.has(str)) {
+    return str;
+  }
+
+  try {
+    const url = new URL(str);
+
+    return url.origin + url.pathname;
+  } catch {
+    return str.split(/[?#]/)[0];
+  }
+}
+
+function isExtensionUrl(value) {
+  return (
+    typeof value === 'string' &&
+    EXTENSION_PREFIXES.some(prefix => value.startsWith(prefix))
+  );
+}
+
+// транспорт по умолчанию: beacon переживает закрытие вкладки; нет его или
+// очередь переполнена — fetch с keepalive. Ответ не читается
+function defaultSend(url, json) {
+  if (typeof navigator !== 'undefined' && navigator.sendBeacon) {
+    try {
+      if (navigator.sendBeacon(url, new Blob([json], { type: 'application/json' }))) {
+        return;
+      }
+    } catch {
+      // старые Chromium бросали SecurityError на Blob с application/json
+      // (crbug.com/490015) — тогда запасной fetch
+    }
+  }
+
+  fetch(url, {
+    method: 'POST',
+    body: json,
+    headers: { 'content-type': 'application/json' },
+    keepalive: true,
+    credentials: 'same-origin',
+  }).catch(() => {});
+}
+
+function noop() {}
+
+/**
+ * Создаёт репортёр клиентских ошибок.
+ * @param {Object} opts
+ * @param {string|null} opts.url - адрес приёма; null — репортёр выключен
+ * @param {Object} [opts.context] - { mode, role, gameId, gameVersion, page, userAgent }
+ * @param {Function} [opts.send] - (url, json) => void; по умолчанию beacon/fetch
+ * @param {Function} [opts.now]
+ * @param {number} [opts.maxKeysPerSession=50]
+ * @param {number} [opts.flushDelayMs=2000] - задержка первой отправки
+ * @param {number} [opts.minIntervalMs=10000] - интервал между отправками по
+ *   таймеру; прямой flush() его не ждёт
+ * @returns {{ capture, warn, flush, setContext, install }}
+ */
+export function createDiagnostics({
+  url,
+  context = {},
+  send = defaultSend,
+  now = Date.now,
+  maxKeysPerSession = 50,
+  flushDelayMs = 2000,
+  minIntervalMs = 10000,
+} = {}) {
+  if (!url) {
+    return {
+      capture: noop,
+      warn: noop,
+      flush: noop,
+      setContext: noop,
+      install: () => noop,
+    };
+  }
+
+  const sessionId = makeSessionId();
+  const ctx = { ...context };
+
+  // ключ дедупа → запись со счётчиками: count — всего за сессию, sentCount —
+  // сколько уже отправлено, deltaFirstAt — первое время в неотправленной дельте
+  const records = new Map();
+
+  let capWarned = false;
+  let timer = null;
+  let lastSentAt = null;
+
+  // ошибка внутри самого репортёра не должна порождать новый отчёт
+  let busy = false;
+
+  function record(item) {
+    const key = `${item.source}|${item.kind}|${item.code ?? item.message}|${topFrame(item.stack)}`;
+    const at = now();
+    const known = records.get(key);
+
+    if (known) {
+      known.count += 1;
+      known.lastAt = at;
+
+      if (known.count - known.sentCount === 1) {
+        known.deltaFirstAt = at;
+      }
+    } else {
+      if (records.size >= maxKeysPerSession) {
+        if (!capWarned) {
+          capWarned = true;
+          console.warn('[vimp] diagnostics: session cap reached');
+        }
+
+        return;
+      }
+
+      records.set(key, {
+        item,
+        count: 1,
+        sentCount: 0,
+        deltaFirstAt: at,
+        lastAt: at,
+      });
+    }
+
+    schedule();
+  }
+
+  function schedule() {
+    if (timer !== null) {
+      return;
+    }
+
+    // первая отправка — через flushDelayMs, следующие — не чаще
+    // minIntervalMs: бокс режет приём лимитом запросов с адреса, и 429
+    // молча съедал бы приросты счётчиков непрерывно повторяющейся ошибки
+    const sinceLast = lastSentAt === null ? Infinity : now() - lastSentAt;
+
+    timer = setTimeout(flush, Math.max(flushDelayMs, minIntervalMs - sinceLast));
+  }
+
+  function guarded(fn) {
+    if (busy) {
+      return;
+    }
+
+    busy = true;
+
+    try {
+      fn();
+    } catch {
+      // репортёр молчит о своих сбоях — иначе он сам стал бы шумом
+    } finally {
+      busy = false;
+    }
+  }
+
+  function capture(error, { source = 'client', kind = 'error' } = {}) {
+    guarded(() => {
+      const raw =
+        error !== null && error !== undefined && error.message !== undefined
+          ? error.message
+          : error;
+      const stack =
+        error !== null && error !== undefined && typeof error.stack === 'string'
+          ? error.stack.slice(0, MAX_STACK)
+          : null;
+
+      record({
+        kind,
+        source,
+        code: null,
+        message: safeString(raw).slice(0, MAX_MESSAGE),
+        stack,
+        details: null,
+      });
+    });
+  }
+
+  function warn(code, details = null, { source = 'plugin', message } = {}) {
+    guarded(() => {
+      const safeCode =
+        typeof code === 'string' && CODE_RE.test(code)
+          ? code.slice(0, MAX_CODE)
+          : 'invalid-code';
+      const stack = new Error().stack;
+
+      record({
+        kind: 'warn',
+        source,
+        code: safeCode,
+        message: safeString(message ?? safeCode).slice(0, MAX_MESSAGE),
+        stack: typeof stack === 'string' ? stack.slice(0, MAX_STACK) : null,
+        details: normalizeDetails(details),
+      });
+    });
+  }
+
+  // нарушение CSP (только в проде: CSP ставит мастер) — одно правило,
+  // сработавшее тысячу раз, одна запись со счётчиком
+  function reportCsp(event) {
+    guarded(() => {
+      if (isExtensionUrl(event.blockedURI) || isExtensionUrl(event.sourceFile)) {
+        return;
+      }
+
+      const blocked = stripUrl(event.blockedURI);
+
+      record({
+        kind: 'csp',
+        source: 'client',
+        code: null,
+        message: `CSP ${event.effectiveDirective} blocked ${blocked}`.slice(
+          0,
+          MAX_MESSAGE,
+        ),
+        stack: null,
+        details: normalizeDetails({
+          directive: event.effectiveDirective,
+          disposition: event.disposition,
+          sourceFile: stripUrl(event.sourceFile),
+          line: event.lineNumber,
+          column: event.columnNumber,
+          sample: (event.sample || '').slice(0, 40),
+        }),
+      });
+    });
+  }
+
+  function body(items) {
+    return JSON.stringify({ v: 1, sessionId, context: ctx, items });
+  }
+
+  // пачка больше предела: сперва без деталей, затем с короткими стеками;
+  // не помогло — по одной записи
+  function sendBatch(items) {
+    let json = body(items);
+
+    if (byteLength(json) > MAX_BATCH_BYTES) {
+      items = items.map(item => ({ ...item, details: null }));
+      json = body(items);
+    }
+
+    if (byteLength(json) > MAX_BATCH_BYTES) {
+      items = items.map(item => ({
+        ...item,
+        stack: item.stack ? item.stack.slice(0, SHRUNK_STACK) : item.stack,
+      }));
+      json = body(items);
+    }
+
+    if (byteLength(json) > MAX_BATCH_BYTES && items.length > 1) {
+      for (const item of items) {
+        send(url, body([item]));
+      }
+
+      return;
+    }
+
+    send(url, json);
+  }
+
+  // уходят только записи, у которых с прошлой отправки вырос счётчик, —
+  // приростом, а не итогом (бокс складывает)
+  function flush() {
+    if (timer !== null) {
+      clearTimeout(timer);
+      timer = null;
+    }
+
+    guarded(() => {
+      const items = [];
+
+      for (const rec of records.values()) {
+        const delta = rec.count - rec.sentCount;
+
+        if (delta > 0) {
+          items.push({
+            ...rec.item,
+            count: delta,
+            firstAt: rec.deltaFirstAt,
+            lastAt: rec.lastAt,
+          });
+          rec.sentCount = rec.count;
+        }
+      }
+
+      if (items.length > 0) {
+        lastSentAt = now();
+      }
+
+      for (let i = 0; i < items.length; i += MAX_BATCH_ITEMS) {
+        sendBatch(items.slice(i, i + MAX_BATCH_ITEMS));
+      }
+    });
+  }
+
+  // смена контекста (игра, роль): накопленное уходит СО СВОИМ контекстом —
+  // иначе отчёт игры A, отправленный уже под игрой B, получил бы на боксе
+  // отпечаток и source maps игры B
+  function setContext(patch) {
+    try {
+      if (Object.keys(patch).some(key => ctx[key] !== patch[key])) {
+        flush();
+      }
+
+      Object.assign(ctx, patch);
+    } catch {
+      // контекст — вспомогательный, его сбой отчёты не останавливает
+    }
+  }
+
+  /**
+   * Вешает глобальные перехватчики.
+   * @param {Window} [target]
+   * @returns {Function} снятие перехватчиков
+   */
+  function install(target = window) {
+    // ошибки загрузки <img>/<script> приходят обычным Event на элементе —
+    // это сбои ресурсов, а не исключения
+    const onError = event => {
+      if (typeof ErrorEvent !== 'undefined' && event instanceof ErrorEvent) {
+        capture(event.error ?? event.message, { kind: 'error' });
+      }
+    };
+    const onRejection = event => {
+      capture(event.reason, { kind: 'rejection' });
+    };
+    const onPageHide = () => flush();
+    const doc = target.document;
+
+    try {
+      target.addEventListener('error', onError);
+      target.addEventListener('unhandledrejection', onRejection);
+      target.addEventListener('pagehide', onPageHide);
+      // событие всплывает к документу
+      doc?.addEventListener('securitypolicyviolation', reportCsp);
+    } catch {
+      // нет цели — просто не ловим
+    }
+
+    return () => {
+      try {
+        target.removeEventListener('error', onError);
+        target.removeEventListener('unhandledrejection', onRejection);
+        target.removeEventListener('pagehide', onPageHide);
+        doc?.removeEventListener('securitypolicyviolation', reportCsp);
+      } catch {
+        // снятие не должно ронять вызывающего
+      }
+    };
+  }
+
+  return { capture, warn, flush, setContext, install };
+}

package/src/client/main.js

@@ -45,6 +45,7 @@ import {
 import { createContextTracker } from './lib/contextTracker.js';
 import { createLocalPlayer } from './lib/localPlayer.js';
 import { createAccolades } from './lib/accolades.js';
+import { createDiagnostics } from './lib/diagnostics.js';
 import { dispatchSocketMessage } from './lib/socketDispatch.js';
 import { pickActiveGame, isGameAvailable } from './lib/pickActiveGame.js';
 import { readCoreAbi, dispatchCoreOp, ABI_UNKNOWN } from '../lib/coreAbi.js';
@@ -81,6 +82,9 @@ import LobbyAuthCtrl from './components/controller/LobbyAuth.js';
 import GamesModel from './components/model/Games.js';
 import GamesView from './components/view/Games.js';
 import GamesCtrl from './components/controller/Games.js';
+import ClientReportsModel from './components/model/ClientReports.js';
+import ClientReportsView from './components/view/ClientReports.js';
+import ClientReportsCtrl from './components/controller/ClientReports.js';
 import BakingProvider from './providers/BakingProvider.js';
 import DependencyProvider from './providers/DependencyProvider.js';
 import { HOT_FLAGS } from '../config/opcodes.js';
@@ -120,6 +124,7 @@ let gameStyleNode = null;
 // переключении в лобби
 function bindActiveGame(manifest, plugin) {
   activeGameManifest = manifest;
+  syncDiagnosticsGame();
   clientPlugin = plugin;
 
   if (!gameStyleNode) {
@@ -147,6 +152,32 @@ const boot = injectedBoot ?? (await resolveBootConfig());
 const bootMode = boot.mode;
 const isLobbyMode = bootMode === 'lobby';
 
+// журнал клиентских ошибок (plan/client-reports): ставится как можно
+// раньше, чтобы ловить и сбои самого старта. Лобби и dedicated шлют на
+// свой бокс; SDK (solo) — только если встраивающий передал reportUrl
+const diagnostics = createDiagnostics({
+  url:
+    bootMode === 'solo' ? (boot.reportUrl ?? null) : lobbyConfig.clientReportUrl,
+  context: {
+    mode: bootMode,
+    role: 'client',
+    gameId: null,
+    gameVersion: null,
+    page: location.pathname.slice(0, 128),
+    userAgent: navigator.userAgent.slice(0, 256),
+  },
+});
+
+diagnostics.install(window);
+
+// игра в контексте отчётов — после каждой смены активного манифеста
+function syncDiagnosticsGame() {
+  diagnostics.setContext({
+    gameId: activeGameManifest?.id ?? null,
+    gameVersion: activeGameManifest?.version ?? null,
+  });
+}
+
 // точка монтирования игрового интерфейса: в lobby-режиме разметку даёт pug и
 // каркас ничего не делает, в solo — собирается в контейнере SDK
 const gameContainer = boot.container ?? document.body;
@@ -157,6 +188,7 @@ try {
   if (boot.manifest) {
     // SDK передаёт манифест-подобный объект в памяти — каталога мастера нет
     activeGameManifest = boot.manifest;
+    syncDiagnosticsGame();
     gamesManifest = [activeGameManifest];
   } else {
     gamesManifest = await manifestPromise;
@@ -170,6 +202,7 @@ try {
     try {
       // недоступная игра активной быть не может (lib/pickActiveGame.js)
       activeGameManifest = pickActiveGame(gamesManifest, boot.gameId);
+      syncDiagnosticsGame();
     } catch (e) {
       // «каталог непустой, но играбельного в нём нет» (движок обновили, все
       // опубликованные игры просят возможность, которой в нём уже нет) — для
@@ -436,6 +469,14 @@ socketMethods[PS_CONFIG_DATA] = async data => {
       // part, объявивший сервис в componentDependencies, строит URL сам —
       // движок не знает ни имён файлов, ни их раскладки внутри пакета
       assetsBase: activeGameManifest.assetsBase,
+      // журнал клиентских ошибок для партов игры (plan/client-reports):
+      // warn(code, details) — своё предупреждение, capture(error) — пойманная
+      // ошибка. Сервис опционален: игра не пишет его в requires
+      diagnostics: {
+        warn: (code, details) =>
+          diagnostics.warn(code, details, { source: 'plugin' }),
+        capture: error => diagnostics.capture(error, { source: 'plugin' }),
+      },
     };
 
     // если есть данные для запекания компонентов
@@ -1430,6 +1471,7 @@ function handleDisconnect(closeCode) {
   hostController?.destroy();
   hostConnections = null;
   hostController = null; // останавливает и reconnect-петлю сигналинга
+  diagnostics.setContext({ role: 'client' });
   hostRegistration = null;
 
   // solo: хост крутится в этом же потоке — его таймеры переживут матч
@@ -1593,8 +1635,11 @@ async function connectAsHost(room) {
     console.warn('[worker] master manifest unavailable, using bundled:', e);
   }
 
+  diagnostics.setContext({ role: 'host' });
+
   hostController = new HostController(room, {
     workerUrl,
+    diagnostics,
     onReady: readyMsg => {
       currentMapName = readyMsg?.mapName;
 
@@ -2288,6 +2333,17 @@ function initLobby() {
   // запись — auth-сервис, перечитывая роль из БД
   games.setAdmin(lobbyAuthModel.getRole() === 'admin');
 
+  // журнал клиентских ошибок (plan/client-reports, этап 5): кнопку «Errors»
+  // видит только админ; фильтр по игре — каталог вкладки
+  const clientReportsModel = new ClientReportsModel(lobbyConfig.clientReports, () =>
+    lobbyAuthModel.getToken(),
+  );
+  const clientReportsView = new ClientReportsView(clientReportsModel, lobbyConfig.clientReports);
+  const clientReports = new ClientReportsCtrl(clientReportsModel, clientReportsView);
+
+  clientReportsView.setGames([...gamesById.values()]);
+  clientReports.setAdmin(lobbyAuthModel.getRole() === 'admin');
+
   // «Test»: манифест застейдженной версии кладётся в каталог вкладки, и
   // админ поднимает по нему комнату обычной кнопкой Create server
   games.publisher.on('staged', ({ manifest }) => {

package/src/client/network/HostController.js

@@ -20,6 +20,24 @@ const SWAP_QUEUE_LIMIT = 2000;
 // предел ожидания ответа Worker'а на отладочный запрос (dump/запись)
 const DEBUG_TIMEOUT = 5000;
 
+// ErrorEvent Worker'а в главном потоке: `error` там null (исключение между
+// потоками не клонируется) — есть только message и filename/lineno/colno.
+// Кадр собирается из них: без него у отчёта нет верхнего кадра, то есть ни
+// различимого отпечатка, ни расшифровки по source map. Пустой message
+// (Worker не загрузился) бокс отбросил бы — отсюда запасной текст
+function workerErrorReport(event) {
+  if (typeof event?.error?.stack === 'string') {
+    return event.error;
+  }
+
+  const message = event?.message || 'Worker error';
+  const stack = event?.filename
+    ? `${message}\n    at ${event.filename}:${event.lineno ?? 0}:${event.colno ?? 0}`
+    : null;
+
+  return { message, stack };
+}
+
 export default class HostController {
   /**
    * @param {Object} room - настройки комнаты (имя/карта/лимит/таймеры).
@@ -35,14 +53,18 @@ export default class HostController {
    *   (WASM/конфиг): комната не поднялась, нужно вернуть пользователя в лобби.
    * @param {Function} [opts.onMapChange] - смена карты в комнате (голосование/
    *   таймер) — для актуализации mapName у мастера.
+   * @param {Object} [opts.diagnostics] - журнал клиентских ошибок
+   *   (lib/diagnostics.js, plan/client-reports): туда уходят ошибки Worker'а.
    */
   constructor(
     room,
-    { workerFactory, workerUrl, onReady, onError, onMapChange } = {},
+    { workerFactory, workerUrl, onReady, onError, onMapChange, diagnostics } = {},
   ) {
     this._room = room;
     this._workerFactory = workerFactory;
+    this._diagnostics = diagnostics ?? null;
     this._worker = this._createWorker(workerUrl);
+    this._watchWorkerErrors(this._worker);
 
     this._onReady = onReady;
     this._onError = onError;
@@ -76,6 +98,22 @@ export default class HostController {
         });
   }
 
+  // журнал клиентских ошибок (plan/client-reports): неперехваченная ошибка
+  // Worker'а приходит сюда. preventDefault не зовётся — консольный вывод
+  // браузера остаётся как есть
+  _watchWorkerErrors(worker) {
+    worker.onerror = event =>
+      this._diagnostics?.capture(workerErrorReport(event), {
+        source: 'host-worker',
+        kind: 'worker',
+      });
+    worker.onmessageerror = () =>
+      this._diagnostics?.capture('messageerror', {
+        source: 'host-worker',
+        kind: 'worker',
+      });
+  }
+
   // регистрирует клиента и (при готовности) поднимает его соединение в Worker'е
   open(socketId, { onMessage, onClose }) {
     this._deliveries.set(socketId, { onMessage, onClose });
@@ -311,18 +349,34 @@ export default class HostController {
     );
 
     next.onmessage = e => this._onNextWorkerMessage(e.data);
+    this._watchWorkerErrors(next);
     next.postMessage({ type: 'init', room: this._room, handoff: state });
   }
 
-  // сообщения нового Worker'а до завершения свопа: ждём только ready/error
+  // сообщения нового Worker'а до завершения свопа: ждём только ready/error,
+  // но его сбои (в том числе провал init) попадают в журнал ошибок так же,
+  // как у рабочего Worker'а
   _onNextWorkerMessage(msg) {
     if (msg.type === 'ready') {
       this._finishSwap();
     } else if (msg.type === 'error') {
+      this._reportWorkerMessage(msg, 'error');
       this._abortSwap(msg.message);
+    } else if (msg.type === 'diagnostic') {
+      this._reportWorkerMessage(msg, msg.kind);
     }
   }
 
+  // сбой Worker'а, присланный сообщением ('error' — провал init,
+  // 'diagnostic' — необработанный reject): стек — самого Worker'а, а не
+  // главного потока
+  _reportWorkerMessage(msg, kind) {
+    this._diagnostics?.capture(
+      { message: msg.message, stack: msg.stack ?? null },
+      { source: 'host-worker', kind },
+    );
+  }
+
   // новый Worker готов: переподключить клиентов, дослать накопленное,
   // завершить эстафету и погасить старый Worker
   _finishSwap() {
@@ -383,9 +437,14 @@ export default class HostController {
         break;
 
       case 'error':
+        this._reportWorkerMessage(msg, 'error');
         this._onError?.(msg);
         break;
 
+      case 'diagnostic':
+        this._reportWorkerMessage(msg, msg.kind);
+        break;
+
       case 'map_changed':
         this._onMapChange?.(msg.mapName);
         break;