You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
63 lines
21 KiB
63 lines
21 KiB
{ |
|
"name": "http-proxy", |
|
"version": "0.10.3", |
|
"description": "A full-featured http reverse proxy for node.js", |
|
"author": { |
|
"name": "Nodejitsu Inc.", |
|
"email": "[email protected]" |
|
}, |
|
"maintainers": [ |
|
{ |
|
"name": "indexzero", |
|
"email": "[email protected]" |
|
}, |
|
{ |
|
"name": "AvianFlu", |
|
"email": "[email protected]" |
|
} |
|
], |
|
"repository": { |
|
"type": "git", |
|
"url": "http://github.com/nodejitsu/node-http-proxy.git" |
|
}, |
|
"keywords": [ |
|
"reverse", |
|
"proxy", |
|
"http" |
|
], |
|
"dependencies": { |
|
"colors": "0.x.x", |
|
"optimist": "0.3.x", |
|
"pkginfo": "0.2.x", |
|
"utile": "~0.1.7" |
|
}, |
|
"devDependencies": { |
|
"request": "2.14.x", |
|
"vows": "0.7.x", |
|
"async": "0.2.x", |
|
"socket.io": "0.9.11", |
|
"socket.io-client": "0.9.11", |
|
"ws": "0.4.23" |
|
}, |
|
"main": "./lib/node-http-proxy", |
|
"bin": { |
|
"node-http-proxy": "./bin/node-http-proxy" |
|
}, |
|
"scripts": { |
|
"test": "npm run-script test-http && npm run-script test-https && npm run-script test-core", |
|
"test-http": "vows --spec && vows --spec --target=https", |
|
"test-https": "vows --spec --proxy=https && vows --spec --proxy=https --target=https", |
|
"test-core": "test/core/run" |
|
}, |
|
"engines": { |
|
"node": ">= 0.6.6" |
|
}, |
|
"readme": "# node-http-proxy [](http://travis-ci.org/nodejitsu/node-http-proxy)\n\n<img src=\"http://i.imgur.com/8fTt9.png\" />\n\n## Battle-hardened node.js http proxy\n\n### Features\n\n* Reverse proxies incoming http.ServerRequest streams\n* Can be used as a CommonJS module in node.js\n* Uses event buffering to support application latency in proxied requests\n* Reverse or Forward Proxy based on simple JSON-based configuration\n* Supports [WebSockets][1]\n* Supports [HTTPS][2]\n* Minimal request overhead and latency\n* Full suite of functional tests\n* Battled-hardened through __production usage__ @ [nodejitsu.com][0]\n* Written entirely in Javascript\n* Easy to use API\n\n### When to use node-http-proxy\n\nLet's suppose you were running multiple http application servers, but you only wanted to expose one machine to the internet. You could setup node-http-proxy on that one machine and then reverse-proxy the incoming http requests to locally running services which were not exposed to the outside network. \n\n### Installing npm (node package manager)\n\n```\ncurl https://npmjs.org/install.sh | sh\n```\n\n### Installing node-http-proxy\n\n```\nnpm install http-proxy\n```\n\n## Using node-http-proxy\n\nThere are several ways to use node-http-proxy; the library is designed to be flexible so that it can be used by itself, or in conjunction with other node.js libraries / tools:\n\n1. Standalone HTTP Proxy server\n2. Inside of another HTTP server (like Connect)\n3. In conjunction with a Proxy Routing Table\n4. As a forward-proxy with a reverse proxy \n5. From the command-line as a long running process\n6. customized with 3rd party middleware.\n\nIn each of these scenarios node-http-proxy can handle any of these types of requests:\n\n1. HTTP Requests (http://)\n2. HTTPS Requests (https://)\n3. WebSocket Requests (ws://)\n4. Secure WebSocket Requests (wss://)\n\nSee the [examples][3] for more working sample code.\n\n### Setup a basic stand-alone proxy server\n\n``` js\nvar http = require('http'),\n httpProxy = require('http-proxy');\n//\n// Create your proxy server\n//\nhttpProxy.createServer(9000, 'localhost').listen(8000);\n\n//\n// Create your target server\n//\nhttp.createServer(function (req, res) {\n res.writeHead(200, { 'Content-Type': 'text/plain' });\n res.write('request successfully proxied!' + '\\n' + JSON.stringify(req.headers, true, 2));\n res.end();\n}).listen(9000);\n```\n\n### Setup a stand-alone proxy server with custom server logic\n\n``` js\nvar http = require('http'),\n httpProxy = require('http-proxy');\n \n//\n// Create a proxy server with custom application logic\n//\nhttpProxy.createServer(function (req, res, proxy) {\n //\n // Put your custom server logic here\n //\n proxy.proxyRequest(req, res, {\n host: 'localhost',\n port: 9000\n });\n}).listen(8000);\n\nhttp.createServer(function (req, res) {\n res.writeHead(200, { 'Content-Type': 'text/plain' });\n res.write('request successfully proxied: ' + req.url +'\\n' + JSON.stringify(req.headers, true, 2));\n res.end();\n}).listen(9000);\n```\n\n### Setup a stand-alone proxy server with latency (e.g. IO, etc)\n\n``` js\nvar http = require('http'),\n httpProxy = require('http-proxy');\n\n//\n// Create a proxy server with custom application logic\n//\nhttpProxy.createServer(function (req, res, proxy) {\n //\n // Buffer the request so that `data` and `end` events\n // are not lost during async operation(s).\n //\n var buffer = httpProxy.buffer(req);\n \n //\n // Wait for two seconds then respond: this simulates\n // performing async actions before proxying a request\n //\n setTimeout(function () {\n proxy.proxyRequest(req, res, {\n host: 'localhost',\n port: 9000, \n buffer: buffer\n }); \n }, 2000);\n}).listen(8000);\n\nhttp.createServer(function (req, res) {\n res.writeHead(200, { 'Content-Type': 'text/plain' });\n res.write('request successfully proxied: ' + req.url +'\\n' + JSON.stringify(req.headers, true, 2));\n res.end();\n}).listen(9000);\n```\n\n### Proxy requests within another http server\n\n``` js\nvar http = require('http'),\n httpProxy = require('http-proxy');\n \n//\n// Create a new instance of HttProxy to use in your server\n//\nvar proxy = new httpProxy.RoutingProxy();\n\n//\n// Create a regular http server and proxy its handler\n//\nhttp.createServer(function (req, res) {\n //\n // Put your custom server logic here, then proxy\n //\n proxy.proxyRequest(req, res, {\n host: 'localhost',\n port: 9000\n });\n}).listen(8001);\n\nhttp.createServer(function (req, res) {\n res.writeHead(200, { 'Content-Type': 'text/plain' });\n res.write('request successfully proxied: ' + req.url +'\\n' + JSON.stringify(req.headers, true, 2));\n res.end();\n}).listen(9000); \n```\n\n### Proxy requests using a ProxyTable\nA Proxy Table is a simple lookup table that maps incoming requests to proxy target locations. Take a look at an example of the options you need to pass to httpProxy.createServer:\n\n``` js\nvar options = {\n router: {\n 'foo.com/baz': '127.0.0.1:8001',\n 'foo.com/buz': '127.0.0.1:8002',\n 'bar.com/buz': '127.0.0.1:8003'\n }\n};\n```\n\nThe above route table will take incoming requests to 'foo.com/baz' and forward them to '127.0.0.1:8001'. Likewise it will take incoming requests to 'foo.com/buz' and forward them to '127.0.0.1:8002'. The routes themselves are later converted to regular expressions to enable more complex matching functionality. We can create a proxy server with these options by using the following code:\n\n``` js\nvar proxyServer = httpProxy.createServer(options);\nproxyServer.listen(80);\n```\n\n### Proxy requests using a 'Hostname Only' ProxyTable\nAs mentioned in the previous section, all routes passes to the ProxyTable are by default converted to regular expressions that are evaluated at proxy-time. This is good for complex URL rewriting of proxy requests, but less efficient when one simply wants to do pure hostname routing based on the HTTP 'Host' header. If you are only concerned with hostname routing, you change the lookup used by the internal ProxyTable:\n\n``` js\nvar options = {\n hostnameOnly: true,\n router: {\n 'foo.com': '127.0.0.1:8001',\n 'bar.com': '127.0.0.1:8002'\n }\n}\n```\n\nNotice here that I have not included paths on the individual domains because this is not possible when using only the HTTP 'Host' header. Care to learn more? See [RFC2616: HTTP/1.1, Section 14.23, \"Host\"][4].\n\n### Proxy requests using a 'Pathname Only' ProxyTable\n\nIf you dont care about forwarding to different hosts, you can redirect based on the request path.\n\n``` js\nvar options = {\n pathnameOnly: true,\n router: {\n '/wiki': '127.0.0.1:8001',\n '/blog': '127.0.0.1:8002',\n '/api': '127.0.0.1:8003'\n }\n}\n```\n\nThis comes in handy if you are running separate services or applications on separate paths. Note, using this option disables routing by hostname entirely.\n\n\n### Proxy requests with an additional forward proxy\nSometimes in addition to a reverse proxy, you may want your front-facing server to forward traffic to another location. For example, if you wanted to load test your staging environment. This is possible when using node-http-proxy using similar JSON-based configuration to a proxy table: \n\n``` js\nvar proxyServerWithForwarding = httpProxy.createServer(9000, 'localhost', {\n forward: {\n port: 9000,\n host: 'staging.com'\n }\n});\nproxyServerWithForwarding.listen(80);\n```\n\nThe forwarding option can be used in conjunction with the proxy table options by simply including both the 'forward' and 'router' properties in the options passed to 'createServer'.\n\n### Listening for proxy events\nSometimes you want to listen to an event on a proxy. For example, you may want to listen to the 'end' event, which represents when the proxy has finished proxying a request.\n\n``` js\nvar httpProxy = require('http-proxy');\n\nvar server = httpProxy.createServer(function (req, res, proxy) {\n var buffer = httpProxy.buffer(req);\n\n proxy.proxyRequest(req, res, {\n host: '127.0.0.1',\n port: 9000,\n buffer: buffer\n });\n});\n\nserver.proxy.on('end', function () {\n console.log(\"The request was proxied.\");\n});\n\nserver.listen(8000);\n```\n\nIt's important to remember not to listen for events on the proxy object in the function passed to `httpProxy.createServer`. Doing so would add a new listener on every request, which would end up being a disaster.\n\n## Using HTTPS\nYou have all the full flexibility of node-http-proxy offers in HTTPS as well as HTTP. The two basic scenarios are: with a stand-alone proxy server or in conjunction with another HTTPS server.\n\n### Proxying to HTTP from HTTPS\nThis is probably the most common use-case for proxying in conjunction with HTTPS. You have some front-facing HTTPS server, but all of your internal traffic is HTTP. In this way, you can reduce the number of servers to which your CA and other important security files are deployed and reduce the computational overhead from HTTPS traffic. \n\nUsing HTTPS in `node-http-proxy` is relatively straight-forward:\n \n``` js\nvar fs = require('fs'),\n http = require('http'),\n https = require('https'),\n httpProxy = require('http-proxy');\n \nvar options = {\n https: {\n key: fs.readFileSync('path/to/your/key.pem', 'utf8'),\n cert: fs.readFileSync('path/to/your/cert.pem', 'utf8')\n }\n};\n\n//\n// Create a standalone HTTPS proxy server\n//\nhttpProxy.createServer(8000, 'localhost', options).listen(8001);\n\n//\n// Create an instance of HttpProxy to use with another HTTPS server\n//\nvar proxy = new httpProxy.HttpProxy({\n target: {\n host: 'localhost', \n port: 8000\n }\n});\nhttps.createServer(options.https, function (req, res) {\n proxy.proxyRequest(req, res)\n}).listen(8002);\n\n//\n// Create the target HTTPS server for both cases\n//\nhttp.createServer(function (req, res) {\n res.writeHead(200, { 'Content-Type': 'text/plain' });\n res.write('hello https\\n');\n res.end();\n}).listen(8000);\n```\n\n### Using two certificates\n\nSuppose that your reverse proxy will handle HTTPS traffic for two different domains `fobar.com` and `barbaz.com`.\nIf you need to use two different certificates you can take advantage of [Server Name Indication](http://en.wikipedia.org/wiki/Server_Name_Indication).\n\n``` js\nvar https = require('https'),\n path = require(\"path\"),\n fs = require(\"fs\"),\n crypto = require(\"crypto\");\n\n//\n// generic function to load the credentials context from disk\n//\nfunction getCredentialsContext (cer) {\n return crypto.createCredentials({\n key: fs.readFileSync(path.join(__dirname, 'certs', cer + '.key')),\n cert: fs.readFileSync(path.join(__dirname, 'certs', cer + '.crt'))\n }).context;\n}\n\n//\n// A certificate per domain hash\n//\nvar certs = {\n \"fobar.com\": getCredentialsContext(\"foobar\"),\n \"barbaz.com\": getCredentialsContext(\"barbaz\")\n};\n\n//\n// Proxy options\n//\nvar options = {\n https: {\n SNICallback: function (hostname) {\n return certs[hostname];\n },\n cert: myCert,\n key: myKey,\n ca: [myCa]\n },\n hostnameOnly: true,\n router: {\n 'fobar.com': '127.0.0.1:8001',\n 'barbaz.com': '127.0.0.1:8002'\n }\n};\n\n//\n// Create a standalone HTTPS proxy server\n//\nhttpProxy.createServer(options).listen(8001);\n\n//\n// Create the target HTTPS server\n//\nhttp.createServer(function (req, res) {\n res.writeHead(200, { 'Content-Type': 'text/plain' });\n res.write('hello https\\n');\n res.end();\n}).listen(8000);\n\n```\n\n### Proxying to HTTPS from HTTPS\nProxying from HTTPS to HTTPS is essentially the same as proxying from HTTPS to HTTP, but you must include the `target` option in when calling `httpProxy.createServer` or instantiating a new instance of `HttpProxy`.\n\n``` js\nvar fs = require('fs'),\n https = require('https'),\n httpProxy = require('http-proxy');\n \nvar options = {\n https: {\n key: fs.readFileSync('path/to/your/key.pem', 'utf8'),\n cert: fs.readFileSync('path/to/your/cert.pem', 'utf8')\n },\n target: {\n https: true // This could also be an Object with key and cert properties\n }\n};\n\n//\n// Create a standalone HTTPS proxy server\n//\nhttpProxy.createServer(8000, 'localhost', options).listen(8001);\n\n//\n// Create an instance of HttpProxy to use with another HTTPS server\n//\nvar proxy = new httpProxy.HttpProxy({ \n target: {\n host: 'localhost', \n port: 8000,\n https: true\n }\n});\n\nhttps.createServer(options.https, function (req, res) {\n proxy.proxyRequest(req, res);\n}).listen(8002);\n\n//\n// Create the target HTTPS server for both cases\n//\nhttps.createServer(options.https, function (req, res) {\n res.writeHead(200, { 'Content-Type': 'text/plain' });\n res.write('hello https\\n');\n res.end();\n}).listen(8000);\n```\n## Middleware\n\n`node-http-proxy` now supports connect middleware. Add middleware functions to your createServer call:\n\n``` js\nhttpProxy.createServer(\n require('connect-gzip').gzip(),\n 9000, 'localhost'\n).listen(8000);\n```\n\nA regular request we receive is to support the modification of html/xml content that is returned in the response from an upstream server. \n\n[Harmon](https://github.com/No9/harmon/) is a stream based middleware plugin that is designed to solve that problem in the most effective way possible. \n\n## Proxying WebSockets\nWebsockets are handled automatically when using `httpProxy.createServer()`, however, if you supply a callback inside the createServer call, you will need to handle the 'upgrade' proxy event yourself. Here's how:\n\n```js\n\nvar options = {\n ....\n};\n\nvar server = httpProxy.createServer(\n callback/middleware, \n options\n);\n\nserver.listen(port, function () { ... });\nserver.on('upgrade', function (req, socket, head) {\n server.proxy.proxyWebSocketRequest(req, socket, head);\n});\n```\n\nIf you would rather not use createServer call, and create the server that proxies yourself, see below:\n\n``` js\nvar http = require('http'),\n httpProxy = require('http-proxy');\n \n//\n// Create an instance of node-http-proxy\n//\nvar proxy = new httpProxy.HttpProxy({\n target: {\n host: 'localhost',\n port: 8000\n }\n});\n\nvar server = http.createServer(function (req, res) {\n //\n // Proxy normal HTTP requests\n //\n proxy.proxyRequest(req, res);\n});\n\nserver.on('upgrade', function (req, socket, head) {\n //\n // Proxy websocket requests too\n //\n proxy.proxyWebSocketRequest(req, socket, head);\n});\n\nserver.listen(8080);\n```\n\n### with custom server logic\n\n``` js\nvar httpProxy = require('http-proxy')\n\nvar server = httpProxy.createServer(function (req, res, proxy) {\n //\n // Put your custom server logic here\n //\n proxy.proxyRequest(req, res, {\n host: 'localhost',\n port: 9000\n });\n})\n\nserver.on('upgrade', function (req, socket, head) {\n //\n // Put your custom server logic here\n //\n server.proxy.proxyWebSocketRequest(req, socket, head, {\n host: 'localhost',\n port: 9000\n });\n});\n\nserver.listen(8080);\n```\n\n### Configuring your Socket limits\n\nBy default, `node-http-proxy` will set a 100 socket limit for all `host:port` proxy targets. You can change this in two ways: \n\n1. By passing the `maxSockets` option to `httpProxy.createServer()`\n2. By calling `httpProxy.setMaxSockets(n)`, where `n` is the number of sockets you with to use. \n\n## POST requests and buffering\n\nexpress.bodyParser will interfere with proxying of POST requests (and other methods that have a request \nbody). With bodyParser active, proxied requests will never send anything to the upstream server, and \nthe original client will just hang. See https://github.com/nodejitsu/node-http-proxy/issues/180 for options.\n\n## Using node-http-proxy from the command line\nWhen you install this package with npm, a node-http-proxy binary will become available to you. Using this binary is easy with some simple options:\n\n``` js\nusage: node-http-proxy [options] \n\nAll options should be set with the syntax --option=value\n\noptions:\n --port PORT Port that the proxy server should run on\n --target HOST:PORT Location of the server the proxy will target\n --config OUTFILE Location of the configuration file for the proxy server\n --silent Silence the log output from the proxy server\n -h, --help You're staring at it\n```\n\n<br/>\n## Why doesn't node-http-proxy have more advanced features like x, y, or z?\n\nIf you have a suggestion for a feature currently not supported, feel free to open a [support issue][6]. node-http-proxy is designed to just proxy http requests from one server to another, but we will be soon releasing many other complimentary projects that can be used in conjunction with node-http-proxy.\n\n## Options\n\n### Http Proxy\n\n`createServer()` supports the following options\n\n```javascript\n{\n forward: { // options for forward-proxy\n port: 8000,\n host: 'staging.com'\n },\n target : { // options for proxy target\n port : 8000, \n host : 'localhost',\n };\n source : { // additional options for websocket proxying \n host : 'localhost',\n port : 8000,\n https: true\n },\n enable : {\n xforward: true // enables X-Forwarded-For\n },\n changeOrigin: false, // changes the origin of the host header to the target URL\n timeout: 120000 // override the default 2 minute http socket timeout value in milliseconds\n}\n```\n\n## Run Tests\nThe test suite is designed to fully cover the combinatoric possibilities of HTTP and HTTPS proxying:\n\n1. HTTP --> HTTP\n2. HTTPS --> HTTP\n3. HTTPS --> HTTPS\n4. HTTP --> HTTPS\n\n```\nvows test/*-test.js --spec\nvows test/*-test.js --spec --https\nvows test/*-test.js --spec --https --target=https\nvows test/*-test.js --spec --target=https\n```\n\n<br/>\n### License\n\n(The MIT License)\n\nCopyright (c) 2010 Charlie Robbins, Mikeal Rogers, Fedor Indutny, & Marak Squires\n\nPermission is hereby granted, free of charge, to any person obtaining\na copy of this software and associated documentation files (the\n\"Software\"), to deal in the Software without restriction, including\nwithout limitation the rights to use, copy, modify, merge, publish,\ndistribute, sublicense, and/or sell copies of the Software, and to\npermit persons to whom the Software is furnished to do so, subject to\nthe following conditions:\n\nThe above copyright notice and this permission notice shall be\nincluded in all copies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND,\nEXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF\nMERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND\nNONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE\nLIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION\nOF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION\nWITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.\n\n[0]: http://nodejitsu.com\n[1]: https://github.com/nodejitsu/node-http-proxy/blob/master/examples/websocket/websocket-proxy.js\n[2]: https://github.com/nodejitsu/node-http-proxy/blob/master/examples/http/proxy-https-to-http.js\n[3]: https://github.com/nodejitsu/node-http-proxy/tree/master/examples\n[4]: http://www.ietf.org/rfc/rfc2616.txt\n[5]: http://socket.io\n[6]: http://github.com/nodejitsu/node-http-proxy/issues\n", |
|
"readmeFilename": "README.md", |
|
"bugs": { |
|
"url": "https://github.com/nodejitsu/node-http-proxy/issues" |
|
}, |
|
"homepage": "https://github.com/nodejitsu/node-http-proxy", |
|
"_id": "[email protected]", |
|
"_from": "http-proxy@~0.10" |
|
}
|
|
|