Compressao

Compressao

Comprima e descomprima dados usando algoritmos gzip, deflate, zlib, brotli e zstd.

Carregamento

local compress = require("compress")

GZIP

Formato mais amplamente suportado (RFC 1952).

Comprimir {id=“gzip-compress”}

-- Comprimir para resposta HTTP
local body = json.encode(large_response)
local compressed, err = compress.gzip.encode(body)
if err then
    return nil, err
end

-- Definir header Content-Encoding
res:set_header("Content-Encoding", "gzip")
res:write(compressed)

-- Compressao maxima para armazenamento
local archived = compress.gzip.encode(data, {level = 9})

-- Compressao rapida para tempo real
local fast = compress.gzip.encode(data, {level = 1})

Parâmetro	Tipo	Descrição
data	string	Dados para comprimir
options	table?	Opções de codificação opcionais

Opções {id=“gzip-compress-options”}

Campo	Tipo	Descrição
level	integer	Nivel de compressao 1-9 (padrão: 6)

Retorna: string, error

Descomprimir {id=“gzip-decompress”}

-- Descomprimir requisição HTTP
local content_encoding = req:header("Content-Encoding")
if content_encoding == "gzip" then
    local body = req:body()
    local decompressed, err = compress.gzip.decode(body)
    if err then
        return nil, errors.new("INVALID", "Invalid gzip data")
    end
    body = decompressed
end

-- Descomprimir com limite de tamanho (prevenir zip bombs)
local decompressed, err = compress.gzip.decode(data, {max_size = 10 * 1024 * 1024})
if err then
    return nil, errors.new("INVALID", "Decompressed size exceeds 10MB limit")
end

Parâmetro	Tipo	Descrição
data	string	Dados comprimidos GZIP
options	table?	Opções de decodificação opcionais

Opções {id=“gzip-decompress-options”}

Campo	Tipo	Descrição
max_size	integer	Tamanho maximo descomprimido em bytes (padrão: 128MB, max: 1GB)

Retorna: string, error

Brotli

Melhor taxa de compressao para texto (RFC 7932).

Comprimir {id=“brotli-compress”}

-- Melhor para assets estaticos e conteudo de texto
local compressed = compress.brotli.encode(html_content, {level = 11})

-- Cachear assets comprimidos
cache:set("static:" .. hash, compressed)

-- Compressao moderada para respostas de API
local compressed = compress.brotli.encode(json_data, {level = 4})

Parâmetro	Tipo	Descrição
data	string	Dados para comprimir
options	table?	Opções de codificação opcionais

Opções {id=“brotli-compress-options”}

Campo	Tipo	Descrição
level	integer	Nivel de compressao 0-11 (padrão: 6)

Retorna: string, error

Descomprimir {id=“brotli-decompress”}

local decompressed, err = compress.brotli.decode(compressed_data)
if err then
    return nil, err
end

-- Com limite de tamanho
local decompressed = compress.brotli.decode(data, {max_size = 50 * 1024 * 1024})

Parâmetro	Tipo	Descrição
data	string	Dados comprimidos Brotli
options	table?	Opções de decodificação opcionais

Opções {id=“brotli-decompress-options”}

Campo	Tipo	Descrição
max_size	integer	Tamanho maximo descomprimido em bytes (padrão: 128MB, max: 1GB)

Retorna: string, error

Zstandard

Compressao rapida com boas taxas (RFC 8878).

Comprimir {id=“zstd-compress”}

-- Bom equilibrio de velocidade e taxa
local compressed = compress.zstd.encode(binary_data)

-- Compressao maior para arquivamento
local archived = compress.zstd.encode(data, {level = 19})

-- Modo rapido para streaming em tempo real
local fast = compress.zstd.encode(data, {level = 1})

Parâmetro	Tipo	Descrição
data	string	Dados para comprimir
options	table?	Opções de codificação opcionais

Opções {id=“zstd-compress-options”}

Campo	Tipo	Descrição
level	integer	Nivel de compressao 1-22 (padrão: 3)
dict	string?	Bytes do dicionário Zstd de train_dict (padrão: nenhum)

Retorna: string, error

Descomprimir {id=“zstd-decompress”}

local decompressed, err = compress.zstd.decode(compressed_data)
if err then
    return nil, err
end

Parâmetro	Tipo	Descrição
data	string	Dados comprimidos Zstandard
options	table?	Opções de decodificação opcionais

Opções {id=“zstd-decompress-options”}

Campo	Tipo	Descrição
max_size	integer	Tamanho maximo descomprimido em bytes (padrão: 128MB, max: 1GB)
dict	string?	Bytes do dicionário Zstd (deve corresponder ao dict usado para codificar)

Retorna: string, error

Dicionários {id=“zstd-dictionaries”}

Treine um dicionário a partir de dados de amostra para melhorar a compressão de muitos payloads pequenos e similares. Passe o dicionário treinado como a opção dict para encode/decode — o mesmo dicionário deve ser usado para ambos.

local dict, err = compress.zstd.train_dict(samples, { size = 112640 })
local packed   = compress.zstd.encode(data, { dict = dict })
local original = compress.zstd.decode(packed, { dict = dict })

train_dict(samples, options?)

Parâmetro	Tipo	Descrição
samples	string[]	Amostras de treinamento (pelo menos uma >= 8 bytes)
options	table?	size (integer, bytes alvo do dict, 256-1048576, padrão 114688), id (integer, padrão 0), level (integer, 1-22)

Retorna: string, error (os bytes do dicionário)

inspect_dict(dict)

Parâmetro	Tipo	Descrição
dict	string	Bytes do dicionário

Retorna: table, error — {id: integer, content_size: integer}

Deflate

Compressao DEFLATE raw (RFC 1951). Usado internamente por outros formatos.

Comprimir {id=“deflate-compress”}

local compressed = compress.deflate.encode(data, {level = 6})

Parâmetro	Tipo	Descrição
data	string	Dados para comprimir
options	table?	Opções de codificação opcionais

Opções {id=“deflate-compress-options”}

Campo	Tipo	Descrição
level	integer	Nivel de compressao 1-9 (padrão: 6)

Retorna: string, error

Descomprimir {id=“deflate-decompress”}

local decompressed = compress.deflate.decode(compressed)

Parâmetro	Tipo	Descrição
data	string	Dados comprimidos DEFLATE
options	table?	Opções de decodificação opcionais

Opções {id=“deflate-decompress-options”}

Campo	Tipo	Descrição
max_size	integer	Tamanho maximo descomprimido em bytes (padrão: 128MB, max: 1GB)

Retorna: string, error

Zlib

DEFLATE com header e checksum (RFC 1950).

Comprimir {id=“zlib-compress”}

local compressed = compress.zlib.encode(data, {level = 6})

Parâmetro	Tipo	Descrição
data	string	Dados para comprimir
options	table?	Opções de codificação opcionais

Opções {id=“zlib-compress-options”}

Campo	Tipo	Descrição
level	integer	Nivel de compressao 1-9 (padrão: 6)

Retorna: string, error

Descomprimir {id=“zlib-decompress”}

local decompressed = compress.zlib.decode(compressed)

Parâmetro	Tipo	Descrição
data	string	Dados comprimidos Zlib
options	table?	Opções de decodificação opcionais

Opções {id=“zlib-decompress-options”}

Campo	Tipo	Descrição
max_size	integer	Tamanho maximo descomprimido em bytes (padrão: 128MB, max: 1GB)

Retorna: string, error

Escolhendo um Algoritmo

Algoritmo	Melhor Para	Velocidade	Taxa	Faixa de Nivel
gzip	HTTP, ampla compatibilidade	Media	Boa	1-9
brotli	Assets estaticos, texto	Lenta	Melhor	0-11
zstd	Arquivos grandes, streaming	Rapida	Boa	1-22
deflate/zlib	Baixo nivel, protocolos especificos	Media	Boa	1-9

-- Resposta HTTP baseada em Accept-Encoding
local accept = req:header("Accept-Encoding") or ""
local body = json.encode(response_data)

if accept:find("br") then
    res:set_header("Content-Encoding", "br")
    res:write(compress.brotli.encode(body))
elseif accept:find("gzip") then
    res:set_header("Content-Encoding", "gzip")
    res:write(compress.gzip.encode(body))
else
    res:write(body)
end

Erros

Condição	Tipo	Retentável
Entrada vazia	errors.INVALID	não
Nivel fora da faixa	errors.INVALID	não
Dados comprimidos inválidos	errors.INVALID	não
Tamanho descomprimido excede limite	errors.INTERNAL	não

Veja Error Handling para trabalhar com erros.