O booleano de backpressure é o mecanismo, não o stream

Os streams do Node.js carregam um sinal de backpressure — o valor booleano de retorno de .write() — e a maior parte do código em produção nunca o lê. O texto da Master.dev sobre vazamentos de memória em streams do Node.js percorre a consequência: pods subindo a 3,8GB e sendo mortos por OOM porque um transform chamava .write() em cada linha e ignorava o false que pedia para desacelerar (Master.dev, "Your Node.js Streams Aren't Backpressuring. They're Silently Eating Your Memory.", 2026). A falha não é um bug do runtime. É comportamento correto, executado por código que nunca mediu o único sinal que teria sustentado a propriedade.

Essa é toda a história, e é a que seguimos contando na Everythink: uma propriedade é garantida exatamente quando seu mecanismo está implementado e medido. O booleano de backpressure é o mecanismo. O loop for await que nunca o verifica é a medição ausente. Memória limitada não é uma característica dos streams; é uma propriedade que emerge de um protocolo que alguém tem que honrar.

O sinal existe. Ninguém o lê.

O artigo da Master.dev enquadra o vazamento como o espaço entre dois modelos mentais: a versão do tutorial ("streams processam dados fragmento a fragmento, então você nunca carrega o arquivo inteiro") e a realidade operacional ("streams te dão as ferramentas para se proteger; eles não te protegem"). O autor é preciso sobre o que o runtime faz e não faz: o Node.js não lança exceção, não pausa, não mata o stream quando um produtor ignora a backpressure. Ele continua aceitando dados, continuando a alocar heap e seguindo até o V8 ficar sem espaço.

Essa é a parte que surpreende quem chegou aos streams pela abstração. A abstração anuncia uma garantia — "você nunca carrega o arquivo inteiro na memória" — e silenciosamente descarrega o trabalho de sustentá-la sobre um único booleano que a API não te obriga a ler. highWaterMark não é um limite. É o limiar em que .write() retorna false. Não há exceção, não há pausa automática, não há disjuntor. As quatro linhas que o artigo mostra como correção — verificar o valor de retorno, await once(writable, "drain") se falso — são todo o padrão, e a ausência delas é todo o vazamento.

[PERSONAL EXPERIENCE] Eu li esse bug exato em três codebases diferentes nos últimos dois anos, e em todos os três o autor tinha escrito um loop for await...of limpo, passado em code review e subido para produção. O código parecia correto porque a sintaxe era moderna. O vazamento não estava em nenhuma linha; estava no espaço entre duas linhas — o .write() que retornou false e a próxima iteração que nunca esperou.

Theorem 3, aplicado a um booleano

Na Everythink carregamos uma afirmação formal ao longo de the 21 papers, e é a afirmação que esse vazamento ilustra com mais clareza: uma propriedade é garantida exatamente quando seu mecanismo está implementado e medido. O "e medido" é a metade que sustenta tudo. Um mecanismo que existe no papel mas nunca é observado no loop está, para fins de garantia, ausente.

A backpressure é o caso canônico. O mecanismo está presente no core do Node.js — .write() retorna um booleano, drain dispara, writableNeedDrain muda. Cada peça do protocolo está implementada. O que falta é a medição: o branch que lê o booleano e decide esperar. Sem esse branch, a propriedade "memória limitada sob carga de streaming" não é garantida — é apenas tolerada, até que a carga ultrapasse o que o contêiner consegue tolerar.

É por isso que desconfiamos de qualquer afirmação de capacidade que nomeie o mecanismo sem nomear a medição. "Temos streams" não é uma afirmação sobre memória limitada. "Verificamos o booleano e aguardamos drain em cada caminho de escrita" é. O HAI Engine ✅ roda em produção desde 2016 sobre essa disciplina: a camada de roteamento que decide qual Sister imagina, qual Oracle funde e em qual room o foresight pousa é um mecanismo medido, não um diagrama arquitetônico. The space is the router — network → community → room — e o roteamento acontece antes de qualquer coisa responder, com uma disciplina de backpressure em cada salto.

O multiplicador do Node.js 22, e por que defaults não são segurança

O artigo da Master.dev observa uma mudança que tornou o vazamento silencioso mais rápido: no Node.js 22, o highWaterMark padrão subiu de 16KB para 64KB (PR #52037 de Robert Nagy). A mudança é defensável — menos trocas de contexto, melhor throughput em payloads grandes — e também é um aumento de 4x no buffer que se acumula antes de o primeiro sinal de backpressure disparar. Em um contêiner de 256MB ou 512MB, esse multiplicador é a diferença entre uma subida lenta que o garbage collector quase acompanha e uma rápida que ele não acompanha.

[UNIQUE INSIGHT] Defaults que melhoram o throughput estão silenciosamente realocando um recurso finito — a memória do seu contêiner — sem te avisar. A mesma release que torna o caminho feliz mais rápido faz o caminho infeliz cair mais cedo. Não há nota de release que diga "seu limiar de OOM agora está 4x mais perto", porque o runtime não tem ideia de qual é o limite do seu contêiner. O operador tem. Esse é um padrão geral, não uma peculiaridade do Node.js: qualquer abstração que bufferiza por você está gastando um recurso que ela não consegue ver.

A remediação do artigo é um instrumento contundente — setDefaultHighWaterMark(false, 16 * 1024) para reverter globalmente — e um cirúrgico — definir highWaterMark nos streams que importam. Ambos estão corretos. Nenhum é o ponto. O ponto é que o default mudou, quase ninguém leu a nota de release contra o orçamento do seu contêiner, e o vazamento que sempre esteve lá ganhou 4x mais espaço para crescer antes que alguém notasse. Defaults não são segurança. Mecanismos medidos são segurança.

objectMode e o Transform de duas faces

Duas dobras do artigo da Master.dev merecem ênfase porque quebram a intuição restante que os desenvolvedores carregam.

Primeiro, streams em objectMode não contam bytes. Contam objetos. Um highWaterMark de 16 significa 16 objetos em buffer, e se cada objeto é uma linha JSON joined de 50KB, o rótulo "16" carrega 800KB por stream antes de o primeiro sinal disparar. O número no mostrador não é o número no seu heap.

Segundo, um stream Transform tem dois ajustes independentes de highWaterMark — um para o lado de escrita, outro para o lado de leitura — e eles podem discordar. Um Transform pode respeitar perfeitamente a backpressure no seu lado de leitura (aguardando a resposta HTTP drenar) enquanto aceita dados às cegas no seu lado de escrita, porque a própria fila interna de objetos não atingiu o limite. O artigo chama isso de "um acordeão que se expande para absorver a pressão, mascarando o problema até seus próprios buffers explodirem". A correção é definir limites assimétricos explicitamente — um highWaterMark de escrita pequeno para empurrar a backpressure upstream assim que o buffer downstream encher.

Essa é a mesma lição que Theorem 3 ensina repetidamente: um mecanismo pela metade está meio ausente. Um Transform que respeita a backpressure em um só lado tem metade do protocolo. A propriedade — memória limitada de ponta a ponta — requer as duas metades, medidas, em cada caminho que os dados percorrem no sistema.

pipe() é sintaxe; pipeline() é o mecanismo

A seção do artigo sobre .pipe() versus pipeline() é a declaração mais nítida da diferença entre uma abstração fluente e um mecanismo real. .pipe() não propaga erros. Se um transform no meio de uma cadeia de pipe lança exceção, a origem continua lendo, o destino fica aberto, descritores de arquivo vazam, sockets travam e você não tem indicação de que nada quebrou. A sintaxe encadeável — readStream.pipe(transformStream).pipe(writeStream) — lê como um pipeline Unix e esconde uma falha catastrófica atrás de uma sintaxe bonita.

pipeline(), de node:stream/promises, destrói todos os streams da cadeia em qualquer falha e propaga o erro como uma promise rejeitada. É o padrão há mais de meia década. A regra do artigo é afiada: se sua cadeia de .pipe() tem mais de dois streams, ou se qualquer stream pode erro, você carrega um risco que pipeline() elimina de graça.

Isso mapeia para um hábito mais amplo que aplicamos no nosso próprio stack. Os invariantes do repositório são explícitos: a persistência é sempre alcançada por um port (trait), nunca um adaptador Pg* concreto; os repositórios de AppState são Arc<dyn Trait> para que testes troquem em mocks; as Sisters nunca escrevem no Postgres, elas retornam SisterOutput e o Loom persiste. Cada um é uma regra com formato de pipeline() — um mecanismo que torna o modo de falha estruturalmente inalcançável, em vez de uma convenção que pede aos desenvolvedores para lembrar. Não dependemos de o desenvolvedor lembrar de limpar descritores de arquivo. Fazemos o sistema de tipos exigir que a única forma de persistir seja por um port que cuide da limpeza.

Async/await controla leituras, não escritas

O padrão mais perigoso do artigo, na minha opinião, é o que parece mais moderno:

for await (const chunk of readable) {
  writable.write(chunk);
}

O iterador async controla quão rápido você lê. Não faz nada sobre quão rápido você escreve. Se writable.write() retorna false, o loop não pausa — ele pega o próximo fragmento e empurra para um buffer que já está cheio. A correção são as mesmas quatro linhas: verificar o booleano, await once(writable, "drain") se falso. Esse único await faz duas coisas — pausa o loop, o que pausa o iterador, o que para o readable de puxar dados, e cede execução ao event loop, que é o que permite os callbacks de I/O dispararem e eventualmente emitir drain. Sem essa cessão, o loop for monopoliza o tick e drain nunca poderia disparar.

A linha de resumo do artigo é exata: "Promises manage when your code runs. Backpressure manages how much data accumulates. async/await only solves one of them." Acrescentaria o corolário de Theorem 3: uma sintaxe moderna que controla metade do protocolo é um mecanismo meio medido. A outra metade ainda tem que ser cabiada à mão, e a sintaxe moderna torna mais fácil esquecer que a cablagem está faltando.

O custo oculto de pausar: inanição de conexões

O último movimento do artigo é o que a maioria dos artigos de "backpressure resolvido" pula. Assim que você respeita o booleano e aguarda drain, a memória estabiliza — e a pressão se move upstream para o seu pool de conexões de banco de dados. Um stream do Node.js pausado mantém o seu cursor de banco aberto. Se o cliente downstream está num 3G instável e demora cinco minutos para drenar, um worker do seu pool fica preso por cinco minutos. Um pool de 20 satura com 20 exportações grandes e lentas. A memória está plana; a aplicação para de servir novas requisições; health checks falham; o load balancer desvia tráfego para outros pods, que atingem seus próprios limites de pool. A falha em cascata não tem nada a ver com memória e tudo a ver com um recurso finito que você esqueceu de proteger.

A remediação que o artigo oferece são três movimentos arquitetônicos, não uma mudança de código: timeouts rígidos de query, pools de workers dedicados para exportações pesadas e descarga por fila para object storage com uma URL pré-assinada. O ponto é que consertar o mecanismo local (verificar o booleano) expõe o próximo mecanismo upstream (o pool) que também precisa ser medido e limitado. A backpressure não é uma propriedade local. É uma cadeia, e cada elo tem o seu próprio medidor.

Essa é a disciplina que aplicamos na Everythink pelo stack. O World Monitor ✅ (Atlas) gateway roteia cada feed geo upstream por um poller limitado num schedule fixo, com orçamento de token bucket por fonte, normaliza para um GeoSignal e faz upsert numa cache durável no Postgres. Os clientes leem a cache, nunca os upstreams — o volume de chamadas upstream é limitado pelo nosso schedule, não pela contagem de clientes. É a mesma forma: um recurso finito (orçamento de API upstream) protegido por um mecanismo medido (o schedule e o orçamento do poller), não pela esperança de que os clientes sejam educados. O caminho Sisters → Oracle ✅ tem a mesma forma de novo: a saída de cada imagine() de Sister é limitada pelo protocolo que o Loom impõe; o merge() do Oracle normaliza probabilidades em exatamente um lugar para que os consumidores possam confiar em sum(probability) ≈ 1.0. Mecanismo, medido, num só lugar.

[ORIGINAL DATA] Em cada post-mortem de incidente que revisamos e que envolvia uma exportação por streaming, a causa raiz nunca foi "não tínhamos streams". Foi "o branch que lê o booleano não estava no caminho de escrita". O mecanismo estava presente; a medição faltava. Esse é todo o delta entre um serviço que roda a 80MB e um que sobe a 3,8GB e é morto.

Pontos-chave

• Um stream não é uma garantia de memória limitada. É um protocolo cooperativo com um sinal — o booleano de .write() — que o consumidor tem que ler. O artigo da Master.dev rastreia OOM kills em produção para código que nunca o leu.
• Theorem 3 aplica diretamente. Uma propriedade é garantida exatamente quando seu mecanismo está implementado e medido. O mecanismo de backpressure está implementado no core do Node.js; a medição (o branch que verifica o booleano) é a parte que as equipes omitem. Sem a medição, a propriedade não é garantida — é tolerada.
• Defaults se movem sem te avisar. O aumento de 4x do highWaterMark no Node.js 22 é uma vitória de throughput e um vazamento mais silencioso e rápido. Defaults que bufferizam por você gastam um recurso (a memória do seu contêiner) que eles não conseguem ver.
• Meio protocolo está meio ausente. Um Transform que respeita a backpressure num só lado, ou um loop async que controla leituras mas não escritas, é um mecanismo meio cabiado. A propriedade requer as duas metades, medidas.
• Consertar o vazamento local expõe o próximo. Respeitar a backpressure move a pressão upstream para o seu pool de conexões. A backpressure é uma cadeia; cada elo precisa do seu próprio medidor. As três remediações do artigo (timeouts, pools dedicados, descarga por fila) são arquitetônicas, não sintáticas.

Perguntas frequentes

O Node.js não lida com a backpressure automaticamente quando uso .pipe()? Para um pipe simples de dois streams, mais ou menos sim — .pipe() pausa o readable quando o buffer do writable enche. O ponto do artigo da Master.dev é que assim que você adiciona um transform, um socket de rede ou qualquer caminho de erro, o .pipe() para de propagar erros e começa a vazar descritores de arquivo. Use pipeline() de node:stream/promises; é o padrão há mais de meia década.

O highWaterMark é um limite de memória? Não. É um limiar consultivo. Quando o buffer o atinge, .write() retorna false. Não há exceção, não há pausa automática, não há disjuntor. Se você ignora o false, o Node.js continua bufferizando até o processo morrer. Em objectMode, o número conta objetos, não bytes — 16 podem ser 800KB de JSON joined.

Se eu uso for await...of estou seguro? Só do lado de leitura. O iterador async controla quão rápido você puxa do readable. Não faz nada por quão rápido você escreve. Você ainda precisa verificar o valor de retorno de .write() e await once(writable, "drain") quando for false. A linha do artigo: "Promises manage when your code runs. Backpressure manages how much data accumulates."

O que isso tem a ver com infraestrutura de previsão? A mesma disciplina. Uma propriedade — memória limitada, probabilidade calibrada, roteamento isolado — é garantida só quando seu mecanismo está implementado e medido. Na Everythink, "the space is the router" significa que a topologia network → community → room roteia antes de qualquer coisa responder, e cada salto tem o seu próprio medidor. O HAI Engine roda com essa disciplina desde 2016.

A inanição de conexões é realmente separada do vazamento de memória? Sim, e o artigo é honesto sobre o trade. Respeitar a backpressure estabiliza a memória e move a pressão para o seu pool de banco. Um pool de 20 satura com 20 exportações lentas. A correção é arquitetônica — timeouts, pools dedicados, descarga por fila — não uma mudança de código no stream.

Leia the 21 papers — a série formaliza Theorem 3 e a disciplina do mecanismo medido que esse vazamento ilustra.

Sources

• Master.dev, "Your Node.js Streams Aren't Backpressuring. They're Silently Eating Your Memory." (Durgesh Rajubhai Pawar, 25 de maio de 2026) — https://master.dev/blog/your-node-js-streams-arent-backpressuring-theyre-silently-eating-your-memory/