Limites de tamanho decodificado protegem um agente contra APIs compactadas?

Uma resposta compactada não é pequena só porque chegou pequena. Ela só permanece pequena até que seu cliente a decodifique, analise, armazene, registre em log e talvez a entregue a um agente que a trate como evidência. Se você impõe um limite apenas aos bytes recebidos pela rede, está medindo a parte menos interessante da transação.

Já vi equipes adicionar um limite HTTP de 5 MB que parecia sensato, comemorar o teste e depois descobrir que poucos kilobytes de dados repetidos e compactados ainda podiam produzir uma resposta grande o bastante para travar um processo ou contaminar uma execução de agente. Ninguém precisou de um ataque sofisticado. Um endpoint devolveu um relatório com um campo repetido muito mais vezes do que o esperado, a compactação fez seu trabalho muito bem, e o cliente fez o que não deveria: reuniu o corpo decodificado antes de decidir se o queria.

Os limites de tamanho decodificado precisam ficar no fluxo decodificado, antes que um parser, log, cache ou contexto de agente consuma o corpo. Mantenha um limite separado para bytes na rede, porque ele impede transferências lentas ou inesperadamente grandes. Os dois limites tratam falhas diferentes. Confundi-los transforma uma verificação defensiva em falsa sensação de segurança.

O tamanho na rede conta apenas parte da história

Content-Length normalmente descreve o corpo da mensagem HTTP conforme ele é transferido. Quando a resposta tem Content-Encoding: gzip ou Content-Encoding: br, essa contagem descreve bytes compactados. Um corpo de 40 KB pode se expandir para dezenas ou centenas de megabytes depois da decodificação se a entrada tiver repetição suficiente. A proporção exata não importa. Basta uma proporção que ultrapasse seu orçamento de alocação ou de contexto para causar problemas.

A RFC 9110 trata a codificação de conteúdo como uma transformação aplicada a uma representação. Essa redação importa. A representação que sua aplicação usa é a forma decodificada, enquanto o transporte leva uma forma codificada. Um cliente que baseia o limite da aplicação na forma de transporte colocou a proteção no lado errado da transformação.

Transfer-Encoding complica ainda mais o cenário. A transferência em blocos não oferece um Content-Length final útil em que o cliente possa confiar, e uma resposta HTTP/2 ou HTTP/3 não usa transferência em blocos da mesma maneira. Mesmo com um cabeçalho presente, um servidor pode enviar um valor errado. Use o cabeçalho como indício para rejeição antecipada, nunca como prova de que o corpo é seguro.

Há três quantidades que vale registrar para uma resposta: bytes lidos da rede, bytes decodificados produzidos e bytes mantidos para quem chama. Às vezes elas serão iguais. Muitas vezes não. Uma resposta JSON pode ser decodificada em 12 MB, ocupar muito mais que 12 MB após a análise e então precisar ser reduzida a 64 KB antes que um agente possa usá-la com segurança.

Essa distinção também evita uma discussão comum sobre uma única configuração de «tamanho máximo da resposta». Uma pessoa da engenharia quer dizer bytes do socket. Outra quer dizer bytes decodificados. Uma terceira quer dizer o texto inserido no resultado de uma ferramenta. Dê a cada limite seu próprio nome e imponha cada um na fronteira que ele descreve.

Decodifique antes de qualquer armazenamento sem limite

A ordem segura é simples: limite o fluxo bruto da resposta, selecione e inicialize o decodificador, limite o fluxo decodificado e só então analise ou mantenha o que quem chama precisa. Não use um método conveniente que lê toda a resposta decodificada em uma fatia de bytes para conferir seu tamanho depois. Nesse ponto, o decodificador já gastou a memória que você queria preservar.

Para uma resposta gzip em Go, o limitador decodificado deve envolver o leitor gzip. Este auxiliar lê deliberadamente um byte além do permitido. Sem esse byte extra, uma resposta cujo tamanho real é exatamente o limite não se distingue de uma resposta maior que foi cortada no limite.

var ErrDecodedBodyTooLarge = errors.New("decoded response exceeds limit")

func readGzipBody(r io.Reader, limit int64) ([]byte, error) {
    zr, err := gzip.NewReader(r)
    if err != nil {
        return nil, err
    }
    defer zr.Close()

    bounded := &io.LimitedReader{R: zr, N: limit + 1}
    body, err := io.ReadAll(bounded)
    if err != nil {
        return nil, err
    }
    if int64(len(body)) > limit {
        return nil, ErrDecodedBodyTooLarge
    }
    return body, nil
}

Aplique também um limite bruto antes de gzip.NewReader. Esse limite não substitui o limite decodificado. Ele impede que um par envie um fluxo compactado enorme e limita a quantidade de trabalho que o cliente aceita antes que o decodificador tenha entrada suficiente para avançar.

Não trunque silenciosamente e prossiga. Um documento JSON truncado em geral falha na análise, mas um texto truncado ou protocolo baseado em linhas pode parecer plausível. Se mantiver uma prévia para diagnóstico, identifique-a como prévia em um campo que não possa ser confundido com o corpo completo. A ação em si deve falhar porque o cliente não obteve uma resposta completa e permitida.

Um decodificador pode detectar uma soma de verificação corrompida apenas ao chegar ao fim do fluxo. Quando o limite decodificado dispara, pare de ler e rejeite a resposta. Não é necessário terminar de verificar um corpo grande demais que você já decidiu descartar. Quando a resposta fica abaixo do limite, leia até EOF e deixe o decodificador informar truncamento ou corrupção normalmente.

Uma resposta pode esgotar o contexto antes de esgotar a memória

A proteção de memória é necessária, mas ferramentas de agentes têm outro orçamento: a quantidade de texto de resultado que pode entrar com segurança na conversa do agente. Uma resposta JSON de 2 MB pode ser inofensiva para um processo desktop e ainda ser um péssimo resultado de ferramenta. Ela pode expulsar a tarefa do contexto, levar o agente a perseguir registros irrelevantes ou obrigar o modelo a raciocinar sobre uma representação parcial que parece completa.

Não use o orçamento de contexto como motivo para aumentar o limite do corpo decodificado. Eles protegem operações diferentes. O limite decodificado permite que o transporte e o parser terminem com segurança. O limite de apresentação controla o que o agente recebe após a decodificação bem-sucedida e, quando aplicável, a análise estruturada.

Para dados estruturados, escolha uma projeção em vez de cortar bytes arbitrários. Se um endpoint devolve uma lista de registros, mantenha uma quantidade limitada de registros e uma quantidade limitada de texto por campo. Inclua a contagem total de registros apenas se o parser a obteve sem manter a lista inteira. Diga que o resultado foi reduzido e informe a regra de seleção, como «os primeiros 50 registros ordenados por data e hora». Assim, o resultado pode ser auditado e o agente não tratará um fragmento como uma busca completa.

Para texto simples, preserve linhas completas quando possível. Uma prévia de log que termina no meio de uma linha é menos útil e pode ocultar o campo que a explica. Defina um orçamento de bytes, leia linha a linha com um limite de comprimento de linha e informe tanto a quantidade mantida quanto o motivo de ter omitido conteúdo adicional. Um leitor de linhas sem seu próprio limite de tamanho de token apenas desloca o problema de alocação para outro auxiliar.

É aqui que muita ideia de «mas o modelo pode resumir isso» desmorona. O modelo pode resumir dados que você selecionou deliberadamente. Ele não torna seguro um transporte sem limite, nem deveria decidir quanta saída remota bruta seu processo aloca antes de você verificá-la.

A codificação de conteúdo precisa ser explícita no contrato do cliente

Trate Content-Encoding como uma entrada que seleciona um decodificador, não como enfeite em torno de um fluxo de bytes que seria idêntico. Aceite apenas as codificações que seu cliente implementa e rejeite claramente valores desconhecidos. Se um serviço devolve gzip, use o caminho gzip. Se devolve br, use um decodificador Brotli envolvido pelo mesmo limitador de bytes decodificados. Se não devolve codificação de conteúdo, envolva o corpo bruto nesse limitador decodificado, porque nesse caso os bytes brutos também são bytes decodificados.

Não aceite várias codificações de conteúdo sem cuidado. HTTP permite uma lista de codificações, e as transformações listadas têm uma ordem. Dar suporte a gzip, br significa que você deve decodificar em ordem inversa, com uma proteção de tamanho após cada etapa de expansão. Um único limite final é mais fraco do que parece, porque uma etapa intermediária pode crescer muito antes que a etapa final a reduza. Se suas integrações não precisam de codificações empilhadas, rejeite-as até ter testes e uma implementação deliberada.

A descompressão automática merece inspeção. Muitas bibliotecas HTTP adicionam Accept-Encoding, decodificam gzip e ocultam essa mudança do código da aplicação. Isso é conveniente para solicitações comuns, mas pode deixar o código contando bytes na camada errada. Descubra se o corpo da resposta entrega bytes da rede ou bytes decodificados, se a biblioteca remove Content-Encoding e se ela expõe contagens de bytes compactados. Escreva um teste que comprove o comportamento para a configuração exata do seu cliente.

Brotli merece o mesmo tratamento que gzip. É tentador escrever um teste gzip porque todo ambiente tem um comando gzip e supor que o trabalho está pronto. Um decodificador diferente envolve tratamento de erros, comportamento de buffering e suporte diferentes nas versões das dependências. O limite precisa envolver o leitor devolvido por cada decodificador, não ficar em um auxiliar chamado apenas pela rota gzip.

Um servidor também pode enviar uma codificação declarada com corpo inválido. Preserve isso como erro de decodificação, distinto de uma resposta decodificada grande demais. Operadores precisam saber se o lado remoto enviou dados ruins, se o orçamento configurado era baixo demais ou se o cliente não tem decodificador para uma codificação declarada.

Teste a expansão com arquivos que você pode inspecionar

Um bom arquivo de teste começa com conteúdo decodificado que você reconhece e consegue medir. Bytes repetidos criam um caso de expansão evidente. Os comandos a seguir criam um corpo de texto de 32 MiB e depois fazem versões gzip e Brotli quando o comando Brotli está instalado.

python3 -c 'open("repeat.txt", "wb").write(b"A" * (32 * 1024 * 1024))'
wc -c repeat.txt
gzip -9 -c repeat.txt > repeat.txt.gz
brotli -f repeat.txt -o repeat.txt.br
wc -c repeat.txt.gz repeat.txt.br

A primeira saída de wc deve ter o formato 33554432 repeat.txt. Os arquivos compactados devem ser muito menores que a fonte porque a entrada repete um byte. Não faça um teste exigir um tamanho compactado específico. Versões e configurações de compactação podem mudá-lo. Verifique o comprimento decodificado, o resultado no cliente e que o cliente não manteve nenhum corpo completo depois de rejeitá-lo.

Crie casos de limite a partir da mesma fonte: um corpo decodificado um byte abaixo do limite configurado, exatamente no limite e um byte acima dele. Execute cada caso por um handler HTTP local que defina Content-Encoding corretamente. Um teste de decodificador de arquivo é útil, mas não detecta uma biblioteca cliente que faça descompressão automática antes de seu código de limite ser executado.

Use uma segunda família de arquivos de teste com estrutura realista. Gere JSON delimitado por linhas, em que cada registro tenha um campo de carga repetido, e então sirva-o sob gzip e Brotli. Isso detecta código que lida corretamente com uma fatia de bytes, mas deixa um parser JSON ou scanner de linhas criar um array sem limite após a decodificação. Inclua um registro maior que seu limite de campo ou linha, pois invasores não precisam repetir linhas curtas para fazer um parser alocar.

Mantenha os arquivos de teste versionados apenas se suas formas compactadas forem pequenas e se a fonte puder ser gerada durante os testes. Um script gerador que produz um comprimento decodificado conhecido é mais fácil de revisar que um blob binário misterioso. Registre o tamanho decodificado esperado no nome do teste, não apenas em um comentário que ninguém vê quando um limite falha.

A falha geralmente começa com um método prático

Considere um agente que chama uma API para obter dados de issues. Normalmente, o endpoint devolve uma página JSON pequena. O cliente envia Accept-Encoding: gzip, recebe uma resposta cujo Content-Length é 18 KB e registra o cabeçalho como prova de que o resultado é modesto. Seu auxiliar HTTP então descompacta o corpo de forma transparente e chama ReadAll antes da análise JSON.

Uma resposta ruim do serviço upstream contém um grande campo de descrição repetido em cada registro. A transferência de 18 KB se expande para muito mais dados do que a página normalmente conteria. O processo aloca a fatia de bytes, depois cria strings e mapas durante a análise e então serializa registros selecionados para o agente. Cada etapa mantém uma cópia diferente durante pelo menos parte da solicitação. Um limite colocado depois da análise percebe o problema apenas depois que o trabalho caro aconteceu.

O primeiro conserto muitas vezes adiciona if len(body) > limit após ReadAll. Esse teste deixa o teste unitário verde, mas preserva o pico de alocação. O segundo conserto envolve o leitor decodificado, que é o caminho certo, mas ainda envia os primeiros limit bytes ao agente como alternativa. Agora o agente pode agir com base em meia resposta, e a trilha de auditoria não mostra uma falha clara.

O conserto completo rejeita cedo no leitor decodificado, descarta o conteúdo parcial, registra a codificação e o orçamento de bytes e devolve a quem chama um erro que ela consegue classificar. Se o endpoint realmente precisa de exportações grandes, transfira esse caso de uso para um caminho explícito de download, com um limite aprovado mais alto, destino escolhido pelo usuário e nenhuma inserção automática do arquivo no contexto do agente.

Essa separação importa porque baixar um relatório e consultar uma ferramenta de agente são operações diferentes. O fato de ambas usarem uma solicitação HTTP não torna seus riscos ou orçamentos iguais.

Limites precisam de um responsável pelo endpoint e de um motivo

Um padrão global é um ponto de partida, não uma política adequada a toda ação HTTP. Atribua um limite de resposta decodificada conforme o resultado pretendido pelo endpoint. Uma verificação de status pode precisar de apenas alguns kilobytes. Uma busca paginada pode devolver uma resposta estruturada moderada. Uma exportação binária pode precisar de um limite maior, mas deve ir para um caminho de arquivo em vez de um resultado de conversa.

Escreva o limite ao lado da definição da ação, junto com o motivo. «A documentação da API diz que o tamanho da página é 100» não é motivo suficiente, porque um registro ainda pode ser enorme. Um bom motivo cita a representação esperada e o uso de quem chama, como «analisar um objeto de status e devolver campos selecionados» ou «salvar um arquivo solicitado pelo usuário após aprovação explícita».

Não derive o limite apenas de um parâmetro de tamanho de página enviado pelo servidor. Servidores podem ignorar um parâmetro, um agente pode solicitar uma consulta ampla e um único campo de texto pode dominar a resposta. Limite o tamanho da página, a abrangência da consulta, os bytes decodificados, os registros analisados e os bytes do resultado do agente onde cada fronteira fizer sentido. Esses controles se sobrepõem por projeto, pois cada um detecta um tipo diferente de solicitação ou resposta ruim.

Ao rejeitar uma resposta, registre detalhes suficientes para diagnóstico: método HTTP, host ou identificador da ação, código de status quando disponível, codificação de conteúdo declarada, bytes compactados observados, limite decodificado e se o decodificador já tinha começado a produzir saída. Não registre o corpo rejeitado por padrão. Registrá-lo pode recriar o problema de memória e dados sensíveis em um caminho que supostamente serve para diagnóstico.

Uma aprovação humana não torna uma resposta inofensiva. A aprovação pode autorizar uma ação com um serviço remoto, mas não prevê quantos dados esse serviço devolverá. Mantenha os limites de resposta aplicados após a aprovação e antes que o agente receba qualquer dado.

Cancelamento e timeouts cobrem outra falha

Um limite de tamanho decodificado interrompe o crescimento depois que o decodificador produz saída suficiente. Ele não interrompe um par que envia bytes dolorosamente devagar, um decodificador que consome CPU demais em um fluxo manipulado ou uma resposta que nunca termina. Defina prazos para a solicitação e garanta que o cancelamento feche o corpo da resposta e interrompa o leitor.

Mantenha separados nas métricas e nos erros o tempo, os bytes compactados, os bytes decodificados e as contagens de itens analisados. Se todas as falhas aparecerem como «solicitação falhou», alguém aumentará o limite de tamanho para resolver um timeout ou aumentará o timeout para resolver uma falha de parser. Essas mudanças dificultam o diagnóstico de incidentes e frequentemente ampliam a superfície de ataque.

Teste o cancelamento em um endpoint que envia um prefixo compactado válido e depois pausa. O cliente deve devolver seu erro de timeout ou cancelamento sem manter uma goroutine esperando pelo decodificador. Depois teste um corpo que se expande rapidamente além do limite decodificado. Esse caminho deve produzir logo o erro de tamanho, mesmo se o servidor continuaria enviando bytes compactados.

A reutilização de conexão exige cuidado após uma rejeição antecipada. Em muitos clientes, fechar o corpo basta para liberar recursos, mas a conexão pode não ser reutilizável se o cliente não consumiu o restante da resposta. Isso é aceitável. Correção e uso limitado de recursos valem mais que extrair mais uma conexão keep-alive de uma resposta hostil ou quebrada.

Evite repetir automaticamente uma resposta grande demais. Um erro transitório de rede pode justificar uma nova tentativa sob uma política limitada. Uma resposta que ultrapassa um limite conhecido costuma ser determinística. Repeti-la desperdiça largura de banda e pode multiplicar a pressão sobre um processo que já lida com uma ação grande demais.

Limites de parsing vêm depois da decodificação, não no lugar dela

Um parser JSON por streaming pode impedir que você armazene todos os registros, mas não elimina o limite de bytes decodificados. Parsers ainda precisam de buffers, strings individuais podem ser enormes e o relatório de erros pode manter fragmentos da fonte. Coloque o limite de bytes antes do parser e então adicione limites de formato compatíveis com os dados aceitos.

Para JSON, considere profundidade máxima de aninhamento, comprimento máximo de string, contagem máxima de registros e um esquema rígido para os campos que o agente usará. Para CSV ou protocolos de linha, defina um comprimento máximo de linha e uma quantidade máxima de linhas. Para XML, desative o processamento de entidades externas e defina limites do parser quando a biblioteca os oferecer. Essas são regras de análise, enquanto o limite do corpo decodificado é uma fronteira de transporte. Não tente fazer um se passar pelo outro.

Valide antes de renderizar. Um campo chamado instructions, command ou message vindo de um serviço remoto continua sendo conteúdo remoto. Seu tamanho pode caber no limite decodificado e ainda assim ser inadequado para o fluxo de controle de um agente. Selecione campos pelo esquema e codifique-os como dados. O limite de tamanho evita uma classe de falhas, mas não estabelece confiança no que os bytes dizem.

Essa separação torna o tratamento de erros menos confuso. Um corpo que ultrapassa o limite decodificado nunca deve chegar ao parser. Um corpo que cabe, mas tem registros demais, deve devolver um erro de limite de análise ou de aplicação. Um corpo que cabe no esquema, mas excede o orçamento de apresentação do agente, deve ser reduzido por uma regra explícita de resultado. Cada desfecho mostra ao operador o que precisa mudar, se é que algo precisa.

Trate o registro de auditoria como um relatório de fronteira

Um registro de auditoria útil informa o que o processo tentou fazer e por que o cliente se recusou a continuar. Ele não precisa do conteúdo rejeitado. Armazene a identidade da ação, o contexto de autorização, destino, hora da solicitação, status da resposta quando conhecido, codificação, contagem de bytes na rede, contagem de bytes decodificados ou um limite inferior e o limite que encerrou a chamada.

Em uma rejeição antecipada, a contagem decodificada pode ser limit + 1, e não o tamanho final real, porque o cliente parou de ler de propósito. Registre isso com honestidade. Afirmar que você conhece o tamanho decodificado completo sugere que consumiu justamente o fluxo que deveria limitar. Um limite inferior basta para explicar a decisão.

Isso é especialmente útil quando um agente repete uma ação depois que uma pessoa operadora muda uma consulta. Você consegue ver que a primeira chamada excedeu o orçamento de apresentação ou decodificação e que a segunda deu certo com uma solicitação mais restrita. Sem essa distinção, uma chamada de ferramenta com falha parece igual a um problema de autenticação ou rede, e as pessoas tentam o conserto errado.

A trilha de atividades do Sallyport pode preservar o caminho do resultado da ação sem entregar a credencial da API ao agente. Quem chama ainda precisa informar um resultado grande demais como falha limitada, em vez de transformar o registro de atividade em uma segunda cópia da resposta.

Faça do caso grande demais parte do critério de lançamento

Não deixe verificações de descompressão como um teste de segurança executado apenas quando alguém se lembra. Coloque arquivos de limite gzip e Brotli na suíte normal de testes do cliente. Execute as mesmas verificações por todos os caminhos HTTP que podem devolver dados a um agente, inclusive redirecionamentos se seu cliente os segue e respostas de erro se ele lê seus corpos para diagnóstico.

As verificações devem ser concretas. Para um corpo abaixo do limite, espere um resultado decodificado completo e validação de soma de verificação bem-sucedida. No limite exato, espere o mesmo. Um byte acima do limite, espere o erro de tamanho tipado, nenhum objeto analisado, nenhum resultado para o agente e um corpo de resposta fechado. Para codificação malformada, espere um erro de decodificação. Para codificação não compatível, espere um erro explícito de codificação não compatível antes de a análise começar.

Adicione um teste para um corpo compactado com tamanho pequeno na rede e tamanho decodificado acima do limite. Esse é o teste que detecta o erro original. Um corpo grande e sem compactação apenas prova que um limitador de bytes comum funciona. Ele não diz nada sobre a fronteira do decodificador.

Revise qualquer mudança que introduza uma biblioteca HTTP nova, um novo auxiliar prático de busca ou um novo caminho de registro de respostas. Essas mudanças frequentemente contornam o leitor cuidadosamente limitado porque parecem inofensivas de forma isolada. A pergunta da revisão de código é simples: em que ponto os bytes decodificados ficam disponíveis pela primeira vez e qual limite envolve exatamente esse leitor?

Se a resposta não estiver clara, a implementação não está pronta para quem chama de forma autônoma. Uma resposta pequena na rede não conquistou confiança especial. Faça-a provar seu tamanho depois da decodificação, antes que tenha a chance de gastar sua memória ou a atenção do seu agente.