proxy

README

gogo-proxy

A fast and robust http/websocket reverse proxy library written in Go

Features

• Simple:
  • Implements http.Handler interface
  • Easy to write Balancers for custom routing logic
  • Built-in balancing patterns (Roundrobin, Random, etc ...)
• Robust: Retry requests on failure
• Flexible:
  • Custom error handling (so you can draw custom error pages etc ...) (use ErrorHandler)
  • Custom request rewriting (use Rewriter)
  • Your Balancer lookups can use information from the request, hard coded rules or they can query databases such as redis, memcache, etcd, mysql, ...
• Fast & "scalable":
  • Written in go, so concurrent by default and fast
  • Easy to deploy (proxies can be compiled as single binaries)

Example

package main

import (
    "github.com/AaronO/gogo-proxy"
    "net/http"
)

func main() {
    p, _ := proxy.New(proxy.ProxyOptions{
        Balancer: func(req *http.Request) (string, error) {
            return "https://www.google.com", nil
        },
    })

    http.ListenAndServe(":8080", p)
}

Acknowledgements

• websocketproxy is written by @fatih
• Inspired by loadfire (disclaimer: I wrote this too)

Documentation

Index

• func DefaultRewriter(req *http.Request, url *url.URL)
• func Random(hosts ...string) func(*http.Request) (string, error)
• func Roundrobin(hosts ...string) func(*http.Request) (string, error)
• type Proxy
  • func New(opts ProxyOptions) (*Proxy, error)
  • func (p *Proxy) ServeHTTP(rw http.ResponseWriter, req *http.Request)
• type ProxyOptions

Functions

func DefaultRewriter

func DefaultRewriter(req *http.Request, url *url.URL)

DefaultRewriter adjust the *http.Request object it's attributes match those of the destionation url (scheme, host, path, ...)

func Random

func Random(hosts ...string) func(*http.Request) (string, error)

Random generates a balancer than randomly picks one of provided hosts (this does not guarantee equal traffic distribution) but with many requests should get close to it

func Roundrobin

func Roundrobin(hosts ...string) func(*http.Request) (string, error)

Roundrobin generates a balancer that cycles through the list of hosts in a round robin fashion (equally distributing traffic)

Types

type Proxy

type Proxy struct {
	*ProxyOptions
	// contains filtered or unexported fields
}

func New

func New(opts ProxyOptions) (*Proxy, error)

New returns a new Proxy instance based on the provided ProxyOptions either 'Backend' (static) or 'Balancer' must be provided

func (*Proxy) ServeHTTP

func (p *Proxy) ServeHTTP(rw http.ResponseWriter, req *http.Request)

ServeHTTP allows us to comply to the http.Handler interface

type ProxyOptions

type ProxyOptions struct {
	// Number of times a request should be tried
	Retries int

	// Period to wait between retries
	Period time.Duration

	// Returns a url that we should proxy to for a given request
	Balancer func(req *http.Request) (string, error)

	// A static backend to route to
	Backend string

	// Rewriter is a function modifying the request before it's proxied
	// usually it should change the hostname of the request object, etc ...
	Rewriter func(req *http.Request, destUrl *url.URL)

	// Allows to customize how errors are written to responses
	ErrorHandler func(rw http.ResponseWriter, req *http.Request, err error)
}