From 95ed603de79c66ff76bfe7e42986a2fc8c7a1fa4 Mon Sep 17 00:00:00 2001 From: Matthew Holt Date: Mon, 23 Dec 2019 12:45:35 -0700 Subject: Improve godocs all around These will be used in the new automated documentation system --- modules/caddyhttp/reverseproxy/reverseproxy.go | 87 ++++++++++++++++++++++---- 1 file changed, 74 insertions(+), 13 deletions(-) (limited to 'modules/caddyhttp/reverseproxy/reverseproxy.go') diff --git a/modules/caddyhttp/reverseproxy/reverseproxy.go b/modules/caddyhttp/reverseproxy/reverseproxy.go index d353dc1..24389b2 100644 --- a/modules/caddyhttp/reverseproxy/reverseproxy.go +++ b/modules/caddyhttp/reverseproxy/reverseproxy.go @@ -41,15 +41,56 @@ func init() { } // 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): +// +// {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 +// type Handler struct { - TransportRaw json.RawMessage `json:"transport,omitempty" caddy:"namespace=http.reverse_proxy.transport inline_key=protocol"` - CBRaw json.RawMessage `json:"circuit_breaker,omitempty" caddy:"namespace=http.reverse_proxy.circuit_breakers inline_key=type"` - LoadBalancing *LoadBalancing `json:"load_balancing,omitempty"` - HealthChecks *HealthChecks `json:"health_checks,omitempty"` - Upstreams UpstreamPool `json:"upstreams,omitempty"` - FlushInterval caddy.Duration `json:"flush_interval,omitempty"` - Headers *headers.Handler `json:"headers,omitempty"` - BufferRequests bool `json:"buffer_requests,omitempty"` + // 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"` + + // 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. + 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"` Transport http.RoundTripper `json:"-"` CB CircuitBreaker `json:"-"` @@ -140,7 +181,7 @@ func (h *Handler) Provision(ctx caddy.Context) error { timeout := time.Duration(h.HealthChecks.Active.Timeout) if timeout == 0 { - timeout = 10 * time.Second + timeout = 5 * time.Second } h.HealthChecks.Active.stopChan = make(chan struct{}) @@ -649,10 +690,30 @@ func removeConnectionHeaders(h http.Header) { // LoadBalancing has parameters related to load balancing. type LoadBalancing struct { - SelectionPolicyRaw json.RawMessage `json:"selection_policy,omitempty" caddy:"namespace=http.reverse_proxy.selection_policies inline_key=policy"` - TryDuration caddy.Duration `json:"try_duration,omitempty"` - TryInterval caddy.Duration `json:"try_interval,omitempty"` - RetryMatchRaw caddyhttp.RawMatcherSets `json:"retry_match,omitempty" caddy:"namespace=http.matchers"` + // 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:"-"` -- cgit v1.2.3