Um playground de Python baseado em navegador que distribui um runtime de 5,5 MB começou a falhar silenciosamente para usuários em conexões lentas. O culpado foi o uso incorreto da Network Information API e um dashboard de agrupamento de erros que rotulou o problema de forma errada. O bug permaneceu oculto por semanas, desperdiçou o tempo dos desenvolvedores e deixou um segmento de usuários incapaz de executar código.

Como o problema surgiu

O rastreador de erros do playground exibiu uma única mensagem chamativa: “undefined is not an object.” O título sugeria um simples erro de digitação em JavaScript, então a equipe perseguiu um caminho de código inexistente. Quando inspecionaram os metadados brutos, viram que 89% desses incidentes eram, na verdade, timeouts de rede. O dashboard pegou o primeiro erro que chegou e o utilizou para nomear todo o lote, mascarando o verdadeiro tipo de falha.

Lição 1 – Títulos de dashboards podem ser enganosos

Um dashboard que agrega incidentes só ajuda se sua lógica de agregação refletir a causa real de cada evento. Aqui, o agrupamento por localização, em vez de por causa do erro, pintou um quadro falso de um bug no lado do cliente (client-side). A lição: nunca corrija um problema baseando-se apenas em um título de dashboard. Extraia uma amostra dos eventos subjacentes e verifique o que realmente está acontecendo antes de alocar recursos.

Lição 2 – Valores de placeholder não são medições

Para evitar o carregamento do pesado runtime para usuários em conexões lentas, o código consultava a Network Information API e lia a propriedade downlink, que informa megabits por segundo. Em uma primeira visita, o Chrome frequentemente retorna um placeholder em vez de uma medição real. A lógica tratou esse placeholder como uma conexão rápida e pulou a otimização, bloqueando efetivamente os próprios usuários que deveria ajudar.

Trate qualquer valor padrão ou sentinela como “sem dados”. Um placeholder deve acionar uma estratégia de fallback, não ser interpretado como uma leitura de velocidade real.

Lição 3 – As condições de rede mudam, portanto, um único snapshot não é confiável

Após o problema com o downlink, a equipe passou a verificar o effectiveType, que categoriza as conexões como “4g”, “3g”, etc. Um teste rápido em laboratório passou, mas a mesma execução do teste momentos depois falhou. Conexões móveis oscilam; um usuário pode aparecer em uma conexão 4G rápida em um segundo e cair para um 3G mais lento no próximo. Verificar a conexão apenas no carregamento da página é uma aposta arriscada.

A abordagem correta é inscrever-se no evento change no objeto Network Information e reagir a qualquer mudança na largura de banda, em vez de tomar uma decisão única.

O que a equipe mudou

  • Download em duas etapas – O runtime agora começa com um arquivo bootstrap minúsculo. Se a conexão for identificada como lenta, o bootstrap busca o restante do runtime em pequenos pedaços, reduzindo a chance de uma interrupção completa.
  • Monitoramento em tempo real – Em vez de uma única leitura de downlink, o código agora escuta eventos de change e ajusta a estratégia de download dinamicamente.
  • Seleção de fonte estável – Anteriormente, o sistema trocava de CDN no meio do download quando um endpoint mais rápido aparecia. Em uma conexão lenta, isso fazia o download reiniciar do zero, agravando o problema. A nova lógica trava a fonte durante toda a duração do download.
  • Escritas de cache adiadas – Operações pesadas de cache que eram executadas antes de o app estar utilizável agora são adiadas para depois que o runtime for iniciado, liberando largura de banda para o download crítico.

O impacto mais amplo

Para desenvolvedores que constroem ferramentas baseadas na web, a variabilidade da rede é uma preocupação de primeira classe. Uma falha silenciosa em uma conexão lenta frustra os usuários e distorce a telemetria, levando as equipes por um caminho de depuração errado. Neste caso, a interpretação incorreta dos dados causou semanas de investigação infrutífera.

O que observar a seguir

Lição aprendida: Quando os dados parecerem limpos demais, provavelmente são um placeholder; quando um título de dashboard apontar para um único bug, investigue mais a fundo; e quando você basear uma decisão em uma única leitura de rede, estará apostando em um alvo móvel. Ajustar-se a essas realidades transforma falhas silenciosas em eventos previsíveis e recuperáveis.