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 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"`
// 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"`
}
ActiveHealthChecks holds configuration related to active health checks (that is, health checks which occur in a background goroutine independently).
type HTTPTransport ¶
type HTTPTransport struct {
// Protocol is the name of this protocol for the JSON config.
// DO NOT USE this. This is a special value to represent this protocol.
// It will be overwritten when we are marshalled.
Protocol HTTPTransportProtocol `json:"protocol"`
// 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"`
// 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"`
}
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) IAmATransport ¶
func (HTTPTransport) IAmATransport()
type HTTPTransportProtocol ¶
type HTTPTransportProtocol string
func (HTTPTransportProtocol) MarshalJSON ¶
func (HTTPTransportProtocol) MarshalJSON() ([]byte, error)
type Handler ¶
type Handler struct {
// Handler is the name of this handler for the JSON config.
// DO NOT USE this. This is a special value to represent this handler.
// It will be overwritten when we are marshalled.
Handler HandlerName `json:"handler"`
// 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.
Transport Transport `json:"transport,omitempty"`
// 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.
// TODO: type this
CB any `json:"circuit_breaker,omitempty"`
// 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.
// TODO: type this
DynamicUpstreams json.RawMessage `json:"dynamic_upstreams,omitempty"`
// 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"`
}
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) IAmAHandler ¶
func (Handler) IAmAHandler()
type HandlerName ¶
type HandlerName string
func (HandlerName) MarshalJSON ¶
func (HandlerName) MarshalJSON() ([]byte, error)
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 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 LoadBalancing ¶
type LoadBalancing struct {
// A selection policy is how to choose an available backend.
// The default policy is random selection.
// TODO: type this
SelectionPolicy any `json:"selection_policy,omitempty"`
// 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.
// TODO: check if this is the correct typing.
RetryMatch []caddyhttp.Match `json:"retry_match,omitempty"`
}
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"`
}
PassiveHealthChecks holds configuration related to passive health checks (that is, health checks which occur during the normal flow of request proxying).
type TLSConfig ¶
type TLSConfig struct {
// Certificate authority module which provides the certificate pool of trusted certificates
CA caddytls.CA `json:"ca,omitempty"`
// 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.
type Upstream ¶
type Upstream struct {
// 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"`
}
Upstream bridges this proxy's configuration to the state of the backend host it is correlated with. Upstream values must not be copied.
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"`
}
UpstreamResolver holds the set of addresses of DNS resolvers of upstream addresses
Source Files
Click to show internal directories.
Click to hide internal directories.