docs: fix v3 documentation

chimurai · Mar 20, 2022 · 994c631 · 994c631
1 parent 9b46bb2
commit 994c631
Show file tree

Hide file tree

Showing 12 changed files with 51 additions and 149 deletions.
diff --git a/recipes/README.md b/recipes/README.md
@@ -1,106 +1,3 @@
 # Recipes
 
 Common usages of `http-proxy-middleware`.
-
-# Configuration example
-
-Overview of `http-proxy-middleware` specific options.
-
-http-proxy-middleware uses Nodejitsu's [http-proxy](https://github.com/nodejitsu/node-http-proxy) to do the actual proxying. All of its [options](https://github.com/nodejitsu/node-http-proxy#options) are exposed via http-proxy-middleware's configuration object.
-
-```javascript
-const { createProxyMiddleware } = require('http-proxy-middleware');
-const winston = require('winston');
-
-/**
- * Proxy options
- */
-const options = {
-  // decide which path(s) should be proxied. (wildcards supported)
-  pathFilter: '/api',
-
-  // hostname to the target server
-  target: 'http://localhost:3000',
-
-  // set correct host headers for name-based virtual hosted sites
-  changeOrigin: true,
-
-  // enable websocket proxying
-  ws: true,
-
-  // additional request headers
-  headers: {
-    'x-powered-by': 'foobar',
-  },
-
-  // rewrite paths
-  pathRewrite: {
-    '^/api/old-path': '/api/new-path', // rewrite path
-    '^/api/remove/path': '/path', // remove base path
-  },
-
-  // re-target based on the request's host header and/or path
-  router: {
-    // host[/path]                 :  <new target>
-    // /path                       :  <new target>
-    'integration.localhost:8000': 'http://localhost:8001', // host only
-    'staging.localhost:8000': 'http://localhost:8002', // host only
-    'localhost:8000/api': 'http://localhost:8003', // host + path
-    '/rest': 'http://localhost:8004', // path only
-  },
-
-  // control logging
-  logLevel: 'silent',
-
-  // use a different lib for logging;
-  // i.e., write logs to file or server
-  logProvider: function (provider) {
-    return winston;
-  },
-
-  // subscribe to http-proxy's error event
-  onError: function onError(err, req, res) {
-    res.writeHead(500, { 'Content-Type': 'text/plain' });
-    res.end('Something went wrong.');
-  },
-
-  // subscribe to http-proxy's proxyRes event
-  onProxyRes: function (proxyRes, req, res) {
-    proxyRes.headers['x-added'] = 'foobar';
-    delete proxyRes.headers['x-removed'];
-  },
-
-  // subscribe to http-proxy's proxyReq event
-  onProxyReq: function (proxyReq, req, res) {
-    // add custom header to request
-    proxyReq.setHeader('x-powered-by', 'foobar');
-  },
-
-  /**
-   * The following options are provided by Nodejitsu's http-proxy
-   */
-
-  // target
-  // forward
-  // agent
-  // ssl
-  // ws
-  // xfwd
-  // secure
-  // toProxy
-  // prependPath
-  // ignorePath
-  // localAddress
-  // changeOrigin
-  // auth
-  // hostRewrite
-  // autoRewrite
-  // protocolRewrite
-  // headers
-};
-
-/**
- * Create the proxy middleware, so it can be used in a server.
- */
-const apiProxy = createProxyMiddleware(options);
-```
diff --git a/recipes/context-matching.md b/recipes/context-matching.md
@@ -0,0 +1,18 @@
+# [BREAKING CHANGE]
+
+This functionality is removed in v3.
+
+The old "context matching" function has been moved to the [pathFilter](pathFilter.md) configuration property.
+
+TL;DR
+
+```js
+createProxyMiddleware('/api', {
+  target: 'http://localhost:3000',
+});
+
+createProxyMiddleware({
+  target: 'http://localhost:3000',
+  pathFilter: '/api',
+});
+```
diff --git a/recipes/corporate-proxy.md b/recipes/corporate-proxy.md
@@ -16,5 +16,5 @@ const options = {
   agent: new HttpsProxyAgent(proxyServer),
 };
 
-const apiProxy = createProxyMiddleware('/api', options);
+const apiProxy = createProxyMiddleware(options);
 ```
diff --git a/recipes/https.md b/recipes/https.md
@@ -9,7 +9,7 @@ All options are provided by [http-proxy](https://github.com/nodejitsu/node-http-
 ```javascript
 const { createProxyMiddleware } = require('http-proxy-middleware');
 
-const apiProxy = createProxyMiddleware('/api', {
+const apiProxy = createProxyMiddleware({
   target: 'https://example.org',
   changeOrigin: true,
 });
@@ -21,7 +21,7 @@ const apiProxy = createProxyMiddleware('/api', {
 const fs = require('fs');
 const { createProxyMiddleware } = require('http-proxy-middleware');
 
-const apiProxy = createProxyMiddleware('/api', {
+const apiProxy = createProxyMiddleware({
   target: {
     protocol: 'https:',
     host: 'example.org',

diff --git a/recipes/logLevel.md b/recipes/logLevel.md
@@ -22,7 +22,7 @@ const options = {
   logLevel: 'debug',
 };
 
-const apiProxy = createProxyMiddleware('/api', options);
+const apiProxy = createProxyMiddleware(options);
 ```
 
 ## Level: silent
@@ -37,5 +37,5 @@ const options = {
   logLevel: 'silent',
 };
 
-const apiProxy = createProxyMiddleware('/api', options);
+const apiProxy = createProxyMiddleware(options);
 ```
diff --git a/recipes/logProvider.md b/recipes/logProvider.md
@@ -15,7 +15,7 @@ const options = {
   },
 };
 
-const apiProxy = createProxyMiddleware('/api', options);
+const apiProxy = createProxyMiddleware(options);
 ```
 
 ## Winston
@@ -43,7 +43,7 @@ const options = {
   logProvider: logProvider,
 };
 
-const apiProxy = createProxyMiddleware('/api', options);
+const apiProxy = createProxyMiddleware(options);
 ```
 
 # Winston Multi Transport
@@ -72,5 +72,5 @@ const options = {
   logProvider: logProvider,
 };
 
-const apiProxy = createProxyMiddleware('/api', options);
+const apiProxy = createProxyMiddleware(options);
 ```
diff --git a/recipes/pathFilter.md b/recipes/pathFilter.md
@@ -1,18 +1,9 @@
 # Path Filter
 
-Determine which requests should be proxied.
+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.
 
 `pathFilter` is optional and is useful in cases where you are not able to use the regular [middleware mounting](http://expressjs.com/en/4x/api.html#app.use).
 
-The [RFC 3986 `path`](https://tools.ietf.org/html/rfc3986#section-3.3) is used for `pathFilter`.
-
-```text
-         foo://example.com:8042/over/there?name=ferret#nose
-         \_/   \______________/\_________/ \_________/ \__/
-          |           |            |            |        |
-       scheme     authority       path        query   fragment
-```
-
 `http-proxy-middleware` offers several ways to do this:
 
 - [Path](#path)
@@ -30,8 +21,8 @@ This will match paths starting with `/api`
 const { createProxyMiddleware } = require('http-proxy-middleware');
 
 const apiProxy = createProxyMiddleware({
-  pathFilter: '/api',
   target: 'http://localhost:3000',
+  pathFilter: '/api',
 });
 
 // `/api/foo/bar` -> `http://localhost:3000/api/foo/bar`
@@ -45,8 +36,8 @@ This will match paths starting with `/api` or `/rest`
 const { createProxyMiddleware } = require('http-proxy-middleware');
 
 const apiProxy = createProxyMiddleware({
-  pathFilter: ['/api', '/rest'],
   target: 'http://localhost:3000',
+  pathFilter: ['/api', '/rest'],
 });
 
 // `/api/foo/bar` -> `http://localhost:3000/api/foo/bar`
@@ -61,8 +52,8 @@ This will match paths starting with `/api/` and should also end with `.json`
 const { createProxyMiddleware } = require('http-proxy-middleware');
 
 const apiProxy = createProxyMiddleware({
-  pathFilter: '/api/**/*.json',
   target: 'http://localhost:3000',
+  pathFilter: '/api/**/*.json',
 });
 ```
 
@@ -74,8 +65,8 @@ Multiple wildcards can be used.
 const { createProxyMiddleware } = require('http-proxy-middleware');
 
 const apiProxy = createProxyMiddleware({
-  pathFilter: ['/api/**/*.json', '/rest/**'],
   target: 'http://localhost:3000',
+  pathFilter: ['/api/**/*.json', '/rest/**'],
 });
 ```
 
@@ -87,8 +78,8 @@ This example will create a proxy with globs.
 const { createProxyMiddleware } = require('http-proxy-middleware');
 
 const apiProxy = createProxyMiddleware({
-  pathFilter: ['foo/*.js', '!bar.js'],
   target: 'http://localhost:3000',
+  pathFilter: ['foo/*.js', '!bar.js'],
 });
 ```
 
@@ -100,12 +91,12 @@ The request `pathname` and `req` object are provided to determine which requests
 ```javascript
 const { createProxyMiddleware } = require('http-proxy-middleware');
 
-const filter = function (pathname, req) {
+const pathFilter = function (pathname, req) {
   return pathname.match('^/api') && req.method === 'GET';
 };
 
 const apiProxy = createProxyMiddleware({
-  pathFilter: filter,
+  pathFilter: pathFilter,
   target: 'http://localhost:3000',
 });
 ```
diff --git a/recipes/pathRewrite.md b/recipes/pathRewrite.md
@@ -2,15 +2,11 @@
 
 Modify request paths before requests are send to the target.
 
-<!-- MarkdownTOC autolink=true bracket=round -->
-
 - [rewrite paths](#rewrite-paths)
 - [remove paths](#remove-paths)
 - [add paths](#add-paths)
 - [custom rewrite function](#custom-rewrite-function)
 
-<!-- /MarkdownTOC -->
-
 ## rewrite paths
 
 Rewrite paths
@@ -25,7 +21,7 @@ const options = {
   },
 };
 
-const apiProxy = createProxyMiddleware('/api', options);
+const apiProxy = createProxyMiddleware(options);
 
 // `/old/api/foo/bar` -> `http://localhost:3000/new/api/foo/bar`
 ```
@@ -44,7 +40,7 @@ const options = {
   },
 };
 
-const apiProxy = createProxyMiddleware('/api', options);
+const apiProxy = createProxyMiddleware(options);
 
 // `/api/lorum/ipsum` -> `http://localhost:3000/lorum/ipsum`
 ```
@@ -63,7 +59,7 @@ const options = {
   },
 };
 
-const apiProxy = createProxyMiddleware('/api', options);
+const apiProxy = createProxyMiddleware(options);
 
 // `/api/lorum/ipsum` -> `http://localhost:3000/extra/api/lorum/ipsum`
 ```
@@ -86,7 +82,7 @@ const options = {
   pathRewrite: rewriteFn,
 };
 
-const apiProxy = createProxyMiddleware('/api', options);
+const apiProxy = createProxyMiddleware(options);
 
 // `/api/foo/lorum/ipsum` -> `http://localhost:3000/api/bar/lorum/ipsum`
 ```
diff --git a/recipes/proxy-events.md b/recipes/proxy-events.md
@@ -16,7 +16,7 @@ const onError = function (err, req, res) {
 
 const options = { target: 'http://localhost:3000', onError: onError };
 
-const apiProxy = createProxyMiddleware('/api', options);
+const apiProxy = createProxyMiddleware(options);
 ```
 
 ## onProxyReq
@@ -33,7 +33,7 @@ const onProxyReq = function (proxyReq, req, res) {
 
 const options = { target: 'http://localhost:3000', onProxyReq: onProxyReq };
 
-const apiProxy = createProxyMiddleware('/api', options);
+const apiProxy = createProxyMiddleware(options);
 ```
 
 ## onProxyReqWs
@@ -50,7 +50,7 @@ const onProxyReqWs = function (proxyReq, req, socket, options, head) {
 
 const options = { target: 'http://localhost:3000', onProxyReqWs: onProxyReqWs };
 
-const apiProxy = createProxyMiddleware('/api', options);
+const apiProxy = createProxyMiddleware(options);
 ```
 
 ## onProxyRes
@@ -70,5 +70,5 @@ const onProxyRes = function (proxyRes, req, res) {
 
 const options = { target: 'http://localhost:3000', onProxyRes: onProxyRes };
 
-const apiProxy = createProxyMiddleware('/api', options);
+const apiProxy = createProxyMiddleware(options);
 ```
diff --git a/recipes/router.md b/recipes/router.md
@@ -2,12 +2,9 @@
 
 Allows you to route to a different `target` by using a table of a custom function.
 
-<!-- MarkdownTOC autolink=true bracket=round -->
-
 - [Custom router function](#custom-router-function)
 - [Proxy Table](#proxy-table)
-
-<!-- /MarkdownTOC -->
+  - [Example](#example)
 
 ## Custom router function
 
@@ -73,7 +70,7 @@ In the example above; all requests will be proxied to `http://localhost:8000`.
 
 When request's `Host HTTP header` and/or `path` match a configuration in the proxyTable, they will be send to matching target.
 
-```
+```text
 http://localhost:3000/lorum/ipsum             -> http://localhost:8000/lorum/ipsum
 http://integration.localhost:3000/lorum/ipsum -> http://localhost:8001/lorum/ipsum
 http://staging.localhost:3000/rest/foo/bar    -> http://localhost:8002/rest/foo/bar