zlib.js

// Copyright Joyent, Inc. and other Node contributors.
//
// Permission is hereby granted, free of charge, to any person obtaining a
// copy of this software and associated documentation files (the
// "Software"), to deal in the Software without restriction, including
// without limitation the rights to use, copy, modify, merge, publish,
// distribute, sublicense, and/or sell copies of the Software, and to permit
// persons to whom the Software is furnished to do so, subject to the
// following conditions:
//
// The above copyright notice and this permission notice shall be included
// in all copies or substantial portions of the Software.
//
// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
// OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
// MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN
// NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
// DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
// OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE
// USE OR OTHER DEALINGS IN THE SOFTWARE.

'use strict';

const {
  ArrayBuffer,
  MathMax,
  MathMin,
  NumberIsNaN,
  ObjectDefineProperties,
  ObjectDefineProperty,
  ObjectEntries,
  ObjectFreeze,
  ObjectKeys,
  ReflectApply,
  SafeMap,
  Symbol,
  SymbolHasInstance,
  Uint32Array,
  Uint8Array,
} = primordials;

const {
  codes: {
    ERR_BROTLI_INVALID_PARAM,
    ERR_BUFFER_TOO_LARGE,
    ERR_INVALID_ARG_TYPE,
    ERR_OUT_OF_RANGE,
    ERR_TRAILING_JUNK_AFTER_STREAM_END,
    ERR_ZSTD_INVALID_PARAM,
  },
  genericNodeError,
} = require('internal/errors');
const { Transform, finished } = require('stream');
const {
  assignFunctionName,
  emitExperimentalWarning,
} = require('internal/util');
const {
  isArrayBufferView,
  isAnyArrayBuffer,
  isUint8Array,
} = require('internal/util/types');
const binding = internalBinding('zlib');
const { crc32: crc32Native, crc32c: crc32cNative } = binding;
const assert = require('internal/assert');
const {
  Buffer,
  kMaxLength,
} = require('buffer');
const { owner_symbol } = require('internal/async_hooks').symbols;
const {
  checkRangesOrGetDefault,
  validateBoolean,
  validateFunction,
  validateUint32,
  validateFiniteNumber,
} = require('internal/validators');
const { FastBuffer } = require('internal/buffer');
const {
  ZipEntry,
  ZipFile,
  ZipBuffer,
  createZipArchive,
  createZipArchiveSync,
  zipFiles,
  getMaxZipContentSize,
  setMaxZipContentSize,
} = require('internal/zip');

const kFlushFlag = Symbol('kFlushFlag');
const kError = Symbol('kError');
const kBufferResult = Symbol('kBufferResult');

const constants = internalBinding('constants').zlib;
const {
  // Zlib flush levels
  Z_NO_FLUSH, Z_BLOCK, Z_PARTIAL_FLUSH, Z_SYNC_FLUSH, Z_FULL_FLUSH, Z_FINISH,
  // Zlib option values
  Z_MIN_CHUNK, Z_MIN_WINDOWBITS, Z_MAX_WINDOWBITS, Z_MIN_LEVEL, Z_MAX_LEVEL,
  Z_MIN_MEMLEVEL, Z_MAX_MEMLEVEL, Z_DEFAULT_CHUNK, Z_DEFAULT_COMPRESSION,
  Z_DEFAULT_STRATEGY, Z_DEFAULT_WINDOWBITS, Z_DEFAULT_MEMLEVEL, Z_FIXED,
  // Node's compression stream modes (node_zlib_mode)
  DEFLATE, DEFLATERAW, INFLATE, INFLATERAW, GZIP, GUNZIP, UNZIP,
  BROTLI_DECODE, BROTLI_ENCODE,
  ZSTD_COMPRESS, ZSTD_DECOMPRESS,
  // Brotli operations (~flush levels)
  BROTLI_OPERATION_PROCESS, BROTLI_OPERATION_FLUSH,
  BROTLI_OPERATION_FINISH, BROTLI_OPERATION_EMIT_METADATA,
  // Zstd end directives (~flush levels)
  ZSTD_e_continue, ZSTD_e_flush, ZSTD_e_end,
} = constants;

// Translation table for return codes.
const codes = {
  Z_OK: constants.Z_OK,
  Z_STREAM_END: constants.Z_STREAM_END,
  Z_NEED_DICT: constants.Z_NEED_DICT,
  Z_ERRNO: constants.Z_ERRNO,
  Z_STREAM_ERROR: constants.Z_STREAM_ERROR,
  Z_DATA_ERROR: constants.Z_DATA_ERROR,
  Z_MEM_ERROR: constants.Z_MEM_ERROR,
  Z_BUF_ERROR: constants.Z_BUF_ERROR,
  Z_VERSION_ERROR: constants.Z_VERSION_ERROR,
};

for (const ckey of ObjectKeys(codes)) {
  codes[codes[ckey]] = ckey;
}

function zlibBuffer(engine, buffer, callback, finishInOneWrite) {
  validateFunction(callback, 'callback');
  // Streams do not support non-Uint8Array ArrayBufferViews yet. Convert it to a
  // Buffer without copying.
  if (isArrayBufferView(buffer) && !isUint8Array(buffer)) {
    buffer = Buffer.from(buffer.buffer, buffer.byteOffset, buffer.byteLength);
  } else if (isAnyArrayBuffer(buffer)) {
    buffer = Buffer.from(buffer);
  }
  engine.buffers = null;
  engine.nread = 0;
  engine.cb = callback;
  engine.on('error', zlibBufferOnError);

  // The whole input is known up front. Unless the engine is handed to the
  // caller (`info`) or a custom flush is requested, process it with the finish
  // flush directly, like the synchronous methods do. This takes one threadpool
  // round trip instead of a write followed by a separate final flush, and skips
  // the stream machinery.
  if (finishInOneWrite && !engine._info &&
      engine._defaultFlushFlag === FLUSH_BOUND[engine._flushBoundIdx][0]) {
    if (typeof buffer === 'string') {
      // Encode strings like Writable#write() does.
      buffer = Buffer.from(buffer, engine._writableState.defaultEncoding);
    }
    if (isUint8Array(buffer)) {
      engine[kBufferResult] = true;
      processChunk(engine, buffer, engine._finishFlushFlag,
                   zlibBufferOnWriteDone);
      return;
    }
  }

  engine.on('data', zlibBufferOnData);
  engine.on('end', zlibBufferOnEnd);
  engine.end(buffer);
}

function zlibBufferAddChunk(engine, chunk) {
  if (!engine.buffers) {
    engine.buffers = [chunk];
  } else {
    engine.buffers.push(chunk);
  }
  engine.nread += chunk.length;
  if (engine.nread > engine._maxOutputLength) {
    engine.close();
    engine.removeAllListeners('end');
    engine.cb(new ERR_BUFFER_TOO_LARGE(engine._maxOutputLength));
  }
}

function zlibBufferOnData(chunk) {
  zlibBufferAddChunk(this, chunk);
}

// Only the concatenated output of a one-shot call is observable, so its output
// buffer can double in size whenever it fills up, and large results take far
// fewer threadpool round trips. It never grows past what is needed to detect
// that maxOutputLength was exceeded.
const kMaxBufferResultChunkSize = 1024 * 1024;
function zlibBufferGrowChunkSize(engine) {
  const size = MathMin(engine._chunkSize * 2, kMaxBufferResultChunkSize,
                       engine._maxOutputLength - engine.nread + 1);
  if (size > engine._chunkSize)
    engine._chunkSize = size;
}

function zlibBufferOnError(err) {
  this.removeAllListeners('end');
  this.cb(err);
}

function zlibBufferFinish(engine) {
  let buf;
  if (engine.nread === 0) {
    buf = new FastBuffer();
  } else {
    const bufs = engine.buffers;
    buf = (bufs.length === 1 ? bufs[0] : Buffer.concat(bufs, engine.nread));
  }
  engine.close();
  if (engine._info)
    engine.cb(null, { buffer: buf, engine });
  else
    engine.cb(null, buf);
}

function zlibBufferOnEnd() {
  zlibBufferFinish(this);
}

// Called by processCallback(), with the handle as `this`, once the whole input
// has been processed. Errors have already been reported to the callback, either
// through the 'error' event or by zlibBufferAddChunk().
function zlibBufferOnWriteDone(err) {
  const engine = this[owner_symbol];
  if (err === undefined && !engine.destroyed)
    zlibBufferFinish(engine);
}

function toSyncInput(buffer) {
  if (typeof buffer === 'string') {
    return Buffer.from(buffer);
  }
  if (!isArrayBufferView(buffer)) {
    if (isAnyArrayBuffer(buffer)) {
      return Buffer.from(buffer);
    }
    throw new ERR_INVALID_ARG_TYPE(
      'buffer',
      ['string', 'Buffer', 'TypedArray', 'DataView', 'ArrayBuffer'],
      buffer,
    );
  }
  return buffer;
}

function zlibBufferSync(engine, buffer) {
  buffer = toSyncInput(buffer);
  buffer = processChunkSync(engine, buffer, engine._finishFlushFlag);
  if (engine._info)
    return { buffer, engine };
  return buffer;
}

function zlibError(message, errno, code) {
  if (code === 'ERR_TRAILING_JUNK_AFTER_STREAM_END') {
    return new ERR_TRAILING_JUNK_AFTER_STREAM_END();
  }
  const error = genericNodeError(message, { errno, code });
  error.errno = errno;
  error.code = code;
  return error;
}

function zlibOnError(message, errno, code) {
  const self = this[owner_symbol];
  // There is no way to cleanly recover.
  // Continuing only obscures problems.
  const error = zlibError(message, errno, code);
  self.destroy(error);
  self[kError] = error;
}

// Without options, a synchronous convenience call (zlib.inflateSync(buffer),
// ...) uses the defaults and its engine is never exposed, so it drives a
// native handle directly instead of constructing a Transform stream. It also
// decompresses into a scratch buffer kept between calls and copies the result
// out, instead of allocating a whole output chunk per call.
let syncScratchBuffer;

function zlibSyncOnError(message, errno, code) {
  this[kError] = zlibError(message, errno, code);
}

function zlibBufferSyncWithDefaults(ctor, buffer) {
  const chunk = toSyncInput(buffer);
  const mode = kEngineModes.get(ctor);
  const writeState = new Uint32Array(2);
  const handle = createDefaultHandle(mode, writeState);
  handle.onerror = zlibSyncOnError;
  // Take the scratch buffer, so that a nested call (e.g. from an async hook)
  // allocates its own.
  const scratch = syncScratchBuffer ?? Buffer.allocUnsafeSlow(Z_DEFAULT_CHUNK);
  syncScratchBuffer = undefined;
  try {
    return processSyncWithDefaults(handle, writeState, chunk,
                                   defaultFinishFlush(mode), scratch);
  } finally {
    handle.close();
    syncScratchBuffer = scratch;
  }
}

// Same as processChunkSync() for an engine created without options.
function processSyncWithDefaults(handle, writeState, chunk, flushFlag,
                                 scratch) {
  const chunkSize = Z_DEFAULT_CHUNK;
  let out = scratch;
  let inOff = 0;
  let availIn = chunk.byteLength;
  let buffers = null;
  let nread = 0;

  while (true) {
    handle.writeSync(flushFlag, chunk, inOff, availIn, out, 0, chunkSize);
    if (handle[kError] !== undefined)
      throw handle[kError];

    const availOutAfter = writeState[0];
    const availInAfter = writeState[1];
    const have = chunkSize - availOutAfter;
    if (have > 0) {
      nread += have;
      if (nread > kMaxLength)
        throw new ERR_BUFFER_TOO_LARGE(kMaxLength);
      if (out !== scratch) {
        buffers.push(out.subarray(0, have));
      } else if (availOutAfter === 0) {
        buffers = [out];
      }
    }
    if (availOutAfter !== 0)
      break;

    // The output buffer is full. Continue with the rest of the input.
    inOff += availIn - availInAfter;
    availIn = availInAfter;
    out = Buffer.allocUnsafe(chunkSize);
  }

  if (nread === 0)
    return new FastBuffer();
  if (buffers === null) {
    // All of the output is in the scratch buffer.
    const result = Buffer.allocUnsafe(nread);
    scratch.copy(result, 0, 0, nread);
    return result;
  }
  return Buffer.concat(buffers, nread);
}

const FLUSH_BOUND = [
  [ Z_NO_FLUSH, Z_BLOCK ],
  [ BROTLI_OPERATION_PROCESS, BROTLI_OPERATION_EMIT_METADATA ],
  [ ZSTD_e_continue, ZSTD_e_end ],
];
const FLUSH_BOUND_IDX_NORMAL = 0;
const FLUSH_BOUND_IDX_BROTLI = 1;
const FLUSH_BOUND_IDX_ZSTD = 2;

// If a flush is scheduled while another flush is still pending, a way to figure
// out which one is the "stronger" flush is needed.
// This is currently only used to figure out which flush flag to use for the
// last chunk.
// Roughly, the following holds:
// Z_NO_FLUSH < Z_BLOCK < Z_PARTIAL_FLUSH <
//     Z_SYNC_FLUSH < Z_FULL_FLUSH < Z_FINISH
const flushiness = [];
const kFlushFlagList = [Z_NO_FLUSH, Z_BLOCK, Z_PARTIAL_FLUSH,
                        Z_SYNC_FLUSH, Z_FULL_FLUSH, Z_FINISH];
for (let i = 0; i < kFlushFlagList.length; i++) {
  flushiness[kFlushFlagList[i]] = i;
}

function maxFlush(a, b) {
  return flushiness[a] > flushiness[b] ? a : b;
}

// Set up a list of 'special' buffers that can be written using .write()
// from the .flush() code as a way of introducing flushing operations into the
// write sequence.
const kFlushBuffers = [];
{
  const dummyArrayBuffer = new ArrayBuffer();
  for (const flushFlag of kFlushFlagList) {
    kFlushBuffers[flushFlag] = Buffer.from(dummyArrayBuffer);
    kFlushBuffers[flushFlag][kFlushFlag] = flushFlag;
  }
}

/**
 * The base class for all Zlib-style streams.
 */
class ZlibBase extends Transform {
  constructor(opts, mode, handle, { flush, finishFlush, fullFlush }) {
    let chunkSize = Z_DEFAULT_CHUNK;
    let maxOutputLength = kMaxLength;
    // The ZlibBase class is not exported to user land, the mode should only be
    // passed in by us.
    assert(typeof mode === 'number');
    assert(mode >= DEFLATE && mode <= ZSTD_DECOMPRESS);

    let flushBoundIdx;
    if (mode === BROTLI_ENCODE || mode === BROTLI_DECODE) {
      flushBoundIdx = FLUSH_BOUND_IDX_BROTLI;
    } else if (mode === ZSTD_COMPRESS || mode === ZSTD_DECOMPRESS) {
      flushBoundIdx = FLUSH_BOUND_IDX_ZSTD;
    } else {
      flushBoundIdx = FLUSH_BOUND_IDX_NORMAL;
    }

    if (opts) {
      chunkSize = opts.chunkSize;
      if (!validateFiniteNumber(chunkSize, 'options.chunkSize')) {
        chunkSize = Z_DEFAULT_CHUNK;
      } else if (chunkSize < Z_MIN_CHUNK) {
        throw new ERR_OUT_OF_RANGE('options.chunkSize',
                                   `>= ${Z_MIN_CHUNK}`, chunkSize);
      }

      flush = checkRangesOrGetDefault(
        opts.flush, 'options.flush',
        FLUSH_BOUND[flushBoundIdx][0], FLUSH_BOUND[flushBoundIdx][1], flush);

      finishFlush = checkRangesOrGetDefault(
        opts.finishFlush, 'options.finishFlush',
        FLUSH_BOUND[flushBoundIdx][0], FLUSH_BOUND[flushBoundIdx][1],
        finishFlush);

      maxOutputLength = checkRangesOrGetDefault(
        opts.maxOutputLength, 'options.maxOutputLength',
        1, kMaxLength, kMaxLength);

      if (opts.rejectGarbageAfterEnd !== undefined) {
        validateBoolean(
          opts.rejectGarbageAfterEnd,
          'options.rejectGarbageAfterEnd',
        );
      }

      if (opts.encoding || opts.objectMode || opts.writableObjectMode ||
          opts.decodeStrings === false) {
        opts = { ...opts };
        opts.encoding = null;
        opts.objectMode = false;
        opts.writableObjectMode = false;
        opts.decodeStrings = true;
      }
    }

    super({ autoDestroy: true, ...opts });
    this[kError] = null;
    this.bytesWritten = 0;
    this._handle = handle;
    handle[owner_symbol] = this;
    // Used by processCallback() and zlibOnError()
    handle.onerror = zlibOnError;
    this._outBuffer = Buffer.allocUnsafe(chunkSize);
    this._outOffset = 0;

    this._chunkSize = chunkSize;
    this._defaultFlushFlag = flush;
    this._finishFlushFlag = finishFlush;
    this._defaultFullFlushFlag = fullFlush;
    this._flushBoundIdx = flushBoundIdx;
    this._info = opts?.info;
    this._maxOutputLength = maxOutputLength;

    this._rejectGarbageAfterEnd = opts?.rejectGarbageAfterEnd === true;
  }

  get _closed() {
    return !this._handle;
  }

  reset() {
    assert(this._handle, 'zlib binding closed');
    return this._handle.reset();
  }

  /**
   * This is the _flush function called by the transform class,
   * internally, when the last chunk has been written.
   * @returns {void}
   */
  _flush(callback) {
    this._transform(new FastBuffer(), '', callback);
  }

  /**
   * Force Transform compat behavior.
   * @returns {void}
   */
  _final(callback) {
    callback();
  }

  flush(kind, callback) {
    if (typeof kind === 'function' || (kind === undefined && !callback)) {
      callback = kind;
      kind = this._defaultFullFlushFlag;
    }

    kind = checkRangesOrGetDefault(
      kind, 'kind',
      FLUSH_BOUND[this._flushBoundIdx][0], FLUSH_BOUND[this._flushBoundIdx][1],
      this._defaultFullFlushFlag);

    if (this.writableFinished) {
      if (callback)
        process.nextTick(callback);
    } else if (this.writableEnded) {
      if (callback)
        this.once('end', callback);
    } else {
      this.write(kFlushBuffers[kind], '', callback);
    }
  }

  /**
   * @param {(err?: Error) => any} [callback]
   */
  close(callback) {
    if (callback) finished(this, callback);
    this.destroy();
  }

  _destroy(err, callback) {
    _close(this);
    callback(err);
  }

  _transform(chunk, encoding, cb) {
    let flushFlag = this._defaultFlushFlag;
    // We use a 'fake' zero-length chunk to carry information about flushes from
    // the public API to the actual stream implementation.
    if (typeof chunk[kFlushFlag] === 'number') {
      flushFlag = chunk[kFlushFlag];
    }

    // For the last chunk, also apply `_finishFlushFlag`.
    if (this.writableEnded && this.writableLength === chunk.byteLength) {
      flushFlag = maxFlush(flushFlag, this._finishFlushFlag);
    }
    processChunk(this, chunk, flushFlag, cb);
  }

  _processChunk(chunk, flushFlag, cb) {
    // _processChunk() is left for backwards compatibility
    if (typeof cb === 'function')
      processChunk(this, chunk, flushFlag, cb);
    else
      return processChunkSync(this, chunk, flushFlag);
  }
}

function processChunkSync(self, chunk, flushFlag) {
  let availInBefore = chunk.byteLength;
  let availOutBefore = self._chunkSize - self._outOffset;
  let inOff = 0;
  let availOutAfter;
  let availInAfter;

  const buffers = [];
  let nread = 0;
  let inputRead = 0;
  const state = self._writeState;
  const handle = self._handle;
  let buffer = self._outBuffer;
  let offset = self._outOffset;
  const chunkSize = self._chunkSize;

  let error;
  self.on('error', function onError(er) {
    error = er;
  });

  while (true) {
    handle.writeSync(flushFlag,
                     chunk, // in
                     inOff, // in_off
                     availInBefore, // in_len
                     buffer, // out
                     offset, // out_off
                     availOutBefore); // out_len
    if (error)
      throw error;
    else if (self[kError])
      throw self[kError];

    availOutAfter = state[0];
    availInAfter = state[1];

    const inDelta = (availInBefore - availInAfter);
    inputRead += inDelta;

    const have = availOutBefore - availOutAfter;
    if (have > 0) {
      const out = buffer.slice(offset, offset + have);
      offset += have;
      buffers.push(out);
      nread += out.byteLength;

      if (nread > self._maxOutputLength) {
        _close(self);
        throw new ERR_BUFFER_TOO_LARGE(self._maxOutputLength);
      }

    } else {
      assert(have === 0, 'have should not go down');
    }

    // Exhausted the output buffer, or used all the input create a new one.
    if (availOutAfter === 0 || offset >= chunkSize) {
      availOutBefore = chunkSize;
      offset = 0;
      buffer = Buffer.allocUnsafe(chunkSize);
    }

    if (availOutAfter === 0) {
      // Not actually done. Need to reprocess.
      // Also, update the availInBefore to the availInAfter value,
      // so that if we have to hit it a third (fourth, etc.) time,
      // it'll have the correct byte counts.
      inOff += inDelta;
      availInBefore = availInAfter;
    } else {
      break;
    }
  }

  if (availInAfter > 0 && self._rejectGarbageAfterEnd) {
    _close(self);
    throw new ERR_TRAILING_JUNK_AFTER_STREAM_END();
  }

  self.bytesWritten = inputRead;
  _close(self);

  if (nread === 0)
    return new FastBuffer();

  return (buffers.length === 1 ? buffers[0] : Buffer.concat(buffers, nread));
}

function processChunk(self, chunk, flushFlag, cb) {
  const handle = self._handle;
  if (!handle) return process.nextTick(cb);

  handle.buffer = chunk;
  handle.cb = cb;
  handle.availOutBefore = self._chunkSize - self._outOffset;
  handle.availInBefore = chunk.byteLength;
  handle.inOff = 0;
  handle.flushFlag = flushFlag;

  handle.write(flushFlag,
               chunk, // in
               0, // in_off
               handle.availInBefore, // in_len
               self._outBuffer, // out
               self._outOffset, // out_off
               handle.availOutBefore); // out_len
}

function processCallback() {
  // This callback's context (`this`) is the `_handle` (ZCtx) object. It is
  // important to null out the values once they are no longer needed since
  // `_handle` can stay in memory long after the buffer is needed.
  const handle = this;
  const self = this[owner_symbol];
  const state = self._writeState;

  if (self.destroyed) {
    this.buffer = null;
    this.cb();
    return;
  }

  const availOutAfter = state[0];
  const availInAfter = state[1];

  const inDelta = handle.availInBefore - availInAfter;
  self.bytesWritten += inDelta;

  const have = handle.availOutBefore - availOutAfter;
  let streamBufferIsFull = false;
  if (have > 0) {
    const out = self._outBuffer.slice(self._outOffset, self._outOffset + have);
    self._outOffset += have;
    if (self[kBufferResult] === true)
      zlibBufferAddChunk(self, out);
    else
      streamBufferIsFull = !self.push(out);
  } else {
    assert(have === 0, 'have should not go down');
  }

  if (self.destroyed) {
    this.cb();
    return;
  }

  // Exhausted the output buffer, or used all the input create a new one.
  if (availOutAfter === 0 || self._outOffset >= self._chunkSize) {
    if (availOutAfter === 0 && self[kBufferResult] === true)
      zlibBufferGrowChunkSize(self);
    handle.availOutBefore = self._chunkSize;
    self._outOffset = 0;
    self._outBuffer = Buffer.allocUnsafe(self._chunkSize);
  }

  if (availOutAfter === 0) {
    // Not actually done. Need to reprocess.
    // Also, update the availInBefore to the availInAfter value,
    // so that if we have to hit it a third (fourth, etc.) time,
    // it'll have the correct byte counts.
    handle.inOff += inDelta;
    handle.availInBefore = availInAfter;


    if (!streamBufferIsFull) {
      this.write(handle.flushFlag,
                 this.buffer, // in
                 handle.inOff, // in_off
                 handle.availInBefore, // in_len
                 self._outBuffer, // out
                 self._outOffset, // out_off
                 self._chunkSize); // out_len
    } else {
      const oldRead = self._read;
      self._read = (n) => {
        self._read = oldRead;
        this.write(handle.flushFlag,
                   this.buffer, // in
                   handle.inOff, // in_off
                   handle.availInBefore, // in_len
                   self._outBuffer, // out
                   self._outOffset, // out_off
                   self._chunkSize); // out_len
        self._read(n);
      };
    }
    return;
  }

  if (availInAfter > 0) {
    // If we have more input that should be written, but we also have output
    // space available, that means that the compression library was not
    // interested in receiving more data, and in particular that the input
    // stream has ended early.
    // This applies to streams where we don't check data past the end of
    // what was consumed; that is, everything except Gunzip/Unzip.

    if (self._rejectGarbageAfterEnd) {
      const err = new ERR_TRAILING_JUNK_AFTER_STREAM_END();
      self.destroy(err);
      this.cb(err);
      return;
    }

    if (self[kBufferResult] !== true)
      self.push(null);
  }

  // Finished with the chunk.
  this.buffer = null;
  this.cb();
}

/**
 * @param {ZlibBase} engine
 * @private
 */
function _close(engine) {
  // Caller may invoke .close after a zlib error (which will null _handle)
  engine._handle?.close();
  engine._handle = null;
}

const zlibDefaultOpts = {
  flush: Z_NO_FLUSH,
  finishFlush: Z_FINISH,
  fullFlush: Z_FULL_FLUSH,
};

// This callback is used by `.params()` to wait until a full flush happened
// before adjusting the parameters. In particular, the call to the native
// `params()` function should not happen while a write is currently in progress
// on the threadpool.
function paramsAfterFlushCallback(level, strategy, callback) {
  assert(this._handle, 'zlib binding closed');
  this._handle.params(level, strategy);
  if (!this.destroyed) {
    this._level = level;
    this._strategy = strategy;
    if (callback) callback();
  }
}

// Base class for all streams actually backed by zlib and using zlib-specific
// parameters.
class Zlib extends ZlibBase {
  constructor(opts, mode) {
    let windowBits = Z_DEFAULT_WINDOWBITS;
    let level = Z_DEFAULT_COMPRESSION;
    let memLevel = Z_DEFAULT_MEMLEVEL;
    let strategy = Z_DEFAULT_STRATEGY;
    let dictionary;

    if (opts) {
      // windowBits is special. On the compression side, 0 is an invalid value.
      // But on the decompression side, a value of 0 for windowBits tells zlib
      // to use the window size in the zlib header of the compressed stream.
      if ((opts.windowBits == null || opts.windowBits === 0) &&
          (mode === INFLATE ||
           mode === GUNZIP ||
           mode === UNZIP)) {
        windowBits = 0;
      } else {
        // `{ windowBits: 8 }` is valid for deflate but not gzip.
        const min = Z_MIN_WINDOWBITS + (mode === GZIP ? 1 : 0);
        windowBits = checkRangesOrGetDefault(
          opts.windowBits, 'options.windowBits',
          min, Z_MAX_WINDOWBITS, Z_DEFAULT_WINDOWBITS);
      }

      level = checkRangesOrGetDefault(
        opts.level, 'options.level',
        Z_MIN_LEVEL, Z_MAX_LEVEL, Z_DEFAULT_COMPRESSION);

      memLevel = checkRangesOrGetDefault(
        opts.memLevel, 'options.memLevel',
        Z_MIN_MEMLEVEL, Z_MAX_MEMLEVEL, Z_DEFAULT_MEMLEVEL);

      strategy = checkRangesOrGetDefault(
        opts.strategy, 'options.strategy',
        Z_DEFAULT_STRATEGY, Z_FIXED, Z_DEFAULT_STRATEGY);

      dictionary = opts.dictionary;
      if (dictionary !== undefined && !isArrayBufferView(dictionary)) {
        if (isAnyArrayBuffer(dictionary)) {
          dictionary = Buffer.from(dictionary);
        } else {
          throw new ERR_INVALID_ARG_TYPE(
            'options.dictionary',
            ['Buffer', 'TypedArray', 'DataView', 'ArrayBuffer'],
            dictionary,
          );
        }
      }
    }

    const handle = new binding.Zlib(mode);
    // Ideally, we could let ZlibBase() set up _writeState. I haven't been able
    // to come up with a good solution that doesn't break our internal API,
    // and with it all supported npm versions at the time of writing.
    const writeState = new Uint32Array(2);
    handle.init(windowBits,
                level,
                memLevel,
                strategy,
                writeState,
                processCallback,
                dictionary,
                opts?.rejectGarbageAfterEnd === true);

    super(opts, mode, handle, zlibDefaultOpts);

    this._writeState = writeState;
    this._level = level;
    this._strategy = strategy;
    this._mode = mode;
  }

  params(level, strategy, callback) {
    checkRangesOrGetDefault(level, 'level', Z_MIN_LEVEL, Z_MAX_LEVEL);
    checkRangesOrGetDefault(strategy, 'strategy', Z_DEFAULT_STRATEGY, Z_FIXED);

    if (this._level !== level || this._strategy !== strategy) {
      this.flush(
        Z_SYNC_FLUSH,
        paramsAfterFlushCallback.bind(this, level, strategy, callback),
      );
    } else {
      process.nextTick(callback);
    }
  }
}

// generic zlib
// minimal 2-byte header
class Deflate extends Zlib {
  constructor(opts) {
    super(opts, DEFLATE);
  }
}

class Inflate extends Zlib {
  constructor(opts) {
    super(opts, INFLATE);
  }
}

class Gzip extends Zlib {
  constructor(opts) {
    super(opts, GZIP);
  }
}

class Gunzip extends Zlib {
  constructor(opts) {
    super(opts, GUNZIP);
  }
}

class DeflateRaw extends Zlib {
  constructor(opts) {
    if (opts && opts.windowBits === 8) opts.windowBits = 9;
    super(opts, DEFLATERAW);
  }
}

class InflateRaw extends Zlib {
  constructor(opts) {
    super(opts, INFLATERAW);
  }
}

class Unzip extends Zlib {
  constructor(opts) {
    super(opts, UNZIP);
  }
}

function createConvenienceMethod(ctor, sync, prepareOpts,
                                 finishInOneWrite = true) {
  if (sync) {
    return function syncBufferWrapper(buffer, opts) {
      if (opts === undefined)
        return zlibBufferSyncWithDefaults(ctor, buffer);
      return zlibBufferSync(new ctor(opts), buffer);
    };
  }
  return function asyncBufferWrapper(buffer, opts, callback) {
    if (typeof opts === 'function') {
      callback = opts;
      opts = {};
    }
    if (prepareOpts !== undefined) {
      opts = prepareOpts(buffer, opts);
    }
    return zlibBuffer(new ctor(opts), buffer, callback, finishInOneWrite);
  };
}

// zstdCompress() writes the input and ends the frame in separate calls, so
// unlike zstdCompressSync() zstd cannot infer the input size and sizes its
// tables for an unbounded stream. Pledge the size, which is known up front.
function withPledgedSrcSize(buffer, opts) {
  if (opts?.pledgedSrcSize !== undefined) {
    return opts;
  }
  let pledgedSrcSize;
  if (typeof buffer === 'string') {
    // The stream encodes strings with defaultEncoding, so only a UTF-8 length
    // is known to match what gets written.
    const encoding = opts?.defaultEncoding;
    if (encoding != null && encoding !== 'utf8' && encoding !== 'utf-8') {
      return opts;
    }
    pledgedSrcSize = Buffer.byteLength(buffer);
  } else if (isArrayBufferView(buffer) || isAnyArrayBuffer(buffer)) {
    pledgedSrcSize = buffer.byteLength;
  } else {
    // Leave invalid input to the existing validation.
    return opts;
  }
  return { __proto__: null, ...opts, pledgedSrcSize };
}

const kMaxBrotliParam = MathMax(
  ...ObjectEntries(constants)
    .map(({ 0: key, 1: value }) => (key.startsWith('BROTLI_PARAM_') ? value : 0)),
);
const brotliInitParamsArray = new Uint32Array(kMaxBrotliParam + 1);

const brotliDefaultOpts = {
  flush: BROTLI_OPERATION_PROCESS,
  finishFlush: BROTLI_OPERATION_FINISH,
  fullFlush: BROTLI_OPERATION_FLUSH,
};

class Brotli extends ZlibBase {
  constructor(opts, mode) {
    assert(mode === BROTLI_DECODE || mode === BROTLI_ENCODE);

    brotliInitParamsArray.fill(-1);
    if (opts?.params) {
      ObjectKeys(opts.params).forEach((origKey) => {
        const key = +origKey;
        if (NumberIsNaN(key) || key < 0 || key > kMaxBrotliParam ||
            (brotliInitParamsArray[key] | 0) !== -1) {
          throw new ERR_BROTLI_INVALID_PARAM(origKey);
        }

        const value = opts.params[origKey];
        if (typeof value !== 'number' && typeof value !== 'boolean') {
          throw new ERR_INVALID_ARG_TYPE('options.params[key]',
                                         'number', opts.params[origKey]);
        }
        brotliInitParamsArray[key] = value;
      });
    }

    let dictionary = opts?.dictionary;
    if (dictionary !== undefined && !isArrayBufferView(dictionary)) {
      if (isAnyArrayBuffer(dictionary)) {
        dictionary = Buffer.from(dictionary);
      } else {
        throw new ERR_INVALID_ARG_TYPE(
          'options.dictionary',
          ['Buffer', 'TypedArray', 'DataView', 'ArrayBuffer'],
          dictionary,
        );
      }
    }

    const handle = mode === BROTLI_DECODE ?
      new binding.BrotliDecoder(mode) : new binding.BrotliEncoder(mode);

    const writeState = new Uint32Array(2);
    handle.init(
      brotliInitParamsArray,
      writeState,
      processCallback,
      dictionary,
    );

    super(opts, mode, handle, brotliDefaultOpts);
    this._writeState = writeState;
  }
}

class BrotliCompress extends Brotli {
  constructor(opts) {
    super(opts, BROTLI_ENCODE);
  }
}

class BrotliDecompress extends Brotli {
  constructor(opts) {
    super(opts, BROTLI_DECODE);
  }
}


const zstdDefaultOpts = {
  flush: ZSTD_e_continue,
  finishFlush: ZSTD_e_end,
  fullFlush: ZSTD_e_flush,
};
class Zstd extends ZlibBase {
  constructor(opts, mode, initParamsArray, maxParam) {
    assert(mode === ZSTD_COMPRESS || mode === ZSTD_DECOMPRESS);

    initParamsArray.fill(-1);
    if (opts?.params) {
      ObjectKeys(opts.params).forEach((origKey) => {
        const key = +origKey;
        if (NumberIsNaN(key) || key < 0 || key > maxParam ||
            (initParamsArray[key] | 0) !== -1) {
          throw new ERR_ZSTD_INVALID_PARAM(origKey);
        }

        const value = opts.params[origKey];
        if (typeof value !== 'number' && typeof value !== 'boolean') {
          throw new ERR_INVALID_ARG_TYPE('options.params[key]',
                                         'number', opts.params[origKey]);
        }
        initParamsArray[key] = value;
      });
    }

    let dictionary = opts?.dictionary;
    if (dictionary !== undefined && !isArrayBufferView(dictionary)) {
      if (isAnyArrayBuffer(dictionary)) {
        dictionary = new Uint8Array(dictionary);
      } else {
        throw new ERR_INVALID_ARG_TYPE(
          'options.dictionary',
          ['Buffer', 'TypedArray', 'DataView', 'ArrayBuffer'],
          dictionary,
        );
      }
    }

    const handle = mode === ZSTD_COMPRESS ?
      new binding.ZstdCompress() : new binding.ZstdDecompress();

    const pledgedSrcSize = opts?.pledgedSrcSize;

    const writeState = new Uint32Array(2);

    handle.init(
      initParamsArray,
      pledgedSrcSize,
      writeState,
      processCallback,
      dictionary,
      opts?.rejectGarbageAfterEnd === true,
    );

    super(opts, mode, handle, zstdDefaultOpts);
    this._writeState = writeState;
  }
}

const kMaxZstdCParam = MathMax(...ObjectKeys(constants).map(
  (key) => (key.startsWith('ZSTD_c_') ?
    constants[key] :
    0),
));

const zstdInitCParamsArray = new Uint32Array(kMaxZstdCParam + 1);

class ZstdCompress extends Zstd {
  constructor(opts) {
    super(opts, ZSTD_COMPRESS, zstdInitCParamsArray, kMaxZstdCParam);
  }
}

const kMaxZstdDParam = MathMax(...ObjectKeys(constants).map(
  (key) => (key.startsWith('ZSTD_d_') ?
    constants[key] :
    0),
));

const zstdInitDParamsArray = new Uint32Array(kMaxZstdDParam + 1);

class ZstdDecompress extends Zstd {
  constructor(opts) {
    super(opts, ZSTD_DECOMPRESS, zstdInitDParamsArray, kMaxZstdDParam);
  }
}

const kEngineModes = new SafeMap([
  [Deflate, DEFLATE],
  [Inflate, INFLATE],
  [Gzip, GZIP],
  [Gunzip, GUNZIP],
  [DeflateRaw, DEFLATERAW],
  [InflateRaw, INFLATERAW],
  [Unzip, UNZIP],
  [BrotliCompress, BROTLI_ENCODE],
  [BrotliDecompress, BROTLI_DECODE],
  [ZstdCompress, ZSTD_COMPRESS],
  [ZstdDecompress, ZSTD_DECOMPRESS],
]);

// Creates the native handle that the engine for `mode` creates when its
// constructor gets no options.
function createDefaultHandle(mode, writeState) {
  let handle;
  switch (mode) {
    case BROTLI_ENCODE:
    case BROTLI_DECODE:
      handle = mode === BROTLI_DECODE ?
        new binding.BrotliDecoder(mode) : new binding.BrotliEncoder(mode);
      brotliInitParamsArray.fill(-1);
      handle.init(brotliInitParamsArray, writeState, processCallback, undefined);
      return handle;
    case ZSTD_COMPRESS:
      zstdInitCParamsArray.fill(-1);
      handle = new binding.ZstdCompress();
      handle.init(zstdInitCParamsArray, undefined, writeState, processCallback,
                  undefined, false);
      return handle;
    case ZSTD_DECOMPRESS:
      zstdInitDParamsArray.fill(-1);
      handle = new binding.ZstdDecompress();
      handle.init(zstdInitDParamsArray, undefined, writeState, processCallback,
                  undefined, false);
      return handle;
    default:
      handle = new binding.Zlib(mode);
      handle.init(Z_DEFAULT_WINDOWBITS, Z_DEFAULT_COMPRESSION,
                  Z_DEFAULT_MEMLEVEL, Z_DEFAULT_STRATEGY, writeState,
                  processCallback, undefined, false);
      return handle;
  }
}

function defaultFinishFlush(mode) {
  if (mode === BROTLI_ENCODE || mode === BROTLI_DECODE)
    return brotliDefaultOpts.finishFlush;
  if (mode === ZSTD_COMPRESS || mode === ZSTD_DECOMPRESS)
    return zstdDefaultOpts.finishFlush;
  return zlibDefaultOpts.finishFlush;
}

function createProperty(ctor) {
  return {
    __proto__: null,
    configurable: true,
    enumerable: true,
    value: assignFunctionName(`create${ctor.name}`, function(options) {
      return new ctor(options);
    }),
  };
}

// ZIP archive support is experimental. The warning fires when the API is
// *used*, not when node:zlib is imported: the ESM facade reads every export to
// build its bindings (see BuiltinModule.syncExports), so warning on property
// access would fire on a bare `import 'node:zlib'`. Each public class is a thin
// subclass whose factory methods (and, for ZipBuffer, its constructor) warn;
// each function is a warn-on-call wrapper. A `[Symbol.hasInstance]` override
// keeps `instanceof` matching instances produced by the internal (unwrapped)
// implementation. The rest of node:zlib is stable and never warns.
function emitZipExperimentalWarning() {
  emitExperimentalWarning('The zlib ZIP archive API');
}

function experimentalZipFunction(fn, thisArg) {
  return function(...args) {
    emitZipExperimentalWarning();
    return ReflectApply(fn, thisArg, args);
  };
}

function experimentalZipProperty(value) {
  return { __proto__: null, configurable: true, enumerable: true, value };
}

// Thin subclasses that gate *use* of the experimental ZIP API behind the
// warning while leaving `instanceof` (and the public class name) intact.
class ExperimentalZipEntry extends ZipEntry {
  static [SymbolHasInstance](instance) { return instance instanceof ZipEntry; }
}

class ExperimentalZipFile extends ZipFile {
  static [SymbolHasInstance](instance) { return instance instanceof ZipFile; }
}

class ExperimentalZipBuffer extends ZipBuffer {
  static [SymbolHasInstance](instance) { return instance instanceof ZipBuffer; }
  constructor(buffer) { emitZipExperimentalWarning(); super(buffer); }
}

// Shadow each public factory with a warn-on-call wrapper, and restore the
// public class name that subclassing changed.
for (const { 0: Wrapper, 1: Raw, 2: factories } of [
  [ExperimentalZipEntry, ZipEntry, ['read', 'create', 'createSync', 'createStream', 'createSymlink']],
  [ExperimentalZipFile, ZipFile, ['open', 'openSync']],
  [ExperimentalZipBuffer, ZipBuffer, []],
]) {
  for (const name of factories) {
    ObjectDefineProperty(Wrapper, name, {
      __proto__: null,
      configurable: true,
      writable: true,
      value: experimentalZipFunction(Raw[name], Raw),
    });
  }
  ObjectDefineProperty(Wrapper, 'name', { __proto__: null, value: Raw.name });
}

function crc32(data, value = 0) {
  if (typeof data !== 'string' && !isArrayBufferView(data)) {
    throw new ERR_INVALID_ARG_TYPE('data', ['Buffer', 'TypedArray', 'DataView', 'string'], data);
  }
  validateUint32(value, 'value');
  // Coerce -0 to +0.
  value += 0;
  return crc32Native(data, value);
}

function crc32c(data, value = 0) {
  if (typeof data !== 'string' && !isArrayBufferView(data)) {
    throw new ERR_INVALID_ARG_TYPE('data', ['Buffer', 'TypedArray', 'DataView', 'string'], data);
  }
  validateUint32(value, 'value');
  // Coerce -0 to +0.
  value += 0;
  return crc32cNative(data, value);
}

// Legacy alias on the C++ wrapper object. This is not public API, so we may
// want to runtime-deprecate it at some point. There's no hurry, though.
ObjectDefineProperty(binding.Zlib.prototype, 'jsref', {
  __proto__: null,
  get() { return this[owner_symbol]; },
  set(v) { return this[owner_symbol] = v; },
});

module.exports = {
  crc32,
  crc32c,
  Deflate,
  Inflate,
  Gzip,
  Gunzip,
  DeflateRaw,
  InflateRaw,
  Unzip,
  BrotliCompress,
  BrotliDecompress,
  ZstdCompress,
  ZstdDecompress,

  // Convenience methods.
  // compress/decompress a string or buffer in one step.
  deflate: createConvenienceMethod(Deflate, false),
  deflateSync: createConvenienceMethod(Deflate, true),
  gzip: createConvenienceMethod(Gzip, false),
  gzipSync: createConvenienceMethod(Gzip, true),
  deflateRaw: createConvenienceMethod(DeflateRaw, false),
  deflateRawSync: createConvenienceMethod(DeflateRaw, true),
  unzip: createConvenienceMethod(Unzip, false),
  unzipSync: createConvenienceMethod(Unzip, true),
  inflate: createConvenienceMethod(Inflate, false),
  inflateSync: createConvenienceMethod(Inflate, true),
  gunzip: createConvenienceMethod(Gunzip, false),
  gunzipSync: createConvenienceMethod(Gunzip, true),
  inflateRaw: createConvenienceMethod(InflateRaw, false),
  inflateRawSync: createConvenienceMethod(InflateRaw, true),
  brotliCompress: createConvenienceMethod(BrotliCompress, false),
  brotliCompressSync: createConvenienceMethod(BrotliCompress, true),
  brotliDecompress: createConvenienceMethod(BrotliDecompress, false),
  brotliDecompressSync: createConvenienceMethod(BrotliDecompress, true),
  // A zstd frame written by a single ZSTD_e_end call can be a few bytes larger
  // than one written by ZSTD_e_continue followed by ZSTD_e_end, so
  // zstdCompress() keeps writing the input and ending the frame separately.
  zstdCompress: createConvenienceMethod(ZstdCompress, false, withPledgedSrcSize,
                                        false),
  zstdCompressSync: createConvenienceMethod(ZstdCompress, true),
  zstdDecompress: createConvenienceMethod(ZstdDecompress, false),
  zstdDecompressSync: createConvenienceMethod(ZstdDecompress, true),
};

ObjectDefineProperties(module.exports, {
  createDeflate: createProperty(Deflate),
  createInflate: createProperty(Inflate),
  createDeflateRaw: createProperty(DeflateRaw),
  createInflateRaw: createProperty(InflateRaw),
  createGzip: createProperty(Gzip),
  createGunzip: createProperty(Gunzip),
  createUnzip: createProperty(Unzip),
  createBrotliCompress: createProperty(BrotliCompress),
  createBrotliDecompress: createProperty(BrotliDecompress),
  createZstdCompress: createProperty(ZstdCompress),
  createZstdDecompress: createProperty(ZstdDecompress),
  constants: {
    __proto__: null,
    configurable: false,
    enumerable: true,
    value: constants,
  },
  codes: {
    __proto__: null,
    enumerable: true,
    writable: false,
    value: ObjectFreeze(codes),
  },

  // ZIP archive support (experimental).
  ZipEntry: experimentalZipProperty(ExperimentalZipEntry),
  ZipFile: experimentalZipProperty(ExperimentalZipFile),
  ZipBuffer: experimentalZipProperty(ExperimentalZipBuffer),
  createZipArchive: experimentalZipProperty(experimentalZipFunction(createZipArchive)),
  createZipArchiveSync: experimentalZipProperty(experimentalZipFunction(createZipArchiveSync)),
  zipFiles: experimentalZipProperty(experimentalZipFunction(zipFiles)),
  getMaxZipContentSize: experimentalZipProperty(experimentalZipFunction(getMaxZipContentSize)),
  setMaxZipContentSize: experimentalZipProperty(experimentalZipFunction(setMaxZipContentSize)),
});

// These should be considered deprecated
// expose all the zlib constants
for (const { 0: key, 1: value } of ObjectEntries(constants)) {
  if (key.startsWith('BROTLI')) continue;
  ObjectDefineProperty(module.exports, key, {
    __proto__: null,
    enumerable: false,
    value,
    writable: false,
  });
}