HTTP Proxy Rules for Node-HTTP-Proxy

Common errors

• The request url and path did not match any of the listed rules!

  cause This message indicates that the incoming HTTP request URL path did not match any of the regular expressions defined in the `rules` object of your `HttpProxyRules` instance, and no `default` target was specified or handled.
  fix Ensure that your `rules` object contains a regex that correctly captures the URL path you are attempting to proxy. Test your regex patterns using an online regex tester. Also, consider adding a `default` target to your `HttpProxyRules` configuration to handle un-matched requests gracefully.

• TypeError: proxy.web is not a function

  cause This error likely means that the `proxy` object, which is an instance of `node-http-proxy`, was not correctly initialized or imported. It could also happen if `node-http-proxy` itself failed to load.
  fix Verify that `node-http-proxy` is correctly installed (`npm install http-proxy`) and that `httpProxy.createProxy()` is called correctly to create the proxy instance: `var proxy = httpProxy.createProxy();`.

Warnings

• breaking This package is explicitly an add-on to `node-http-proxy`. Updates or major version changes in `node-http-proxy` (e.g., v2.x to v3.x or later) may introduce incompatibilities that `http-proxy-rules` does not address, as it appears to be unmaintained. Developers should thoroughly test `http-proxy-rules` with newer `node-http-proxy` versions.
  Fix: Review the changelogs for `node-http-proxy` and `http-proxy-rules` carefully. Consider migrating to more actively maintained proxy solutions if encountering issues with newer Node.js or `node-http-proxy` versions.
• gotcha Rule matching order is crucial. If multiple rules could match a given URL path, the module will apply the *first* rule defined in the `rules` object. This relies on JavaScript engine behavior for object key enumeration, which has generally been insertion-order preserved since ES2015, but it's important to define rules from most specific to least specific.
  Fix: Structure your `rules` object such that more specific or exact matches appear earlier in the object definition than broader, more general matches. For example, a rule for `/users/profile` should come before a rule for `/users/.*`.
• gotcha The module automatically appends `(?:\W|$)` to your regex-supported URL path keys. This means `.*/test` will match `/test`, `/test/`, or `/test?` but NOT `/testing`. Be mindful of this implicit suffix when crafting your rule keys, as it can lead to unexpected non-matches.
  Fix: Test your rules thoroughly with various URL paths, including those you expect to match and those you expect *not* to match. If you need a more permissive match that includes suffixes, you may need to adjust your regex (e.g., `.*/test.*` if you truly want to match `/testing`).
• deprecated The project appears to be abandoned, with no recent updates or maintenance activity on its GitHub repository. This means it may not receive security patches, bug fixes, or compatibility updates for newer Node.js versions or dependencies, making it a potential long-term risk for production systems.
  Fix: For new projects, consider using actively maintained alternatives for HTTP proxying and routing. For existing projects, evaluate the risk, ensure thorough testing, and consider contributing fixes or migrating if vulnerabilities or critical bugs arise.

Install

• npm install http-proxy-rules npm
• yarn add http-proxy-rules yarn
• pnpm add http-proxy-rules pnpm

Imports

• HttpProxyRules
  wrong:

  const HttpProxyRules = require('http-proxy-rules');

  correct:

  import HttpProxyRules from 'http-proxy-rules';

  While CommonJS `require` is shown in examples, the library is old enough that it might predate widespread ESM usage. For modern projects using ESM, this is the correct pattern. Ensure your project is configured for CommonJS if using `require`.
• HttpProxyRules
  wrong:

  import { HttpProxyRules } from 'http-proxy-rules';

  correct:

  const HttpProxyRules = require('http-proxy-rules');

  This package primarily exports a default class. Named imports like `{ HttpProxyRules }` will not work.

Quickstart

This example demonstrates how to set up an HTTP proxy server using `http-proxy-rules` to define routing logic and `node-http-proxy` to handle the actual proxying. It creates a proxy server on port 6010 that routes requests based on URL path patterns to different target backend services, with a default fallback. This shows how to initialize `HttpProxyRules`, define regex-based rules, and use the `match` method within an `http-proxy` server callback.

const http = require('http');
const httpProxy = require('http-proxy');
const HttpProxyRules = require('http-proxy-rules');

// Set up proxy rules instance
const proxyRules = new HttpProxyRules({
  rules: {
    '.*/api/v1/users': 'http://localhost:3001/users',
    '.*/api/v1/products/([0-9]+)': 'http://localhost:3002/items/$1',
    '/admin': 'http://localhost:3003/dashboard',
    '/images/(.*)': 'http://localhost:3004/assets/$1'
  },
  default: 'http://localhost:3000' // Default target if no rules match
});

// Create reverse proxy instance
const proxy = httpProxy.createProxy();

// Create http server that leverages reverse proxy instance
// and proxy rules to proxy requests to different targets
http.createServer(function(req, res) {
  const target = proxyRules.match(req);

  if (target) {
    console.log(`Proxying ${req.url} to ${target}`);
    return proxy.web(req, res, { target: target });
  } else {
    console.log(`No rule matched for ${req.url}. Using default.`);
    return proxy.web(req, res, { target: proxyRules.default });
  }
}).listen(6010, () => {
  console.log('Proxy server listening on port 6010');
  console.log('  - Try: http://localhost:6010/api/v1/users');
  console.log('  - Try: http://localhost:6010/api/v1/products/123');
  console.log('  - Try: http://localhost:6010/admin');
  console.log('  - Try: http://localhost:6010/images/logo.png');
  console.log('  - Try: http://localhost:6010/unknown-path');
});