DEV Community: Andrej Kirejeŭ

Отказоустойчивые видеозвонки на WebRTC

Andrej Kirejeŭ — Sun, 26 Apr 2026 09:51:30 +0000

Как мы спроектировали, реализовали и проверили в реальных условиях модуль видеосвязи для видеоинтервью и самостоятельных видеотестов в Recruiter.AI — и какие технические проблемы пришлось решить по пути.

Сразу обозначим рамки статьи. WebRTC — большая тема, по которой написаны целые книги. Это не учебник по WebRTC, а разбор конкретной архитектуры и инженерных решений, которые мы приняли для видеозвонков в Recruiter.AI.

Код видеозвонков доступен в репозитории GDMN Meet. Его можно попробовать на meet.gdmn.app или увидеть в работе в сценарии интервью Recruiter.AI.

1. Почему понадобилось свое решение

Recruiter.AI от Andersen Lab — платформа для найма с поддержкой ИИ. Две ее ключевые функции — видеоинтервью между кандидатом и интервьюером и самостоятельный видеотест, где кандидат записывает ответы на вопросы один перед камерой, — зависят от видеопотока, который должен стабильно работать не только в идеальных условиях.

Пользователь может подключаться из дома, из гостиницы, через нестабильный мобильный интернет, за корпоративным файрволом или из сети с национальной DPI-фильтрацией. Для такой среды недостаточно просто вызвать WebRTC API и рассчитывать, что браузер все сделает сам.

В статье разберем:

общую архитектуру и причины, по которым она устроена именно так;
собственный минимальный сигнальный сервер на Socket.IO;
STUN, TURN и проблему юрисдикций, в том числе ограничения сетей, фильтруемых российским РКН;
паттерн «идеального согласования» (Perfect Negotiation) и буферизацию ICE-кандидатов;
многоуровневое восстановление соединения для нестабильных сетей;
обнаружение замершего медиапотока, когда браузер все еще считает соединение активным;
различия между Chrome, Firefox и Safari и конкретные обходные решения;
проверку оборудования и горячую замену камер и микрофонов во время звонка;
конвейер записи: компоновку через canvas, загрузку фрагментами и исправление для Safari, на поиск которого ушло два дня;
инструменты диагностики, которые помогают проверять все это в реальных сетях.

2. Общая картина

На верхнем уровне в системе есть четыре плоскости:

Медиаплоскость (P2P). Два RTCPeerConnection обмениваются зашифрованным DTLS-SRTP-трафиком. При удачном сценарии медиаданные идут напрямую между браузерами, без промежуточного сервера.
Плоскость сигнального обмена. Минимальный Socket.IO-сервер на стороне приложения пересылает типизированные сообщения между участниками комнаты и хранит только минимальное состояние присутствия, нужное для защиты от повторных входов.
ICE-плоскость. STUN-серверы Google, Cloudflare и наш собственный coturn помогают проходить NAT. Если прямое P2P-соединение невозможно, медиатрафик идет через TURN-серверы поверх TLS на порту 443.
Приемник записи. API загрузки фрагментами принимает 30-секундные медиаблоки, которые создает CallRecorder.

На клиенте ответственность разделена между двумя хуками, связанными небольшим интеграционным слоем. Первый управляет RTCPeerConnection, сигнальным обменом и восстановлением соединения. Второй отвечает за камеры, микрофоны, подключение и отключение устройств, а также за локальный медиапоток. Такое разделение оказалось важным: замена устройств во время звонка сама по себе достаточно сложна, и смешивать ее с состоянием сигнального обмена было бы ошибкой.

3. Сигнальный сервер: минимальный, восстанавливаемый, свой

Для сигнального обмена мы используем точку подключения Socket.IO как часть сервера приложения. У нее три задачи:

Пересылать сообщения. Сервер не хранит состояние звонка, а только передает сообщения между участниками. Благодаря этому протокол можно развивать без изменений на серверной стороне.
Восстанавливать сессию после краткого обрыва. Если у кандидата на несколько секунд пропал Wi-Fi, страница не должна требовать ручной перезагрузки.
Отслеживать присутствие в минимальном объеме. Сервер должен понимать, кто находится в комнате, чтобы отклонять повторный вход одного и того же участника.

Именно второй пункт стал причиной, по которой мы выбрали Socket.IO, а не обычный WebSocket. В Socket.IO есть connectionStateRecovery: механизм буферизует события в течение заданного окна и восстанавливает сессию, если клиент успевает переподключиться. У нас это окно равно пяти минутам.

Сам протокол компактный: девять типов сообщений — JOIN/LEAVE, ENUM, CALLING, ANSWER_CALL, SIGNAL, SOCKET_PING/PONG, RESTART_CALL, END_CALL, MAKE_CALL. SIGNAL передает и SDP, и ICE-кандидаты. В каждом сообщении есть fromId/toId, поэтому серверу не нужно хранить сведения о том, кто именно с кем разговаривает.

Последовательность успешной установки звонка:

В начальной фазе подключения есть две важные детали:

Каждая попытка подключения отправляет новый instanceId (UUID v4) вместе с participantId. Если вторая вкладка входит с тем же participantId, сервер отвечает already_in_room, и вторая вкладка прекращает подключение. Так мы обнаруживаем и отклоняем дублирующиеся входы — частую причину жалоб вроде «я вижу себя в сетке два раза».
При закрытии вкладки клиент отправляет LEAVE через navigator.sendBeacon(). window.onbeforeunload в мобильных браузерах ненадежен; sendBeacon работает лучше.

4. STUN, TURN и проблема юрисдикций

Получить ICE-кандидаты сравнительно просто: достаточно указать для RTCPeerConnection несколько публичных STUN-серверов. Конфигурация по умолчанию:

stun:stun.l.google.com:19302
stun:stun.cloudflare.com:3478
наш собственный сервер для резервирования

Сложная часть — TURN. Существенная доля пользователей не может установить прямое P2P-соединение: корпоративные сети, симметричные NAT, мобильные операторы с NAT операторского класса (carrier-grade NAT) и, что особенно важно для Recruiter.AI, пользователи внутри национально фильтруемых сетей. В таких случаях медиатрафик должен идти через промежуточный TURN-сервер.

Поэтому мы подняли собственный coturn и открыли TURN на порту 443. URL ICE-сервера выглядит так:

turns:coturn.our_server.com:443

Порт 443 важен. Многие корпоративные файрволы и национальные DPI-фильтры пропускают TLS по TCP/443, потому что блокировка этого трафика нарушит работу HTTPS. TURN-сервер на этом порту, работающий внутри корректного TLS-туннеля, для большинства DPI выглядит как обычная HTTPS-сессия. Поэтому мы используем TURN поверх TLS на :443, а не стандартные транспорты UDP 3478 или TCP 5349.

Но при работе с пользователями из стран с жесткой фильтрацией трафика возникает еще одна проблема.

Проблема российской фильтрации

Российская инфраструктура национальной фильтрации трафика — система РКН, включая ТСПУ на точках пиринга провайдеров, — блокирует не только известные адреса. Соединения могут прерываться и для узлов, чьи IP-адреса или SNI-имена попали в списки фильтрации. Кроме того, фильтрация становится все агрессивнее к трафику, который похож на WebRTC: долгоживущим UDP-потокам или характерным STUN-пакетам поверх TCP. TURN-сервер, который безупречно работает из Амстердама, может за ночь стать недоступным из Москвы, если соседний сервис из того же IP-диапазона попал под фильтрацию.

Практический вывод: одного TURN-развертывания, даже качественного, недостаточно. Мы стали размещать TURN-серверы в разных юрисдикциях, чтобы у пользователей из конкретного региона всегда был доступный сервер-посредник с IP-адресом и hostname, которые не блокируются на их сетевом маршруте. Конфигурация WebRTC вычисляется для каждой организации во время выполнения через внутренний реестр сервисов, а конфигурация из переменных окружения служит запасным вариантом. Это позволяет направлять клиентов в подходящий TURN-пул без нового развертывания.

Сборка конфигурации

Сборщик конфигурации превращает JSON из переменных окружения в RTCConfiguration. Он небольшой, но ошибки в значениях по умолчанию здесь приводят к особенно неприятным последствиям, поэтому мы сделали его строгим:

export const getRTCConfiguration = ({ stun, turn, icePolicy }: WebRTCConfig): RTCConfiguration => {
  const config: RTCConfiguration = {
    iceServers: [
      ...turn.map(s => ({
        urls: s.urls,
        username: s.username || '1',
        credential: s.credential || '1',
      })),
      ...stun.map(s => ({ urls: s.urls })),
    ].filter(Boolean),
    iceTransportPolicy: icePolicy,
  };
  return config;
};

icePolicy настраивается: по умолчанию это 'all', но на уровне конфигурации его можно переключить в 'relay'. Это удобно для отладки и для клиентов, которым по юридическим причинам нужен единый маршрут через TURN. Код звонка при этом не меняется.

5. Идеальное согласование (Perfect Negotiation) с буферизацией ICE

Оба участника могут одновременно попытаться создать предложение соединения (offer). В WebRTC такая коллизия называется конфликтом предложений (glare). Паттерн W3C Perfect Negotiation назначает одну сторону «вежливой» (polite peer) и позволяет ей откатить собственное локальное описание, если входящее предложение конфликтует с уже созданным локальным предложением. Мы реализуем этот подход через стандартные флаги makingOffer, ignoreOffer и polite. Вежливой стороной у нас выступает принимающий участник.

Важная практическая деталь: ICE-кандидаты могут прийти раньше, чем будет установлено удаленное описание (remoteDescription). Это особенно часто проявляется в медленных сетях: SDP доходит с задержкой, а ICE-кандидаты начинают поступать почти сразу. В современных браузерах вызов addIceCandidate до setRemoteDescription приводит к ошибке. Поэтому мы буферизуем ICE-кандидаты для каждого участника и очищаем буфер только после успешного setRemoteDescription. На практике в буфере обычно всего несколько кандидатов, но без этого механизма звонок на нестабильных сетях может не установиться без явной ошибки.

6. Восстановление: шаг за шагом

Эта часть потребовала больше всего итераций. WebRTC дает connectionState, iceConnectionState, iceGatheringState, signalingState, но ни одно из этих состояний нельзя считать исчерпывающим источником правды. Соединение с connectionState === 'connected' все еще может передавать ноль байт, если сетевой маршрут перестал пропускать трафик. А состояние iceConnectionState === 'disconnected' иногда восстанавливается само через секунду, если дать браузеру время.

Поэтому мы объединили несколько сигналов и сделали ступенчатую схему восстановления с пятью порогами:

const heartbeatDelay = 2500;
const heartbeatThreshold = heartbeatDelay * 2; // 5 s
const statsDelay = 5_001;
const recoveryDelay = 18_000;                  // full restart
const iceRestartDelay = recoveryDelay / 2;     //  9 s — ICE restart
const videoWarmUpDelay = 8_000;
const waitingForInternetDelay = 60_000;        // give up

Схема выглядит так:

В текстовом виде это работает так:

Каждые 2,5 секунды каждая сторона отправляет SOCKET_PING, а вторая отвечает SOCKET_PONG. Два пропуска подряд, то есть 5 секунд, означают, что путь через сигнальный сервер, скорее всего, недоступен.
Примерно каждые 5 секунд вызывается pc.getStats(), после чего сравниваются счетчики RTP-байтов. Если не изменились ни входящие, ни исходящие байты, медиапоток считается замершим независимо от состояния WebRTC.
При первом признаке проблемы (connectionState === 'failed', ICE disconnected/closed, неактивный медиапоток или отсутствие передачи данных) мы сохраняем отметку preProblemDiscovered. Если на следующем цикле проблема сохраняется, она повышается до problemDiscovered. Такая задержка на один цикл убрала большую часть ложных срабатываний в тестах.
Через 9 секунд подтвержденной проблемы, если соединение с сигнальным сервером живо и текущая сторона является инициатором звонка, вызывается pc.restartIce(). Это запускает повторное ICE-согласование без пересоздания RTCPeerConnection: операция требует мало ресурсов и обычно выполняется быстро.
Через 18 секунд выполняется полный restartCall(): текущий RTCPeerConnection закрывается, через сокет отправляется RESTART_CALL, вторая сторона также очищает свое состояние, после чего соединение создается заново. Это более ресурсоемкий, но надежный вариант восстановления.
Если недоступен сам сокет или navigator.onLine === false, перезапуск не запускается: для него все равно нет рабочего канала управления. В этом состоянии мы ждем до 60 секунд; только после этого интерфейс показывает сообщение: «Connection lost. Please check internet connection.»

У этой логики много условий и переходов, поэтому мы многократно проверяли ее в условиях искусственно ограниченной сети. Ключевой блок из цикла проверки статистики:

if (elapsed > recoveryDelay) {
  if (!socket?.connected || !navigator.onLine || missedHeartbeat(p.socketPingReceived)) {
    if (elapsed > waitingForInternetDelay) {
      if (!socket?.connected) {
        endCall(p, 'Connection lost. Please check internet connection.');
      } else {
        endCall(p);
      }
    } else {
      updateParticipant(p.id, { healthCheck: Date.now() });
    }
  } else {
    if (p.role === 'caller') {
      restartCall(p);
    } else {
      // caller must manage the call, but if it avoids its responsibilities...
      if (elapsed > (waitingForInternetDelay + recoveryDelay)) {
        endCall(p);
      } else {
        updateParticipant(p.id, { healthCheck: Date.now() });
      }
    }
  }
}

Есть два важных ограничения:

Перезапуск инициирует только вызывающая сторона. Если обе стороны одновременно начнут пересоздавать соединение, они будут постоянно конфликтовать на уровне SDP. Принимающая сторона реагирует на сигнал перезапуска, но сама его не запускает. Если же инициатор перестал выполнять эту роль — например, браузер заморозил его вкладку, — принимающая сторона завершает звонок самостоятельно после более длинного таймаута (waitingForInternetDelay + recoveryDelay = 78 s).
Время «с момента проблемы» считается от Math.max(problemDiscovered, lastSocketConnected, socketPingRestored, lastIceStateChange). Если сокет кратко восстановился или ICE-состояние на секунду вернулось в норму, таймер восстановления сбрасывается. Без этого звонок можно было бы завершить уже после того, как кратковременный сбой фактически прошел.

7. Как мы находим замерший медиапоток

Один из самых полезных фрагментов кода в проекте оказался очень небольшим. Мы отслеживаем изменение счетчиков RTP-байтов из pc.getStats(). Если за полный интервал проверки не изменились ни отправленные, ни полученные байты, соединение считается неработоспособным независимо от значения iceConnectionState:

function isDataTransmitted<S>(p: Participant<S>) {
  if (
    p.statInterval &&
    p.bytesReceived !== undefined &&
    p.bytesTime !== undefined &&
    p.bytesPrevReceived !== undefined &&
    p.bytesPrevTime !== undefined &&
    p.bytesSent !== undefined &&
    p.bytesPrevSent !== undefined
  ) {
    const deltaTime = p.bytesTime - p.bytesPrevTime;
    const deltaReceived = p.bytesReceived - p.bytesPrevReceived;
    const deltaSent = p.bytesSent - p.bytesPrevSent;
    // only judge if there were enough time to transmit some data
    // Connection is alive if EITHER data is being received OR sent (not both required)
    return deltaTime < statsDelay || (deltaReceived > 0 || deltaSent > 0);
  } else {
    return true;
  }
}

Проверка deltaReceived > 0 || deltaSent > 0, а не &&, была осознанным решением. У одного из участников может быть выключен микрофон, а часть медиаданных может временно идти только в одном направлении. Если считать соединение живым только при одновременном росте обоих счетчиков, система будет ошибочно завершать нормальные звонки. Поэтому для проверки достаточно, чтобы данные передавались хотя бы в одну сторону.

Также есть короткий запас времени на появление первого медиапотока после установки звонка (videoWarmUpDelay = 8_000). Некоторые браузеры, особенно Safari, заметно задерживают первый видеокадр даже после connectionState === 'connected'. Если проверять отсутствие видео раньше восьми секунд, система будет выдавать ложные срабатывания.

8. Браузерные войны: Chrome, Firefox, Safari

Больше всего времени в проекте заняли различия между браузерами. Вот конкретные случаи, которые стоит зафиксировать.

Safari: `MediaRecorder` требует `timeSlice`

В Chrome и Firefox MediaRecorder.start() без аргументов возвращает один большой Blob при вызове stop(); если передать timeSlice в миллисекундах, данные будут приходить периодически. В Safari вызов start() без timeSlice может не отдавать данные вообще. При этом рекордер выглядит рабочим: нет ошибок, промисы не отклоняются, но ondataavailable не приносит полезных данных.

На этом мы потеряли два дня в сценарии самостоятельного видеотеста. Исправление — флаг useTimeSlice, включаемый только для нужного браузера, в обоих классах рекордера:

this.useTimeSlice = browserName === "Safari";
…
if (this.useTimeSlice && this.TIME_SLICE > 0) {
  this.mediaRecorder.start(this.TIME_SLICE); // 1000 ms
} else {
  this.mediaRecorder.start();
}

Есть и второй уровень проблемы: на границе 30-секундного фрагмента рекордер останавливается и запускается снова. В Safari данные снова появляются только если передавать timeSlice в start() при каждом запуске. Поэтому тот же флаг используется и при перезапуске рекордера.

Firefox: названия устройств пустые, пока не запросишь доступ

navigator.mediaDevices.enumerateDevices() возвращает label: "" для каждого устройства, пока пользователь хотя бы раз не выдал доступ через getUserMedia(). Chrome может заполнить подписи до запроса, если сайт уже был авторизован раньше; Firefox — нет. Поэтому мы сначала перечисляем устройства, затем запрашиваем доступ, после чего перечисляем устройства повторно и показываем обновленные подписи в списках выбора.

Выбор MIME

Chrome и Firefox предпочитают WebM: VP8/VP9 для видео и Opus для аудио. Safari надежно кодирует только MP4 с AVC и AAC. Мы при загрузке проверяем поддержку и выбираем лучшую доступную комбинацию, а для Safari запасным вариантом используем 'video/mp4; codecs="avc1.42E01E, mp4a.40.2"'. Это решение влияет и на расширение загружаемого файла (.webm или .mp4), по которому серверная часть выбирает нужный конвейер последующей обработки.

iOS

На iOS в ограничениях для видео мы всегда указываем facingMode: 'user', чтобы по умолчанию открывалась фронтальная камера. deviceId: { exact: … } на iOS иногда выбирает не тот объектив, который ожидает пользователь. Это был небольшой, но устойчивый источник ошибок, пока мы не стандартизировали поведение через facingMode.

9. Оборудование: проверить, заменить, восстановить

Интервью и самостоятельные видеотесты — это записываемая оценка реальных людей, поэтому оборудование должно работать правильно. Здесь помогают три вещи.

9.1 Проверка микрофона перед звонком

Перед входом в звонок пользователь проходит проверку звука в модальном окне с живым индикатором громкости. Мы создаем AudioContext + AnalyserNode на отдельном потоке getUserMedia({ audio: { deviceId: { exact } } }), снимаем частотные данные, отслеживаем пиковый уровень в dB и сравниваем его с порогом −35 dB. Если микрофон пользователя не достигает этого порога, мы предупреждаем его до начала звонка, а не тогда, когда интервьюер уже ждет.

9.2 Горячая замена во время звонка

Если кандидат подключил USB-гарнитуру во время звонка, соединение не должно прерываться. Для этого нужны две вещи:

Хук медиаустройств слушает navigator.mediaDevices.ondevicechange с задержкой в 1 секунду: при подключении устройство часто порождает несколько событий подряд.
Когда пользователь выбирает новое устройство, RTCPeerConnection не пересогласуется. Мы заменяем трек через RTCRtpSender.replaceTrack():

// useVideoCall switchTrack (wired from useMediaDevices)
for (const p of participantsRef.current) {
  if (p.state === 'in-call' && p.pc) {
    const sender = p.pc.getSenders().find(s => s.track?.kind === newTrack.kind);
    if (sender) {
      await sender.replaceTrack(newTrack); // no renegotiation
    }
  }
}
localStreamRef.current = newStream;

replaceTrack здесь именно тот инструмент, который нужен: новое согласование по схеме «предложение/ответ» (offer/answer) не требуется, удаленная сторона видит непрерывный трек, а рекордер, если он уже работает, продолжает запись.

9.3 Восстановление, когда устройство исчезло

Если активная камера или микрофон исчезают — пользователь отключил USB-устройство, разрешение было отозвано на уровне ОС или браузер выбрал другое устройство, — включается двухступенчатое восстановление:

Мягкое восстановление. track.onended помечает тип устройства как требующий замены. Затем срабатывает обработчик devicechange с задержкой, мы заново перечисляем устройства, выбираем первое доступное устройство нужного типа и вызываем switchDevices через тот же путь replaceTrack, что и при обычной ручной замене. Для удаленного участника звонок продолжается без заметного разрыва.
Жесткое восстановление. Если замены нет — все камеры отключены или разрешения отозваны, — локальный медиапоток корректно останавливается, сохраняется контекст восстановления со старыми и новыми device IDs, а наверх поднимается типизированная ошибка (isNotAllowedError, isNotFoundError, isNotReadableError, isOverconstrainedError). Ее принимает отдельный интерфейс для ошибок медиаустройств и показывает правильное действие: «Разрешите доступ к камере», «Подключите камеру», «Закройте другое приложение, которое использует камеру» и так далее.

Есть еще одна важная деталь: виртуальный фон создает синтетический трек с искусственным deviceId. Если записать этот ID обратно в состояние выбранной камеры, в следующий раз пользователь откроет настройки и увидит UUID, который не соответствует ни одному реальному устройству. Исправление — разделить выбор пользователя (selectedCameraId) и текущее рабочее состояние (currentCamera). Когда виртуальный фон включен, мы сохраняем исходный ID выбранной камеры, а не ID синтетического трека.

Все операции с устройствами сериализованы через Semaphore, чтобы быстрые клики по выпадающему списку устройств не создавали перекрывающиеся getUserMedia-вызовы и брошенные треки.

10. Конвейер записи

У записи был собственный набор сложностей: видеозвонок многопользовательский — интервьюер, кандидат, иногда больше людей, — а на выходе нужен один удобный для просмотра артефакт.

Для звонка (CallRecorder):

<video> каждого участника отрисовывается в сетку 2×2 на canvas на каждом кадре анимации. canvas.captureStream() превращает результат в MediaStream с одним составным видеотреком.
Этот составной поток передается в один MediaRecorder для видео.
Параллельно аудиотрек каждого участника передается в свой MediaRecorder. Раздельное аудио упрощает последующую транскрибацию по спикерам — не нужно разделять уже смешанный звук — и позволяет не сводить WebRTC-аудиотреки на лету с потерей качества.
Каждые 30 секунд рекордеры переключаются на новый фрагмент: stop() отдает последний Blob через ondataavailable, затем start(TIME_SLICE) начинает следующий фрагмент. Каждый Blob сразу загружается с interviewId, participantId, timestamp и расширением медиатипа. Если загрузка не удалась, повторяется отправка только этого фрагмента: один сетевой сбой не должен уничтожить всю запись.

Для самостоятельного видеотеста (AssessmentRecorder) компоновка не нужна: говорит один человек, поэтому достаточно одного рекордера для объединенного потока. Дополнительно AssessmentRecorder дает барьер остановки на основе промиса: stopRecording() возвращает объект Promise, который завершается только после того, как последний Blob прошел через ondataavailable. Благодаря этому код интерфейса, который хочет заменить устройство, точно знает, что поток уже можно безопасно разбирать.

Оба рекордера учитывают обходное решение для Safari с timeSlice из §8.

11. Тестирование в реальном мире

Юнит-тесты ловят баги протокола, но ни один юнит-тест не скажет, что coturn во Франкфурте на этой неделе недоступен из сети конкретного российского провайдера. Поэтому мы сделали клиентскую диагностическую проверку.

Для каждого сервера она создает одноразовый RTCPeerConnection, указывает ему ровно один STUN- или TURN-сервер, открывает канал данных (data channel), чтобы принудительно запустить сбор кандидатов, и ждет результата ICE-процедуры. Возможные результаты:

Рабочий STUN-сервер должен дать кандидата типа srflx.
Рабочий TURN-сервер должен дать кандидата типа relay.
Все остальное — тайм-аут через 10 секунд или ошибка соединения — означает, что этот сервер недоступен для этого клиента.

Результат приводится к простой форме { url, type, status, candidates[], duration } и показывается на внутренней диагностической странице. Когда пользователь пишет «звонок не подключается», он может нажать одну кнопку и сразу увидеть, какие серверы доступны из его сети. Это сократило отладку с многодневной переписки до одного скриншота.

В сценарии интервью поверх серверных проверок есть еще слой контроля нарушений (anti-cheating), который отмечает переключения вкладок во время интервью. Это не совсем WebRTC-задача, но механизм работает через тот же сокетный канал, а пропавший сигнал о переключении вкладки бывает полезным косвенным признаком проблемы с соединением.

12. Что мы вынесли

Коротко и без особого порядка:

Не доверяйте ни одной отдельной машине состояний WebRTC. Перепроверяйте ее по изменениям RTP-счетчиков через getStats(). 'connected' — это заявление, а не факт.
Буферизуйте ICE-кандидаты. На медленном канале они действительно приходят раньше, чем завершается setRemoteDescription.
Восстанавливайте соединение постепенно. Пульсовая проверка → ICE restart → полный перезапуск → ожидание восстановления сети. Слишком ранний полный перезапуск хуже, чем еще несколько секунд работы в деградировавшем состоянии.
Восстановлением должна управлять одна сторона. Перезапуск запускает инициатор звонка, а принимающая сторона обрабатывает полученный сигнал. Если перезапуск запускают оба участника, начинаются конфликты при согласовании SDP.
Поднимайте собственный coturn на :443 с TLS. Бесплатные STUN-серверы годятся; бесплатных TURN-серверов либо нет, либо они не масштабируются, либо находятся не там, где нужно.
Размещайте TURN в нескольких юрисдикциях, если ваши пользователи находятся за национальными фильтрами. Российский случай сделал это для нас обязательным, но та же логика работает для корпоративного DPI и строгих мобильных операторов где угодно. Конфигурация на уровне клиента позволяет выбрать подходящий TURN-пул без нового развертывания.
Используйте replaceTrack для замены устройств. Пересогласовывать весь RTCPeerConnection на каждый клик «сменить микрофон» медленно и ненадежно.
Разделяйте выбор пользователя и текущее рабочее состояние, когда появляются виртуальные фоны или другие синтетические треки. Это избавляет от трудноуловимых ошибок в настройках устройств.
Safari требует timeSlice для MediaRecorder. Всегда. И после каждого stop/start его нужно передавать снова.
Firefox требует повторного enumerateDevices() после выдачи разрешения. Иначе список устройств будет заполнен пустыми подписями.
Сделайте собственную проверку доступности серверов. Это небольшая задача, но она позволяет диагностировать проблемы в пользовательской сети за 30 секунд.

Видеозвонки Recruiter.AI продолжают развиваться: впереди настройка предпочтительных кодеков, одновременная передача нескольких видеопотоков разного качества (simulcast) и автоматическая адаптация качества к доступной пропускной способности канала. Но описанная здесь архитектура уже выдержала тысячи реальных интервью и самостоятельных видеотестов, в том числе в сетях, где WebRTC обычно ведет себя непредсказуемо. Если вы создаете похожую систему, начинать стоит не с интерфейса, а со схемы восстановления соединения и TURN-стратегии. От этих двух решений зависит все остальное.

Building a Resilient WebRTC Video Call

Andrej Kirejeŭ — Wed, 22 Apr 2026 23:49:54 +0000

How we designed, built, and battle‑tested the video calling engine that powers video interviews and video self‑assessment inside Recruiter.AI — and the long list of problems we had to beat along the way.

Before we dive in, a quick note on the scope of this article. WebRTC is a huge topic, and there are entire books written about it. This is not a WebRTC tutorial. It’s a postmortem of the specific architecture and design decisions we made for Recruiter.AI’s video calling features, and the rationale behind them.

You can find the video call code in the GDMN Meet repository, try it out on meet.gdmn.app, or see it in action in the Recruiter.AI interview flow.

1. Why this was built

Recruiter.AI from Andersen Lab is a platform for AI‑assisted hiring. Two of its most visible features — video interviews between a candidate and an interviewer, and video self‑assessment where a candidate records answers to questions alone in front of the camera — depend on a live video stream that has to just work. Not in the lab. In a candidate's bedroom, on a hotel Wi‑Fi, on a flaky mobile network, behind a corporate firewall, behind a national DPI filter.

What we will cover:

the end‑to‑end architecture and why it looks the way it does;
why we built our own thin Socket.IO signaling server;
STUN, TURN, and the jurisdiction problem (for example, the one that stops calls working inside Russian RKN‑filtered networks);
Perfect Negotiation with buffered ICE candidates;
the multi‑tier connection recovery needed to survive bad links;
how we detect frozen media that every browser still calls "connected";
Chrome vs. Firefox vs. Safari — concrete workarounds;
equipment checks, hot‑swap of cameras and microphones mid‑call;
the recording pipeline (canvas compositing + chunked upload + a Safari fix that took two days to find);
the tooling we built to test it all.

2. The big picture

At a high level there are four planes:

Media plane (P2P). Two RTCPeerConnections exchange encrypted DTLS‑SRTP traffic, ideally peer‑to-peer.
Signaling plane. A thin Socket.IO server — provided by the application server — that forwards typed messages between participants in a room and keeps just enough presence state to reject duplicate joins.
ICE plane. STUN servers (Google, Cloudflare, and our own coturn server) for NAT traversal, plus a set of TURN over TLS relays on port 443 that act as media hairpins when direct P2P can't be established — which is more often than you'd think.
Recording sink. A chunked upload API that accepts 30‑second media blobs produced by CallRecorder.

On the client, responsibilities are split across two cooperating hooks wired together by a thin integration layer: one owns the peer connection, signaling and recovery; the other owns cameras, microphones, device hot‑plug handling and the local stream. Keeping those responsibilities separate was one of the first good decisions — swapping devices mid‑call is already tricky enough without also owning signaling state.

3. The signaling server: thin, recoverable, ours

For signaling we run a Socket.IO endpoint as part of the application server. Its job is narrow and strictly defined:

Dumb relay. The server forwards messages and nothing else. No call state lives on the server, which means the signaling protocol can evolve without server‑side changes.
Self‑recovering at the socket layer so a candidate who blips off Wi‑Fi for ten seconds does not have to refresh the page.
Presence‑aware, minimally. It tracks room membership just enough to reject duplicate joins from the same participant (more on that below).

The second point is the reason we picked Socket.IO over a raw WebSocket: Socket.IO ships connectionStateRecovery, which buffers events for a configurable window and resumes the session if the client reconnects in time. The window is set to five minutes.

The protocol itself is tiny: nine message types — JOIN/LEAVE, ENUM, CALLING, ANSWER_CALL, SIGNAL (which wraps both SDP and ICE), SOCKET_PING/PONG, RESTART_CALL, END_CALL, MAKE_CALL. Each message carries fromId/toId so the server can stay stateless about who is talking to whom.

Sequence of a successful call setup:

Two small but important details in the connection bootstrap:

Every connection attempt sends a fresh instanceId (UUID v4) alongside the participantId. If a second tab joins with the same participantId, the server replies with already_in_room and the second tab backs off. This is how we detect and reject duplicate entries (the most common cause of "I see two of myself in the grid" reports from testers).
On tab unload, the client fires a LEAVE message through navigator.sendBeacon(). window.onbeforeunload is not reliable on mobile browsers; sendBeacon is.

4. STUN, TURN, and the jurisdiction problem

Getting ICE candidates is the easy part — point RTCPeerConnection at a few public STUN servers and you're done. The default config:

stun:stun.l.google.com:19302
stun:stun.cloudflare.com:3478
our own server, for redundancy

The hard part is TURN. A non‑trivial fraction of users — corporate networks, symmetric NATs, mobile carriers with carrier‑grade NAT, and, crucially for Recruiter.AI, users inside nationally filtered networks — cannot establish direct peer connections. They need a relay.

So we stood up our own coturn instance and crucially exposed TURN on port 443. The ICE server URL looks like:

turns:coturn.our_server.com:443

Port 443 matters. A lot of corporate firewalls and national DPI filters let TCP/443 TLS through because blocking it would break HTTPS. A TURN server listening on that port, inside a proper TLS tunnel, is indistinguishable from a normal HTTPS session to most DPI. That is why we use TURN over TLS on :443 rather than the default UDP 3478 or TCP 5349 transports.

But there is a further twist, particular to running Recruiter.AI for users inside restrictive countries.

The Russian filter problem

Russia's national traffic filtering infrastructure (the RKN system, including the TSPU boxes deployed at ISP peering points) does not only block well‑known addresses. It also drops connections to endpoints whose IPs or SNI hostnames have been added to the filter lists, and it has become increasingly aggressive about throttling or blocking traffic that looks like WebRTC — long‑lived UDP flows, or STUN packet patterns over TCP. A TURN server that works flawlessly from Amsterdam can suddenly be unreachable from Moscow overnight, because somebody else's traffic from the same IP range poisoned the filter.

The practical consequence is that a single TURN deployment — even a good one — is not enough. What we ended up doing is placing TURN servers in different jurisdictions so that users from any particular region always have a reachable relay whose IP/hostname is clean for their network path. The WebRTC config is resolved per organization at runtime through an internal service registry, with an env‑based default as a fallback. That lets us route tenants to the TURN pool whose jurisdiction and IP hygiene actually work for them, without requiring a redeploy.

Building the config

The config builder is where env JSON becomes RTCConfiguration. It's small but it's the place that gets wrong defaults wrong in exciting ways, so we kept it strict:

export const getRTCConfiguration = ({ stun, turn, icePolicy }: WebRTCConfig): RTCConfiguration => {
  const config: RTCConfiguration = {
    iceServers: [
      ...turn.map(s => ({
        urls: s.urls,
        username: s.username || '1',
        credential: s.credential || '1',
      })),
      ...stun.map(s => ({ urls: s.urls })),
    ].filter(Boolean),
    iceTransportPolicy: icePolicy,
  };
  return config;
};

icePolicy is configurable: default is 'all', but it can be flipped to 'relay' at config level — useful for debugging, or for tenants where a uniform TURN path is required for jurisdictional reasons — without touching the call code.

5. Perfect Negotiation with buffered ICE

Two peers can try to create an offer at the same time — classic WebRTC glare. The W3C Perfect Negotiation pattern assigns one side as "polite" and lets it roll back its own local description if an incoming offer collides. We implement it with the usual makingOffer, ignoreOffer and polite flags. The callee is the polite peer.

There is one detail that bites: ICE candidates can arrive before the remote description is set, especially on a slow network where SDP takes a while to traverse but ICE candidates start trickling immediately. Calling addIceCandidate before setRemoteDescription throws in modern browsers. So we buffer ICE candidates per peer and flush them after setRemoteDescription resolves. The buffer is not large in practice — usually a handful of candidates — but without it, the call silently fails to connect on bad links.

6. Recovery, step by step

This was the part that took the most iteration. WebRTC gives you connectionState, iceConnectionState, iceGatheringState, signalingState — and at least one of them lies to you at any given moment. A connectionState === 'connected' peer can still be sending zero bytes because the path got silently blackholed. A peer in iceConnectionState === 'disconnected' can recover on its own in a second if you just wait.

So we layered several signals together and built an escalating recovery ladder with five thresholds:

const heartbeatDelay = 2500;
const heartbeatThreshold = heartbeatDelay * 2; // 5 s
const statsDelay = 5_001;
const recoveryDelay = 18_000;                  // full restart
const iceRestartDelay = recoveryDelay / 2;     //  9 s — ICE restart
const videoWarmUpDelay = 8_000;
const waitingForInternetDelay = 60_000;        // give up

The ladder:

Translated into words:

Every 2.5 s each side sends a SOCKET_PING; the counterpart replies with SOCKET_PONG. Two missed in a row (5 s) means the socket path is likely dead.
Every ~5 s a stats poll runs pc.getStats() and diffs RTP byte counters. If neither inbound nor outbound bytes moved, media is frozen regardless of what the state machine says.
On the first tick where something looks wrong (connectionState === 'failed', ICE disconnected/closed, stream inactive, or no bytes moved), we stamp a preProblemDiscovered. If the next tick still looks bad, it promotes to problemDiscovered. This debounce by itself removed the majority of false alarms in testing.
After 9 s of real trouble, if the socket is still alive and we are the caller, pc.restartIce() is called. That triggers ICE renegotiation without tearing down the peer connection — cheap and fast when it works.
After 18 s, we escalate to a full restartCall(): close the RTCPeerConnection, send RESTART_CALL over the socket so the other side does the same, and rebuild from scratch. Expensive but reliable.
If the socket itself is down or navigator.onLine === false, we wait instead of restarting — there is nothing to restart over. The wait runs up to 60 s; only then does the UI say "Connection lost. Please check internet connection."

The branching logic is dense and it took a lot of trial runs on a throttled network to get right. The key block, from the stats‑tick loop:

if (elapsed > recoveryDelay) {
  if (!socket?.connected || !navigator.onLine || missedHeartbeat(p.socketPingReceived)) {
    if (elapsed > waitingForInternetDelay) {
      if (!socket?.connected) {
        endCall(p, 'Connection lost. Please check internet connection.');
      } else {
        endCall(p);
      }
    } else {
      updateParticipant(p.id, { healthCheck: Date.now() });
    }
  } else {
    if (p.role === 'caller') {
      restartCall(p);
    } else {
      // caller must manage the call, but if it avoids its responsibilities...
      if (elapsed > (waitingForInternetDelay + recoveryDelay)) {
        endCall(p);
      } else {
        updateParticipant(p.id, { healthCheck: Date.now() });
      }
    }
  }
}

Two subtleties worth calling out:

Only the caller initiates restart. If both sides raced to restart, they'd endlessly step on each other's SDP. The callee passively follows. But if the caller abdicates — for example, its tab was suspended — the callee eventually gives up on its own after a longer timeout (waitingForInternetDelay + recoveryDelay = 78 s).
The "elapsed since problem" time is computed against Math.max(problemDiscovered, lastSocketConnected, socketPingRestored, lastIceStateChange). If the socket flaps or the ICE state briefly recovers, the recovery clock resets. Without that, a call that bounced through a short outage would get killed even after it stabilized.

7. Detecting frozen media

Possibly the most satisfying bit of code in the whole project is also the smallest. We keep a running delta of RTP bytes from pc.getStats(). If both sent and received deltas are zero over a full stats window, the connection is dead — no matter what iceConnectionState claims:

function isDataTransmitted<S>(p: Participant<S>) {
  if (
    p.statInterval &&
    p.bytesReceived !== undefined &&
    p.bytesTime !== undefined &&
    p.bytesPrevReceived !== undefined &&
    p.bytesPrevTime !== undefined &&
    p.bytesSent !== undefined &&
    p.bytesPrevSent !== undefined
  ) {
    const deltaTime = p.bytesTime - p.bytesPrevTime;
    const deltaReceived = p.bytesReceived - p.bytesPrevReceived;
    const deltaSent = p.bytesSent - p.bytesPrevSent;
    // only judge if there were enough time to transmit some data
    // Connection is alive if EITHER data is being received OR sent (not both required)
    return deltaTime < statsDelay || (deltaReceived > 0 || deltaSent > 0);
  } else {
    return true;
  }
}

The deltaReceived > 0 || deltaSent > 0 (rather than &&) was a conscious call. One side can legitimately be muted; demanding both byte streams to flow would produce spurious "dead call" alarms when a participant stops talking. As long as something is moving, the link is alive.

There is also a tiny grace period for the initial media flow after a call is established (videoWarmUpDelay = 8_000). Some browsers — Safari in particular — take a noticeable time to push the first video frame even after connectionState === 'connected'. Complaining about "no video" before eight seconds produces a false positive.

8. Browser wars: Chrome, Firefox, Safari

Nothing in this project ate more time than cross‑browser quirks. The concrete ones worth writing down:

Safari: `MediaRecorder` is silent until you ask

In Chrome and Firefox, MediaRecorder.start() with no argument produces one big blob on stop(), or periodic blobs if you give it a timeSlice in ms. In Safari, start() without a timeSlice can silently never emit anything. The recorder thinks it is recording — no errors, no rejected promises, just an eternal nothing.

This one cost us two days in the self‑assessment flow. The fix is a browser‑gated useTimeSlice flag in both recorder classes:

this.useTimeSlice = browserName === "Safari";
…
if (this.useTimeSlice && this.TIME_SLICE > 0) {
  this.mediaRecorder.start(this.TIME_SLICE); // 1000 ms
} else {
  this.mediaRecorder.start();
}

There's a second layer: when the 30‑second chunk boundary fires and the recorder stops and restarts, Safari only starts producing data again if timeSlice is passed to start() every time. So the same flag governs the restart path.

Firefox: device labels are empty until you ask

navigator.mediaDevices.enumerateDevices() returns label: "" for every device until getUserMedia() has been granted at least once. Chrome fills labels pre‑permission if the site has been granted before; Firefox does not. So we enumerate once, request permission, then re‑enumerate and use the new labels to populate the device pickers.

MIME negotiation

Chrome and Firefox prefer WebM (VP8/VP9 video, Opus audio). Safari only reliably encodes MP4 with AVC and AAC. We run a support check at load time and pick the best supported combination, falling back to 'video/mp4; codecs="avc1.42E01E, mp4a.40.2"' for Safari. That decision ripples into the uploaded file extension (.webm vs .mp4), which the backend uses to route to the right post‑processing pipeline.

iOS

On iOS the video constraints always include facingMode: 'user' so the front camera comes up by default; deviceId: { exact: … } on iOS sometimes picks an unexpected lens. A small but persistent source of bug reports until standardising on facingMode.

9. Hardware: check, swap, recover

Because interviews and self‑assessments are recorded evaluations of real people, getting the hardware right matters. Three things help here.

9.1 The pre‑call sound check

Before the user joins a call, a pre‑call sound‑check modal paired with a live volume meter walks them through a microphone test. It spins up an AudioContext + AnalyserNode on a dedicated getUserMedia({ audio: { deviceId: { exact } } }) stream, captures frequency data, tracks a peak dB value, and compares against a −35 dB threshold. If the user's microphone peaks below that, we warn them before the call starts rather than after the interviewer is already waiting.

9.2 Hot‑swap during a call

If a candidate plugs in USB headphones mid‑call, the call must not die. That has two parts:

The media‑devices hook listens to navigator.mediaDevices.ondevicechange with a 1‑second debounce (the event fires several times in quick succession during a plug).
When the user picks a new device, the peer connection is not renegotiated — the track is swapped underneath it using RTCRtpSender.replaceTrack():

// useVideoCall switchTrack (wired from useMediaDevices)
for (const p of participantsRef.current) {
  if (p.state === 'in-call' && p.pc) {
    const sender = p.pc.getSenders().find(s => s.track?.kind === newTrack.kind);
    if (sender) {
      await sender.replaceTrack(newTrack); // no renegotiation
    }
  }
}
localStreamRef.current = newStream;

replaceTrack is the right tool: no new offer/answer, the remote side sees an uninterrupted track, and the recorder (if running) keeps going.

9.3 Recovery when a device vanishes

If the active camera or microphone disappears — USB unplug, OS‑level permission revoked, the browser decides to put a different device in your face — a two‑stage recovery kicks in:

Soft recovery. The track.onended handler marks the device type as "needs replacement". The devicechange debounce fires, we re‑enumerate, pick the first available device of that kind, and call switchDevices through the same replaceTrack path as a normal user swap. To the remote peer, nothing happened.
Hard recovery. If no replacement exists (all cameras unplugged; permissions revoked), the local stream is stopped cleanly, a recovery context is preserved with the old/new device IDs, and a typed error (isNotAllowedError, isNotFoundError, isNotReadableError, isOverconstrainedError) surfaces up to a dedicated media‑error UI. It uses the error flags to show the right remediation — "Grant camera permission", "Plug in a camera", "Close the other app using your camera", etc.

One extra wrinkle: background removal (the virtual‑background feature) generates its own synthetic track with a fake deviceId. Naively writing that synthetic ID back to the selected‑camera state would leave the user with a UUID that doesn't map to any real device the next time they open the settings panel. The fix was to separate user intent (selectedCameraId) from runtime state (currentCamera): when background is on, we remember the originally selected camera ID rather than the synthetic one.

All device operations are serialized through a Semaphore so rapid user clicks on the device dropdown can't produce overlapping getUserMedia calls and orphaned tracks.

10. The recording pipeline

Recording had its own set of challenges because the video call is multi‑party (interviewer + candidate, sometimes more) but the output needs to be a single watchable asset.

For a call (CallRecorder):

Every participant's <video> element is drawn into a 2×2 canvas grid every animation frame. canvas.captureStream() turns that into a MediaStream with a single composite video track.
That composite stream feeds one MediaRecorder for video.
In parallel, each participant's audio track feeds its own MediaRecorder. Keeping audio separate means per‑speaker transcription downstream is straightforward (no need to separate mixed audio), and it sidesteps the issue of WebRTC audio tracks being difficult to mix losslessly on the fly.
Every 30 s the recorders rotate: stop() emits the last blob via ondataavailable, then start(TIME_SLICE) begins the next chunk. Each blob is uploaded immediately, tagged with interviewId, participantId, timestamp, and the media type extension. If the upload fails, the chunk is retried independently — no single network blip can lose the whole recording.

For a self‑assessment (AssessmentRecorder), there is no compositing — it's a single speaker — so a single recorder for the combined stream is enough. What AssessmentRecorder adds is a promise‑based stop barrier: stopRecording() returns a promise that only resolves once the last blob has fired through ondataavailable, so UI code that wants to swap devices knows it's safe to tear down the stream.

Both recorders honour the Safari timeSlice workaround from §8.

11. Testing in the wild

Unit tests can catch protocol bugs, but no unit test will tell you that coturn in Frankfurt is unreachable from a specific Russian ISP this week. So we shipped a client‑side probe.

Per‑server, it spins up a disposable RTCPeerConnection, points it at just that one STUN or TURN server, creates a data channel to force candidate gathering, and waits for the ICE process to complete or fail. The result is one of:

A working STUN server should produce a srflx candidate.
A working TURN server should produce a relay candidate.
Anything else — timeout after 10 s, connection error — means that server is broken for this client.

The result is a simple { url, type, status, candidates[], duration } shape, surfaced in an internal diagnostics page. When a user reports "the call won't connect", they can click one button and instantly see which servers are reachable from their network. This has cut our debug cycle from "multi‑day email thread" to "one screenshot".

On top of the server probes, the interview flow also has an anti‑cheating layer that flags tab switches during an interview — not a WebRTC issue per se, but it rides on the same socket channel, and a missing tab‑switch signal is a useful side‑channel indicator of a broken connection.

12. Lessons learned

Condensed, in no particular order:

Don't trust any single WebRTC state machine. Cross‑check with RTP byte deltas over getStats(). 'connected' is a claim, not a fact.
Buffer ICE candidates. On a slow link they will arrive before setRemoteDescription resolves.
Escalate recovery gradually. Heartbeat → ICE restart → full restart → wait for internet. Full restart too eagerly is worse than letting the call limp for 10 seconds.
Only one side drives recovery. Caller restarts, callee follows. Both restarting is chaos.
Run your own coturn on :443 with TLS. Free STUN servers are fine; free TURN servers either don't exist, don't scale, or are in the wrong country.
Place TURN in multiple jurisdictions when your users live behind national filters. The Russian case made this non‑negotiable for us, but the same logic applies to corporate DPI and strict mobile carriers everywhere. Per‑tenant config lets you route the TURN pool to the client without a redeploy.
Use replaceTrack for device swaps. Renegotiating the whole peer connection on every "switch microphone" click is slow and fragile.
Separate user intent from runtime state when virtual backgrounds or other synthetic tracks enter the picture. Future‑you will thank you.
Safari's MediaRecorder needs timeSlice. Always. And pass it again after every stop/start.
Firefox needs a device re‑enumeration after permission grant. Otherwise your device picker is full of blank labels.
Ship your own server‑reachability probe. The cost is a Saturday; the payoff is being able to diagnose a user's broken network in 30 seconds.

Recruiter.AI's video call still evolves — codec preferences, simulcast, and bandwidth‑adaptive quality are on the roadmap — but the bones described here have held up through thousands of real interviews and self‑assessments, including plenty conducted on networks that would make any WebRTC engineer wince. For anyone building something similar: start with the recovery ladder and the TURN story, not with the UI. Everything else is downstream of getting those two right.

What do you do while waiting for the code?

Andrej Kirejeŭ — Tue, 21 Apr 2026 00:15:37 +0000

Waiting for the LLM to produce the next patch is painful. The last time I spent so much time just waiting was in the late 80s, when the MK-61 programmable calculator took me to the Moon and back. It blinked while crunching the digits (the same way older people murmur numbers when doing addition or subtraction in their heads), running a 105-step program in over a minute.

Yes, there were games for programmable calculators. Plenty of them, actually. There was even a section in a popular Soviet technical magazine where new games were published, discussed, and sometimes accompanied by sci-fi stories based on them.

What do other people do in those moments of waiting now? Just watch the streaming progress, like the heroes in The Matrix watching green falling hieroglyphs? Open another IDE in parallel, trying to match the heroics of Alexei Stakhanov? (They weren’t actually heroic, we know.) Keep an eye on the hopeless Phoenix Suns losing to the Oklahoma City Thunder? Learn a foreign language? Enjoy cute Korean cheerleaders on YouTube? Or just wonder what else you could do once it’s finally done with the programming?

Just curious.

A Correspondence Match

Andrej Kirejeŭ — Thu, 22 Jan 2026 21:52:42 +0000

In the old Polish comedy "Mistrz zawsze traci" from 1976, a crafty French pharmacist arranges a correspondence match between two grandmasters who have never met each other.

For the past couple of days, I’ve been feeling like that very swindler. I explained to Copilot what needed to be done, waited for it to write the code, then wrapped it all up into a pull request. Then I waited for Cursor BugBot to do the review, copied its recommendations, and forwarded them back to Copilot for fixes. And so it goes, round and round.

Alas, exposure awaits us all sooner or later.

How to connect the Next.js MCP server to VS Code Copilot Chat

Andrej Kirejeŭ — Sat, 22 Nov 2025 21:35:49 +0000

The MCP server functionality is built in starting from Next.js 16 and doesn't require any additional configuration in the settings files. The path to the MCP server API is /_next/mcp.

Assuming your dev server is running on the port number 5002, do the following:

In the .vscode folder in the root of your project, create a mcp.json file.

Put the following content inside it:

{
  "servers": {
  "nextjs-mcp": {
    "url": "http://localhost:5002/_next/mcp",
    "type": "http"
  }
},
"inputs": []
}

Save the file.
Run your project's dev server.
Open Copilot Chat.
Ask something specific to Next.js, for example:

nextjs devtools, are there any build errors?
If prompted, allow running the MCP server and executing actions.

In our case, the answer was:

No Next.js devtools build errors are currently reported. Let me know if you want me to keep monitoring or run a build/test explicitly.

Now let's ask what the MCP server could do for us:

nextjs devtools, tell me what you are able to do?

I’m connected to the Next.js devtools MCP server, so I can pull diagnostics like build/runtime errors, fetch the dev-server logs, list app/pages routes, and inspect server actions. If you need anything along those lines—checking status, seeing routes, digging into errors—just let me know which detail you want.

Enjoy, and happy vibe coding!

Unit Testing React Hooks with NextJS Back-End: Challenges and Solutions

Andrej Kirejeŭ — Sat, 31 May 2025 10:30:11 +0000

Implementing unit tests for React hooks that interact with a back-end can be challenging, especially when the back-end server is built with NextJS. As of Spring 2025, Copilot does not provide assistance for this task, so developers must rely on their own expertise. We hope that the insights shared in this document will save others in similar situations from spending excessive time searching through resources and attempting to integrate various libraries.

Initial state:

A NextJS application where the NextJS server also is the application’s back-end server.
A React hook to be tested that heavily interacts with the back-end server.
Node test runner used as testing framework.

Custom server.ts

In our case the server.ts file is customized to accommodate specific back-end logic and provide global data structures shared among Next.js server pages and route handlers.

In development mode, the server is run using the command:

"scripts": {
  ...
  "dev": "cross-env NODE_ENV=development tsx watch --conditions=typescript --tsconfig tsconfig.server.json ./server.ts",
  ...
}

In production mode, the server is built and then executed as a JavaScript script using bare Node.js:

"build": "cross-env NODE_ENV=production next build && tsc --project tsconfig.server.json",
"start": "cross-env NODE_ENV=production node dist/server.js",

To test React hooks outside the browser environment, install the following libraries as development dependencies:

pnpm add @testing-library/dom @testing-library/react global-jsdom jsdom -D

Writing a unit test

For unit testing, a separate instance of the server should be launched before the test begins. The React hook is then tested, and upon completion of the test, the server instance is shut down.

Running node directly appears to be the main issue. Problems were encountered when running the server through pnpm run or tsx; the node test runner would hang at the end until Ctrl-C was manually pressed in the terminal window.

Here are functions to start and safely shut down the server as a child process:

// Server setup
let serverProcess: ChildProcess | null = null;

/**
 * Start the backend server before tests
 */
async function startServer(): Promise<void> {
  return new Promise((resolve, reject) => {
    console.log('Starting server...');

    serverProcess = spawn('node', ['dist/server.js'], {
      cwd: process.cwd(),
      stdio: 'pipe',
      shell: false,
      env: {
        ...process.env,
        NODE_ENV: 'production'
      }
    });

    let serverReady = false;
    const timeout = setTimeout(() => {
      if (!serverReady) {
        reject(new Error('Server failed to start within timeout'));
      }
    }, 30_000);

    if (serverProcess.stdout) {
      serverProcess.stdout.on('data', (data) => {
        const output = data.toString();
        console.log('Server stdout:', output);

        // Look for server ready indicator
        if (output.includes('Server is running on')) {
          if (!serverReady) {
            serverReady = true;
            clearTimeout(timeout);
            // Small delay to ensure server is fully ready
            setTimeout(resolve, 2_000);
          }
        }
      });
    }

    if (serverProcess.stderr) {
      serverProcess.stderr.on('data', (data) => {
        console.log('Server stderr:', data.toString());
      });
    }

    serverProcess.on('error', (error) => {
      console.error('Server process error:', error);
      clearTimeout(timeout);
      reject(error);
    });

    serverProcess.on('exit', (code) => {
      console.log('Server process exited with code:', code);
      clearTimeout(timeout);
      if (!serverReady) {
        reject(new Error(`Server exited with code ${code}`));
      }
    });
  });
}

/**
 * Stop the backend server after tests
 */
async function stopServer(): Promise<void> {
  return new Promise((resolve) => {
    console.log('Cleaning up test environment...');

    if (serverProcess) {
      console.log('Stopping server...');

      // Set up exit handler before killing
      const exitHandler = () => {
        console.log('Server stopped');
        serverProcess = null;
        resolve();
      };

      serverProcess.once('exit', exitHandler);

      // Try graceful shutdown first
      console.log('Sending SIGTERM to server...');
      serverProcess.kill('SIGTERM');

      // Force kill after timeout
      setTimeout(() => {
        if (serverProcess && !serverProcess.killed) {
          console.log('Force killing server...');
          serverProcess.kill('SIGKILL');
          // Give it a moment to clean up
          setTimeout(() => {
            if (serverProcess) {
              serverProcess = null;
            }
            resolve();
          }, 1_000);
        }
      }, 3_000);
    } else {
      resolve();
    }
  });
}

The unit test is as follows:

/**
 * Wait for server to be ready by making health check requests
 */
async function waitForServer(): Promise<void> {
  try {
    const response = await fetch(`http://localhost:${process.env.PORT}`);
    if (response.ok) {
      console.log('Server is ready!');
    } else {
      throw new Error('Server failed to become ready');
    }
  } catch (error) {
    // Server not ready yet
    throw new Error('Server failed to become ready');
  }
};

describe('useObject Hook Tests', async () => {

  before(async () => {
    await startServer();
  });

  after(async () => {
    await stopServer();
  });


  describe('Test Server is Running', async () => {
    it('should ensure the test environment is set up', async () => {
      assert.ok(serverProcess, 'Server process should be running');
      await waitForServer();
      assert.strictEqual(serverProcess?.killed, false, 'Server process should not be killed');
    });
  });

  describe('Test Entity', () => {
    describe('Data Loading', () => {
      it('should load data successfully when entityParam is provided', async () => {
        const { result } = renderHook(() =>
          useObject({
            entityParam: EntityName.Test
          })
        );

        // Initially should be in loading state
        assert.strictEqual(result.current.state, 'loading');
        assert.strictEqual(result.current.data.length, 0);
        assert.strictEqual(result.current.object, null);

        // Wait for data to load
        await waitFor(() => {
          assert.strictEqual(result.current.state, 'success');
        }, { timeout: 10_000 });

        // Verify final state
        assert.strictEqual(result.current.state, 'success');
        assert(Array.isArray(result.current.data));
        assert(result.current.entity);
        assert.strictEqual(result.current.entity.name, 'Test');
      });
    });
  });
});

To conduct the test, it is necessary to initialize a simulated DOM beforehand. This is achieved by passing the –import switch to the tsx utility. The command required is as follows (adjust for the actual .env location in your case):

"test": "pnpm run build && tsx --enable-source-maps --import=global-jsdom/register --test --env-file ../../.env.local"

All sources are compiled in this gist for your convenience.

Высококачественная транскрипция зашумлённых двухканальных телефонных звонков

Andrej Kirejeŭ — Fri, 02 May 2025 07:24:18 +0000

Высококачественная транскрипция зашумлённых двухканальных телефонных звонков

В одном из наших недавних проектов возникла необходимость транскрибировать телефонные звонки с крайне низким качеством звука. Аудиозаписи было трудно разобрать: речь часто прерывалась перекрывающимися голосами оператора и клиента. Кроме того, на стороне клиента часто присутствовали фоновый шум и посторонние звуки, улавливаемые микрофоном. Вдобавок к этому, речь часто содержала смесь языков и суржик.

В предыдущих проектах мы успешно использовали модель WhisperX, которая показала достойные результаты при удовлетворительном качестве аудио. Однако в данном случае полученные транскрипции оказались слишком низкого качества и непригодными для использования.

С выходом модели GPT-4o-transcribe мы решили оценить её возможности. В отличие от Whisper, эта модель принимает детализированные подсказки (prompts), что позволяет значительно улучшить качество транскрипции. Кроме того, GPT-4o-transcribe можно инструктировать распознавать реплики Оператора и Клиента. К сожалению, из-за отсутствия полноценной диаризации модель часто путает, кто из участников говорит.

Клиент возлагал большие надежды на проект, но остался недоволен первым результатом. Он требовал точной транскрипции, но не был готов выделить время или бюджет на сбор обучающих данных, аннотирование аудио или дообучение Whisper. Единственным улучшением по сравнению с исходными записями было то, что аудиоканалы оператора и клиента записывались отдельно.

Первая попытка (неудачная)

Первым логичным шагом было транскрибировать каждый канал отдельно с помощью Whisper, а затем объединить транскрипции по временным меткам. Этот подход не сработал. Whisper сильно «галлюцинирует» во время длинных пауз и на коротких репликах из одного слова. Кроме того, возвращаемые временные метки часто включали не только речь, но и окружающие участки тишины. Попытка скорректировать эти метки с помощью фильтра тишины из ffmpeg тоже не дала удовлетворительных результатов.

Гибридный подход

Мы пересмотрели наш подход. GPT-4o-transcribe выдаёт качественный текст, но без временных меток. Whisper, напротив, даёт временные метки, но при этом сильно теряет в точности. Внимательный человек, сравнивая оба результата, вполне может восстановить точную структуру речи.

Так мы пришли к следующему пайплайну:

Финальный алгоритм

Транскрибировать канал клиента с помощью gpt-4o-transcribe-mini. Затем определить язык речи с помощью GPT-4o. Язык оператора известен заранее.
Транскрибировать оба канала с помощью whisper-1.
- Установить температуру в 0.0.
- Использовать языковой prompt с несколькими типичными фразами.
- Результат — в формате VTT с временными метками.
Транскрибировать оба канала с помощью gpt-4o-transcribe.
- Установить температуру в 0.1.
- Использовать подробные prompts, адаптированные к содержанию каждого канала.

   Prompt для Оператора:

   Ты эксперт в области аудиотранскрипции.

   1. Предоставленный аудиофайл содержит только реплики оператора из телефонного разговора.
   2. Оператор представляет компанию "XXXXXX", работающую под торговой маркой "YYYYYYY", веб-сайт "ZZZZZZZZ".
   3. Оператор рекламирует услуги кредитования. Он описывает условия, процесс выдачи кредита, процентные ставки, комиссии и сборы.
   4. Клиент может задавать вопросы, соглашаться с условиями, отказываться от них или просить больше не звонить.
   5. Разговор может вестись на языке Language1, языке Language2 или быть их сочетанием. Сохраняйте оригинальный язык реплик.
   6. Качество аудио низкое. Исправляйте галлюцинации и нерелевантный контент.

   Предоставь полную транскрипцию.

   Промпт для Клиента:

   Ты эксперт по расшифровке аудио.

   1. Аудио содержит только реплики клиента.
   2. Оператор продвигает кредитные услуги.
   3. Клиент может спрашивать об условиях, ставках, комиссиях или отклонить предложение.
   4. Клиент может запросить дополнительную информацию или отказаться от дальнейшего общения.
   5. Язык может быть украинским, русским или смешанным. Сохраняйте оригинальные языки.
   6. Качество аудио низкое. Исключайте галлюцинации и несвязанный контент.

   Предоставьте полную расшифровку.

4. Сопоставить транскрипт GPT-4o с временными метками Whisper с помощью GPT-4.1, используя следующий prompt:

   Ты эксперт по анализу и восстановлению транскрипций телефонных звонков, связанных с продвижением кредитных услуг.

   Я предоставлю два текста:

   1. Транскрипция, созданная моделью gpt-4o-transcribe.
   2. Транскрипция в формате VTT с помеченными по времени репликами от whisper-1.

   Твоя задача — выровнять первую транскрипцию, используя временные метки из второй.

   * Если тексты отличаются из-за галлюцинаций, используйте версию GPT-4o.
   * Включите весь контент из GPT-4o.
   * Если временная метка отсутствует, добавьте текст к следующей строке   и скорректируйте время начала соответствующим образом.

   Верни только итоговую транскрипцию в формате VTT.

5. Скорректировать временные интервалы реплик Оператора с использованием периодов тишины, полученных через фильтры ffmpeg.

6. Повторить шаги 4–5 для транскрипта Клиента.

7. Объединить финальные VTT-транскрипты обоих каналов, обеспечив правильное распределение реплик по времени и по участникам разговора.

Заключение

Это решение не является ни быстрым, ни дешёвым — оно требует многократных вызовов моделей OpenAI. Однако результат — почти идеальная транскрипция, даже в тех случаях, когда Whisper полностью проваливается.

Исходный код, адаптированный для работы с украинским и русским языками, можно найти здесь.

High-Quality Transcription of Noisy Dual-Channel Phone Calls

Andrej Kirejeŭ — Thu, 01 May 2025 10:16:52 +0000

In one of our recent projects, we needed to transcribe phone calls with extremely poor audio quality. The recordings were hard to decipher, often interrupted by overlapping voices from both the operator and the client. Additionally, the client’s side frequently featured noisy backgrounds and extraneous sounds captured by the microphone. To make matters worse, the speech often contained a mix of languages and Surzhyk.

In our previous work, we had successfully used WhisperX, which performed reasonably well under decent conditions. However, in this case, the quality of the transcriptions was too poor to be useful.

With the release of GPT-4o-transcribe, we decided to evaluate its capabilities. This model accepts detailed prompts, unlike Whisper, which relies on keyword-based prompts. This flexibility significantly improves transcription quality. Moreover, GPT-4o-transcribe can be instructed to distinguish between the Operator and the Client. Unfortunately, due to its lack of true diarization, this often results in confusion between speakers.

The client had high expectations but was dissatisfied with the initial output. They requested accurate transcription but were unwilling to allocate time or budget for collecting training samples, annotating audio, or fine-tuning Whisper. The only improvement we had over raw recordings was that the operator’s and client’s audio channels were recorded separately.

Initial Attempt (Failed)

The first logical approach was to transcribe each channel separately using Whisper, and then merge the transcripts based on the timestamps. This did not work well. Whisper tends to hallucinate heavily during long silences and with short, one-word utterances. Additionally, the returned timestamps often included stretches of surrounding silence rather than isolating the actual speech. We attempted to refine these timestamps using silence detection via ffmpeg, but the results were still inaccurate.

A Hybrid Strategy

We took a step back and reassessed. GPT-4o-transcribe produces high-quality text but lacks timestamps. Whisper, on the other hand, provides timestamps but delivers lower-quality text. An attentive human could easily deduce the correct structure by comparing both.

Thus, we built the following pipeline:

Final Algorithm

Transcribe the Client’s channel using gpt-4o-transcribe-mini. Then, use GPT-4o to detect the spoken language. The Operator's language is known in advance.
Transcribe both channels using whisper-1.
- Set temperature to 0.0.
- Use a language-specific prompt with a few representative phrases.
- The output is in VTT format with timestamps.
Transcribe both channels using gpt-4o-transcribe.
- Set temperature to 0.1.
- Use detailed prompts tailored to each channel’s content.

   Operator’s Prompt:

   You are an expert in the field of audio transcription.
   1. The provided audio file contains only the operator’s lines from a phone conversation.
   2. The operator represents the company "XXXXXX", operating under the trade name "YYYYYYY", website "ZZZZZZZZ".
   3. The operator is advertising credit services.
   4. They describe terms, loan issuance process, interest rates, fees, and commissions.
   5. The client may ask questions, accept or reject terms, or request no further contact.
   6. The language may be Language1, Language2, or a mixture. Preserve original languages.
   7. Audio quality is poor. Fix hallucinations and unrelated content.

   Provide the full transcription.

   Client’s Prompt:

   You are an expert in audio transcription.
   1. The audio contains only the client’s lines.
   2. The operator promotes credit services.
   3. The client may ask about terms, rates, fees, or reject the offer.
   4. The client may request more info or refuse further contact.
   5. Language may be Ukrainian, Russian, or mixed. Preserve original languages.
   6. Audio quality is poor. Fix hallucinations and unrelated content.

   Provide the full transcription.

4. Align the GPT-4o transcript to Whisper’s timestamps using GPT-4.1. Use the following prompt:

   You are an expert in analyzing and reconstructing transcripts of phone calls promoting credit services.
   I will provide two texts:
   1. A transcript generated using the gpt-4o-transcribe model.
   2. A transcript in VTT format with timestamped utterances from whisper-1.
   Your task: align the first transcript using timestamps from the second.
   - If text differs due to hallucinations, use GPT-4o’s version.
   - Include all content from GPT-4o.
   - If a timestamp is missing, prepend the text to the next line and adjust the start time accordingly.

   Return only the final VTT transcript.

5. Correct the Operator’s timestamps using silence periods detected via ffmpeg filters.

6. Repeat steps 4–5 for the Client’s transcript.

7. Merge the final VTT transcripts from both channels, ensuring accurate timestamp ordering and correct speaker attribution.

Conclusion

This solution is neither fast nor cheap — it involves multiple calls to OpenAI models — but it yields nearly perfect transcripts even in cases where Whisper alone fails dramatically.

You can find the code adapted for handling Ukrainian and Russian languages here.

Trees in SQL (part 2)

Andrej Kirejeŭ — Wed, 25 Dec 2024 16:28:43 +0000

This is the second and final part of the article “Trees in SQL”. Following the principles of a good narrative, the most interesting part is saved for the end.

Interval Tree

Up until now, we have tried to work with a tree structure as if it were a graph. The challenges we faced—such as using recursion, an additional table, or a bulky string field—arose because SQL is inherently designed for working with sets rather than graphs.

To represent a tree structure as nested sets, each node must be assigned two integer parameters: a left boundary and a right boundary. These parameters must satisfy the following conditions:

The right boundary of a node must be greater than or equal to the left boundary.
The left boundaries of descendants must be greater than the left boundary of their parent node.
The right boundaries of descendants must be less than or equal to the right boundary of their parent node.
The intervals defined by the left and right boundaries of nodes with the same parent must not overlap.

The following diagram illustrates the representation of a tree as nested sets:

To store an interval-based tree structure, we create the following table:

CREATE TABLE test4 (
  id INTEGER NOT NULL,
  parent INTEGER,
  lb INTEGER NOT NULL,
  rb INTEGER NOT NULL,

  PRIMARY KEY (id),
  FOREIGN KEY (parent) REFERENCES test4 (id)
    ON UPDATE CASCADE
    ON DELETE CASCADE,
  CHECK (lb <= rb)
);

To improve data access speed, two indexes are required:

CREATE INDEX test4_x_lb ON test4 (lb);
CREATE DESCENDING INDEX test4_x_rb ON test4 (rb);

Extracting Subtree Nodes

A query to extract all nodes of a subtree with root node P would look like this:

SELECT t.*
FROM test4 t JOIN test4 t2
  ON t.lb > t2.lb AND t.rb <= t2.rb
WHERE
  t2.id = :P

If we replace the strict inequality on the left boundary with a non-strict one, the root of the subtree will also be included in the result set.

Manipulating Tree Data

Compared to previously discussed structures, interval trees require the most effort when adding a new node or moving a node from one branch to another. In addition to two triggers, a stored procedure is also needed.

We start with the procedure EL_TEST4, which identifies and returns the left boundary for a descendant of a given node (PARENT). If the parent’s interval is exhausted, it will be expanded by at least the value specified by the DELTA parameter. During the interval expansion, all higher-level intervals are also expanded, and intervals to the right are shifted. Intervals falling within the boundaries defined by LB2 and RB2 are excluded from processing to prevent infinite loops when moving a subtree from one parent to another.

CREATE PROCEDURE EL_TEST4 (
  PARENT INTEGER,
  DELTA INTEGER,
  LB2 INTEGER,
  RB2 INTEGER)
RETURNS (
  LEFTBORDER INTEGER)
AS
  DECLARE VARIABLE R INTEGER;
  DECLARE VARIABLE L INTEGER;
  DECLARE VARIABLE R2 INTEGER;
  DECLARE VARIABLE MKey INTEGER;
  DECLARE VARIABLE MultiDelta INTEGER;
BEGIN
  /* Retrieve parent boundaries */
  SELECT rb, lb
  FROM test4
  WHERE id = :Parent
  INTO :R, :L;

  /* Get the rightmost boundary of the parent's descendants, if any */
  R2 = NULL;
  SELECT MAX(rb) FROM test4 WHERE parent = :Parent
    INTO :R2;

  /* If there are no descendants, use the parent's left boundary */
  IF (:R2 IS NULL) THEN
    R2 = :L;

  /* Check if there is enough space for another descendant */
  IF (:R - :R2 < :Delta) THEN
  BEGIN
    /* If not, expand the interval */
    MultiDelta = :R - :L + 100;

    /* Ensure the new range is sufficient */
    IF (:Delta > :MultiDelta) THEN
      MultiDelta = :Delta;

    /* Shift the right boundary of parent intervals */
    IF (:LB2 > -1) THEN
      UPDATE test4 SET rb = rb + :MultiDelta
      WHERE lb <= :L AND rb >= :R
        AND NOT (lb >= :LB2 AND rb <= :RB2);
    ELSE
      UPDATE test4 SET rb = rb + :MultiDelta
      WHERE lb <= :L AND rb >= :R;

    /* Shift both boundaries of intervals to the right of the parent interval */
    IF (:LB2 > -1) THEN
      UPDATE test4
        SET lb = lb + :MultiDelta,
        rb = rb + :MultiDelta
        WHERE lb > :R
          AND NOT (lb >= :LB2 AND rb <= :RB2);
    ELSE
      UPDATE test4
        SET lb = lb + :MultiDelta,
        rb = rb + :MultiDelta
        WHERE lb > :R;
  END

  /* Return the found boundary */
  LeftBorder = :R2 + 1;
END;

The trigger TEST4_BI is called after inserting a record and assigns its left and right boundaries:

CREATE TRIGGER test4_bi FOR test4
  BEFORE INSERT
  POSITION 32000
AS
BEGIN
  /* Check if adding the root of a new tree or a descendant to an existing node */
  IF (NEW.parent IS NULL) THEN
  BEGIN
    /* If adding a new tree, set its left boundary after the highest known right boundary */
    NEW.lb = NULL;
    SELECT MAX(rb) FROM test4 INTO NEW.lb;

    IF (NEW.lb IS NULL) THEN
      /* Adding the first element to the table; use integers >0 for interval boundaries */
      NEW.lb = 1;
    ELSE
      NEW.lb = NEW.lb + 1;
  END ELSE
  BEGIN
    /* Call the procedure to find a possible left boundary for the descendant. 
       If the parent's interval is exhausted, it will be expanded. */
    EXECUTE PROCEDURE el_test4 (NEW.parent, 1, -1, -1)
      RETURNING_VALUES NEW.lb;
  END

  NEW.rb = NEW.lb;
END;

The trigger TEST4_BU adjusts node intervals when moving a node to a different parent:

CREATE EXCEPTION tree_e_invalid_parent
  'Invalid parent';

CREATE TRIGGER test4_bu FOR test4
  BEFORE UPDATE
  POSITION 32000
AS
  DECLARE VARIABLE OldDelta INTEGER;
  DECLARE VARIABLE L INTEGER;
  DECLARE VARIABLE R INTEGER;
  DECLARE VARIABLE NewL INTEGER;
BEGIN
  /* Check for changes in the parent */
  IF ((NEW.parent <> OLD.parent)
    OR (OLD.parent IS NULL AND NOT NEW.parent IS NULL)
    OR (NEW.parent IS NULL AND NOT OLD.parent IS NULL))
  THEN
  BEGIN
    /* Check for circular references */
    IF (EXISTS(SELECT * FROM test4
      WHERE id = NEW.parent
      AND lb >= OLD.lb AND rb <= OLD.rb)) THEN
    BEGIN
      EXCEPTION tree_e_invalid_parent;
    END ELSE
    BEGIN
      IF (NEW.parent IS NULL) THEN
      BEGIN
        /* Retrieve the rightmost boundary */
        SELECT MAX(rb)
        FROM test4
        WHERE parent IS NULL
        INTO :NewL;
        /* Assume at least one element with a null parent exists */
        NewL = :NewL + 1;
      END ELSE
      BEGIN
        /* Retrieve the new left boundary */
        EXECUTE PROCEDURE el_test4 (NEW.parent,
          OLD.rb - OLD.lb + 1, OLD.lb, OLD.rb)
        RETURNING_VALUES :NewL;
      END

      /* Calculate the shift */
      OldDelta = :NewL - OLD.lb;
      /* Shift main branch boundaries */
      NEW.lb = OLD.lb + :OldDelta;
      NEW.rb = OLD.rb + :OldDelta;
      /* Shift child boundaries */
      UPDATE test4
        SET lb = lb + :OldDelta, rb = rb + :OldDelta
        WHERE lb > OLD.lb AND rb <= OLD.rb;
    END
  END
END;

Deleting all nested elements when a node is deleted is ensured by the ON DELETE CASCADE rule on the PARENT field, so no additional actions are required to compress the intervals.

Conclusion

A reasonable question might arise: is there a universally optimal way to organize tree structures in SQL that suits all applications? Unfortunately, the answer is no. Each structure has its strengths and weaknesses that must be evaluated based on the specific requirements of the task. For instance:

What is the total number of records in the table? For small trees, performance differences between methods are minimal and insignificant.
How often will the tree data be modified? Interval trees achieve the best results for data retrieval, but demand significant computational resources for inserting new records or moving nodes.
What is the maximum depth of the tree? For depths of 10 levels or more, the second and third methods (mentioned earlier) result in a significant increase in database size due to the need to store all node connections along the path to the root.
What is more critical for the task: retrieval speed or data storage size?

Ultimately, the choice is left to the database designer, and we hope this article serves as a helpful guide.

Trees in SQL

Andrej Kirejeŭ — Wed, 25 Dec 2024 16:27:47 +0000

Business applications often need to represent and store information such as a company's organizational hierarchy, a country's administrative divisions, an inventory structure, or simply a set of folders and files. Despite their apparent differences, these examples share a common feature— they are all trees. Not the green, wood-made kind that provide pleasant shade on a sunny day, but, mathematically speaking, connected acyclic graphs. In computer science, the links between nodes are described in terms of parent-child relationships. Each node in the tree, except the root, has exactly one parent and zero, one, or many children.

The figure above shows an example of a tree. Vertex A is called the root of the tree. Nodes without subtrees — C, D, F, G, and H — are called leaves. Edges of the tree show parent-child relationships between nodes. A rooted tree is k-ary if each node has no more than k children. A binary tree is a well-known particular case of a k-ary tree where k = 2.

One of the common tasks performed on tree data is the retrieval of all child nodes at any nesting level, given a parent node. For example, calculating the total turnover of an account involves determining the turnovers of all its subaccounts, or compiling a list of goods belonging to a given goods group includes lists from all the nested subgroups.

In imperative programming languages, we usually use a graph traversal algorithm to find all subnodes. Although most modern database servers support SQL queries with recursive common table expressions, using the recursive part inside complex queries on large amounts of data can significantly degrade performance.

The reason is that SQL deals primarily with sets, not graphs, so one should implement dedicated data structures to represent nodes and edges as nested sets for efficient data selection.

In this article, we will consider four ways of storing tree-like structures inside a relational database and evaluate them in terms of query performance and the space needed for storing the underlying data.

Link to the parent

Perhaps the most intuitive and easiest way to represent tree-like data is to use the adjacency matrix in a relational table. Every record in the table corresponds to a node in the tree and holds the unique ID of the node (primary key) and the ID of its parent (for root nodes, the parent is null).

Below is a DDL query that creates the test1 table:

CREATE TABLE test1 (
  id INTEGER NOT NULL,
  parent INTEGER,
  name VARCHAR(60) NOT NULL,
  PRIMARY KEY (id),
  FOREIGN KEY (parent) REFERENCES test1 (id)
    ON UPDATE CASCADE
    ON DELETE CASCADE
)

Pay attention to the ON DELETE CASCADE clause of the FOREIGN KEY constraint declared on the PARENT field. It guarantees that the entire subtree will be deleted at once if the parent node is deleted. To protect the subtree from accidental deletion, the rule should be changed from CASCADE to RESTRICT.

Corresponding data for the tree shown at the beginning of the article looks like:

id	parent	name
1	NULL	A
2	1	B
3	1	E
4	1	H
5	2	C
6	2	D
7	3	F
8	3	G

Operations on tree data

Addition of a new tree node is done by the INSERT INTO operator:

INSERT INTO test1 (id, parent)
VALUES (<unique id of the node>, 
  <id of the parent node or NULL for a root node>)

To move the node from one parent to another, a value of the PARENT field has to be changed:

UPDATE test1
SET parent = <id of the new parent>
WHERE id = <id of the node being moved>

Obviously, to delete the node, one should invoke DELETE FROM operator providing ID of the node.

DELETE FROM test1
WHERE id = <id of the node>

Selecting whole subtree of the given node

With such an organization of the data, a simple SELECT operator allows us to fetch only one level of nesting of node's descendants.

SELECT id
FROM test1
WHERE parent = :P

So, what should we do if the task is to extract all subnodes, regardless of how deep they lie in the subtree?

An unconventional solution would be to write a query for every possible level of nesting and then merge their outputs using the UNION operator. Fortunately, we can use either recursive stored procedures or recursive common table expressions to assist us.

The procedure below returns the IDs of all subnodes of a given node. The second parameter specifies whether the parent node will be included in the resulting set.

CREATE PROCEDURE RecTest1(AnID INTEGER, Self INTEGER)
  RETURNS (ID INTEGER)
AS
BEGIN
  IF (:Self <> 0) THEN
  BEGIN
    ID = :AnID;
    SUSPEND;
  END

  FOR SELECT id FROM test1
  WHERE parent = :AnID INTO :ID
    DO FOR SELECT id FROM RecTest1(:ID, 1) INTO :ID
      DO SUSPEND;
END;

We can use the procedure on its own or JOIN its output with the tree data to select the required columns:

SELECT t.*
FROM test1 t
  JOIN RecTest1(:P, 0) r ON t.id = r.id

If a specific SQL server supports recursive common table expressions, we can write a query that selects all nested subnodes of the given node:

WITH RECURSIVE
  tree AS (
    SELECT id, parent
    FROM test1
    WHERE parent = <id of the given node>

    UNION ALL

    SELECT g.id, g.parent
    FROM test1 g JOIN tree h
      ON g.parent = h.id
  )
SELECT
  gt.id,
  gt.parent
FROM
  tree gt

Storing auxiliary links

In the previous example, we placed an id-parent link in the table with tree data. Since we only know about the relationship between a given node and its children, we need recursive queries to scan the tree in depth, which is not efficient when working with large amounts of data.

To overcome this limitation, an auxiliary table should be introduced. Such a table holds pairs of connected nodes along with the distance between them, where a distance of 1 indicates a parent-child relationship, and distances greater than 1 correspond to deeper levels of ancestry.

CREATE TABLE test2(
  id INTEGER NOT NULL,
  name VARCHAR(60) NOT NULL,
  PRIMARY KEY (id)
);

CREATE TABLE test2_link(
  id_from INTEGER NOT NULL,
  id_to INTEGER NOT NULL,
  distance INTEGER NOT NULL,

  PRIMARY KEY (id_from, id_to),
  FOREIGN KEY (id_from) REFERENCES test2 (id)
    ON UPDATE CASCADE
    ON DELETE CASCADE,
  FOREIGN KEY (id_to) REFERENCES test2 (id)
    ON UPDATE CASCADE
    ON DELETE CASCADE
);

Here is data for the tree:

id_from	id_to	distance
B	A	1
C	B	1
D	B	1
C	A	2
D	A	2
E	A	1
F	E	1
G	E	1
F	A	2
G	A	2
H	A	1

Let's get back to our business. Selection of the subtree now done much easier. No recursion required.

SELECT
  t.*
FROM
  test2 t JOIN test2_link l
    ON l.id_from = t.id
WHERE
  l.id_to = :P

Using distance field, we can arrange the resulting set by node's closeness to the given root node.

Manipulating Tree Data

While we have managed to avoid recursion when retrieving data, this has significantly complicated the processes of inserting and modifying records.

Adding a Node

To add a node, you need to perform two operations: insert into the tree nodes table and the links table.

For example, to add a child node with an identifier 2 to a parent node with an identifier 1, execute the following commands:

INSERT INTO test2 (id) VALUES (2);

INSERT INTO test2_link (id_from, id_to, distance)
VALUES (2, 1, 1);

Creating Triggers

To automate the maintenance of tree relationships, it's advisable to create two triggers.

The first trigger fires after inserting a record into the test2 table and adds a self-referential link with a distance of 0 into test2_link:

CREATE TRIGGER test2_ai FOR test2
AFTER INSERT
POSITION 32000
AS
BEGIN
  INSERT INTO test2_link (id_from, id_to, distance)
  VALUES (NEW.id, NEW.id, 0);
END;

The second trigger fires after inserting a record into the test2_link table.

Its purpose is to create links between the new node and its descendants (if adding a subtree) and all ancestors of the parent node:

CREATE TRIGGER test2_link_ai FOR test2_link
AFTER INSERT
POSITION 32000
AS
DECLARE VARIABLE AnID INTEGER;
DECLARE VARIABLE ADistance INTEGER;
BEGIN
  IF (NEW.distance = 1) THEN
  BEGIN
    INSERT INTO test2_link (id_from, id_to, distance)
    SELECT down.id_from, up.id_to,
           down.distance + up.distance + 1
    FROM test2_link up, test2_link down
    WHERE up.id_from = NEW.id_to
      AND down.id_to = NEW.id_from
      AND down.distance + up.distance > 0;
  END
END;

Moving a Node

To move a node (or subtree) from one parent to another, follow these steps:

Remove the link to the current parent, detaching the subtree:

   DELETE FROM test2_link
   WHERE id_from = <ID of the node or subtree>
     AND id_to = <ID of the current parent>
     AND distance = 1;

Add the subtree to the new parent:

   INSERT INTO test2_link (id_from, id_to, distance)
   VALUES (
     <ID of the node or subtree>,
     <ID of the new parent>,
     1
   );

The previously created insert trigger will handle the new relationships automatically.

Create a trigger that, upon deleting a link with a distance of 1, removes all links between the nodes of the subtree and the nodes along the path from the parent node to the tree root:

CREATE TRIGGER test2_link_bd FOR test2_link
BEFORE DELETE
POSITION 32000
AS
DECLARE VARIABLE AnIDFrom INTEGER;
DECLARE VARIABLE AnIDTo INTEGER;
BEGIN
  IF (OLD.distance = 1) THEN
  BEGIN
    FOR
      SELECT down.id_from, up.id_to
      FROM test2_link down
      JOIN test2_link up
        ON up.id_from = OLD.id_from
       AND up.distance + down.distance > 1
       AND down.id_to = OLD.id_from
      INTO :AnIDFrom, :AnIDTo
    DO
      DELETE FROM test2_link
      WHERE id_from = :AnIDFrom
        AND id_to = :AnIDTo;
  END
END;

Deleting a Node

Deleting a node doesn't require special handling, as foreign keys in the test2_link table are configured for cascading deletions.

When a node is deleted from the test2 table, all related records in test2_link are automatically removed:

DELETE FROM test2 WHERE id = <Node ID>;

Ensuring Data Integrity

To maintain logical data integrity and adherence to our model, create two additional triggers.

The first trigger prevents editing records in the test2_link table:

CREATE EXCEPTION tree_e_incorrect_operation
  'Incorrect operation';

CREATE TRIGGER test2_link_au FOR test2_link
BEFORE UPDATE
POSITION 32000
AS
BEGIN
  EXCEPTION tree_e_incorrect_operation;
END;

The second trigger deletes a node if a record with a distance of 0 is removed from the links table:

CREATE TRIGGER test2_link_ad FOR test2_link
AFTER DELETE
POSITION 32000
AS
BEGIN
  IF (OLD.distance = 0) THEN
  BEGIN
    DELETE FROM test2 WHERE id = OLD.id_from;
  END
END;

These measures will help maintain data integrity and ensure the correct tree structure within the database.

Composite Path

It's not necessary to use a separate table to store the list of nodes leading to the root of a tree. Instead, you can concatenate the ordered list of node identifiers into a string, using a chosen delimiter, and store it directly within the node records table. For example:

CREATE TABLE test3 (
  id INTEGER NOT NULL,
  parent INTEGER,
  path VARCHAR(60) NOT NULL,

  PRIMARY KEY (id),
  FOREIGN KEY (parent) REFERENCES test3 (id)
    ON UPDATE CASCADE
    ON DELETE CASCADE
);

To optimize retrieval operations using the STARTING WITH operator, it's essential to create the following index to enhance performance:

CREATE INDEX test3_x_path ON test3 (path);

If you choose a forward slash (/) as the delimiter, the test3 table for the tree depicted in the figure above would be populated as follows:

id	parent	path
A	NULL	/
B	A	/A/
C	B	/A/B/
D	B	/A/B/
E	A	/A/
F	E	/A/E/
G	E	/A/E/
H	A	/A/

Retrieving Subtree Nodes

To retrieve all nodes in the subtree rooted at node P, execute the following query:

SELECT *
FROM test3
WHERE path STARTING WITH
  (SELECT path FROM test3 WHERE id = :P);

If you wish to exclude the root node itself from the results, modify the query accordingly:

SELECT *
FROM test3
WHERE path STARTING WITH
  (SELECT path FROM test3 WHERE id = :P)
  AND id <> :P;

Manipulating Tree Data

Similar to the simplest method of organizing hierarchical data discussed earlier, adding, moving, or deleting a node can be accomplished using standard SQL commands: INSERT, UPDATE, or DELETE.

The automatic generation of the path string can be managed by implementing the following triggers:

CREATE TRIGGER test3_bi FOR test3
  BEFORE INSERT
  POSITION 32000
AS
  DECLARE VARIABLE P INTEGER;
BEGIN
  NEW.path = '';
  P = NEW.parent;
  WHILE (NOT :P IS NULL) DO
  BEGIN
    NEW.path = CAST(:P AS VARCHAR(60)) || '/'
      || NEW.path;
    SELECT parent
    FROM test3
    WHERE id = :P
    INTO :P;
  END
  NEW.path = '/' || NEW.path;
END;

CREATE EXCEPTION tree_e_incorrect_operation2
  'Incorrect operation';

CREATE TRIGGER test3_bu FOR test3
  BEFORE UPDATE
  POSITION 32000
AS
  DECLARE VARIABLE P INTEGER;
  DECLARE VARIABLE T INTEGER;
  DECLARE VARIABLE NP VARCHAR(60);
  DECLARE VARIABLE OP VARCHAR(60);
BEGIN
  IF((NEW.parent <> OLD.parent)
    OR (NEW.parent IS NULL AND NOT OLD.parent IS NULL)
    OR (NOT NEW.parent IS NULL
      AND OLD.parent IS NULL)) THEN
  BEGIN
    NEW.path = '';
    P = NEW.parent;
    WHILE (NOT :P IS NULL) DO
    BEGIN
      NEW.path = CAST(:P AS VARCHAR(60)) || '/'
        || NEW.path;
      SELECT parent
      FROM test3
      WHERE id = :P
      INTO :P;
    END
    NEW.path = '/' || NEW.path;

    /* Check for circular references */
    IF (POSITION(('/' ||
      CAST(NEW.id AS VARCHAR(60)) || '/')
      IN NEW.path) > 0) THEN
      EXCEPTION tree_e_incorrect_operation2;

    NP = NEW.path ||
      CAST(NEW.id AS VARCHAR(60)) || '/';
    OP = OLD.path ||
      CAST(OLD.id AS VARCHAR(60)) || '/';
    T = LENGTH(OP) + 1;

    UPDATE test3
    SET path = :NP || SUBSTRING(path FROM :T FOR 60)
    WHERE path STARTING WITH :OP;
  END
END;

Storing the composite path from the tree root to the current node imposes a limitation on the maximum tree depth, approximately equal to L div (K + 1), where L is the length of the string field used to store the path, and K is the average length of the string representation of the record key.

Go to the part 2...

Using Node's built-in test runner with Turborepo

Andrej Kirejeŭ — Sun, 22 Dec 2024 11:00:15 +0000

It takes only five easy steps to add unit tests to a Turborepo monorepo. No external testing frameworks, such as Jest or Mocha, are needed.

1. Add tsx at the monorepo’s root level to run TypeScript code without issues related to different module systems:

npm add --dev tsx

2. Add a test task to turbo.json:

{
  ...
  "tasks": {
    "test": {
      "outputs": []
    },
    ...
  },
  ...
}

3. Add a test script in every package.json where necessary:

  "scripts": {
    ...
    "test": "tsx --test"
  },

4. Add a test script into the monorepo's root package.json:

  "scripts": {
   ... 
   "test": "turbo run build && turbo run test"
  }

The build step is optional, but it ensures the project compiles successfully before running tests. Alternatively, add a dependency on the build step in turbo.json.

5. That is it. Now add your first test using the built-in Node.js test runner functionality:

add.ts

  export function add(a: number, b: number) {
    return a + b;
  };

add.test.ts

import assert from 'node:assert/strict';
import { describe, it } from 'node:test';
import { add } from './add.ts';

describe('Test addition', () => {
  it('should add two positive numbers', () => {
    assert.equal(add(2, 2), 4);
  });

  it('should add two negative numbers', () => {
    assert.equal(add(-2, -2), -4);
  });
});

Finally, give it a try by running:

npm run test

What about starting a new platform?

Andrej Kirejeŭ — Tue, 30 Jan 2024 20:58:45 +0000

Twenty-five years ago, a significant leap in software development speed occurred when Borland Delphi entered the market with an entirely new approach: component-driven visual programming. Around that time, ideas for integrating relational databases into the object-oriented world evolved into robust ORM concepts. While numerous developers were stuck with either the laborious task of C++ development using the complicated MFC library or the clumsy and limited Visual Basic interpreter, we were eager to dive into this brave new world. With a small team of ten developers, we won a competition over more formidable and larger rivals, becoming one of the IT leaders in our country for the next two decades.

Over the last two years, I have dedicated my time to studying new technologies and observing the trends in modern software development. Now, I have a strong sense of déjà vu. We are once again on the cusp of a new technological shift, and those who quickly board this accelerating train will reap the most significant benefits, vastly outperforming competitors who cling to obsolete platforms and tools.

If I were to start a new platform right now, I would undoubtedly use the following strategies:

Full-stack development using Node.js, Next.js, and React Native. This approach is a significant time and effort saver. In our recent projects, we often have developers single-handedly implementing a complete feature—including server-side code, web application, and mobile applications for both Android and iOS—in just one to two weeks. I know teams that adhere to the classic back-end/front-end separation and spend more time just discussing data exchange protocol details.
Decouple the ER model from the physical database. This flexibility allows easy switching and mixing of SQL/NoSQL databases. When we were laying the first modules of our Gedemin platform in the late '90s, the low-level integration with the database driver code allowed us to utilize every bit of memory (which was scarce at that time) and maximize CPU cycle efficiency. Times have changed, and computational power is much cheaper now; there's no need to be as frugal as we once were.
Avoid manually drawing the UI. Well, JSX is great, but instead of mixing your code with HTML tags, build an engine that renders screens and forms based on ER entities and provided rules. This approach allows you to change the program's look and feel as easily and quickly as a snake sheds its skin during molting.
Eliminate even the slightest compatibility concerns. Embrace every novel feature CSS/HTML/JS has to offer without fear. By the time your program hits the market, these technologies will be implemented in even the most basic devices.
Integrate AI services extensively. Functions like natural language queries, human-like summaries and reports, and interpretation of commands and instructions, once the stuff of science fiction books 15–20 years ago, are now just a matter of making calls to the OpenAI API.

DEV Community: Andrej Kirejeŭ

Отказоустойчивые видеозвонки на WebRTC

1. Почему понадобилось свое решение

2. Общая картина

3. Сигнальный сервер: минимальный, восстанавливаемый, свой

4. STUN, TURN и проблема юрисдикций

Проблема российской фильтрации

Сборка конфигурации

5. Идеальное согласование (Perfect Negotiation) с буферизацией ICE

6. Восстановление: шаг за шагом

7. Как мы находим замерший медиапоток

8. Браузерные войны: Chrome, Firefox, Safari

Safari: MediaRecorder требует timeSlice

Firefox: названия устройств пустые, пока не запросишь доступ

Выбор MIME

iOS

9. Оборудование: проверить, заменить, восстановить

9.1 Проверка микрофона перед звонком

9.2 Горячая замена во время звонка

9.3 Восстановление, когда устройство исчезло

10. Конвейер записи

11. Тестирование в реальном мире

12. Что мы вынесли

Building a Resilient WebRTC Video Call

1. Why this was built

2. The big picture

3. The signaling server: thin, recoverable, ours

4. STUN, TURN, and the jurisdiction problem

The Russian filter problem

Building the config

5. Perfect Negotiation with buffered ICE

6. Recovery, step by step

7. Detecting frozen media

8. Browser wars: Chrome, Firefox, Safari

Safari: MediaRecorder is silent until you ask

Firefox: device labels are empty until you ask

MIME negotiation

iOS

9. Hardware: check, swap, recover

9.1 The pre‑call sound check

9.2 Hot‑swap during a call

9.3 Recovery when a device vanishes

10. The recording pipeline

11. Testing in the wild

12. Lessons learned

What do you do while waiting for the code?

A Correspondence Match

How to connect the Next.js MCP server to VS Code Copilot Chat

Unit Testing React Hooks with NextJS Back-End: Challenges and Solutions

Initial state:

Custom server.ts

Writing a unit test

Высококачественная транскрипция зашумлённых двухканальных телефонных звонков

Высококачественная транскрипция зашумлённых двухканальных телефонных звонков

Первая попытка (неудачная)

Гибридный подход

Финальный алгоритм

Заключение

High-Quality Transcription of Noisy Dual-Channel Phone Calls

Initial Attempt (Failed)

A Hybrid Strategy

Final Algorithm

Conclusion

Trees in SQL (part 2)

Interval Tree

Extracting Subtree Nodes

Manipulating Tree Data

Conclusion

Trees in SQL

Link to the parent

Operations on tree data

Selecting whole subtree of the given node

Storing auxiliary links

Manipulating Tree Data

Adding a Node

Creating Triggers

Moving a Node

Deleting a Node

Ensuring Data Integrity

Composite Path

Safari: `MediaRecorder` требует `timeSlice`

Safari: `MediaRecorder` is silent until you ask