HTTP Proxy Response Rewrite

Common errors

• TypeError: Cannot read properties of undefined (reading 'on') or similar errors related to `gzip` or `deflate`.

  cause This error often occurs when the `Content-Encoding` header from the proxied response is not 'gzip' or 'deflate', and the `modifyResponse` function tries to initialize a zlib stream for an unsupported or missing encoding.
  fix Verify that the `proxyRes.headers['content-encoding']` is correctly set by the target server and is either 'gzip' or 'deflate' or completely absent (for uncompressed). If the target sends an unsupported encoding, the library will fail.

• Error: premature close or similar stream-related errors.

  cause These errors can arise if the response stream is closed prematurely or handled incorrectly after modification, especially if the `modifyResponse` callback takes too long or encounters an error before the stream operations are complete.
  fix Ensure that your modification logic within the `modifyResponse` callback is robust and handles all potential data states (e.g., empty body, invalid JSON). Also, confirm that `http-proxy` and Node.js `http` stream handling are correctly configured and not being interfered with by other middleware.

Warnings

• deprecated The package `http-proxy-response-rewrite` is effectively abandoned. It has not received updates in approximately 8 years and is stuck at version 0.0.1. It is not recommended for new projects and existing projects should seek alternatives for security and maintenance reasons.
  Fix: Consider using newer and actively maintained proxy middleware solutions like `http-proxy-middleware` which offer response interception and manipulation capabilities, often with better support for various compression types and modern JavaScript features.
• gotcha This library only supports `gzip`, `deflate`, and uncompressed response bodies for modification. If the upstream server uses other compression formats (e.g., Brotli), this library will not be able to decompress and modify the response, potentially leading to corrupt or unhandled data.
  Fix: Ensure your upstream server's `Content-Encoding` header matches one of the supported formats. For unsupported formats, you would need to implement custom decompression logic or use an alternative library with broader support. Modern alternatives like `http-proxy-middleware` often include Brotli support.
• gotcha The `modifyResponse` callback expects a string or null return. If the callback function returns an `undefined` value, the `http-proxy` might send an empty or incomplete response to the client, leading to unexpected behavior in client-side applications.
  Fix: Always ensure the callback function passed to `modifyResponse` explicitly returns the modified body (as a string) or the original `body` if no modification is needed. Return `null` only if you intend to send an empty response body.

Install

• npm install http-proxy-response-rewrite npm
• yarn add http-proxy-response-rewrite yarn
• pnpm add http-proxy-response-rewrite pnpm

Imports

• modifyResponse
  wrong:

  const modifyResponse = require('http-proxy-response-rewrite/index.js');

  correct:

  import modifyResponse from 'http-proxy-response-rewrite';

  While the examples use `require('../')`, for an installed package, the correct CommonJS import is `require('http-proxy-response-rewrite')`. For modern Node.js environments supporting ESM, use the `import` statement.

Quickstart

This quickstart demonstrates setting up an HTTP proxy to intercept and modify a gzipped JSON response from a target server. It parses the body, changes an attribute, deletes another, and then re-serializes and re-compresses the response.

const zlib = require('zlib');
const http = require('http');
const httpProxy = require('http-proxy');
const modifyResponse = require('http-proxy-response-rewrite');

// Create a proxy server
const proxy = httpProxy.createProxyServer({
    target: 'http://localhost:5001'
});

// Listen for the `proxyRes` event on `proxy` to modify responses
proxy.on('proxyRes', function (proxyRes, req, res) {
    modifyResponse(res, proxyRes.headers['content-encoding'], function (body) {
        if (body) {
            // Modify the response body (e.g., JSON manipulation)
            let modifiedBody = JSON.parse(body);
            modifiedBody.age = 2;
            delete modifiedBody.version;
            return JSON.stringify(modifiedBody);
        }
        return body;
    });
});

// Create your server and then proxies the request
const server = http.createServer(function (req, res) {
    proxy.web(req, res);
}).listen(5000, () => console.log('Proxy server listening on port 5000'));

// Create a target server with gzipped content
const targetServer = http.createServer(function (req, res) {
    const gzip = zlib.createGzip();
    const _write = res.write;
    const _end = res.end;

    gzip.on('data', function (buf) {
        _write.call(res, buf);
    });
    gzip.on('end', function () {
        _end.call(res);
    });

    res.write = function (data) {
        gzip.write(data);
    };
    res.end = function () {
        gzip.end();
    };

    res.writeHead(200, {'Content-Type': 'application/json', 'Content-Encoding': 'gzip'});
    res.write(JSON.stringify({name: 'http-proxy-json', age: 1, version: '1.0.0'}));
    res.end();
}).listen(5001, () => console.log('Target server listening on port 5001'));