Local Proctoring

Распакованное расширение Google Chrome для локальной записи экрана, камеры и микрофона, с отправкой в основной прокторинг или ручной выгрузкой. Текущая версия — в VERSION. Подготовка ведётся в pre-release.

Связанные проекты и область поддержки

• proctoring — пользовательский вход, приём видео, очередь, /teach/:id и результаты.
• proctoring-ml — анализ после сохранения в backend.
• В этом репозитории актуален только client/. Папки server/ и playground/ не участвуют в рабочем запуске; отдельный сервер расширения не разворачивается.

VERSION задаёт версию этого проекта; CHANGELOG.md — изменения; политика проекта — правила синхронизации. В client/manifest.json версия генерируется из VERSION; отдельный version_name не нужен.

Для смены версии измените собственный VERSION, затем из корня этого проекта выполните: node scripts/sync-release-version.js и node scripts/check-release-version.js. Обновляется только client/manifest.json; соседние репозитории не требуются.

Требования и распространение

Обновление установок и серверной связки: production-инструкция.

Официально поддерживается Google Chrome 134+, Linux / Windows. Сквозной тест выполнен на Linux Chrome 154. Другие Chromium и macOS требуют проверки. Расширение распространяется архивом, не через Chrome Web Store. Получайте актуальный архив у сопровождающего проекта; старые внешние ссылки на релизы не определяют актуальную локальную версию.

1. Распакуйте client, откройте chrome://extensions и включите режим разработчика.
2. Выберите «Загрузить распакованное расширение» и каталог client.
3. Проверьте ID nlhjjbgkbfkopkigkbkojpkbffbkeohg; закрепите расширение в панели Chrome.
4. Войдите на сайт прокторинга в том же профиле браузера.

Общий публичный manifest key закрепляет ID независимо от пути распаковки. Не меняйте key при обновлении, не удаляйте расширение и не очищайте его данные, пока остались невыгруженные записи. Перед первым переходом со старого ID выгрузите все файлы: OPFS и настройки привязаны к ID и автоматически не мигрируют. Ключ публичный; он не секрет и не доказательство подлинности кода расширения.

Настройка API

В client/settings.json:

{
  "session_settings": {
    "server_connection": true,
    "local_video_saving": true,
    "server_url": "http://127.0.0.1:8000/api/remoteSessions"
  }
}

Это фрагмент, а не замена всего файла: сохраняйте video_settings и существующие параметры. Для production укажите HTTPS-домен основного прокторинга. В client/manifest.json host_permissions должен разрешать именно origin сервера с /*.

В proctoring/backend/.env добавьте, сохраняя прочие разрешённые origin:

FRONTEND_ORIGINS=chrome-extension://nlhjjbgkbfkopkigkbkojpkbffbkeohg

Пересоздайте backend после изменения env. Не отключайте checkOrigin и не разрешайте все chrome-extension origin. ML_SERVICE_KEY / JWT / пароль не нужны в расширении: авторизация выполняется cookie сайта через credentials: include. Для локального запуска используйте только 127.0.0.1.

Проверка обновлений

При каждом открытии popup расширение проверяет версию на сервере. Панель над формой показывает новую версию, предупреждение о запрете старта и ссылку на HTTPS-архив, если её задал администратор. Ошибка проверки не меняет запись / отправку. В автономном режиме запрос не выполняется. Перед стартом записи политика проверяется повторно; обновлять расширение нужно после выгрузки видео.

Запись и отправка

1. Откройте popup, заполните группу / ФИО / данные сессии.
2. Нажмите «Разрешения», предоставьте доступ к экрану, камере и микрофону.
3. Не закрывайте и не обновляйте служебную вкладку записи.
4. Запустите запись; после «Остановить» дождитесь финализации последнего чанка и OPFS.
5. При локальном сохранении дождитесь завершения скачивания, не только появления downloadId.
6. Запустите отправку; её выполняет служебная вкладка, не краткоживущий popup.
7. На /teach/:id дождитесь завершения обоих ML-потоков и проверьте видео / события.

Не удаляйте локальные оригиналы по одному HTTP 200: код проверяет явные success / videosSaved. Если видео уже сохранены, но очередь ML не запустилась, повторно загружать их нельзя; нужен повтор обработки на стороне прокторинга. После потери ответа сначала проверяется status/:id.

Remote API допускает до 8 GiB на файл / 16 GiB на запрос, но стандартный лимит скачивания одного видео в ML — 4 GiB. Для больших записей оператор должен заранее согласовать ML_VIDEO_MAX_BYTES и дисковое место; принятый upload ещё не означает завершённый анализ.

Для offline-записи заранее задайте server_connection=false и local_video_saving=true. После выгрузки используйте форму самостоятельной загрузки на странице сессии сайта. Не переключайте режим посреди записи. Ручная форма принимает одну пару файлов; несколько самостоятельных WebM нельзя просто объединить Blob или переименованием. Прямая отправка расширением поддерживает серверное объединение фрагментов.

Подробный контракт и краткая пользовательская инструкция: client/API-COMPATIBILITY.md, client/README.md. Настройка сервера описана здесь и в API-COMPATIBILITY.

Локальные записи и восстановление

Ссылка «Мои записи» в popup и служебной вкладке открывает содержимое OPFS, включая файлы без индекса. Можно просмотреть WebM и скачать его без удаления оригинала; после скачивания доступно «Показать в папке». OPFS не является обычной папкой файловой системы, поэтому прямое открытие его каталога не используется.

После попытки отправки продолжение записи блокируется до завершения отправки. Повтор сначала проверяет серверный статус. Если старое подтверждение нельзя связать с точным составом файлов, они сохраняются для ручного скачивания. Ошибки чтения/удаления сохраняют индекс восстановления. Сетевые запросы ограничены 30 секундами (статус) и 15 минутами (upload); после timeout можно повторить отправку. Проверки сбоев: tests/recording-recovery/VALIDATION.md.

Проверки

Из корня репозитория, Node 20.20+:

node --experimental-default-type=module --test client/tests/*.test.js

Проверка скриптов версии: node --test scripts/tests/*.test.js. Отдельная сборка client не нужна: Chrome загружает каталог напрямую. Результаты финального прогона — в docs/validation.md.

Ограничения

Уничтожение вкладки / Chrome может потерять последний незафиксированный чанк. Многочасовые записи требуют проверки квоты, свободного места и производительности OPFS. Логи разных extension-контекстов могут терять события при конкурентном read-modify-write. Локальное видео не доказывает непрерывность контроля: владелец браузера может изменить код / файл. Не объявляйте проверенными production HTTPS, аварийные сценарии или распознавание реальных лиц на основании тестовой камеры. Правила разработки: AGENTS.md.