Потоки, жизненный цикл и совместимость

Наблюдение

Потоки передают ограниченный набор наблюдений и курсоры; клиент не становится владельцем состояния Core. ObserveProjectAsync сначала получает полный снимок, затем читает поток с привязкой к его курсору. Методы подписки нижнего уровня принимают курсор из соответствующего снимка или предыдущего события.

Обрабатывайте subscribed, resync_required, пропуски диагностики и явные ошибки. После пропуска получите новый снимок. Сохраните и сравните несохранённые черновики интерфейса вместо их автоматической замены обновлённой моделью.

WebSocket для других языков

Используйте обнаруженный адрес со схемой ws и путём /api/v1/streams. При установке соединения передайте согласованный сеанс в заголовке Authorization: Bearer <accessToken>. Не помещайте токен в параметры URL. После подключения отправьте текстовую подписку JSON в UTF-8:

{
  "type": "subscribe",
  "stream": "project",
  "cursor": "opaque-cursor-from-the-project-snapshot"
}

Передавайте фактический курсор Core. Не разбирайте, не увеличивайте и не придумывайте его. Поток project использует курсор снимка проекта; shell, runtime, status, diagnostics и logs имеют собственные снимки и разрешения. Курсор одного потока нельзя использовать для другого.

Обрабатывайте управляющие сообщения subscribed, resync_required, gap, error и события с типом потока и события, идентификаторами Host/проекта и курсором. Точные поля смотрите в схемах ProjectStreamSubscribeDto, ProjectStreamControlDto, ProjectStreamEventDto и HostStreamEventDto. Обычный клиент по умолчанию ограничивает сообщение 2 МиБ; также учитывайте ограничения Core.

Сохраняйте последний курсор только после обработки события. После пропуска отбросьте кэш наблюдения, получите новый согласованный снимок и подпишитесь с его курсором. Не применяйте события прежнего Host или проекта к новому состоянию.

Средства .NET и жизненный цикл

SubscribeProjectAsync, SubscribeShellAsync, SubscribeRuntimeAsync, SubscribeStatusAsync, SubscribeDiagnosticsAsync и SubscribeLogsAsync предоставляют управляющие сообщения и события. ApiStreamMessage.RequiresSnapshot сообщает о пропуске или необходимости обновить снимок. Завершение перечисления не продлевает разрешение и не заменяет черновики интерфейса.

Для согласованного наблюдения проекта, shell и runtime ApiConnection принимает вашу фабрику переподключения. Она читает согласованные снимки и проходит состояния Connecting, Syncing, Ready, Lost, Incompatible. Фабрика должна заново прочитать обнаружение и подключиться с подтверждёнными учётными данными и разрешениями host.status, project.read, runtime.read. Хранение и продление учётных данных обеспечивает приложение.

Перезапуск Core меняет идентификатор Host и делает старые сеансы и курсоры недействительными; переключение проекта меняет идентификатор проекта. Прекратите изменения по старому идентификатору и прочитайте актуальное состояние.

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