feat(legacyCreateProxyMiddleware): adapter with v2 behaviour

[chimurai]

Description

• Add legacyCreateProxyMiddleware() to use v3 with v2 behaviour.
• User's onError and on.error handler replaces default error handler.
• MIGRATION.md

Motivation and Context

V3 introduces some breaking changes: https://github.com/chimurai/http-proxy-middleware/milestone/2?closed=1

Allow users to upgrade to v3 with minimal changes. After upgrading you can migrate deprecated functionality at your own pace.

How has this been tested?

• unit tests
• unit tested patched webpack-dev-server with v3 (https://github.com/webpack/webpack-dev-server/commit/eea50f342e3090483f6da4932b84ed52bba44c58)
• webpack-dev-server: npm run test:only -- --testNamePattern=proxy

https://github.com/webpack/webpack-dev-server/commit/eea50f342e3090483f6da4932b84ed52bba44c58 with http-proxy-middleware-v3.patch:

diff --git a/lib/Server.js b/lib/Server.js
index 9f374ba..c976f7c 100644
--- a/lib/Server.js
+++ b/lib/Server.js
@@ -31,7 +31,7 @@ const schema = require("./options.json");
 /** @typedef {import("bonjour-service").Bonjour} Bonjour */
 /** @typedef {import("bonjour-service").Service} BonjourOptions */
 /** @typedef {import("http-proxy-middleware").RequestHandler} RequestHandler */
-/** @typedef {import("http-proxy-middleware").Options} HttpProxyMiddlewareOptions */
+/** @typedef {import("http-proxy-middleware").LegacyOptions} HttpProxyMiddlewareOptions */
 /** @typedef {import("http-proxy-middleware").Filter} HttpProxyMiddlewareOptionsFilter */
 /** @typedef {import("serve-index").Options} ServeIndexOptions */
 /** @typedef {import("serve-static").ServeStaticOptions} ServeStaticOptions */
@@ -2120,7 +2120,7 @@ class Server {
     });

     if (this.options.proxy) {
-      const { createProxyMiddleware } = require("http-proxy-middleware");
+      const { legacyCreateProxyMiddleware: createProxyMiddleware } = require("http-proxy-middleware");

       /**
        * @param {ProxyConfigArrayItem} proxyConfig
diff --git a/test/e2e/allowed-hosts.test.js b/test/e2e/allowed-hosts.test.js
index aeb5b7a..8550be4 100644
--- a/test/e2e/allowed-hosts.test.js
+++ b/test/e2e/allowed-hosts.test.js
@@ -2,7 +2,7 @@

 const express = require("express");
 const webpack = require("webpack");
-const { createProxyMiddleware } = require("http-proxy-middleware");
+const { legacyCreateProxyMiddleware: createProxyMiddleware } = require("http-proxy-middleware");
 const Server = require("../../lib/Server");
 const config = require("../fixtures/client-config/webpack.config");
 const runBrowser = require("../helpers/run-browser");
diff --git a/test/e2e/web-socket-server-url.test.js b/test/e2e/web-socket-server-url.test.js
index a83f3d3..63d8392 100644
--- a/test/e2e/web-socket-server-url.test.js
+++ b/test/e2e/web-socket-server-url.test.js
@@ -2,7 +2,7 @@

 const express = require("express");
 const webpack = require("webpack");
-const { createProxyMiddleware } = require("http-proxy-middleware");
+const { legacyCreateProxyMiddleware: createProxyMiddleware } = require("http-proxy-middleware");
 const Server = require("../../lib/Server");
 const config = require("../fixtures/client-config/webpack.config");
 const runBrowser = require("../helpers/run-browser");

Types of changes

• [ ] Bug fix (non-breaking change which fixes an issue)
• [x] New feature (non-breaking change which adds functionality)
• [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)

Checklist:

• [x] My change requires a change to the documentation.
• [x] I have updated the documentation accordingly.

[coveralls]

Coverage increased (+0.3%) to 97.82% when pulling 4dc3e1df866e2d04322abe88c6269f5e3d8efb84 on legacy-adaptor into 397aed3ab9a1928ed5615102fa95e30168c9cb6d on v3.