Ajuste do TTL do Cache Webfinger na Federação do Mastodon

Quando instâncias do Mastodon se comunicam, elas usam consultas Webfinger para resolver endereços de usuário como usuario@exemplo.com em dados de perfil locais. Cada resultado da consulta é armazenado em cache para reduzir a carga de rede e acelerar requisições futuras. O TTL (Time to Live) padrão do cache controla por quanto tempo esses dados permanecem atualizados antes que o sistema os busque novamente. Um TTL muito curto aumenta requisições de saída e a carga do servidor. Um TTL muito longo pode fazer com que informações desatualizadas do usuário persistam na federação. Este artigo explica o que o TTL do cache Webfinger faz, como ajustá-lo na sua instância do Mastodon e quais efeitos colaterais esperar após alterar o valor.

O que o TTL do Cache Webfinger Controla no Mastodon

Webfinger é o protocolo que o Mastodon usa para descobrir o endpoint ActivityPub de um usuário a partir de um endereço federado. Quando você pesquisa um usuário em uma instância remota, sua instância local envia uma requisição Webfinger para a instância remota. O servidor remoto responde com dados JSON que incluem o nome de exibição do usuário, URL do avatar e a localização do seu actor ActivityPub. O Mastodon armazena essa resposta em um cache local para que pesquisas subsequentes pelo mesmo usuário não exijam uma nova requisição de saída.

O TTL do cache define o tempo máximo em segundos que uma resposta Webfinger em cache permanece válida. Após o TTL expirar, a próxima consulta para aquele usuário dispara uma nova requisição Webfinger. Os dados em cache não são atualizados automaticamente em segundo plano. Eles são substituídos apenas quando uma nova consulta ocorre após o TTL ter expirado.

O TTL padrão é 86400 segundos, que equivale a 24 horas. Esse valor funciona bem para a maioria das instâncias do Mastodon porque alterações de perfil de usuário em instâncias remotas são relativamente raras. Encurtar o TTL aumenta o número de requisições de saída que sua instância faz, o que pode levar a limitação de taxa por servidores remotos ou maior uso de largura de banda. Aumentar o TTL reduz requisições de saída, mas aumenta a chance de sua instância exibir informações desatualizadas do usuário, como um nome de exibição ou avatar antigo.

Passos para Alterar o TTL do Cache Webfinger

1. Abra o arquivo .env.production
   Conecte-se ao seu servidor Mastodon via SSH. Navegue até o diretório de instalação do Mastodon, geralmente /home/mastodon/live. Abra o arquivo .env.production com um editor de texto como nano ou vim. Exemplo de comando: sudo -u mastodon nano /home/mastodon/live/.env.production
2. Adicione ou edite a variável WEBFINGER_CACHE_TTL
   Encontre a linha que começa com WEBFINGER_CACHE_TTL. Se não existir, adicione-a no final do arquivo. Defina o valor para o número desejado de segundos. Para um TTL de 12 horas, use 43200. Para um TTL de 48 horas, use 172800. Exemplo de linha: WEBFINGER_CACHE_TTL=43200
3. Salve o arquivo e saia do editor
   No nano, pressione Ctrl+O para salvar, depois Ctrl+X para sair. No vim, pressione Escape, digite :wq e pressione Enter.
4. Reinicie os serviços do Mastodon
   Execute os seguintes comandos para reiniciar os processos web e sidekiq do Mastodon: sudo systemctl restart mastodon-web e sudo systemctl restart mastodon-sidekiq. O novo valor de TTL entra em vigor imediatamente após a reinicialização dos serviços.
5. Verifique a alteração
   Execute o console Rails do Mastodon para confirmar que a variável de ambiente foi carregada: cd /home/mastodon/live && sudo -u mastodon RAILS_ENV=production bin/rails c. Em seguida, digite ENV['WEBFINGER_CACHE_TTL'] e pressione Enter. O console deve retornar o novo valor como uma string. Digite exit para sair do console.

Erros Comuns e Efeitos Colaterais ao Ajustar o TTL

Definir o TTL Muito Baixo Causa Requisições de Saída Excessivas

Se você definir WEBFINGER_CACHE_TTL para um valor abaixo de 3600 segundos (uma hora), sua instância enviará requisições Webfinger para o mesmo usuário remoto muitas vezes por dia. Servidores remotos podem limitar a taxa ou bloquear sua instância se o volume de requisições for muito alto. Isso pode degradar o desempenho da federação em vez de melhorá-lo. Um TTL abaixo de 3600 segundos não é recomendado para instâncias de produção.

Alterar o TTL Não Limpa as Entradas de Cache Existentes

A variável de ambiente afeta apenas novas consultas. As respostas Webfinger em cache existentes permanecem no cache até que seu TTL original expire. Para limpar todas as entradas em cache do Webfinger imediatamente, você deve limpar o cache do Rails. Execute o comando: cd /home/mastodon/live && sudo -u mastodon RAILS_ENV=production bin/tootctl cache clear. Este comando remove todos os dados em cache, incluindo respostas Webfinger. Após a limpeza, cada consulta buscará dados frescos.

Dados de Usuário Desatualizados Persistem em Instâncias Federadas

Sua própria instância do Mastodon controla apenas seu próprio cache. Instâncias remotas que armazenaram em cache os dados Webfinger dos seus usuários continuarão usando suas próprias configurações de TTL. Mesmo que sua instância atualize seu cache a cada hora, uma instância remota com um TTL de 24 horas não verá o perfil atualizado do seu usuário até que seu próprio cache expire. Isso é por design e não pode ser sobrescrito do seu lado.

TTL do Cache Webfinger vs Outras Configurações de Cache da Federação

Item	TTL do Cache Webfinger	Outros Caches da Federação
Propósito	Controla por quanto tempo um resultado de descoberta de usuário é armazenado localmente	Controla por quanto tempo objetos ActivityPub e timelines são armazenados em cache
Variável de ambiente	WEBFINGER_CACHE_TTL	ACTIVITYPUB_CACHE_TTL e TIMELINE_CACHE_TTL
Valor padrão	86400 segundos (24 horas)	300 segundos (5 minutos) para objetos ActivityPub
Efeito de valor baixo	Aumento de requisições HTTP de saída para instâncias remotas	Maior carga de CPU e consultas ao banco de dados na instância local
Efeito de valor alto	Nomes de exibição e avatares de usuário desatualizados	Postagens desatualizadas em timelines federadas

O cache Webfinger é separado do cache de objetos ActivityPub e do cache de timeline. Ajustar um não afeta os outros. Se você quiser reduzir a carga geral da federação, considere ajustar as três variáveis de ambiente juntas, mas teste cada alteração separadamente em um ambiente de staging primeiro.

Agora você pode ajustar o TTL do cache Webfinger na sua instância do Mastodon para corresponder ao seu tráfego de federação e frequência de atualização de usuários. Comece com o padrão de 86400 segundos e diminua apenas se observar dados desatualizados de usuários de instâncias remotas específicas. Após alterar o valor, reinicie os serviços mastodon-web e mastodon-sidekiq. Use o comando tootctl cache clear para forçar uma limpeza completa se precisar de resultados imediatos. Para ajustes avançados, monitore a taxa de requisições HTTP de saída da sua instância usando uma ferramenta como Prometheus para encontrar o TTL ideal para a capacidade do seu servidor.