service

Documentation

Index

• Constants
• Variables
• func DefaultSkipper(_ http.ResponseWriter, _ *http.Request) bool
• func Proxy(balancer ProxyBalancer) func(http.Handler) http.Handler
• func ProxyWithConfig(config ProxyConfig) func(http.Handler) http.Handler
• type CommonBalancer
  • func (b *CommonBalancer) AddTarget(target *ProxyTarget) bool
  • func (b *CommonBalancer) RemoveTarget(name string) bool
• type LoadBalancer
• type PrefixBalancer
  • func (b *PrefixBalancer) IsEnabled() bool
  • func (b *PrefixBalancer) Next(w http.ResponseWriter, r *http.Request) *ProxyTarget
• type PrefixServers
• type ProxyBalancer
  • func NewRandomBalancer(targets []*ProxyTarget) ProxyBalancer
  • func NewRoundRobinBalancer(targets []*ProxyTarget) ProxyBalancer
• type ProxyConfig
• type ProxyTarget
• type Server
• type Service
  • func (m *Service) GetBalancer() (ProxyBalancer, error)
  • func (m *Service) Middleware() ([]func(http.Handler) http.Handler, error)
• type Skipper
• type TargetProvider

Constants

const StatusCodeContextCanceled = 499

StatusCodeContextCanceled is a custom HTTP status code for situations where a client unexpectedly closed the connection to the server. As there is no standard error code for "client closed connection", but various well-known HTTP clients and server implement this HTTP code we use 499 too instead of the more problematic 5xx, which does not allow to detect this situation

Variables

var (
	// DefaultProxyConfig is the default Proxy middleware config.
	DefaultProxyConfig = ProxyConfig{
		Skipper:    DefaultSkipper,
		ContextKey: "target",
	}
)

Functions

func DefaultSkipper

func DefaultSkipper(_ http.ResponseWriter, _ *http.Request) bool

func Proxy

func Proxy(balancer ProxyBalancer) func(http.Handler) http.Handler

Proxy returns a Proxy middleware.

Proxy middleware forwards the request to upstream server using a configured load balancing technique.

func ProxyWithConfig

func ProxyWithConfig(config ProxyConfig) func(http.Handler) http.Handler

ProxyWithConfig returns a Proxy middleware with config. See: `Proxy()`

Types

type CommonBalancer

type CommonBalancer struct {
	// contains filtered or unexported fields
}

func (*CommonBalancer) AddTarget

func (b *CommonBalancer) AddTarget(target *ProxyTarget) bool

AddTarget adds an upstream target to the list and returns `true`.

However, if a target with the same name already exists then the operation is aborted returning `false`.

func (*CommonBalancer) RemoveTarget

func (b *CommonBalancer) RemoveTarget(name string) bool

RemoveTarget removes an upstream target from the list by name.

Returns `true` on success, `false` if no target with the name is found.

type LoadBalancer

type LoadBalancer struct {
	Servers []Server `cfg:"servers"`
}

type PrefixBalancer

type PrefixBalancer struct {
	CommonBalancer

	Prefixes       []PrefixServers `cfg:"prefixes"`
	DefaultServers []Server        `cfg:"default_servers"`

	DefaultBalancer ProxyBalancer
}

func (*PrefixBalancer) IsEnabled

func (b *PrefixBalancer) IsEnabled() bool

func (*PrefixBalancer) Next

func (b *PrefixBalancer) Next(w http.ResponseWriter, r *http.Request) *ProxyTarget

type PrefixServers

type PrefixServers struct {
	Prefix  string   `cfg:"prefix"`
	Servers []Server `cfg:"servers"`

	Balancer ProxyBalancer
}

type ProxyBalancer

type ProxyBalancer interface {
	AddTarget(*ProxyTarget) bool
	RemoveTarget(string) bool
	Next(w http.ResponseWriter, r *http.Request) *ProxyTarget
}

ProxyBalancer defines an interface to implement a load balancing technique.

func NewRandomBalancer

func NewRandomBalancer(targets []*ProxyTarget) ProxyBalancer

NewRandomBalancer returns a random proxy balancer.

func NewRoundRobinBalancer

func NewRoundRobinBalancer(targets []*ProxyTarget) ProxyBalancer

NewRoundRobinBalancer returns a round-robin proxy balancer.

type ProxyConfig

type ProxyConfig struct {
	// Skipper defines a function to skip middleware.
	Skipper Skipper

	// Balancer defines a load balancing technique.
	// Required.
	Balancer ProxyBalancer

	// RetryCount defines the number of times a failed proxied request should be retried
	// using the next available ProxyTarget. Defaults to 0, meaning requests are never retried.
	RetryCount int

	// RetryFilter defines a function used to determine if a failed request to a
	// ProxyTarget should be retried. The RetryFilter will only be called when the number
	// of previous retries is less than RetryCount. If the function returns true, the
	// request will be retried. The provided error indicates the reason for the request
	// failure. When the ProxyTarget is unavailable, the error will be an instance of
	// echo.HTTPError with a Code of http.StatusBadGateway. In all other cases, the error
	// will indicate an internal error in the Proxy middleware. When a RetryFilter is not
	// specified, all requests that fail with http.StatusBadGateway will be retried. A custom
	// RetryFilter can be provided to only retry specific requests. Note that RetryFilter is
	// only called when the request to the target fails, or an internal error in the Proxy
	// middleware has occurred. Successful requests that return a non-200 response code cannot
	// be retried.
	RetryFilter func(w http.ResponseWriter, r *http.Request, e error) bool

	// ErrorHandler defines a function which can be used to return custom errors from
	// the Proxy middleware. ErrorHandler is only invoked when there has been
	// either an internal error in the Proxy middleware or the ProxyTarget is
	// unavailable. Due to the way requests are proxied, ErrorHandler is not invoked
	// when a ProxyTarget returns a non-200 response. In these cases, the response
	// is already written so errors cannot be modified. ErrorHandler is only
	// invoked after all retry attempts have been exhausted.
	ErrorHandler func(w http.ResponseWriter, r *http.Request, err error) error

	// Rewrite defines URL path rewrite rules. The values captured in asterisk can be
	// retrieved by index e.g. $1, $2 and so on.
	// Examples:
	// "/old":              "/new",
	// "/api/*":            "/$1",
	// "/js/*":             "/public/javascripts/$1",
	// "/users/*/orders/*": "/user/$1/order/$2",
	Rewrite map[string]string

	// RegexRewrite defines rewrite rules using regexp.Rexexp with captures
	// Every capture group in the values can be retrieved by index e.g. $1, $2 and so on.
	// Example:
	// "^/old/[0.9]+/":     "/new",
	// "^/api/.+?/(.*)":    "/v2/$1",
	RegexRewrite map[*regexp.Regexp]string

	// Context key to store selected ProxyTarget into context.
	// Optional. Default value "target".
	ContextKey string

	// To customize the transport to remote.
	// Examples: If custom TLS certificates are required.
	Transport http.RoundTripper

	// ModifyResponse defines function to modify response from ProxyTarget.
	ModifyResponse func(*http.Response) error
}

ProxyConfig defines the config for Proxy middleware.

type ProxyTarget

type ProxyTarget struct {
	Name string
	URL  *url.URL
	Meta map[string]interface{}
}

ProxyTarget defines the upstream target.

type Server

type Server struct {
	URL string `cfg:"url"`
}

type Service

type Service struct {
	InsecureSkipVerify bool `cfg:"insecure_skip_verify"`
	PassHostHeader     bool `cfg:"pass_host_header"`

	PrefixBalancer PrefixBalancer `cfg:"prefixbalancer"`
	LoadBalancer   LoadBalancer   `cfg:"loadbalancer"`
}

func (*Service) GetBalancer

func (m *Service) GetBalancer() (ProxyBalancer, error)

func (*Service) Middleware

func (m *Service) Middleware() ([]func(http.Handler) http.Handler, error)

type Skipper

type Skipper func(w http.ResponseWriter, r *http.Request) bool

Skipper defines a function to skip middleware. Returning true skips processing the middleware.

type TargetProvider

type TargetProvider interface {
	NextTarget(w http.ResponseWriter, r *http.Request) (*ProxyTarget, error)
}

TargetProvider defines an interface that gives the opportunity for balancer to return custom errors when selecting target.