Redbird Reverse Proxy
About this fork
This is a temporary fork of redbird until the original works with node 14.
With built-in Cluster, HTTP2, LetsEncrypt and Docker support
It should be easy and robust to handle dynamic virtual hosts, load balancing, proxying web sockets and SSL encryption.
With Redbird you get a complete library to build dynamic reverse proxies with the speed and robustness of http-proxy.
This light-weight package includes everything you need for easy reverse routing of your applications.
Great for routing many applications from different domains in one single host, handling SSL with ease, etc.
Developed by manast
SUPER HOT
Support for HTTP2. You can now enable HTTP2 just by setting the HTTP2 flag to true. Keep in mind that HTTP2 requires
SSL/TLS certificates. Thankfully we also support LetsEncrypt so this becomes easy as pie.
HOT
We have now support for automatic generation of SSL certificates using LetsEncrypt. Zero config setup for your
TLS protected services that just works.
Features
- Flexible and easy routing
- Websockets
- Seamless SSL Support (HTTPS -> HTTP proxy)
- Automatic HTTP to HTTPS redirects
- Automatic TLS Certificates generation and renewal
- Load balancer
- Register and unregister routes programmatically without restart (allows zero downtime deployments)
- Docker support for automatic registration of running containers
- Cluster support that enables automatic multi-process
- Based on top of rock-solid node-http-proxy and battle tested on production in many sites
- Optional logging based on bunyan
Install
npm install @artcodestudio/redbird
Example
You can programmatically register or unregister routes dynamically even if the proxy is already running:
const Redbird = require('@artcodestudio/redbird');
var proxy = new Redbird({port: 80});
var proxy = new Redbird({port: 80, xfwd: false});
proxy.register("optimalbits.com", "http://167.23.42.67:8000");
proxy.register("example.com", "http://172.17.42.1:8001");
proxy.register("example.com/static", "http://172.17.42.1:8002");
proxy.register("example.com/media", "http://172.17.42.1:8003");
proxy.register("abc.example.com", "http://172.17.42.4:8080");
proxy.register("abc.example.com/media", "http://172.17.42.5:8080");
proxy.register("foobar.example.com", "http://172.17.42.6:8080/foobar");
proxy.register("balance.me", "http://172.17.40.6:8080");
proxy.register("balance.me", "http://172.17.41.6:8080");
proxy.register("balance.me", "http://172.17.42.6:8080");
proxy.register("balance.me", "http://172.17.43.6:8080");
proxy.register("temporary.com", "http://172.17.45.1:8004");
proxy.unregister("temporary.com", "http://172.17.45.1:8004");
redbird.register('example.com', 'http://172.60.80.2:8082', {
ssl: {
letsencrypt: {
email: 'john@example.com',
production: true,
}
}
});
var proxy = new Redbird({
port: 80,
letsencrypt: {
path: __dirname + '/certs',
port: 9999
},
greenlock: {
packageRoot: __dirname,
},
ssl: {
http2: true,
port: 443,
}
});
About HTTPS
The HTTPS proxy supports virtual hosts by using SNI (which most modern browsers support: IE7 and above).
The proxying is performed by hostname, so you must use the same SSL certificates for a given hostname independently of its paths.
LetsEncrypt
Some important considerations when using LetsEncrypt. You need to agree to LetsEncrypt terms of service. When using
LetsEncrypt, the obtained certificates will be copied to disk to the specified path. Its your responsibility to backup, or save persistently when applicable. Keep in mind that
these certificates needs to be handled with care so that they cannot be accessed by malicious users. The certificates will be renewed every
2 months automatically forever.
HTTPS Example
(NOTE: This is a legacy example not needed when using LetsEncrypt)
Conceptually HTTPS is easy, but it is also easy to struggle getting it right. With Redbird its straightforward, check this complete example:
- Generate a localhost development SSL certificate:
/certs $ openssl genrsa -out dev-key.pem 1024
/certs $ openssl req -new -key dev-key.pem -out dev-csr.pem
// IMPORTANT: Do not forget to fill the field! Common Name (e.g. server FQDN or YOUR name) []:localhost
/certs $ openssl x509 -req -in dev-csr.pem -signkey dev-key.pem -out dev-cert.pem
Note: For production sites you need to buy valid SSL certificates from a trusted authority.
- Create a simple redbird based proxy:
var redbird = new Redbird({
port: 8080,
ssl: {
port: 8443,
key: "certs/dev-key.pem",
cert: "certs/dev-cert.pem",
}
});
redbird.register('localhost', 'http://localhost:8082', {ssl: true});
- Test it:
Point your browser to localhost:8000
and you will see how it automatically redirects to your https server and proxies you to
your target server.
You can define many virtual hosts, each with its own SSL certificate. And if you do not define any, they will use the default one
as in the example above:
redbird.register('example.com', 'http://172.60.80.2:8082', {
ssl: {
key: "../certs/example.key",
cert: "../certs/example.crt",
ca: "../certs/example.ca"
}
});
redbird.register('foobar.com', 'http://172.60.80.3:8082', {
ssl: {
key: "../certs/foobar.key",
cert: "../certs/foobar.crt",
}
});
You can also specify https hosts as targets and also specify if you want the connection to the target host to be secure (default is true).
var redbird = new Redbird({
port: 80,
secure: false,
ssl: {
port: 443,
key: "../certs/default.key",
cert: "../certs/default.crt",
}
});
redbird.register('tutorial.com', 'https://172.60.80.2:8083', {
ssl: {
key: "../certs/tutorial.key",
cert: "../certs/tutorial.crt",
}
});
Edge case scenario: you have an HTTPS server with two IP addresses assigned to it and your clients use old software without SNI support. In this case, both IP addresses will receive the same fallback certificate. I.e. some of the domains will get a wrong certificate. To handle this case you can create two HTTPS servers each one bound to its own IP address and serving the appropriate certificate.
var redbird = new Redbird({
port: 8080,
ssl: [
{
port: 443,
ip: '123.45.67.10',
key: 'certs/tutorial.key',
cert: 'certs/tutorial.crt',
},
{
port: 443,
ip: '123.45.67.11',
key: 'certs/my-other-domain.key',
cert: 'certs/my-other-domain.crt',
}
]
});
redbird.register('tutorial.com', 'http://192.168.0.10:8001', {
ssl: {
key: 'certs/tutorial.key',
cert: 'certs/tutorial.crt',
}
});
redbird.register('my-other-domain.com', 'http://192.168.0.12:8001', {
ssl: {
key: 'certs/my-other-domain.key',
cert: 'certs/my-other-domain.crt',
}
});
Docker support
If you use docker, you can tell Redbird to automatically register routes based on image
names. You register your image name and then every time a container starts from that image,
it gets registered, and unregistered if the container is stopped. If you run more than one
container from the same image, Redbird will load balance following a round-robin algorithm:
var redbird = new Redbird({
port: 8080,
});
var docker = Redbird.docker;
docker(redbird).register("old.api.com", 'company/api:v1.0.0');
docker(redbird).register("stable.api.com", 'company/api:v2.*');
docker(redbird).register("preview.api.com", 'company/api:v[3-9].*');
etcd backend
Redbird can use node-etcd to automatically create proxy records from an etcd cluster. Configuration
is accomplished by passing an array of options, plus the hosts and path variables,
which define which etcd cluster hosts, and which directory within those hosts, that Redbird should poll for updates.
var redbird = new Redbird({
port:8080
});
var options = {
hosts: ['localhost:2379'],
path: ['@artcodestudio/redbird'],
...
}
Redbird.etcd(redbird,options);
etcd records can be created in one of two ways, either as a target destination pair:
/redbird/example.com "8.8.8.8"
or by passing a JSON object containing multiple hosts, and Redbird options:
/redbird/derek.com { "hosts" : ["10.10.10.10", "11.11.11.11"]}
/redbird/johnathan.com { "ssl" : true }
/redbird/jeff.com { "docker" : "alpine/alpine:latest" }
Cluster support
Redbird supports automatic node cluster generation. To use, just specify the number
of processes that you want Redbird to use in the options object. Redbird will automatically
restart any thread that crashes, increasing reliability.
var redbird = new Redbird({
port: 8080,
cluster: 4
});
NTLM support
If you need NTLM support, you can tell Redbird to add the required header handler. This
registers a response handler which makes sure the NTLM auth header is properly split into
two entries from http-proxy.
var redbird = new Redbird({
port: 8080,
ntlm: true
});
Custom Resolvers
With custom resolvers, you can decide how the proxy server handles request. Custom resolvers allow you to extend Redbird considerably. With custom resolvers, you can perform the following:
- Do path-based routing.
- Do headers based routing.
- Do wildcard domain routing.
- Use variable upstream servers based on availability, for example in conjunction with Etcd or any other service discovery platform.
- And more.
Resolvers should be:
- Be invokable function. The
this
context of such function is the Redbird Proxy object. The resolver function takes in two parameters : host
and url
- Have a priority, resolvers with higher priorities are called before those of lower priorities. The default resolver, has a priority of 0.
- A resolver should return a route object or a string when matches it matches the parameters passed in. If string is returned, then it must be a valid upstream URL, if object, then the object must conform to the following:
{
url: string or array of string [required], when array, the urls will be load-balanced across.
path: path prefix for route, [optional], defaults to '/',
opts: {}
}
Defining Resolvers
Resolvers can be defined when initializing the proxy object with the resolvers
parameter. An example is below:
var customResolver1 = function(host, url, req) {
if(/^\/api\//.test(url)){
return 'http://127.0.0.1:8888';
}
};
customResolver1.priority = 100;
var proxy = new Redbird({
port: 8080,
resolvers: [
customResolver1,
function(host, url, req) {
if(/\.example\.com/.test(host)){
return 'http://127.0.0.1:9999'
}
}]
})
Adding and Removing Resolvers at Runtime
You can add or remove resolvers at runtime, this is useful in situations where your upstream is tied to a service discovery service system.
var topPriority = function(host, url, req) {
return /app\.example\.com/.test(host) ? {
url: [
'http://127.0.0.1:8000',
'http://128.0.1.1:9999'
]
} : null;
};
topPriority.priority = 200;
proxy.addResolver(topPriority);
setTimeout(function() {
proxy.removeResolver(topPriority);
}, 600000);
Replacing the default HTTP/HTTPS server modules
By passing serverModule: module
or ssl: {serverModule : module}
you can override the default http/https
servers used to listen for connections with another module.
One application for this is to enable support for PROXY protocol: This is useful if you want to use a module like
findhit-proxywrap to enable support for the
PROXY protocol.
PROXY protocol is used in tools like HA-Proxy, and can be optionally enabled in Amazon ELB load balancers to pass the
original client IP when proxying TCP connections (similar to an X-Forwarded-For header, but for raw TCP). This is useful
if you want to run redbird on AWS behind an ELB load balancer, but have redbird terminate any HTTPS connections so you
can have SNI/Let's Encrypt/HTTP2support. With this in place Redbird will see the client's IP address rather
than the load-balancer's, and pass this through in an X-Forwarded-For header.
proxy_opts = {strict: false};
proxyWrap = require('findhit-proxywrap');
var opts = {
port: process.env.HTTP_PORT,
serverModule: proxyWrap.proxy( require('http'), proxy_opts),
ssl: {
http2: true,
serverModule: proxyWrap.proxy(require('spdy').server, proxy_opts),
port: process.env.HTTPS_PORT,
}
}
var proxy = new Redbird(opts);
Roadmap
- Statistics (number of connections, load, response times, etc)
- CORS support.
- Rate limiter.
- Simple IP Filtering.
- Automatic routing via Redis.
Reference
constructor
register
unregister
notFound
close
Redbird(opts)
This is the Proxy constructor. Creates a new Proxy and starts listening to
the given port.
Arguments
opts {Object}
{
port: {Number}
ssl: {
port: {Number}
key: keyPath,
cert: certPath,
ca: caPath
redirectPort: port,
http2: false,
serverModule : require('https')
}
bunyan: {Object}
resolvers: {Function | Array}
serverModule : {Module}
}
Redbird::register(src, target, opts)
Register a new route. As soon as this method is called, the proxy will
start routing the sources to the given targets.
Arguments
src {String} {String|URL}
target {String|URL}
opts {Object}
{ssl : true}
{ssl: {
redirect: true,
key: keyPath,
cert: certPath,
ca: caPath,
secureOptions: constants.SSL_OP_NO_TLSv1
}
}
{onRequest: (req, res, target) => {
}}
Note: if you need to use ssl.secureOptions, to disable older, insecure TLS versions, import crypto/constants first:
const { constants } = require('crypto')
Redbird.unregister(src, [target])
Unregisters a route. After calling this method, the given route will not
be proxied anymore.
Arguments
src {String|URL} A string or a url parsed by node url module.
target {String|URL} A string or a url parsed by node url module. If not
specified, it will unregister all routes for the given source.
Redbird.notFound(callback)
Gives Redbird a callback function with two parameters, the HTTP request
and response objects, respectively, which will be called when a proxy route is
not found. The default is
function(req, res){
res.statusCode = 404;
res.write('Not Found');
res.end();
};
.
Arguments
src {Function(req, res)} The callback which will be called with the HTTP
request and response objects when a proxy route is not found.
Redbird.close()
Close the proxy stopping all the incoming connections.