Zlib

Модуль zlib предоставляет функциональность сжатия, реализованную с использованием Gzip и Deflate/Inflate, а также Brotli. К нему можно обратиться следующим образом:

const zlib = require('zlib');

Сжатие или разархивирование потока (например, файла) может быть выполнено путем передачи данных исходного потока через поток zlib в целевой поток:

const gzip = zlib.createGzip();
const fs = require('fs');
const inp = fs.createReadStream('input.txt');
const out = fs.createWriteStream('input.txt.gz');

inp.pipe(gzip).pipe(out);

Также возможно сжать или разархивировать данные в одном шаге:

const input = '.................................';
zlib.deflate(input, (err, buffer) => {
  if (!err) {
    console.log(buffer.toString('base64'));
  } else {
    // handle error
  }
});

const buffer = Buffer.from('eJzT0yMAAGTvBe8=', 'base64');
zlib.unzip(buffer, (err, buffer) => {
  if (!err) {
    console.log(buffer.toString());
  } else {
    // handle error
  }
});

Использование пула потоков

Обратите внимание, что все API zlib, кроме явно синхронных, используют пул потоков libuv. Это может привести к неожиданным результатам в некоторых приложениях, таким как низкая производительность (что можно смягчить, настроив размер пула размер пула) и/или необратимая и катастрофическая фрагментация памяти.

Сжатие HTTP-запросов и ответов

Модуль zlib может использоваться для реализации поддержки механизмов кодирования содержимого gzip, deflate и br, определенных в HTTP.

HTTP-заголовок Accept-Encoding используется в запросе HTTP для идентификации кодировок сжатия, принимаемых клиентом. Заголовок Content-Encoding используется для идентификации кодировок сжатия, фактически примененных к сообщению.

Приведенные ниже примеры существенно упрощены, чтобы продемонстрировать основную концепцию. Использование кодирования zlib может быть дорогостоящим, и результаты следует кешировать. Подробнее о компромиссах между скоростью, памятью и степенью сжатия при использовании zlib см. в разделе Настройка использования памяти.

// client request example
const zlib = require('zlib');
const http = require('http');
const fs = require('fs');
const request = http.get({ host: 'example.com',
                           path: '/',
                           port: 80,
                           headers: { 'Accept-Encoding': 'br,gzip,deflate' } });
request.on('response', (response) => {
  const output = fs.createWriteStream('example.com_index.html');

  switch (response.headers['content-encoding']) {
    case 'br':
      response.pipe(zlib.createBrotliDecompress()).pipe(output);
      break;
    // Or, just use zlib.createUnzip() to handle both of the following cases:
    case 'gzip':
      response.pipe(zlib.createGunzip()).pipe(output);
      break;
    case 'deflate':
      response.pipe(zlib.createInflate()).pipe(output);
      break;
    default:
      response.pipe(output);
      break;
  }
});

// server example
// Running a gzip operation on every request is quite expensive.
// It would be much more efficient to cache the compressed buffer.
const zlib = require('zlib');
const http = require('http');
const fs = require('fs');
http.createServer((request, response) => {
  const raw = fs.createReadStream('index.html');
  let acceptEncoding = request.headers['accept-encoding'];
  if (!acceptEncoding) {
    acceptEncoding = '';
  }

  // Note: This is not a conformant accept-encoding parser.
  // See https://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.3
  if (/\bdeflate\b/.test(acceptEncoding)) {
    response.writeHead(200, { 'Content-Encoding': 'deflate' });
    raw.pipe(zlib.createDeflate()).pipe(response);
  } else if (/\bgzip\b/.test(acceptEncoding)) {
    response.writeHead(200, { 'Content-Encoding': 'gzip' });
    raw.pipe(zlib.createGzip()).pipe(response);
  } else if (/\bbr\b/.test(acceptEncoding)) {
    response.writeHead(200, { 'Content-Encoding': 'br' });
    raw.pipe(zlib.createBrotliCompress()).pipe(response);
  } else {
    response.writeHead(200, {});
    raw.pipe(response);
  }
}).listen(1337);

По умолчанию методы zlib генерируют ошибку при разархивировании усеченных данных. Однако, если известно, что данные неполные, или требуется проверить только начало сжатого файла, можно подавить обработку ошибок по умолчанию, изменив метод сброса, который используется для разархивирования последнего блока входных данных:

// This is a truncated version of the buffer from the above examples
const buffer = Buffer.from('eJzT0yMA', 'base64');

zlib.unzip(
  buffer,
  // For Brotli, the equivalent is zlib.constants.BROTLI_OPERATION_FLUSH.
  { finishFlush: zlib.constants.Z_SYNC_FLUSH },
  (err, buffer) => {
    if (!err) {
      console.log(buffer.toString());
    } else {
      // handle error
    }
  });

Это не изменит поведение в других ситуациях, генерирующих ошибки, например, когда входные данные имеют недопустимый формат. Используя этот метод, невозможно определить, закончился ли ввод преждевременно или отсутствуют проверки целостности, что делает необходимым вручную проверить, что результат разархивирования является допустимым.

Настройка использования памяти

Для потоков, основанных на zlib

Из zlib/zconf.h, изменённое для использования в Node.js:

Требования к памяти для deflate (в байтах):

(1 << (windowBits + 2)) + (1 << (memLevel + 9))

То есть: 128 КБ для windowBits = 15 + 128 КБ для memLevel = 8 (значения по умолчанию) плюс несколько килобайт для небольших объектов.

Например, чтобы уменьшить требования к памяти по умолчанию с 256 КБ до 128 КБ, параметры следует установить следующим образом:

const options = { windowBits: 14, memLevel: 7 };

Однако это, как правило, ухудшит сжатие.

Требования к памяти для inflate (в байтах) 1 << windowBits. То есть, 32 КБ для windowBits = 15 (значение по умолчанию) плюс несколько килобайт для небольших объектов.

Это помимо одного внутреннего буфера выходного набора размером chunkSize, по умолчанию равным 16 КБ.

Скорость сжатия zlib наиболее сильно зависит от параметра level. Более высокое значение приведет к лучшему сжатию, но займет больше времени. Более низкое значение приведет к меньшему сжатию, но будет намного быстрее.

В целом, большие значения параметров использования памяти означают, что Node.js должен выполнить меньше вызовов zlib, потому что он сможет обработать больше данных в каждой операции write. Таким образом, это еще один фактор, влияющий на скорость, но за счет использования памяти.

Для потоков, основанных на Brotli

Существуют аналоги zlib-параметров для потоков, основанных на Brotli, хотя диапазоны этих параметров отличаются от диапазонов для zlib:

• Параметр level zlib соответствует параметру BROTLI_PARAM_QUALITY Brotli.
• Параметр windowBits zlib соответствует параметру BROTLI_PARAM_LGWIN Brotli.

Дополнительные сведения о специфичных для Brotli параметрах см. в разделе ниже.

Сброс

Вызов .flush() для потока сжатия заставит zlib вернуть как можно больше выходных данных. Это может привести к ухудшению качества сжатия, но может быть полезно, когда данные должны быть доступны как можно скорее.

В следующем примере используется flush(), чтобы записать частичный сжатый HTTP-ответ клиенту:

const zlib = require('zlib');
const http = require('http');

http.createServer((request, response) => {
  // For the sake of simplicity, the Accept-Encoding checks are omitted.
  response.writeHead(200, { 'content-encoding': 'gzip' });
  const output = zlib.createGzip();
  output.pipe(response);

  setInterval(() => {
    output.write(`The current time is ${Date()}\n`, () => {
      // The data has been passed to zlib, but the compression algorithm may
      // have decided to buffer the data for more efficient compression.
      // Calling .flush() will make the data available as soon as the client
      // is ready to receive it.
      output.flush();
    });
  }, 1000);
}).listen(1337);

Константы

Константы zlib

Все константы, определенные в zlib.h, также определены в require('zlib').constants. В нормальном ходе операций использование этих констант не потребуется. Они документированы, чтобы их присутствие не вызывало удивления. Этот раздел почти полностью взят из документации zlib. Более подробная информация доступна на https://zlib.net/manual.html#Constants.

Ранее константы были доступны непосредственно из require('zlib'), например zlib.Z_NO_FLUSH. Доступ к константам напрямую из модуля по-прежнему возможен, но устарел.

Допустимые значения сброса.

• zlib.constants.Z_NO_FLUSH
• zlib.constants.Z_PARTIAL_FLUSH
• zlib.constants.Z_SYNC_FLUSH
• zlib.constants.Z_FULL_FLUSH
• zlib.constants.Z_FINISH
• zlib.constants.Z_BLOCK
• zlib.constants.Z_TREES

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

• zlib.constants.Z_OK
• zlib.constants.Z_STREAM_END
• zlib.constants.Z_NEED_DICT
• zlib.constants.Z_ERRNO
• zlib.constants.Z_STREAM_ERROR
• zlib.constants.Z_DATA_ERROR
• zlib.constants.Z_MEM_ERROR
• zlib.constants.Z_BUF_ERROR
• zlib.constants.Z_VERSION_ERROR

Уровни сжатия.

• zlib.constants.Z_NO_COMPRESSION
• zlib.constants.Z_BEST_SPEED
• zlib.constants.Z_BEST_COMPRESSION
• zlib.constants.Z_DEFAULT_COMPRESSION

Стратегия сжатия.

• zlib.constants.Z_FILTERED
• zlib.constants.Z_HUFFMAN_ONLY
• zlib.constants.Z_RLE
• zlib.constants.Z_FIXED
• zlib.constants.Z_DEFAULT_STRATEGY

Константы Brotli

Для потоков, основанных на Brotli, доступно несколько параметров и других констант:

Операции сброса

Следующие значения являются допустимыми операциями сброса для потоков, основанных на Brotli:

• zlib.constants.BROTLI_OPERATION_PROCESS (значение по умолчанию для всех операций)
• zlib.constants.BROTLI_OPERATION_FLUSH (значение по умолчанию при вызове .flush())
• zlib.constants.BROTLI_OPERATION_FINISH (значение по умолчанию для последнего блока)

• zlib.constants.BROTLI_OPERATION_EMIT_METADATA

  • Эта конкретная операция может быть сложной для использования в контексте Node.js, так как слой потоковой передачи затрудняет определение, какие данные попадут в этот кадр. Также в настоящее время нет способа получить доступ к этим данным через API Node.js.

Параметры сжатия

Существует несколько параметров, которые можно задать для Brotli-кодировщиков, влияющих на эффективность и скорость сжатия. И ключи, и значения могут быть доступны в качестве свойств объекта zlib.constants.

Наиболее важные параметры:

• BROTLI_PARAM_MODE

  • BROTLI_MODE_GENERIC (значение по умолчанию)
  • BROTLI_MODE_TEXT, скорректировано для UTF-8 текста
  • BROTLI_MODE_FONT, скорректировано для шрифтов WOFF 2.0

• BROTLI_PARAM_QUALITY

  • Значения от BROTLI_MIN_QUALITY до BROTLI_MAX_QUALITY, по умолчанию BROTLI_DEFAULT_QUALITY.

• BROTLI_PARAM_SIZE_HINT

  • Целочисленное значение, представляющее ожидаемый размер ввода; по умолчанию 0 для неизвестного размера ввода.

Следующие флаги можно установить для расширенного управления алгоритмом сжатия и настройкой использования памяти:

• BROTLI_PARAM_LGWIN

  • Значения от BROTLI_MIN_WINDOW_BITS до BROTLI_MAX_WINDOW_BITS, по умолчанию BROTLI_DEFAULT_WINDOW, или до BROTLI_LARGE_MAX_WINDOW_BITS если установлен флаг BROTLI_PARAM_LARGE_WINDOW.

• BROTLI_PARAM_LGBLOCK

  • Значения от BROTLI_MIN_INPUT_BLOCK_BITS до BROTLI_MAX_INPUT_BLOCK_BITS.

• BROTLI_PARAM_DISABLE_LITERAL_CONTEXT_MODELING

  • Флаг, уменьшающий коэффициент сжатия в пользу скорости разархивирования.

• BROTLI_PARAM_LARGE_WINDOW

  • Флаг, активирующий режим «Large Window Brotli» (несовместим с форматом Brotli, стандартизированным в RFC 7932).

• BROTLI_PARAM_NPOSTFIX

  • Значения от 0 до BROTLI_MAX_NPOSTFIX.

• BROTLI_PARAM_NDIRECT

  • Диапазон значений от 0 до 15 << NPOSTFIX с шагом 1 << NPOSTFIX.

Параметры разархивирования

Эти расширенные параметры доступны для управления разархивированием:

• BROTLI_DECODER_PARAM_DISABLE_RING_BUFFER_REALLOCATION

  • Флаг, влияющий на внутренние схемы распределения памяти.

• BROTLI_DECODER_PARAM_LARGE_WINDOW

  • Флаг, активирующий режим «Large Window Brotli» (несовместим с форматом Brotli, стандартизированным в RFC 7932).

Класс: Опции

Каждый класс, основанный на zlib, принимает объект options. Все параметры необязательны.

Обратите внимание, что некоторые параметры актуальны только при сжатии и игнорируются классами разархивирования.

• flush <integer> По умолчанию: zlib.constants.Z_NO_FLUSH
• finishFlush <integer> По умолчанию: zlib.constants.Z_FINISH
• chunkSize <integer> По умолчанию: 16 * 1024
• windowBits <integer>
• level <integer> (только для сжатия)
• memLevel <integer> (только для сжатия)
• strategy <integer> (только для сжатия)
• dictionary <Buffer> | <TypedArray> | <DataView> | <ArrayBuffer> (только deflate/inflate, по умолчанию пустой словарь)
• info <boolean> (Если true, возвращает объект с buffer и engine.)

См. описание deflateInit2 и inflateInit2 по адресу https://zlib.net/manual.html#Advanced для получения дополнительной информации об этих параметрах.

Класс: BrotliOptions

Каждый класс, основанный на Brotli, принимает объект options. Все параметры необязательны.

• flush <integer> По умолчанию: zlib.constants.BROTLI_OPERATION_PROCESS
• finishFlush <integer> По умолчанию: zlib.constants.BROTLI_OPERATION_FINISH
• chunkSize <integer> По умолчанию: 16 * 1024
• params <Object> Объект с ключевыми значениями, содержащий индексированные параметры Brotli.

Например:

const stream = zlib.createBrotliCompress({
  chunkSize: 32 * 1024,
  params: {
    [zlib.constants.BROTLI_PARAM_MODE]: zlib.constants.BROTLI_MODE_TEXT,
    [zlib.constants.BROTLI_PARAM_QUALITY]: 4,
    [zlib.constants.BROTLI_PARAM_SIZE_HINT]: fs.statSync(inputFile).size
  }
});

Класс: zlib.BrotliCompress[src]

Сжатие данных с помощью алгоритма Brotli.

Класс: zlib.BrotliDecompress[src]

Распаковка данных с помощью алгоритма Brotli.

Класс: zlib.Deflate[src]

Сжатие данных с помощью deflate.

Класс: zlib.DeflateRaw[src]

Сжатие данных с помощью deflate без добавления zlib заголовка.

Класс: zlib.Gunzip[src]

Распаковка gzip потока.

Класс: zlib.Gzip[src]

Сжатие данных с помощью gzip.

Класс: zlib.Inflate[src]

Распаковка deflate потока.

Класс: zlib.InflateRaw[src]

Распаковка сырого deflate потока.

Класс: zlib.Unzip[src]

Распаковка сжатого gzip или deflate потока, автоматически определяя заголовок.

Класс: zlib.ZlibBase

Не экспортируется модулем zlib. Он документирован здесь, потому что является базовым классом для классов сжатия/распаковки.

Этот класс наследуется от stream.Transform, что позволяет использовать объекты zlib в конвейерах и аналогичных операциях с потоками.

zlib.bytesRead

• <number>

Устаревшее псевдоним для zlib.bytesWritten. Изначально это имя было выбрано, так как также имело смысл интерпретировать значение как количество байт, прочитанных движком, но оно не согласуется с другими потоками в Node.js, которые экспонируют значения под этими именами.

zlib.bytesWritten

• <number>

Свойство zlib.bytesWritten указывает количество байт, записанных в движок, до обработки байтов (сжатия или распаковки, в зависимости от производного класса).

zlib.close([callback])

• callback <Function>

Закрытие базового дескриптора.

zlib.flush([kind, ]callback)

• kind По умолчанию: zlib.constants.Z_FULL_FLUSH для потоков на основе zlib, zlib.constants.BROTLI_OPERATION_FLUSH для потоков на основе Brotli.
• callback <Function>

Очистка данных. Не вызывайте это слишком часто, преждевременные очистки негативно влияют на эффективность алгоритма сжатия.

Вызов этой функции только очищает данные из внутреннего состояния zlib, и не производит очистку каких-либо видов на уровне потоков. Вместо этого он ведет себя как обычный вызов .write(), т.е. он будет поставлен в очередь позади других ожидающих записей и выведет результат только тогда, когда данные будут считываться из потока.

zlib.params(level, strategy, callback)

• level <integer>
• strategy <integer>
• callback <Function>

Эта функция доступна только для потоков на основе zlib, т.е. не Brotli.

Динамическое обновление уровня сжатия и стратегии сжатия. Применимо только к алгоритму deflate.

zlib.reset()

Сбросить сжимающий/распаковывающий модуль к заводским настройкам. Применимо только к алгоритмам сжатия/распаковки inflate и deflate.

zlib.constants

Предоставляет объект, перечисляющий константы, связанные с Zlib.

zlib.createBrotliCompress([options])

• options <brotli options>

Создаёт и возвращает новый объект BrotliCompress.

zlib.createBrotliDecompress([options])

• options <brotli options>

Создаёт и возвращает новый объект BrotliDecompress.

zlib.createDeflate([options])

• options <Object>

Создаёт и возвращает новый объект Deflate.

zlib.createDeflateRaw([options])

• options <Object>

Создаёт и возвращает новый объект DeflateRaw.

Обновление zlib с версии 1.2.8 до 1.2.11 изменило поведение, когда windowBits установлено в 8 для потоков raw deflate. zlib автоматически устанавливал windowBits в 9, если изначально оно было равно 8. Более новые версии zlib будут выбрасывать исключение, поэтому Node.js восстановил исходное поведение, повышая значение 8 до 9, поскольку передача windowBits = 9 в zlib фактически приводит к сжатому потоку, который эффективно использует 8-битное окно.

zlib.createGunzip([options])

• options <Object>

Создаёт и возвращает новый объект Gunzip.

zlib.createGzip([options])

• options <Object>

Создаёт и возвращает новый объект Gzip.

zlib.createInflate([options])

• options <Object>

Создаёт и возвращает новый объект Inflate.

zlib.createInflateRaw([options])

• options <Object>

Создаёт и возвращает новый объект InflateRaw.

zlib.createUnzip([options])

• options <Object>

Создаёт и возвращает новый объект Unzip.

Удобные методы

Все они принимают Buffer, TypedArray, DataView, ArrayBuffer или строку в качестве первого аргумента, необязательный второй аргумент для передачи параметров классам zlib, и вызовет предоставленный обратный вызов с callback(error, result).

Каждый метод имеет *Sync аналог, который принимает те же аргументы, но без обратного вызова.

zlib.brotliCompress(buffer[, options], callback)

• buffer <Buffer> | <TypedArray> | <DataView> | <ArrayBuffer> | <string>
• options <brotli options>
• callback <Function>

zlib.brotliCompressSync(buffer[, options])

• buffer <Buffer> | <TypedArray> | <DataView> | <ArrayBuffer> | <string>
• options <brotli options>

Сжать блок данных с помощью BrotliCompress.

zlib.brotliDecompress(buffer[, options], callback)

• buffer <Buffer> | <TypedArray> | <DataView> | <ArrayBuffer> | <string>
• options <brotli options>
• callback <Function>

zlib.brotliDecompressSync(buffer[, options])

• buffer <Buffer> | <TypedArray> | <DataView> | <ArrayBuffer> | <string>
• options <brotli options>

Распаковать блок данных с помощью BrotliDecompress.

zlib.deflate(buffer[, options], callback)

• buffer <Buffer> | <TypedArray> | <DataView> | <ArrayBuffer> | <string>
• options <Object>
• callback <Function>

zlib.deflateSync(buffer[, options])

• buffer <Buffer> | <TypedArray> | <DataView> | <ArrayBuffer> | <string>
• options <Object>

Сжать блок данных с помощью Deflate.

zlib.deflateRaw(buffer[, options], callback)

• buffer <Buffer> | <TypedArray> | <DataView> | <ArrayBuffer> | <string>
• options <Object>
• callback <Function>

zlib.deflateRawSync(buffer[, options])

• buffer <Buffer> | <TypedArray> | <DataView> | <ArrayBuffer> | <string>
• options <Object>

Сжать блок данных с помощью DeflateRaw.

zlib.gunzip(buffer[, options], callback)

• buffer <Buffer> | <TypedArray> | <DataView> | <ArrayBuffer> | <string>
• options <Object>
• callback <Function>

zlib.gunzipSync(buffer[, options])

• buffer <Buffer> | <TypedArray> | <DataView> | <ArrayBuffer> | <string>
• options <Object>

Распаковать блок данных с помощью Gunzip.

zlib.gzip(buffer[, options], callback)

• buffer <Buffer> | <TypedArray> | <DataView> | <ArrayBuffer> | <string>
• options <Object>
• callback <Function>

zlib.gzipSync(buffer[, options])

• buffer <Buffer> | <TypedArray> | <DataView> | <ArrayBuffer> | <string>
• options <Object>

Сжать блок данных с помощью Gzip.

zlib.inflate(buffer[, options], callback)

• buffer <Buffer> | <TypedArray> | <DataView> | <ArrayBuffer> | <string>
• options <Object>
• callback <Function>

zlib.inflateSync(buffer[, options])

• buffer <Buffer> | <TypedArray> | <DataView> | <ArrayBuffer> | <string>
• options <Object>

Распакуйте фрагмент данных с помощью Inflate.

zlib.inflateRaw(buffer[, options], callback)

• buffer <Buffer> | <TypedArray> | <DataView> | <ArrayBuffer> | <string>
• options <Object>
• callback <Function>

zlib.inflateRawSync(buffer[, options])

• buffer <Buffer> | <TypedArray> | <DataView> | <ArrayBuffer> | <string>
• options <Object>

Распакуйте фрагмент данных с помощью InflateRaw.

zlib.unzip(buffer[, options], callback)

• buffer <Buffer> | <TypedArray> | <DataView> | <ArrayBuffer> | <string>
• options <Object>
• callback <Function>

zlib.unzipSync(buffer[, options])

• buffer <Buffer> | <TypedArray> | <DataView> | <ArrayBuffer> | <string>
• options <Object>

Распакуйте фрагмент данных с помощью Unzip.