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

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

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

const zlib = require('node: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) => {});
} copy

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

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

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

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

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

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

// Client request example
const zlib = require('node:zlib');
const http = require('node:http');
const fs = require('node:fs');
const { pipeline } = require('node: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;
  }
}); copy

// 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('node:zlib');
const http = require('node:http');
const fs = require('node:fs');
const { pipeline } = require('node: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); copy

По умолчанию методы 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());
  }); copy

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

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

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

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

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

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

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

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

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

Однако это обычно ухудшит сжатие.

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

В дополнение к одному внутреннему выходному буферу размером chunkSize, который по умолчанию составляет 16 КБ.

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

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

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

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

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

См. ниже для получения более подробной информации о параметрах, специфичных для Brotli.

Сброс

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

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

const zlib = require('node:zlib');
const http = require('node:http');
const { pipeline } = require('node: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); copy

Константы

Константы zlib

Все константы, определенные в zlib.h, также определены в require('node:zlib').constants. В обычных операциях не будет необходимости использовать эти константы. Они документированы, чтобы их наличие не вызывало удивления. Этот раздел взят почти напрямую из документации zlib.

Ранее константы были доступны непосредственно из require('node: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> | <ArrayBuffer> (только для 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,
  },
}); copy

Класс: 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

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

Этот класс наследуется от stream.Transform, позволяя объектам node: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> | <Массив буферов> | <строка>
• options <опции Brotli>
• callback <Функция>

zlib.brotliCompressSync(buffer[, options])

• buffer <Буфер> | <Массив типа> | <DataView> | <Массив буферов> | <строка>
• options <опции Brotli>

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

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

• buffer <Буфер> | <Массив типа> | <DataView> | <Массив буферов> | <строка>
• options <опции Brotli>
• callback <Функция>

zlib.brotliDecompressSync(buffer[, options])

• buffer <Буфер> | <Массив типа> | <DataView> | <Массив буферов> | <строка>
• options <опции Brotli>

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

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

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

zlib.deflateSync(buffer[, options])

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

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

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

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

zlib.deflateRawSync(buffer[, options])

• buffer <Буфер> | <Массив типа> | <DataView> | <Массив буферов> | <строка>
• 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.