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

Все 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:

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

См. ниже для получения дополнительной информации о специфичных для 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> | <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
  }
});

Класс: zlib.BrotliCompress

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

Класс: zlib.BrotliDecompress

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

Класс: zlib.Deflate

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

Класс: zlib.DeflateRaw

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

Класс: zlib.Gunzip

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

Класс: zlib.Gzip

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

Класс: zlib.Inflate

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

Класс: zlib.InflateRaw

Распаковать сырой 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 <Буфер> | <Тип массива> | <DataView> | <Массив байтов> | <строка>
• options <опции zlib>

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

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

• buffer <Buffer> | <Тип массива> | <DataView> | <Массив байтов> | <строка>
• options <опции zlib>
• callback <Функция>

zlib.unzipSync(buffer[, options])

• buffer <Buffer> | <Тип массива> | <DataView> | <Массив байтов> | <строка>
• options <опции zlib>

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