Протокол durable (экспериментально)

Экспериментальная. Сетевой протокол может измениться или функция может быть удалена в последующем минорном релизе. В Версии и информативное приветствие описано, как изменения доходят до вас.

Сетевой протокол durable — это способ взаимодействия Collie с durable-агентом. На этой странице он описан для разработчика, который создаёт durable-агента без SDK или хочет знать, что именно делает SDK. Точные правила приведены в WIRE.md, и если эта страница расходится с тем файлом, верным считается WIRE.md. Durable SDK берёт на себя всю работу с протоколом.

Что передаётся по сети

Collie подключается, а durable agent слушает; каждый обмен представляет собой один HTTP-запрос с телом в формате JSON.

Durable agent слушает приватный Unix-сокет или доступен через TLS по URL (Транспорты). Collie опрашивает его: здесь нет push-уведомлений, WebSocket и потоков. Каждый путь начинается с /session/v1 — это фиксированное имя, а не версия. Каждый вызов, кроме первого hello, передаёт версию в заголовке X-Collie-Session. Тело запроса представляет собой один JSON-объект размером не более 64 КиБ, а пустое тело POST читается как {}.

Каждая ошибка представляет собой тело JSON с code, например 409 stale или 404 no-such-pane. Любой другой путь возвращает 404 not-found. Ответ, превышающий лимит, не читается, а результат POST-запроса с оборванным ответом считается неизвестным (Идентификаторы запросов).

Приветствие и эпоха

hello указывает, чем является durable agent, а эпоха указывает, с каким именно его запуском взаимодействует Collie.

Collie сначала вызывает hello без заголовка версии, выбирает наибольшую поддерживаемую обеими сторонами версию и передаёт её во всех последующих вызовах. Пока ready равно false, каждый маршрут, кроме hello, возвращает 503 starting, а на телефоне отображается, что durable agent запускается. Durable agent выставляет ready только после того, как все диалоги снова отображены и каждый открытый ask создан повторно, поэтому при перезапуске никогда не отображается незавершённая разметка.

ETag снимка равен "<epoch>-<rev>". Значение rev увеличивается при каждом изменении, видимом для читателя, поэтому ответ 304 почти ничего не стоит для durable agent. Новая эпоха сообщает Collie, что durable agent перезапустился. Collie продолжает показывать имеющиеся панели, пока не считает новый снимок. Затем он считывает каждую панель со старым курсором и получает всё текущее представление панели в одном ответе.

Одно неудачное чтение после успешного сохраняет последний снимок на время этого опроса. Два сбоя подряд показывают durable agent как недоступный. Путь к сокету, не прошедший проверку прав доступа, становится недоступным сразу.

Запросы и ответы

Ask представляет собой карточку с вопросом; он открыт от события ask в durable agent до события ask-closed.

Нажатие, совершённое после принятия решения, возвращает 409 decided с первым результатом, и ничего не запускается. Затем на карточке отображается, кто принял решение первым: «Решено в durable agent.», «Время истекло до получения ответа.» или после повторного нажатия «Ответ уже дан. Эта карточка исчезнет при следующем обновлении.». Запрос, о котором durable agent больше не знает, возвращает 200 too-late. Тогда на карточке отображается: «Не принят. Вопрос может появиться снова через минуту.», поскольку после перезапуска durable agent может создать его повторно с тем же идентификатором.

Запрос бывает одного из четырёх типов: permission, choice, text или form. У каждого своя структура ответа, описанная рядом с Вопросы в SDK.

Идентификаторы запросов

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

Телефон генерирует по одному идентификатору запроса на каждое намерение, а Collie записывает собственную квитанцию перед дальнейшей передачей идентификатора. Durable agent хранит как минимум 500 последних идентификаторов своей эпохи. Повтор завершённого идентификатора снова получает первый ответ с replayed: true и ничего не запускает. Тот же идентификатор с другим телом запроса возвращает 409 request-id-reused.

Collie никогда не повторяет POST самостоятельно. Запрос POST, завершившийся по тайм-ауту, потерявший соединение или получивший ответ 5xx, имеет неизвестный результат. В поле ответа на карточке появляется сообщение "Not sure the answer arrived. Try again sends it once more.", а кнопка Try again отправляет тот же идентификатор запроса, поэтому память durable agent отвечает на повтор.

Повторная попытка, которая застаёт запрос закрытым или ход переданным, не может определить, прошёл ли первый запрос. В этом случае Collie возвращает телефону ответ "maybe applied", карточка сообщает "May already be applied. Check the chat.", и действие больше никогда не отправляется в третий раз.

Транспорты

Durable agent использует один из двух транспортов: приватный сокет на машине Collie или TLS с токеном.

Байты в обоих случаях одинаковы: маршруты, тела запросов, заголовок версии, ETag и коды ошибок. Различается лишь то, кому разрешён доступ к durable agent.

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

Ограничения

Collie обрезает или отклоняет всё, что выходит за эти пределы, поэтому durable agent в их границах ничего не теряет.

Строка, превышающая лимит, обрезается, а её управляющие и невидимые символы удаляются. Список, превышающий лимит, сохраняет первые записи. Страница истории, превышающая лимит, не читается вовсе.

Версии и информативное приветствие

Сейчас существует одна версия сетевого протокола, 1, и Collie использует 1..1.

Когда выйдет версия 2, Collie продолжит поддерживать версию 1 в течение одного минорного релиза, а следующий за ним минорный релиз прекратит её поддержку. Читатель игнорирует неизвестные ему поля, типы событий, разновидности элементов и коды. Поле, добавленное в рамках версии 1, такое как expiresAt или decidedBy, является необязательным. Новое обязательное поле, новое значение для старого поля или удалённое поле требуют новой версии.

Запрос неизвестного телефону типа отображается как запрос, на который нельзя ответить с телефона, без кнопок.

Если два диапазона не пересекаются, Collie больше ничего не читает от durable agent. Один раз за эпоху durable agent он отправляет ещё один hello, на этот раз со своей версией, чтобы durable agent мог зафиксировать несовпадение в своём журнале. Durable agent отвечает 409 incompatible с заголовком refusal, где указаны оба диапазона. Это информационное приветствие.

Collie записывает одну строку в журнал для каждого отклонённого диапазона, а collie doctor показывает оба диапазона. Домашний экран durable agent на телефоне выводит то же сообщение, например: «The durable agent speaks wire v2, this Collie speaks v1. Update Collie, or the agent's SDK.» Обновите устаревшую сторону.

Где найти точные правила

WIRE.md — это контракт со всеми структурами, кодами и правилами.

Решения, лежащие в его основе, зафиксированы в репозитории: