Устранение неполадок с durable agent

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

Если durable agent не появляется, отображает Unreachable или не реагирует на нажатие: три команды помогут найти причину, а таблица причин и список неполадок содержат решения. Документ Устранение неполадок посвящён Collie в целом.

Первичная проверка

Выполните эти три команды в указанном порядке:

collie durable list
collie doctor
collie logs

Телефон выводит меньше информации. В строке durable agent отображается Starting или Unreachable без указания причин. Отказ из-за версии сетевого протокола имеет отдельный статус Version mismatch и блок с предупреждением на главной странице durable agent. Отклонённый токен имеет свои формулировки в панели подключения. Документы collie doctor и collie logs содержат все остальные причины.

Таблица причин

Когда Collie не удаётся связаться с durable-агентом, остальная часть Collie всё равно запускается, а durable-агент отображается как недоступный с указанием причины.

В причине указывается переменная окружения, даже если durable-агент задан записью в sources.json. Считайте COLLIE_DURABLE_SOCKET полем socket этой записи, COLLIE_DURABLE_URL — её полем url, а COLLIE_DURABLE_TOKEN — её полем token. Исправление для записи вносится в sources.json. Исправление для формы только с durable вносится в .env, затем в collie restart.

Параметр нарушает правило

Collie сообщает об этом, не пытаясь подключиться к durable-агенту. Правила, заданные в записях sources.json, также отклоняются при запуске моста (Опечатка в sources.json).

Durable-агент не отвечает или отвечает с ошибкой

Строки doctor для durable agents

collie doctor отправляет каждому durable agent те же запросы, что и мост, и в том же порядке. Отправляется только hello.

Каждая запись в sources.json получает один блок из шести строк, обозначенный как durable-socket:desk для durable agent с именем desk. Строка sources перед блоками проверяет файл, а после них идёт одна строка durable-lead. Collie, работающий только в режиме durable, выводит те же шесть строк без суффикса, а его строка mux содержит durable, see the durable-* lines.

Строка с ошибкой останавливает следующие за ней строки. Они выводятся как пропущенные с причиной fix the row above first, так как Collie никогда не обращается к durable agent через сокет, не прошедший проверку приватности, или с токеном, нарушающим его правило. Пропущенная строка не является сбоем.

Случаи

Для каждого случая указано то, что вы видите, причина и решение.

Опечатка в sources.json

Collie недоступен полностью, а не только один durable agent: телефон не может подключиться. collie logs заканчивается на [bridge] FATAL:, путь к файлу, запись и поле.

Мост считывает sources.json при запуске и останавливается при обнаружении неизвестного поля, kind, отличного от durable, имени, нарушающего правило, повторяющегося имени, socket и url вместе, отсутствия обоих, url без token или token с socket. Исправьте файл, затем выполните collie restart. collie doctor показывает то же сообщение в строке sources.

Если мост не может определить имя записи (это не объект, есть неизвестное поле или имя нарушает правило), он считает с 0 и выводит entry 1 для второй записи. collie durable attach считает с 1 и выводит entry 2 для той же записи. В обоих случаях указывается поле. Как только имя станет корректным, мост выводит имя: entry "desk".

attach и detach отказываются записывать файл, который не могут прочитать, поэтому опечатка не повредит остальным записям. Они завершают работу с кодом возврата 1.

Durable agent не появляется после attach

Вы не видите durable agent на телефоне, а collie durable list выводит not loaded (restart to apply).

attach и detach только записывают sources.json. Мост считывает его при запуске. Выполните collie restart или добавьте --restart к команде в следующий раз. Если not loaded сохраняется после перезапуска, проверьте collie logs: list формулирует HTTP 400 от моста так же, как 404.

Проверка конфиденциальности не пройдена

Вы видите socket-not-private: the socket's folder /tmp/hello has mode 0755, not 0700, и строка doctor durable-socket выделена красным.

Collie подключается к сокету только в том случае, если весь путь приватный. Обычные причины: каталог с правами 0755, сокет прямо в /tmp или другом общем каталоге, а также символическая ссылка в пути. Символическую ссылку легко не заметить: на многих хостах Linux /var/run указывает на /run, поэтому путь, начинающийся с /var/run/, завершается ошибкой /var/run is a symlink. Используйте реальный путь.

Выполните chmod 700 для каталога самого сокета или переместите сокет в $XDG_RUNTIME_DIR. Правила приведены в Безопасность durable agent. Durable agent, созданный с помощью SDK, отказывается запускаться в существующем каталоге, права которого отличны от 0700, и сообщает об этом сам.

Устаревший файл сокета

Вы видите connection refused на сокете, при этом файл существует.

Аварийно завершившийся durable agent оставляет файл сокета, и его никто не слушает. Запустите durable agent снова. SDK удаляет неактивный файл сокета перед началом прослушивания и останавливается с ошибкой another instance is already listening, если сокет активен. Удаляйте файл вручную только тогда, когда ваш durable agent не очищает его сам.

Имя совпадает с именем терминальной сессии

Мост останавливается при запуске с ошибкой the name is the terminal session's own; pick another, либо терминальная сессия отсутствует на телефоне.

Durable agent не может использовать имя терминала, из которого запущен Collie. В большинстве установок это имя — default, а в режиме durable-only у Collie default имя берётся от его durable agent. Мост останавливается при запуске и указывает имя записи. Сессия Herdr с именем durable agent — другой случай: durable agent сохраняет имя, телефон не показывает эту сессию, а в лог выводится однократное сообщение. Переименуйте одну из них.

Постоянное предупреждение durable-ready

Вы видите durable-ready как предупреждение при каждом запуске collie doctor.

Durable agent возвращает hello и сообщает ready: false. Телефон показывает статус Starting. Durable agent сообщает о готовности только после того, как восстановит свои диалоги и снова поднимет открытые вопросы. Проверьте собственный лог durable agent, чтобы узнать, чего он ожидает.

Durable agent останавливается при запуске на проверке потомков

Durable agent останавливается при запуске с ошибкой the descendant check needs Bun on Linux to read the peer of a socket; pass callerCheck: "off" to run without it.

Для проверки требуется Bun на Linux. На macOS запускайте durable agent через Node или передайте callerCheck: "off" в openCollie и предварительно прочитайте что защищает проверка. Ошибка исходит от durable agent. Collie к ней не причастен.

Вопрос появляется снова после перезапуска

Вы снова видите вопрос после перезапуска durable agent или карточку с сообщением о том, что ответ уже получен.

Ответ на вопрос, заданный до перезапуска, получает too-late, карточка сообщает об этом и исчезает. Durable agent, который вычисляет id вопроса из вызова своего инструмента, задаёт тот же вопрос снова, поэтому отправленный через перезапуск ответ доходит, и инструмент выполняется один раз. Durable agent, создающий новый id каждый раз, задаёт новый вопрос для того же вызова инструмента. Карточка показывает его, и Collie не отправляет повторный пуш, так как защита от частых пушей привязана к вызову инструмента. Защита также разрешает 3 пуша на диалог в минуту, 10 на хост в минуту и 30 на хост в час. Пуш, который стал бы 31-м за час, превращается в один сводный пуш для этого хоста, и хост больше ничего не отправляет в течение часа после него. Карточка показывается всегда.

403 caller-refused

На телефоне отображается, что ответ или сообщение отклонены, а причина durable agent: 403 caller-refused.

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

Повторите попытку, и ответ, который может быть применён

Вы видите «Not sure the answer arrived» с кнопкой Try again, а после нажатия — «May already be applied. Check the chat.»

Таймаут, обрыв соединения или ошибка 5xx после отправки ответа означают, что он мог дойти. Кнопка Try again отправляет тот же id запроса, поэтому durable agent возвращает replayed и никогда не разрешает вопрос дважды. Если вопрос уже закрыт, его могла закрыть первая попытка, поэтому телефон предлагает проверить чат. Отправка, остановка и нажатие кнопки сообщают то же самое своими словами.

Durable agent отклонил токен

В строке подключения отображается «The durable agent refused the token. Check COLLIE_DURABLE_TOKEN on this peer.», а причина — token-refused.

Durable agent вернул 401 или 403 в ответ на токен. Самая частая причина — ротация, когда одна из сторон обновилась раньше. В сообщении на телефоне указано COLLIE_DURABLE_TOKEN даже для записи sources.json: читайте это как token этой записи. Передайте новый токен в durable agent перед перезапуском Collie. Шаги ротации описаны в Токены. Ошибка 403 также может исходить от прокси доступа перед durable agent.

Переключение в Unreachable, требующее двух чтений

Вы видите, что durable agent остаётся в статусе Ready при одном неудачном чтении, а затем переключается в Unreachable.

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

По протоколу https к упавшему или отклоняющему токен durable agent обращение происходит не чаще одного раза в 10 с, так как каждая попытка тарифицируется. Через сокет минимальный интервал между двумя чтениями упавшего durable agent составляет 250 мс.

В составе crew

Durable agent на участнике crew отображается на телефоне ведущего узла, поэтому ведущему узлу нужно знать, что такое durable agent.

Ведущий узел версии ниже 1.21.0 выводит диалоги durable agent без карточки вопроса, а его вкладка Terminal опрашивает диалог, у которого нет терминала. На стороне участника это ничем не исправить. Участник сам сообщает об этом: collie doctor предупреждает в durable-lead, а в лог выводится одна строка, [durable] the lead is 1.20.1; it shows durable panes without the question card and its Terminal tab polls; update the lead, один раз для каждого обнаруженного релиза. Обновите ведущий узел.

Если участник старее ведущего узла, возникает противоположная ошибка. Телефон сообщает: «This machine runs an older Collie and cannot take answers here. Update it, or answer in the durable agent.» Обновите этого участника.