@ohos-ports/http-proxy-middleware 0.0.0-stage → 4.2.0-beta.1

package/LICENSE

@@ -0,0 +1,22 @@
+The MIT License (MIT)
+
+Copyright (c) 2015 Steven Chim
+
+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.
+

package/README.md

@@ -1,3 +1,671 @@
-# Temporary Holding Version
+# http-proxy-middleware
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![GitHub Workflow Status (with branch)](https://img.shields.io/github/actions/workflow/status/chimurai/http-proxy-middleware/ci.yml?branch=master&logo=github-actions&logoColor=white&style=flat-square)](https://github.com/chimurai/http-proxy-middleware/actions/workflows/ci.yml?query=branch%3Amaster)
+[![Coveralls](https://img.shields.io/coveralls/chimurai/http-proxy-middleware.svg?style=flat-square&logo=coveralls)](https://coveralls.io/r/chimurai/http-proxy-middleware)
+[![Known Vulnerabilities](https://snyk.io/test/github/chimurai/http-proxy-middleware/badge.svg)](https://snyk.io/test/github/chimurai/http-proxy-middleware)
+[![npm](https://img.shields.io/npm/v/http-proxy-middleware?color=%23CC3534&style=flat-square&logo=npm)](https://www.npmjs.com/package/http-proxy-middleware)
+
+Node.js proxying made simple. Configure proxy middleware with ease for [connect](https://github.com/senchalabs/connect), [express](https://github.com/expressjs/express), [next.js](https://github.com/vercel/next.js), [hono](https://github.com/honojs/hono) and [many more](#compatible-servers).
+
+Powered by [`httpxy`](https://github.com/unjs/httpxy). A maintained version of [http-proxy](https://github.com/http-party/node-http-proxy).
+
+## ⚠️ Note <!-- omit in toc -->
+
+This page is showing documentation for version **v4.x.x** ([release notes](https://github.com/chimurai/http-proxy-middleware/releases))
+
+For older documentation:
+
+- [v3.0.5](https://github.com/chimurai/http-proxy-middleware/tree/v3.0.5#readme)
+- [v2.0.4](https://github.com/chimurai/http-proxy-middleware/tree/v2.0.4#readme)
+- [v0.21.0](https://github.com/chimurai/http-proxy-middleware/tree/v0.21.0#readme)
+
+## TL;DR <!-- omit in toc -->
+
+Proxy `/api` requests to `http://www.example.org`
+
+:bulb: **Tip:** Set the option `changeOrigin` to `true` for [name-based virtual hosted sites](http://en.wikipedia.org/wiki/Virtual_hosting#Name-based).
+
+```typescript
+// typescript
+import express from 'express';
+import type { NextFunction, Request, Response } from 'express';
+import { createProxyMiddleware } from 'http-proxy-middleware';
+import type { Filter, Options, RequestHandler } from 'http-proxy-middleware';
+
+const app = express();
+
+const proxyMiddleware = createProxyMiddleware<Request, Response>({
+  target: 'http://www.example.org/api',
+  changeOrigin: true,
+});
+
+app.use('/api', proxyMiddleware);
+
+app.listen(3000);
+
+// proxy and keep the same base path "/api"
+// http://127.0.0.1:3000/api/foo/bar -> http://www.example.org/api/foo/bar
+```
+
+_All_ `httpxy` [options](https://github.com/unjs/httpxy#options) can be used, along with some extra `http-proxy-middleware` [options](#options).
+
+## Table of Contents <!-- omit in toc -->
+
+<!-- // spell-checker:disable -->
+
+- [Install](#install)
+- [Basic usage](#basic-usage)
+- [Express Server Example](#express-server-example)
+  - [app.use(path, proxy)](#appusepath-proxy)
+- [Options](#options)
+  - [`pathFilter` (string, \[\]string, glob, \[\]glob, function)](#pathfilter-string-string-glob-glob-function)
+  - [`pathRewrite` (object/function)](#pathrewrite-objectfunction)
+  - [`router` (object/function)](#router-objectfunction)
+  - [`plugins` (Array)](#plugins-array)
+  - [`ejectPlugins` (boolean) default: `false`](#ejectplugins-boolean-default-false)
+- [`definePlugin` helper](#defineplugin-helper)
+  - [`logger` (Object)](#logger-object)
+- [`httpxy` events](#httpxy-events)
+- [`httpxy` options](#httpxy-options)
+- [WebSocket](#websocket)
+  - [External WebSocket upgrade](#external-websocket-upgrade)
+- [Intercept and manipulate requests](#intercept-and-manipulate-requests)
+- [Intercept and manipulate responses](#intercept-and-manipulate-responses)
+- [Node.js 17+: ECONNREFUSED issue with IPv6 and localhost (#705)](#nodejs-17-econnrefused-issue-with-ipv6-and-localhost-705)
+- [Debugging](#debugging)
+- [Working examples](#working-examples)
+- [Recipes](#recipes)
+- [Compatible servers](#compatible-servers)
+- [Tests](#tests)
+- [Changelog](#changelog)
+- [License](#license)
+
+<!-- // spell-checker:enable -->
+
+## Install
+
+```shell
+npm install --save-dev http-proxy-middleware
+```
+
+## Basic usage
+
+Create and configure a proxy middleware with: `createProxyMiddleware(config)`.
+
+```javascript
+import { createProxyMiddleware } from 'http-proxy-middleware';
+
+const apiProxy = createProxyMiddleware({
+  target: 'http://www.example.org',
+  changeOrigin: true,
+});
+
+// 'apiProxy' is now ready to be used as middleware in a server.
+```
+
+- **options.target**: target host to proxy to. _(protocol + host)_
+- **options.changeOrigin**: for virtual hosted sites
+
+- see full list of [`http-proxy-middleware` configuration options](#options)
+
+## Express Server Example
+
+An example with `express` server.
+
+```javascript
+// include dependencies
+import express from 'express';
+import { createProxyMiddleware } from 'http-proxy-middleware';
+
+const app = express();
+
+// create the proxy
+/** @type {import('http-proxy-middleware').RequestHandler<import('express').Request, import('express').Response>} */
+const exampleProxy = createProxyMiddleware({
+  target: 'http://www.example.org/api', // target host with the same base path
+  changeOrigin: true, // needed for virtual hosted sites
+});
+
+// mount `exampleProxy` in web server
+app.use('/api', exampleProxy);
+app.listen(3000);
+```
+
+### app.use(path, proxy)
+
+If you want to use the server's `app.use` `path` parameter to match requests.
+Use `pathFilter` option to further include/exclude requests which you want to proxy.
+
+```javascript
+app.use(
+  createProxyMiddleware({
+    target: 'http://www.example.org/api',
+    changeOrigin: true,
+    pathFilter: '/api/proxy-only-this-path',
+  }),
+);
+```
+
+`app.use` documentation:
+
+- express: <http://expressjs.com/en/4x/api.html#app.use>
+- connect: <https://github.com/senchalabs/connect#mount-middleware>
+- polka: <https://github.com/lukeed/polka#usebase-fn>
+
+## Options
+
+http-proxy-middleware options:
+
+### `pathFilter` (string, []string, glob, []glob, function)
+
+Narrow down which requests should be proxied. The `path` used for filtering is the `request.url` pathname. In Express, this is the `path` relative to the mount-point of the proxy.
+
+- **path matching**
+  - `createProxyMiddleware({...})` - matches any path, all requests will be proxied when `pathFilter` is not configured.
+  - `createProxyMiddleware({ pathFilter: '/api', ...})` - matches paths starting with `/api`
+
+- **multiple path matching**
+  - `createProxyMiddleware({ pathFilter: ['/api', '/ajax', '/someotherpath'], ...})`
+
+- **wildcard path matching**
+
+  For fine-grained control you can use wildcard matching. Glob pattern matching is done by _micromatch_. Visit [micromatch](https://www.npmjs.com/package/micromatch) or [glob](https://www.npmjs.com/package/glob) for more globbing examples.
+  - `createProxyMiddleware({ pathFilter: '**', ...})` matches any path, all requests will be proxied.
+  - `createProxyMiddleware({ pathFilter: '**/*.html', ...})` matches any path which ends with `.html`
+  - `createProxyMiddleware({ pathFilter: '/*.html', ...})` matches paths directly under path-absolute
+  - `createProxyMiddleware({ pathFilter: '/api/**/*.html', ...})` matches requests ending with `.html` in the path of `/api`
+  - `createProxyMiddleware({ pathFilter: ['/api/**', '/ajax/**'], ...})` combine multiple patterns
+  - `createProxyMiddleware({ pathFilter: ['/api/**', '!**/bad.json'], ...})` exclusion
+
+  **Note**: In multiple path matching, you cannot use string paths and wildcard paths together.
+
+- **custom matching**
+
+  For full control you can provide a custom function to determine which requests should be proxied or not.
+
+  ```javascript
+  /**
+   * @return {Boolean}
+   */
+  const pathFilter = function (path, req) {
+    return path.match('^/api') && req.method === 'GET';
+  };
+
+  const apiProxy = createProxyMiddleware({
+    target: 'http://www.example.org',
+    pathFilter: pathFilter,
+  });
+  ```
+
+### `pathRewrite` (object/function)
+
+Rewrite target's url path. Object-keys will be used as _RegExp_ to match paths.
+
+```javascript
+// rewrite path
+pathRewrite: {'^/old/api' : '/new/api'}
+
+// remove path
+pathRewrite: {'^/remove/api' : ''}
+
+// add base path
+pathRewrite: {'^/' : '/basepath/'}
+
+// custom rewriting
+pathRewrite: function (path, req, res, options) { return path.replace('/api', '/base/api') }
+
+// custom rewriting, returning Promise
+pathRewrite: async function (path, req, res, options) {
+  const should_add_something = await httpRequestToDecideSomething(path);
+  if (should_add_something) path += "something";
+  return path;
+}
+
+// `res` is undefined in WebSocket upgrade flows.
+```
+
+### `router` (object/function)
+
+Re-target `option.target` for specific requests.
+
+```javascript
+// Use `host` and/or `path` to match requests. First match will be used.
+// The order of the configuration matters.
+router: {
+    'integration.localhost:3000' : 'http://127.0.0.1:8001',  // host only
+    'staging.localhost:3000'     : 'http://127.0.0.1:8002',  // host only
+    'localhost:3000/api'         : 'http://127.0.0.1:8003',  // host + path
+    '/rest'                      : 'http://127.0.0.1:8004'   // path only
+}
+
+// Custom router function (string target)
+router: function(req, res, options) {
+    return 'http://127.0.0.1:8004';
+}
+
+// Custom router function (target object)
+router: function(req, res, options) {
+    return {
+        protocol: 'https:', // The : is required
+        host: '127.0.0.1',
+        port: 8004
+    };
+}
+
+// Asynchronous router function which returns promise
+router: async function(req, res, options) {
+    const url = await doSomeIO();
+    return url;
+}
+
+// NOTE: `res` is undefined in WebSocket upgrade flows.
+```
+
+### `plugins` (Array)
+
+```js
+const simpleRequestLogger = (proxyServer, options) => {
+  proxyServer.on('proxyReq', (proxyReq, req, res) => {
+    console.log(`[HPM] [${req.method}] ${req.url}`); // outputs: [HPM] GET /users
+  });
+},
+
+const config = {
+  target: `http://example.org`,
+  changeOrigin: true,
+  plugins: [simpleRequestLogger],
+};
+```
+
+### `ejectPlugins` (boolean) default: `false`
+
+If you're not satisfied with the pre-configured plugins, you can eject them by configuring `ejectPlugins: true`.
+
+NOTE: register your own error handlers to prevent server from crashing.
+
+```js
+// eject default plugins and manually add them back
+import {
+  debugProxyErrorsPlugin, // subscribe to proxy errors to prevent server from crashing
+  errorResponsePlugin, // return 5xx response on proxy error
+  loggerPlugin, // log proxy events to a logger (ie. console)
+  proxyEventsPlugin, // implements the "on:" option
+} from 'http-proxy-middleware';
+
+createProxyMiddleware({
+  target: `http://example.org`,
+  changeOrigin: true,
+  ejectPlugins: true,
+  plugins: [debugProxyErrorsPlugin, loggerPlugin, errorResponsePlugin, proxyEventsPlugin],
+});
+```
+
+## `definePlugin` helper
+
+Create your own `http-proxy-middleware` plugin.
+
+(Default plugins are created with `definePlugin`)
+
+```ts
+import { createProxyMiddleware, definePlugin } from 'http-proxy-middleware';
+
+const myPlugin = definePlugin((proxyServer, options) => {
+  // plugin implementation
+});
+
+// use configure and use plugin
+createProxyMiddleware({
+  target: `http://example.org`,
+  plugins: [myPlugin],
+});
+```
+
+### `logger` (Object)
+
+Configure a logger to output information from http-proxy-middleware: ie. `console`, `winston`, `pino`, `bunyan`, `log4js`, etc...
+
+Only `info`, `warn`, `error` are used internally for compatibility across different loggers.
+
+If you use `winston`, make sure to enable interpolation: <https://github.com/winstonjs/winston#string-interpolation>
+
+See also logger recipes ([recipes/logger.md](https://github.com/chimurai/http-proxy-middleware/blob/master/recipes/logger.md)) for more details.
+
+```javascript
+createProxyMiddleware({
+  logger: console,
+});
+```
+
+## `httpxy` events
+
+Subscribe to [httpxy events](https://github.com/unjs/httpxy#events) with the `on` option:
+
+```js
+createProxyMiddleware({
+  target: 'http://www.example.org',
+  on: {
+    proxyReq: (proxyReq, req, res) => {
+      /* handle proxyReq */
+    },
+    proxyRes: (proxyRes, req, res) => {
+      /* handle proxyRes */
+    },
+    error: (err, req, res) => {
+      /* handle error */
+    },
+  },
+});
+```
+
+- **option.on.error**: function, subscribe to httpxy's `error` event for custom error handling.
+
+  ```javascript
+  function onError(err, req, res, target) {
+    res.writeHead(500, {
+      'Content-Type': 'text/plain',
+    });
+    res.end('Something went wrong. And we are reporting a custom error message.');
+  }
+  ```
+
+- **option.on.proxyRes**: function, subscribe to httpxy's `proxyRes` event.
+
+  ```javascript
+  function onProxyRes(proxyRes, req, res) {
+    proxyRes.headers['x-added'] = 'foobar'; // add new header to response
+    delete proxyRes.headers['x-removed']; // remove header from response
+  }
+  ```
+
+- **option.on.proxyReq**: function, subscribe to httpxy's `proxyReq` event.
+
+  ```javascript
+  function onProxyReq(proxyReq, req, res) {
+    // add custom header to request
+    proxyReq.setHeader('x-added', 'foobar');
+    // or log the req
+  }
+  ```
+
+- **option.on.proxyReqWs**: function, subscribe to httpxy's `proxyReqWs` event.
+
+  ```javascript
+  function onProxyReqWs(proxyReq, req, socket, options, head) {
+    // add custom header
+    proxyReq.setHeader('X-Special-Proxy-Header', 'foobar');
+  }
+  ```
+
+- **option.on.open**: function, subscribe to httpxy's `open` event.
+
+  ```javascript
+  function onOpen(proxySocket) {
+    // listen for messages coming FROM the target here
+    proxySocket.on('data', hybridParseAndLogMessage);
+  }
+  ```
+
+- **option.on.close**: function, subscribe to httpxy's `close` event.
+
+  ```javascript
+  function onClose(res, socket, head) {
+    // view disconnected websocket connections
+    console.log('Client disconnected');
+  }
+  ```
+
+## `httpxy` options
+
+The following options are provided by the underlying [httpxy](https://github.com/unjs/httpxy#options) library.
+
+- **option.target**: url string to be parsed with the url module
+- **option.forward**: url string to be parsed with the url module
+- **option.agent**: object to be passed to http(s).request (see Node's [https agent](http://nodejs.org/api/https.html#https_class_https_agent) and [http agent](http://nodejs.org/api/http.html#http_class_http_agent) objects)
+- **option.ssl**: object to be passed to https.createServer()
+- **option.ws**: true/false: if you want to proxy websockets
+- **option.xfwd**: true/false, adds x-forward headers
+- **option.secure**: true/false, if you want to verify the SSL Certs
+- **option.toProxy**: true/false, passes the absolute URL as the `path` (useful for proxying to proxies)
+- **option.prependPath**: true/false, Default: true - specify whether you want to prepend the target's path to the proxy path
+- **option.ignorePath**: true/false, Default: false - specify whether you want to ignore the proxy path of the incoming request (note: you will have to append / manually if required).
+- **option.localAddress** : Local interface string to bind for outgoing connections
+- **option.changeOrigin**: true/false, Default: false - changes the origin of the host header to the target URL
+- **option.preserveHeaderKeyCase**: true/false, Default: false - specify whether you want to keep letter case of response header key
+- **option.auth** : Basic authentication i.e. 'user:password' to compute an Authorization header.
+- **option.hostRewrite**: rewrites the location hostname on (301/302/307/308) redirects.
+- **option.autoRewrite**: rewrites the location host/port on (301/302/307/308) redirects based on requested host/port. Default: false.
+- **option.protocolRewrite**: rewrites the location protocol on (301/302/307/308) redirects to 'http' or 'https'. Default: null.
+- **option.cookieDomainRewrite**: rewrites domain of `set-cookie` headers. Possible values:
+  - `false` (default): disable cookie rewriting
+  - String: new domain, for example `cookieDomainRewrite: "new.domain"`. To remove the domain, use `cookieDomainRewrite: ""`.
+  - Object: mapping of domains to new domains, use `"*"` to match all domains.  
+    For example keep one domain unchanged, rewrite one domain and remove other domains:
+
+    ```jsonc
+    cookieDomainRewrite: {
+      "unchanged.domain": "unchanged.domain",
+      "old.domain": "new.domain",
+      "*": ""
+    }
+    ```
+
+- **option.cookiePathRewrite**: rewrites path of `set-cookie` headers. Possible values:
+  - `false` (default): disable cookie rewriting
+  - String: new path, for example `cookiePathRewrite: "/newPath/"`. To remove the path, use `cookiePathRewrite: ""`. To set path to root use `cookiePathRewrite: "/"`.
+  - Object: mapping of paths to new paths, use `"*"` to match all paths.
+    For example, to keep one path unchanged, rewrite one path and remove other paths:
+
+    ```jsonc
+    cookiePathRewrite: {
+      "/unchanged.path/": "/unchanged.path/",
+      "/old.path/": "/new.path/",
+      "*": ""
+    }
+    ```
+
+- **option.headers**: object, adds [request headers](https://en.wikipedia.org/wiki/List_of_HTTP_header_fields#Request_fields). (Example: `{host:'www.example.org'}`)
+- **option.proxyTimeout**: timeout (in millis) when proxy receives no response from target
+- **option.timeout**: timeout (in millis) for incoming requests
+- **option.followRedirects**: true/false, Default: false - specify whether you want to follow redirects
+- **option.selfHandleResponse** true/false, if set to true, none of the webOutgoing passes are called and it's your responsibility to appropriately return the response by listening and acting on the `proxyRes` event
+- **option.buffer**: stream of data to send as the request body. Maybe you have some middleware that consumes the request stream before proxying it on e.g. If you read the body of a request into a field called 'req.rawbody' you could restream this field in the buffer option:
+
+  ```javascript
+  import { createProxyServer } from 'httpxy';
+  import streamify from 'stream-array';
+
+  const proxy = createProxyServer();
+
+  export default function proxyWithBody(req, res, next) {
+    proxy.web(
+      req,
+      res,
+      {
+        target: 'http://127.0.0.1:4003/',
+        buffer: streamify(req.rawBody),
+      },
+      next,
+    );
+  }
+  ```
+
+## WebSocket
+
+See [recipes/websocket.md](recipes/websocket.md) for more examples.
+
+```javascript
+// verbose api
+createProxyMiddleware({ pathFilter: '/', target: 'http://echo.websocket.org', ws: true });
+```
+
+### External WebSocket upgrade
+
+In the previous WebSocket examples, http-proxy-middleware relies on an initial HTTP request in order to listen to the HTTP `upgrade` event. If you need to proxy WebSockets without the initial HTTP request, you can subscribe to the server's HTTP `upgrade` event manually.
+
+When the same middleware instance is attached to multiple servers and `ws: true` is used, each server needs its own initial HTTP request before upgrades are auto-subscribed.
+
+```javascript
+const wsProxy = createProxyMiddleware({ target: 'ws://echo.websocket.org', changeOrigin: true });
+
+const app = express();
+app.use(wsProxy);
+
+const server = app.listen(3000);
+server.on('upgrade', wsProxy.upgrade); // <-- subscribe to http 'upgrade'
+```
+
+## Intercept and manipulate requests
+
+Intercept requests from downstream by defining `onProxyReq` in `createProxyMiddleware`.
+
+Currently the only pre-provided request interceptor is `fixRequestBody`, which is used to fix proxied POST requests when `bodyParser` is applied before this middleware.
+
+Example:
+
+```javascript
+import { createProxyMiddleware, fixRequestBody } from 'http-proxy-middleware';
+
+const proxy = createProxyMiddleware({
+  /**
+   * Fix bodyParser
+   **/
+  on: {
+    proxyReq: fixRequestBody,
+  },
+});
+```
+
+## Intercept and manipulate responses
+
+Intercept responses from upstream with `responseInterceptor`. (Make sure to set `selfHandleResponse: true`)
+
+Responses which are compressed with `brotli`, `gzip` and `deflate` will be decompressed automatically. The response will be returned as `buffer` ([docs](https://nodejs.org/api/buffer.html)) which you can manipulate.
+
+With `buffer`, response manipulation is not limited to text responses (html/css/js, etc...); image manipulation will be possible too. ([example](https://github.com/chimurai/http-proxy-middleware/blob/master/recipes/response-interceptor.md#manipulate-image-response))
+
+NOTE: `responseInterceptor` disables streaming of target's response.
+
+Example:
+
+```javascript
+import { createProxyMiddleware, responseInterceptor } from 'http-proxy-middleware';
+
+const proxy = createProxyMiddleware({
+  /**
+   * IMPORTANT: avoid res.end being called automatically
+   **/
+  selfHandleResponse: true, // res.end() will be called internally by responseInterceptor()
+
+  /**
+   * Intercept response and replace 'Hello' with 'Goodbye'
+   **/
+  on: {
+    proxyRes: responseInterceptor(async (responseBuffer, proxyRes, req, res) => {
+      const response = responseBuffer.toString('utf8'); // convert buffer to string
+      return response.replace('Hello', 'Goodbye'); // manipulate response and return the result
+    }),
+  },
+});
+```
+
+Check out [interception recipes](https://github.com/chimurai/http-proxy-middleware/blob/master/recipes/response-interceptor.md) for more examples.
+
+## Node.js 17+: ECONNREFUSED issue with IPv6 and localhost ([#705](https://github.com/chimurai/http-proxy-middleware/issues/705))
+
+Node.js 17+ no longer prefers IPv4 over IPv6 for DNS lookups.
+E.g. It's **not** guaranteed that `localhost` will be resolved to `127.0.0.1` – it might just as well be `::1` (or some other IP address).
+
+If your target server only accepts IPv4 connections, trying to proxy to `localhost` will fail if resolved to `::1` (IPv6).
+
+Ways to solve it:
+
+- Change `target: "http://localhost"` to `target: "http://127.0.0.1"` (IPv4).
+- Change the target server to (also) accept IPv6 connections.
+- Add this flag when running `node`: `node index.js --dns-result-order=ipv4first`. (Not recommended.)
+
+Additional IPv6 notes:
+
+- Unspecified IPv6 host `http://[::]:port` is normalized to loopback (`::1`) to reach local listeners.
+
+> Note: There’s a thing called [Happy Eyeballs](https://en.wikipedia.org/wiki/Happy_Eyeballs) which means connecting to both IPv4 and IPv6 in parallel, which Node.js doesn’t have, but explains why for example `curl` can connect.
+
+## Debugging
+
+Configure the `DEBUG` environment variable enable debug logging.
+
+See [`debug`](https://github.com/debug-js/debug#readme) project for more options.
+
+```shell
+DEBUG=http-proxy-middleware* node server.js
+
+$ http-proxy-middleware proxy created +0ms
+$ http-proxy-middleware proxying request to target: 'http://www.example.org' +359ms
+```
+
+## Working examples
+
+View and play around with [working examples](https://github.com/chimurai/http-proxy-middleware/tree/master/examples).
+
+- Browser-Sync ([example source](https://github.com/chimurai/http-proxy-middleware/tree/master/examples/browser-sync/index.js))
+- express ([example source](https://github.com/chimurai/http-proxy-middleware/tree/master/examples/express/index.js))
+- connect ([example source](https://github.com/chimurai/http-proxy-middleware/tree/master/examples/connect/index.js))
+- WebSocket ([example source](https://github.com/chimurai/http-proxy-middleware/tree/master/examples/websocket/index.js))
+- Response Manipulation ([example source](https://github.com/chimurai/http-proxy-middleware/blob/master/examples/response-interceptor/index.js))
+
+## Recipes
+
+View the [recipes](https://github.com/chimurai/http-proxy-middleware/tree/master/recipes) for common use cases.
+
+## Compatible servers
+
+`http-proxy-middleware` is compatible with the following servers:
+
+- [connect](https://www.npmjs.com/package/connect)
+- [express](https://www.npmjs.com/package/express)
+- [hono](https://www.npmjs.com/package/@hono/node-server)
+- [next.js](https://www.npmjs.com/package/next)
+- [fastify](https://www.npmjs.com/package/fastify)
+- [browser-sync](https://www.npmjs.com/package/browser-sync)
+- [lite-server](https://www.npmjs.com/package/lite-server)
+- [polka](https://github.com/lukeed/polka)
+- [grunt-contrib-connect](https://www.npmjs.com/package/grunt-contrib-connect)
+- [grunt-browser-sync](https://www.npmjs.com/package/grunt-browser-sync)
+- [gulp-connect](https://www.npmjs.com/package/gulp-connect)
+- [gulp-webserver](https://www.npmjs.com/package/gulp-webserver)
+
+Sample implementations can be found in the [server recipes](https://github.com/chimurai/http-proxy-middleware/tree/master/recipes/servers.md).
+
+## Tests
+
+Run the test suite:
+
+```bash
+# install dependencies
+$ yarn
+
+# linting
+$ yarn lint
+$ yarn lint:fix
+
+# building (compile typescript to js)
+$ yarn build
+
+# unit tests
+$ yarn test
+
+# code coverage
+$ yarn coverage
+
+# check spelling mistakes
+$ yarn spellcheck
+```
+
+## Changelog
+
+- [View changelog](https://github.com/chimurai/http-proxy-middleware/blob/master/CHANGELOG.md)
+
+## License
+
+The MIT License (MIT)
+
+Copyright (c) 2015-2026 Steven Chim