Como Auditar uma Conexão de Relay do Mastodon com a API

Relays do Mastodon enviam posts públicos de uma instância para várias outras. Quando sua instância se conecta a um relay, você espera um fluxo constante de conteúdo federado. Mas às vezes o relay para de entregar posts ou entrega duplicatas. Você precisa de uma forma para verificar se a conexão está ativa e funcionando corretamente. Este artigo explica como usar a API do Mastodon para auditar uma conexão de relay, verificar seu status e confirmar que os posts estão fluindo como esperado.

O Que é um Relay do Mastodon e Por Que Auditá-lo?

Um relay do Mastodon é um servidor especial que recebe posts públicos de muitas instâncias e os redistribui para todas as instâncias conectadas. Isso ajuda instâncias pequenas a descobrir conteúdo do fediverso sem precisar seguir cada usuário individualmente. O relay mantém uma lista de instâncias inscritas e envia novos posts para cada uma.

Quando você adiciona um relay à sua instância, seu servidor envia uma solicitação de inscrição. O relay aceita e começa a encaminhar posts públicos. Se o relay ficar offline, mudar de URL ou bloquear sua instância, a conexão é interrompida silenciosamente. Sua instância pode não mostrar posts do relay por horas ou dias. Auditar a conexão com a API do Mastodon permite detectar essas falhas rapidamente.

A API do Mastodon fornece dois endpoints principais para gerenciamento de relays. O endpoint GET /api/v1/relays retorna uma lista de todos os relays configurados. Cada entrada inclui a URL da inbox do relay, o estado atual (pending, accepted ou rejected) e a data em que foi adicionado. O endpoint GET /api/v1/instance/relays/:id fornece mais detalhes para um único relay, como a última vez que ele contatou sua instância e quaisquer mensagens de erro.

Você precisa de acesso de administrador à sua instância do Mastodon para usar esses endpoints da API. Usuários comuns não podem visualizar configurações de relay. Você também precisa de um token de acesso com os escopos admin:read e admin:write. Se você administra uma instância de usuário único, é o administrador por padrão e pode gerar um token em Preferências > Desenvolvimento.

Passos para Auditar uma Conexão de Relay do Mastodon Usando a API

Siga estes passos para verificar a conexão de relay na sua instância e confirmar que está funcionando corretamente. Substitua yourinstance.social pelo domínio real da sua instância do Mastodon e YOUR_TOKEN pelo seu token de acesso de administrador.

1. Gerar um token de acesso de administrador
   Faça login na sua instância do Mastodon como administrador. Vá em Preferências > Desenvolvimento > Nova Aplicação. Dê um nome para a aplicação, por exemplo “Auditoria de Relay”. Em Escopos, selecione admin:read e admin:write. Clique em Enviar. Copie o token de acesso exibido na tela seguinte. Mantenha este token seguro, pois ele concede controle total de administrador.
2. Listar todos os relays configurados
   Abra um terminal ou cliente de API como curl ou Postman. Envie uma requisição GET para https://yourinstance.social/api/v1/relays com o cabeçalho Authorization: Bearer YOUR_TOKEN. A resposta é um array JSON. Cada objeto no array contém os campos id, inbox_url, state e created_at. O campo state será um de pending, accepted ou rejected. Se a lista estiver vazia, sua instância não tem relays configurados.
3. Inspecionar o estado de cada relay
   Para cada relay na lista, observe o valor de state. Um estado accepted significa que o relay aceitou sua inscrição e deve estar encaminhando posts. Um estado pending significa que o relay ainda não respondeu à sua solicitação de inscrição. Um estado rejected significa que o relay negou sua inscrição, geralmente devido a um bloqueio ou incompatibilidade de configuração.
4. Obter status detalhado de um único relay
   Para ver mais detalhes de um relay específico, envie uma requisição GET para https://yourinstance.social/api/v1/instance/relays/RELAY_ID, onde RELAY_ID é o id da lista. Use o mesmo cabeçalho de autorização. A resposta inclui id, inbox_url, state, last_contact_at, error e created_at. O campo last_contact_at mostra a última vez que o relay enviou dados para sua instância. Se este campo for nulo ou mostrar uma data muito antiga, o relay pode estar offline ou desconectado.
5. Verificar o campo de erro para motivos de falha
   Na resposta detalhada, observe o campo error. Se o relay encontrou um problema, este campo contém uma mensagem descritiva. Erros comuns incluem Connection refused, Timeout, Invalid SSL certificate ou HTTP 403 Forbidden. Essas mensagens indicam se o problema está do seu lado, do lado do relay ou é um problema de rede.
6. Verificar se os posts do relay aparecem na sua instância
   Após verificar o status da API, confirme se os posts do relay estão realmente aparecendo na sua instância. Abra a linha do tempo federada no seu cliente Mastodon. Procure por posts de contas em outras instâncias que você não seguiu diretamente. Se a linha do tempo federada estiver vazia ou mostrar apenas posts locais, o relay pode não estar enviando conteúdo mesmo que a API reporte status accepted. Nesse caso, readicione o relay usando a API.
7. Readicionar o relay se necessário
   Se o estado for rejected ou o último contato for muito antigo, remova e readicione o relay. Envie uma requisição DELETE para https://yourinstance.social/api/v1/relays/RELAY_ID com o mesmo cabeçalho de autorização. Em seguida, envie uma requisição POST para https://yourinstance.social/api/v1/relays com um corpo JSON contendo {"relay_url": "https://relay.example.com/inbox"} e o cabeçalho de autorização. Isso redefine o handshake de inscrição.

Problemas Comuns ao Auditar Conexões de Relay do Mastodon

Estado do Relay Mostra Pendente por Mais de 24 Horas

Um estado pendente significa que sua instância enviou uma solicitação de inscrição, mas o relay não respondeu. Isso geralmente acontece porque o relay está offline, a URL do relay está incorreta ou o relay está bloqueando sua instância. Verifique o site ou página de status do relay para ver se está operacional. Confirme que a URL da inbox na configuração do relay corresponde exatamente ao que o relay espera, incluindo o caminho e a barra final. Se o relay for privado, pode ser necessário solicitar aprovação do operador do relay.

Estado do Relay Mostra Rejeitado

Um estado rejeitado significa que o relay negou explicitamente sua inscrição. Isso pode acontecer se sua instância estiver em uma lista de bloqueio mantida pelo operador do relay, se sua instância tiver má reputação ou se o relay aceitar apenas instâncias que atendam a certos critérios, como um padrão mínimo de moderação. Entre em contato com o operador do relay para perguntar por que sua instância foi rejeitada. Alternativamente, mude para um relay público diferente que tenha inscrição aberta.

Último Contato é Recente mas a Linha do Tempo Federada Está Vazia

Se a API reportar um last_contact_at recente, mas você não vir novos posts do relay, sua instância pode estar recebendo os posts, mas filtrando-os. Verifique as configurações de moderação da sua instância. Se você ativou bloqueios de domínio ou filtros de palavras-chave, eles podem suprimir os posts do relay. Verifique também se o relay em si está ativo e produzindo conteúdo. Alguns relays pausam o encaminhamento se detectarem uma onda de spam ou se a instância upstream estiver offline.

API Retorna 401 Não Autorizado ao Acessar Endpoints de Relay

Um erro 401 significa que o token de acesso é inválido ou está faltando os escopos necessários. Regere o token em Preferências > Desenvolvimento. Certifique-se de que o token inclua ambos os escopos admin:read e admin:write. Se você estiver usando um cliente de terceiros, confirme que o cliente está enviando o token no cabeçalho Authorization como Bearer YOUR_TOKEN. Não envie o token como parâmetro de consulta, pois o Mastodon ignora tokens na URL por razões de segurança.

Comparação de Endpoints da API de Relay

Item	GET /api/v1/relays	GET /api/v1/instance/relays/:id
Propósito	Listar todos os relays configurados na instância	Obter status detalhado de um único relay
Campos da resposta	id, inbox_url, state, created_at	id, inbox_url, state, last_contact_at, error, created_at
Escopo necessário	admin:read	admin:read
Caso de uso	Auditoria inicial para ver todos os relays	Investigação aprofundada de um problema específico de relay

Agora você pode auditar qualquer conexão de relay do Mastodon usando os endpoints da API descritos acima. Comece listando todos os relays e verificando seu estado. Se um relay mostrar pendente ou rejeitado, investigue o campo de erro e readicione o relay se necessário. Para uma verificação mais aprofundada, compare o horário do último contato com os posts reais que aparecem na sua linha do tempo federada. Se você gerencia várias instâncias, automatize as chamadas de API com curl ou uma ferramenta como jq para realizar auditorias regulares e detectar falhas de relay precocemente.