Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type ActiveHealthChecks

type ActiveHealthChecks struct {
	// The URI path to use for health checks.
	Path string `json:"path,omitempty"`

	// The port to use (if different from the upstream's dial
	// address) for health checks.
	Port int `json:"port,omitempty"`

	// HTTP headers to set on health check requests.
	Headers http.Header `json:"headers,omitempty"`

	// How frequently to perform active health checks (default 30s).
	Interval caddy.Duration `json:"interval,omitempty"`

	// How long to wait for a response from a backend before
	// considering it unhealthy (default 5s).
	Timeout caddy.Duration `json:"timeout,omitempty"`

	// The maximum response body to download from the backend
	// during a health check.
	MaxSize int64 `json:"max_size,omitempty"`

	// The HTTP status code to expect from a healthy backend.
	ExpectStatus int `json:"expect_status,omitempty"`

	// A regular expression against which to match the response
	// body of a healthy backend.
	ExpectBody string `json:"expect_body,omitempty"`
	// contains filtered or unexported fields
}

ActiveHealthChecks holds configuration related to active health checks (that is, health checks which occur in a background goroutine independently).

type CircuitBreaker

type CircuitBreaker interface {
	OK() bool
	RecordMetric(statusCode int, latency time.Duration)
}

CircuitBreaker is a type that can act as an early-warning system for the health checker when backends are getting overloaded. This interface is still experimental and is subject to change.

type DialError

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

DialError is an error that specifically occurs in a call to Dial or DialContext.

type DialInfo

type DialInfo struct {
	// Upstream is the Upstream associated with
	// this DialInfo. It may be nil.
	Upstream *Upstream

	// The network to use. This should be one of
	// the values that is accepted by net.Dial:
	// https://golang.org/pkg/net/#Dial
	Network string

	// The address to dial. Follows the same
	// semantics and rules as net.Dial.
	Address string

	// Host and Port are components of Address.
	Host, Port string
}

DialInfo contains information needed to dial a connection to an upstream host. This information may be different than that which is represented in a URL (for example, unix sockets don't have a host that can be represented in a URL, but they certainly have a network name and address).

func GetDialInfo

func GetDialInfo(ctx context.Context) (DialInfo, bool)

GetDialInfo gets the upstream dialing info out of the context, and returns true if there was a valid value; false otherwise.

func (DialInfo) String

func (di DialInfo) String() string

String returns the Caddy network address form by joining the network and address with a forward slash.

type FirstSelection

type FirstSelection struct{}

FirstSelection is a policy that selects the first available host.

func (FirstSelection) CaddyModule

func (FirstSelection) CaddyModule() caddy.ModuleInfo

CaddyModule returns the Caddy module information.

func (FirstSelection) Select

func (FirstSelection) Select(pool UpstreamPool, _ *http.Request) *Upstream

Select returns an available host, if any.

func (*FirstSelection) UnmarshalCaddyfile

func (r *FirstSelection) UnmarshalCaddyfile(d *caddyfile.Dispenser) error

UnmarshalCaddyfile sets up the module from Caddyfile tokens.

type HTTPTransport

type HTTPTransport struct {

	// Configures the DNS resolver used to resolve the IP address of upstream hostnames.
	Resolver *UpstreamResolver `json:"resolver,omitempty"`

	// Configures TLS to the upstream. Setting this to an empty struct
	// is sufficient to enable TLS with reasonable defaults.
	TLS *TLSConfig `json:"tls,omitempty"`

	// Configures HTTP Keep-Alive (enabled by default). Should only be
	// necessary if rigorous testing has shown that tuning this helps
	// improve performance.
	KeepAlive *KeepAlive `json:"keep_alive,omitempty"`

	// Whether to enable compression to upstream. Default: true
	Compression *bool `json:"compression,omitempty"`

	// Maximum number of connections per host. Default: 0 (no limit)
	MaxConnsPerHost int `json:"max_conns_per_host,omitempty"`

	// How long to wait before timing out trying to connect to
	// an upstream.
	DialTimeout caddy.Duration `json:"dial_timeout,omitempty"`

	// How long to wait before spawning an RFC 6555 Fast Fallback
	// connection. A negative value disables this.
	FallbackDelay caddy.Duration `json:"dial_fallback_delay,omitempty"`

	// How long to wait for reading response headers from server.
	ResponseHeaderTimeout caddy.Duration `json:"response_header_timeout,omitempty"`

	// The length of time to wait for a server's first response
	// headers after fully writing the request headers if the
	// request has a header "Expect: 100-continue".
	ExpectContinueTimeout caddy.Duration `json:"expect_continue_timeout,omitempty"`

	// The maximum bytes to read from response headers.
	MaxResponseHeaderSize int64 `json:"max_response_header_size,omitempty"`

	// The size of the write buffer in bytes.
	WriteBufferSize int `json:"write_buffer_size,omitempty"`

	// The size of the read buffer in bytes.
	ReadBufferSize int `json:"read_buffer_size,omitempty"`

	// The versions of HTTP to support. As a special case, "h2c"
	// can be specified to use H2C (HTTP/2 over Cleartext) to the
	// upstream (this feature is experimental and subject to
	// change or removal). Default: ["1.1", "2"]
	Versions []string `json:"versions,omitempty"`

	// The pre-configured underlying HTTP transport.
	Transport *http.Transport `json:"-"`
	// contains filtered or unexported fields
}

HTTPTransport is essentially a configuration wrapper for http.Transport. It defines a JSON structure useful when configuring the HTTP transport for Caddy's reverse proxy. It builds its http.Transport at Provision.

func (HTTPTransport) CaddyModule

func (HTTPTransport) CaddyModule() caddy.ModuleInfo

CaddyModule returns the Caddy module information.

func (HTTPTransport) Cleanup

func (h HTTPTransport) Cleanup() error

Cleanup implements caddy.CleanerUpper and closes any idle connections.

func (*HTTPTransport) EnableTLS

func (h *HTTPTransport) EnableTLS(base *TLSConfig) error

EnableTLS enables TLS on the transport.

func (*HTTPTransport) NewTransport

func (h *HTTPTransport) NewTransport(ctx caddy.Context) (*http.Transport, error)

NewTransport builds a standard-lib-compatible http.Transport value from h.

func (*HTTPTransport) Provision

func (h *HTTPTransport) Provision(ctx caddy.Context) error

Provision sets up h.Transport with a *http.Transport that is ready to use.

func (*HTTPTransport) RoundTrip

func (h *HTTPTransport) RoundTrip(req *http.Request) (*http.Response, error)

RoundTrip implements http.RoundTripper.

func (*HTTPTransport) SetScheme

func (h *HTTPTransport) SetScheme(req *http.Request)

SetScheme ensures that the outbound request req has the scheme set in its URL; the underlying http.Transport requires a scheme to be set.

func (HTTPTransport) TLSEnabled

func (h HTTPTransport) TLSEnabled() bool

TLSEnabled returns true if TLS is enabled.

func (*HTTPTransport) UnmarshalCaddyfile

func (h *HTTPTransport) UnmarshalCaddyfile(d *caddyfile.Dispenser) error

UnmarshalCaddyfile deserializes Caddyfile tokens into h.

transport http {
    read_buffer  <size>
    write_buffer <size>
    dial_timeout <duration>
    tls_client_auth <cert_file> <key_file>
    tls_insecure_skip_verify
    tls_timeout <duration>
    tls_trusted_ca_certs <cert_files...>
    keepalive [off|<duration>]
    keepalive_idle_conns <max_count>
    versions <versions...>
}

type Handler

type Handler struct {
	// Configures the method of transport for the proxy. A transport
	// is what performs the actual "round trip" to the backend.
	// The default transport is plaintext HTTP.
	TransportRaw json.RawMessage `json:"transport,omitempty" caddy:"namespace=http.reverse_proxy.transport inline_key=protocol"`

	// A circuit breaker may be used to relieve pressure on a backend
	// that is beginning to exhibit symptoms of stress or latency.
	// By default, there is no circuit breaker.
	CBRaw json.RawMessage `json:"circuit_breaker,omitempty" caddy:"namespace=http.reverse_proxy.circuit_breakers inline_key=type"`

	// Load balancing distributes load/requests between backends.
	LoadBalancing *LoadBalancing `json:"load_balancing,omitempty"`

	// Health checks update the status of backends, whether they are
	// up or down. Down backends will not be proxied to.
	HealthChecks *HealthChecks `json:"health_checks,omitempty"`

	// Upstreams is the list of backends to proxy to.
	Upstreams UpstreamPool `json:"upstreams,omitempty"`

	// Adjusts how often to flush the response buffer. A
	// negative value disables response buffering.
	// TODO: figure out good defaults and write docs for this
	// (see https://github.com/caddyserver/caddy/issues/1460)
	FlushInterval caddy.Duration `json:"flush_interval,omitempty"`

	// Headers manipulates headers between Caddy and the backend.
	// By default, all headers are passed-thru without changes,
	// with the exceptions of special hop-by-hop headers.
	//
	// X-Forwarded-For and X-Forwarded-Proto are also set
	// implicitly, but this may change in the future if the official
	// standardized Forwarded header field gains more adoption.
	Headers *headers.Handler `json:"headers,omitempty"`

	// If true, the entire request body will be read and buffered
	// in memory before being proxied to the backend. This should
	// be avoided if at all possible for performance reasons.
	BufferRequests bool `json:"buffer_requests,omitempty"`

	// List of handlers and their associated matchers to evaluate
	// after successful roundtrips. The first handler that matches
	// the response from a backend will be invoked. The response
	// body from the backend will not be written to the client;
	// it is up to the handler to finish handling the response.
	// If passive health checks are enabled, any errors from the
	// handler chain will not affect the health status of the
	// backend.
	//
	// Two new placeholders are available in this handler chain:
	// - `{http.reverse_proxy.status_code}` The status code
	// - `{http.reverse_proxy.status_text}` The status text
	HandleResponse []caddyhttp.ResponseHandler `json:"handle_response,omitempty"`

	Transport http.RoundTripper `json:"-"`
	CB        CircuitBreaker    `json:"-"`
	// contains filtered or unexported fields
}

Handler implements a highly configurable and production-ready reverse proxy.

Upon proxying, this module sets the following placeholders (which can be used both within and after this handler):

Placeholder | Description ------------|------------- `{http.reverse_proxy.upstream.address}` | The full address to the upstream as given in the config `{http.reverse_proxy.upstream.hostport}` | The host:port of the upstream `{http.reverse_proxy.upstream.host}` | The host of the upstream `{http.reverse_proxy.upstream.port}` | The port of the upstream `{http.reverse_proxy.upstream.requests}` | The approximate current number of requests to the upstream `{http.reverse_proxy.upstream.max_requests}` | The maximum approximate number of requests allowed to the upstream `{http.reverse_proxy.upstream.fails}` | The number of recent failed requests to the upstream

func (Handler) CaddyModule

func (Handler) CaddyModule() caddy.ModuleInfo

CaddyModule returns the Caddy module information.

func (*Handler) Cleanup

func (h *Handler) Cleanup() error

Cleanup cleans up the resources made by h during provisioning.

func (*Handler) Provision

func (h *Handler) Provision(ctx caddy.Context) error

Provision ensures that h is set up properly before use.

func (*Handler) ServeHTTP

func (h *Handler) ServeHTTP(w http.ResponseWriter, r *http.Request, next caddyhttp.Handler) error

func (*Handler) UnmarshalCaddyfile

func (h *Handler) UnmarshalCaddyfile(d *caddyfile.Dispenser) error

UnmarshalCaddyfile sets up the handler from Caddyfile tokens. Syntax:

reverse_proxy [<matcher>] [<upstreams...>] {
    # upstreams
    to <upstreams...>

    # load balancing
    lb_policy <name> [<options...>]
    lb_try_duration <duration>
    lb_try_interval <interval>

    # active health checking
    health_path <path>
    health_port <port>
    health_interval <interval>
    health_timeout <duration>
    health_status <status>
    health_body <regexp>

    # passive health checking
    max_fails <num>
    fail_duration <duration>
    max_conns <num>
    unhealthy_status <status>
    unhealthy_latency <duration>

    # streaming
    flush_interval <duration>

    # header manipulation
    header_up   [+|-]<field> [<value|regexp> [<replacement>]]
    header_down [+|-]<field> [<value|regexp> [<replacement>]]

    # round trip
    transport <name> {
        ...
    }
}

Proxy upstream addresses should be network dial addresses such as `host:port`, or a URL such as `scheme://host:port`. Scheme and port may be inferred from other parts of the address/URL; if either are missing, defaults to HTTP.

type HeaderHashSelection

type HeaderHashSelection struct {
	// The HTTP header field whose value is to be hashed and used for upstream selection.
	Field string `json:"field,omitempty"`
}

HeaderHashSelection is a policy that selects a host based on a given request header.

func (HeaderHashSelection) CaddyModule

func (HeaderHashSelection) CaddyModule() caddy.ModuleInfo

CaddyModule returns the Caddy module information.

func (HeaderHashSelection) Select

func (s HeaderHashSelection) Select(pool UpstreamPool, req *http.Request) *Upstream

Select returns an available host, if any.

func (*HeaderHashSelection) UnmarshalCaddyfile

func (s *HeaderHashSelection) UnmarshalCaddyfile(d *caddyfile.Dispenser) error

UnmarshalCaddyfile sets up the module from Caddyfile tokens.

type HealthChecks

type HealthChecks struct {
	// Active health checks run in the background on a timer. To
	// minimally enable active health checks, set either path or
	// port (or both).
	Active *ActiveHealthChecks `json:"active,omitempty"`

	// Passive health checks monitor proxied requests for errors or timeouts.
	// To minimally enable passive health checks, specify at least an empty
	// config object.
	Passive *PassiveHealthChecks `json:"passive,omitempty"`
}

HealthChecks configures active and passive health checks.

type Host

type Host interface {
	// NumRequests returns the number of requests
	// currently in process with the host.
	NumRequests() int

	// Fails returns the count of recent failures.
	Fails() int

	// Unhealthy returns true if the backend is unhealthy.
	Unhealthy() bool

	// CountRequest atomically counts the given number of
	// requests as currently in process with the host. The
	// count should not go below 0.
	CountRequest(int) error

	// CountFail atomically counts the given number of
	// failures with the host. The count should not go
	// below 0.
	CountFail(int) error

	// SetHealthy atomically marks the host as either
	// healthy (true) or unhealthy (false). If the given
	// status is the same, this should be a no-op and
	// return false. It returns true if the status was
	// changed; i.e. if it is now different from before.
	SetHealthy(bool) (bool, error)
}

Host represents a remote host which can be proxied to. Its methods must be safe for concurrent use.

type IPHashSelection

type IPHashSelection struct{}

IPHashSelection is a policy that selects a host based on hashing the remote IP of the request.

func (IPHashSelection) CaddyModule

func (IPHashSelection) CaddyModule() caddy.ModuleInfo

CaddyModule returns the Caddy module information.

func (IPHashSelection) Select

func (IPHashSelection) Select(pool UpstreamPool, req *http.Request) *Upstream

Select returns an available host, if any.

func (*IPHashSelection) UnmarshalCaddyfile

func (r *IPHashSelection) UnmarshalCaddyfile(d *caddyfile.Dispenser) error

UnmarshalCaddyfile sets up the module from Caddyfile tokens.

type KeepAlive

type KeepAlive struct {
	// Whether HTTP Keep-Alive is enabled. Default: true
	Enabled *bool `json:"enabled,omitempty"`

	// How often to probe for liveness.
	ProbeInterval caddy.Duration `json:"probe_interval,omitempty"`

	// Maximum number of idle connections.
	MaxIdleConns int `json:"max_idle_conns,omitempty"`

	// Maximum number of idle connections per upstream host.
	MaxIdleConnsPerHost int `json:"max_idle_conns_per_host,omitempty"`

	// How long connections should be kept alive when idle.
	IdleConnTimeout caddy.Duration `json:"idle_timeout,omitempty"`
}

KeepAlive holds configuration pertaining to HTTP Keep-Alive.

type LeastConnSelection

type LeastConnSelection struct{}

LeastConnSelection is a policy that selects the host with the least active requests. If multiple hosts have the same fewest number, one is chosen randomly. The term "conn" or "connection" is used in this policy name due to its similar meaning in other software, but our load balancer actually counts active requests rather than connections, since these days requests are multiplexed onto shared connections.

func (LeastConnSelection) CaddyModule

func (LeastConnSelection) CaddyModule() caddy.ModuleInfo

CaddyModule returns the Caddy module information.

func (LeastConnSelection) Select

func (LeastConnSelection) Select(pool UpstreamPool, _ *http.Request) *Upstream

Select selects the up host with the least number of connections in the pool. If more than one host has the same least number of connections, one of the hosts is chosen at random.

func (*LeastConnSelection) UnmarshalCaddyfile

func (r *LeastConnSelection) UnmarshalCaddyfile(d *caddyfile.Dispenser) error

UnmarshalCaddyfile sets up the module from Caddyfile tokens.

type LoadBalancing

type LoadBalancing struct {
	// A selection policy is how to choose an available backend.
	// The default policy is random selection.
	SelectionPolicyRaw json.RawMessage `json:"selection_policy,omitempty" caddy:"namespace=http.reverse_proxy.selection_policies inline_key=policy"`

	// How long to try selecting available backends for each request
	// if the next available host is down. By default, this retry is
	// disabled. Clients will wait for up to this long while the load
	// balancer tries to find an available upstream host.
	TryDuration caddy.Duration `json:"try_duration,omitempty"`

	// How long to wait between selecting the next host from the pool. Default
	// is 250ms. Only relevant when a request to an upstream host fails. Be
	// aware that setting this to 0 with a non-zero try_duration can cause the
	// CPU to spin if all backends are down and latency is very low.
	TryInterval caddy.Duration `json:"try_interval,omitempty"`

	// A list of matcher sets that restricts with which requests retries are
	// allowed. A request must match any of the given matcher sets in order
	// to be retried if the connection to the upstream succeeded but the
	// subsequent round-trip failed. If the connection to the upstream failed,
	// a retry is always allowed. If unspecified, only GET requests will be
	// allowed to be retried. Note that a retry is done with the next available
	// host according to the load balancing policy.
	RetryMatchRaw caddyhttp.RawMatcherSets `json:"retry_match,omitempty" caddy:"namespace=http.matchers"`

	SelectionPolicy Selector              `json:"-"`
	RetryMatch      caddyhttp.MatcherSets `json:"-"`
}

LoadBalancing has parameters related to load balancing.

type PassiveHealthChecks

type PassiveHealthChecks struct {
	// How long to remember a failed request to a backend. A duration > 0
	// enables passive health checking. Default is 0.
	FailDuration caddy.Duration `json:"fail_duration,omitempty"`

	// The number of failed requests within the FailDuration window to
	// consider a backend as "down". Must be >= 1; default is 1. Requires
	// that FailDuration be > 0.
	MaxFails int `json:"max_fails,omitempty"`

	// Limits the number of simultaneous requests to a backend by
	// marking the backend as "down" if it has this many concurrent
	// requests or more.
	UnhealthyRequestCount int `json:"unhealthy_request_count,omitempty"`

	// Count the request as failed if the response comes back with
	// one of these status codes.
	UnhealthyStatus []int `json:"unhealthy_status,omitempty"`

	// Count the request as failed if the response takes at least this
	// long to receive.
	UnhealthyLatency caddy.Duration `json:"unhealthy_latency,omitempty"`
	// contains filtered or unexported fields
}

PassiveHealthChecks holds configuration related to passive health checks (that is, health checks which occur during the normal flow of request proxying).

type RandomChoiceSelection

type RandomChoiceSelection struct {
	// The size of the sub-pool created from the larger upstream pool. The default value
	// is 2 and the maximum at selection time is the size of the upstream pool.
	Choose int `json:"choose,omitempty"`
}

RandomChoiceSelection is a policy that selects two or more available hosts at random, then chooses the one with the least load.

func (RandomChoiceSelection) CaddyModule

func (RandomChoiceSelection) CaddyModule() caddy.ModuleInfo

CaddyModule returns the Caddy module information.

func (*RandomChoiceSelection) Provision

func (r *RandomChoiceSelection) Provision(ctx caddy.Context) error

Provision sets up r.

func (RandomChoiceSelection) Select

func (r RandomChoiceSelection) Select(pool UpstreamPool, _ *http.Request) *Upstream

Select returns an available host, if any.

func (*RandomChoiceSelection) UnmarshalCaddyfile

func (r *RandomChoiceSelection) UnmarshalCaddyfile(d *caddyfile.Dispenser) error

UnmarshalCaddyfile sets up the module from Caddyfile tokens.

func (RandomChoiceSelection) Validate

func (r RandomChoiceSelection) Validate() error

Validate ensures that r's configuration is valid.

type RandomSelection

type RandomSelection struct{}

RandomSelection is a policy that selects an available host at random.

func (RandomSelection) CaddyModule

func (RandomSelection) CaddyModule() caddy.ModuleInfo

CaddyModule returns the Caddy module information.

func (RandomSelection) Select

func (r RandomSelection) Select(pool UpstreamPool, request *http.Request) *Upstream

Select returns an available host, if any.

func (*RandomSelection) UnmarshalCaddyfile

func (r *RandomSelection) UnmarshalCaddyfile(d *caddyfile.Dispenser) error

UnmarshalCaddyfile sets up the module from Caddyfile tokens.

type RoundRobinSelection

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

RoundRobinSelection is a policy that selects a host based on round-robin ordering.

func (RoundRobinSelection) CaddyModule

func (RoundRobinSelection) CaddyModule() caddy.ModuleInfo

CaddyModule returns the Caddy module information.

func (*RoundRobinSelection) Select

func (r *RoundRobinSelection) Select(pool UpstreamPool, _ *http.Request) *Upstream

Select returns an available host, if any.

func (*RoundRobinSelection) UnmarshalCaddyfile

func (r *RoundRobinSelection) UnmarshalCaddyfile(d *caddyfile.Dispenser) error

UnmarshalCaddyfile sets up the module from Caddyfile tokens.

type Selector

type Selector interface {
	Select(UpstreamPool, *http.Request) *Upstream
}

Selector selects an available upstream from the pool.

type TLSConfig

type TLSConfig struct {
	// Optional list of base64-encoded DER-encoded CA certificates to trust.
	RootCAPool []string `json:"root_ca_pool,omitempty"`

	// List of PEM-encoded CA certificate files to add to the same trust
	// store as RootCAPool (or root_ca_pool in the JSON).
	RootCAPEMFiles []string `json:"root_ca_pem_files,omitempty"`

	// PEM-encoded client certificate filename to present to servers.
	ClientCertificateFile string `json:"client_certificate_file,omitempty"`

	// PEM-encoded key to use with the client certificate.
	ClientCertificateKeyFile string `json:"client_certificate_key_file,omitempty"`

	// If specified, Caddy will use and automate a client certificate
	// with this subject name.
	ClientCertificateAutomate string `json:"client_certificate_automate,omitempty"`

	// If true, TLS verification of server certificates will be disabled.
	// This is insecure and may be removed in the future. Do not use this
	// option except in testing or local development environments.
	InsecureSkipVerify bool `json:"insecure_skip_verify,omitempty"`

	// The duration to allow a TLS handshake to a server.
	HandshakeTimeout caddy.Duration `json:"handshake_timeout,omitempty"`

	// The server name (SNI) to use in TLS handshakes.
	ServerName string `json:"server_name,omitempty"`
}

TLSConfig holds configuration related to the TLS configuration for the transport/client.

func (TLSConfig) MakeTLSClientConfig

func (t TLSConfig) MakeTLSClientConfig(ctx caddy.Context) (*tls.Config, error)

MakeTLSClientConfig returns a tls.Config usable by a client to a backend. If there is no custom TLS configuration, a nil config may be returned.

type TLSTransport

type TLSTransport interface {
	// TLSEnabled returns true if the transport
	// has TLS enabled, false otherwise.
	TLSEnabled() bool

	// EnableTLS enables TLS within the transport
	// if it is not already, using the provided
	// value as a basis for the TLS config.
	EnableTLS(base *TLSConfig) error
}

TLSTransport is implemented by transports that are capable of using TLS.

type URIHashSelection

type URIHashSelection struct{}

URIHashSelection is a policy that selects a host by hashing the request URI.

func (URIHashSelection) CaddyModule

func (URIHashSelection) CaddyModule() caddy.ModuleInfo

CaddyModule returns the Caddy module information.

func (URIHashSelection) Select

func (URIHashSelection) Select(pool UpstreamPool, req *http.Request) *Upstream

Select returns an available host, if any.

func (*URIHashSelection) UnmarshalCaddyfile

func (r *URIHashSelection) UnmarshalCaddyfile(d *caddyfile.Dispenser) error

UnmarshalCaddyfile sets up the module from Caddyfile tokens.

type Upstream

type Upstream struct {
	Host `json:"-"`

	// The [network address](/docs/conventions#network-addresses)
	// to dial to connect to the upstream. Must represent precisely
	// one socket (i.e. no port ranges). A valid network address
	// either has a host and port or is a unix socket address.
	//
	// Placeholders may be used to make the upstream dynamic, but be
	// aware of the health check implications of this: a single
	// upstream that represents numerous (perhaps arbitrary) backends
	// can be considered down if one or enough of the arbitrary
	// backends is down. Also be aware of open proxy vulnerabilities.
	Dial string `json:"dial,omitempty"`

	// If DNS SRV records are used for service discovery with this
	// upstream, specify the DNS name for which to look up SRV
	// records here, instead of specifying a dial address.
	LookupSRV string `json:"lookup_srv,omitempty"`

	// The maximum number of simultaneous requests to allow to
	// this upstream. If set, overrides the global passive health
	// check UnhealthyRequestCount value.
	MaxRequests int `json:"max_requests,omitempty"`
	// contains filtered or unexported fields
}

Upstream bridges this proxy's configuration to the state of the backend host it is correlated with.

func (*Upstream) Available

func (u *Upstream) Available() bool

Available returns true if the remote host is available to receive requests. This is the method that should be used by selection policies, etc. to determine if a backend should be able to be sent a request.

func (*Upstream) Full

func (u *Upstream) Full() bool

Full returns true if the remote host cannot receive more requests at this time.

func (*Upstream) Healthy

func (u *Upstream) Healthy() bool

Healthy returns true if the remote host is currently known to be healthy or "up". It consults the circuit breaker, if any.

func (Upstream) String

func (u Upstream) String() string

type UpstreamPool

type UpstreamPool []*Upstream

UpstreamPool is a collection of upstreams.

type UpstreamResolver

type UpstreamResolver struct {
	// The addresses of DNS resolvers to use when looking up the addresses of proxy upstreams.
	// It accepts [network addresses](/docs/conventions#network-addresses)
	// with port range of only 1. If the host is an IP address, it will be dialed directly to resolve the upstream server.
	// If the host is not an IP address, the addresses are resolved using the [name resolution convention](https://golang.org/pkg/net/#hdr-Name_Resolution) of the Go standard library.
	// If the array contains more than 1 resolver address, one is chosen at random.
	Addresses []string `json:"addresses,omitempty"`
	// contains filtered or unexported fields
}

UpstreamResolver holds the set of addresses of DNS resolvers of upstream addresses

Directories

Path Synopsis
fastcgi