Использование пула потоков и соображения по производительности

Все zlib API, за исключением тех, которые явно асинхронные, используют внутренний пул потоков Node.js. Это может приводить к неожиданным последствиям и ограничениям производительности в некоторых приложениях.

Создание и одновременное использование большого числа объектов zlib может привести к существенной фрагментации памяти.

const zlib = require('zlib');

const payload = Buffer.from('This is some data');

// WARNING: DO NOT DO THIS!
for (let i = 0; i < 30000; ++i) {
  zlib.deflate(payload, (err, buffer) => {});
}

В предыдущем примере одновременно создаётся 30 000 экземпляров deflate. Из-за того, как некоторые операционные системы обрабатывают выделение и освобождение памяти, это может привести к существенной фрагментации памяти.

Сильно рекомендуется кешировать результаты операций сжатия для предотвращения дублирования усилий.

Сжатие 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 { pipeline } = require('stream');

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');

  const onError = (err) => {
    if (err) {
      console.error('An error occurred:', err);
      process.exitCode = 1;
    }
  };

  switch (response.headers['content-encoding']) {
    case 'br':
      pipeline(response, zlib.createBrotliDecompress(), output, onError);
      break;
    // Or, just use zlib.createUnzip() to handle both of the following cases:
    case 'gzip':
      pipeline(response, zlib.createGunzip(), output, onError);
      break;
    case 'deflate':
      pipeline(response, zlib.createInflate(), output, onError);
      break;
    default:
      pipeline(response, output, onError);
      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');
const { pipeline } = require('stream');

http.createServer((request, response) => {
  const raw = fs.createReadStream('index.html');
  // Store both a compressed and an uncompressed version of the resource.
  response.setHeader('Vary', 'Accept-Encoding');
  let acceptEncoding = request.headers['accept-encoding'];
  if (!acceptEncoding) {
    acceptEncoding = '';
  }

  const onError = (err) => {
    if (err) {
      // If an error occurs, there's not much we can do because
      // the server has already sent the 200 response code and
      // some amount of data has already been sent to the client.
      // The best we can do is terminate the response immediately
      // and log the error.
      response.end();
      console.error('An error occurred:', err);
    }
  };

  // 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' });
    pipeline(raw, zlib.createDeflate(), response, onError);
  } else if (/\bgzip\b/.test(acceptEncoding)) {
    response.writeHead(200, { 'Content-Encoding': 'gzip' });
    pipeline(raw, zlib.createGzip(), response, onError);
  } else if (/\bbr\b/.test(acceptEncoding)) {
    response.writeHead(200, { 'Content-Encoding': 'br' });
    pipeline(raw, zlib.createBrotliCompress(), response, onError);
  } else {
    response.writeHead(200, {});
    pipeline(raw, response, onError);
  }
}).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.error('An error occurred:', err);
      process.exitCode = 1;
    }
    console.log(buffer.toString());
  });

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

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

Для потоков, основанных на 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');
const { pipeline } = require('stream');

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();
  let i;

  pipeline(output, response, (err) => {
    if (err) {
      // If an error occurs, there's not much we can do because
      // the server has already sent the 200 response code and
      // some amount of data has already been sent to the client.
      // The best we can do is terminate the response immediately
      // and log the error.
      clearInterval(i);
      response.end();
      console.error('An error occurred:', err);
    }
  });

  i = 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.

Ранее константы были доступны напрямую из 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).

Класс: Options

Каждый класс, основанный на zlib, принимает объект options. Опции не требуются.

Некоторые опции актуальны только при сжатии и игнорируются классами для распаковки.

• flush <целое> По умолчанию: zlib.constants.Z_NO_FLUSH
• finishFlush <целое> По умолчанию: zlib.constants.Z_FINISH
• chunkSize <целое> По умолчанию: 16 * 1024
• windowBits <целое>
• level <целое> (только для сжатия)
• memLevel <целое> (только для сжатия)
• strategy <целое> (только для сжатия)
• dictionary <Буфер> | <Массив типов> | <DataView> | <Массив буферов> (только для deflate/inflate, пустой словарь по умолчанию)
• info <логическое> (Если true, возвращает объект с buffer и engine.)
• maxOutputLength <целое> Ограничивает размер выходных данных при использовании методов удобного использования. По умолчанию: buffer.kMaxLength

См. документацию deflateInit2 и inflateInit2 для получения дополнительной информации.

Класс: BrotliOptions

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

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

Например:

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

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

Класс: zlib.BrotliDecompress

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

Класс: zlib.Deflate

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

Класс: zlib.DeflateRaw

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

Класс: zlib.Gunzip

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

Класс: zlib.Gzip

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

Класс: zlib.Inflate

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

Класс: zlib.InflateRaw

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

Класс: zlib.Unzip

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

Класс: zlib.ZlibBase

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

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

zlib.bytesRead

• <число>

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

zlib.bytesWritten

• <число>

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

zlib.close([callback])

• callback <Функция>

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

zlib.flush([kind, ]callback)

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

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

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

zlib.params(level, strategy, callback)

• level <целое число>
• strategy <целое число>
• callback <Функция>

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

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

zlib.reset()

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

zlib.constants

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

zlib.createBrotliCompress([options])

• options <опции Brotli>

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

zlib.createBrotliDecompress([options])

• options <опции Brotli>

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

zlib.createDeflate([options])

• options <опции zlib>

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

zlib.createDeflateRaw([options])

• options <опции zlib>

Создаёт и возвращает новый объект 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 <опции zlib>

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

zlib.createGzip([options])

• options <опции zlib>

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

zlib.createInflate([options])

• options <опции zlib>

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

zlib.createInflateRaw([options])

• options <опции zlib>

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

zlib.createUnzip([options])

• options <опции zlib>

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

Методы для удобства

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

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

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

• buffer <Буфер> | <Тип массива> | <DataView> | <ArrayBuffer> | <строка>
• options <параметры brotli>
• callback <Функция>

zlib.brotliCompressSync(buffer[, options])

• buffer <Буфер> | <Тип массива> | <DataView> | <ArrayBuffer> | <строка>
• options <параметры brotli>

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

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

• buffer <Буфер> | <Тип массива> | <DataView> | <ArrayBuffer> | <строка>
• options <параметры brotli>
• callback <Функция>

zlib.brotliDecompressSync(buffer[, options])

• buffer <Буфер> | <Тип массива> | <DataView> | <ArrayBuffer> | <строка>
• options <параметры brotli>

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

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

• buffer <Буфер> | <Тип массива> | <DataView> | <ArrayBuffer> | <строка>
• options <опции zlib>
• callback <Функция>

zlib.deflateSync(buffer[, options])

• buffer <Буфер> | <Тип массива> | <DataView> | <ArrayBuffer> | <строка>
• options <опции zlib>

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

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

• buffer <Буфер> | <Тип массива> | <DataView> | <ArrayBuffer> | <строка>
• options <опции zlib>
• callback <Функция>

zlib.deflateRawSync(buffer[, options])

• buffer <Буфер> | <Тип массива> | <DataView> | <ArrayBuffer> | <строка>
• options <опции zlib>

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

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

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

zlib.gunzipSync(buffer[, options])

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

Распакуйте часть данных с помощью Gunzip.

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

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

zlib.gzipSync(buffer[, options])

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

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

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

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

zlib.inflateSync(buffer[, options])

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

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

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

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

zlib.inflateRawSync(buffer[, options])

• buffer <Buffer> | <TypedArray> | <DataView> | <ArrayBuffer> | <строка>
• options <zlib параметры>

Разархивировать фрагмент данных с помощью InflateRaw.

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

• buffer <Buffer> | <TypedArray> | <DataView> | <ArrayBuffer> | <строка>
• options <zlib параметры>
• callback <Функция>

zlib.unzipSync(buffer[, options])

• buffer <Buffer> | <TypedArray> | <DataView> | <ArrayBuffer> | <строка>
• options <zlib параметры>

Разархивировать фрагмент данных с помощью Unzip.