Introdução: por que o HTTP em streaming via proxy virou um problema generalizado

Imagine: você enviou uma requisição para um modelo de linguagem e, em vez do habitual "digitar" dos tokens, a tela fica muda por quarenta segundos e depois cospe a resposta inteira de uma vez. Ou um dashboard de monitoramento que deveria atualizar a cada segundo mostra dados com meio minuto de atraso. Ou um scraper que escuta o fluxo de eventos de uma plataforma de negociação recebe pacotes de cem eventos em vez de um riacho constante. Em nove de cada dez casos, a culpa não é do servidor nem do cliente. A culpa é de quem está entre eles: um proxy, balanceador, CDN ou gateway corporativo que resolveu "ajudar" e acumular a resposta inteira antes de repassar.

O tema de respostas HTTP em streaming através de nós intermediários foi considerado nicho por muito tempo. Em 2026, virou algo massivo. Streaming de tokens de APIs de LLM, eventos do servidor em interfaces web, long-polling em mensageiros e bots, barras de progresso de exportações longas, entrega em streaming de resultados de scraping — tudo isso roda sobre o bom e velho HTTP, que simplesmente não tem pressa de fechar a resposta. E tudo isso quebra assim que aparece no caminho um nó com bufferização ativada.

Neste guia, vamos destrinchar três mecanismos clássicos — chunked transfer encoding, Server-Sent Events e long-polling — especificamente do ponto de vista de atravessar proxies. Uma ressalva importante logo de cara: aqui não haverá WebSocket nem gRPC. Eles têm material próprio, e a diferença é fundamental. Lá acontece um upgrade de protocolo ou se usa enquadramento binário sobre HTTP/2, e o proxy precisa reconhecer e deixar passar esse upgrade. Aqui, é uma resposta HTTP comum, sem o cabeçalho Content-Length, que o servidor mantém aberta. Nenhum handshake, nenhuma transição para outro protocolo. Parece que não poderia ser mais simples. Mas é justamente essa simplicidade que cria o problema: o proxy não vê nada de especial e aplica as regras padrão de bufferização, pensadas para respostas curtas.

O que você vai encontrar neste material: entendimento de como o stream é estruturado no nível de bytes e cabeçalhos; um mapa de todos os pontos onde a resposta pode travar; configurações prontas para nginx, HAProxy, Envoy e bibliotecas cliente; um framework de escolha entre os três mecanismos; checklists de diagnóstico; casos reais dissecados com números. O material é voltado para desenvolvedores, engenheiros DevOps e todos que usam proxies para trabalhar com APIs, scraping e automação.

Fundamentos: como uma resposta HTTP comum se transforma em stream

Duas formas de informar o tamanho da resposta

No HTTP/1.1 existem duas formas fundamentais de dizer ao cliente onde termina o corpo da resposta. A primeira é o cabeçalho Content-Length: o servidor declara antecipadamente o número exato de bytes. A segunda é Transfer-Encoding: chunked: o servidor envia o corpo em porções, cada porção começa com seu tamanho em formato hexadecimal, e tudo termina com um chunk zero. Há também uma terceira variante arcaica — simplesmente fechar a conexão depois do último byte —, mas com keep-alive isso praticamente não se usa.

Por que isso importa para o streaming? Porque Content-Length exige saber o tamanho com antecedência. Se o servidor gera a resposta gradualmente — token por token, evento por evento —, ele fisicamente não consegue calcular o tamanho antes de começar a transmitir. A única opção no HTTP/1.1 é chunked. No HTTP/2 e HTTP/3, a codificação chunked como tal não existe: o corpo já é transmitido em quadros DATA, e o fim é marcado pela flag END_STREAM. Mas a lógica é a mesma: uma resposta sem comprimento declarado, que pode durar o quanto for.

O que significa "não fechar a resposta"

Uma analogia. Uma resposta HTTP comum é como um pacote: você recebe uma caixa com o peso escrito na etiqueta, abre e sabe que tem tudo ali. Uma resposta em streaming é como uma esteira transportadora: caixas vão chegando uma atrás da outra, e você não sabe quando a esteira vai parar. O servidor enviou os cabeçalhos com status 200, enviou o primeiro chunk — e espera. Chegaram novos dados — envia o próximo. A conexão permanece aberta por minutos, horas, às vezes dias.

Do ponto de vista do TCP, nada de anormal acontece: o mesmo socket, os mesmos segmentos. Do ponto de vista do HTTP, é uma única requisição e uma única resposta, só que muito longas. E é aqui que mora a raiz de todos os problemas com proxies: o nó intermediário vê o início da resposta, não vê o fim e precisa decidir o que fazer com os bytes que já chegaram. Repassar imediatamente? Ou esperar, acumular mais e enviar com mais eficiência? Por padrão, a maioria dos proxies escolhe a segunda opção.

Três mecanismos: o que há em comum e o que difere

  • Chunked streaming — o mais baixo nível. O servidor simplesmente escreve bytes no corpo e chama flush. O formato do conteúdo é livre: texto, NDJSON, dados binários. O cliente decide como parsear.
  • Server-Sent Events — formato textual padronizado sobre o fluxo chunked. Content-Type: text/event-stream, eventos separados por linhas vazias, com campos data, event, id, retry. O navegador oferece suporte nativo via EventSource com reconexão automática.
  • Long-polling — a rigor, não é streaming. O cliente faz uma requisição, o servidor a mantém aberta até surgir dado ou até estourar o timeout, responde e fecha. O cliente imediatamente faz a próxima requisição. É a simulação de um stream por meio de uma sequência de respostas comuns, cada uma podendo ter Content-Length.

O que eles têm em comum? Nos três casos, a resposta a uma única requisição fica retida por tempo indeterminado, e o proxy precisa sobreviver a isso: não derrubar a conexão por timeout e não segurar os dados no buffer. A diferença está em quão dependente cada mecanismo é da transparência do nó intermediário. Chunked e SSE dependem criticamente. Long-polling, minimamente — e essa é sua maior vantagem.

O papel do proxy na cadeia

Na infraestrutura moderna, raramente há um vazio entre cliente e servidor. A cadeia típica: aplicação cliente — proxy de saída (por exemplo, móvel ou residencial) — internet — CDN — balanceador de nuvem — proxy reverso — aplicação. Cada um desses nós é um ponto potencial de bufferização. E cada um, por padrão, está configurado para otimizar respostas curtas: coletar, comprimir, entregar tudo de uma vez. Para o streaming, essa otimização é uma catástrofe. Vamos remover essas camadas uma a uma e ver o que acontece em cada nível.

Mergulho profundo: onde e por que o stream trava em um nó intermediário

Por que os proxies bufferizam, afinal

Antes de xingar a bufferização, vale entender a lógica dela. Um proxy reverso como o nginx bufferiza por três motivos. Primeiro, proteção do backend contra o cliente lento: se o cliente em uma conexão móvel lê a dez kilobytes por segundo, e o backend já gerou a resposta, é mais vantajoso pegar tudo do backend de uma vez, liberar o worker dele e depois entregar calmamente ao cliente a partir do buffer. Segundo, compressão: gzip e brotli funcionam melhor em blocos grandes. Terceiro, a possibilidade de definir Content-Length e tratar corretamente erros do backend antes de enviar cabeçalhos ao cliente.

Para uma API típica com respostas de alguns kilobytes, tudo isso faz sentido e economiza recursos. Para o streaming, é exatamente o contrário: ao atrasar os bytes, o proxy destrói o próprio valor do stream. Esse valor está na pontualidade, não no volume.

Mapa de oito pontos de bufferização

Vamos percorrer a cadeia e marcar cada ponto onde os dados podem travar. Mantenha esta lista por perto ao diagnosticar.

  1. Aplicação. O framework pode bufferizar a saída por conta própria. Servidores WSGI, PHP com output_buffering ativado, frameworks Node.js com middleware de compressão. Flush não é chamado — os dados ficam no buffer do processo.
  2. Proxy reverso na frente da aplicação. nginx com proxy_buffering on (ativado por padrão) acumula a resposta nos buffers definidos por proxy_buffer_size e proxy_buffers e, quando estouram, em arquivo temporário em disco. Apache mod_proxy bufferiza menos, mas tem suas configurações. Caddy não bufferiza por padrão, mas vale checar o flush_interval.
  3. Compressão no proxy. Mesmo com proxy_buffering off, o gzip ativado acumula dados até o tamanho da janela de compressão. É um dos pontos mais traiçoeiros: a bufferização está formalmente desligada, e o stream sai em trancos.
  4. Balanceador L7. O HAProxy em modo http transmite os dados conforme chegam, se http-buffer-request não estiver ativado, mas fica limitado pelo tune.bufsize. O Envoy faz streaming por padrão, mas filtros de compressão ou Lua podem acumular o corpo.
  5. CDNs e gateways de nuvem. Muitas CDNs bufferizam respostas para cache e compressão. Parte dos provedores não suporta streams acima de determinado tempo ou exige configurações explícitas. Gateways de API em nuvem geralmente têm limite rígido de tempo de resposta em torno de 30 segundos e simplesmente não suportam streaming de corpo.
  6. Proxy de saída do lado do cliente. O proxy HTTP pelo qual você navega na internet — corporativo, móvel, residencial — também é um parser de HTTP. Se for construído sobre nginx ou Squid e configurado para bufferizar, o stream trava ali. Serviços de proxy de qualidade passam respostas chunked de forma transparente, mas isso precisa ser verificado na prática.
  7. TLS e TCP. Os dados podem ficar retidos em registros TLS se a biblioteca os acumular até 16 kilobytes. O algoritmo de Nagle atrasa segmentos TCP pequenos até o recebimento do ACK anterior. Para um stream de chunks pequenos, isso adiciona dezenas de milissegundos a cada um.
  8. Biblioteca cliente. O requests em Python lê todo o corpo em memória se stream=True não for passado. Vários clientes HTTP bufferizam até o tamanho de chunk_size.

Oito pontos. Se pelo menos um deles acumular dados, você verá o stream em trancos ou em um único grande pacote no final. E o mais desagradável: o comportamento depende do volume. Em respostas pequenas, tudo parece normal; sob carga ou em respostas longas, o buffer enche, começa a gravação em arquivos temporários e as latências disparam. Não é à toa que muitas equipes só descobrem o problema em produção.

HTTP/1.1 versus HTTP/2 no contexto de streaming

No HTTP/1.1, uma conexão carrega uma resposta por vez. Uma resposta de longa duração ocupa a conexão inteira. O navegador limita o número de conexões simultâneas a um mesmo host a seis, então seis streams SSE abertos bloqueiam todas as demais requisições àquele host. Um proxy que fala HTTP/1.1 com o backend também mantém uma conexão para cada stream.

No HTTP/2, a multiplexação remove essa limitação: cem streams convivem em uma única conexão TCP. Mas surge uma sutileza — o controle de fluxo no nível do protocolo. Se o receptor não expande a janela via WINDOW_UPDATE, o emissor para. Alguns proxies implementam o encaminhamento desses quadros de forma descuidada e criam pausas artificiais.

É importante entender: o proxy pode receber a requisição via HTTP/2 do cliente e ir até o backend via HTTP/1.1. Ele reempacota quadros DATA em chunks e vice-versa. É uma operação normal, mas é justamente na fronteira de conversão que muitas vezes se perde o flush pontual — o proxy espera acumular um tamanho "conveniente" de quadro.

Timeouts — o segundo assassino de streams

A bufferização atrasa dados. Os timeouts cortam a conexão. No nginx existe o proxy_read_timeout — tempo máximo entre duas operações consecutivas de leitura do backend, 60 segundos por padrão. Se o servidor fica em silêncio mais do que isso, o nginx fecha a conexão e devolve um 504 ao cliente. Para long-polling com espera de 90 segundos, isso é falha garantida. No HAProxy — timeout server e timeout tunnel. Nos balanceadores de nuvem — idle timeout, frequentemente de 60 ou 350 segundos. Nas operadoras móveis — timeouts de NAT que derrubam conexões inativas depois de alguns minutos.

Daí a regra de ferro: um stream sem atividade periódica está condenado. Mensagens de heartbeat a cada 15-30 segundos não são uma opção, são um requisito obrigatório de qualquer resposta de longa duração.

Matriz de escolha do mecanismo

Antes de partir para a prática, fixemos o framework de decisão. Responda quatro perguntas.

  • Você controla toda a cadeia de proxies? Sim — chunked e SSE são adequados. Não, há gateways desconhecidos na cadeia — comece com long-polling ou preveja degradação para ele.
  • Quem é o cliente? Navegador — SSE com EventSource dá reconexão de graça. Código próprio — chunked com NDJSON é mais flexível.
  • Qual a natureza dos dados? Fragmentos de uma única entidade (tokens de uma mesma resposta) — chunked ou SSE. Eventos discretos e independentes — SSE ou long-polling.
  • Qual a frequência? Dezenas de eventos por segundo — chunked ou SSE com batching. Evento uma vez por minuto — long-polling com timeout alto ou SSE com heartbeat.

Método 1: chunked transfer encoding — streaming de baixo nível sem camada extra

Quando escolher chunked puro

Um stream chunked puro é adequado quando o cliente é código seu, não um navegador; quando o formato dos dados não é textual ou não se encaixa no modelo de eventos; quando você precisa do máximo controle sobre cada byte. Exemplos típicos: streaming de NDJSON de uma API, entrega em streaming de resultados de scraping, download de exportações grandes com indicador de progresso, proxy de respostas de LLM em formato próprio.

Configuração passo a passo do lado do servidor

  1. Garanta que a aplicação escreva por partes. Após cada porção lógica, chame flush. Em Python com servidor ASGI, é um gerador que produz bytes; em Node.js — res.write seguido de flush, se houver compressão envolvida; em Go — a interface http.Flusher após cada Write.
  2. Não defina Content-Length. A maioria dos frameworks troca automaticamente para chunked se o comprimento não for informado. Verifique se na resposta sob HTTP/1.1 aparece Transfer-Encoding: chunked.
  3. Desative a compressão no nível da aplicação para rotas de streaming ou garanta que ela faça flush junto com os dados. O compromisso é gzip com flush síncrono após cada chunk; funciona, mas reduz a taxa de compressão.
  4. Defina o cabeçalho X-Accel-Buffering: no. É um cabeçalho específico do nginx que desativa a bufferização para aquela resposta específica sem alterar a configuração global. Alguns outros proxies também o entendem. Adicione também Cache-Control: no-cache, no-transform — o segundo valor pede que os nós intermediários não modifiquem o corpo.
  5. Configure o proxy reverso. Para o nginx, no location da rota de streaming: proxy_buffering off; proxy_cache off; proxy_http_version 1.1; proxy_set_header Connection ''; proxy_read_timeout 3600s; gzip off;. A diretiva proxy_http_version 1.1 é obrigatória: por padrão o nginx fala com o backend por HTTP/1.0, onde chunked não existe, e o nginx é forçado a bufferizar até o fechamento da conexão.
  6. Separe as rotas. Se a compressão for necessária para o restante da API, ative-a apenas em blocos location que não sejam de streaming.
  7. Verifique o algoritmo de Nagle. No nginx o tcp_nodelay vem ativado por padrão, mas na aplicação, com chunks pequenos e frequentes, pode ser necessário definir TCP_NODELAY explicitamente no socket.

Configuração de HAProxy e Envoy

HAProxy. Na seção backend, não use option http-buffer-request. Certifique-se de que timeout server seja suficientemente grande para o seu cenário, e para streams realmente longos defina timeout tunnel. Desative a compressão para os caminhos de streaming via ACL ou confie no cabeçalho no-transform: o HAProxy respeita Cache-Control: no-transform e não comprime tais respostas.

Envoy. A bufferização vem desligada por padrão, o que é ótimo. Mas verifique dois timeouts: stream_idle_timeout no HTTP connection manager (cinco minutos por padrão) e o route timeout (quinze segundos por padrão — é ele que mais frequentemente derruba streams). Para rotas de streaming, defina timeout igual a 0s, o que significa sem limite, e conte com o idle timeout combinado com heartbeat.

Checklist de verificação do stream chunked

  • A resposta contém Transfer-Encoding: chunked, ou usa HTTP/2 sem Content-Length.
  • O cabeçalho X-Accel-Buffering: no está presente na resposta da aplicação.
  • Não há Content-Encoding ou a compressão faz flush junto com os dados.
  • O primeiro byte do corpo chega em até um segundo após os cabeçalhos.
  • Os intervalos entre chunks no cliente coincidem com os intervalos de geração no servidor com erro de até 50 milissegundos.
  • A conexão vive mais de um minuto sem queda, desde que haja heartbeat.
  • Não há registros de bufferização em arquivo temporário nos logs do proxy.

Método 2: Server-Sent Events — o padrão para eventos de servidor para cliente

A estrutura do formato

SSE é uma convenção sobre como organizar eventos em um fluxo textual. A resposta tem Content-Type: text/event-stream. Cada evento é um conjunto de linhas no formato "campo: valor", terminadas por uma linha vazia. Campos: data — a carga útil (pode se repetir, com as linhas concatenadas por quebra de linha); event — o nome do tipo de evento; id — identificador para retomada; retry — atraso sugerido de reconexão em milissegundos. Uma linha começando com dois-pontos é um comentário, e é o heartbeat perfeito: o navegador o ignora, mas o proxy vê atividade na conexão.

A beleza do SSE está na assimetria. A complexidade fica na especificação e no navegador, e o servidor permanece trivial. Sem handshake, sem enquadramento binário. Apenas texto que flui. É por isso que SSE virou o padrão de fato para streaming de respostas de modelos de linguagem: a esmagadora maioria das grandes APIs de LLM entrega tokens em formato text/event-stream. É curioso que uma tecnologia descrita em especificações há mais de quinze anos esteja vivendo um segundo florescimento em 2026.

Por que o SSE é especialmente sensível à bufferização

Um evento SSE pesa entre algumas dezenas de bytes e alguns kilobytes. O buffer padrão do nginx é de 4 ou 8 kilobytes no primeiro bloco e de oito blocos de 4-8 kilobytes na sequência. Ou seja, o proxy vai acumular de cinquenta a várias centenas de eventos antes de entregar o primeiro. Para um chat com modelo, isso se traduz em: o usuário espera quinze segundos, depois o parágrafo inteiro aparece de uma vez. A ilusão de digitação está destruída — e era justamente por causa dela que o streaming foi adotado.

Implementação passo a passo de SSE via proxy

  1. Cabeçalhos da resposta: Content-Type: text/event-stream; charset=utf-8, Cache-Control: no-cache, no-transform, X-Accel-Buffering: no, e para HTTP/1.1 ainda Connection: keep-alive.
  2. Heartbeat. Envie uma linha de comentário no formato : ping a cada 15-25 segundos. Isso é menor que qualquer idle timeout razoável e mantém as tabelas NAT das operadoras em estado atualizado.
  3. Identificadores de evento. Atribua a cada evento um id crescente e monotônico. Ao reconectar, o navegador envia o cabeçalho Last-Event-ID, e o servidor pode reenviar o que foi perdido. Sem isso, qualquer queda no proxy significa perda de dados.
  4. Campo retry. Defina um valor sensato, por exemplo 3000 milissegundos, para que os clientes não provoquem uma tempestade de reconexões ao reiniciar o servidor.
  5. Configuração do nginx — a mesma do chunked. Adicionalmente, garanta que gzip não seja aplicado a text/event-stream: se gzip_types inclui text/*, adicione um location específico com gzip off.
  6. Planejamento de conexões. Cada stream SSE aberto em HTTP/1.1 é uma conexão separada entre proxy e backend. Para mil clientes simultâneos, são mil conexões. Use HTTP/2 do lado do cliente e servidor assíncrono no backend.
  7. Tratamento de fechamento. O servidor deve detectar que o cliente rompeu a conexão e interromper a geração. Via proxy, isso acontece com atraso: o servidor descobre a queda apenas ao tentar escrever. Para operações caras como inferência de modelo, isso significa segundos desperdiçados de GPU. A solução são escritas regulares de heartbeat, que provocam erro de escrita em conexões rompidas.

SSE e HTTP/2: nuances

Via HTTP/2 o SSE funciona sem a limitação de seis conexões — é a principal razão para habilitar HTTP/2 no proxy de front-end. No entanto, ao traduzir HTTP/2 para HTTP/1.1 rumo ao backend, alguns proxies adicionam um pequeno atraso por causa da agregação de quadros. Garanta que o primeiro evento saia imediatamente, sem esperar preencher o quadro. Se o backend também fala HTTP/2, os atrasos são mínimos, mas verifique se o proxy repassa corretamente os WINDOW_UPDATE e não estrangula o stream com o controle de janela.

Framework de design de um stream SSE

  1. Defina os tipos de eventos e sua frequência. Eventos raros exigem heartbeat; eventos frequentes pedem batching de várias escritas dentro de um mesmo evento.
  2. Escolha a estratégia de retomada: manter um buffer circular dos últimos eventos no servidor para tratar Last-Event-ID, ou contar com ressincronização completa na reconexão.
  3. Estabeleça um limite de duração para cada stream. Boa prática — o servidor fecha o stream sozinho a cada 5-10 minutos, e o cliente reconecta de forma transparente. Isso protege contra acúmulo de estado e contorna timeouts ocultos da infraestrutura.
  4. Pense na degradação: se o stream não passa pelo proxy, migre automaticamente para long-polling.

Método 3: long-polling — stream feito de sequência de respostas comuns

Como funciona e por que continua relevante

Long-polling é a técnica mais antiga das três. O cliente envia a requisição, o servidor não responde na hora, mas espera por um evento até um timeout definido (normalmente 20-60 segundos). Surgiu um evento — o servidor entrega a resposta e a fecha. Não surgiu nada — entrega uma resposta vazia. O cliente envia imediatamente a próxima requisição. Visto de fora, parece um stream com latência mínima, mas cada resposta é comum, com Content-Length, totalmente compatível com qualquer proxy, qualquer cache e qualquer gateway.

Por que em 2026 o long-polling continua vivo e saudável? Porque ele passa em qualquer lugar. Por gateways corporativos que cortam chunked. Por gateways de API em nuvem com limite de tempo de resposta. Por servidores proxy com bufferização imprevisível. O exemplo mais conhecido é o método de obtenção de atualizações em uma Bot API de um grande mensageiro, em que o parâmetro timeout define a duração da espera. A esmagadora maioria dos bots opera assim há anos, através dos mais variados proxies, sem problemas.

Cinco regras de design de long-polling via proxy

  1. O timeout do servidor deve ser menor que o menor timeout da cadeia. Se o proxy tem proxy_read_timeout de 60 segundos, a espera do servidor não passa de 50. Se há um gateway de nuvem com 30 segundos na cadeia, não passe de 25. Caso contrário, em vez de uma resposta vazia o cliente vai receber um 504, e a cascata de erros vai enlouquecer o monitoramento.
  2. Cursor ou offset. O cliente envia o identificador do último evento recebido. O servidor entrega tudo o que surgiu depois dele. O protocolo vira idempotente: uma resposta perdida simplesmente provoca o reenvio dos mesmos eventos.
  3. Jitter na reconexão após erro. Crescimento exponencial do atraso — 1, 2, 4, 8 segundos — mais uma adição aleatória. Sem jitter, mil clientes golpeiam o servidor ao mesmo tempo depois de uma falha.
  4. Zero de pausa após resposta bem-sucedida. A próxima requisição sai imediatamente. Qualquer pausa aqui é latência perdida.
  5. Keep-alive é obrigatório. Sem ele, cada requisição é uma nova conexão TCP e um novo handshake TLS. Isso adiciona de 50 a 300 milissegundos a cada ciclo, e via proxy remoto, ainda mais.

Implementação passo a passo

  1. Servidor: o endpoint recebe offset e timeout, espera por um evento em uma fila interna ou por assinatura, responde com um array de eventos e o novo offset. Array vazio é uma resposta normal, não um erro.
  2. Proxy: configuração padrão, mas proxy_read_timeout não menor que o timeout do servidor mais dez segundos de folga. A bufferização pode ficar ativada — a resposta é curta e íntegra.
  3. Cliente: loop com tratamento de três desfechos — dados, resposta vazia, erro. Pool de conexões unificado, keep-alive, timeout do cliente maior que o do servidor.
  4. Monitoramento: proporção de respostas vazias, tempo médio de espera, frequência de 5xx e timeouts do cliente.

Quando o long-polling perde

Com alta frequência de eventos, o overhead de cabeçalhos e do ciclo requisição-resposta se torna perceptível. Com milhares de clientes, o servidor precisa manter milhares de requisições em espera — sem uma stack assíncrona não dá. E, claro, o long-polling é desconfortável para o streaming de uma única resposta longa, na qual se precisa de uma sequência de fragmentos de uma mesma entidade. Tokens de um modelo de linguagem via long-polling são teoricamente possíveis, mas na prática desajeitados.

Método 4: consumir respostas em streaming através de um proxy de saída

Particularidades do cenário

Até agora olhamos pelos olhos do dono do servidor. Agora vamos virar o quadro: você é o cliente, acessa a API de streaming de terceiros através de um servidor proxy, e só o lado do cliente depende de você. Tarefas típicas: coletar dados de APIs em streaming através de um pool de endereços, trabalhar com streaming de LLM em scripts de automação, distribuir a carga da API por IPs diferentes, acompanhar eventos de plataformas em tempo real, testar seu próprio serviço a partir de redes distintas.

Aqui, três coisas importam. O próprio proxy precisa passar respostas chunked de forma transparente. A biblioteca cliente precisa ler o stream conforme ele chega. E você precisa conseguir distinguir um problema do proxy de um problema do servidor de destino.

Testando o proxy quanto à transparência de stream

  1. Pegue um endpoint comprovadamente de streaming — um serviço público de testes que entrega linhas com atraso, ou um endpoint próprio com cronograma conhecido de chunks.
  2. Execute a requisição diretamente e via proxy com curl usando a flag -N (desliga a bufferização da própria saída do curl) e a flag --trace-time para marcas de tempo. Compare os momentos de chegada dos fragmentos.
  3. Se via proxy todos os fragmentos chegam de uma vez no final — o proxy bufferiza totalmente. Se chegam em blocos de alguns kilobytes — parcialmente. Se coincidem com a requisição direta — é transparente.
  4. Teste um stream longo (5-10 minutos) com heartbeat. Uma queda após um tempo fixo revela o idle timeout do proxy.
  5. Teste HTTPS. Via proxy com método CONNECT, cria-se um túnel, e o proxy não interpreta o HTTP interno — bufferização no nível HTTP não pode existir, só atrasos de TCP. É uma das razões pelas quais APIs em streaming via túnel CONNECT costumam funcionar com mais regularidade do que via proxy HTTP comum, que interpreta requisições.

Nuance sobre proxies móveis: a rede celular em si adiciona jitter, e o NAT das operadoras fecha agressivamente conexões inativas. Para streams longos via proxy móvel, heartbeat a cada 15-20 segundos é necessidade. A rotação de IP por agendamento deve considerar streams abertos: trocar o endereço no meio de uma conexão SSE garante que ela vai cair. Sincronize a rotação com o ciclo de vida dos streams — fechou o stream, trocou o endereço, abriu um novo com cursor.

Bibliotecas cliente: o que ativar

  • Python, requests: stream=True na chamada, depois iter_lines ou iter_content com chunk_size pequeno. Defina o timeout como uma tupla (connect, read), onde read é o tempo permitido entre chunks, não o tempo total da resposta.
  • Python, httpx: client.stream e aiter_lines para código assíncrono; para SSE, wrappers especializados que parseiam o formato de eventos.
  • Python, aiohttp: response.content.iter_any entrega dados exatamente como chegaram do socket, sem reempacotamento — ideal para medir intervalos reais.
  • Node.js: fetch com leitura de response.body como ReadableStream; para SSE, bibliotecas de parsing do formato.
  • Go: http.Client comum, leitura de resp.Body via bufio.Scanner com buffer grande o suficiente para eventos extensos.

Em todos os casos: não chame métodos que leem o corpo inteiro — text, json, read sem argumentos. Caso contrário, o cliente vai esperar o fechamento da conexão e você vai culpar o proxy por uma bufferização que não existe.

Protocolo de diagnóstico "três pontos"

Quando o stream se comporta de forma estranha, meça o tempo até o primeiro byte e a distribuição dos intervalos entre chunks em três configurações: diretamente ao servidor a partir da mesma máquina; via proxy ao servidor; via proxy a um endpoint de streaming de referência. A comparação localiza o problema de forma inequívoca. Via proxy ao endpoint de referência vai bem, mas ao servidor de destino vai mal — a culpa é da infraestrutura do servidor de destino. Ao endpoint de referência vai mal — a culpa é do proxy. Diretamente também vai mal — a culpa é do seu código ou da rede. Esse protocolo leva dez minutos e economiza dias de discussão.

Erros comuns ao trabalhar com streams via proxy

  1. Desligaram o proxy_buffering, esqueceram o gzip. O erro mais frequente. O stream formalmente não é bufferizado, mas a compressão acumula dados até o tamanho da janela. Sintoma: trancos de vários kilobytes.
  2. Deixaram proxy_http_version 1.0. Por padrão, o nginx fala com o backend por HTTP/1.0, onde chunked não existe, e é forçado a esperar o fechamento da conexão. Sintoma: a resposta inteira chega no final.
  3. Não enviam heartbeat. O stream vive exatamente até o primeiro idle timeout da cadeia — 60 segundos no nginx, 15 no Envoy por rota, alguns minutos no NAT. Sintoma: quedas em intervalos regulares.
  4. Timeout do long-polling maior que o timeout do proxy. O cliente recebe 504 em vez de resposta vazia, o monitoramento fica vermelho e os eventos podem duplicar.
  5. Confiam em uma configuração global do proxy. Ao migrar para um novo ambiente ou trocar de CDN, o streaming silenciosamente quebra. A solução é X-Accel-Buffering e no-transform no nível da resposta: o comportamento é definido pela aplicação, não pelo administrador do proxy.
  6. Sem Last-Event-ID e sem cursores. Qualquer queda é perda de dados. Via proxy, as quedas acontecem sensivelmente com mais frequência do que diretamente.
  7. Leem o corpo inteiro no cliente. O stream=True foi esquecido, o cliente espera o término, e o desenvolvedor culpa o proxy.
  8. Rotação de IP durante um stream aberto. A conexão cai, não há reconexão, os dados se perdem.
  9. Testam em respostas curtas. O buffer não enche, tudo parece ótimo. Em produção, em respostas longas, começa a gravação em arquivo temporário e as latências disparam.
  10. Misturam rotas de streaming e comuns em um mesmo location. Ou quebram o streaming, ou perdem compressão e bufferização para respostas comuns, o que prejudica a performance de toda a API.
  11. Ignoram a queda da conexão do cliente. Via proxy, o servidor descobre a queda tardiamente e continua a geração cara. Para inferência de LLM, isso é dinheiro direto.
  12. Usam chunked onde long-polling seria o caso. Através de um gateway corporativo ou API gateway em nuvem com limite de resposta, o stream não passa, mas o long-polling passa sem problemas.

Ferramentas e recursos para configuração e diagnóstico

Proxies reversos e balanceadores

  • nginx — referência em flexibilidade. Diretivas-chave: proxy_buffering, proxy_http_version, proxy_read_timeout, gzip, suporte ao cabeçalho X-Accel-Buffering.
  • HAProxy — bufferização mínima de fábrica. Atenção a timeout server, timeout tunnel e compressão.
  • Envoy — faz streaming por padrão. Críticos são o route timeout e o stream_idle_timeout.
  • Caddy — não bufferiza por padrão; flush_interval com valor -1 define flush imediato explicitamente.
  • Traefik — repassa streams de forma transparente; timeouts são configurados no nível dos entrypoints.

Diagnóstico

  • curl com as flags -N, -v e --trace-time mostra os momentos de chegada de cada fragmento. O parâmetro -w com as variáveis time_starttransfer e time_total dá o tempo do primeiro byte e o tempo total.
  • tcpdump e Wireshark — para verificar se os bytes saem com atraso no nível de rede ou se ficam retidos mais acima.
  • mitmproxy — visualização de streams preservando a estrutura dos chunks. Ative obrigatoriamente o modo de streaming, senão ele próprio vira ponto de bufferização.
  • Ferramentas de desenvolvedor do navegador — a aba EventStream para SSE mostra cada evento com marca de tempo.

Endpoints de teste e bibliotecas

Serviços públicos para testar HTTP têm endpoints que entregam um número definido de linhas com atraso — são ideais para verificar a transparência do proxy. Um servidor mínimo próprio em qualquer linguagem, entregando um chunk por segundo com marca de tempo, é ainda melhor: você controla os dois lados. Para SSE no servidor, praticamente qualquer framework assíncrono tem uma classe de resposta pronta para text/event-stream. Para SSE no cliente fora do navegador, existem parsers do formato para Python, Node.js e Go. Para long-polling, bibliotecas especiais não são necessárias — basta um cliente HTTP com pool de conexões.

Monitoramento

Métricas que vale coletar: tempo até o primeiro byte do corpo; distribuição dos intervalos entre chunks nos percentis 50, 95 e 99; duração de vida dos streams e motivo do fechamento; número de streams ativos no proxy e no backend; proporção de reconexões com Last-Event-ID. Um salto súbito no intervalo entre chunks acompanhado de aumento de volume é sinal claro de bufferização ativada.

Casos e resultados: como isso se parece em projetos reais

Caso 1. Streaming de LLM via nginx: de 11 segundos para 310 milissegundos

A equipe implantou um chat baseado em modelo de linguagem. Localmente os tokens apareciam suavemente. Após o deploy atrás do nginx, os usuários viam uma tela em branco por 8-12 segundos e depois a resposta inteira de uma vez. O diagnóstico pelo protocolo "três pontos" mostrou: diretamente na aplicação o primeiro token chegava em 280 milissegundos; via nginx, em 11 segundos. As causas eram clássicas: proxy_buffering on e proxy_http_version 1.0 por padrão. Depois de adicionar proxy_buffering off, proxy_http_version 1.1, gzip off para a rota e o cabeçalho X-Accel-Buffering: no na resposta da aplicação, o tempo até o primeiro token via proxy ficou em 310 milissegundos. Um achado paralelo: ao fechar a aba, a inferência continuava até o fim da resposta. Após implementar heartbeat com verificação de erro de escrita, o consumo de tempo de GPU em requisições abandonadas caiu cerca de um quarto.

Caso 2. Dashboard em SSE e redes móveis

Um serviço de monitoramento entregava eventos via SSE. Na internet cabeada tudo funcionava, mas em dispositivos móveis os streams caíam a cada 2-4 minutos sem erros no servidor. A causa eram os timeouts de NAT das operadoras em conexões inativas. A solução: comentário de heartbeat a cada 20 segundos mais fechamento forçado do stream pelo servidor a cada 10 minutos, com Last-Event-ID correto. As reclamações de "dashboard travado" caíram praticamente a zero, a duração média de stream contínuo aumentou de 3 para 10 minutos (já limitada por fechamento intencional), e não se registrou perda de eventos na reconexão.

Caso 3. Scraping de API em streaming via pool de proxies móveis

A equipe coletava eventos de uma plataforma que entrega dados em stream NDJSON, através de um pool de proxies móveis. Havia dois problemas: parte dos streams vinha em trancos de 8 kilobytes, e parte caía na rotação de endereço. Os testes mostraram que, para requisições não criptografadas, o proxy interpretava o HTTP e bufferizava as respostas, enquanto via túnel CONNECT para endpoint HTTPS passava o stream de forma transparente. A migração para HTTPS resolveu o primeiro problema por completo. O segundo foi fechado com sincronização: a rotação de IP só ocorre após o fechamento correto do stream, e a reconexão acontece com o cursor do último evento. A completude dos dados coletados subiu de cerca de 91 para 99,7 por cento.

Caso 4. Bot em long-polling via gateway restrito

O desenvolvedor mantinha um bot em uma infraestrutura onde as requisições de saída passavam por um gateway corporativo com limite de resposta de 30 segundos. Inicialmente usava timeout de espera de 60 segundos — metade das requisições terminava com erro do gateway, e as atualizações duplicavam. Após reduzir o timeout para 25 segundos e adicionar jitter exponencial em caso de erro, a taxa de erro caiu de 48 para menos de 0,5 por cento. A latência média de entrega dos eventos não mudou — ela é determinada pelo momento do evento, não pela duração da espera.

Caso 5. Migração para HTTP/2 no SSE

Um aplicativo web abria de 3 a 4 streams SSE por aba. Com várias abas abertas, o navegador esgotava o limite de seis conexões, e as requisições comuns ficavam na fila atrás dos streams. Habilitar HTTP/2 no proxy de front-end levou todos os streams para uma única conexão. O tempo de carregamento da página com cinco abas abertas caiu de 9 para 1,5 segundo. Achado paralelo: após a migração foi preciso aumentar o stream_idle_timeout, já que as configurações anteriores eram pensadas para HTTP/1.1.

FAQ: perguntas profundas sobre respostas em streaming via proxy

Em que o HTTP em streaming difere fundamentalmente do WebSocket do ponto de vista do proxy?

O WebSocket exige um upgrade de protocolo: o proxy precisa reconhecer os cabeçalhos Upgrade e Connection, entrar em modo túnel e parar de interpretar HTTP. O HTTP em streaming não exige nada — é uma resposta comum que demora a terminar. O paradoxo é que o WebSocket via proxy ou funciona, ou não funciona de jeito nenhum, enquanto o HTTP em streaming sempre "funciona", mas pode funcionar mal: os dados chegam, só que com atraso. Por isso problemas com streams são mais difíceis de perceber e diagnosticar.

Por que o X-Accel-Buffering: no nem sempre ajuda?

O cabeçalho é entendido pelo nginx e proxies compatíveis. CDNs, gateways de nuvem ou proxies de outro tipo vão ignorá-lo. Além disso, X-Accel-Buffering não afeta o gzip — a compressão precisa ser desativada separadamente. E se entre a aplicação e o nginx houver uma camada que remove cabeçalhos não padrão, ele não chega ao nginx.

É possível comprimir uma resposta em streaming?

Tecnicamente sim: o gzip suporta flush síncrono, e o servidor pode comprimir cada chunk com entrega imediata. A taxa de compressão cai, porque o dicionário não tem tempo de se encher. Na prática, para SSE e tokens de LLM a compressão é desativada: economizar alguns por cento de tráfego não compensa o risco de atrasos. Para streams de objetos JSON grandes, a compressão com flush pode trazer ganho considerável.

Como escolher entre SSE e long-polling?

Se o cliente é o navegador, os eventos acontecem com mais frequência que a cada alguns segundos e você controla pelo menos o proxy reverso — SSE. Se há na cadeia nós não controlados com limites de tempo de resposta, os eventos são raros ou você precisa do máximo de compatibilidade — long-polling. Sistemas maduros implementam as duas opções e alternam automaticamente pelo resultado da primeira conexão.

O HTTP/3 influencia no problema de bufferização?

O HTTP/3 roda sobre QUIC e elimina o bloqueio de fila no nível de transporte, mas a bufferização está acima — na lógica do proxy. Um proxy com HTTP/3 na entrada e HTTP/1.1 na saída bufferiza exatamente da mesma forma. O que realmente muda é o comportamento em redes móveis: o QUIC lida melhor com troca de rede e perdas, então streams via HTTP/3 caem menos do lado do cliente.

Como saber se quem bufferiza é o proxy de saída e não o servidor de destino?

Método dos "três pontos": a mesma requisição diretamente, via proxy e via proxy a um endpoint de streaming de referência. Adicionalmente, tente HTTPS via CONNECT — se o stream ficar regular, o proxy estava interpretando e bufferizando o HTTP não criptografado.

Qual intervalo de heartbeat escolher?

Menor que o menor timeout da cadeia, com margem de duas vezes. Para infraestrutura típica — 15-25 segundos, para redes móveis mais perto de 15. Heartbeat frequente demais gera tráfego extra e carga em milhares de conexões; raro demais, quedas.

O que fazer se o stream precisar durar horas?

Não faça isso. Projete um fechamento forçado pelo servidor a cada 5-15 minutos, com cursor para retomada. Isso protege contra acúmulo de memória, vazamentos e timeouts invisíveis, e também simplifica o deploy: você reinicia os servidores sem se preocupar com conexões de horas.

Como o proxy afeta a detecção de desconexão do cliente?

Entre cliente e servidor agora existem duas conexões. Quando o cliente se desconecta, o proxy descobre na hora, mas só avisa o servidor na próxima tentativa de escrita ou por regras próprias. O servidor só percebe a queda ao escrever. Daí a prática de escritas regulares de heartbeat para detecção precoce da ruptura e interrupção de operações caras.

É necessária configuração especial de proxy móvel para streams?

Do lado do usuário, normalmente o proxy em si não é configurável. Mas é preciso: preferir HTTPS para túnel transparente; sincronizar a rotação de IP com o ciclo de vida dos streams; manter heartbeat a cada 15-20 segundos no máximo; usar keep-alive e pool de conexões; verificar cada pool quanto à transparência antes de ir para produção.

Conclusão: resumo e próximos passos

HTTP em streaming não é exotismo nem um protocolo à parte. É uma resposta comum que não tem pressa de fechar. É justamente por isso que é tão vulnerável a nós intermediários: o proxy não vê nada de especial e aplica regras pensadas para respostas curtas. A bufferização atrasa os dados, os timeouts cortam a conexão, a compressão mascara a bufferização — e tudo isso em oito pontos diferentes da cadeia.

Os três mecanismos — chunked, SSE e long-polling — resolvem a mesma tarefa com graus distintos de dependência da transparência do proxy. O chunked dá o máximo de controle ao custo de tratamento próprio no cliente. O SSE traz um modelo de eventos pronto e reconexão no navegador, mas exige atenção em cada nó. O long-polling passa por qualquer coisa, mas paga por isso com overhead de requisições frequentes. A escolha é definida por quatro perguntas: você controla a cadeia, quem é o cliente, qual a natureza dos dados e qual sua frequência.

O que fazer já hoje:

  1. Percorra o mapa dos oito pontos de bufferização da sua infraestrutura e marque quais você controla.
  2. Adicione às respostas das rotas de streaming os cabeçalhos X-Accel-Buffering: no e Cache-Control: no-cache, no-transform — independentemente da configuração atual do proxy.
  3. Verifique proxy_http_version, proxy_buffering, gzip e proxy_read_timeout no nginx ou seus equivalentes no seu proxy. Separe as rotas de streaming em blocos próprios.
  4. Implemente heartbeat a cada 25 segundos no máximo e fechamento forçado do stream a cada 5-15 minutos com cursor.
  5. Se você consome streams de terceiros via proxy — rode o protocolo "três pontos" em cada pool de endereços e migre as requisições de streaming para HTTPS.
  6. Configure monitoramento do tempo do primeiro byte e dos intervalos entre chunks. É a única forma de saber da bufferização antes dos usuários.

O proxy não é inimigo do stream. Bem configurado, ele adiciona ao stream resiliência, distribuição de carga e proteção do backend. A questão é apenas explicar a ele: esta resposta é especial, precisa ser repassada como chega. Agora você tem tudo para fazer essa explicação soar no idioma dele.