routing.md

Routing

• Examples
• Route Config Options
• Route Override
• Change Origin

When Shunter receives an incoming request it needs to know where the request should be proxied to. This is configured by setting a routes property when you create your shunter app, typically by requiring a config file:

var app = shunter({
	routes: require('./config/routes.json'),
	...
});

Examples

The config is used to match the incoming hostname and request url and match it to a proxy target.

{
	"www.example.com": {
		"/^\\/blog/": {
			"host": "blog.example.com",
			"port": 80
		},
		"/^\\/demo/": {
			"host": "demo.example.com"
		},
		"/^\\/about/": {
			"host": "about.example.com",
			"port": 1337
		},
		"default": {
			"host": "cms.example.com",
			"port": 8080
		}
	},
	"test-www.example.com": {
		"/^\\/blog/": {
			"host": "test-blog.example.com",
			"port": 80
		},
		"default": {
			"host": "test-cms.example.com",
			"port": 8080
		}
	},
	"localhost": {
		"default": {
			"host": "127.0.0.1",
			"port": 5000
		}
	}
}

The table shows how different requests would be mapped using this config:

Host Header	Request Url	Proxy Destination
www.example.com	/blog/article123	blog.example.com:80/blog/article123
www.example.com	/demo/test	demo.example.com/demo/test
www.example.com	/about/contact.html	about.example.com:1337/about/contact.html
www.example.com	/foo	cms.example.com:8080/foo
test-www.example.com	/blog/article123	test-blog.example.com:80/blog/article123
test-www.example.com	/about/contact.html	test-cms.example.com:8080/about/contact.html
test-www.example.com	/foo	test-cms.example.com:8080/foo
foo.example.com	/foo/bar	127.0.0.1:5000/foo/bar

Route Config Options

By default if none of the regex patterns are matched Shunter will use the route under the default key. The name of the default key can be configured by providing the route-config option when you start your shunter app. So if you had the config:

{
	"www.example.com": {
		"custom": {
			"host": "127.0.0.1",
			"port": 1337
		},
		"default": {
			"host": "127.0.0.1",
			"port": 5000
		}
	}
}

And ran your Shunter app with --route-config=custom requests would be routed to port 1337 instead of 5000.

Route Override

Routing can be overridden entirely by setting the route-override option. Running your Shunter app with --route-override=http://www.example.com:1337 would route all requests to that destination. You could also route to an IPv4: --route-override=8.8.8.8:80

If you do not specify a protocol (http or https) when setting a route via route-override, then it will default to http. Please also note that https is currently unsupported by Shunter.

--route-override=$BACKEND_URL

BACKEND_URL	Proxy Destination
http://www.example.com	http://www.example.com
https://foo.example.com	https://foo.example.com
www.example.com	http://www.example.com
www.example.com:80	http://www.example.com:80
localhost	http://localhost
127.0.0.1:5000	http://127.0.0.1:5000
8.8.8.8	http://8.8.8.8
https://8.8.8.8:80	https://8.8.8.8:80

You can use the --origin-override (-g) option in conjunction with the route-override option to set changeOrigin: true for the overriding route. See Change Origin for more details.

This would be useful when deploying your Shunter app to a platform that makes use of environment variables. For example you could start up a Shunter app with:

node app -p $PORT --route-override=$BACKEND_APP --origin-override

Change Origin

In addition to setting the host and port for the proxy target there is an additional changeOrigin option that can be used. When this is set to true (it defaults to false) Shunter will update the host header to match the destination server. So with the following config:

{
	"www.example.com": {
		"default": {
			"host": "cms.example.com",
			"port": 8080,
			"changeOrigin": true
		}
	}
}

The application on cms.example.com would receive requests with a host header of cms.example.com instead of www.example.com. The original host header will be passed through to the backend in an X-Orig-Host header.