quickblox 2.23.0 → 2.23.1-beta.4

package/__getStats-mediaType-guard-fix-plan.md

@@ -0,0 +1,340 @@
+# SDK fix plan — unhandled TypeError in `_getStats` (`s.remote[mediaType].bitrate`)
+
+**Клон:** `C:\___QuickBlox\05-quickblox-javascript-sdk-internal`
+**База:** ветка `develop`, версия **`2.23.0-beta.3`** (= версия, опубликованная на проекте
+Q-Consultation; именно она крашится в логе QC-1682).
+**Целевая ветка фикса:** отдельная от `develop` (имя создаёт пользователь; Claude
+объявляет «приступаю к ветке X» → пользователь создаёт → «начинай»).
+**Файл:** `src/modules/webrtc/qbRTCPeerConnection.js`
+**Происхождение:** диагностика логов QC-1682 (P2P web-провайдер, видео отсутствует).
+Полный разбор лога — `03-q-consultation-premium/__ai-work-log/bug-batch-2026-05-28-brightside/logs/QC-1682-log-analysis-2026-05-30.md`.
+
+> Примечание: ранняя версия этого плана была сохранена в клоне 01
+> (`__getStats-mediaType-guard-fix-plan.md`, ветка `rc/...-QC-1454`, beta.2). Она
+> устарела — выполняем в клоне 05. Тот файл можно удалить отдельно.
+
+---
+
+## 1. Симптом (из лога QC-1682)
+
+В консоли web-провайдера 7 раз подряд:
+```
+[Error] Unhandled Promise Rejection: TypeError: undefined is not an object
+(evaluating '(e=s.remote[r.mediaType]).bitrate=c(r,a,!1)')
+    (anonymous function) (vendors...js:2:2190970)
+    forEach
+    forEachWrapper
+    forEach
+```
+
+## 2. Точное место (верифицировано в клоне 05)
+
+`src/modules/webrtc/qbRTCPeerConnection.js`, функция `_getStats` (объявлена строкой 521),
+внутри `peer.getStats(null).then(... results.forEach(function (result) {...}))`.
+Строки **547-564** в клоне 05 **идентичны** клону 01 (сверено 2026-05-30).
+
+```js
+// строки 522-533 — заранее заведённые ключи:
+var statistic = {
+    'local':  { 'audio': {}, 'video': {}, 'candidate': {} },
+    'remote': { 'audio': {}, 'video': {}, 'candidate': {} }
+};
+...
+// строки 547-555 — падающая ветка (remote / inbound-rtp):
+if (result.bytesReceived && result.type === 'inbound-rtp') {
+    item = statistic.remote[result.mediaType];          // ← (1) item может стать undefined
+    item.bitrate = _getBitratePerSecond(result, lastResults, false);  // ← (2) КРАШ: (undefined).bitrate
+    item.bytesReceived = result.bytesReceived;
+    item.packetsReceived = result.packetsReceived;
+    item.timestamp = result.timestamp;
+    if (result.mediaType === 'video' && result.framerateMean) {
+        item.framesPerSecond = Math.round(result.framerateMean * 10) / 10;
+    }
+}
+// строки 556-564 — симметричная local / outbound-rtp ветка с тем же дефектом:
+else if (result.bytesSent && result.type === 'outbound-rtp') {
+    item = statistic.local[result.mediaType];           // ← тот же риск
+    item.bitrate = _getBitratePerSecond(result, lastResults, true);
+    ...
+}
+```
+
+Сопоставление с минифик-стеком (1:1): `s`=`statistic`, `r`=`result`,
+`c`=`_getBitratePerSecond`, `a`=`lastResults`, `!1`=`false`, внешний `forEach` = `results.forEach`.
+
+## 3. Корневая причина (верифицировано)
+
+`statistic.remote` содержит **только** ключи `audio` / `video` / `candidate` (строки 528-532).
+В ветке `inbound-rtp` код индексирует `statistic.remote[result.mediaType]` **без проверки**,
+что `result.mediaType` — один из этих ключей. Если у inbound-rtp report
+`result.mediaType` равен `undefined` или нестандартному значению — `statistic.remote[undefined]`
+=== `undefined`, и следующая строка делает `(undefined).bitrate = ...` → `TypeError`.
+
+**Почему mediaType бывает undefined:** поле `RTCStats.mediaType` устаревшее и заменено на
+`kind` в современном webrtc-stats. Safari/iOS WebKit может не заполнять `mediaType` в
+inbound-rtp статистике → индекс по `undefined`. В логе QC-1682 ровно этот сценарий
+(P2P web↔iOS-mobile).
+
+Это **НЕ корень отсутствия видео** в QC-1682 (тот корень — отсутствие H.264 в SDP,
+backend-задача). Это **самостоятельный дефект getStats SDK**: краш при отсутствующем/
+нестандартном `mediaType`. Он будет всплывать в любом звонке, где это поле не заполнено,
+и при этом **прерывает весь `forEach` и роняет промис** (`getStats(null).then(...)` без
+catch на этом уровне → unhandled rejection) — то есть теряется ВЕСЬ stats-репорт за тик,
+не только проблемный трек. Это затрагивает и потребителей `_onCallStatsReport` (на нём
+у Q-Consultation построены QC-1645/QC-1475 — оценка «живости» видео).
+
+**Стабильность кода:** строка `item = statistic.remote[result.mediaType]` присутствует
+минимум с релиза 2.12.5 и не менялась. Guard никогда не добавлялся.
+
+**Допущение про beta.3 — СНЯТО.** Клон 05 = ровно `2.23.0-beta.3` (версия с бага), код
+строк 547-564 подтверждён идентичным. В клоне 01 (beta.2) это было непроверенным риском —
+здесь его нет.
+
+## 4. План правки (РЕШЕНО 2026-05-30: guard + `kind`-fallback, вариант 1)
+
+**Scope:** guard (убрать краш) + `mediaType || kind` fallback (заполнить Safari-stats).
+Оба изменения — в одном `[QC-1682]`-PR.
+
+> **СОСТОЯНИЕ КОДА на 2026-05-31 (сверено с `qbRTCPeerConnection.js`):** другой агент уже
+> применил БОЛЬШУЮ часть: (1) логика вынесена из inline-`forEach` в отдельную функцию
+> `_applyStatReport(statistic, result, lastResults)` (строка 551) — это и есть T2-рефактор,
+> делающий код тестируемым; (2) **guard `if (item) {...} else { traceWarning }` уже стоит**
+> в обеих ветках (inbound строки 557-567, outbound 571-581). **ОСТАЛОСЬ ТОЛЬКО `kind`-fallback.**
+> Блоки кода ниже — это ЦЕЛЕВОЕ состояние; фактическая правка = добавить fallback к уже
+> существующему `_applyStatReport`, а не писать guard заново.
+
+### Ключевая деталь fallback — нормализовать тип ОДИН раз в локальную переменную
+
+`result.mediaType` используется в обеих ветках **дважды**: для индексации
+(`statistic.remote[result.mediaType]`) И для проверки framerate
+(`result.mediaType === 'video'`, строки 114/137 исходника). Если применить fallback только
+к индексации, то на Safari (где есть только `result.kind`) индекс заработает, а проверка
+`result.mediaType === 'video'` останется ложной → `framesPerSecond` не запишется.
+Поэтому fallback вычисляем **один раз** в `var mediaType` и используем его в обоих местах:
+
+```js
+var mediaType = result.mediaType || result.kind;   // ← в начале forEach-колбэка, рядом с `var item;`
+```
+
+(`var item;` уже объявлен в `_applyStatReport` строкой 552 — добавляем `mediaType` туда же.)
+
+### Фактическая правка в `_applyStatReport` (4 точечных замены)
+
+В существующей функции `_applyStatReport` (строка 551):
+
+1. **Строка 552** — добавить вычисление `mediaType` сразу после `var item;`:
+   ```js
+   var item;
+   var mediaType = result.mediaType || result.kind;
+   ```
+2. **Строка 555** (inbound индексация): `statistic.remote[result.mediaType]`
+   → `statistic.remote[mediaType]`
+3. **Строка 562** (inbound framerate): `if (result.mediaType === 'video' ...`
+   → `if (mediaType === 'video' ...`
+4. **Строка 569** (outbound индексация): `statistic.local[result.mediaType]`
+   → `statistic.local[mediaType]`
+5. **Строка 576** (outbound framerate): `if (result.mediaType === 'video' ...`
+   → `if (mediaType === 'video' ...`
+6. (косметика, опц.) traceWarning-строки 566/580: текст `unknown mediaType:` +
+   `result.mediaType` → `unknown mediaType/kind:` + `mediaType` (чтобы лог показывал
+   уже нормализованное значение).
+
+**Целевое состояние inbound-ветки (557-567):**
+```js
+if (result.bytesReceived && result.type === 'inbound-rtp') {
+    item = statistic.remote[mediaType];
+
+    if (item) {
+        item.bitrate = _getBitratePerSecond(result, lastResults, false);
+        item.bytesReceived = result.bytesReceived;
+        item.packetsReceived = result.packetsReceived;
+        item.timestamp = result.timestamp;
+        if (mediaType === 'video' && result.framerateMean) {
+            item.framesPerSecond = Math.round(result.framerateMean * 10) / 10;
+        }
+    } else {
+        Helpers.traceWarning('_getStats: skipping inbound-rtp report with unknown mediaType/kind: ' + mediaType);
+    }
+}
+```
+Outbound-ветка (568-581) — симметрично (`statistic.local[mediaType]`,
+`mediaType === 'video'`, `isLocal=true`).
+
+**Эффект fallback:** на Safari/iOS (`result.mediaType === undefined`, но
+`result.kind === 'video'/'audio'`) `mediaType` теперь резолвится в корректный ключ →
+`statistic.remote.video` / `.audio` заполняются → QC-1645/QC-1475 получают stats.
+**guard остаётся** как страховка: если у report'а нет ни `mediaType`, ни `kind` (или
+значение нестандартное, напр. `'data'`/`'application'`) — `item` будет `undefined`, и
+тело пропускается с diagnostic-warn вместо краша.
+
+**Почему `Helpers.traceWarning`, а не свой `if (config.debug) console.warn`:**
+- Файл уже импортирует `Helpers = require('./qbWebRTCHelpers')` (строка 2 в require-блоке),
+  `traceWarning` используется в SDK широко.
+- `traceWarning` сам гейтит на `config.debug` (qbWebRTCHelpers.js:26-29) — в production
+  под `config.debug=false` лог молчит, никакого шума.
+- В debug-сессиях (диагностика следующих QC-инцидентов) команда сразу увидит причину
+  пропуска report без поиска guard'а в коде.
+
+### Что НЕ трогаем
+
+- Ветки `local-candidate` / `remote-candidate` / `track` (565-593) — там `item`
+  присваивается фиксированным ключам (`statistic.local.candidate`, `statistic.remote.video`),
+  всегда существующим. Краш невозможен — guard не нужен. **(Утверждение
+  предварительное; перед началом реализации перечитать строки 565-593 и явно
+  подтвердить в commit-сообщении.)**
+- `_getBitratePerSecond` / `_getFramesPerSecond` — не меняем.
+- `package.json` версию — НЕ бамаем без отдельного решения (правило DO NOT).
+- Грязные в `develop` файлы (`STATE.md`, `DECISIONS.md`, `__ai-work-log/assessments/`) —
+  не трогаем, они не относятся к фиксу (AI-tooling). Их не коммитим в ветку фикса.
+
+### Что НЕ делаем в этом PR (зафиксировано как follow-up)
+
+- **`result.mediaType || result.kind` fallback** — отдельный follow-up SDK-тикет.
+  Контекст: поле `mediaType` deprecated в текущем W3C WebRTC stats spec, заменено на
+  `kind` (значения те же — `'audio'`/`'video'`). Старые Chrome/FF отдавали `mediaType`,
+  современные браузеры отдают оба ради backward-compat, **Safari/WebKit в части report'ов
+  отдаёт только `kind`** — это и есть истинная причина `mediaType === undefined` в логе
+  QC-1682. Текущий guard устраняет краш и unhandled rejection (P0), но Safari-stats
+  по-прежнему будут пустыми (P1 — функциональная потеря для QC-1645/QC-1475 «оценка
+  живости видео», которые читают `_onCallStatsReport`).
+  - Почему не делаем сейчас: fallback **меняет наблюдаемое поведение**
+    (`statistic.remote.video` для Safari начнёт заполняться там, где раньше был
+    `undefined`), а guard — нет (для валидного `mediaType` идентичный путь). Это разный
+    риск, разный scope, разный test plan. Не смешиваем.
+  - Что делаем: **РЕШЕНИЕ (2026-05-30): отдельного тикета НЕТ — всё в рамках QC-1682.**
+    Если fallback тоже делаем (см. §8 п.1), он идёт тем же `[QC-1682]`-коммитом/в том же
+    PR, что и guard. Если откладываем — фиксируем как follow-up внутри QC-1682, без
+    нового номера.
+
+## 5. Тестирование — реалистичная оценка (ВАЖНО, честно)
+
+`_getStats` — **приватная функция** (`function _getStats(...)` в модуле, НЕ на прототипе,
+НЕ экспортируется). `QB-WebRTCSpec.js` (79 строк) — **integration-тест**: реальный
+`QB.init` + `QB.chat.connect` к серверу (креды из `spec/config`), и почти всё `pending()`
+под Node (`WebRTC API isn't supported outside of the browser`). getStats там НЕ покрыт.
+
+Из этого следует: **изолированный юнит-тест на `_getStats` без вмешательства в файл
+или новой dev-зависимости невозможен**, а integration-путь требует браузера + живого
+`RTCPeerConnection` и не воспроизводит `mediaType=undefined` детерминированно. Варианты,
+что реально доступно:
+
+- **Вариант T1 (минимум, рекомендую для этого точечного guard'а):** без нового авто-теста.
+  Обоснование: правка — чистый guard + warn, не меняет поведение для валидных `mediaType`
+  (`item` существует → идентичный путь); меняет только путь `mediaType ∉ {audio,video}`
+  (раньше краш → теперь skip + traceWarning). Проверка — `lint` + существующие
+  `test:pr` (регрессия, что ничего не сломали) + ручная сверка `git diff`.
+- **Вариант T1.5 (рассмотреть, если когда-то понадобится покрытие `_getStats`):** юнит-тест
+  через `rewire` / `proxyquire` — эти библиотеки умеют доставать приватные функции из
+  модуля через `__get__` API, **не меняя production-код**. Файл `qbRTCPeerConnection.js`
+  не модифицируется, тест получает реальный `_getStats` и проверяет его на fake-peer'е
+  с `getStats: () => Promise.resolve([{ type: 'inbound-rtp', bytesReceived: 100,
+  mediaType: undefined }])`. Покрытие 100% настоящего кода без рефактора. **Цена:**
+  `rewire` — новая dev-зависимость, требует отдельного approval (CLAUDE.md DO NOT
+  запрещает `npm install` без подтверждения). **Не для этого PR**: если ставим rewire —
+  это отдельный шаг «инфраструктура тестов», не часть guard-фикса.
+- **Вариант T2 (если нужен авто-тест без новых dev-зависимостей):** вынести «нормализатор
+  одного stats-report» в чистую экспортируемую утилиту (напр.
+  `applyStatReport(statistic, result, lastResults)`), написать на неё jasmine-тест в Node
+  (без браузера) с кейсами `mediaType: 'video' | 'audio' | undefined | 'application'`.
+  Это уже **рефактор-фикс**, шире guard'а — отдельное решение пользователя (риск задеть
+  рабочий код ради тестируемости).
+
+**Рекомендация:** **T1** для самого фикса. T1.5 — кандидат на будущий PR (`mediaType ||
+kind` fallback из §4), там покрытие важнее и rewire оправдан. T2 — только если команда
+SDK хочет покрытие, но без новых dev-зависимостей.
+
+### Сравнительная таблица
+
+| Вариант | Меняет prod-код | Новые deps | Покрытие настоящего `_getStats` | Риск регрессии |
+|---|---|---|---|---|
+| T1 (рекомендую) | Нет | Нет | 0% (только lint + regression) | Минимальный |
+| T1.5 (rewire) | Нет | +rewire (требует approval) | 100% | Минимальный |
+| T2 (рефактор) | Да | Нет | 100% | Средний (риск задеть смежное) |
+
+## 6. Сборка / проверка (клон 05)
+
+`node_modules` на месте — `npm i` не требуется. Скрипты (из package.json):
+1. `git diff` — только строки 547-564 (2 блока).
+2. `npm run lint` (jshint) — должно быть чисто.
+3. `npm run test:pr` (jasmine PR-набор, включает `QB-WebRTCSpec.js`) — регрессия зелёная.
+4. (опц.) `npm run test:node-regression` (`spec/phase-a-upgrade-check.js`).
+5. `npm run build` НЕ обязателен для PR кода (dist собирается отдельно), но если нужен
+   собранный артефакт для проверки на проекте — `npm run build` (lint+gulp+minify).
+
+## 7. Definition of Done
+
+- [x] Логика вынесена в `_applyStatReport` (T2-рефактор) — уже сделано другим агентом.
+- [x] Guard + `traceWarning` в обеих ветках — уже сделано другим агентом.
+- [ ] **`kind`-fallback добавлен** (`var mediaType = result.mediaType || result.kind` +
+      4 замены `result.mediaType` → `mediaType`, см. §4) — ОСТАВШАЯСЯ работа.
+- [ ] `git diff` чист (только функция `_applyStatReport`, файл
+      `src/modules/webrtc/qbRTCPeerConnection.js`).
+- [ ] Подтверждено перечитыванием candidate/`track`-веток (после 581), что они используют
+      фиксированные ключи (`statistic.*.candidate`, `statistic.remote.video` по
+      `remoteSource`) и fallback/guard им не нужен.
+- [ ] `npm run lint` зелёный.
+- [ ] `npm run test:pr` зелёный (регрессия).
+- [ ] **Авто-тест на `_applyStatReport`** (теперь реалистичен — функция выделена; см. §5):
+      кейсы `mediaType:'video'` / `kind:'video'` без mediaType (Safari) / ни того ни
+      другого (skip+warn). Решить T1 (без теста) vs тест на `_applyStatReport` — §8 п.2.
+- [ ] Префикс коммита — `[QC-1682]` (РЕШЕНИЕ 2026-05-30: отдельного тикета нет, всё в
+      рамках QC-1682). Связь отражена в коммите/PR: это побочный SDK-дефект из диагностики
+      QC-1682, НЕ чинит само отсутствие видео (корень — H.264/backend). Шаблон сообщения:
+      «Surfaced while diagnosing QC-1682. Not the root cause of QC-1682 video absence —
+      that is backend H.264 negotiation.»
+- [ ] Коммит/пуш — только после явного approval пользователя; Claude готовит текст
+      коммита (1-2 строки), пользователь коммитит.
+
+## 8. Решения и открытые вопросы
+
+**РЕШЕНО (2026-05-30):**
+- **Доставка — вариант A:** фикс в SDK (клон 05) → бамп версии + build + `npm publish`
+  → перевод Q-Consultation на новую версию. Полный релизный цикл. Детали — §9.
+- **Без отдельного Jira-тикета:** всё в рамках **QC-1682**. Префикс коммита `[QC-1682]`.
+
+- **Scope — РЕШЕНО (вариант 1): guard + `kind`-fallback.** Закрывает и краш, и пустую
+  Safari-статистику (QC-1645/QC-1475). Оба в одном `[QC-1682]`-PR. Guard уже в коде;
+  остался fallback (§4).
+
+**ОТКРЫТО (нужно решение перед финальной правкой):**
+1. **Авто-тест на `_applyStatReport`?** Функция уже выделена другим агентом, поэтому
+   юнит-тест без новых dev-зависимостей теперь возможен (jasmine, Node): передать
+   fake-`statistic` + fake-`result` с разными `mediaType`/`kind`, проверить заполнение и
+   skip. Варианты: **T-да** (написать тест — рекомендую, раз функция уже тестопригодна) /
+   **T-нет** (только lint+test:pr регрессия). Цена T-да минимальна (функция чистая).
+
+## 9. Доставка фикса до прода — вариант A (РЕШЕНО 2026-05-30)
+
+Полный релизный цикл: SDK → npm → Q-Consultation. Всё под `[QC-1682]`.
+
+### Этап 1 — фикс в SDK (клон 05, отдельная ветка от `develop`)
+Реализация по §4 (другой агент), проверка по §6 (`lint` + `test:pr`). Коммит — пользователь,
+после approval, текст готовит Claude (1-2 строки, префикс `[QC-1682]`).
+
+### Этап 2 — версия + публикация в npm ⚠️ финансово/инфраструктурно значимо
+- **Бамп версии** в `package.json` SDK: `2.23.0-beta.3` → `2.23.0-beta.4` (или по
+  конвенции релизов QuickBlox — уточнить у владельца релиза SDK). Это и есть «отдельное
+  решение», которое снимает запрет §4 «версию не бамаем».
+- **Сборка `dist/`:** `npm run build` (lint + gulp + minify) — npm-пакет содержит
+  собранный код, не `src/`.
+- **`npm publish`** под нужным dist-tag (вероятно `beta`). Выполняет **ПОЛЬЗОВАТЕЛЬ**
+  (или CI/релиз-процесс). Claude НЕ имеет и не должен иметь доступа к npm-аккаунту
+  QuickBlox (security-baseline §5 «НИКОГДА npm publish»). Claude только готовит шаги.
+- Проверить, что новая версия реально появилась в npm registry перед этапом 3.
+
+### Этап 3 — перевод Q-Consultation на новую версию
+Клон проекта: `C:\___QuickBlox\0X-q-consultation-premium` (тот, где будем переключать —
+уточнить какой; текущая работа шла в `03-`).
+- `packages/quickblox/package.json`: `"quickblox": "2.23.0-beta.3"` → новая версия.
+  (Проверено 2026-05-30: зависимость объявлена именно там; `yarn.lock` резолвит из npm.)
+- `yarn install` — обновит `yarn.lock` (пользователь разрешил install объявленного без
+  отдельного спроса; но смена версии пакета — это уже изменение зависимости, спросить).
+- Пересборка зависимых пакетов: `@qc/quickblox`, `@qc/conference` (зависят от `quickblox`).
+- Проверка: tsc (provider/client/api) + vitest + Playwright + dev-test реального звонка
+  (web↔Safari/iOS, чтобы убедиться: краш `bitrate` ушёл; если делали `kind`-fallback —
+  что Safari-stats заполняются).
+
+### Что подтвердить ПЕРЕД этапом 3
+- Версию (`beta.4`?) и dist-tag — согласовать с владельцем релиза SDK.
+- Не сломает ли смена версии SDK другие клоны Q-Consultation (01/02/04) — они на той же
+  зависимости; менять только целевой клон или все — отдельное решение.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "quickblox",
   "description": "QuickBlox JavaScript SDK",
-  "version": "2.23.0",
+  "version": "2.23.1-beta.4",
   "homepage": "https://quickblox.com/developers/Javascript",
   "main": "src/qbMain.js",
   "types": "quickblox.d.ts",
@@ -83,6 +83,9 @@
     "lint": "jshint src --reporter=node_modules/jshint-stylish",
     "test:node-regression": "node spec/phase-a-upgrade-check.js",
     "test:regression": "npm run test:node-regression && npm test",
+    "test:pr": "jasmine --config=spec/support/jasmine.pr.json",
+    "test:full": "jasmine --config=spec/support/jasmine.full.json",
+    "test:ci": "npm run lint && npm run test:node-regression && npm run test:pr",
     "build": "cross-env NODE_ENV=production npm run lint && gulp build && gulp minify",
     "buildNotMinified": "npm run lint && gulp build",
     "generateBuildVersion": "gulp generate-build_version",