Skip to content

N
node-http-proxy
Commit 28f6dc15 authored by Ben Atkin's avatar Ben Atkin
Browse files
Options

format markdown for syntax highlighting on GitHub

parent 332d2d78
Show whitespace changes
Inline Side-by-side
Showing with 205 additions and 205 deletions
README.md
View file @ 28f6dc15
...@@ -23,14 +23,14 @@ ...@@ -23,14 +23,14 @@
Let'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. Let'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.
### Installing npm (node package manager) ### Installing npm (node package manager)
<pre> ``` js
curl http://npmjs.org/install.sh | sh curl http://npmjs.org/install.sh | sh
</pre> ```
### Installing node-http-proxy ### Installing node-http-proxy
<pre> ``` js
npm install http-proxy npm install http-proxy
</pre> ```
## Using node-http-proxy ## Using node-http-proxy
...@@ -51,33 +51,33 @@ In each of these scenarios node-http-proxy can handle any of these types of requ ...@@ -51,33 +51,33 @@ In each of these scenarios node-http-proxy can handle any of these types of requ
See the [examples][3] for more working sample code. See the [examples][3] for more working sample code.
### Setup a basic stand-alone proxy server ### Setup a basic stand-alone proxy server
<pre> ``` js
var http = require('http'), var http = require('http'),
httpProxy = require('http-proxy'); httpProxy = require('http-proxy');
// //
// Create your proxy server // Create your proxy server
// //
httpProxy.createServer(9000, 'localhost').listen(8000); httpProxy.createServer(9000, 'localhost').listen(8000);
// //
// Create your target server // Create your target server
// //
http.createServer(function (req, res) { http.createServer(function (req, res) {
res.writeHead(200, { 'Content-Type': 'text/plain' }); res.writeHead(200, { 'Content-Type': 'text/plain' });
res.write('request successfully proxied!' + '\n' + JSON.stringify(req.headers, true, 2)); res.write('request successfully proxied!' + '\n' + JSON.stringify(req.headers, true, 2));
res.end(); res.end();
}).listen(9000); }).listen(9000);
</pre> ```
### Setup a stand-alone proxy server with custom server logic ### Setup a stand-alone proxy server with custom server logic
<pre> ``` js
var http = require('http'), var http = require('http'),
httpProxy = require('http-proxy'); httpProxy = require('http-proxy');
// //
// Create a proxy server with custom application logic // Create a proxy server with custom application logic
// //
httpProxy.createServer(function (req, res, proxy) { httpProxy.createServer(function (req, res, proxy) {
// //
// Put your custom server logic here // Put your custom server logic here
// //
...@@ -85,24 +85,24 @@ See the [examples][3] for more working sample code. ...@@ -85,24 +85,24 @@ See the [examples][3] for more working sample code.
host: 'localhost', host: 'localhost',
port: 9000 port: 9000
}); });
}).listen(8000); }).listen(8000);
http.createServer(function (req, res) { http.createServer(function (req, res) {
res.writeHead(200, { 'Content-Type': 'text/plain' }); res.writeHead(200, { 'Content-Type': 'text/plain' });
res.write('request successfully proxied: ' + req.url +'\n' + JSON.stringify(req.headers, true, 2)); res.write('request successfully proxied: ' + req.url +'\n' + JSON.stringify(req.headers, true, 2));
res.end(); res.end();
}).listen(9000); }).listen(9000);
</pre> ```
### Setup a stand-alone proxy server with latency (e.g. IO, etc) ### Setup a stand-alone proxy server with latency (e.g. IO, etc)
<pre> ``` js
var http = require('http'), var http = require('http'),
httpProxy = require('http-proxy'); httpProxy = require('http-proxy');
// //
// Create a proxy server with custom application logic // Create a proxy server with custom application logic
// //
httpProxy.createServer(function (req, res, proxy) { httpProxy.createServer(function (req, res, proxy) {
// //
// Buffer the request so that `data` and `end` events // Buffer the request so that `data` and `end` events
// are not lost during async operation(s). // are not lost during async operation(s).
...@@ -120,29 +120,29 @@ See the [examples][3] for more working sample code. ...@@ -120,29 +120,29 @@ See the [examples][3] for more working sample code.
buffer: buffer buffer: buffer
}); });
}, 2000); }, 2000);
}).listen(8000); }).listen(8000);
http.createServer(function (req, res) { http.createServer(function (req, res) {
res.writeHead(200, { 'Content-Type': 'text/plain' }); res.writeHead(200, { 'Content-Type': 'text/plain' });
res.write('request successfully proxied: ' + req.url +'\n' + JSON.stringify(req.headers, true, 2)); res.write('request successfully proxied: ' + req.url +'\n' + JSON.stringify(req.headers, true, 2));
res.end(); res.end();
}).listen(9000); }).listen(9000);
</pre> ```
### Proxy requests within another http server ### Proxy requests within another http server
<pre> ``` js
var http = require('http'), var http = require('http'),
httpProxy = require('http-proxy'); httpProxy = require('http-proxy');
// //
// Create a new instance of HttProxy to use in your server // Create a new instance of HttProxy to use in your server
// //
var proxy = new httpProxy.HttpProxy(); var proxy = new httpProxy.HttpProxy();
// //
// Create a regular http server and proxy its handler // Create a regular http server and proxy its handler
// //
http.createServer(function (req, res) { http.createServer(function (req, res) {
// //
// Put your custom server logic here, then proxy // Put your custom server logic here, then proxy
// //
...@@ -150,129 +150,129 @@ See the [examples][3] for more working sample code. ...@@ -150,129 +150,129 @@ See the [examples][3] for more working sample code.
host: 'localhost', host: 'localhost',
port: 9000 port: 9000
}); });
}).listen(8001); }).listen(8001);
http.createServer(function (req, res) { http.createServer(function (req, res) {
res.writeHead(200, { 'Content-Type': 'text/plain' }); res.writeHead(200, { 'Content-Type': 'text/plain' });
res.write('request successfully proxied: ' + req.url +'\n' + JSON.stringify(req.headers, true, 2)); res.write('request successfully proxied: ' + req.url +'\n' + JSON.stringify(req.headers, true, 2));
res.end(); res.end();
}).listen(9000); }).listen(9000);
</pre> ```
### Proxy requests using a ProxyTable ### Proxy requests using a ProxyTable
A 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: A 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:
<pre> ``` js
var options = { var options = {
router: { router: {
'foo.com/baz': '127.0.0.1:8001', 'foo.com/baz': '127.0.0.1:8001',
'foo.com/buz': '127.0.0.1:8002', 'foo.com/buz': '127.0.0.1:8002',
'bar.com/buz': '127.0.0.1:8003' 'bar.com/buz': '127.0.0.1:8003'
} }
}; };
</pre> ```
The 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: The 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:
<pre> ``` js
var proxyServer = httpProxy.createServer(options); var proxyServer = httpProxy.createServer(options);
proxyServer.listen(80); proxyServer.listen(80);
</pre> ```
### Proxy requests using a 'Hostname Only' ProxyTable ### Proxy requests using a 'Hostname Only' ProxyTable
As 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: As 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:
<pre> ``` js
var options = { var options = {
hostnameOnly: true, hostnameOnly: true,
router: { router: {
'foo.com': '127.0.0.1:8001', 'foo.com': '127.0.0.1:8001',
'bar.com': '127.0.0.1:8002' 'bar.com': '127.0.0.1:8002'
} }
} }
</pre> ```
Notice 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]. Notice 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].
### Proxy requests with an additional forward proxy ### Proxy requests with an additional forward proxy
Sometimes 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: Sometimes 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:
<pre> ``` js
var proxyServerWithForwarding = httpProxy.createServer(9000, 'localhost', { var proxyServerWithForwarding = httpProxy.createServer(9000, 'localhost', {
forward: { forward: {
port: 9000, port: 9000,
host: 'staging.com' host: 'staging.com'
} }
}); });
proxyServerWithForwarding.listen(80); proxyServerWithForwarding.listen(80);
</pre> ```
The 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'. The 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'.
### Using node-http-proxy from the command line ### Using node-http-proxy from the command line
When 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: When 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:
<pre> ``` js
usage: node-http-proxy [options] usage: node-http-proxy [options]
All options should be set with the syntax --option=value All options should be set with the syntax --option=value
options: options:
--port PORT Port that the proxy server should run on --port PORT Port that the proxy server should run on
--target HOST:PORT Location of the server the proxy will target --target HOST:PORT Location of the server the proxy will target
--config OUTFILE Location of the configuration file for the proxy server --config OUTFILE Location of the configuration file for the proxy server
--silent Silence the log output from the proxy server --silent Silence the log output from the proxy server
-h, --help You're staring at it -h, --help You're staring at it
</pre> ```
### Proxying over HTTPS ### Proxying over HTTPS
You 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. You 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.
<pre> ``` js
var fs = require('fs'), var fs = require('fs'),
https = require('https'), https = require('https'),
httpProxy = require('http-proxy'); httpProxy = require('http-proxy');
var options = { var options = {
https: { https: {
key: fs.readFileSync('path/to/your/key.pem', 'utf8'), key: fs.readFileSync('path/to/your/key.pem', 'utf8'),
cert: fs.readFileSync('path/to/your/cert.pem', 'utf8') cert: fs.readFileSync('path/to/your/cert.pem', 'utf8')
} }
}; };
// //
// Create a standalone HTTPS proxy server // Create a standalone HTTPS proxy server
// //
httpProxy.createServer(8000, 'localhost', options).listen(8001); httpProxy.createServer(8000, 'localhost', options).listen(8001);
// //
// Create an instance of HttpProxy to use with another HTTPS server // Create an instance of HttpProxy to use with another HTTPS server
// //
var proxy = new httpProxy.HttpProxy({ https: true }); var proxy = new httpProxy.HttpProxy({ https: true });
https.createServer(options.https, function (req, res) { https.createServer(options.https, function (req, res) {
proxy.proxyRequest(req, res, { proxy.proxyRequest(req, res, {
host: 'localhost', host: 'localhost',
port: 8000 port: 8000
}) })
}).listen(8002); }).listen(8002);
// //
// Create the target HTTPS server for both cases // Create the target HTTPS server for both cases
// //
https.createServer(options.https, function (req, res) { https.createServer(options.https, function (req, res) {
res.writeHead(200, { 'Content-Type': 'text/plain' }); res.writeHead(200, { 'Content-Type': 'text/plain' });
res.write('hello https\n'); res.write('hello https\n');
res.end(); res.end();
}).listen(8000); }).listen(8000);
</pre> ```
### Proxying WebSockets ### Proxying WebSockets
Websockets are handled automatically when using the `httpProxy.createServer()`, but if you want to use it in conjunction with a stand-alone HTTP + WebSocket (such as [socket.io][5]) server here's how: Websockets are handled automatically when using the `httpProxy.createServer()`, but if you want to use it in conjunction with a stand-alone HTTP + WebSocket (such as [socket.io][5]) server here's how:
<pre> ``` js
var http = require('http'), var http = require('http'),
httpProxy = require('http-proxy'); httpProxy = require('http-proxy');
// //
// Create an instance of node-http-proxy // Create an instance of node-http-proxy
// //
var proxy = new httpProxy.HttpProxy(); var proxy = new httpProxy.HttpProxy();
var server = http.createServer(function (req, res) { var server = http.createServer(function (req, res) {
// //
// Proxy normal HTTP requests // Proxy normal HTTP requests
// //
...@@ -280,9 +280,9 @@ Websockets are handled automatically when using the `httpProxy.createServer()`, ...@@ -280,9 +280,9 @@ Websockets are handled automatically when using the `httpProxy.createServer()`,
host: 'localhost', host: 'localhost',
port: 8000 port: 8000
}) })
}); });
server.on('upgrade', function(req, socket, head) { server.on('upgrade', function(req, socket, head) {
// //
// Proxy websocket requests too // Proxy websocket requests too
// //
...@@ -290,8 +290,8 @@ Websockets are handled automatically when using the `httpProxy.createServer()`, ...@@ -290,8 +290,8 @@ Websockets are handled automatically when using the `httpProxy.createServer()`,
host: 'localhost', host: 'localhost',
port: 8000 port: 8000
}); });
}); });
</pre> ```
<br/> <br/>
### Why doesn't node-http-proxy have more advanced features like x, y, or z? ### Why doesn't node-http-proxy have more advanced features like x, y, or z?
...@@ -299,10 +299,10 @@ Websockets are handled automatically when using the `httpProxy.createServer()`, ...@@ -299,10 +299,10 @@ Websockets are handled automatically when using the `httpProxy.createServer()`,
If 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. If 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.
## Run Tests ## Run Tests
<pre> ``` js
vows test/*-test.js --spec vows test/*-test.js --spec
vows test/*-test.js --spec --https vows test/*-test.js --spec --https
</pre> ```
<br/> <br/>
### License ### License
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7