feat(legacyCreateProxyMiddleware): adapter with legacy behavior

MIGRATION.md

@@ -0,0 +1,129 @@
+# Migration guide
+
+- [v2 to v3 adapter](#v2-to-v3-adapter)
+  - [`legacyCreateProxyMiddleware`](#legacycreateproxymiddleware)
+- [v3 breaking changes](#v3-breaking-changes)
+  - [Removed `req.url` patching](#removed-requrl-patching)
+  - [Removed "shorthand" usage](#removed-shorthand-usage)
+  - [Removed `context` argument](#removed-context-argument)
+  - [Removed `logProvider` and `logLevel` options](#removed-logprovider-and-loglevel-options)
+  - [Refactored proxy events](#refactored-proxy-events)
+
+## v2 to v3 adapter
+
+### `legacyCreateProxyMiddleware`
+
+Use the adapter to use v3 without changing too much of your v2 code and configuration.
+
+NOTE: `legacyCreateProxyMiddleware` will be removed in a future version.
+
+```js
+// before
+const { createProxyMiddleware } = require('http-proxy-middleware');
+
+createProxyMiddleware(...);
+
+// after
+const { legacyCreateProxyMiddleware } = require('http-proxy-middleware');
+
+legacyCreateProxyMiddleware(...);
+```
+
+```ts
+// before
+import { createProxyMiddleware, Options } from 'http-proxy-middleware';
+
+createProxyMiddleware(...);
+
+// after
+import { legacyCreateProxyMiddleware, LegacyOptions } from 'http-proxy-middleware';
+
+legacyCreateProxyMiddleware(...);
+```
+
+## v3 breaking changes
+
+### Removed `req.url` patching
+
+```js
+// before
+app.use('/user', proxy({ target: 'http://www.example.org' }));
+
+// after
+app.use('/user', proxy({ target: 'http://www.example.org/user' }));
+```
+
+### Removed "shorthand" usage
+
+```js
+// before
+createProxyMiddleware('http:/www.example.org');
+
+// after
+createProxyMiddleware({ target: 'http:/www.example.org' });
+```
+
+### Removed `context` argument
+
+See [recipes/pathFilter.md](./recipes/pathFilter.md) for more information.
+
+```js
+// before
+createProxyMiddleware('/path', { target: 'http://www.example.org' });
+
+// after
+createProxyMiddleware({
+  target: 'http://www.example.org',
+  pathFilter: '/path',
+});
+```
+
+### Removed `logProvider` and `logLevel` options
+
+Use your external logging library to control the logging level.
+
+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>
+
+````js
+
+See [recipes/logger.md](./recipes/logger.md) for more information.
+
+```js
+// new
+createProxyMiddleware({
+  target: 'http://www.example.org',
+  logger: console,
+});
+````
+
+### Refactored proxy events
+
+See [recipes/proxy-events.md](./recipes/proxy-events.md) for more information.
+
+```js
+// before
+createProxyMiddleware({
+  target: 'http://www.example.org',
+  onError: () => {},
+  onProxyReq: () => {},
+  onProxyRes: () => {},
+  onProxyReqWs: () => {},
+  onOpen: () => {},
+  onClose: () => {},
+});
+
+// after
+createProxyMiddleware({
+  target: 'http://www.example.org',
+  on: {
+    error: () => {},
+    proxyReq: () => {},
+    proxyRes: () => {},
+    proxyReqWs: () => {},
+    open: () => {},
+    close: () => {},
+  },
+});
+```

README.md

@@ -11,15 +11,21 @@ Powered by the popular Nodejitsu [`http-proxy`](https://github.com/nodejitsu/nod
 
 ## ⚠️ Note <!-- omit in toc -->
 
-This page is showing documentation for version v2.x.x ([release notes](https://github.com/chimurai/http-proxy-middleware/releases))
+This page is showing documentation for version v3.x.x ([release notes](https://github.com/chimurai/http-proxy-middleware/releases))
 
-If you're looking for v0.x documentation. Go to:
-https://github.com/chimurai/http-proxy-middleware/tree/v0.21.0#readme
+See [MIGRATION.md](https://github.com/chimurai/http-proxy-middleware/blob/master/MIGRATION.md) for details on how to migrate from v2.x.x to v3.x.x
+
+If you're looking for older documentation. Go to:
+
+- <https://github.com/chimurai/http-proxy-middleware/tree/v2.0.4#readme>
+- <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).
+
 ```javascript
 // javascript
 
@@ -58,8 +64,6 @@ app.listen(3000);
 
 _All_ `http-proxy` [options](https://github.com/nodejitsu/node-http-proxy#options) can be used, along with some extra `http-proxy-middleware` [options](#options).
 
-:bulb: **Tip:** Set the option `changeOrigin` to `true` for [name-based virtual hosted sites](http://en.wikipedia.org/wiki/Virtual_hosting#Name-based).
-
 ## Table of Contents <!-- omit in toc -->
 
 <!-- // spell-checker:disable -->
@@ -160,9 +164,9 @@ app.use(
 
 `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
+- 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
 
@@ -302,7 +306,7 @@ const {
   loggerPlugin, // log proxy events to a logger (ie. console)
   errorResponsePlugin, // return 5xx response on proxy error
   proxyEventsPlugin, // implements the "on:" option
-} = require('http-proxy-middleware/plugins/default');
+} = require('http-proxy-middleware');
 
 createProxyMiddleware({
   target: `http://example.org`,
@@ -316,6 +320,10 @@ createProxyMiddleware({
 
 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
@@ -424,29 +432,35 @@ The following options are provided by the underlying [http-proxy](https://github
 - **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:
+
     ```json
     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:
+
     ```json
     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

cspell.json

@@ -2,14 +2,21 @@
   "language": "en",
   "spellCheckDelayMs": 500,
   "dictionaries": ["node", "npm", "typescript", "contributors"],
-  "ignorePaths": ["node_modules/**", "coverage/**", "dist/**", "package.json", "yarn.lock"],
+  "ignorePaths": [
+    "node_modules/**",
+    "coverage/**",
+    "dist/**",
+    "package.json",
+    "yarn.lock",
+    "*.tgz"
+  ],
   "dictionaryDefinitions": [
     {
       "name": "contributors",
       "path": "CONTRIBUTORS.txt"
     }
   ],
-  "ignoreRegExpList": ["[a-z]+path"],
+  "ignoreRegExpList": ["[a-z]+path", "\\]\\(#[a-z-]+\\)"],
   "words": [
     "camelcase",
     "codesandbox",

examples/connect/index.js

@@ -11,7 +11,6 @@ const { createProxyMiddleware } = require('../../dist'); // require('http-proxy-
 const jsonPlaceholderProxy = createProxyMiddleware({
   target: 'http://jsonplaceholder.typicode.com/users',
   changeOrigin: true, // for vhosted sites, changes host header to match to target's host
-  logLevel: 'debug',
 });
 
 const app = connect();

examples/express/index.js

@@ -10,7 +10,6 @@ const { createProxyMiddleware } = require('../../dist'); // require('http-proxy-
 const jsonPlaceholderProxy = createProxyMiddleware({
   target: 'http://jsonplaceholder.typicode.com/users',
   changeOrigin: true, // for vhosted sites, changes host header to match to target's host
-  logLevel: 'debug',
   logger: console,
 });
 

recipes/websocket.md

@@ -5,8 +5,9 @@ This example will create a proxy middleware with websocket support.
 ```javascript
 const { createProxyMiddleware } = require('http-proxy-middleware');
 
-const socketProxy = createProxyMiddleware('/socket', {
+const socketProxy = createProxyMiddleware({
   target: 'http://localhost:3000',
+  pathFilter: '/socket',
   ws: true,
 });
 ```
@@ -21,12 +22,13 @@ const { createProxyMiddleware } = require('http-proxy-middleware');
 const options = {
   target: 'http://localhost:3000',
   ws: true,
+  pathFilter: '/socket',
   pathRewrite: {
     '^/socket': '',
   },
 };
 
-const socketProxy = createProxyMiddleware('/socket', options);
+const socketProxy = createProxyMiddleware(options);
 ```
 
 ## WebSocket - Server update subscription
@@ -38,8 +40,9 @@ Subscribe to server's upgrade event.
 ```javascript
 const { createProxyMiddleware } = require('http-proxy-middleware');
 
-const socketProxy = createProxyMiddleware('/socket', {
+const socketProxy = createProxyMiddleware({
   target: 'http://localhost:3000',
+  pathFilter: '/socket',
   ws: true,
 });
 

src/http-proxy-middleware.ts

@@ -116,6 +116,15 @@ export class HttpProxyMiddleware {
    * @return {Object} proxy options
    */
   private prepareProxyRequest = async (req: Request) => {
+    /**
+     * Incorrect usage confirmed: https://github.com/expressjs/express/issues/4854#issuecomment-1066171160
+     * Temporary restore req.url patch for {@link src/legacy/create-proxy-middleware.ts legacyCreateProxyMiddleware()}
+     * FIXME: remove this patch in future release
+     */
+    if ((this.middleware as unknown as any).__LEGACY_HTTP_PROXY_MIDDLEWARE__) {
+      req.url = (req as unknown as any).originalUrl || req.url;
+    }
+
     const newProxyOptions = Object.assign({}, this.proxyOptions);
 
     // Apply in order:

src/index.ts

@@ -6,13 +6,16 @@ export function createProxyMiddleware(options: Options): RequestHandler {
   return middleware;
 }
 
-/**
- * @deprecated
- */
-// export function legacyCreateProxyMiddleware(pathFilter: Filter, options: Options) {
-//   return createProxyMiddleware({ ...options, pathFilter });
-// }
-
 export * from './handlers';
 
 export type { Filter, Options, RequestHandler } from './types';
+
+/**
+ * Default plugins
+ */
+export * from './plugins/default';
+
+/**
+ * Legacy exports
+ */
+export * from './legacy';

src/legacy/create-proxy-middleware.ts

@@ -0,0 +1,33 @@
+import { createProxyMiddleware } from '..';
+import { Debug } from '../debug';
+import { Filter, RequestHandler } from '../types';
+import { legacyOptionsAdapter } from './options-adapter';
+import { LegacyOptions } from './types';
+
+const debug = Debug.extend('legacy-create-proxy-middleware');
+
+/**
+ * @deprecated
+ * This function is deprecated and will be removed in a future version.
+ *
+ * Use {@link createProxyMiddleware} instead.
+ */
+export function legacyCreateProxyMiddleware(shortHand: string): RequestHandler;
+export function legacyCreateProxyMiddleware(legacyOptions: LegacyOptions): RequestHandler;
+export function legacyCreateProxyMiddleware(
+  legacyContext: Filter,
+  legacyOptions: LegacyOptions
+): RequestHandler;
+export function legacyCreateProxyMiddleware(legacyContext, legacyOptions?): RequestHandler {
+  debug('init');
+
+  const options = legacyOptionsAdapter(legacyContext, legacyOptions);
+
+  const proxyMiddleware = createProxyMiddleware(options);
+
+  // https://github.com/chimurai/http-proxy-middleware/pull/731/files#diff-07e6ad10bda0df091b737caed42767657cd0bd74a01246a1a0b7ab59c0f6e977L118
+  debug('add marker for patching req.url (old behavior)');
+  (proxyMiddleware as any).__LEGACY_HTTP_PROXY_MIDDLEWARE__ = true;
+
+  return proxyMiddleware;
+}

src/legacy/index.ts

@@ -0,0 +1 @@
+export * from './public';