route/doc/theory.md

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:

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.