DEV Community: Andrej Kirejeŭ

Бухгалтерия на естественном языке: каким должен быть MCP-сервер. Часть 4

Andrej Kirejeŭ — Sat, 31 Oct 2026 14:46:15 +0000

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

Сложные вопросы

Возьмём вопрос "почему упала прибыль в третьем квартале". Цепочку рассуждений строит модель на стороне клиента. Задача сервера — давать проверяемые факты: каждый инструмент возвращает цифру с указанием, как она получена, а выводы модель делает сама.

sequenceDiagram
    actor U as Пользователь
    participant L as LLM
    participant S as MCP-сервер
    participant W as Веб-поиск
    U->>L: Почему упала прибыль в III квартале?
    L->>U: Сравниваем со II кварталом или с III кварталом прошлого года?
    U->>L: С прошлым годом
    L->>S: get_pnl([2025-Q3, 2026-Q3])
    S-->>L: прибыль -18%, валовая прибыль -12%
    L->>S: compare_periods("Валовая прибыль", 2025-Q3, 2026-Q3, by="Номенклатура")
    S-->>L: три группы товаров дают 80% снижения
    L->>S: factor_analysis(2025-Q3, 2026-Q3, by="Номенклатура")
    S-->>L: цена +2%, объём -4%, себестоимость единицы +11%
    L->>S: get_one_off_items(2026-Q3)
    S-->>L: курсовые разницы по импортным поставкам
    L->>W: курс валюты, цены поставщиков отрасли
    W-->>L: валюта подорожала на 9% за год
    L->>U: Выводы, гипотезы, рекомендации

Рис. 7 Цепочка вызовов при анализе причин снижения прибыли.

Методику анализа лучше не оставлять на вдохновение модели, а записать как сценарий: в одних клиентах это MCP prompts, в других — файл инструкций или навык. Для нашего вопроса сценарий примерно такой:

Уточнить период, базу сравнения и организацию.
Получить отчёт о прибылях и убытках за оба периода и помесячную динамику.
Найти статьи с наибольшим вкладом в отклонение.
Разложить отклонение на факторы цены, объёма и структуры.
Отделить разовые события от устойчивых тенденций.
Сопоставить с внешней средой: курсы валют, спрос в отрасли, цены поставщиков, ставки.
Сформулировать выводы и рекомендации.

Ответ тоже стоит разметить. Сначала два-три предложения вывода с ключевыми цифрами. Дальше факты из учёта — с указанием, каким инструментом, за какой период и по какому показателю они получены. Потом внешние факторы со ссылками на источники. Гипотезы отдельно, вместе с тем, чем их можно проверить. И только в конце рекомендации, по возможности с оценкой эффекта. Так руководитель сразу видит, где цифры, а где догадки.

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

Чему нас научила разработка

Архитектура из третьей части сложилась не сразу. Начинали мы с наивной схемы из первой части (рис. 1), и большинство проблем, описанных во второй, увидели именно на ней.

Первый урок преподал главный бухгалтер. Он спросил, сколько мы должны одному из поставщиков. Модель ответила, что задолженности нет, хотя она была. Оказалось, что модель отбирала проводки по счёту 60 по объекту аналитики не того вида: искала поставщика среди договоров, а не среди контрагентов. В этом случае отбор не нашёл записей, и пустую сумму модель доложила как ноль. Главбух знал ответ заранее и проверял систему, поэтому ошибку заметили сразу. С тех пор сервер, получив пустой результат по счёту с аналитикой, сам добавляет к нему предупреждение: проверь, те ли объекты аналитики ты ищешь. По нашим наблюдениям, такая подсказка в ответе помогает заметно чаще, чем то же правило в общей документации.

Второй урок — про несуществующие поля. Модель раз за разом просила у таблицы оборотов в корреспонденции поле, которое бывает только у таблицы остатков. СУБД возвращала ошибку обращения к несуществующему полю, модель пробовала снова, с другим, тоже несуществующим полем, и после трёх-четырёх попыток сдавалась. Помогла предварительная проверка: сервер ещё до выполнения смотрит, к каким полям обращается запрос, и сразу возвращает список допустимых с ближайшими по написанию вариантами. Теперь модель обычно исправляется с первой попытки.

Ошибались, впрочем, не только модели. В одном из наших собственных инструментов отбор по счёту стоял во внешнем WHERE, а не в параметрах функции, которая считает остатки. Упрощённо это выглядит так:

-- было
SELECT * FROM account_saldo(:date) WHERE account_code LIKE '62.%'
-- стало
SELECT * FROM account_saldo(:date, '62', :include_subaccounts)

Без параметра счёта функция не знает, по каким объектам аналитики разворачивать сальдо, и возвращает по каждому счёту одну строку со свёрнутым остатком. Внешний WHERE отбирает нужные строки, но детализация по покупателям уже потеряна внутри функции, и развёрнутое сальдо из этих строк не получить. Для свёрнутого остатка такой запрос всего лишь медленнее: функция считает остатки по всем счетам, а нужен один. Ошибку нашли, когда сверили ответ сервера с оборотно-сальдовой ведомостью по счёту 62.

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

Из журнала работы сервера со временем вырастает коллекция удачных запросов. Проверенные пары "вопрос — запрос" заметно улучшают следующие запросы, а самые частые шаблоны в конце концов становятся отдельными инструментами.

Дороже всего обошлась защита персональных данных. Задача выглядела простой: перед отправкой в облачную модель заменить наименования контрагентов и фамилии псевдонимами. Закрыли прямой выбор поля — тестировщик достал то же значение через приведение типа, например CAST(name AS VARCHAR(200)). Закрыли и это — значение пришло через временную таблицу, куда его сначала скопировали. Потом через выражение с лишним пробелом, которого не ожидал разборщик запросов. Каждая правка закрывала один способ, а тестировщик вскоре находил следующий. Маскировка поверх произвольного SQL так и остаётся эвристикой, а не гарантией, да к тому же ощутимо тормозит сервер. Если требования к конфиденциальности жёсткие, произвольный SQL лучше ограничить с самого начала и отдавать данные только через инструменты, где состав полей известен заранее.

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

Заключение

Прямой доступ модели к учётной базе даёт эффектную демонстрацию и ненадёжные цифры. SQL модель знает хорошо. Как в конкретной системе хранятся сложные проводки, аналитика, внутренние обороты и служебные записи, — не знает. Поэтому учётную логику должен считать сервер, а лучше всего штатный движок отчётов. Модели остаётся то, что у неё действительно получается: выбрать инструмент, рассудить и объяснить.

Есть ли универсальный набор инструментов на все случаи жизни? К сожалению, нет. Состав инструментов зависит от ответов на несколько вопросов:

Можно ли вызвать движок отчётов системы без пользовательского интерфейса?
Как хранятся проводки: парами или сторонами, и бывают ли сложные проводки?
Как хранится аналитика: в универсальных колонках, в отдельной колонке на каждый вид или в многоуровневых аналитических счетах?
Как формируются проводки: кодом проведения документа или настраиваемыми шаблонами типовых операций?
Описывают ли метаданные системы реквизиты документов, или их придётся описывать вручную?
Какие требования предъявляются к конфиденциальности данных, передаваемых в облачную модель?

От ответов на эти вопросы зависит, какую часть учётной логики придётся перенести на сервер. И какой бы она ни оказалась, серверные расчёты нужно сверять со штатными отчётами системы: именно с ними пользователь будет сравнивать ответы модели.

На этом цикл заканчивается. В первой части речь шла о выборе между частным и универсальным сервером, во второй — об ошибках модели при прямом доступе к учётной базе, в третьей — об архитектуре и инструментах сервера.

Бухгалтерия на естественном языке: каким должен быть MCP-сервер. Часть 3

Andrej Kirejeŭ — Sat, 31 Oct 2026 14:45:49 +0000

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

Архитектура сервера

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

flowchart TB
    U[Пользователь] <--> C[LLM-клиент]
    C <-->|MCP| G[Слой ограничений:<br/>только чтение, лимиты, аудит]
    subgraph S[MCP-сервер]
        G --> T1[Уровень 1<br/>учётные регистры, отчёты, аналитика]
        G --> T2[Уровень 2<br/>поиск объектов]
        G --> T3[Уровень 3<br/>документы и SQL]
        G --> K[База знаний<br/>правила проведения, показатели]
    end
    T1 --> R[Движок отчётов<br/>учётной системы]
    T2 --> DB[(Реплика БД)]
    T3 --> DB
    R --> DB
    K -.->|готовится заранее| DB
    C <-->|веб-поиск| W[Внешние данные]

Рис. 4 Архитектура: три уровня доступа к данным и база знаний.

На первом уровне живут учётные регистры и отчёты: оборотно-сальдовая ведомость, журнал-ордер, карточка и анализ счёта, а с ними аналитические инструменты. Цифры здесь обязаны совпадать с тем, что пользователь видит в системе, копейка в копейку. Поэтому лучше всего, если сервер вызывает штатный движок отчётов, а не изобретает его заново.

Второй уровень — поиск. Пользователь говорит "Ромашка" или "расчёты с поставщиками", а инструментам нужны коды и идентификаторы. Инструменты поиска сопоставляют одно с другим.

Третий уровень — данные первичных документов и SQL. У каждого вида документа есть реквизиты, которые в аналитику проводок не попадают: ставка НДС, склад, условия оплаты. Без них многие вопросы остаются без ответа. Описывать вручную сотни видов документов долго, и описания быстро устаревают, поэтому описание схемы сервер строит сам, по метаданным системы.

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

Порядок выбора инструмента записывается в инструкциях сервера:

flowchart TD
    Q[Вопрос пользователя] --> F[Найти объекты:<br/>счета, контрагентов, номенклатуру]
    F --> A{Покрывается учётным<br/>регистром или отчётом?}
    A -->|да| R1[Уровень 1]
    A -->|нет| B{Нужны реквизиты<br/>документов?}
    B -->|да| R2[query_documents]
    B -->|нет или мало| R3[run_sql с примерами<br/>и предварительной проверкой]
    R1 & R2 & R3 --> X{Нужно объяснить,<br/>откуда цифра?}
    X -->|да| K[Правила проведения,<br/>статистика проводок]
    X -->|нет| Ans[Ответ с периодом,<br/>организацией и источником]
    K --> Ans

Рис. 5 Порядок выбора инструмента.

Инструменты

Перечислим инструменты, которые, на наш взгляд, нужны серверу. Параметры даны схематично, в нотации TypeScript; знак ? отмечает необязательный параметр. Список длинный, поэтому описания инструментов должны чётко различаться: по ним модель выбирает подходящий. Какие описания и когда попадают в контекст модели, зависит от клиента.

Несколько правил касаются всех инструментов сразу. Параметры задаются на языке бухгалтера: код счёта "60.1", период "2026-Q3", наименование контрагента; внутренние идентификаторы модель получает только от инструментов поиска. Итоги и сальдо считает сервер и возвращает их всегда, даже если сами строки обрезаны постраничным выводом: длинные столбцы чисел языковые модели складывают ненадёжно. В ответ включаются применённые фильтры, валюта сумм, признак учёта внутренних оборотов, дата среза и параметры перехода к детализации: из строки оборотно-сальдовой ведомости — к карточке счёта, из строки карточки — к документу. А ошибки пишутся для модели, а не для программиста: "Счёт 60.5 не найден, ближайшие: 60.1, 60.2" вместо трассировки стека.

Параметры учётных регистров едины для всех форм, как и в самих учётных системах:

type Period = { from: string; to: string } | string;   // "2026-09", "2026-Q3"

interface LedgerParams {
  period: Period;
  accounts: string[];                 // ["60", "62"]
  include_subaccounts?: boolean;      // по умолчанию true
  include_internal?: boolean;         // внутренние обороты, по умолчанию false
  filter?: Record<string, string[]>;  // { "Контрагенты": ["Ромашка"] }
  group_by?: string[];                // порядок важен: ["Подразделение", "Номенклатура"]
  quantity?: boolean;                 // количественные показатели
  currency?: "national" | "currency" | "both";
  company?: string;                   // организация, по умолчанию текущая
  expanded_balance?: boolean;         // развёрнутое сальдо
}

Уровень 1: учётные регистры и отчёты

get_chart_of_accounts(root?: string, depth?: number)
  // план счетов: код, наименование, вид (А/П/АП), объекты аналитики,
  // признаки количественного и валютного учёта, подробное описание счёта

get_balance(account: string, date: string, filter?, expanded_balance?: boolean)
  // сальдо на дату

get_trial_balance(params: LedgerParams)
  // оборотно-сальдовая ведомость

get_journal_order(account: string, params: LedgerParams)
  // журнал-ордер по кредиту счёта и ведомость по дебету

get_account_card(account: string, params: LedgerParams & {
  corr_account?: string; corr_side?: "D" | "C"; merge_identical?: boolean })
  // карточка (карта) счёта: проводки с документами и текущим сальдо

get_account_analysis(account: string, params: LedgerParams)
  // анализ счёта (шахматка): обороты в корреспонденции со счетами

get_general_ledger(period: Period, accounts?: string[])
  // главная книга

list_saved_reports(query?: string)
run_saved_report(name: string, period: Period)
  // настройки отчётов, которые бухгалтеры уже сохранили в системе

list_reports(query?: string)
get_report_info(id: string)              // описание и параметры
run_report(id: string, params: object)   // данные, а не печатная форма

Уровень 2: поиск объектов

find_account(query: string)          // по коду, наименованию или смыслу
find_counterparty(query: string)     // наименование, УНП/ИНН, часть наименования
find_item(query: string)             // номенклатура
find_document_type(query: string)
find_analytic_value(kind: string, query: string)
  // все возвращают список кандидатов с признаками для различения;
  // при неоднозначности модель переспрашивает пользователя

Уровень 3: документы и SQL

search_schema(text: string)
  // "где хранится ставка НДС", "в каких документах есть склад"

get_document_type_schema(type: string)
  // таблицы вида документа, поля с понятными названиями,
  // ссылки на справочники, заполненность полей, шаблон запроса

query_documents(type: string, fields: string[], filter?: object,
                group_by?: string[], only_with_entries?: boolean)
  // универсальный запрос к любому виду документа без написания SQL

get_documents(type?: string, period?: Period, counterparty?: string)
get_document(id: string)              // шапка, табличная часть и проводки

describe_core()                       // описание базовых представлений
get_sql_examples(topic: string)       // проверенные пары "вопрос - SQL"
validate_sql(query: string)           // предварительная проверка без выполнения
run_sql(query: string, limit?: number)

Базовых представлений — плана счетов, проводок, документов — немного, и пишутся они вручную. В представлении проводок уже обезврежены все ловушки, о которых шла речь во второй части. Как бы ни хранились проводки в системе, оно отдаёт их в двух формах: по счетам, для оборотов и сальдо, и парами корреспонденции с правильными суммами. Объекты аналитики развёрнуты в именованные колонки с наименованиями, служебные записи помечены.

База знаний и аналитика

get_posting_rule(doc_type: string)
  // карточка правила проведения: какие проводки формирует документ и при каких условиях

get_posting_stats(doc_type?: string, period?: Period)
  // фактические корреспонденции счетов: сколько проводок, на какие суммы

list_metrics()
get_metric_definition(name: string)   // выручка, себестоимость, валовая прибыль...

get_pnl(periods: Period[], breakdown?: string)        // отчёт о прибылях и убытках
compare_periods(metric: string, a: Period, b: Period, by?: string)
  // отклонение показателя с разложением по вкладу
factor_analysis(a: Period, b: Period, by?: string)    // цена, объём, структура
get_metric_series(metric: string, period: Period, step: "month" | "quarter", by?: string)
get_top_contributors(metric: string, period: Period, by: string, n?: number)
get_aging(account: string, date: string, buckets?: number[])
  // старение дебиторской и кредиторской задолженности
get_one_off_items(period: Period, threshold?: number)
  // разовые операции: крупные списания, резервы, курсовые разницы
export_dataset(query: object)          // выгрузка в CSV для расчётов в клиенте

Служебные

get_database_overview()
  // дата среза данных, организации, валюта учёта, закрытые периоды,
  // горизонт данных — то, с чего модели стоит начинать разговор

Отдельно скажем об описаниях инструментов: на них не стоит экономить. Хорошее описание говорит не только что инструмент делает, но и когда им пользоваться, а когда нет. Именно по описанию модель решает, построить журнал-ордер штатным отчётом или сочинить свой запрос.

Знание предметной области

Карточки правил проведения

Проводки появляются по правилу, которое срабатывает при проведении (отработке) документа. Где-то это программный код обработчика в модуле документа. Где-то — типовая хозяйственная операция или образец операции: шаблон проводок с формулами сумм, который настраивает пользователь, а если формул не хватает, дописывает скрипт. Суть одна: есть правило, по которому хозяйственная операция, оформленная документом, превращается в проводки. Так не отдать ли это правило модели целиком — пусть разбирается?

Не стоит. Учётная логика в коде проведения перемешана с циклами, обработкой ошибок и обращениями к объектам системы, и модели пришлось бы заново восстанавливать смысл при каждом вопросе. Удобнее один раз изложить правило в виде короткой карточки, например:

Поступление материалов от поставщика. Дт 10 / Кт 60 — сумма без НДС; Дт 19 / Кт 60 — НДС. Аналитика: поставщик, договор, номенклатура, склад. Если в документе указан признак "импорт", вместо субсчёта 60.1 "Расчёты в национальной валюте" используется 60.2 "Расчёты в иностранной валюте". Если не заполнен склад, проводки не формируются.

Составляет такие карточки тоже языковая модель, но без проверки её результат мы не используем. Процесс выглядит так:

Сервер собирает для правила проведения код со всеми вызываемыми функциями, описание реквизитов документа, статистику проводок за год и два-три реальных документа.
Модель пишет черновик карточки. Всё, что она не поняла однозначно, уходит в отдельное поле "неясности": додумывать запрещено.
Черновик сверяется со статистикой фактических проводок.
Карточка проходит проверку предсказанием.
Если проверка не пройдена, карточку смотрит человек.

flowchart LR
    C[Код проведения<br/>и зависимости] --> I[Сборка входа]
    M[Метаданные документа] --> I
    St[Статистика проводок<br/>за год] --> I
    Ex[2-3 реальных документа] --> I
    I --> L[LLM: черновик карточки]
    L --> V1{Сверка со<br/>статистикой}
    V1 --> V2{Проверка<br/>предсказанием}
    V2 -->|расхождения| H[Проверка человеком]
    V2 -->|ок| OK[Карточка в базе знаний]
    H --> OK

Рис. 6 Подготовка карточки правила проведения.

Сверка со статистикой ловит грубые промахи: если в карточке есть корреспонденция, которой нет в данных, это либо мёртвая ветка кода, либо выдумка модели. Проверка предсказанием тоньше. Отдельный вызов модели получает только карточку и реквизиты 10–20 случайных документов и должен угадать их проводки. Если проводки не совпали, значит, в карточке чего-то не хватает.

Особое внимание — полю "при каких условиях проводки не формируются". В одних системах у документа есть явный признак "проведён" или "отработан в учёте". В других его нет вовсе, и непроведённый документ изображают условием в правиле проведения. Модель в любом случае должна знать, какие документы на учёт не повлияли.

Определения показателей

Для аналитики модели нужно знать, что считать выручкой, себестоимостью и прибылью в рабочем плане счетов организации. Если оставить это на её усмотрение, на один и тот же вопрос она может давать разные цифры.

Пример. Выручка отражается по кредиту субсчёта 90.1 вместе с НДС, сам НДС — по дебету субсчёта 90.3 "Налог на добавленную стоимость". Кроме того, организация сдаёт в аренду часть склада, и арендная плата, раз аренда для неё не основная деятельность, идёт по кредиту субсчёта 91.1 "Прочие доходы". За III квартал по кредиту 90.1 прошло 1 200 000, по дебету 90.3 — 200 000, по кредиту 91.1 — 150 000.

Финансовый директор три дня подряд спрашивает одно и то же: "Какая выручка за III квартал?"

День	Как модель посчитала выручку	Ответ
Понедельник	Кредитовый оборот 90.1	1 200 000
Вторник	Учла НДС: кредит 90.1 минус дебет 90.3	1 000 000
Среда	Сочла аренду выручкой и добавила кредит 91.1	1 150 000

Каждый ответ можно обосновать, и ни в одном нет ошибки SQL. Но после трёх разных чисел на один вопрос финансовый директор вряд ли поверит и четвёртому. Хуже, если в прошлом году модель считала выручку без НДС, а в этом — с НДС: она найдёт рост на 20%, которого не было, и предложит ему объяснение.

С себестоимостью и прибылью вариантов ещё больше. Включать ли расходы на продажу со счёта 44 "Расходы на продажу"? Считать прибыль от продаж или до налогообложения, с прочими доходами и расходами со счёта 91 "Прочие доходы и расходы"?

Мы пришли к такому решению: показатель определяют люди, один раз, а модель берёт его готовым. Хранить определения удобнее всего там, где им и место, — в описании счетов плана счетов или в отдельном справочнике показателей, в едином формате: "Показатель: Выручка; оборот: Кт 90.1 минус Дт 90.3; без внутренних оборотов". Сервер читает описания, строит справочник и заодно проверяет полноту: счёт с оборотами, не привязанный ни к одному показателю, попадает в отчёт о расхождениях.

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

Бухгалтерия на естественном языке: каким должен быть MCP-сервер. Часть 2

Andrej Kirejeŭ — Sat, 31 Oct 2026 14:45:17 +0000

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

Условная схема данных

Возьмём условную схему хранения проводок. Это лишь один из вариантов, другие встретятся по ходу дела.

CREATE TABLE account (          /* план счетов */
  id         INTEGER PRIMARY KEY,
  parent_id  INTEGER,           /* счёт для субсчёта */
  code       VARCHAR(20),       /* 60, 60.1, 90.2 ... */
  name       VARCHAR(180),
  kind       CHAR(2)            /* А, П, АП */
);

CREATE TABLE entry (            /* бухгалтерская проводка */
  id         INTEGER PRIMARY KEY,
  doc_id     INTEGER,           /* первичный документ */
  entry_date DATE,
  rule_id    INTEGER            /* правило проведения */
);

CREATE TABLE entry_line (       /* одна сторона проводки */
  id         INTEGER PRIMARY KEY,
  entry_id   INTEGER REFERENCES entry(id),
  account_id INTEGER REFERENCES account(id),
  side       CHAR(1),           /* D - дебет, C - кредит */
  amount     NUMERIC(15,2),
  analytic1  INTEGER,           /* объекты аналитического учёта */
  analytic2  INTEGER,
  analytic3  INTEGER
);

Теперь хрестоматийная сложная проводка: от поставщика поступили материалы на 120, в том числе НДС 20. На схеме счетов, как её рисуют в учебниках, она выглядит так:

        Счёт 60 "Расчёты с поставщиками
             и подрядчиками"                          Счёт 10 "Материалы"
   Дт                                Кт         Дт                                Кт
   ─────────────────┬─────────────────          ─────────────────┬─────────────────
                    │  (1) 120 ──┬─────────►     (1) 100         │
                    │            │                               │
                                 │
                                 │                  Счёт 19 "НДС по приобретённым
                                 │                           ценностям"
                                 │              Дт                                Кт
                                 │              ─────────────────┬─────────────────
                                 └─────────►     (1)  20         │
                                                                 │

Рис. 2 Сложная проводка на схеме счетов: кредит счёта 60 корреспондирует с дебетом счетов 10 и 19.

В нашей схеме данных эта проводка лежит не одной строкой "дебет — кредит — сумма", а тремя: по строке на каждую её часть. Так удобно хранить сложные проводки с несколькими дебетуемыми или кредитуемыми счетами.

flowchart LR
    D[Первичный документ] --> E[entry<br/>проводка]
    E --> L1[entry_line<br/>D · счёт 10 · 100]
    E --> L2[entry_line<br/>D · счёт 19 · 20]
    E --> L3[entry_line<br/>C · счёт 60 · 120]

Рис. 3 Та же проводка в базе данных: заголовок и три строки сторон.

Бывает и по-другому. Проводка хранится парой "счёт дебета — счёт кредита — сумма", хозяйственная операция состоит из заголовка и спецификации таких пар, а сложная проводка раскладывается на простые: Дт 10 Кт 60 — 100 и Дт 19 Кт 60 — 20. Для наших выводов разница невелика: ошибки возможны при обоих способах хранения, только разные.

Где ошибается модель

Сложная проводка и двойной счёт

Попросим модель построить обороты по кредиту счёта 60 в корреспонденции с другими счетами. Ответ для нашего поступления материалов (Рис. 2) очевиден: Дт 10 — 100, Дт 19 — 20, итого 120. Модель напишет примерно такой запрос:

SELECT d_acc.code AS debit, c_acc.code AS credit,
       SUM(c.amount) AS amount
FROM entry_line c
  JOIN entry_line d ON d.entry_id = c.entry_id AND d.side = 'D'
  JOIN account c_acc ON c_acc.id = c.account_id
  JOIN account d_acc ON d_acc.id = d.account_id
WHERE c.side = 'C' AND c_acc.code = '60'
GROUP BY 1, 2

И получит:

Дебет	Кредит	Сумма
10	60	120
19	60	120

240 вместо 120. Самосоединение размножило единственную кредитовую строку по числу дебетовых. Брать сумму пары нужно со стороны, где строк несколько, но это знание о том, как устроена конкретная система, а вовсе не о SQL. При этом такой же запрос по дебету счёта 10 даёт верный результат, а на тестовых данных, где у проводок по одной дебетовой строке, ошибка может долго оставаться незамеченной.

Там, где проводки хранятся парами, этой ловушки нет. Зато есть зеркальная: сумма хозяйственной операции из заголовка повторяется в каждой строке спецификации, стоит только соединить заголовок со спецификацией. Запрос "сумма операций по поставщику" даст всё ту же удвоенную цифру.

Развёрнутое сальдо

Напомним: активно-пассивные счета могут одновременно иметь дебетовое и кредитовое сальдо и показываются и в активе, и в пассиве баланса.

Вопрос: "Какое сальдо по счёту 62 на конец года?" Счёт 62 "Расчёты с покупателями и заказчиками" как раз активно-пассивный. Покупатель А должен нам 100, покупатель Б перечислил аванс 30. Модель, скорее всего, вычтет кредитовые обороты из дебетовых и сообщит: дебетовое сальдо 70.

Арифметически это верно, но сальдо по счетам расчётов показывают развёрнуто: дебетовое 100 (дебиторская задолженность, актив) и кредитовое 30 (полученные авансы, пассив). Свёрнутые 70 занижают и то, и другое, и баланс с такой цифрой аудитор не примет. Чтобы получить правильный ответ, остаток считают по каждому покупателю и только потом отдельно складывают положительные и отрицательные.

Внутренние обороты и закрытие счетов

"Какая выручка за год?" Модель знает, что выручку отражают по кредиту счёта 90, и складывает кредитовый оборот счёта 90 со всеми субсчетами. Пусть выручка за год — 1000 (в корреспонденции со счётом 62), себестоимость — 700 (списана со счёта 41 "Товары"). В конце года субсчета 90.1 "Выручка" и 90.2 "Себестоимость продаж" закрываются на субсчёт 90.9 "Прибыль/убыток от продаж":

Дебет	Кредит	Сумма	Смысл
62	90.1	1000	выручка
90.2	41	700	себестоимость
90.1	90.9	1000	закрытие 90.1
90.9	90.2	700	закрытие 90.2

Кредитовый оборот счёта 90 со всеми субсчетами: 1000 + 1000 + 700 = 2700. Выручка, по мнению модели, — 2700. А сальдо счёта 90 на конец года равно нулю, хотя продажи за год были.

Записи между субсчетами одного счёта — это внутренние обороты. Именно поэтому учётные системы держат в отчётах флажок "включать внутренние обороты". Добавьте сюда служебные записи — перенос остатков при закрытии периода, ввод начальных остатков, — и станет понятно, почему без явных правил модель в таких вопросах ошибается регулярно.

Объекты аналитического учёта

Аналитику ведут по объектам: на счёте 60 — поставщики и договоры, на счёте 10 — материалы и склады, на счёте 70 — работники. Хранят эти объекты по-разному, и у каждого способа свои ловушки.

Первый способ — универсальные колонки analytic1, analytic2, analytic3, смысл которых зависит от счёта. На счёте 60 в analytic1 лежит контрагент, на счёте 10 — номенклатура. Модели приходится угадывать, в какой из трёх колонок искать поставщика. Если она ошибётся, запрос "сколько мы должны Ромашке" вернёт пустую выборку. Ещё хуже, если в колонке окажется идентификатор, случайно совпавший с идентификатором Ромашки в совсем другом справочнике.

Второй способ — отдельная колонка на каждый вид аналитики: "контрагент", "склад", "подразделение", а у счёта признаки, какие из них на нём ведутся. Угадывать проще. Но ничто не мешает модели взять колонку, которая на этом счёте не ведётся и заполнена как попало или пуста.

Третий — многоуровневые аналитические счета: под субсчётом поставщик, под поставщиком договор. Запрос по аналитическому счёту поставщика без учёта вложенных уровней потеряет суммы, учтённые на договорах.

Пустая выборка здесь опаснее синтаксической ошибки. В наших проверках модель обычно принимала её за ответ ("задолженности нет"), а не за повод перепроверить запрос.

Субсчета и иерархия плана счетов

Обороты по счёту 60 — это обороты по самому счёту и всем его субсчетам. Модель напишет WHERE code = '60' и ничего не найдёт: проводки делаются на субсчета. Или напишет WHERE code LIKE '60%' и прихватит счёт 600, если в рабочем плане счетов организации он вдруг есть. Правильно идти по иерархии плана счетов, а как именно она хранится — ссылкой на родителя, вложенными множествами или составным путём, — модели опять же должен сказать сервер.

Журнал-ордер и прочие формы учётных регистров

Пользователь просит журнал-ордер по счёту 51 "Расчётные счета". Н. П. Кондраков в учебнике "Бухгалтерский учёт" (2007, гл. 4, § 3 "Формы бухгалтерского учета") описывает журнально-ордерную форму так: "В журналы-ордера производятся только кредитовые записи того синтетического счета, операции которого учитываются в данном журнале". Дебетуемые счета идут в графах журнала-ордера как корреспондирующие, а дебетовый оборот самого счёта собирается из других журналов-ордеров. Для контроля к журналу-ордеру по счёту 51 обычно ведут ещё и ведомость по дебету. Модель же, как правило, выдаёт все обороты счёта 51 одним списком. У каждой учётной формы — оборотно-сальдовой ведомости, карточки счёта, анализа счёта, главной книги — есть устоявшееся содержание, как бы её ни называли в конкретной системе. Пользователь ждёт именно его.

Мелочи, которые складываются

Список можно продолжать долго. Модель пишет конструкции привычного ей диалекта SQL, которых нет в вашей СУБД: даже ограничение числа строк в разных СУБД записывается по-разному. Придумывает колонки, которых нет, но которые "должны быть", вроде debit_amount или turnover. Учитывает документы, по которым проводки не формировались. Складывает рубли с долларами. Не подозревает, что в базе несколько организаций или несколько планов счетов.

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

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

Бухгалтерия на естественном языке: каким должен быть MCP-сервер

Andrej Kirejeŭ — Sat, 31 Oct 2026 14:44:36 +0000

Если бы Beatles пели не о любви, а о бухгалтерском учёте, то получилось бы что-то вроде: All you need is report. Всем от бухгалтерии интересно что-то узнать: налоговой — размер выручки, работнику — почему так мало начислили за прошлый месяц, а руководителю — начал ли хоть кто-то из хронических дебиторов рассчитываться с нами.

Мы занимаемся автоматизацией бухучёта с середины девяностых. Технологии менялись, но добыча нужных цифр всегда была процессом длительным, часто грязным (кто менял ленточки на Epson-ах или досыпал тонер в картриджи HP — знает) и дорогим: надо позвать программиста, объяснить ему, какой отчёт нужен, подождать пару недель и получить на выходе не то, что ожидалось.

ChatGPT изменил современный мир и то, как мы общаемся с компьютером. Пользователь больше не хочет продираться через минное поле выпадающих списков, чекбоксов и радиокнопок. Он хочет просто спросить обычным языком и получить ответ с текстом и цифрами, а если понадобится, то и с таблицами и графиками. Вопросы у пользователя могут быть как простыми: "Какое сальдо по расчётам с поставщиками на 1 октября?" или "покажи карточку счёта 50 за сентябрь", так и требующими рассуждений и анализа: "Почему упала прибыль в прошлом квартале, что происходит на рынке и что нам делать?" На простые вопросы модель обязана отвечать точно. На сложные — хотя бы обоснованно.

Мостиком между моделью и учётной базой служит Model Context Protocol (MCP) — открытый протокол, через который языковая модель подключается к внешним данным и инструментам. Тем, кто застал девяностые, проще всего представить его как ODBC для нейросетей: один разъём, к которому подключается что угодно. Дело за малым — написать сервер, который будет висеть на другом конце провода. О том, каким он должен быть, и пойдёт речь.

К конкретной учётной системе цикл не привязан. Схема данных условная, план счетов типовой — тот самый, по которому сдают экзамен в вузе (счёт 50 из примера выше — это, конечно, "Касса"). С терминологией сложнее: каждая система норовит назвать одно и то же по-своему. Документ где-то проводят, где-то отрабатывают в учёте, где-то формируют по нему проводки по типовой хозяйственной операции. Объекты аналитического учёта зовутся то субконто, то аналитиками, то аналитическими счетами, то классификаторами. Карточку счёта иногда величают картой, анализ счёта — шахматкой. Мы будем держаться языка учебника, а синонимы приводить там, где без них можно запутаться. Механизмы своей системы читатель, надеемся, узнает и без них.

План цикла

Часть 1 (эта статья). Два пути: частный и универсальный сервер. Соблазн прямого доступа.
Часть 2. Условная схема данных. Где ошибается модель.
Часть 3. Архитектура сервера. Инструменты. Знание предметной области.
Часть 4. Сложные вопросы. Чему нас научила разработка. Заключение.

Два пути: частный и универсальный сервер

Прежде чем браться за сервер, придётся выбрать дорогу. Их две.

Частный сервер — набор инструментов под конкретные вопросы: дай дебиторов, дай список сотрудников, дай начисления по сотруднику, дай остатки на складе. Он похож на кофейный автомат: нажал кнопку "капучино" — получил капучино.

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

Частный сервер подкупает простотой. Написать его легко, протестировать ещё легче. Для чат-бота, через который сотрудник узнаёт остаток своего отпуска, ничего другого и не нужно. Трудности обычно появляются на втором-третьем уточняющем вопросе.

Представим разговор с финансовым директором. В частном сервере есть инструменты get_employees(), get_accruals(employee) и get_revenue(period).

Вопрос	Частный сервер	Универсальный сервер
Покажи начисления Иванову за сентябрь	`get_accruals("Иванов")` — ответ получен	Карточка счёта 70 "Расчёты с персоналом по оплате труда" с отбором по работнику
Сколько премий начислено отделу продаж в III квартале?	Инструмента для отдела и вида начисления нет. Модель вызывает `get_accruals` для каждого из 40 сотрудников и складывает 40 ответов в уме, путаясь в видах начислений	Обороты по кредиту счёта 70 с группировкой по подразделению; вид начисления — из документов начисления заработной платы. Два вызова, итоги считает сервер
А по сравнению со II кварталом?	Ещё 40 вызовов	Тот же вызов со сравнением периодов
Как это соотносится с выручкой отдела?	`get_revenue` об отделах не знает. Ответа нет	Выручка по кредиту счёта 90 "Продажи" в разрезе подразделений — показатель из справочника показателей
Почему премии выросли, а выручка нет?	Ответа нет	Анализ счёта, документы начисления премий и их основания

На первый вопрос оба сервера отвечают одинаково. На втором у частного сервера нет подходящего инструмента, и у разработчика остаётся два варианта. Можно дописать get_accruals_by_department_and_type, следом get_revenue_by_department, следом ещё десяток. Чем больше похожих инструментов, тем чаще модель выбирает не тот. А можно добавлять параметры: отбор по подразделению, группировку, период сравнения. Только инструмент с отбором по любому объекту аналитики, группировкой и сравнением периодов — это уже оборотно-сальдовая ведомость. Частный сервер, если его развивать, постепенно превращается в универсальный, только без единой схемы параметров.

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

Дальше речь пойдёт только об универсальном сервере. Но универсальный не значит "дай модели SQL, пусть разбирается". Почему — в следующем разделе.

Соблазн прямого доступа

Самый короткий путь к универсальному серверу — дать модели описание таблиц и инструмент для выполнения SQL-запросов. SQL современные модели пишут неплохо, схема базы известна. Что тут может пойти не так?

flowchart LR
    U[Бухгалтер] -->|вопрос| L[Языковая модель]
    L -->|SQL| S[MCP-сервер<br/>run_sql]
    S --> D[(Учётная база)]
    D --> S --> L -->|ответ| U

Рис. 1 Наивная архитектура: модель сама пишет запросы к учётной базе.

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

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

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

Anthropic опускается, опускается Anthropic...

Andrej Kirejeŭ — Sun, 16 Aug 2026 21:59:06 +0000

Opus 5 стал многословным и тупым, если так можно выражаться о модели. Постоянно все забывает и путает. Сваливается в жаргон. Может спокойно предложить выполнить вот ту команду только с другим ключиком. Только саму команду не покажет, а она была где нибудь три часа назад по чату. Живет какимми то своими убеждениями и верованиями. Вместо того чтобы проверить простейшую вещь способен отправить пользователя на 1-2 часовой круг.

Как-то фирма Ashton-Tate правила миром через свою СУБД dBase III, но потом выпустила глючный dBase IV и была мигом сожрана конкурентами. О таком подарке FoxPro с Clipper-ом даже и мечтать не могли.

Если Anthropic не подсуетится, то китайцы с одной стороны, а одесское пароходство (зачеркнуто) openai -- с другой, его просто аннигилируют. Тем более что словоблудный Opus 5 только треть их проблем, вкупе с отсутствием дешевой модели с ризонингом и маленьким входящим и исходящим буфером haiku.

PS: стоило только написать и минуту спустя:

В приличных домах за такое дают внеочередной резет.

What is Cursor AI’s business model? Asking for a friend.

Andrej Kirejeŭ — Mon, 27 Apr 2026 21:12:37 +0000

Other big players may have collateral incentives. OpenAI & Claude has much broader goals for its AI. Microsoft has a whole range of technologies, plus Azure, to lock developers into its ecosystem. But what about Cursor?

The more it progresses, the fewer human programmers will be left, which would eventually eliminate subscription revenue. Are they on an audacious path? Or do their business plans envision a bright future in which the world produces and uses 100x or even 1000x more software?

Отказоустойчивые видеозвонки на 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.