# Theory of route

## Why does this project exist?

HTTP load balancing is harder than it needs to be. Existing projects assume
there is a direct line-of-fire from the load balancer to the underlying services.
This is NOT always true. Containerization has lead to a lot of hacks such as
overlay networks to offer this direct line-of-fire so that the load balancer
can make a direct TCP connection to the underlying services.

Route exists to invert this problem.

In most networks, it is true that it is a lot easier to guarantee the backends
have a direct line-of-fire to the load balancer, not the other way around.
Why not just make a connection to the load balancer and re-use it for HTTP
traffic?

Route allows you to simplify your network architecture by removing the
requirement that all backend services need a direct TCP line-of-fire to the
load balancer. Route allows you to host HTTP services behind NAT. Route
allows you to throw out overlay networks and return to a simpler cluster layout.

## How does route work?

Route has several basic nouns, they are:

- route
- backend
- balancer
- agent

They are inter-related like this:

```graphviz
digraph G {
    balancer -> agent
    agent -> balancer
    agent -> backend
    backend -> agent

    user -> balancer
    balancer -> user
}
```

### route

A route is a combination of HTTP domain and path (currently unsupported, so
assume `/`). An example route would be `cloudsdale.cf/`. This maps to the
location users get.

### backend

A backend is the underlying service being proxied to by route. An example backend
is Apache, Nginx or anything else that serves compliant HTTP/1.1 traffic.

### balancer

A balancer is an instance of `cmd/routed` running on some server somewhere.
Balancers accept both agent and HTTP connections, proxying requests from the HTTP
connections to agent connections and back.