reverseproxy

package
v2.8.0-beta.2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 7, 2024 License: Apache-2.0 Imports: 49 Imported by: 60

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type AUpstreams added in v2.5.0 

type AUpstreams struct {
	// The domain name to look up.
	Name string `json:"name,omitempty"`

	// The port to use with the upstreams. Default: 80
	Port string `json:"port,omitempty"`

	// The interval at which to refresh the A lookup.
	// Results are cached between lookups. Default: 1m
	Refresh caddy.Duration `json:"refresh,omitempty"`

	// Configures the DNS resolver used to resolve the
	// domain name to A records.
	Resolver *UpstreamResolver `json:"resolver,omitempty"`

	// If Resolver is configured, how long to wait before
	// timing out trying to connect to the DNS server.
	DialTimeout caddy.Duration `json:"dial_timeout,omitempty"`

	// If Resolver is configured, 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"`

	// The IP versions to resolve for. By default, both
	// "ipv4" and "ipv6" will be enabled, which
	// correspond to A and AAAA records respectively.
	Versions *IPVersions `json:"versions,omitempty"`
	// contains filtered or unexported fields
}

AUpstreams provides upstreams from A/AAAA lookups. Results are cached and refreshed at the configured refresh interval.

func (AUpstreams) CaddyModule added in v2.5.0 

func (AUpstreams) CaddyModule() caddy.ModuleInfo

CaddyModule returns the Caddy module information.

func (AUpstreams) GetUpstreams added in v2.5.0 

func (au AUpstreams) GetUpstreams(r *http.Request) ([]*Upstream, error)

func (*AUpstreams) Provision added in v2.5.0 

func (au *AUpstreams) Provision(ctx caddy.Context) error

func (AUpstreams) String added in v2.5.0 

func (au AUpstreams) String() string

func (*AUpstreams) UnmarshalCaddyfile added in v2.5.0 

func (u *AUpstreams) UnmarshalCaddyfile(d *caddyfile.Dispenser) error

UnmarshalCaddyfile deserializes Caddyfile tokens into h. 

dynamic a [<name> <port] {
    name                <name>
    port                <port>
    refresh             <interval>
    resolvers           <resolvers...>
    dial_timeout        <timeout>
    dial_fallback_delay <timeout>
    versions            ipv4|ipv6
}

type ActiveHealthChecks 

type ActiveHealthChecks struct {
	// DEPRECATED: Use 'uri' instead. This field will be removed. TODO: remove this field
	Path string `json:"path,omitempty"`

	// The URI (path and query) to use for health checks
	URI string `json:"uri,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"`

	// Whether to follow HTTP redirects in response to active health checks (default off).
	FollowRedirects bool `json:"follow_redirects,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"`

	// Number of consecutive health check passes before marking
	// a previously unhealthy backend as healthy again (default 1).
	Passes int `json:"passes,omitempty"`

	// Number of consecutive health check failures before marking
	// a previously healthy backend as unhealthy (default 1).
	Fails int `json:"fails,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).

func (*ActiveHealthChecks) IsEnabled added in v2.7.0 

func (a *ActiveHealthChecks) IsEnabled() bool

IsEnabled checks if the active health checks have the minimum config necessary to be enabled.

func (*ActiveHealthChecks) Provision added in v2.7.0 

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

Provision ensures that a is set up properly before use.

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 ClientIPHashSelection added in v2.7.0 

type ClientIPHashSelection struct{}

ClientIPHashSelection is a policy that selects a host based on hashing the client IP of the request, as determined by the HTTP app's trusted proxies settings.

func (ClientIPHashSelection) CaddyModule added in v2.7.0 

func (ClientIPHashSelection) CaddyModule() caddy.ModuleInfo

CaddyModule returns the Caddy module information.

func (ClientIPHashSelection) Select added in v2.7.0 

func (ClientIPHashSelection) Select(pool UpstreamPool, req *http.Request, _ http.ResponseWriter) *Upstream

Select returns an available host, if any.

func (*ClientIPHashSelection) UnmarshalCaddyfile added in v2.7.0 

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

UnmarshalCaddyfile sets up the module from Caddyfile tokens.

type CookieHashSelection added in v2.3.0 

type CookieHashSelection struct {
	// The HTTP cookie name whose value is to be hashed and used for upstream selection.
	Name string `json:"name,omitempty"`
	// Secret to hash (Hmac256) chosen upstream in cookie
	Secret string `json:"secret,omitempty"`

	// The fallback policy to use if the cookie is not present. Defaults to `random`.
	FallbackRaw json.RawMessage `json:"fallback,omitempty" caddy:"namespace=http.reverse_proxy.selection_policies inline_key=policy"`
	// contains filtered or unexported fields
}

CookieHashSelection is a policy that selects a host based on a given cookie name.

func (CookieHashSelection) CaddyModule added in v2.3.0 

func (CookieHashSelection) CaddyModule() caddy.ModuleInfo

CaddyModule returns the Caddy module information.

func (*CookieHashSelection) Provision added in v2.7.0 

func (s *CookieHashSelection) Provision(ctx caddy.Context) error

Provision sets up the module.

func (CookieHashSelection) Select added in v2.3.0 

func (s CookieHashSelection) Select(pool UpstreamPool, req *http.Request, w http.ResponseWriter) *Upstream

Select returns an available host, if any.

func (*CookieHashSelection) UnmarshalCaddyfile added in v2.3.0 

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

UnmarshalCaddyfile sets up the module from Caddyfile tokens. Syntax: 

lb_policy cookie [<name> [<secret>]] {
	fallback <policy>
}

By default name is `lb`

type CopyResponseHandler added in v2.5.0 

type CopyResponseHandler struct {
	// To write the upstream response's body but with a different
	// status code, set this field to the desired status code.
	StatusCode caddyhttp.WeakString `json:"status_code,omitempty"`
	// contains filtered or unexported fields
}

CopyResponseHandler is a special HTTP handler which may only be used within reverse_proxy's handle_response routes, to copy the proxy response. EXPERIMENTAL, subject to change.

func (CopyResponseHandler) CaddyModule added in v2.5.0 

func (CopyResponseHandler) CaddyModule() caddy.ModuleInfo

CaddyModule returns the Caddy module information.

func (*CopyResponseHandler) Provision added in v2.5.0 

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

Provision ensures that h is set up properly before use.

func (CopyResponseHandler) ServeHTTP added in v2.5.0 

func (h CopyResponseHandler) ServeHTTP(rw http.ResponseWriter, req *http.Request, _ caddyhttp.Handler) error

ServeHTTP implements the Handler interface.

func (*CopyResponseHandler) UnmarshalCaddyfile added in v2.5.0 

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

UnmarshalCaddyfile sets up the handler from Caddyfile tokens. Syntax: 

copy_response [<matcher>] [<status>] {
    status <status>
}

type CopyResponseHeadersHandler added in v2.5.0 

type CopyResponseHeadersHandler struct {
	// A list of header fields to copy from the response.
	// Cannot be defined at the same time as Exclude.
	Include []string `json:"include,omitempty"`

	// A list of header fields to skip copying from the response.
	// Cannot be defined at the same time as Include.
	Exclude []string `json:"exclude,omitempty"`
	// contains filtered or unexported fields
}

CopyResponseHeadersHandler is a special HTTP handler which may only be used within reverse_proxy's handle_response routes, to copy headers from the proxy response. EXPERIMENTAL; subject to change.

func (CopyResponseHeadersHandler) CaddyModule added in v2.5.0 

func (CopyResponseHeadersHandler) CaddyModule() caddy.ModuleInfo

CaddyModule returns the Caddy module information.

func (*CopyResponseHeadersHandler) Provision added in v2.5.0 

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

Provision ensures that h is set up properly before use.

func (CopyResponseHeadersHandler) ServeHTTP added in v2.5.0 

func (h CopyResponseHeadersHandler) ServeHTTP(rw http.ResponseWriter, req *http.Request, next caddyhttp.Handler) error

ServeHTTP implements the Handler interface.

func (*CopyResponseHeadersHandler) UnmarshalCaddyfile added in v2.5.0 

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

UnmarshalCaddyfile sets up the handler from Caddyfile tokens. Syntax: 

copy_response_headers [<matcher>] {
    include <fields...>
    exclude <fields...>
}

func (*CopyResponseHeadersHandler) Validate added in v2.5.0 

func (h *CopyResponseHeadersHandler) Validate() error

Validate ensures the h's configuration is valid.

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, _ http.ResponseWriter) *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"`

	// If non-empty, which PROXY protocol version to send when
	// connecting to an upstream. Default: off.
	ProxyProtocol string `json:"proxy_protocol,omitempty"`

	// URL to the server that the HTTP transport will use to proxy
	// requests to the upstream. See http.Transport.Proxy for
	// information regarding supported protocols. This value takes
	// precedence over `HTTP_PROXY`, etc.
	//
	// Providing a value to this parameter results in
	// requests flowing through the reverse_proxy in the following
	// way:
	//
	// User Agent ->
	//  reverse_proxy ->
	//  forward_proxy_url -> upstream
	//
	// Default: http.ProxyFromEnvironment
	ForwardProxyURL string `json:"forward_proxy_url,omitempty"`

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

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

	// How long to wait for reading response headers from server. Default: No timeout.
	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". Default: No timeout.
	ExpectContinueTimeout caddy.Duration `json:"expect_continue_timeout,omitempty"`

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

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

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

	// The maximum time to wait for next read from backend. Default: no timeout.
	ReadTimeout caddy.Duration `json:"read_timeout,omitempty"`

	// The maximum time to wait for next write to backend. Default: no timeout.
	WriteTimeout caddy.Duration `json:"write_timeout,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(caddyCtx 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.

This method may be used by other transport modules that wrap/use this one.

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>
    max_response_header     <size>
    forward_proxy_url       <url>
    dial_timeout            <duration>
    dial_fallback_delay     <duration>
    response_header_timeout <duration>
    expect_continue_timeout <duration>
    resolvers               <resolvers...>
    tls
    tls_client_auth <automate_name> | <cert_file> <key_file>
    tls_insecure_skip_verify
    tls_timeout <duration>
    tls_trusted_ca_certs <cert_files...>
    tls_server_name <sni>
    tls_renegotiation <level>
    tls_except_ports <ports...>
    keepalive [off|<duration>]
    keepalive_interval <interval>
    keepalive_idle_conns <max_count>
    keepalive_idle_conns_per_host <count>
    versions <versions...>
    compression off
    max_conns_per_host <count>
    max_idle_conns_per_host <count>
}

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 static list of backends to proxy to.
	Upstreams UpstreamPool `json:"upstreams,omitempty"`

	// A module for retrieving the list of upstreams dynamically. Dynamic
	// upstreams are retrieved at every iteration of the proxy loop for
	// each request (i.e. before every proxy attempt within every request).
	// Active health checks do not work on dynamic upstreams, and passive
	// health checks are only effective on dynamic upstreams if the proxy
	// server is busy enough that concurrent requests to the same backends
	// are continuous. Instead of health checks for dynamic upstreams, it
	// is recommended that the dynamic upstream module only return available
	// backends in the first place.
	DynamicUpstreamsRaw json.RawMessage `json:"dynamic_upstreams,omitempty" caddy:"namespace=http.reverse_proxy.upstreams inline_key=source"`

	// Adjusts how often to flush the response buffer. By default,
	// no periodic flushing is done. A negative value disables
	// response buffering, and flushes immediately after each
	// write to the client. This option is ignored when the upstream's
	// response is recognized as a streaming response, or if its
	// content length is -1; for such responses, writes are flushed
	// to the client immediately.
	//
	// Normally, a request will be canceled if the client disconnects
	// before the response is received from the backend. If explicitly
	// set to -1, client disconnection will be ignored and the request
	// will be completed to help facilitate low-latency streaming.
	FlushInterval caddy.Duration `json:"flush_interval,omitempty"`

	// A list of IP ranges (supports CIDR notation) from which
	// X-Forwarded-* header values should be trusted. By default,
	// no proxies are trusted, so existing values will be ignored
	// when setting these headers. If the proxy is trusted, then
	// existing values will be used when constructing the final
	// header values.
	TrustedProxies []string `json:"trusted_proxies,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, X-Forwarded-Proto and X-Forwarded-Host
	// are also set implicitly.
	Headers *headers.Handler `json:"headers,omitempty"`

	// If nonzero, the entire request body up to this size will be read
	// and buffered in memory before being proxied to the backend. This
	// should be avoided if at all possible for performance reasons, but
	// could be useful if the backend is intolerant of read latency or
	// chunked encodings.
	RequestBuffers int64 `json:"request_buffers,omitempty"`

	// If nonzero, the entire response body up to this size will be read
	// and buffered in memory before being proxied to the client. This
	// should be avoided if at all possible for performance reasons, but
	// could be useful if the backend has tighter memory constraints.
	ResponseBuffers int64 `json:"response_buffers,omitempty"`

	// If nonzero, streaming requests such as WebSockets will be
	// forcibly closed at the end of the timeout. Default: no timeout.
	StreamTimeout caddy.Duration `json:"stream_timeout,omitempty"`

	// If nonzero, streaming requests such as WebSockets will not be
	// closed when the proxy config is unloaded, and instead the stream
	// will remain open until the delay is complete. In other words,
	// enabling this prevents streams from closing when Caddy's config
	// is reloaded. Enabling this may be a good idea to avoid a thundering
	// herd of reconnecting clients which had their connections closed
	// by the previous config closing. Default: no delay.
	StreamCloseDelay caddy.Duration `json:"stream_close_delay,omitempty"`

	// If configured, rewrites the copy of the upstream request.
	// Allows changing the request method and URI (path and query).
	// Since the rewrite is applied to the copy, it does not persist
	// past the reverse proxy handler.
	// If the method is changed to `GET` or `HEAD`, the request body
	// will not be copied to the backend. This allows a later request
	// handler -- either in a `handle_response` route, or after -- to
	// read the body.
	// By default, no rewrite is performed, and the method and URI
	// from the incoming request is used as-is for proxying.
	Rewrite *rewrite.Rewrite `json:"rewrite,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.
	//
	// Three new placeholders are available in this handler chain:
	// - `{http.reverse_proxy.status_code}` The status code from the response
	// - `{http.reverse_proxy.status_text}` The status text from the response
	// - `{http.reverse_proxy.header.*}` The headers from the response
	HandleResponse []caddyhttp.ResponseHandler `json:"handle_response,omitempty"`

	// If set, the proxy will write very detailed logs about its
	// inner workings. Enable this only when debugging, as it
	// will produce a lot of output.
	//
	// EXPERIMENTAL: This feature is subject to change or removal.
	VerboseLogs bool `json:"verbose_logs,omitempty"`

	Transport        http.RoundTripper `json:"-"`
	CB               CircuitBreaker    `json:"-"`
	DynamicUpstreams UpstreamSource    `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; for example, in response headers):

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 `{http.reverse_proxy.upstream.latency}` | How long it took the proxy upstream to write the response header. `{http.reverse_proxy.upstream.latency_ms}` | Same as 'latency', but in milliseconds. `{http.reverse_proxy.upstream.duration}` | Time spent proxying to the upstream, including writing response body to client. `{http.reverse_proxy.upstream.duration_ms}` | Same as 'upstream.duration', but in milliseconds. `{http.reverse_proxy.duration}` | Total time spent proxying, including selecting an upstream, retries, and writing response. `{http.reverse_proxy.duration_ms}` | Same as 'duration', but in milliseconds.

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.

func (*Handler) FinalizeUnmarshalCaddyfile added in v2.4.0 

func (h *Handler) FinalizeUnmarshalCaddyfile(helper httpcaddyfile.Helper) error

FinalizeUnmarshalCaddyfile finalizes the Caddyfile parsing which requires having an httpcaddyfile.Helper to function, to parse subroutes.

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...>] {
    # backends
    to      <upstreams...>
    dynamic <name> [...]

    # load balancing
    lb_policy <name> [<options...>]
    lb_retries <retries>
    lb_try_duration <duration>
    lb_try_interval <interval>
    lb_retry_match <request-matcher>

    # active health checking
    health_uri      <uri>
    health_port     <port>
    health_interval <interval>
    health_passes   <num>
    health_fails    <num>
    health_timeout  <duration>
    health_status   <status>
    health_body     <regexp>
    health_follow_redirects
    health_headers {
        <field> [<values...>]
    }

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

    # streaming
    flush_interval     <duration>
    buffer_requests
    buffer_responses
    max_buffer_size    <size>
    stream_timeout     <duration>
    stream_close_delay <duration>
    trace_logs

    # request manipulation
    trusted_proxies [private_ranges] <ranges...>
    header_up   [+|-]<field> [<value|regexp> [<replacement>]]
    header_down [+|-]<field> [<value|regexp> [<replacement>]]
    method <method>
    rewrite <to>

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

    # optionally intercept responses from upstream
    @name {
        status <code...>
        header <field> [<value>]
    }
    replace_status [<matcher>] <status_code>
    handle_response [<matcher>] {
        <directives...>

        # special directives only available in handle_response
        copy_response [<matcher>] [<status>] {
            status <status>
        }
        copy_response_headers [<matcher>] {
            include <fields...>
            exclude <fields...>
        }
    }
}

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.

The FinalizeUnmarshalCaddyfile method should be called after this to finalize parsing of "handle_response" blocks, if possible.

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"`

	// The fallback policy to use if the header is not present. Defaults to `random`.
	FallbackRaw json.RawMessage `json:"fallback,omitempty" caddy:"namespace=http.reverse_proxy.selection_policies inline_key=policy"`
	// contains filtered or unexported fields
}

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) Provision added in v2.7.0 

func (s *HeaderHashSelection) Provision(ctx caddy.Context) error

Provision sets up the module.

func (HeaderHashSelection) Select 

func (s HeaderHashSelection) Select(pool UpstreamPool, req *http.Request, _ http.ResponseWriter) *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). Note that active health check status
	// (healthy/unhealthy) is stored per-proxy-handler, not
	// globally; this allows different handlers to use different
	// criteria to decide what defines a healthy backend.
	//
	// Active health checks do not run for dynamic upstreams.
	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 with fail_duration > 0. Passive health check state is
	// shared (stored globally), so a failure from one handler will be counted
	// by all handlers; but the tolerances or standards for what defines
	// healthy/unhealthy backends is configured per-proxy-handler.
	//
	// Passive health checks technically do operate on dynamic upstreams,
	// but are only effective for very busy proxies where the list of
	// upstreams is mostly stable. This is because the shared/global
	// state of upstreams is cleaned up when the upstreams are no longer
	// used. Since dynamic upstreams are allocated dynamically at each
	// request (specifically, each iteration of the proxy loop per request),
	// they are also cleaned up after every request. Thus, if there is a
	// moment when no requests are actively referring to a particular
	// upstream host, the passive health check state will be reset because
	// it will be garbage-collected. It is usually better for the dynamic
	// upstream module to only return healthy, available backends instead.
	Passive *PassiveHealthChecks `json:"passive,omitempty"`
}

HealthChecks configures active and passive health checks.

type Host 

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

Host is the basic, in-memory representation of the state of a remote host. Its fields are accessed atomically and Host values must not be copied.

func (*Host) Fails 

func (h *Host) Fails() int

Fails returns the number of recent failures with the upstream.

func (*Host) NumRequests 

func (h *Host) NumRequests() int

NumRequests returns the number of active requests to the upstream.

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, _ http.ResponseWriter) *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 IPVersions added in v2.7.0 

type IPVersions struct {
	IPv4 *bool `json:"ipv4,omitempty"`
	IPv6 *bool `json:"ipv6,omitempty"`
}

type KeepAlive 

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

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

	// Maximum number of idle connections. Default: `0`, which means no limit.
	MaxIdleConns int `json:"max_idle_conns,omitempty"`

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

	// How long connections should be kept alive when idle. Default: `2m`.
	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, _ http.ResponseWriter) *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 many times to retry selecting available backends for each
	// request if the next available host is down. If try_duration is
	// also configured, then retries may stop early if the duration
	// is reached. By default, retries are disabled (zero).
	Retries int `json:"retries,omitempty"`

	// How long to try selecting available backends for each request
	// if the next available host is down. Clients will wait for up
	// to this long while the load balancer tries to find an available
	// upstream host. If retries is also configured, tries may stop
	// early if the maximum retries is reached. By default, retries
	// are disabled (zero duration).
	TryDuration caddy.Duration `json:"try_duration,omitempty"`

	// How long to wait between selecting the next host from the pool.
	// Default is 250ms if try_duration is enabled, otherwise zero. 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 MultiUpstreams added in v2.6.0 

type MultiUpstreams struct {
	// The list of upstream source modules to get upstreams from.
	// They will be queried in order, with their results appended
	// in the order they are returned.
	SourcesRaw []json.RawMessage `json:"sources,omitempty" caddy:"namespace=http.reverse_proxy.upstreams inline_key=source"`
	// contains filtered or unexported fields
}

MultiUpstreams is a single dynamic upstream source that aggregates the results of multiple dynamic upstream sources. All configured sources will be queried in order, with their results appended to the end of the list. Errors returned from individual sources will be logged and the next source will continue to be invoked.

This module makes it easy to implement redundant cluster failovers, especially in conjunction with the `first` load balancing policy: if the first source returns an error or no upstreams, the second source's upstreams will be used naturally.

func (MultiUpstreams) CaddyModule added in v2.6.0 

func (MultiUpstreams) CaddyModule() caddy.ModuleInfo

CaddyModule returns the Caddy module information.

func (MultiUpstreams) GetUpstreams added in v2.6.0 

func (mu MultiUpstreams) GetUpstreams(r *http.Request) ([]*Upstream, error)

func (*MultiUpstreams) Provision added in v2.6.0 

func (mu *MultiUpstreams) Provision(ctx caddy.Context) error

func (*MultiUpstreams) UnmarshalCaddyfile added in v2.6.0 

func (u *MultiUpstreams) UnmarshalCaddyfile(d *caddyfile.Dispenser) error

UnmarshalCaddyfile deserializes Caddyfile tokens into h. 

dynamic multi {
    <source> [...]
}

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 ProxyProtocolInfo added in v2.7.0 

type ProxyProtocolInfo struct {
	AddrPort netip.AddrPort
}

ProxyProtocolInfo contains information needed to write proxy protocol to a connection to an upstream host.

type QueryHashSelection added in v2.7.0 

type QueryHashSelection struct {
	// The query key whose value is to be hashed and used for upstream selection.
	Key string `json:"key,omitempty"`

	// The fallback policy to use if the query key is not present. Defaults to `random`.
	FallbackRaw json.RawMessage `json:"fallback,omitempty" caddy:"namespace=http.reverse_proxy.selection_policies inline_key=policy"`
	// contains filtered or unexported fields
}

QueryHashSelection is a policy that selects a host based on a given request query parameter.

func (QueryHashSelection) CaddyModule added in v2.7.0 

func (QueryHashSelection) CaddyModule() caddy.ModuleInfo

CaddyModule returns the Caddy module information.

func (*QueryHashSelection) Provision added in v2.7.0 

func (s *QueryHashSelection) Provision(ctx caddy.Context) error

Provision sets up the module.

func (QueryHashSelection) Select added in v2.7.0 

func (s QueryHashSelection) Select(pool UpstreamPool, req *http.Request, _ http.ResponseWriter) *Upstream

Select returns an available host, if any.

func (*QueryHashSelection) UnmarshalCaddyfile added in v2.7.0 

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

UnmarshalCaddyfile sets up the module from Caddyfile tokens.

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, _ http.ResponseWriter) *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, _ http.ResponseWriter) *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, _ http.ResponseWriter) *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 SRVUpstreams added in v2.5.0 

type SRVUpstreams struct {
	// The service label.
	Service string `json:"service,omitempty"`

	// The protocol label; either tcp or udp.
	Proto string `json:"proto,omitempty"`

	// The name label; or, if service and proto are
	// empty, the entire domain name to look up.
	Name string `json:"name,omitempty"`

	// The interval at which to refresh the SRV lookup.
	// Results are cached between lookups. Default: 1m
	Refresh caddy.Duration `json:"refresh,omitempty"`

	// If > 0 and there is an error with the lookup,
	// continue to use the cached results for up to
	// this long before trying again, (even though they
	// are stale) instead of returning an error to the
	// client. Default: 0s.
	GracePeriod caddy.Duration `json:"grace_period,omitempty"`

	// Configures the DNS resolver used to resolve the
	// SRV address to SRV records.
	Resolver *UpstreamResolver `json:"resolver,omitempty"`

	// If Resolver is configured, how long to wait before
	// timing out trying to connect to the DNS server.
	DialTimeout caddy.Duration `json:"dial_timeout,omitempty"`

	// If Resolver is configured, 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"`
	// contains filtered or unexported fields
}

SRVUpstreams provides upstreams from SRV lookups. The lookup DNS name can be configured either by its individual parts (that is, specifying the service, protocol, and name separately) to form the standard "_service._proto.name" domain, or the domain can be specified directly in name by leaving service and proto empty. See RFC 2782.

Lookups are cached and refreshed at the configured refresh interval.

Returned upstreams are sorted by priority and weight.

func (SRVUpstreams) CaddyModule added in v2.5.0 

func (SRVUpstreams) CaddyModule() caddy.ModuleInfo

CaddyModule returns the Caddy module information.

func (SRVUpstreams) GetUpstreams added in v2.5.0 

func (su SRVUpstreams) GetUpstreams(r *http.Request) ([]*Upstream, error)

func (*SRVUpstreams) Provision added in v2.5.0 

func (su *SRVUpstreams) Provision(ctx caddy.Context) error

func (SRVUpstreams) String added in v2.5.0 

func (su SRVUpstreams) String() string

func (*SRVUpstreams) UnmarshalCaddyfile added in v2.5.0 

func (u *SRVUpstreams) UnmarshalCaddyfile(d *caddyfile.Dispenser) error

UnmarshalCaddyfile deserializes Caddyfile tokens into h. 

dynamic srv [<name>] {
    service             <service>
    proto               <proto>
    name                <name>
    refresh             <interval>
    resolvers           <resolvers...>
    dial_timeout        <timeout>
    dial_fallback_delay <timeout>
    grace_period        <duration>
}

type Selector 

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

Selector selects an available upstream from the pool.

type TLSConfig 

type TLSConfig struct {
	// Certificate authority module which provides the certificate pool of trusted certificates
	CARaw json.RawMessage `json:"ca,omitempty" caddy:"namespace=tls.ca_pool.source inline_key=provider"`

	// DEPRECATED: Use the `ca` field with the `tls.ca_pool.source.inline` module instead.
	// Optional list of base64-encoded DER-encoded CA certificates to trust.
	RootCAPool []string `json:"root_ca_pool,omitempty"`

	// DEPRECATED: Use the `ca` field with the `tls.ca_pool.source.file` module instead.
	// 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. Default: No timeout.
	HandshakeTimeout caddy.Duration `json:"handshake_timeout,omitempty"`

	// The server name used when verifying the certificate received in the TLS
	// handshake. By default, this will use the upstream address' host part.
	// You only need to override this if your upstream address does not match the
	// certificate the upstream is likely to use. For example if the upstream
	// address is an IP address, then you would need to configure this to the
	// hostname being served by the upstream server. Currently, this does not
	// support placeholders because the TLS config is not provisioned on each
	// connection, so a static value must be used.
	ServerName string `json:"server_name,omitempty"`

	// TLS renegotiation level. TLS renegotiation is the act of performing
	// subsequent handshakes on a connection after the first.
	// The level can be:
	//  - "never": (the default) disables renegotiation.
	//  - "once": allows a remote server to request renegotiation once per connection.
	//  - "freely": allows a remote server to repeatedly request renegotiation.
	Renegotiation string `json:"renegotiation,omitempty"`

	// Skip TLS ports specifies a list of upstream ports on which TLS should not be
	// attempted even if it is configured. Handy when using dynamic upstreams that
	// return HTTP and HTTPS endpoints too.
	// When specified, TLS will automatically be configured on the transport.
	// The value can be a list of any valid tcp port numbers, default empty.
	ExceptPorts []string `json:"except_ports,omitempty"`

	// The list of elliptic curves to support. Caddy's
	// defaults are modern and secure.
	Curves []string `json:"curves,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, _ http.ResponseWriter) *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"`

	// 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. Upstream values must not be copied.

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

(pointer receiver necessary to avoid a race condition, since copying the Upstream reads the 'unhealthy' field which is accessed atomically)

type UpstreamPool 

type UpstreamPool []*Upstream

UpstreamPool is a collection of upstreams.

type UpstreamResolver added in v2.2.0 

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

func (*UpstreamResolver) ParseAddresses added in v2.5.0 

func (u *UpstreamResolver) ParseAddresses() error

ParseAddresses parses all the configured network addresses and ensures they're ready to be used.

type UpstreamSource added in v2.5.0 

type UpstreamSource interface {
	GetUpstreams(*http.Request) ([]*Upstream, error)
}

UpstreamSource gets the list of upstreams that can be used when proxying a request. Returned upstreams will be load balanced and health-checked. This should be a very fast function -- instant if possible -- and the return value must be as stable as possible. In other words, the list of upstreams should ideally not change much across successive calls. If the list of upstreams changes or the ordering is not stable, load balancing will suffer. This function may be called during each retry, multiple times per request, and as such, needs to be instantaneous. The returned slice will not be modified.

type WeightedRoundRobinSelection added in v2.7.0 

type WeightedRoundRobinSelection struct {
	// The weight of each upstream in order,
	// corresponding with the list of upstreams configured.
	Weights []int `json:"weights,omitempty"`
	// contains filtered or unexported fields
}

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

func (WeightedRoundRobinSelection) CaddyModule added in v2.7.0 

func (WeightedRoundRobinSelection) CaddyModule() caddy.ModuleInfo

CaddyModule returns the Caddy module information.

func (*WeightedRoundRobinSelection) Provision added in v2.7.0 

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

Provision sets up r.

func (*WeightedRoundRobinSelection) Select added in v2.7.0 

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

Select returns an available host, if any.

func (*WeightedRoundRobinSelection) UnmarshalCaddyfile added in v2.7.0 

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

UnmarshalCaddyfile sets up the module from Caddyfile tokens.

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.