frontend

Documentation

Overview

Package frontend provides a mechanism by which a single Go binary can distribute incoming connections to a set of backends or serve them directly.

Index

• Variables
• func MustCIDR(cidr string) *net.IPNet
• type Endpoint
  • func (b *Endpoint) ServeHTTP(w http.ResponseWriter, original *http.Request)
• type Frontend
  • func New() *Frontend
  • func (f *Frontend) Debug(h http.Handler) http.HandlerFunc
  • func (f *Frontend) HandleDebug()
  • func (f *Frontend) HandleEndpoint(b *Endpoint)
  • func (f *Frontend) ListBackends(w http.ResponseWriter, r *http.Request)
  • func (f *Frontend) ServeBackend(conn net.Conn, pingDelay time.Duration) error
  • func (f *Frontend) ServeBackends(l net.Listener, pingDelay time.Duration) error
• type RegisterBackend
• type ServeMux
• type Status

Variables

var LocalDebugIPs = []*net.IPNet{
	MustCIDR("127.0.0.0/8"),
	MustCIDR("::1/128"),
	MustCIDR("169.254.0.0/16"),
	MustCIDR("fe80::/10"),
	MustCIDR("fc00::/7"),
	MustCIDR("10.0.0.0/8"),
	MustCIDR("172.16.0.0/12"),
	MustCIDR("192.168.0.0/16"),
}

LocalDebugIPs contains the standard "private" IPv4 and IPv6 networks. It can be used with Frontend.DebugIPs.

var Sleepish = func(dur time.Duration) {
	const StdDev = 0.15
	const Min, Max = 0.5, 1.5

	fuzz := 1 + rand.NormFloat64()*StdDev
	if fuzz > Max {
		fuzz = Max
	} else if fuzz < Min {
		fuzz = Min
	}

	sleep(time.Duration(float64(dur) * fuzz))
}

Sleepish sleeps for approximately the given duration. It will sleep somewhere (pseudo-randomly, normally distributed) +/- 50% of the given sleep time.

It is a variable to facilitate instant testing; it shoulg not generally need to be swapped out.

Functions

func MustCIDR

func MustCIDR(cidr string) *net.IPNet

MustCIDR is a helper function for parsing networks. See net.ParseCIDR for the format of the netmask.

Unlike http.ParseCIDR, this does not return the IP address itself.

This function is for use with constructing Frontend.DebugIPs with constant strings.

Types

type Endpoint

type Endpoint struct {
	// Basic backend configuration
	Name string // name of this backend (shown in __backends)
	Root string

	// Additional limits
	AllowHeader   map[string]bool
	StripHeader   map[string]bool
	BodySizeLimit int64

	// Transport for making requests.  HandleEndpoint will set
	// this to http.DefaultTransport if it is nil.
	http.RoundTripper
	// contains filtered or unexported fields
}

An Endpoint handles routing requests to a backend. The zero values of all unexported fields and of all map fields are safe to use. No unexported fields may be modified after the Endpoint begins to serve traffic.

The following are used to construct the backend request:

Method              - Unmodified
URL.Path            - Unmodified
URL.RawQuery        - Unmodified
Header              - Subject to whitelisting
Body                - Subject to size limits
ContentLength       - Subject to size limits

The request contains the following standard headers:

Host                - Set to the Host from the client
X-Forwarded-For     - Set to the source IP of the client
X-Forwarded-Proto   - Set to "http" or "https"

The request also contains the following nonstandard headers:

X-Gofr-Backend      - Set to the name of the bakend
X-Gofr-Backend-Root - Set to the backend's root path

The response will have the following additional headers:

X-Frame-Options     - Set to "sameorigin"
X-XSS-Protection    - Set to "1; mode=block"

The following headers are passed through by default:

Accept, Accept-Language, Content-Type
Authorization, Referer, User-Agent, Cookie
ETag, Etag, Cache-Control, If-Modified-Since
If-Unmodified-Since, If-Match, If-None-Match

A number of standard headers are stripped by default:

Accept-Charset, Accept-Encoding, Accept-Datetime
Content-MD5, Via, Connection

Any other headers will log a warning before being discarded.

func (*Endpoint) ServeHTTP

func (b *Endpoint) ServeHTTP(w http.ResponseWriter, original *http.Request)

ServeHTTP proxies the request to the backend.

type Frontend

type Frontend struct {
	// Frontend configuration
	DebugIPs []*net.IPNet // IP networks allowed to access the debug handlers

	// Requests are handled by this ServeMux
	ServeMux
	// contains filtered or unexported fields
}

A Frontend manages backends and other handlers for this frontend. The zero value of all unexported fields are already for use.

func New

func New() *Frontend

New returns a frontend with a standard http.ServeMux and no DebugIPs.

func (*Frontend) Debug

func (f *Frontend) Debug(h http.Handler) http.HandlerFunc

Debug serves 404 except for source IPs in the DebugIPs set.

func (*Frontend) HandleDebug

func (f *Frontend) HandleDebug()

HandleDebug registers the following handlers:

/__backends   - backend information (ListBackends)

func (*Frontend) HandleEndpoint

func (f *Frontend) HandleEndpoint(b *Endpoint)

HandleEndpoint registers the given endpoint at its specified Root.

func (*Frontend) ListBackends

func (f *Frontend) ListBackends(w http.ResponseWriter, r *http.Request)

ListBackends serves a simple backend status list.

func (*Frontend) ServeBackend

func (f *Frontend) ServeBackend(conn net.Conn, pingDelay time.Duration) error

ServeBackend handles the given backend connection.

func (*Frontend) ServeBackends

func (f *Frontend) ServeBackends(l net.Listener, pingDelay time.Duration) error

ServeBackends serves backend handling connections accepted from the given Listener. This function should be run in its own goroutine.

type RegisterBackend

type RegisterBackend struct {
	Name string // name of endpoint to join
	Host string // source IP assumed if empty
	Port int    // port number (required)
}

RegisterBackend is sent by backend upon connection. The backend is assumed to be served from the source port of the incoming connection.

type ServeMux

type ServeMux interface {
	http.Handler
	Handle(pattern string, handler http.Handler)
	HandleFunc(pattern string, fn func(http.ResponseWriter, *http.Request))
}

A ServeMux allows handlers to be registered and can distribute requests to them.

This package has been designed in particular to work with the ServeMux provided by "net/http" and "kylelemons.net/go/gofr/trie".

type Status

type Status struct {
	Nonce int64 // must match response
}

Status is sent from the frontend to the backend with a Nonce, after which the Status is sent back to the frontend with the same Nonce and an up-to-date Status.