{"name":"express-http-proxy","version":"1.6.2","description":"http proxy middleware for express","engines":{"node":">=6.0.0"},"main":"index.js","scripts":{"test":"npm -s run mocha && npm run -s lint","test:debug":"mocha debug -R spec test --recursive --exit","mocha":"mocha -R spec test --recursive --exit","lint":"eslint index.js **/*js"},"repository":{"type":"git","url":"git://github.com/villadora/express-http-proxy.git"},"keywords":["express-http-proxy"],"author":{"name":"villadora","email":"jky239@gmail.com"},"license":"MIT","bugs":{"url":"https://github.com/villadora/express-http-proxy/issues"},"devDependencies":{"body-parser":"^1.17.2","chai":"^4.1.2","cookie-parser":"^1.4.3","eslint":"^4.19.1","express":"^4.15.4","mocha":"^8.0.1","nock":"^10.0.6","supertest":"^3.4.2"},"dependencies":{"debug":"^3.0.1","es6-promise":"^4.1.1","raw-body":"^2.3.0"},"contributors":[{"name":"Liam Bennett"},{"name":"eldereal","url":"https://github.com/eldereal"},{"name":"Saulius Menkevičius","url":"https://github.com/razzmatazz"},{"name":"Jérémy Lal","email":"kapouer@melix.org"},{"name":"Wei Gao","email":"jky239@gmail.com"},{"name":"Nik Krimm","url":"https://github.com/monkpow"}],"gitHead":"3de3f76af48d763c6a2720f7966575ce0ef70a04","homepage":"https://github.com/villadora/express-http-proxy#readme","_id":"express-http-proxy@1.6.2","_nodeVersion":"12.16.1","_npmVersion":"6.13.4","dist":{"shasum":"e87152e45958cee4b91da2fdaa20a1ffd581204a","size":27673,"noattachment":false,"tarball":"https://r2.cnpmjs.org/express-http-proxy/-/express-http-proxy-1.6.2.tgz","integrity":"sha512-soP7UXySFdLbeeMYL1foBkEoZj6HELq9BDAOCr1sLRpqjPaFruN5o6+bZeC+7U4USWIl4JMKEiIvTeKJ2WQdlQ=="},"maintainers":[{"name":"gstroup","email":"gstroup@gmail.com"},{"name":"monkpow","email":"nkrimm@gmail.com"}],"_npmUser":{"name":"monkpow","email":"nkrimm@gmail.com"},"directories":{},"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/express-http-proxy_1.6.2_1595296471206_0.1490252618108574"},"_hasShrinkwrap":false,"publish_time":1595296471343,"_cnpm_publish_time":1595296471343,"_cnpmcore_publish_time":"2021-12-16T16:12:39.414Z","readme":"# express-http-proxy [![NPM version](https://badge.fury.io/js/express-http-proxy.svg)](http://badge.fury.io/js/express-http-proxy) [![Build Status](https://travis-ci.org/villadora/express-http-proxy.svg?branch=master)](https://travis-ci.org/villadora/express-http-proxy) \n\n\nExpress middleware to proxy request to another host and pass response back to original caller.\n\n## Install\n\n```bash\n$ npm install express-http-proxy --save\n```\n\n## Usage\n```js\nproxy(host, options);\n```\n\n### Example:\nTo proxy URLS starting with '/proxy' to the host 'www.google.com':\n\n```js\nvar proxy = require('express-http-proxy');\nvar app = require('express')();\n\napp.use('/proxy', proxy('www.google.com'));\n```\n\n### Streaming\n\nProxy requests and user responses are piped/streamed/chunked by default.\n\nIf you define a response modifier (userResDecorator, userResHeaderDecorator),\nor need to inspect the response before continuing (maybeSkipToNext), streaming\nis disabled, and the request and response are buffered.\nThis can cause performance issues with large payloads.\n\n### Promises\n\nMany function hooks support Promises.\nIf any Promise is rejected, ```next(x)``` is called in the hosting application, where ```x``` is whatever you pass to ```Promise.reject```;\n\n\ne.g.\n```js\n app.use(proxy('/reject-promise', {\n proxyReqOptDecorator: function() {\n return Promise.reject('An arbitrary rejection message.');\n }\n }));\n```\n\neventually calls\n\n```js\nnext('An arbitrary rejection messasage');\n```\n\n### Host\n\nThe first positional argument is for the proxy host; in many cases you will use a static string here, eg.\n\n```js\napp.use('/', proxy('http://google.com'))\n```\n\nHowever, this argument can also be a function, and that function can be\nmemoized or computed on each request, based on the setting of\n```memoizeHost```.\n\n```js\nfunction selectProxyHost() {\n return (new Date() % 2) ? 'http://google.com' : 'http://altavista.com';\n}\n\napp.use('/', proxy(selectProxyHost));\n```\n### Middleware mixing\n\nIf you use 'https://www.npmjs.com/package/body-parser' you should declare it AFTER the proxy configuration, otherwise original 'POST' body could be modified and not proxied correctly.\n\n```\n\napp.use('/proxy', 'http://foo.bar.com')\n\n// Declare use of body-parser AFTER the use of proxy\napp.use(bodyParser.foo(bar))\napp.use('/api', ...)\n```\n\n### Options\n\n#### proxyReqPathResolver (supports Promises)\n\nNote: In ```express-http-proxy```, the ```path``` is considered the portion of\nthe url after the host, and including all query params. E.g. for the URL\n```http://smoogle.com/search/path?q=123```; the path is\n```/search/path?q=123```. Authors using this resolver must also handle the query parameter portion of the path.\n\nProvide a proxyReqPathResolver function if you'd like to\noperate on the path before issuing the proxy request. Use a Promise for async\noperations.\n\n```js\n app.use(proxy('localhost:12345', {\n proxyReqPathResolver: function (req) {\n var parts = req.url.split('?');\n var queryString = parts[1];\n var updatedPath = parts[0].replace(/test/, 'tent');\n return updatedPath + (queryString ? '?' + queryString : '');\n }\n }));\n```\nPromise form\n\n```js\napp.use('/proxy', proxy('localhost:12345', {\n proxyReqPathResolver: function(req) {\n return new Promise(function (resolve, reject) {\n setTimeout(function () { // simulate async\n var parts = req.url.split('?');\n var queryString = parts[1];\n var updatedPath = parts[0].replace(/test/, 'tent');\n var resolvedPathValue = updatedPath + (queryString ? '?' + queryString : '');\n resolve(resolvedPathValue);\n }, 200);\n });\n }\n}));\n```\n\n#### forwardPath\n\nDEPRECATED. See proxyReqPathResolver\n\n#### forwardPathAsync\n\nDEPRECATED. See proxyReqPathResolver\n\n#### filter (supports Promises)\n\nThe ```filter``` option can be used to limit what requests are proxied. Return\n```true``` to continue to execute proxy; return false-y to skip proxy for this\nrequest.\n\nFor example, if you only want to proxy get request:\n\n```js\napp.use('/proxy', proxy('www.google.com', {\n filter: function(req, res) {\n return req.method == 'GET';\n }\n}));\n```\n\nPromise form:\n\n```js\n app.use(proxy('localhost:12346', {\n filter: function (req, res) { \n return new Promise(function (resolve) { \n resolve(req.method === 'GET');\n }); \n }\n }));\n```\n\nNote that in the previous example, `resolve(false)` will execute the happy path\nfor filter here (skipping the rest of the proxy, and calling `next()`).\n`reject()` will also skip the rest of proxy and call `next()`. \n\n#### userResDecorator (was: intercept) (supports Promise)\n\nYou can modify the proxy's response before sending it to the client.\n\n```js\napp.use('/proxy', proxy('www.google.com', {\n userResDecorator: function(proxyRes, proxyResData, userReq, userRes) {\n data = JSON.parse(proxyResData.toString('utf8'));\n data.newProperty = 'exciting data';\n return JSON.stringify(data);\n }\n}));\n```\n\n```js\napp.use(proxy('httpbin.org', {\n userResDecorator: function(proxyRes, proxyResData) {\n return new Promise(function(resolve) {\n proxyResData.funkyMessage = 'oi io oo ii';\n setTimeout(function() {\n resolve(proxyResData);\n }, 200);\n });\n }\n}));\n```\n\n##### 304 - Not Modified\n\nWhen your proxied service returns 304, not modified, this step will be skipped, since there is no body to decorate.\n\n##### exploiting references\nThe intent is that this be used to modify the proxy response data only.\n\nNote:\nThe other arguments (proxyRes, userReq, userRes) are passed by reference, so\nyou *can* currently exploit this to modify either response's headers, for\ninstance, but this is not a reliable interface. I expect to close this\nexploit in a future release, while providing an additional hook for mutating\nthe userRes before sending.\n\n##### gzip responses\n\nIf your proxy response is gzipped, this program will automatically unzip\nit before passing to your function, then zip it back up before piping it to the\nuser response. There is currently no way to short-circuit this behavior.\n\n#### limit\n\nThis sets the body size limit (default: `1mb`). If the body size is larger than the specified (or default) limit,\na `413 Request Entity Too Large` error will be returned. See [bytes.js](https://www.npmjs.com/package/bytes) for\na list of supported formats.\n\n```js\napp.use('/proxy', proxy('www.google.com', {\n limit: '5mb'\n}));\n```\n\n#### memoizeHost\n\nDefaults to ```true```.\n\nWhen true, the ```host``` argument will be parsed on first request, and\nmemoized for subsequent requests.\n\nWhen ```false```, ```host``` argument will be parsed on each request.\n\nE.g.,\n\n```js\n\n function coinToss() { return Math.random() > .5 }\n function getHost() { return coinToss() ? 'http://yahoo.com' : 'http://google.com' }\n\n app.use(proxy(getHost, {\n memoizeHost: false\n }))\n```\n\nIn this example, when ```memoizeHost:false```, the coinToss occurs on each\nrequest, and each request could get either value.\n\nConversely, When ```memoizeHost:true```, the coinToss would occur on the first\nrequest, and all additional requests would return the value resolved on the\nfirst request.\n\n\n### userResHeaderDecorator\n\nWhen a `userResHeaderDecorator` is defined, the return of this method will replace (rather than be merged on to) the headers for `userRes`.\n\n```js\napp.use('/proxy', proxy('www.google.com', {\n userResHeaderDecorator(headers, userReq, userRes, proxyReq, proxyRes) {\n // recieves an Object of headers, returns an Object of headers.\n return headers;\n }\n}));\n```\n\n\n#### decorateRequest\n\nREMOVED: See ```proxyReqOptDecorator``` and ```proxyReqBodyDecorator```.\n\n\n#### skipToNextHandlerFilter(supports Promise form)\n(experimental: this interface may change in upcoming versions)\n\nAllows you to inspect the proxy response, and decide if you want to continue processing (via express-http-proxy) or call ```next()``` to return control to express.\n\n```js\napp.use('/proxy', proxy('www.google.com', {\n skipToNextHandlerFilter: function(proxyRes) {\n return proxyRes.statusCode === 404;\n }\n}));\n```\n\n### proxyErrorHandler\n\nBy default, ```express-http-proxy``` will pass any errors except ECONNRESET to\nnext, so that your application can handle or react to them, or just drop\nthrough to your default error handling. ECONNRESET errors are immediately\nreturned to the user for historical reasons.\n\nIf you would like to modify this behavior, you can provide your own ```proxyErrorHandler```.\n\n\n```js\n// Example of skipping all error handling.\n\napp.use(proxy('localhost:12346', {\n proxyErrorHandler: function(err, res, next) {\n next(err);\n }\n}));\n\n\n// Example of rolling your own\n\napp.use(proxy('localhost:12346', {\n proxyErrorHandler: function(err, res, next) {\n switch (err && err.code) {\n case 'ECONNRESET': { return res.status(405).send('504 became 405'); }\n case 'ECONNREFUSED': { return res.status(200).send('gotcher back'); }\n default: { next(err); }\n }\n}}));\n```\n\n\n\n#### proxyReqOptDecorator (supports Promise form)\n\nYou can override most request options before issuing the proxyRequest.\nproxyReqOpt represents the options argument passed to the (http|https).request\nmodule.\n\nNOTE: req.path cannot be changed via this method; use ```proxyReqPathResolver``` instead. (see https://github.com/villadora/express-http-proxy/issues/243)\n\n```js\napp.use('/proxy', proxy('www.google.com', {\n proxyReqOptDecorator: function(proxyReqOpts, srcReq) {\n // you can update headers\n proxyReqOpts.headers['Content-Type'] = 'text/html';\n // you can change the method\n proxyReqOpts.method = 'GET';\n return proxyReqOpts;\n }\n}));\n```\n\nYou can use a Promise for async style.\n\n```js\napp.use('/proxy', proxy('www.google.com', {\n proxyReqOptDecorator: function(proxyReqOpts, srcReq) {\n return new Promise(function(resolve, reject) {\n proxyReqOpts.headers['Content-Type'] = 'text/html';\n resolve(proxyReqOpts);\n })\n }\n}));\n```\n\n#### proxyReqBodyDecorator (supports Promise form)\n\nYou can mutate the body content before sending the proxyRequest.\n\n```js\napp.use('/proxy', proxy('www.google.com', {\n proxyReqBodyDecorator: function(bodyContent, srcReq) {\n return bodyContent.split('').reverse().join('');\n }\n}));\n```\n\nYou can use a Promise for async style.\n\n```js\napp.use('/proxy', proxy('www.google.com', {\n proxyReqBodyDecorator: function(proxyReq, srcReq) {\n return new Promise(function(resolve, reject) {\n http.get('http://dev/null', function (err, res) {\n if (err) { reject(err); }\n resolve(res);\n });\n })\n }\n}));\n```\n\n#### https\n\nNormally, your proxy request will be made on the same protocol as the `host`\nparameter. If you'd like to force the proxy request to be https, use this\noption.\n\n```js\napp.use('/proxy', proxy('www.google.com', {\n https: true\n}));\n```\n\n#### preserveHostHdr\n\nYou can copy the host HTTP header to the proxied express server using the `preserveHostHdr` option.\n\n```js\napp.use('/proxy', proxy('www.google.com', {\n preserveHostHdr: true\n}));\n```\n\n#### parseReqBody\n\nThe ```parseReqBody``` option allows you to control parsing the request body.\nFor example, disabling body parsing is useful for large uploads where it would be inefficient\nto hold the data in memory.\n\n##### Note: this setting is required for binary uploads. A future version of this library may handle this for you.\n\nThis defaults to true in order to preserve legacy behavior.\n\nWhen false, no action will be taken on the body and accordingly ```req.body``` will no longer be set.\n\nNote that setting this to false overrides ```reqAsBuffer``` and ```reqBodyEncoding``` below.\n\n```js\napp.use('/proxy', proxy('www.google.com', {\n parseReqBody: false\n}));\n```\n\n#### reqAsBuffer\n\nNote: this is an experimental feature. ymmv\n\nThe ```reqAsBuffer``` option allows you to ensure the req body is encoded as a Node\n```Buffer``` when sending a proxied request. Any value for this is truthy.\n\nThis defaults to to false in order to preserve legacy behavior. Note that\nthe value of ```reqBodyEnconding``` is used as the encoding when coercing strings\n(and stringified JSON) to Buffer.\n\nIgnored if ```parseReqBody``` is set to false.\n\n```js\napp.use('/proxy', proxy('www.google.com', {\n reqAsBuffer: true\n}));\n```\n\n#### reqBodyEncoding\n\nEncoding used to decode request body. Defaults to ```utf-8```.\n\nUse ```null``` to preserve as Buffer when proxied request body is a Buffer. (e.g image upload)\nAccept any values supported by [raw-body](https://www.npmjs.com/package/raw-body#readme).\n\nThe same encoding is used in the intercept method.\n\nIgnored if ```parseReqBody``` is set to false.\n\n```js\napp.use('/post', proxy('httpbin.org', {\n reqBodyEncoding: null\n}));\n```\n\n#### timeout\n\nBy default, node does not express a timeout on connections.\nUse timeout option to impose a specific timeout.\nTimed-out requests will respond with 504 status code and a X-Timeout-Reason header.\n\n```js\napp.use('/', proxy('httpbin.org', {\n timeout: 2000 // in milliseconds, two seconds\n}));\n```\n\n## Trace debugging\n\nThe node-debug module is used to provide a trace debugging capability.\n\n```\nDEBUG=express-http-proxy npm run YOUR_PROGRAM\nDEBUG=express-http-proxy npm run YOUR_PROGRAM | grep 'express-http-proxy' # to filter down to just these messages\n```\n\nWill trace the execution of the express-http-proxy module in order to aide debugging.\n\n\n\n\n## Upgrade to 1.0, transition guide and breaking changes\n\n1.\n```decorateRequest``` has been REMOVED, and will generate an error when called. See ```proxyReqOptDecorator``` and ```proxyReqBodyDecorator```.\n\nResolution: Most authors will simply need to change the method name for their\ndecorateRequest method; if author was decorating reqOpts and reqBody in the\nsame method, this will need to be split up.\n\n\n2.\n```intercept``` has been REMOVED, and will generate an error when called. See ```userResDecorator```.\n\nResolution: Most authors will simply need to change the method name from ```intercept``` to ```userResDecorator```, and exit the method by returning the value, rather than passing it to a callback. E.g.:\n\nBefore:\n\n```js\napp.use('/proxy', proxy('www.google.com', {\n intercept: function(proxyRes, proxyResData, userReq, userRes, cb) {\n data = JSON.parse(proxyResData.toString('utf8'));\n data.newProperty = 'exciting data';\n cb(null, JSON.stringify(data));\n }\n}));\n```\n\nNow:\n\n```js\napp.use('/proxy', proxy('www.google.com', {\n userResDecorator: function(proxyRes, proxyResData, userReq, userRes) {\n data = JSON.parse(proxyResData.toString('utf8'));\n data.newProperty = 'exciting data';\n return JSON.stringify(data);\n }\n}));\n```\n\n3.\n```forwardPath``` and ```forwardPathAsync``` have been DEPRECATED and will generate a warning when called. See ```proxyReqPathResolver```.\n\nResolution: Simple update the name of either ```forwardPath``` or ```forwardPathAsync``` to ```proxyReqPathResolver```.\n\n## When errors occur on your proxy server\n\nWhen your proxy server responds with an error, express-http-proxy returns a response with the same status code. See ```test/catchingErrors``` for syntax details.\n\nWhen your proxy server times out, express-http-proxy will continue to wait indefinitely for a response, unless you define a ```timeout``` as described above.\n\n\n## Questions\n\n### Q: Does it support https proxy?\n\nThe library will automatically use https if the provided path has 'https://' or ':443'. You may also set option ```https``` to true to always use https.\n\nYou can use ```proxyReqOptDecorator``` to ammend any auth or challenge headers required to succeed https.\n\n### Q: How can I support non-standard certificate chains?\n\nYou can use the ability to decorate the proxy request prior to sending. See ```proxyReqOptDecorator``` for more details.\n\n```js\napp.use('/', proxy('internalhost.example.com', {\n proxyReqOptDecorator: function(proxyReqOpts, originalReq) {\n proxyReqOpts.ca = [caCert, intermediaryCert]\n return proxyReqOpts;\n }\n})\n```\n\n### Q: How to ignore self-signed certificates ?\n\nYou can set the `rejectUnauthorized` value in proxy request options prior to sending. See ```proxyReqOptDecorator``` for more details.\n\n```js\napp.use('/', proxy('internalhost.example.com', {\n proxyReqOptDecorator: function(proxyReqOpts, originalReq) {\n proxyReqOpts.rejectUnauthorized = false\n return proxyReqOpts;\n }\n}))\n```\n\n\n## Release Notes\n\n| Release | Notes |\n| --- | --- |\n| 1.6.3 | [#453] Author should be able to delete headers in userResHeaderDecorator.\n| 1.6.2 | Update node.js versions used by ci. |\n| 1.6.1 | Minor bug fixes and documentation. |\n| 1.6.0 | Do gzip and gunzip aysyncronously. Test and documentation improvements, dependency updates. |\n| 1.5.1 | Fixes bug in stringifying debug messages. |\n| 1.5.0 | Fixes bug in `filter` signature. Fix bug in skipToNextHandler, add expressHttpProxy value to user res when skipped. Add tests for host as ip address. |\n| 1.4.0 | DEPRECATED. Critical bug in the `filter` api.| \n| 1.3.0 | DEPRECATED. Critical bug in the `filter` api. `filter` now supports Promises. Update linter to eslint. |\n| 1.2.0 | Auto-stream when no decorations are made to req/res. Improved docs, fixes issues in maybeSkipToNexthandler, allow authors to manage error handling. | \n| 1.1.0 | Add step to allow response headers to be modified.\n| 1.0.7 | Update dependencies. Improve docs on promise rejection. Fix promise rejection on body limit. Improve debug output. |\n| 1.0.6 | Fixes preserveHostHdr not working, skip userResDecorator on 304, add maybeSkipToNext, test improvements and cleanup. |\n| 1.0.5 | Minor documentation and test patches |\n| 1.0.4 | Minor documentation, test, and package fixes |\n| 1.0.3 | Fixes 'limit option is not taken into account |\n| 1.0.2 | Minor docs corrections. |\n| 1.0.1 | Minor docs adjustments. |\n| 1.0.0 | Major revision.
REMOVE decorateRequest, ADD proxyReqOptDecorator and proxyReqBodyDecorator.
REMOVE intercept, ADD userResDecorator
userResDecorator supports a Promise form for async operations.
General cleanup of structure and application of hooks. Documentation improvements. Update all dependencies. Re-organize code as a series of workflow steps, each (potentially) supporting a promise, and creating a reusable pattern for future development. |\n| 0.11.0 | Allow author to prevent host from being memoized between requests. General program cleanup. |\n| 0.10.1| Fixed issue where 'body encoding' was being incorrectly set to the character encoding.
Dropped explicit support for node 0.10.
Intercept can now deal with gziped responses.
Author can now 'force https', even if the original request is over http.
Do not call next after ECONNRESET catch. |\n| 0.10.0 | Fix regression in forwardPath implementation. |\n| 0.9.1 | Documentation updates. Set 'Accept-Encoding' header to match bodyEncoding. |\n| 0.9.0 | Better handling for request body when body is JSON. |\n| 0.8.0 | Features: add forwardPathAsync option
Updates: modernize dependencies
Fixes: Exceptions parsing proxied response causes error: Can't set headers after they are sent. (#111)
If client request aborts, proxied request is aborted too (#107) |\n| 0.7.4 | Move jscs to devDependencies to avoid conflict with nsp. |\n| 0.7.3 | Adds a timeout option. Code organization and small bug fixes. |\n| 0.7.2 | Collecting many minor documentation and test improvements. |\n| 0.4.0 | Signature of `intercept` callback changed from `function(data, req, res, callback)` to `function(rsp, data, req, res, callback)` where `rsp` is the original response from the target |\n\n## Licence\n\nMIT\n\n"}