Сжатие данных

Сжатие и распаковка данных с использованием алгоритмов gzip, deflate, zlib, brotli и zstd.

Загрузка

local compress = require("compress")

GZIP

Наиболее широко поддерживаемый формат (RFC 1952).

Сжатие {id=“gzip-compress”}

-- Сжатие для HTTP-ответа
local body = json.encode(large_response)
local compressed, err = compress.gzip.encode(body)
if err then
    return nil, err
end

-- Установка заголовка Content-Encoding
res:set_header("Content-Encoding", "gzip")
res:write(compressed)

-- Максимальное сжатие для хранения
local archived = compress.gzip.encode(data, {level = 9})

-- Быстрое сжатие для реального времени
local fast = compress.gzip.encode(data, {level = 1})

Параметр	Тип	Описание
`data`	string	Данные для сжатия
`options`	table?	Опции кодирования (опционально)

Опции {id=“gzip-compress-options”}

Поле	Тип	Описание
`level`	integer	Уровень сжатия 1-9 (по умолчанию: 6)

Возвращает: string, error

Распаковка {id=“gzip-decompress”}

-- Распаковка 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

-- Распаковка с ограничением размера (защита от zip-бомб)
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

Параметр	Тип	Описание
`data`	string	Сжатые GZIP-данные
`options`	table?	Опции декодирования (опционально)

Опции {id=“gzip-decompress-options”}

Поле	Тип	Описание
`max_size`	integer	Макс. размер после распаковки в байтах (по умолчанию: 128MB, макс: 1GB)

Возвращает: string, error

Brotli

Лучшая степень сжатия для текста (RFC 7932).

Сжатие {id=“brotli-compress”}

-- Лучше всего подходит для статических ресурсов и текста
local compressed = compress.brotli.encode(html_content, {level = 11})

-- Кэширование сжатых ресурсов
cache:set("static:" .. hash, compressed)

-- Умеренное сжатие для API-ответов
local compressed = compress.brotli.encode(json_data, {level = 4})

Параметр	Тип	Описание
`data`	string	Данные для сжатия
`options`	table?	Опции кодирования (опционально)

Опции {id=“brotli-compress-options”}

Поле	Тип	Описание
`level`	integer	Уровень сжатия 0-11 (по умолчанию: 6)

Возвращает: string, error

Распаковка {id=“brotli-decompress”}

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

-- С ограничением размера
local decompressed = compress.brotli.decode(data, {max_size = 50 * 1024 * 1024})

Параметр	Тип	Описание
`data`	string	Сжатые Brotli-данные
`options`	table?	Опции декодирования (опционально)

Опции {id=“brotli-decompress-options”}

Поле	Тип	Описание
`max_size`	integer	Макс. размер после распаковки в байтах (по умолчанию: 128MB, макс: 1GB)

Возвращает: string, error

Zstandard

Быстрое сжатие с хорошим соотношением (RFC 8878).

Сжатие {id=“zstd-compress”}

-- Хороший баланс скорости и степени сжатия
local compressed = compress.zstd.encode(binary_data)

-- Высокое сжатие для архивов
local archived = compress.zstd.encode(data, {level = 19})

-- Быстрый режим для потоковой передачи
local fast = compress.zstd.encode(data, {level = 1})

Параметр	Тип	Описание
`data`	string	Данные для сжатия
`options`	table?	Опции кодирования (опционально)

Опции {id=“zstd-compress-options”}

Поле	Тип	Описание
`level`	integer	Уровень сжатия 1-22 (по умолчанию: 3)
`dict`	string?	Байты Zstd-словаря из `train_dict` (по умолчанию: нет)

Возвращает: string, error

Распаковка {id=“zstd-decompress”}

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

Параметр	Тип	Описание
`data`	string	Сжатые Zstandard-данные
`options`	table?	Опции декодирования (опционально)

Опции {id=“zstd-decompress-options”}

Поле	Тип	Описание
`max_size`	integer	Макс. размер после распаковки в байтах (по умолчанию: 128MB, макс: 1GB)
`dict`	string?	Байты Zstd-словаря (должны совпадать со словарём, использованным для кодирования)

Возвращает: string, error

Словари {id=“zstd-dictionaries”}

Обучите словарь на образцах данных, чтобы улучшить сжатие множества небольших похожих нагрузок. Передавайте обученный словарь как опцию dict в encode/decode — для обоих должен использоваться один и тот же словарь.

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?)

Параметр	Тип	Описание
`samples`	string[]	Обучающие образцы (хотя бы один >= 8 байт)
`options`	table?	`size` (integer, целевой размер словаря в байтах, 256-1048576, по умолчанию 114688), `id` (integer, по умолчанию 0), `level` (integer, 1-22)

Возвращает: string, error (байты словаря)

inspect_dict(dict)

Параметр	Тип	Описание
`dict`	string	Байты словаря

Возвращает: table, error — {id: integer, content_size: integer}

Deflate

Чистое DEFLATE-сжатие (RFC 1951). Используется внутри других форматов.

Сжатие {id=“deflate-compress”}

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

Параметр	Тип	Описание
`data`	string	Данные для сжатия
`options`	table?	Опции кодирования (опционально)

Опции {id=“deflate-compress-options”}

Поле	Тип	Описание
`level`	integer	Уровень сжатия 1-9 (по умолчанию: 6)

Возвращает: string, error

Распаковка {id=“deflate-decompress”}

local decompressed = compress.deflate.decode(compressed)

Параметр	Тип	Описание
`data`	string	Сжатые DEFLATE-данные
`options`	table?	Опции декодирования (опционально)

Опции {id=“deflate-decompress-options”}

Поле	Тип	Описание
`max_size`	integer	Макс. размер после распаковки в байтах (по умолчанию: 128MB, макс: 1GB)

Возвращает: string, error

Zlib

DEFLATE с заголовком и контрольной суммой (RFC 1950).

Сжатие {id=“zlib-compress”}

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

Параметр	Тип	Описание
`data`	string	Данные для сжатия
`options`	table?	Опции кодирования (опционально)

Опции {id=“zlib-compress-options”}

Поле	Тип	Описание
`level`	integer	Уровень сжатия 1-9 (по умолчанию: 6)

Возвращает: string, error

Распаковка {id=“zlib-decompress”}

local decompressed = compress.zlib.decode(compressed)

Параметр	Тип	Описание
`data`	string	Сжатые Zlib-данные
`options`	table?	Опции декодирования (опционально)

Опции {id=“zlib-decompress-options”}

Поле	Тип	Описание
`max_size`	integer	Макс. размер после распаковки в байтах (по умолчанию: 128MB, макс: 1GB)

Возвращает: string, error

Выбор алгоритма

Алгоритм	Применение	Скорость	Степень	Диапазон уровней
gzip	HTTP, широкая совместимость	Средняя	Хорошая	1-9
brotli	Статические ресурсы, текст	Низкая	Лучшая	0-11
zstd	Большие файлы, потоки	Высокая	Хорошая	1-22
deflate/zlib	Низкоуровневые протоколы	Средняя	Хорошая	1-9

-- HTTP-ответ на основе 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

Ошибки

Условие	Kind	Повторяемо
Пустой ввод	`errors.INVALID`	нет
Уровень вне диапазона	`errors.INVALID`	нет
Некорректные сжатые данные	`errors.INVALID`	нет
Распакованный размер превышает лимит	`errors.INTERNAL`	нет

См. Обработка ошибок для работы с ошибками.