Solução de problemas de um durable agent

Experimental. O protocolo de rede, o SDK e esta página podem mudar, ou o recurso pode ser removido, em uma versão secundária posterior. Durable agents explica o que decide sua permanência.

Um durable agent que não aparece, exibe Unreachable ou não responde a um toque: três comandos encontram a causa, e uma tabela de motivos com uma lista de casos fornece a solução. Solução de problemas cobre o Collie como um todo.

Primeiras verificações

Execute estes três, nesta ordem:

collie durable list
collie doctor
collie logs

O telefone mostra menos informações. A linha de um durable agent exibe Starting ou Unreachable e não fornece nenhum motivo. Uma recusa de versão de protocolo tem uma mensagem própria, Version mismatch, e uma caixa de aviso na página inicial do durable agent. Um token recusado tem sua própria mensagem na barra de conexão. collie doctor e collie logs indicam todos os outros motivos.

A tabela de motivos

Quando o Collie não consegue alcançar um agente durável, o restante do Collie inicia mesmo assim, e o agente durável aparece como inacessível com um motivo.

Um motivo indica o nome da variável de ambiente mesmo quando o agente durável é uma entrada de sources.json. Leia COLLIE_DURABLE_SOCKET como o socket da entrada, COLLIE_DURABLE_URL como seu url e COLLIE_DURABLE_TOKEN como seu token. A correção para uma entrada fica em sources.json. A correção para o formato exclusivo para duráveis fica em .env, depois collie restart.

A configuração viola uma regra

O Collie relata estes erros sem discar para o agente durável. Regras presentes em entradas de sources.json também são recusadas no início da bridge (Um erro de digitação em sources.json).

O agente durável não responde, ou responde incorretamente

Linhas do doctor para durable agents

collie doctor faz a cada agente durável as mesmas perguntas que o bridge faz, na ordem em que o bridge as faz. Ele não envia nada além de hello.

Cada entrada de sources.json recebe um bloco de seis linhas, escrito durable-socket:desk para um agente durável chamado desk. Uma linha sources antes dos blocos verifica o arquivo, e uma linha durable-lead os segue. Um Collie exclusivo para duráveis imprime as mesmas seis linhas sem sufixo, e sua linha mux exibe durable, see the durable-* lines.

Uma linha com falha interrompe as linhas seguintes. Elas são exibidas como ignoradas com o motivo fix the row above first, porque o Collie nunca faz requisições a um durable agent por um socket que falhe na verificação de privacidade ou com um token que viole sua regra. Uma linha ignorada não é uma falha.

Casos

Cada caso informa o que você vê, o motivo e a correção.

Um erro de digitação em sources.json

Você vê o Collie fora do ar, e não apenas um durable agent: o celular não consegue se conectar. collie logs termina com [bridge] FATAL:, o caminho do arquivo, a entrada e o campo.

A bridge lê sources.json na inicialização e para em um campo desconhecido, um kind que não seja durable, um nome que viole a regra, um nome duplicado, socket e url juntos, nenhum dos dois, um url sem token ou um token com um socket. Corrija o arquivo e execute collie restart. O collie doctor mostra a mesma mensagem na linha sources.

Quando a bridge não consegue nomear a entrada (ela não é um objeto, tem um campo desconhecido ou o nome viola a regra), ela conta a partir de 0 e grava entry 1 para a segunda entrada. O collie durable attach conta a partir de 1 e grava entry 2 para a mesma entrada. Ambos indicam qual é o campo. Quando o nome for válido, a bridge grava o nome: entry "desk".

attach e detach se recusam a gravar um arquivo que não conseguem ler, portanto um erro de digitação nunca afeta suas outras entradas. Eles param com o código de saída 1.

Um durable agent não aparece após o attach

Você não vê nenhum durable agent no celular, e collie durable list indica not loaded (restart to apply).

attach e detach apenas gravam sources.json. A bridge o lê na inicialização. Execute collie restart ou adicione --restart ao verbo da próxima vez. Quando not loaded persistir após uma reinicialização, leia collie logs: list formula um HTTP 400 da bridge da mesma forma que um 404.

A verificação de privacidade falhou

Você vê socket-not-private: the socket's folder /tmp/hello has mode 0755, not 0700, e a linha do doctor durable-socket está vermelha.

O Collie só se conecta a um socket se o caminho inteiro for privado. As causas comuns são uma pasta com modo 0755, um socket diretamente em /tmp ou em outra pasta compartilhada e um link simbólico no caminho. É fácil não notar um link simbólico: /var/run aponta para /run em muitos hosts Linux, então um caminho que começa com /var/run/ falha com /var/run is a symlink. Use o caminho real.

Execute chmod 700 na própria pasta do socket ou mova o socket para $XDG_RUNTIME_DIR. As regras estão em Segurança de um durable agent. Um durable agent criado com o SDK se recusa a iniciar em uma pasta existente cujo modo não seja 0700, e avisa isso por conta própria.

Um arquivo de socket órfão

Você vê connection refused em um socket, e o arquivo existe.

Um durable agent que travou deixa seu arquivo de socket para trás, e nada escuta nele. Inicie o durable agent novamente. O SDK remove um arquivo de socket inativo antes de escutar e para com another instance is already listening quando o socket estiver ativo. Exclua o arquivo manualmente apenas se o durable agent não limpá-lo.

Um nome que também é uma sessão de terminal

Você vê a bridge parar na inicialização com the name is the terminal session's own; pick another, ou uma sessão de terminal ausente no celular.

Um durable agent não pode ter o mesmo nome do terminal a partir do qual o Collie é executado. Esse nome é default na maioria das instalações e, em um Collie apenas com durable agents, default é o do seu durable agent. A bridge para na inicialização e nomeia a entrada. Uma sessão do Herdr com o mesmo nome de um durable agent é outro caso: o durable agent mantém o nome, o celular não mostra essa sessão e o log avisa isso uma vez. Renomeie um deles.

Um aviso de durable-ready que persiste

Você vê durable-ready como um aviso em cada execução de collie doctor.

O durable agent responde com hello e informa ready: false. O celular o mostra como Starting. Um durable agent só informa que está pronto depois de estruturar suas conversas e reabrir suas perguntas em aberto. Leia o próprio log do durable agent para saber o que ele está aguardando.

O durable agent para na inicialização na verificação de descendentes

Você vê o durable agent parar na inicialização com the descendant check needs Bun on Linux to read the peer of a socket; pass callerCheck: "off" to run without it.

A verificação requer o Bun no Linux. No macOS, execute o durable agent com Node ou passe callerCheck: "off" para openCollie e leia o que a verificação protege primeiro. O erro se origina no durable agent. O Collie não está envolvido.

Uma pergunta volta após uma reinicialização

Você vê uma pergunta novamente após a reinicialização do durable agent, ou um card informando que ela já foi respondida.

Uma resposta a uma pergunta de antes da reinicialização recebe too-late, e o card mostra isso e desaparece. Um durable agent que deriva o id da pergunta a partir da chamada de ferramenta faz a mesma pergunta novamente, de modo que uma resposta enviada durante a reinicialização chega e a ferramenta roda uma vez. Um durable agent que gera um novo id a cada vez faz uma nova pergunta para a mesma chamada de ferramenta. O card a exibe, e o Collie não envia um segundo push, pois a proteção de push usa a chamada de ferramenta como chave. A proteção também permite 3 pushes por conversa por minuto, 10 por host por minuto e 30 por host por hora. O push que seria o 31º em uma hora se torna um único push de resumo para aquele host, e o host não envia mais nada até uma hora depois dele. Um card é sempre exibido.

403 caller-refused

Você vê o celular informar que a resposta ou a mensagem foi recusada, e o motivo do durable agent é 403 caller-refused.

A verificação de descendentes do durable agent recusou o chamador. Ela recusa o próprio durable agent, qualquer processo iniciado pelo durable agent e qualquer chamador que ela não consiga distinguir deles. O Collie cai do lado do durable agent quando o durable agent, ou uma ferramenta executada por ele, iniciou o processo do Collie e o processo ainda é seu filho. Inicie o Collie a partir de fora do durable agent e tente novamente.

Tentar novamente e uma resposta que pode ser aplicada

Você vê "Not sure the answer arrived" com um botão Tentar novamente e, após o toque, "May already be applied. Check the chat."

Um timeout, uma conexão perdida ou um 5xx após o envio da resposta significa que ela pode ter chegado. Tentar novamente envia o mesmo id de requisição, de modo que o durable agent responde replayed e nunca resolve a pergunta duas vezes. Quando a pergunta já está fechada, a primeira tentativa pode tê-la fechado, então o celular diz para verificar o chat. Um envio, uma parada e um toque de botão dizem o mesmo com palavras próprias.

O agente durável recusou o token

Você vê a barra de conexão dizer "The durable agent refused the token. Check COLLIE_DURABLE_TOKEN on this peer.", e o motivo é token-refused.

O durable agent respondeu 401 ou 403 para o token. A causa mais comum é uma rotação em que um lado mudou primeiro. As palavras no celular mencionam COLLIE_DURABLE_TOKEN mesmo para uma entrada de sources.json: leia isso como o token da entrada. Forneça o novo token ao durable agent antes de reiniciar o Collie. Tokens contém as etapas de rotação. Um 403 também pode vir de um proxy de acesso na frente do durable agent.

Uma mudança para Unreachable que leva duas leituras

Você vê um durable agent permanecer Ready por uma leitura com falha e depois mudar para Unreachable.

Uma leitura com falha após uma bem-sucedida mantém o último layout para essa sondagem. A segunda falha consecutiva muda o estado do durable agent. Um token recusado segue a mesma regra. Um caminho de socket que falha na verificação de privacidade é a única exceção: ele é exibido imediatamente.

Via https, um durable agent que está fora do ar ou recusa o token é consultado no máximo uma vez a cada 10 s, porque cada tentativa é uma requisição cobrada. Via socket, o menor intervalo entre duas leituras de um durable agent fora do ar é de 250 ms.

Em uma crew

Um durable agent em um membro de uma crew aparece no celular do lead, então o lead precisa saber o que é um durable agent.

Um lead anterior a 1.21.0 lista as conversas do durable agent sem o card de pergunta, e sua aba Terminal sonda uma conversa que não tem terminal. Nada no membro corrige isso. O membro avisa por si mesmo: collie doctor alerta em durable-lead, e o log recebe uma linha, [durable] the lead is 1.20.1; it shows durable panes without the question card and its Terminal tab polls; update the lead, uma vez para cada versão identificada. Atualize o lead.

Um membro que é mais antigo que o lead tem a falha oposta. O celular diz "This machine runs an older Collie and cannot take answers here. Update it, or answer in the durable agent." Atualize esse membro.